Added extra docs for temp file handling.

Changes.txt

@@ -11,7 +11,7 @@
 
 # 0.3.9 July 2 2016
 
-- Added support for MinGW, MinGW-w64, Gygwin, MSYS and MSYS2.
+- Added support for MinGW, MinGW-w64, Cygwin, MSYS and MSYS2.
   See @ref gsg_ming.
 
 

docs/src/getting_started.dox

@@ -240,6 +240,26 @@ libxlsxwriter example programs by copying the code from one of the
 `libxlsxwriter\example\*.c` programs.
 
 
+@subsection gsg_tmpdir Specifying a TEMP directory for libxlsxwriter
+
+The libxlsxwriter library creates temporary files in the system `TEMP`
+directory during assembly of an xlsx file. On Windows this directory may not
+be writeable by a libxlsxwriter application (although it will try several
+`TEMP` locations before returning an error). To work around this you can set
+the `tmpdir` parameter of the #lxw_workbook_options struct and pass it to
+`workbook_new_opt()`:
+
+@code
+   lxw_workbook_options options = {.constant_memory = LXW_FALSE,
+                                   .tmpdir = "C:\\Temp"};
+
+   lxw_workbook  *workbook  = workbook_new_opt("filename.xlsx", &options);
+@endcode
+
+This can also be used on Unix systems where the `TEMP` directory isn't
+writeable.
+
+
 @section gsg_ming Installation on Windows using Mingw-w64 and MSYS2
 
 The libxlsxwriter library can also be compiled on Windows using the
@@ -267,17 +287,11 @@ 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) and
+It is also possible to use [Cygwin](https://cygwin.com) and the older [MinGW
-with [Cygwin](https://cygwin.com). Libxlsxwriter has been confirmed to compile
+and MSYS](http://mingw.org). Libxlsxwriter has been confirmed to compile and
-and work in all of these environments.
+work in all of these environments.
 
-@note The libxlsxwriter library uses files in the system TEMP directory during
+See also @ref gsg_tmpdir.
-assembly of a xlsx file. On Windows this directory may not be writeable by a
-libxlsxwriter application. To work around this you can make the Windows TEMP
-directory writeable or if you are using MSYS/MSYS2 you can change the `/tmp`
-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`
 
 @section gsg_next Next steps
 

examples/constant_memory.c

@@ -16,7 +16,8 @@ int main() {
     lxw_col_t max_col = 50;
 
     /* Set the worksheet options. */
-    lxw_workbook_options options = {LXW_TRUE, NULL};
+    lxw_workbook_options options = {.constant_memory = LXW_TRUE,
+                                    .tmpdir = NULL};
 
     /* Create a new workbook with options. */
     lxw_workbook  *workbook  = workbook_new_opt("constant_memory.xlsx", &options);

include/xlsxwriter/common.h

@@ -233,7 +233,7 @@ enum lxw_custom_property_types {
 #define lxw_snprintf __builtin_snprintf
 #endif
 
-/* Define a snprintf for MCVC 2010. */
+/* Define a snprintf for MSVC 2010. */
 #if defined(_MSC_VER) && _MSC_VER < 1900
 
 #include <stdarg.h>

include/xlsxwriter/workbook.h

@@ -171,7 +171,7 @@ typedef struct lxw_doc_properties {
  * - `constant_memory`: Reduces the amount of data stored in memory so that
  *   large files can be written efficiently.
  *
- *   Note, in this mode a row of data is written and then discarded when a
+ *   @note In this mode a row of data is written and then discarded when a
  *   cell in a new row is added via one of the `worksheet_write_*()`
  *   methods. Therefore, once this option is active, data should be written in
  *   sequential row order. For this reason the `worksheet_merge_range()`
@@ -187,7 +187,7 @@ typedef struct lxw_workbook_options {
     /** Optimize the workbook to use constant memory for worksheets */
     uint8_t constant_memory;
 
-    /**  Directory to use for temporary files used by libxlsxwriter. */
+    /** Directory to use for the temporary files created by libxlsxwriter. */
     char *tmpdir;
 } lxw_workbook_options;
 
@@ -273,15 +273,28 @@ lxw_workbook *workbook_new(const char *filename);
  * additional options to be set.
  *
  * @code
- *    lxw_workbook_options options = {.constant_memory = 1};
+ *    lxw_workbook_options options = {.constant_memory = 1,
+ *                                    .tmpdir = "C:\\Temp"};
  *
  *    lxw_workbook  *workbook  = workbook_new_opt("filename.xlsx", &options);
  * @endcode
  *
- * Note, in this mode a row of data is written and then discarded when a cell
+ * The options that can be set via #lxw_workbook_options are:
- * in a new row is added via one of the worksheet `worksheet_write_*()`
+ *
- * methods.  Therefore, once this mode is active, data should be written in
+ * - `constant_memory`: Reduces the amount of data stored in memory so that
- * sequential row order.
+ *   large files can be written efficiently.
+ *
+ *   @note In this mode a row of data is written and then discarded when a
+ *   cell in a new row is added via one of the `worksheet_write_*()`
+ *   methods. Therefore, once this option is active, data should be written in
+ *   sequential row order. For this reason the `worksheet_merge_range()`
+ *   doesn't work in this mode. See also @ref ww_mem_constant.
+ *
+ * - `tmpdir`: libxlsxwriter stores workbook data in temporary files prior
+ *   to assembling the final XLSX file. The temporary files are created in the
+ *   system's temp directory. If the default temporary directory isn't
+ *   accessible to your application, or doesn't contain enough space, you can
+ *   specify an alternative location using the `tempdir` option.*
  *
  * See @ref working_with_memory for more details.
  *