Minor doc changes.

dev/docs/source/author.rst

@@ -15,8 +15,9 @@ You can contact me at jmcnamara@cpan.org.
 Donations
 ---------
 
-If you would like to donate to the XlsxWriter project to keep it active you
-can do so via `PayPal <https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=RRZCPSL65X858>`_.
+If you would like to donate to the XlsxWriter project to keep it active you can
+do so via
+`PayPal <https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=RRZCPSL65X858>`_.
 
 .. raw:: html
 

dev/docs/source/bugs.rst

@@ -6,6 +6,22 @@ Known Issues and Bugs
 This section lists known issues and bugs and gives some information on how to
 submit bug reports.
 
+Content is Unreadable. Open and Repair
+--------------------------------------
+
+Very, very occasionally you may see an Excel warning when opening an XlsxWriter
+file like:
+
+   Excel could not open file.xlsx because some content is unreadable. Do you
+   want to open and repair this workbook.
+
+This ominous sounding message is Excel's default warning for any validation
+error in the XML used for the components of the XLSX file.
+
+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`.
+
 
 'unknown encoding: utf-8' Error
 -------------------------------
@@ -19,6 +35,24 @@ at the end of the program::
 This appears to be an issue with the implicit destructor on Windows. It is
 under investigation. Use ``close()`` as a workaround.
 
+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
+of these functions are ``ACOT``, ``CHISQ.DIST.RT`` , ``CONFIDENCE.NORM``,
+``STDEV.P``, ``STDEV.S`` and ``WORKDAY.INTL``. The full list is given in the
+`MS XLSX extensions documentation on future functions <http://msdn.microsoft.com/en-us/library/dd907480%28v=office.12%29.aspx>`_.
+
+When written using ``write_formula()`` these functions need to be fully
+qualified with the ``_xlfn.`` prefix as they are shown in the MS XLSX
+documentation link above. For example::
+
+    worksheet.write_formula('A1', '=_xlfn.STDEV.S(B1:B10)')
+
+
+
+
 
 Formula results displaying as zero in non-Excel applications
 ------------------------------------------------------------
@@ -79,8 +113,7 @@ follows::
 
     python -c 'import xlsxwriter; print(xlsxwriter.__version__)'
 
-Check the :ref:`changes` section to see what has changed in the latest
-versions.
+Check the :ref:`changes` section to see what has changed in the latest versions.
 
 
 Read the documentation

dev/docs/source/getting_started.rst

@@ -104,8 +104,8 @@ Documentation
 -------------
 
 The latest version of this document is hosted on
-`Read The Docs <https://xlsxwriter.readthedocs.org/en/latest/>`_. It is
-also available as a
+`Read The Docs <https://xlsxwriter.readthedocs.org/en/latest/>`_. It is also
+available as a
 `PDF <https://github.com/jmcnamara/XlsxWriter/raw/master/docs/XlsxWriter.pdf>`_.
 
 Once you are happy that the module is installed and operational you can have a

dev/docs/source/index.rst

@@ -11,9 +11,9 @@ XlsxWriter is a Python module for creating Excel XLSX files.
 
    **XlsxWriter**
 
-XlsxWriter can be used to write text, numbers, formulas and hyperlinks to
-multiple worksheets and it supports features such as formatting and many more,
-including:
+XlsxWriter is a Python module that can be used to write text, numbers, formulas
+and hyperlinks to multiple worksheets in an Excel 2007+ XLSX file. It supports
+features such as formatting and many more, including:
 
 * 100% compatible Excel XLSX files.
 * Full formatting.
@@ -34,7 +34,7 @@ standard libraries only.
 .. only:: html
 
    This document explains how to use the XlsxWriter module. See the following
-   sections for more information.
+   sections for more information, or jump straight to the :ref:`intro`.
 
    .. toctree::
       :maxdepth: 1

dev/docs/source/introduction.rst

@@ -10,15 +10,27 @@ It can be used to write text, numbers, and formulas to multiple worksheets and
 it supports features such as formatting, images, charts, page setup,
 autofilters, conditional formatting and many others.
 
