Update FAQ, add TODO-list example.

git-svn-id: https://svn.code.sf.net/p/docutils/code/trunk@9276 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

2 files changed, 334 insertions, 139 deletions

diff --git a/docutils/FAQ.txt b/docutils/FAQ.txt
index c68426bcc..83a6e148a 100644
--- a/docutils/FAQ.txt
+++ b/docutils/FAQ.txt
@@ -1,10 +1,6 @@
-.. -*- coding: utf-8 -*-
-
-
 .. NOTE TO MAINTAINERS: Please add new questions to the end of their
    sections, so section/question numbers remain stable.
 
-
 ===========================================
  Docutils FAQ (Frequently Asked Questions)
 ===========================================
@@ -19,8 +15,8 @@
 
 
 This is a work in progress.  If you are reading a local copy, the
-`master copy`_ might be newer.  This document uses are relative links;
-if they don't work, please use the `master copy`_.
+`master copy`_ might be newer.  This document uses relative links;
+if they don't work, please use the master copy.
 
 Please feel free to ask questions and/or provide answers; send email
 to the `Docutils-users`_ mailing list.  Project members should feel
@@ -215,12 +211,12 @@ __ https://en.wikipedia.org/wiki/Representational_State_Transfer
 What's the standard filename extension for a reStructuredText file?
 -------------------------------------------------------------------
 
-It's ".txt".  Some people would like to use ".rest" or ".rst" or
-".restx", but why bother?  ReStructuredText source files are meant to
-be readable as plaintext, and most operating systems already associate
-".txt" with text files.  Using a specialized filename extension would
-require that users alter their OS settings, which is something that
-many users will not be willing or able to do.
+It's ".txt".  ReStructuredText source files are meant to be readable as
+plaintext, and most operating systems already associate ".txt" with text
+files.
+
+That said, we see an increasing number of projects settling on
+the extension ".rst".
 
 Also see `What's the official MIME type for reStructuredText data?`_
 
@@ -275,10 +271,10 @@ How can I represent esoteric characters (e.g. character entities) in a document?
 
 For example, say you want an em-dash (XML character entity —,
 Unicode character U+2014) in your document: use a real em-dash.
-Insert concrete characters (e.g. type a *real* em-dash) into your
+Insert literal characters (e.g. type a *real* em-dash) into your
 input file, using whatever encoding suits your application, and tell
 Docutils the input encoding.  Docutils uses Unicode internally, so the
-em-dash character is a real em-dash internally.
+em-dash character is U+2014 internally.
 
 Emacs users should refer to the `Emacs Support for reStructuredText`__
 document.  Tips for other editors are welcome.
@@ -286,7 +282,8 @@ document.  Tips for other editors are welcome.
 __ tools/editors/emacs/README.html
 
 ReStructuredText has no character entity subsystem; it doesn't know
-anything about XML charents.  To Docutils, "—" in input text is
+anything about XML character entities.
+To Docutils, "—" in input text is
 7 discrete characters; no interpretation happens.  When writing HTML,
 the "&" is converted to "&", so in the raw output you'd see
 "—".  There's no difference in interpretation for text
@@ -294,26 +291,19 @@ inside or outside inline literals or literal blocks -- there's no
 character entity interpretation in either case.
 
 If you can't use a Unicode-compatible encoding and must rely on 7-bit
