Simplify README.md and move the full documentation to RST.

ivanlanin · ivanlanin · commit 0bd29cba8212 · 2014-03-20T22:53:48.000+07:00
diff --git a/README.md b/README.md
diff --git a/docs/containers.rst b/docs/containers.rst
@@ -3,6 +3,11 @@
 Containers
 ==========
 
+Containers are objects where you can put elements (texts, lists, tables,
+etc). There are 3 main containers, i.e. sections, headers, and footers.
+There are 3 elements that can also act as containers, i.e. textruns,
+table cells, and footnotes.
+
 Sections
 --------
 
@@ -29,8 +34,8 @@ Section settings
 
 Below are the available settings for section:
 
--  ``orientation`` Page orientation, i.e. ‘portrait’ (default) or
-   ‘landscape’
+-  ``orientation`` Page orientation, i.e. 'portrait' (default) or
+   'landscape'
 -  ``marginTop`` Page margin top in twips
 -  ``marginLeft`` Page margin left in twips
 -  ``marginRight`` Page margin right in twips
@@ -51,21 +56,42 @@ Below are the available settings for section:
    evenPage, oddPage)
 
 The following two settings are automatically set by the use of the
-``orientation`` setting. You can alter them but that’s not recommended.
+``orientation`` setting. You can alter them but that's not recommended.
 
 -  ``pageSizeW`` Page width in twips
 -  ``pageSizeH`` Page height in twips
 
-Section page numbering
-~~~~~~~~~~~~~~~~~~~~~~
+Page number
+~~~~~~~~~~~
 
-You can change a section page numbering.
+You can change a section page number by using the ``pageNumberingStart``
+property of the section.
 
 .. code:: php
 
+    // Method 1
+    $section = $phpWord->createSection(array('pageNumberingStart' => 1));
+
+    // Method 2
     $section = $phpWord->createSection();
     $section->getSettings()->setPageNumberingStart(1);
 
+Multicolumn
+~~~~~~~~~~~
+
+You can change a section layout to multicolumn (like in a newspaper) by
+using the ``breakType`` and ``colsNum`` property of the section.
+
+.. code:: php
+
+    // Method 1
+    $section = $phpWord->createSection(array('breakType' => 'continuous', 'colsNum' => 2));
+
+    // Method 2
+    $section = $phpWord->createSection();
+    $section->getSettings()->setBreakType('continuous');
+    $section->getSettings()->setColsNum(2);
+
 Headers
 -------
 
@@ -77,9 +103,9 @@ the ``createHeader`` method:
     $header = $section->createHeader();
 
 Be sure to save the result in a local object. You can use all elements
-that are available for the footer. See “Footer” section for detail.
+that are available for the footer. See "Footer" section for detail.
 Additionally, only inside of the header reference you can add watermarks
-or background pictures. See “Watermarks” section.
+or background pictures. See "Watermarks" section.
 
 Footers
 -------
@@ -100,4 +126,11 @@ footer. You can add the following elements to footers:
 -  Tables
 -  Preserve text
 
-See the “Elements” section for the detail of each elements.
+See the "Elements" section for the detail of each elements.
+
+Other containers
+----------------
+
+Textruns, table cells, and footnotes are elements that can also act as
+containers. See the corresponding "Elements" section for the detail of
+each elements.
diff --git a/docs/elements.rst b/docs/elements.rst
@@ -18,6 +18,9 @@ syntaxes are as follow:
     $section->addText($text, [$fontStyle], [$paragraphStyle]);
     $textrun = $section->createTextRun([$paragraphStyle]);
 
+Text styles
+~~~~~~~~~~~
+
 You can use the ``$fontStyle`` and ``$paragraphStyle`` variable to
 define text formatting. There are 2 options to style the inserted text
 elements, i.e. inline style by using array or defined style by adding
@@ -49,7 +52,7 @@ Defined style examples:
     $text = $section->addText('Hello world!', 'pStyle');
 
 Font style
-~~~~~~~~~~
+^^^^^^^^^^
 
 Available font styles:
 
@@ -66,7 +69,7 @@ Available font styles:
 -  ``fgColor`` Font highlight color, e.g. *yellow*, *green*, *blue*
 
 Paragraph style
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
 
 Available paragraph styles:
 
@@ -82,7 +85,7 @@ Available paragraph styles:
 -  ``keepNext`` Keep paragraph with next paragraph, *true* or *false*
 -  ``keepLines`` Keep all lines on one page, *true* or *false*
 -  ``pageBreakBefore`` Start paragraph on next page, *true* or *false*
--  ``lineHeight`` text line height, e.g. *1.0*, *1.5*, ect…
+-  ``lineHeight`` text line height, e.g. *1.0*, *1.5*, ect...
 -  ``tabs`` Set of custom tab stops
 
 Titles
@@ -98,7 +101,7 @@ need titles or headings. To add a title to the document, use the
     $section->addTitle($text, [$depth]);
 
 Its necessary to add a title style to your document because otherwise
-the title won’t be detected as a real title.
+the title won't be detected as a real title.
 
 Links
 ~~~~~