-This module cannot be used to modify or write to an existing Excel XLSX file.
-There are some :ref:`alternatives` Python modules that do that.
-
-XlsxWriter is intended to have a high degree of compatibility with files
-produced by Excel. In most cases the files produced are 100% equivalent to
-files produced by Excel and the
-`test suite <https://github.com/jmcnamara/XlsxWriter/tree/master/xlsxwriter/test/comparison>`_
-contains a large number of test cases that verify the output of XlsxWriter
-against actual files created in Excel.
-
-XlsxWriter is licensed under a BSD :ref:`License` and is available as a ``git``
-repository on `GitHub <http://github.com/jmcnamara/XlsxWriter>`_.
+XlsxWriter has some advantages and disadvantages over the
+:ref:`alternative Python modules <alternatives>` for writing Excel files.
+
+* Advantages:
+
+   * It supports more Excel features than any of the alternative modules.
+
+   * It has a high degree of fidelity with files produced by Excel. In most
+     cases the files produced are 100% equivalent to files produced by Excel.
+
+   * It has extensive documentation, example files and tests.
+
+   * It is fast and can be configured to use very little memory even for very
+     large output files.
+
+* Disadvantages:
+
+   * It cannot read or modify existing Excel XLSX files.
+
+
+XlsxWriter is licensed under a BSD :ref:`License` and the source code is
+available on `GitHub <http://github.com/jmcnamara/XlsxWriter>`_.
+
+To try out the module see the next section on :ref:`getting_started`.

dev/docs/source/page_setup.rst

@@ -619,21 +619,23 @@ worksheet.set_h_pagebreaks()
 
    Set the horizontal page breaks on a worksheet.
 
-   :param list breaks: List of pagebreak rows.
+   :param list breaks: List of page break rows.
 
 The ``set_h_pagebreaks()`` method adds horizontal page breaks to a worksheet. A
 page break causes all the data that follows it to be printed on the next page.
-Horizontal page breaks act between rows. To create a page break between rows
-20 and 21 you must specify the break at row 21. However in zero index notation
-this is actually row 20. So you can pretend for a small while that you are
-using 1 index notation::
+Horizontal page breaks act between rows.
 
-    worksheet1.set_h_pagebreaks([20])  # Break between row 20 and 21.
-
-The ``set_v_pagebreaks()`` method takes a list of page breaks::
+The ``set_h_pagebreaks()`` method takes a list of one or more page breaks::
 
+    worksheet1.set_v_pagebreaks([20])
     worksheet2.set_v_pagebreaks([20, 40, 60, 80, 100])
 
+To create a page break between rows 20 and 21 you must specify the break at row
+21. However in zero index notation this is actually row 20. So you can pretend
+for a small while that you are using 1 index notation::
+
+    worksheet.set_h_pagebreaks([20])  # Break between row 20 and 21.
+
 .. Note::
    Note: If you specify the "fit to page" option via the ``fit_to_pages()``
    method it will override all manual page breaks.
@@ -649,7 +651,7 @@ worksheet.set_v_pagebreaks()
 
    Set the vertical page breaks on a worksheet.
 
-   :param list breaks: List of pagebreak columns.
+   :param list breaks: List of page break columns.
 
 The ``set_v_pagebreaks()`` method is the same as the above
 :func:`set_h_pagebreaks()` method except it adds page breaks between columns.

dev/docs/source/worksheet.rst

@@ -272,18 +272,28 @@ formula. The calculated ``value`` is added at the end of the argument list::
 
     worksheet.write('A1', '=2+2', num_format, 4)
 
-.. note::
-
-   Excel stores formulas in US style formatting regardless of the Locale or
-   Language of the Excel version. Therefore all formula names written using
-   XlsxWriter must be in English (use the following
-   `formula translator <http://fr.excel-translator.de>`_ if necessary). Also,
-   formulas must be written with the US style separator/range operator which
-   is a comma (not semi-colon). Therefore a formula with multiple values
-   should be written as follows::
-
-      worksheet.write_formula('A1', '=SUM(1, 2, 3)')  # OK
-      worksheet.write_formula('A2', '=SUM(1; 2; 3)')  # NO. Error on load.
+Excel stores formulas in US style formatting regardless of the Locale or
+Language of the Excel version. Therefore all formula names written using
+XlsxWriter must be in English (use the following
+`formula translator <http://fr.excel-translator.de>`_ if necessary). Also,
+formulas must be written with the US style separator/range operator which is a
+comma (not semi-colon). Therefore a formula with multiple values should be
+written as follows::
+
+    worksheet.write_formula('A1', '=SUM(1, 2, 3)')  # OK
+    worksheet.write_formula('A2', '=SUM(1; 2; 3)')  # NO. Error on load.
+
+Excel 2010 and 2013 added functions which weren't defined in the original file
+specification. These functions are referred to as *future* functions. Examples
+of these functions are ``ACOT``, ``CHISQ.DIST.RT`` , ``CONFIDENCE.NORM``,
+``STDEV.P``, ``STDEV.S`` and ``WORKDAY.INTL``. The full list is given in the
+`MS XLSX extensions documentation on future functions <http://msdn.microsoft.com/en-us/library/dd907480%28v=office.12%29.aspx>`_.
+
+When written using ``write_formula()`` these functions need to be fully
+qualified with the ``_xlfn.`` prefix as they are shown in the MS XLSX
+documentation link above. For example::
+
+    worksheet.write_formula('A1', '=_xlfn.STDEV.S(B1:B10)')
 
 
 worksheet.write_array_formula()