github-starred/libxlsxwriter
2
0
Fork 0
mirror of https://github.com/jmcnamara/libxlsxwriter.git synced 2026-05-15 14:15:54 -06:00
Code Issues 16 Projects Packages Wiki Activity Actions

Added sections to the docs.

Browse source
This commit is contained in:
John McNamara 2016-07-03 00:51:02 +01:00
parent f24916334b
commit 234ab73cd2
9 changed files with 68 additions and 63 deletions
Download patch file Download diff file Expand all files Collapse all files

24
docs/src/bugs.dox
View file

@ -2,11 +2,12 @@
@page bugs Known Issues and Bugs
@tableofcontents
This section lists known issues and bugs and gives some information on
how to submit bug reports.
## Content is Unreadable. Open and Repair
@section bugs_unreadable Content is Unreadable. Open and Repair
Very, very occasionally you may encounter a bug which generates an Excel
warning when opening an `libxlsxwriter` file like:
@ -21,7 +22,7 @@ If you encounter an issue like this you should open an issue on GitHub with a
program to replicate the issue (see below) or send one of the failing output
files to the @ref author.
## Formulas displayed as `NAME?` until edited
@section bugs_formula_name Formulas displayed as 'NAME?' until edited
Excel 2010 and 2013 added functions which weren't defined in the original file
specification. These functions are referred to as *future* functions. Examples
@ -37,8 +38,7 @@ documentation link above. For example:
worksheet_write_formula(worksheet, 0, 0,"=_xlfn.STDEV.S(B1:B10)", NULL);
## Formula results displaying as zero in non-Excel applications
@section bugs_formula_zero Formula results displaying as zero in non-Excel applications
Due to wide range of possible formulas and inter-dependencies between them,
`xlsxwriter` doesn't, and realistically cannot, calculate the result of a
@ -55,7 +55,7 @@ If required, it is also possible to specify the calculated result of the
formula using the `worksheet_write_formula_num()` function.
## Strings aren't displayed in Apple Numbers in 'constant_memory' mode
@section bugs_apple_numbers Strings aren't displayed in Apple Numbers in 'constant_memory' mode
In `workbook_new_opt()` `constant_memory` mode libxlsxwriter uses an optimization
where cell strings aren't stored in an Excel structure call "shared strings"
@ -65,7 +65,7 @@ This is a documented Excel feature that is supported by most spreadsheet
applications. One known exception is Apple Numbers for Mac where the string
data isn't displayed.
## Images not displayed correctly in Excel 2001 for Mac and non-Excel applications
@section bugs_images Images not displayed correctly in Excel 2001 for Mac and non-Excel applications
Images inserted into worksheets via `worksheet_insert_image()` may not display
correctly in Excel 2011 for Mac and non-Excel applications such as OpenOffice
@ -75,11 +75,11 @@ This is not an XlsxWriter issue. It also occurs with files created in Excel
2007 and Excel 2010.
# Reporting Bugs
@section bugs_reporting Reporting Bugs
Here are some tips on reporting bugs in `libxlsxwriter`.
## Upgrade to the latest version of the library
@subsection bugs_upgrade Upgrade to the latest version of the library
The bug you are reporting may already be fixed in the latest version of
the module.
@ -103,24 +103,24 @@ int main() {
@endcode
## Read the documentation
@subsection bugs_docs Read the documentation
Read or search the `libxlsxwriter` documentation to see if the issue you are
encountering is already explained.
## Look at the example programs
@subsection bugs_examples Look at the example programs
There are many @ref examples in the distribution. Try to identify an example
program that corresponds to your query and adapt it to use as a bug report.
## Use the xlsxwriter Issue tracker
@subsection bugs_issues Use the xlsxwriter Issue tracker
The [libxlsxwriter issue tracker]
(https://github.com/jmcnamara/libxlsxwriter/issues) is on GitHub.
## Tips for submitting a bug report
@subsection bugs_tips Tips for submitting a bug report
1. Describe the problem as clearly and as concisely as possible.
2. Include a sample program. This is probably the most important step.

18
docs/src/faq.dox
View file

@ -2,10 +2,12 @@
@page faq Frequently Asked Questions
@tableofcontents
The section outlines some answers to some frequently asked questions.
### Q. Can Libxlsxwriter use an existing Excel file as a template?
@section faq_template Q. Can Libxlsxwriter use an existing Excel file as a template?
No.
@ -13,7 +15,7 @@ Libxlsxwriter is designed only as a file *writer*. It cannot read or modify
an existing Excel file.
### Q. Why do my formulas show a zero result in some, non-Excel applications?
@section faq_formula_zero Q. Why do my formulas show a zero result in some, non-Excel applications?
Due to wide range of possible formulas and inter-dependencies between them
`libxlsxwriter` doesn't, and realistically cannot, calculate the result of a
@ -30,25 +32,25 @@ If required, it is also possible to specify the calculated result of the
formula using the worksheet_write_formula_num() function.
### Q. Can I apply a format to a range of cells in one go?
@section faq_range_format Q. Can I apply a format to a range of cells in one go?
Currently no. However, it is a planned features to allow cell formats
and data to be written separately.
### Q. Is Visual C++ on Windows supported?
@section faq_msvc Q. Is Visual C++ on Windows supported?
Yes. See @ref getting_started.
Yes. See @ref gsg_msvc.
### Q. Is feature X supported or will it be supported?
@section faq_features Q. Is feature X supported or will it be supported?
All supported features are documented. In time the feature set may expand to
include more of the functionality of the [Python
XlsxWriter](http://xlsxwriter.readthedocs.org) module.
### Q. Is there an "AutoFit" option for columns?
@section faq_autofit Q. Is there an "AutoFit" option for columns?
Unfortunately, there is no way to specify "AutoFit" for a column in the
Excel file format. This feature is only available at runtime from within
@ -56,7 +58,7 @@ Excel. It is possible to simulate "AutoFit" by tracking the width of the
data in the column as your write it.
### Q. Do people actually ask these questions frequently, or at all?
@section faq_faq Q. Do people actually ask these questions frequently, or at all?
Apart from this question, yes.

44
docs/src/getting_started.dox
View file

@ -1,15 +1,15 @@
/**
@page getting_started Getting Started with libxlsxwriter
@tableofcontents
Here are some instructions to get you up and running with the libxlsxwriter
library on different OSes.
@section gsg_linux Installation on Linux and FreeBSD
## Installation on Linux and FreeBSD
### Quick-start on Linux
@subsection gsg_quick_start Quick-start on Linux
If you prefer to assemble Ikea furniture first and only read the instructions
when you have parts left over then the following minimal set of commands
@ -24,7 +24,7 @@ should get you up and running on a Debian like system:
If you read instructions first and then assemble the furniture you will know
how to proceed.
### Install the dependencies
@subsection gsg_dependencies Install the dependencies
The only dependency (apart from @ref running_the_tests "testing dependencies")
is [Zlib](http://www.zlib.net) version 1.2.8.
@ -49,7 +49,7 @@ However, you need to ensure that the version installed is 1.2.8 or you will
get zlib related compilation issues.
### Get the source code via Git
@subsection gsg_git Get the source code via Git
Clone the libxlsxwriter source code repository from GitHub as follows:
@ -57,14 +57,14 @@ Clone the libxlsxwriter source code repository from GitHub as follows:
# Or use your preferred protocol instead of https.
### Get the source code as a tarball
@subsection gsg_tarball Get the source code as a tarball
If you prefer you can get a tarball of the latest code as follows:
curl -O -L http://github.com/jmcnamara/libxlsxwriter/archive/master.tar.gz
### Build the source code
@subsection gsg_build Build the source code
Build the source code as follows:
@ -83,7 +83,7 @@ To see a verbose summary of the compilation steps use `V=1`:
make V=1
### Try an example
@subsection gsg_examples Try an example
If there weren't any warnings or errors in the previous step (and there
shouldn't have been) then you can build the programs in the `examples`
@ -100,7 +100,7 @@ There is a large range of tests that you can run but they have some additional
dependencies. If you are interested see @ref running_the_tests.
### Install the library
@subsection gsg_install Install the library
Libxlsxwriter supports a simplified installation scheme for a static and
dynamic/shared library and header files. The installation has been tested on
@ -112,7 +112,7 @@ This isn't fool proof but if it fails on your system you will probably know
exactly how to fix it or have no idea how to fix it. I'm hoping for the
former.
### Using the library
@subsection gsg_using Using the library
Using you favourite editor create a file like the following called
`myexcel.c`:
@ -151,7 +151,7 @@ library you created in the "Build the source code" step:
/path/to/libxlsxwriter/lib/libxlsxwriter.a -lz
## Installation on Mac OS X and iOS
@section gsg_macos Installation on Mac OS X and iOS
The instructions for installing on Linux, shown above, will also work on Mac
OS X.
@ -159,7 +159,7 @@ OS X.
To install for Xcode and iOS use the Cocoa Pods method shown in the next
section.
### Install using Cocoa Pods for Xcode
@subsection gsg_cocoapods Install using Cocoa Pods for Xcode
For iOS and OS X projects in Xcode you can install libxlsxwriter using
[CocoaPods](https://cocoapods.org).
@ -170,7 +170,7 @@ Examples](https://github.com/lrossi/libxlsxwriterCocoaExamples), provided by
Ludovico Rossi.
## Installation on Windows using Microsoft Visual Studio
@section gsg_msvc Installation on Windows using Microsoft Visual Studio
There is a sample Microsoft Visual Studio project on GitHub called
[MSVCLibXlsxWriter](https://github.com/jmcnamara/MSVCLibXlsxWriter).
@ -178,7 +178,7 @@ There is a sample Microsoft Visual Studio project on GitHub called
The allows you to build a DLL of libxlsxwriter and also a sample application
that uses it to create an Excel output file.
### Building a Windows DLL of libxlsxwriter
@subsection gsg_dll Building a Windows DLL of libxlsxwriter
The MSVCLibXlsxWriter repository contains 3 directories:
@ -216,7 +216,7 @@ and `.dll` in:
MSVCLibXlsxWriter\LibXlsxWriterProj\x64\Debug
### Building a console application using the LibXlsxWriter.lib
@subsection gsg_console Building a console application using the LibXlsxWriter.lib
Ensure that `LibXlsxWriter.lib` was built correctly in the previous steps.
@ -240,12 +240,12 @@ libxlsxwriter example programs by copying the code from one of the
`libxlsxwriter\example\*.c` programs.
## Installation on Windows using Mingw-w64 and MSYS2
@section gsg_ming Installation on Windows using Mingw-w64 and MSYS2
The libxlsxwriter library can also be compiled on Windows using the
[Mingw-w64](http://mingw-w64.org/doku.php) "Minimalist GNU for Windows"
toolchain. These tools can be run from the Windows `cmd.exe` but it is
recommended to use the [MSYS2](http://msys2.github.io) "Minimal SYStem" Bourne
recommended to use the [MSYS2](http://msys2.github.io) "Minimal System" Bourne
Shell.
Here are some instructions on how to compile libxlsxwriter with Mingw-w64 and
@ -261,13 +261,13 @@ MSYS2:
cd libxlsxwriter/
make
After compilation you can follow the instructions in the "Install the library"
and "Use the library" sections above. When using the library you may also need
to link against the zlib library using `-lz`:
After compilation you can follow the instructions in the @ref gsg_install and
@ref gsg_using sections above. When using the library you may also need to
link against the zlib library using `-lz`:
gcc myexcel.c -o myexcel -lxlsxwriter -lz
It is also possible to use the older [MinGW and MSYS](http://mingw.org)j and
It is also possible to use the older [MinGW and MSYS](http://mingw.org) and
with [Cygwin](https://cygwin.com). Libxlsxwriter has been confirmed to compile
and work in all of these environments.
@ -279,7 +279,7 @@ directory using the system fstab file. Or alternatively you can define your
own TEMP directory in libxlsxwriter using the `USE_TMPFILE2` workaround in
`src/utility.c`
## Next steps
@section gsg_next Next steps
If you got libxlsxwriter built and working then the next sections will look at
some more detailed examples.

9
docs/src/running_the_tests.dox
View file

@ -1,10 +1,11 @@
/**
@page running_the_tests Running the Test Suite
@tableofcontents
This section shows how to set up and run the test suite for libxlsxwriter.
## Functional Tests
@section tests_functional Functional Tests
The functional tests compare the output from libxlsxwriter against xlsx files
created in Excel.
@ -41,7 +42,7 @@ The functional tests can then be run:
=========================== 14 passed in 0.41 seconds =====================
## Unit Tests
@section tests_ Unit Tests
The unit tests test the components of the library at the level of individual
functions or compilation units.
@ -71,7 +72,7 @@ Both functional and unit test can be run together:
$ make test
## Valgrind Tests
@section tests_valgrind Valgrind Tests
The functional tests and examples can be run under
[Valgrind](http://valgrind.org) to verify that there are no memory leaks.
@ -85,7 +86,7 @@ Then run the tests:
make test_valgrind
## Travis Continuous Integration
@section tests_travis Travis Continuous Integration
Libxlsxwriter is configured to run all tests in [Travis Continuous
Integration](https://travis-ci.org/jmcnamara/libxlsxwriter) for each commit.

1
docs/src/tutorial01.dox
View file

@ -1,6 +1,7 @@
/**
@page tutorial01 Tutorial 1: Create a simple XLSX file
Next: @ref tutorial02.
Let's start by creating a simple spreadsheet using C and the
@c libxlsxwriter library.

1
docs/src/tutorial02.dox
View file

@ -1,6 +1,7 @@
/**
@page tutorial02 Tutorial 2: Adding formatting to the XLSX File
Next: @ref tutorial03.
In the previous section we created a simple spreadsheet using C and
the @c libxlsxwriter library.

8
docs/src/working_with_charts.dox
View file

@ -1,12 +1,13 @@
/**
@page working_with_charts Working with Charts
@tableofcontents
This section explains how to work with some of the options and features of
@ref chart.h "The Chart object".
Chart Value and Category Axes
-----------------------------
@section ww_charts_axes Chart Value and Category Axes
When working with charts it is important to understand how Excel
differentiates between a chart axis that is used for series categories and a
@ -24,8 +25,7 @@ axis, some can be set for a category axis and some properties can be set for
both. The documentation calls out the type of axis to which functions apply.
Chart Limitations
-----------------
@section ww_charts_limitations Chart Limitations
The following chart features aren't currently supported in libxlsxwriter but
will be in time:

12
docs/src/working_with_formats.dox
View file

@ -1,11 +1,13 @@
/**
@page working_with_formats Working with Formats
@tableofcontents
The main functions and properties used to add formatting to a cell are shown
in @ref format.h "The Format object". This section provides some additional
information about working with formats.
## Creating and using a Format object
@section ww_formats_creating Creating and using a Format object
Formats are created by calling the workbook_add_format() method and properties
as set using the various functions shown below:
@ -37,7 +39,7 @@ for a row or column:
@endcode
## Format methods and Format properties
@section ww_formats_properties Format methods and Format properties
The following table shows the Excel format categories and the equivalent
`libxlsxwriter` Format function:
@ -76,7 +78,7 @@ The following table shows the Excel format categories and the equivalent
| | Right color | format_set_right_color() |
## Format Colors
@section ww_formats_colors Format Colors
Format property colors are specified using a Html style RGB integer value or a
limited number of defined colors:
@ -88,7 +90,7 @@ limited number of defined colors:
See see @ref working_with_colors for more details.
## Format Defaults
@section ww_formats_default Format Defaults
The default Excel 2007+ cell format is Calibri 11 with all other properties
off.
@ -102,7 +104,7 @@ for example:
format_set_bold(format);
@endcode
## Modifying and Reusing Formats
@section ww_formats_reusing Modifying and Reusing Formats
Once a format has been created it can be used and reused in
`worksheet_write*()` functions across any number of worksheets:

14
docs/src/working_with_memory.dox
View file

@ -1,8 +1,9 @@
/**
@page working_with_memory Working with Memory and Performance
Constant Memory Mode
--------------------
@tableofcontents
@section ww_mem_constant Constant Memory Mode
By default libxlsxwriter holds all cell data in memory. This is to allow
non-sequential data storage and also to allow future features where formatting
@ -33,8 +34,7 @@ features that manipulate cell data after it is written. Currently the only
such feature is worksheet_set_row() which in `constant_memory` mode can only
be used when writing data to the current row.
Row Column Order
----------------
@section ww_mem_row_order Row Column Order
Since each new row flushes the previous row, data must be written in sequential
row order when `constant_memory` mode is on:
@ -52,8 +52,7 @@ row order when `constant_memory` mode is on:
-*- mode: }
@endcode
Inline strings
--------------
@section ww_mem_inline_strings Inline strings
Another optimization that is used to reduce memory usage in `constant_memory`
mode is that cell strings aren't stored in an Excel structure call "shared
@ -61,8 +60,7 @@ strings" and instead are written "in-line". This is a documented Excel feature
that is supported by most spreadsheet applications. One known exception is
Apple Numbers for Mac where the string data isn't displayed.
Performance
-----------
@section ww_mem_performance Performance
Currently the library isn't optimized. There are some known bottlenecks that
will be reduced in upcoming versions. Also, the library is currently single