Reorganize documentation

CHANGES.rst

@@ -1,6 +1,7 @@
 0.16.4 (2022-08-04)
 -------------------
 - Regional fonts for RichText
+- Reorganize documentation
 
 0.16.3 (2022-07-14)
 -------------------

docs/index.rst

@@ -62,31 +62,6 @@ MS Word will create internally only one 'run' in the paragraph. Now,
 if you put in bold a text in the middle of this paragraph,
 word will transform the previous 'run' into 3 different 'runs' (normal - bold - normal).
 
-**Important:**
-
-Always put space after a jinja2 starting var/tag delimiter and a space before the ending one :
-
-Avoid::
-
-   {{myvariable}}
-   {%if something%}
-
-Use instead::
-
-   {{ myvariable }}
-   {% if something %}
-
-Get Defined Variables
-+++++++++++++++++++++
-
-In order to get the missing variables after rendering use ::
-
-   tpl=DocxTemplate('your_template.docx')
-   tpl.render(context_dict)
-   set_of_variables = tpl.get_undeclared_template_variables()
-
-**IMPORTANT** : You may use the method before rendering to get a set of keys you need, e.g. to be prompted to a user or written in a file for manual processing.
-
 Extensions
 ++++++++++
 
@@ -100,8 +75,34 @@ In order to manage paragraphs, table rows, table columns, runs, special syntax h
    {%tc jinja2_tag %} for table columns
    {%r jinja2_tag %} for runs
 