@@ -111,8 +114,8 @@ You can add Hyperlinks to the document by using the function addLink:
 
 -  ``$linkSrc`` The URL of the link.
 -  ``$linkName`` Placeholder of the URL that appears in the document.
--  ``$fontStyle`` See “Font style” section.
--  ``$paragraphStyle`` See “Paragraph style” section.
+-  ``$fontStyle`` See "Font style" section.
+-  ``$paragraphStyle`` See "Paragraph style" section.
 
 Preserve texts
 ~~~~~~~~~~~~~~
@@ -138,8 +141,8 @@ syntax. All paramaters are optional.
     $section->addTextBreak([$breakCount], [$fontStyle], [$paragraphStyle]);
 
 -  ``$breakCount`` How many lines
--  ``$fontStyle`` See “Font style” section.
--  ``$paragraphStyle`` See “Paragraph style” section.
+-  ``$fontStyle`` See "Font style" section.
+-  ``$paragraphStyle`` See "Paragraph style" section.
 
 Page breaks
 ~~~~~~~~~~~
@@ -162,11 +165,11 @@ To add a list item use the function ``addListItem``.
 
 -  ``$text`` Text that appears in the document.
 -  ``$depth`` Depth of list item.
--  ``$fontStyle`` See “Font style” section.
+-  ``$fontStyle`` See "Font style" section.
 -  ``$listStyle`` List style of the current element TYPE\_NUMBER,
    TYPE\_ALPHANUM, TYPE\_BULLET\_FILLED, etc. See list of constants in
    PHPWord\_Style\_ListItem.
--  ``$paragraphStyle`` See “Paragraph style” section.
+-  ``$paragraphStyle`` See "Paragraph style" section.
 
 Tables
 ------
@@ -193,12 +196,15 @@ Table style can be defined with ``addTableStyle``:
     $PHPWord->addTableStyle('myTable', $tableStyle, $firstRowStyle);
     $table = $section->addTable('myTable');
 
+Table, row, and cell styles
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Table styles:
 
 -  ``$width`` Table width in percent
--  ``$bgColor`` Background color, e.g. ‘9966CC’
+-  ``$bgColor`` Background color, e.g. '9966CC'
 -  ``$border(Top|Right|Bottom|Left)Size`` Border size in twips
--  ``$border(Top|Right|Bottom|Left)Color`` Border color, e.g. ‘9966CC’
+-  ``$border(Top|Right|Bottom|Left)Color`` Border color, e.g. '9966CC'
 -  ``$cellMargin(Top|Right|Bottom|Left)`` Cell margin in twips
 
 Row styles:
@@ -211,22 +217,25 @@ Cell styles:
 -  ``$width`` Cell width in twips
 -  ``$valign`` Vertical alignment, *top*, *center*, *both*, *bottom*
 -  ``$textDirection`` Direction of text
--  ``$bgColor`` Background color, e.g. ‘9966CC’
+-  ``$bgColor`` Background color, e.g. '9966CC'
 -  ``$border(Top|Right|Bottom|Left)Size`` Border size in twips
--  ``$border(Top|Right|Bottom|Left)Color`` Border color, e.g. ‘9966CC’
+-  ``$border(Top|Right|Bottom|Left)Color`` Border color, e.g. '9966CC'
 -  ``$gridSpan`` Number of columns spanned
 -  ``$vMerge`` *restart* or *continue*
 
 Cell span
 ~~~~~~~~~
 
-You can span a cell on multiple columms.
+You can span a cell on multiple columns by using ``gridSpan`` or
+multiple rows by using ``vMerge``.
 
 .. code:: php
 
     $cell = $table->addCell(200);
     $cell->getStyle()->setGridSpan(5);
 
+See ``Sample_09_Tables.php`` for more code sample.
+
 Images
 ------
 
@@ -302,7 +311,7 @@ Table of contents
 
 To add a table of contents (TOC), you can use the ``addTOC`` method.
 Your TOC can only be generated if you have add at least one title (See
-“Titles”).
+"Titles").
 
 .. code:: php
 