-ASCII, there is a workaround.  New in Docutils 0.3.10 is a set of
-`Standard Substitution Definition Sets`_, which provide equivalents of
-XML & HTML character entity sets as substitution definitions.  For
-example, the Japanese yen currency symbol can be used as follows::
+ASCII, there is a workaround:
+`Standard Substitution Definition Sets`_ provide equivalents of
+XML & HTML character entity sets as substitution definitions. [#]_
+For example, the Japanese yen currency symbol can be used as follows::
 
     .. include:: <xhtml1-lat1.txt>
 
     |yen| 600 for a complete meal?  That's cheap!
 
-Thanks to David Priest for the original idea.
-
-If you insist on using XML-style charents, you'll have to implement a
-pre-processing system to convert to UTF-8 or something.  That
-introduces complications though; you can no longer *write* about
-charents naturally; instead of writing "&mdash;" you'd have to write
-"&amp;mdash;".
+.. [#] Thanks to David Priest for the original idea.
 
-For the common case of long dashes, you might also want to insert the
-following substitution definitions into your document (both of them are
-using the "unicode_" directive)::
+You can create custom `substitution definitions`_ in your document
+using the "unicode_" directive, e.g.::
 
     .. |--| unicode:: U+2013   .. en dash
     .. |---| unicode:: U+2014  .. em dash, trimming surrounding whitespace
@@ -331,12 +321,9 @@ thus you need to add spaces ("``foo |---| bar``") and advise the
 reStructuredText parser to trim the spaces.
 
 .. _Standard Substitution Definition Sets: docs/ref/rst/definitions.html
+.. _substitution definitions: docs/ref/rst/restructuredtext.html
+                              #substitution-definitions
 .. _unicode: docs/ref/rst/directives.html#unicode-character-codes
-.. _are available: https://docutils.sourceforge.io/tmp/charents/
-.. _tarball: https://docutils.sourceforge.io/tmp/charents.tgz
-.. _description and instructions:
-   https://docutils.sourceforge.io/tmp/charents/README.html
-.. _to-do list: docs/dev/todo.html
 
 
 How can I generate backticks using a Scandinavian keyboard?
@@ -541,8 +528,9 @@ be indented and that ambiguous cases be escaped.
 How can I include mathematical equations in documents?
 ------------------------------------------------------
 
-Use the `math directive`_ and `math role`_, available since Docutils 0.8.
+Use `LaTeX math syntax`_ in a `math directive`_ or `math role`_.
 
+.. _LaTeX math syntax: docs/ref/rst/mathematics.html
 .. _math directive: docs/ref/rst/directives.html#math
 .. _math role: docs/ref/rst/roles.html#math
 
@@ -877,22 +865,66 @@ reStructuredText file?`_
 .. [#] The "x-" prefix means it's an unregistered MIME type.
 
 
+How can I mark up a TODO list?
+------------------------------
+
+You may use a field list with class argument and some CSS styling.
+For an example see `Docutils TODO lists`_ and its source todo-lists.txt_.
+
+.. _Docutils TODO lists: docs/user/todo-lists.html
+.. _todo-lists.txt: docs/user/todo-lists.txt
+
+
+How can I specify an image grid?
+--------------------------------
+
+In order to arrange images (or other content) in a grid,
+a borderless `list table`_ can be used. For example::
+
+    .. list-table::
+       :class: borderless
+     
+       * - .. image:: rst/images/title-scaling.svg
+         - .. image:: rst/images/biohazard.svg
+       * - .. image:: rst/images/biohazard.svg
+         - .. image:: rst/images/biohazard.svg
+    
+Use figures, if you want also captions::
+    
+    .. list-table:: 
+      :class: borderless
+    
+      * - .. figure:: rst/images/title-scaling.svg
+    
+            Figure 1/1
+    
+        - .. figure:: rst/images/biohazard.svg
+    
+            Figure 1/2
+
+.. _list table: docs/ref/rst/directives.html#list-table
+
+
 HTML Writer
 ===========
 
 What is the status of the HTML Writer?
 --------------------------------------
 
-The default HTML Writer module, ``docutils/writers/html4css1.py``, is
+The default HTML Writer module, `html4css1`_, is
 a proof-of-concept reference implementation.  While it is a complete
 implementation, some aspects of the HTML it produces may be outdated or
 incompatible with older browsers or specialized applications (such as
 web templating).
 
+The `html5 writer`_ generates semantic HTML output compatible with HTML5.
 For the full selection see `Docutils HTML writers`_
 
+.. _html4css1: docs/user/html.html#html4css1
+.. _HTML5 writer: docs/user/html.html#html5
 .. _Docutils HTML writers: docs/user/html.html
 
+
 What browsers are supported?
 ----------------------------
 
@@ -907,110 +939,116 @@ browsers are welcome.
 Unexpected results from tools/rst2html.py: H1, H1 instead of H1, H2.  Why?
 --------------------------------------------------------------------------
 
-Here's the question in full:
-
-    I have this text::
-
-        Heading 1
-        =========
+This only regards output from the `html4css1`_ writer.
+The `html5 writer`_ uses H1, H2, ...
+
+.. class:: details
+
+details
+    Here's the question in full:
+
+        I have this text::
+
+            Heading 1
+            =========
 
-        All my life, I wanted to be H1.
+            All my life, I wanted to be H1.
 
-        Heading 1.1
-        -----------
+            Heading 1.1
+            -----------
 
-        But along came H1, and so shouldn't I be H2?
-        No!  I'm H1!
+            But along came H1, and so shouldn't I be H2?
+            No!  I'm H1!
 
-        Heading 1.1.1
-        *************
+            Heading 1.1.1
+            *************
 
-        Yeah, imagine me, I'm stuck at H3!  No?!?
+            Yeah, imagine me, I'm stuck at H3!  No?!?
 
-    When I run it through tools/rst2html.py, I get unexpected results
-    (below).  I was expecting H1, H2, then H3; instead, I get H1, H1,
-    H2::
+        When I run it through tools/rst2html.py, I get unexpected results
+        (below).  I was expecting H1, H2, then H3; instead, I get H1, H1,
+        H2::
 
-        ...
-        <html lang="en">
-        <head>
-        ...
-        <title>Heading 1</title>
-        </head>
-        <body>
-        <div class="document" id="heading-1">
-        <h1 class="title">Heading 1</h1>                <-- first H1
-        <p>All my life, I wanted to be H1.</p>
-        <div class="section" id="heading-1-1">
-        <h1><a name="heading-1-1">Heading 1.1</a></h1>        <-- H1
-        <p>But along came H1, and so now I must be H2.</p>
-        <div class="section" id="heading-1-1-1">
-        <h2><a name="heading-1-1-1">Heading 1.1.1</a></h2>
-        <p>Yeah, imagine me, I'm stuck at H3!</p>
-        ...
+            ...
+            <html lang="en">
+            <head>
+            ...
+            <title>Heading 1</title>
+            </head>
+            <body>
+            <div class="document" id="heading-1">
+            <h1 class="title">Heading 1</h1>                <-- first H1
+            <p>All my life, I wanted to be H1.</p>
+            <div class="section" id="heading-1-1">
+            <h1><a name="heading-1-1">Heading 1.1</a></h1>        <-- H1
+            <p>But along came H1, and so now I must be H2.</p>
+            <div class="section" id="heading-1-1-1">
+            <h2><a name="heading-1-1-1">Heading 1.1.1</a></h2>
+            <p>Yeah, imagine me, I'm stuck at H3!</p>
+            ...
 
-    What gives?
+        What gives?
 
-Check the "class" attribute on the H1 tags, and you will see a
-difference.  The first H1 is actually ``<h1 class="title">``; this is
-the document title, and the default stylesheet renders it centered.
-There can also be an ``<h2 class="subtitle">`` for the document
-subtitle.
+    Check the "class" attribute on the H1 tags, and you will see a
+    difference.  The first H1 is actually ``<h1 class="title">``; this is
+    the document title, and the default stylesheet renders it centered.
+    There can also be an ``<h2 class="subtitle">`` for the document
+    subtitle.
 
-If there's only one highest-level section title at the beginning of a
-document, it is treated specially, as the document title.  (Similarly, a
-lone second-highest-level section title may become the document
-subtitle.)  See `How can I indicate the document title?  Subtitle?`_ for
-details.  Rather than use a plain H1 for the document title, we use ``<h1
-class="title">`` so that we can use H1 again within the document.  Why
-do we do this?  HTML only has H1-H6, so by making H1 do double duty, we
-effectively reserve these tags to provide 6 levels of heading beyond the
-single document title.
+    If there's only one highest-level section title at the beginning of a
+    document, it is treated specially, as the document title.  (Similarly, a
+    lone second-highest-level section title may become the document
+    subtitle.)  See `How can I indicate the document title?  Subtitle?`_ for
+    details.  Rather than use a plain H1 for the document title, we use ``<h1
+    class="title">`` so that we can use H1 again within the document.  Why
+    do we do this?  HTML only has H1-H6, so by making H1 do double duty, we
+    effectively reserve these tags to provide 6 levels of heading beyond the
+    single document title.
 
-With "html4css1", HTML is being used for dumb formatting for nothing
-but final display. A stylesheet *is required*, and one is provided;
-see `Docutils HTML writers`_.  Of course, you're
-welcome to roll your own.  The default stylesheet provides rules to
-format ``<h1 class="title">`` and ``<h2 class="subtitle">``
-differently from ordinary ``<h1>`` and ``<h2>``::
+    With "html4css1", HTML is being used for dumb formatting for nothing
+    but final display. A stylesheet *is required*, and one is provided;
+    see `Docutils HTML writers`_.  Of course, you're
+    welcome to roll your own.  The default stylesheet provides rules to
+    format ``<h1 class="title">`` and ``<h2 class="subtitle">``
+    differently from ordinary ``<h1>`` and ``<h2>``::
 
-    h1.title {
-      text-align: center }
+        h1.title {
+          text-align: center }
 
-    h2.subtitle {
-      text-align: center }
+        h2.subtitle {
+          text-align: center }
 
-If you don't want the top section heading to be interpreted as a
-title at all, disable the `doctitle_xform`_ setting
-(``--no-doc-title`` option).  This will interpret your document
-differently from the standard settings, which might not be a good
-idea.  If you don't like the reuse of the H1 in the HTML output, you
-can tweak the `initial_header_level`_ setting
-(``--initial-header-level`` option) -- but unless you match its value
-to your specific document, you might end up with bad HTML (e.g. H3
-without H2).
+    If you don't want the top section heading to be interpreted as a
+    title at all, disable the `doctitle_xform`_ setting
+    (``--no-doc-title`` option).  This will interpret your document
+    differently from the standard settings, which might not be a good
+    idea.  If you don't like the reuse of the H1 in the HTML output, you
+    can tweak the `initial_header_level`_ setting
+    (``--initial-header-level`` option) -- but unless you match its value
+    to your specific document, you might end up with bad HTML (e.g. H3
+    without H2).
 
-.. _doctitle_xform: docs/user/config.html#doctitle-xform
-.. _initial_header_level: docs/user/config.html#initial-header-level
+    .. _doctitle_xform: docs/user/config.html#doctitle-xform
+    .. _initial_header_level: docs/user/config.html#initial-header-level
 
-(Thanks to Mark McEahern for the question and much of the answer.)
+    (Thanks to Mark McEahern for the question and much of the answer.)
 
-.. note:: For the html5 writer, `initial_header_level`_ defaults to
-   ``2`` because this is what the `HTML5 standard`__ expects as
-   start value for headings nested in <section> elements.
+    .. note:: For the `html5 writer`_, `initial_header_level`_ defaults to
+       ``2`` because this is what the `HTML5 standard`__ expects as
+       start value for headings nested in <section> elements.
 
-   .. Sectioning content elements are always considered subsections of
-      their nearest ancestor *sectioning root* [#]_ or their nearest
-      ancestor element of *sectioning content*  [#]_, whichever is nearest,
-      [...]
+       .. Sectioning content elements are always considered subsections of
+          their nearest ancestor *sectioning root* [#]_ or their nearest
+          ancestor element of *sectioning content*  [#]_, whichever is nearest,
+          [...]
 
-      .. [#] <blockquote>, <body>, <details>, <dialog>, <fieldset>,
-             <figure>, <td>
-      .. [#] <article>, <aside>, <nav>, <section>
+          .. [#] <blockquote>, <body>, <details>, <dialog>, <fieldset>,
+                 <figure>, <td>
+          .. [#] <article>, <aside>, <nav>, <section>
 
-      I.e., a top-level <section> is a subsection of <body>.
-
-   __ https://www.w3.org/TR/html53/sections.html#headings-and-sections
+          I.e., a top-level <section> is a subsection of <body>.
+
+       __ https://www.w3.org/TR/html53/sections.html#headings-and-sections
 
 
 
@@ -1190,25 +1228,28 @@ The Sphinx_ documentation generator includes an autodoc module.
 
 Version 2.0 of Ed Loper's `Epydoc <http://epydoc.sourceforge.net/>`_
 supports reStructuredText-format docstrings for HTML output.  Docutils
-0.3 or newer is required.  Development of a Docutils-specific
-auto-documentation tool will continue.  Epydoc works by importing
-Python modules to be documented, whereas the Docutils-specific tool,
-described above, will parse modules without importing them (as with
-`HappyDoc <http://happydoc.sourceforge.net/>`_, which doesn't support
-reStructuredText).
-
-The advantages of parsing over importing are security and flexibility;
-the disadvantage is complexity/difficulty.
-
-* Security: untrusted code that shouldn't be executed can be parsed;
-  importing a module executes its top-level code.
-* Flexibility: comments and unofficial docstrings (those not supported
-  by Python syntax) can only be processed by parsing.
-* Complexity/difficulty: it's a lot harder to parse and analyze a
-  module than it is to ``import`` and analyze one.
-
-For more details, please see "Docstring Extraction Rules"
-in :PEP:`258`, item 3 ("How").
+0.3 or newer is required.
+
+Development of a Docutils-specific auto-documentation tool is suspended.
+
+.. Epydoc works by importing
+   Python modules to be documented, whereas the Docutils-specific tool,
+   described above, will parse modules without importing them (as with
+   `HappyDoc <http://happydoc.sourceforge.net/>`_, which doesn't support
+   reStructuredText).
+
+   The advantages of parsing over importing are security and flexibility;
+   the disadvantage is complexity/difficulty.
+
+   * Security: untrusted code that shouldn't be executed can be parsed;
+     importing a module executes its top-level code.
+   * Flexibility: comments and unofficial docstrings (those not supported
+     by Python syntax) can only be processed by parsing.
+   * Complexity/difficulty: it's a lot harder to parse and analyze a
+     module than it is to ``import`` and analyze one.
+
+   For more details, please see "Docstring Extraction Rules"
+   in :PEP:`258`, item 3 ("How").
 
 
 Miscellaneous
diff --git a/docutils/docs/user/todo-lists.txt b/docutils/docs/user/todo-lists.txt
new file mode 100644
index 000000000..5320e2e78
--- /dev/null
+++ b/docutils/docs/user/todo-lists.txt
@@ -0,0 +1,154 @@
+.. include:: ../header.txt
+
+===================
+Docutils TODO lists
+===================
+
+TODO lists allow you to create a list of items with checkboxes.
+In `extended Markdown`_, they are called `task lists`.
+
+Checkbox variants
+=================
+
+[x] ASCII-art checkbox.
+
+[ ] ASCII space character and NBSP are smaller than the x.
+
+[ ] The "figure space" has the correct width but is not easy to type.
+
+You may define substitutions for ballot box and checked ballot box or
+other suitable Unicode characters:
+
+.. |-| unicode:: U+2610
+.. |x| unicode:: U+2611
+.. |y| unicode:: U+1F5F9
+
+|-| U+2610 BALLOT BOX
+
+|x| U+2611 BALLOT BOX WITH CHECK
+
+|y| U+1F5F9 BALLOT BOX WITH BOLD CHECK
+
+List Markup
+===========
+
+Paragraphs
+----------
+
+|x| Simple *paragraphs* are easy for small lists with short values
+
+|-| but not well suited for complex TODO items.
+
+Line Blocks
+-----------
+
+| |x| Line blocks are rendered as "unstyled" lists.
+| |y| They don't need additional styling.
+| |-| However, you cannot nest block elements.
+
+
+Description Lists
+-----------------
+
+.. class:: description
+
+|x|
+    A *description list* works out of the box in HTML5 and XeTeX.
+
+|-|
+    It looks suboptimal in the rST source (definition list with class
+    value "description").
+
+[x]
+    Lists may use ASCII-art or substitutions.
+
+[ ]
+    All list markup variants require special styling based on a
+    preceding class__ directive.
+
+__ https://docutils.sourceforge.io/docs/ref/rst/directives.html#class
+
+Bullet Lists
+------------
+
+.. class:: todo
+
+- |x| bullet lists (similar to the Markdown_ for `task
+  lists`) can be styled accordingly.
+- |-| They don't look good in the rST source.
+- [x] Lists may use ASCII-art or substitutions.
+- [ ] The "figure space" has the correct width.
+
+- |x| Another idea: use bullet lists with ``+`` and ``-`` markers.
+
+      + Clean and simple markup in the source.
+
+      - A new marker character starts a new list :-(
+
+      - Requires change to the writer: Pass the "bullet" attribute to
+        the output document (use `HTML5 "data-" attriibutes`__?).
+
+__ https://html.spec.whatwg.org/#embedding-custom-non-visible-data-with-the-data-*-attributes
+
+Field Lists
+-----------
+
+.. class:: todo
+
+:|x|: Compile this example with ``rst2html5.py``,
+:|y|: compare markup variants,
+:|-|: select the best.
+
+.. class:: todo monospace
+
+:[x]: ASCII-art checkbox.
+:[ ]: The "figure space" has the correct width.
+:[ ]: CSS styling can switch to monospace fonts for the ASCII-art boxes,
+      so an ASCII space character can be used.
+
+.. class:: todo monospace brackets
+
+:x: ASCII-art checkbox - brackets added by CSS.
+: : Simple rST source, easy typing.
+
+.. class:: todo monospace framed
+
+:x: checkbox border added by CSS.
+: : Simple rST source, easy typing.
+
+I recommend a field list with class argument and some CSS styling.
+
+
+.. _Markdown: https://www.markdownguide.org
+.. _extended Markdown: https://www.markdownguide.org/extended-syntax/
+
+
+.. ! The follwing CSS rules are included here as raw HTML to keep the
+     example compact. They compromise the HTML validity, as styling is not
+     allowed in the document body.
+     For production use, place CSS styling rules in a custom style sheet.
+
+.. raw:: html
+
+   <style type="text/css"><!--
+    ul.todo {list-style-type: none;
+             padding-left: 0;}
+    ul.todo > li > p {padding-left: 1.2em;
+                      text-indent: -1.2em;}
+
+    dl.todo > dt > .colon {display: none}
+    dl.todo > dd {margin-left: 2.5em;}
+
+    dl.monospace > dt {font-family: monospace;}
+
+    dl.brackets > dt:before {content: '[';}
+    dl.brackets > dt:after {content: ']';}
+
+    dl.framed > dt {border: solid;
+                    border-width: thin;
+                    padding: 0 0.2em;
+                    margin-top: 0.2em;
+                    line-height: 0.9;
+                   }
+
+    --></style>