-By using these tags, python-docx-template will take care to put the real jinja2 tags at the right place into the document's xml source code.
+By using these tags, python-docx-template will take care to put the real jinja2 tags (without the `p`, `tr`, `tc` or `r`) at the right place into the document's xml source code.
-In addition, these tags also tell python-docx-template to **remove** the paragraph, table row, table column or run where the begin and ending tags are located and only takes care about what is in between.
+In addition, these tags also tell python-docx-template to **remove** the paragraph, table row, table column or run where the tags are located.
+
+For example, if you have this kind of template::
+
+   {%p if display_paragraph %}
+   One or many paragraphs
+   {%p endif %}
+
+The first and last paragraphs (those containing ``{%p ... %}`` tags) will never appear in generated docx, regardless of the ``display_paragraph`` value.
+
+Here only::
+
+   One or many paragraphs
+
+will appear in generated docx if ``display_paragraph`` is True, otherwise, no paragraph at all are displayed.
+
+**IMPORTANT :** Always put space after a starting tag delimiter and a space before the ending one :
+
+Avoid::
+
+   {%if something%}
+   {%pif display_paragraph%}
+
+Use instead::
+
+   {% if something %}
+   {%p if display_paragraph %}
 
 **IMPORTANT** : Do not use ``{%p``, ``{%tr``, ``{%tc`` or ``{%r`` twice in the same
 paragraph, row, column or run. Example :
@@ -116,8 +117,40 @@ But use this instead in your docx template ::
    Here is my paragraph
    {%p endif %}
 
-This syntax is possible because MS Word considers each line as a new paragraph and
+This syntax is possible because MS Word considers each line as a new paragraph (if you do not use CTRL-RETURN).
-``{%p`` tags are not in the same paragraph in the second case.
+
+Display variables
+.................
+
+As part of jinja2, one can used double braces::
+
+   {{ <var> }}
+
+if ``<var>`` is a string, ``\n``, ``\a``, ``\t`` and ``\f`` will be translated respectively into newlines, new paragraphs, tabs and page breaks
+
+But if ``<var>`` is a RichText_ object, you must specify that you are changing the actual 'run'::
+
+   {{r <var> }}
+
+Note the ``r`` right after the opening braces.
+
+**VERY IMPORTANT :** Variables must not contains characters like ``<``, ``>`` and ``&`` unless using Escaping_
+
+**IMPORTANT :** Always put space after a starting var delimiter and a space before the ending one :
+
+Avoid::
+
+   {{myvariable}}
+   {{rmyrichtext}}
+
+Use instead::
+
+   {{ myvariable }}
+   {{r myrichtext }}
+
+**IMPORTANT** : Do not use 2 times ``{{r`` in the same run. Use RichText.add()
+method to concatenate several strings and styles at python side and only one
+``{{r`` at template side.
 
 Comments
 ........
@@ -130,15 +163,6 @@ You can add jinja-like comments in your template ::
 
 See tests/templates/comments_tpl.docx for an example.
 
-Multiple rendering
-..................
-
-Since v0.15.0, it is possible to create ``DocxTemplate`` object once and call
-``render(context)`` several times. Note that if you want to use replacement
-methods like ``replace_media()``, ``replace_embedded()`` and/or ``replace_zipname()``
-during multiple rendering, you will have to call ``reset_replacements()``
-at rendering loop start.
-
 Split and merge text
 ....................
 
@@ -163,33 +187,35 @@ One can use *ENTER* or *SHIFT+ENTER* to split a text like below, then use ``{%-`
 
 **IMPORTANT 2 :** ``{%- xxx -%}`` tags must be alone in a line : do not add some text before or after on the same line.
 
+Escaping delimiters
+...................
 
-Display variables
+In order to display ``{%``, ``%}``, ``{{`` or ``}}``, one can use::
-.................
 
-As part of jinja2, one can used double braces::
+   {_%, %_}, {_{ or  }_}
 
-   {{ <var> }}
+Tables
+......
 
-if ``<var>`` is a string, ``\n``, ``\a``, ``\t`` and ``\f`` will be translated respectively into newlines, new paragraphs, tabs and page breaks
+Spanning
+~~~~~~~~
 
-But if ``<var>`` is a RichText_ object, you must specify that you are changing the actual 'run'::
+You can span table cells horizontally in two ways, by using ``colspan`` tag (see tests/dynamic_table.py)::
 
-   {{r <var> }}
+   {% colspan <var> %}
 
-Note the ``r`` right after the opening braces.
+`<var>` must contain an integer for the number of columns to span. See tests/test_files/dynamic_table.py for an example.
 
-**IMPORTANT** : Do not use the ``r`` variable in your template because ``{{r}}`` could be interpreted as a ``{{r``
+You can also span horizontally within a for loop (see tests/horizontal_merge.py)::
-without variable specified. Nevertheless, you can use a bigger variable name starting
-with 'r'. For example ``{{render_color}}`` will be interpreted as ``{{ render_color }}`` not as ``{{r ender_color}}``.
 
-**IMPORTANT** : Do not use 2 times ``{{r`` in the same run. Use RichText.add()
+   {% hm %}
-method to concatenate several strings and styles at python side and only one
-``{{r`` at template side.
 
+You can also merge cells vertically within a for loop (see tests/vertical_merge.py)::
+
+   {% vm %}
 
 Cell color
-..........
+~~~~~~~~~~
 
 There is a special case when you want to change the background color of a table cell, you must put the following tag at the very beginning of the cell::
 
@@ -197,24 +223,6 @@ There is a special case when you want to change the background color of a table
 
 `<var>` must contain the color's hexadecimal code *without* the hash sign
 
-Column spanning
-...............
-
-If you want to dynamically span a table cell over many column (this is useful when you have a table with a dynamic column count),
-you must put the following tag at the very beginning of the cell to span::
-
-   {% colspan <var> %}
-
-`<var>` must contain an integer for the number of columns to span. See tests/test_files/dynamic_table.py for an example.
-
-Escaping
-........
-
-In order to display ``{%``, ``%}``, ``{{`` or ``}}``, one can use::
-
-   {_%, %_}, {_{ or  }_}
-
-
 .. _RichText:
 
 RichText
@@ -227,6 +235,9 @@ You can change color, bold, italic, size, font and so on, but the best way is to
 ( Home tab -> modify style -> manage style button -> New style, select ‘Character style’ in the form ), see example in `tests/richtext.py`
 Instead of using ``RichText()``, one can use its shortcut : ``R()``
 
+The ``RichText()`` or ``R()`` offers newline, new paragraph, and page break features : just use ``\n``, ``\a``, ``\t`` or ``\f`` in the
+text, they will be converted accordingly.
+
 There is a specific case for font: if your font is not displayed correctly, it may be because it is defined
 only for a region. To know your region, it requires a little work by analyzing the document.xml inside the docx template (this is a zip file).
 To specify a region, you have to prefix your font name this that region and a column::
@@ -279,10 +290,14 @@ calling method `new_subdoc()` ::
 
 see `tests/merge_docx.py` for full code
 
-Escaping, newline, new paragraph, Listing
+.. _Escaping:
------------------------------------------
 
-When you use a ``{{ <var> }}``, you are modifying an **XML** word document, this means you cannot use all chars,
+Escaping
+--------
+
+By default, no escaping is done : read carefully this chapter if you want to avoid crashes during docx generation.
+
+When you use a ``{{ <var> }}``, under the hood, you are modifying an **XML** word document, this means you cannot use all chars,
 especially ``<``, ``>`` and ``&``. In order to use them, you must escape them. There are 4 ways :
 
    *  ``context = { 'var':R('my text') }`` and ``{{r <var> }}`` in the template (note the ``r``),
@@ -290,12 +305,9 @@ especially ``<``, ``>`` and ``&``. In order to use them, you must escape them. T
    *  ``context = { 'var':escape('my text')}`` and ``{{ <var> }}`` in the template.
    *  enable autoescaping when calling render method: ``tpl.render(context, autoescape=True)`` (default is autoescape=False)
 
-The ``RichText()`` or ``R()`` offers newline, new paragraph, and page break features : just use ``\n``, ``\a``, ``\t`` or ``\f`` in the
-text, they will be converted accordingly.
-
 See tests/escape.py example for more informations.
 
-Another solution, if you want to include a listing into your document, that is to escape the text and manage \n, \a, and \f
+Another solution, if you want to include a listing into your document, that is to escape the text and manage ``\n``, ``\a``, and ``\f``
 you can use the ``Listing`` class :
 
 in your python code::
@@ -303,6 +315,7 @@ in your python code::
    context = { 'mylisting':Listing('the listing\nwith\nsome\nlines \a and some paragraph \a and special chars : <>&') }
 
 in your docx template just use ``{{ mylisting }}``
+
 With ``Listing()``, you will keep the current character styling (except after a ``\a`` as you start a new paragraph).
 
 Replace docx pictures
@@ -368,6 +381,26 @@ The zipname starts with "word/embeddings/". Note that the file to be replaced is
 This works for embedded MSWord file like Excel or PowerPoint file, but won't work for others like PDF, Python or even Text files :
 For these ones, MSWord generate an oleObjectNNN.bin file which is no use to be replaced as it is encoded.
 
+Get Defined Variables
+---------------------
+
+In order to get the missing variables after rendering use ::
+
+   tpl=DocxTemplate('your_template.docx')
+   tpl.render(context_dict)
+   set_of_variables = tpl.get_undeclared_template_variables()
+
+**IMPORTANT** : You may use the method before rendering to get a set of keys you need, e.g. to be prompted to a user or written in a file for manual processing.
+
+Multiple rendering
+------------------
+
+Since v0.15.0, it is possible to create ``DocxTemplate`` object once and call
+``render(context)`` several times. Note that if you want to use replacement
+methods like ``replace_media()``, ``replace_embedded()`` and/or ``replace_zipname()``
+during multiple rendering, you will have to call ``reset_replacements()``
+at rendering loop start.
+
 
 
 Microsoft Word 2016 special cases
@@ -388,20 +421,6 @@ And in your template, use the {{r notation::
    {{r test_space_r}} Spaces will be preserved
    {{r test_tabs_r}} Tabs will be displayed
 
-Tables
-------
-
-You can span table cells horizontally in two ways, by using ``colspan`` tag (see tests/dynamic_table.py)::
-
-   {% colspan <number of column to span> %}
-
-or within a for loop (see tests/horizontal_merge.py)::
-
-   {% hm %}
-
-You can also merge cells vertically within a for loop (see tests/vertical_merge.py)::
-
-   {% vm %}
 
 Jinja custom filters
 --------------------