@@ -317,7 +326,7 @@ Your TOC can only be generated if you have add at least one title (See
 Footnotes
 ---------
 
-You can create footnotes in texts or textruns, but it’s recommended to
+You can create footnotes in texts or textruns, but it's recommended to
 use textrun to have better layout.
 
 On textrun:
diff --git a/docs/general.rst b/docs/general.rst
@@ -7,7 +7,7 @@ Basic example
 -------------
 
 The following is a basic example of the PHPWord library. More examples
-are provided in the `samples folder`.
+are provided in the `samples folder <samples/>`__.
 
 .. code:: php
 
@@ -77,8 +77,8 @@ name. Use the following functions:
 Measurement units
 -----------------
 
-The base length unit in Open Office XML is twip. Twip means “TWentieth
-of an Inch Point”, i.e. 1 twip = 1/1440 inch.
+The base length unit in Open Office XML is twip. Twip means "TWentieth
+of an Inch Point", i.e. 1 twip = 1/1440 inch.
 
 You can use PHPWord helper functions to convert inches, centimeters, or
 points to twips.
diff --git a/docs/index.rst b/docs/index.rst
@@ -3,10 +3,16 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to PHPWord's documentation!
-===================================
+Welcome to PHPWord's documentation
+==================================
 
-Contents:
+|PHPWord|
+
+PHPWord is a library written in pure PHP that provides a set of classes to
+write to and read from different document file formats. The current version of
+PHPWord supports Microsoft Office Open XML (OOXML or OpenXML), OASIS Open
+Document Format for Office Applications (OpenDocument or ODF), and Rich Text
+Format (RTF).
 
 .. toctree::
    :maxdepth: 2
@@ -17,15 +23,16 @@ Contents:
    containers
    elements
    templates
+   references
    recipes
    faq
    credits
 
-
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
 
+.. |PHPWord| image:: https://raw.github.com/PHPOffice/PHPWord/develop/docs/images/phpword.png
diff --git a/docs/intro.rst b/docs/intro.rst
@@ -5,35 +5,32 @@ Introduction
 
 PHPWord is a library written in pure PHP that provides a set of classes
 to write to and read from different document file formats. The current
-version of PHPWord supports Microsoft `Office Open XML`_ (OOXML or
-OpenXML), OASIS `Open Document Format for Office Applications`_
-(OpenDocument or ODF), and `Rich Text Format`_ (RTF).
+version of PHPWord supports Microsoft `Office Open
+XML <http://en.wikipedia.org/wiki/Office_Open_XML>`__ (OOXML or
+OpenXML), OASIS `Open Document Format for Office
+Applications <http://en.wikipedia.org/wiki/OpenDocument>`__
+(OpenDocument or ODF), and `Rich Text
+Format <http://en.wikipedia.org/wiki/Rich_Text_Format>`__ (RTF).
 
 No Windows operating system is needed for usage because the resulting
 DOCX, ODT, or RTF files can be opened by all major `word processing
-softwares`_.
+softwares <http://en.wikipedia.org/wiki/List_of_word_processors>`__.
 
-PHPWord is an open source project licensed under `LGPL`_. PHPWord is
-`unit tested`_ to make sure that the released versions are stable.
+PHPWord is an open source project licensed under `LGPL <license.md>`__.
+PHPWord is `unit tested <https://travis-ci.org/PHPOffice/PHPWord>`__ to
+make sure that the released versions are stable.
 
-**Want to contribute?** `Fork us`_ or `submit`_ your bug reports or
-feature requests to us.
-
-.. _Office Open XML: http://en.wikipedia.org/wiki/Office_Open_XML
-.. _Open Document Format for Office Applications: http://en.wikipedia.org/wiki/OpenDocument
-.. _Rich Text Format: http://en.wikipedia.org/wiki/Rich_Text_Format
-.. _word processing softwares: http://en.wikipedia.org/wiki/List_of_word_processors
-.. _LGPL: license.md
-.. _unit tested: https://travis-ci.org/PHPOffice/PHPWord
-.. _Fork us: https://github.com/PHPOffice/PHPWord/fork
-.. _submit: https://github.com/PHPOffice/PHPWord/issues
+**Want to contribute?** `Fork
+us <https://github.com/PHPOffice/PHPWord/fork>`__ or
+`submit <https://github.com/PHPOffice/PHPWord/issues>`__ your bug
+reports or feature requests to us.
 
 Features
 --------
 
 -  Set document properties, e.g. title, subject, and creator.
--  Create document sections with different settings,
-   e.g. portrait/landscape, page size, and page numbering
+-  Create document sections with different settings, e.g.
+   portrait/landscape, page size, and page numbering
 -  Create header and footer for each sections
 -  Set default font type, font size, and paragraph style
 -  Use UTF-8 and East Asia fonts/characters
@@ -54,7 +51,7 @@ Features
 -  Create document from templates
 -  Use XSL 1.0 style sheets to transform main document part of OOXML
    template
--  … and many more features on progress
+-  ... and many more features on progress
 
 File formats
 ------------
diff --git a/docs/references.rst b/docs/references.rst
@@ -0,0 +1,20 @@
+.. _references:
+
+References
+==========
+
+Formal specifications
+---------------------
+
+-  `Office Open XML (OOXML) (ECMA-376)
+   Schema <http://www.schemacentral.com/sc/ooxml/ss.html>`__
+-  `Oasis OpenDocument Standard Version
+   1.2 <http://docs.oasis-open.org/office/v1.2/os/OpenDocument-v1.2-os.html>`__
+-  `Rich Text Format (RTF) Specification, version
+   1.9.1 <http://www.microsoft.com/en-us/download/details.aspx?id=10725>`__
+
+Other resources
+---------------
+
+-  `DocumentFormat.OpenXml.Wordprocessing Namespace on
+   MSDN <http://msdn.microsoft.com/en-us/library/documentformat.openxml.wordprocessing%28v=office.14%29.aspx>`__
diff --git a/docs/setup.rst b/docs/setup.rst
diff --git a/docs/templates.rst b/docs/templates.rst
