Reformat config.txt (options as sub-sections).

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

1 files changed, 1067 insertions, 840 deletions

diff --git a/docs/user/config.txt b/docs/user/config.txt
index 73d395eb1..a08942a60 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -92,6 +92,8 @@ recognized:
 :On: "true", "yes", "on", "1"
 :Off: "false", "no", "off", "0", "" (no value)
 
+.. _list:
+
 List values can be comma- or colon-delimited.
 
 strip_classes_, strip_elements_with_classes_, stylesheet, and
@@ -192,495 +194,581 @@ Some knowledge of Python_ is assumed for some attributes.
 
 Settings in the "[general]" section are always applied.
 
-_`auto_id_prefix`
-    Prefix prepended to all auto-generated IDs generated within the
-    document, after id_prefix_.
+auto_id_prefix
+--------------
 
-    Default: "id".  Options: ``--auto-id-prefix`` (hidden, intended
-    mainly for programmatic use).
+Prefix prepended to all auto-generated IDs generated within the
+document, after id_prefix_.
 
-_`datestamp`
-    Include a time/datestamp in the document footer.  Contains a
-    format string for Python's ``time.strftime``.  See the `time
-    module documentation`__.
+Default: "id".
+Options: ``--auto-id-prefix`` (hidden, intended mainly for programmatic use).
 
-    Default: None.  Options: ``--date, -d, --time, -t,
-    --no-datestamp``.
+datestamp
+---------
 
-    Configuration file entry examples::
+Include a time/datestamp in the document footer.  Contains a
+format string for Python's ``time.strftime``.  See the `time
+module documentation`__.
 
-        # Equivalent to --date command-line option, results in
-        # ISO 8601 extended format datestamp, e.g. "2001-12-21":
-        datestamp: %Y-%m-%d
+Default: None.
+Options: ``--date, -d, --time, -t, --no-datestamp``.
 
-        # Equivalent to --time command-line option, results in
-        # date/timestamp like "2001-12-21 18:43 UTC":
-        datestamp: %Y-%m-%d %H:%M UTC
+Configuration file entry examples::
 
-        # Disables datestamp; equivalent to --no-datestamp:
-        datestamp:
+    # Equivalent to --date command-line option, results in
+    # ISO 8601 extended format datestamp, e.g. "2001-12-21":
+    datestamp: %Y-%m-%d
 
-    __ http://www.python.org/doc/current/lib/module-time.html
+    # Equivalent to --time command-line option, results in
+    # date/timestamp like "2001-12-21 18:43 UTC":
+    datestamp: %Y-%m-%d %H:%M UTC
 
-_`debug`
-    Report debug-level system messages.
+    # Disables datestamp; equivalent to --no-datestamp:
+    datestamp:
 
-    Default: don't (None).  Options: ``--debug, --no-debug``.
+__ http://www.python.org/doc/current/lib/module-time.html
 
-_`dump_internals`
-    At the end of processing, write all internal attributes of the
-    document (``document.__dict__``) to stderr.
+debug
+-----
 
-    Default: don't (None).  Options: ``--dump-internals`` (hidden, for
-    development use only).
+Report debug-level system messages.
 
-_`dump_pseudo_xml`
-    At the end of processing, write the pseudo-XML representation of
-    the document to stderr.
+Default: don't (None).  Options: ``--debug, --no-debug``.
 
-    Default: don't (None).  Options: ``--dump-pseudo-xml`` (hidden,
-    for development use only).
+dump_internals
+--------------
 
-_`dump_settings`
-    At the end of processing, write all Docutils settings to stderr.
+At the end of processing, write all internal attributes of the
+document (``document.__dict__``) to stderr.
 
-    Default: don't (None).  Options: ``--dump-settings`` (hidden, for
-    development use only).
+Default: don't (None).
+Options: ``--dump-internals`` (hidden, for development use only).
 
-_`dump_transforms`
-    At the end of processing, write a list of all transforms applied
-    to the document to stderr.
+dump_pseudo_xml
+---------------
 
-    Default: don't (None).  Options: ``--dump-transforms`` (hidden,
-    for development use only).
+At the end of processing, write the pseudo-XML representation of
+the document to stderr.
 
-_`error_encoding`
-    The text encoding for error output.
+Default: don't (None).
+Options: ``--dump-pseudo-xml`` (hidden, for development use only).
 
-    Default: "ascii".  Options: ``--error-encoding, -e``.
+dump_settings
+-------------
 
-_`error_encoding_error_handler`
-    The error handler for unencodable characters in error output.  See
-    output_encoding_error_handler_ for acceptable values.
+At the end of processing, write all Docutils settings to stderr.
 
-    Default: "backslashreplace"
-    Options: ``--error-encoding-error-handler,
-    --error-encoding, -e``.
+Default: don't (None).
+Options: ``--dump-settings`` (hidden, for development use only).
 
-_`exit_status_level`
-    A system message level threshold; non-halting system messages at
-    or above this level will produce a non-zero exit status at normal
-    exit.  Exit status is the maximum system message level plus 10 (11
-    for INFO, etc.).
+dump_transforms
+---------------
 
-    Default: disabled (5).  Options: ``--exit-status``.
+At the end of processing, write a list of all transforms applied
+to the document to stderr.
 
-_`expose_internals`
-    List of internal attribues to expose as external attributes (with
-    "internal:" namespace prefix).  To specify multiple attributes in
-    configuration files, use colons to separate names; on the command
-    line, the option may be used more than once.
+Default: don't (None).
+Options: ``--dump-transforms`` (hidden, for development use only).
 
-    Default: don't (None).  Options: ``--expose-internal-attribute``
-    (hidden, for development use only).
+error_encoding
+--------------
 
-_`footnote_backlinks`
-    Enable or disable backlinks from footnotes and citations to their
-    references.
+The text encoding for error output.
 
-    Default: enabled (1).  Options: ``--footnote-backlinks,
-    --no-footnote-backlinks``.
+Default: "ascii".  Options: ``--error-encoding, -e``.
 
-_`generator`
-    Include a "Generated by Docutils" credit and link in the document
-    footer.
+error_encoding_error_handler
+----------------------------
 
-    Default: off (None).  Options: ``--generator, -g,
-    --no-generator``.
+The error handler for unencodable characters in error output.  See
+output_encoding_error_handler_ for acceptable values.
 
-_`halt_level`
-    The threshold at or above which system messages are converted to
-    exceptions, halting execution immediately.  If `traceback`_ is
-    set, the exception will propagate; otherwise, Docutils will exit.
+Default: "backslashreplace"
+Options: ``--error-encoding-error-handler, --error-encoding, -e``.
 
-    Default: severe (4).  Options: ``--halt, --strict``.
+exit_status_level
+-----------------
 
-_`id_prefix`
-    Prefix prepended to all IDs generated within the document.  See
-    also auto_id_prefix_.
+A system message level threshold; non-halting system messages at
+or above this level will produce a non-zero exit status at normal
+exit.  Exit status is the maximum system message level plus 10 (11
+for INFO, etc.).
 
-    Default: "" (empty).  Options: ``--id-prefix`` (hidden, intended
-    mainly for programmatic use).
+Default: disabled (5).  Options: ``--exit-status``.
 
-_`input_encoding`
-    The text encoding for input.
+expose_internals
+----------------
 
-    Default: auto-detect (None).  Options: ``--input-encoding, -i``.
+List_ of internal attribues to expose as external attributes (with
+"internal:" namespace prefix).  To specify multiple attributes in
+configuration files, use colons to separate names; on the command
+line, the option may be used more than once.
 
-_`input_encoding_error_handler`
-    The error handler for undecodable characters in the input.
-    Acceptable values include:
+Default: don't (None).
+Options: ``--expose-internal-attribute`` (hidden, for development use only).
 
-    strict
-        Raise an exception in case of an encoding error.
-    replace
-        Replace malformed data with the official Unicode replacement
-        character, U+FFFD.
-    ignore
-        Ignore malformed data and continue without further notice.
+footnote_backlinks
+------------------
 
-    Acceptable values are the same as for the "error" parameter of
-    Python's ``unicode`` function; other values may be defined in
-    applications or in future versions of Python.
+Enable or disable backlinks from footnotes and citations to their
+references.
 
-    Default: "strict".  Options: ``--input-encoding-error-handler,
-    --input-encoding, -i``.
+Default: enabled (1).
+Options: ``--footnote-backlinks, --no-footnote-backlinks``.
 
-_`language_code`
-    Case-insensitive `language tag`_ as defined in `BCP 47`_.
+generator
+---------
 
-    Sets the document language, also used for localized directive and
-    role names as well as Docutils-generated text.
+Include a "Generated by Docutils" credit and link in the document footer.
 
-    A typical language identifier consists of a 2-letter language code
-    from `ISO 639`_ (3-letter codes can be used if no 2-letter code
-    exists). The language identifier can have an optional subtag,
-    typically for variations based on country (from `ISO 3166`_
-    2-letter country codes).  Avoid subtags except where they add
-    useful distinguishing information. Examples of language tags
-    include "fr", "en-GB", "pt_br" (the same as "pt-BR"), and
-    "de-1901" (German with pre-1998 spelling).
+Default: off (None).  Options: ``--generator, -g, --no-generator``.
 
-    The language of document parts can be specified with a
-    "language-<language tag>" `class attribute`_, e.g.
-    ``.. class:: language-el-polyton`` for a quote in polytonic Greek.
+halt_level
+----------
 
-    Default: English ("en").  Options: ``--language, -l``.
+The threshold at or above which system messages are converted to
+exceptions, halting execution immediately.  If `traceback`_ is set, the
+exception will propagate; otherwise, Docutils will exit.
 
-    .. _class attribute: ../ref/doctree.html#classes
+Default: severe (4).  Options: ``--halt, --strict``.
 
-_`output_encoding`
-    The text encoding for output.
+id_prefix
+---------
 
-    Default: "UTF-8".  Options: ``--output-encoding, -o``.
+Prefix prepended to all IDs generated within the document.  See also
+auto_id_prefix_.
 
-_`output_encoding_error_handler`
-    The error handler for unencodable characters in the output.
-    Acceptable values include:
+Default: "" (empty).
+Options: ``--id-prefix`` (hidden, intended mainly for programmatic use).
 
-    strict
-        Raise an exception in case of an encoding error.
-    replace
-        Replace malformed data with a suitable replacement marker,
-        such as "?".
-    ignore
-        Ignore malformed data and continue without further notice.
-    xmlcharrefreplace
-        Replace with the appropriate XML character reference, such as
-        "``&#8224;``".
-    backslashreplace
-        Replace with backslashed escape sequences, such as "``\u2020``".
+input_encoding
+--------------
 
-    Acceptable values are the same as for the "error" parameter of
-    Python's ``encode`` string method; other values may be defined in
-    applications or in future versions of Python.
+The text encoding for input.
 
-    Default: "strict".  Options: ``--output-encoding-error-handler,
-    --output-encoding, -o``.
+Default: auto-detect (None).  Options: ``--input-encoding, -i``.
 
-_`record_dependencies`
-    Path to a file where Docutils will write a list of files that were
-    required to generate the output, e.g. included files or embedded
-    stylesheets [#dependencies]_. [#pwd]_ The format is one path per
-    line with forward slashes as separator, the encoding is ``utf8``.
+input_encoding_error_handler
+----------------------------
 
-    Set to ``-`` in order to write dependencies to stdout.
+The error handler for undecodable characters in the input. Acceptable
+values include:
 
-    This option is particularly useful in conjunction with programs like
-    ``make`` using ``Makefile`` rules like::
+strict
+    Raise an exception in case of an encoding error.
+replace
+    Replace malformed data with the official Unicode replacement
+    character, U+FFFD.
+ignore
+    Ignore malformed data and continue without further notice.
 
-      ham.html: ham.txt $(shell cat hamdeps.txt)
-        rst2html.py --record-dependencies=hamdeps.txt ham.txt ham.html
+Acceptable values are the same as for the "error" parameter of
+Python's ``unicode`` function; other values may be defined in
+applications or in future versions of Python.
 
-    If the filesystem encoding differs from utf8, replace the ``cat``
-    command with a call to a converter, e.g.::
+Default: "strict".
+Options: ``--input-encoding-error-handler, --input-encoding, -i``.
 
-      $(shell iconv -f utf8 -t latin1 hamdeps.txt)
+language_code
+-------------
 
-    Default: None.  Option: ``--record-dependencies``.
+Case-insensitive `language tag`_ as defined in `BCP 47`_.
 
-_`report_level`
-    Report system messages at or higher than <level>:
+Sets the document language, also used for localized directive and
+role names as well as Docutils-generated text.
 
-    1  info
-    2  warning
-    3  error
-    4  severe
-    5  none
+A typical language identifier consists of a 2-letter language code
+from `ISO 639`_ (3-letter codes can be used if no 2-letter code
+exists). The language identifier can have an optional subtag,
+typically for variations based on country (from `ISO 3166`_
+2-letter country codes).  Avoid subtags except where they add
+useful distinguishing information. Examples of language tags
+include "fr", "en-GB", "pt_br" (the same as "pt-BR"), and
+"de-1901" (German with pre-1998 spelling).
 
-    Default: warning (2).  Options: ``--report, -r, --verbose, -v,
-    --quiet, -q``.
+The language of document parts can be specified with a
+"language-<language tag>" `class attribute`_, e.g.
+``.. class:: language-el-polyton`` for a quote in polytonic Greek.
 
-_`sectnum_xform`
-    Enable or disable automatic section numbering by Docutils
-    (docutils.transforms.parts.SectNum) associated with the `sectnum
-    directive`_.
+Default: English ("en").  Options: ``--language, -l``.
 
-    If disabled, section numbers might be added to the output by the
-    renderer (e.g. LaTeX or via a CSS style definition).
+.. _class attribute: ../ref/doctree.html#classes
 
-    Default: enabled (1).  Options: ``--section-numbering``,
-    ``--no-section-numbering``.
+output_encoding
+---------------
 
-    .. _sectnum directive: ../ref/rst/directives.html#sectnum
+The text encoding for output.
 
-_`source_link`
-    Include a "View document source" link in the document footer.  URL
-    will be relative to the destination.
+Default: "UTF-8".  Options: ``--output-encoding, -o``.
 
-    Default: don't (None).  Options: ``--source-link, -s,
-    --no-source-link``.
+output_encoding_error_handler
+-----------------------------
 
-_`source_url`
-    An explicit URL for a "View document source" link, used verbatim.
+The error handler for unencodable characters in the output. Acceptable
+values include:
 
-    Default: compute if source_link (None).  Options: ``--source-url,
-    --no-source-link``.
+strict
+    Raise an exception in case of an encoding error.
+replace
+    Replace malformed data with a suitable replacement marker,
+    such as "?".
+ignore
+    Ignore malformed data and continue without further notice.
+xmlcharrefreplace
+    Replace with the appropriate XML character reference, such as
+    "``&#8224;``".
+backslashreplace
+    Replace with backslashed escape sequences, such as "``\u2020``".
 
-_`strict_visitor`
-    When processing a document tree with the Visitor pattern, raise an
-    error if a writer does not support a node type listed as optional.
-    For transitional development use.
+Acceptable values are the same as for the "error" parameter of
+Python's ``encode`` string method; other values may be defined in
+applications or in future versions of Python.
 
-    Default: disabled (None).  Option: ``--strict-visitor`` (hidden,
-    for development use only).
+Default: "strict".
+Options: ``--output-encoding-error-handler, --output-encoding, -o``.
 
-_`strip_classes`
-    Comma-separated list of "classes" attribute values to remove from
-    all elements in the document tree.
-    The command line option may be used more than once.
+record_dependencies
+-------------------
 
-    .. WARNING:: Potentially dangerous; use with caution.
+Path to a file where Docutils will write a list of files that were
+required to generate the output, e.g. included files or embedded
+stylesheets [#dependencies]_. [#pwd]_ The format is one path per
+line with forward slashes as separator, the encoding is ``utf8``.
 
-    Default: disabled (None).  Option: ``--strip-class``.
+Set to ``-`` in order to write dependencies to stdout.
 
-_`strip_comments`
-    Enable the removal of comment elements from the document tree.
+This option is particularly useful in conjunction with programs like
+``make`` using ``Makefile`` rules like::
 
-    Default: disabled (None).  Options: ``--strip-comments``,
-    ``--leave-comments``.
+  ham.html: ham.txt $(shell cat hamdeps.txt)
+    rst2html.py --record-dependencies=hamdeps.txt ham.txt ham.html
 
-_`strip_elements_with_classes`
-    Comma-separated list of "classes" attribute values;
-    matching elements are removed from the document tree.
-    The command line option may be used more than once.
+If the filesystem encoding differs from utf8, replace the ``cat``
+command with a call to a converter, e.g.::
 
-    .. WARNING:: Potentially dangerous; use with caution.
+  $(shell iconv -f utf8 -t latin1 hamdeps.txt)
 
-    Default: disabled (None).  Option: ``--strip-element-with-class``.
+Default: None.  Option: ``--record-dependencies``.
 
-_`title`
-    The document title as metadata, which does not become part of the
-    document body.  It overrides a document-supplied title.  For
-    example, in HTML output the metadata document title appears in the
-    title bar of the browser window.
+report_level
+------------
 
-    Default: none.  Option: ``--title``.
+Report system messages at or higher than <level>:
 
-_`toc_backlinks`
-    Enable backlinks from section titles to table of contents entries
-    ("entry"), to the top of the TOC ("top"), or disable ("none").
+1  info
+2  warning
+3  error
+4  severe
+5  none
 
-    Default: "entry".  Options: ``--toc-entry-backlinks,
-    --toc-top-backlinks, --no-toc-backlinks``.
+Default: warning (2).
+Options: ``--report, -r, --verbose, -v, --quiet, -q``.
 
-_`traceback`
-    Enable Python tracebacks when halt-level system messages and other
-    exceptions occur.  Useful for debugging, and essential for issue
-    reports.  Exceptions are allowed to propagate, instead of being
-    caught and reported (in a user-friendly way) by Docutils.
+sectnum_xform
+-------------
 
-    Default: disabled (None) unless Docutils is run programmatically
-    using the `Publisher Interface`_.  Options: ``--traceback,
-    --no-traceback``.
+Enable or disable automatic section numbering by Docutils
+(docutils.transforms.parts.SectNum) associated with the `sectnum
+directive`_.
 
-    .. _Publisher Interface: ../api/publisher.html
+If disabled, section numbers might be added to the output by the
+renderer (e.g. LaTeX or via a CSS style definition).
 
-_`warning_stream`
-    Path to a file for the output of system messages (warnings)
-    [#pwd]_.
+Default: enabled (1).
+Options: ``--section-numbering``, ``--no-section-numbering``.
 
-    Default: stderr (None).  Options: ``--warnings``.
+.. _sectnum directive: ../ref/rst/directives.html#sectnum
 
+source_link
+-----------
 
-[parsers]
+Include a "View document source" link in the document footer.  URL will
+be relative to the destination.
+
+Default: don't (None).
+Options: ``--source-link, -s, --no-source-link``.
+
+source_url
+----------
+
+An explicit URL for a "View document source" link, used verbatim.
+
+Default: compute if source_link (None).
+Options: ``--source-url, --no-source-link``.
+
+strict_visitor
+--------------
+
+When processing a document tree with the Visitor pattern, raise an
+error if a writer does not support a node type listed as optional. For
+transitional development use.
+
+Default: disabled (None).
+Option: ``--strict-visitor`` (hidden, for development use only).
+
+strip_classes
+-------------
+
+Comma-separated list_ of "classes" attribute values to remove from all
+elements in the document tree. The command line option may be used more
+than once.
+
+.. WARNING:: Potentially dangerous; use with caution.
+
+Default: disabled (None).  Option: ``--strip-class``.
+
+strip_comments
+--------------
+
+Enable the removal of comment elements from the document tree.
+
+Default: disabled (None).
+Options: ``--strip-comments``, ``--leave-comments``.
+
+strip_elements_with_classes
+---------------------------
+
+Comma-separated list_ of "classes" attribute values;
+matching elements are removed from the document tree.
+The command line option may be used more than once.
+
+.. WARNING:: Potentially dangerous; use with caution.
+
+Default: disabled (None).  Option: ``--strip-element-with-class``.
+
+title
+-----
+
+The document title as metadata, which does not become part of the
+document body.  It overrides a document-supplied title.  For
+example, in HTML output the metadata document title appears in the
+title bar of the browser window.
+
+Default: none.  Option: ``--title``.
+
+toc_backlinks
+-------------
+
+Enable backlinks from section titles to table of contents entries
+("entry"), to the top of the TOC ("top"), or disable ("none").
+
+Default: "entry".
+Options: ``--toc-entry-backlinks, --toc-top-backlinks, --no-toc-backlinks``.
+
+traceback
 ---------
 
+Enable Python tracebacks when halt-level system messages and other
+exceptions occur.  Useful for debugging, and essential for issue
+reports.  Exceptions are allowed to propagate, instead of being
+caught and reported (in a user-friendly way) by Docutils.
+
+Default: disabled (None) unless Docutils is run programmatically
+using the `Publisher Interface`_.
+Options: ``--traceback, --no-traceback``.
+
+.. _Publisher Interface: ../api/publisher.html
+
+warning_stream
+--------------
+
+Path to a file for the output of system messages (warnings) [#pwd]_.
+
+Default: stderr (None).  Options: ``--warnings``.
+
+
+[parsers]
+=========
+
 Docutils currently supports only one parser, for reStructuredText.
 
 
 [restructuredtext parser]
-`````````````````````````
+-------------------------
 
-_`file_insertion_enabled`
-    Enable or disable directives that insert the contents of external
-    files, such as the "include_" & "raw_".  A "warning" system
-    message (including the directive text) is inserted instead.  (See
-    also raw_enabled_ for another security-relevant setting.)
+file_insertion_enabled
+~~~~~~~~~~~~~~~~~~~~~~
 
-    Default: enabled (1).  Options: ``--file-insertion-enabled,
-    --no-file-insertion``.
+Enable or disable directives that insert the contents of external
+files, such as the "include_" & "raw_".  A "warning" system
+message (including the directive text) is inserted instead.  (See
+also raw_enabled_ for another security-relevant setting.)
 
-    .. _include: ../ref/rst/directives.html#include
-    .. _raw: ../ref/rst/directives.html#raw
+Default: enabled (1).
+Options: ``--file-insertion-enabled, --no-file-insertion``.
 
-_`pep_references`
-    Recognize and link to standalone PEP references (like "PEP 258").
+.. _include: ../ref/rst/directives.html#include
+.. _raw: ../ref/rst/directives.html#raw
 
-    Default: disabled (None); enabled (1) in PEP Reader.  Options:
-    ``--pep-references``.
+pep_references
+~~~~~~~~~~~~~~
 
-_`pep_base_url`
-    Base URL for PEP references.
+Recognize and link to standalone PEP references (like "PEP 258").
 
-    Default: "http://www.python.org/peps/".  Option:
-    ``--pep-base-url``.
+Default: disabled (None); enabled (1) in PEP Reader.
+Options: ``--pep-references``.
 
-_`pep_file_url_template`
-    Template for PEP file part of URL, interpolated with the PEP
-    number and appended to pep_base_url_.
+pep_base_url
+~~~~~~~~~~~~
+Base URL for PEP references.
 
-    Default: "pep-%04d".  Option: ``--pep-file-url``.
+Default: "http://www.python.org/peps/".
+Option: ``--pep-base-url``.
 
-_`raw_enabled`
-    Enable or disable the "raw_" directive.  A "warning" system
-    message (including the directive text) is inserted instead.  (See
-    also file_insertion_enabled_ for another security-relevant
-    setting.)
+pep_file_url_template
+~~~~~~~~~~~~~~~~~~~~~
 
-    Default: enabled (1).  Options: ``--raw-enabled, --no-raw``.
+Template for PEP file part of URL, interpolated with the PEP
+number and appended to pep_base_url_.
 
-_`rfc_references`
-    Recognize and link to standalone RFC references (like "RFC 822").
+Default: "pep-%04d".  Option: ``--pep-file-url``.
 
-    Default: disabled (None); enabled (1) in PEP Reader.  Options:
-    ``--rfc-references``.
+raw_enabled
+~~~~~~~~~~~
 
-_`rfc_base_url`
-    Base URL for RFC references.
+Enable or disable the "raw_" directive.  A "warning" system message
+(including the directive text) is inserted instead.  (See also
+file_insertion_enabled_ for another security-relevant setting.)
 
-    Default: "http://www.faqs.org/rfcs/".  Option: ``--rfc-base-url``.
+Default: enabled (1).  Options: ``--raw-enabled, --no-raw``.
 
-_`tab_width`
-    Number of spaces for hard tab expansion.
+rfc_references
+~~~~~~~~~~~~~~
 
-    Default: 8.  Options: ``--tab-width``.
+Recognize and link to standalone RFC references (like "RFC 822").
 
-_`trim_footnote_reference_space`
-    Remove spaces before footnote references.
+Default: disabled (None); enabled (1) in PEP Reader.
+Options: ``--rfc-references``.
 
-    Default: don't (None); may be overriden by a writer-specific
-    footnote_references__ default though.  Options:
-    ``--trim-footnote-reference-space,
-    --leave-footnote-reference-space``.
+rfc_base_url
+~~~~~~~~~~~~
 
-__ `footnote_references [latex2e writer]`_
+Base URL for RFC references.
 
+Default: "http://www.faqs.org/rfcs/".  Option: ``--rfc-base-url``.
 
-_`syntax_highlight`
-    Token type names used by Pygments_ when parsing contents of the code_
-    directive and role.
+smart_quotes
+~~~~~~~~~~~~
 
-    Supported values:
+Change straight quotation marks to typographic form. `Quote characters`_
+are selected according to the language of the current block element (see
+language_code_). Also changes consequtive runs of hyphen-minus and full
+stops (``---``, ``--``, ``...``) to em-dash, en-dash and ellipsis Unicode
+characters respectively.
 
-    long
-      Use hierarchy of long token type names.
-    short
-      Use short token type names. (For use with
-      `Pygments-generated stylesheets`_.)
-    none
-      No code parsing. Use this to avoid the "Pygments not
-      found" warning when Pygments is not installed.
+Supported values:
 
-    Default: "long".  Option: ``--syntax-highlight``.
+booleans_ (yes/no)
+  Use smart quotes?
+
+alt (or "alternative")
+  Use alternative quote set (if defined for the language).
+
+Default: "no". Option: ``--smart-quotes``.
+
+New in Docutils 0.10.
+
+.. _quote characters:
+   http://en.wikipedia.org/wiki/Non-English_usage_of_quotation_marks
 
-    New in Docutils 0.9.
+syntax_highlight
+~~~~~~~~~~~~~~~~
+
+Token type names used by Pygments_ when parsing contents of the code_
+directive and role.
+
+Supported values:
+
+long
+  Use hierarchy of long token type names.
+short
+  Use short token type names. (For use with
+  `Pygments-generated stylesheets`_.)
+none
+  No code parsing. Use this to avoid the "Pygments not
+  found" warning when Pygments is not installed.
+
+Default: "long".  Option: ``--syntax-highlight``.
+
+New in Docutils 0.9.
 
 .. _Pygments: http://pygments.org/
 .. _code: ../ref/rst/directives.html#code
 .. _Pygments-generated stylesheets:
    http://pygments.org/docs/cmdline/#generating-styles
 
-_`smart_quotes`
-    Change straight quotation marks to typographic form. `Quote characters`_
-    are selected according to the language of the current block element (see
-    language_code_). Also changes consequtive runs of hyphen-minus and full
-    stops (``---``, ``--``, ``...``) to em-dash, en-dash and ellipsis
-    Unicode characters respectively.
+tab_width
+~~~~~~~~~
 
-    Supported values:
+Number of spaces for hard tab expansion.
 
-    booleans_ (yes/no)
-      Use smart quotes?
+Default: 8.  Options: ``--tab-width``.
 
-    alt (or "alternative")
-      Use alternative quote set (if defined for the language).
+trim_footnote_reference_space
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    Default: "no". Option: ``--smart-quotes``.
+Remove spaces before footnote references.
 
-    New in Docutils 0.10.
+Default: don't (None); may be overriden by a writer-specific
+footnote_references__ default though.
 
-.. _quote characters:
-   http://en.wikipedia.org/wiki/Non-English_usage_of_quotation_marks
+Options: ``--trim-footnote-reference-space, --leave-footnote-reference-space``.
+
+__ `footnote_references [latex2e writer]`_
 
 
 [readers]
----------
+=========
 
 
 [standalone reader]
-```````````````````
+-------------------
+
+docinfo_xform
+~~~~~~~~~~~~~
+
+Enable or disable the bibliographic field list transform
+(docutils.transforms.frontmatter.DocInfo).
 
-_`docinfo_xform`
-    Enable or disable the bibliographic field list transform
-    (docutils.transforms.frontmatter.DocInfo).
+Default: enabled (1).  Options: ``--no-doc-info``.
 
-    Default: enabled (1).  Options: ``--no-doc-info``.
+doctitle_xform
+~~~~~~~~~~~~~~
 
-_`doctitle_xform`
-    Enable or disable the promotion of a lone top-level section title
-    to document title (and subsequent section title to document
-    subtitle promotion; docutils.transforms.frontmatter.DocTitle).
+Enable or disable the promotion of a lone top-level section title
+to document title (and subsequent section title to document
+subtitle promotion; docutils.transforms.frontmatter.DocTitle).
 
-    Default: enabled (1).  Options: ``--no-doc-title``.
+Default: enabled (1).  Options: ``--no-doc-title``.
 
-_`sectsubtitle_xform`
+sectsubtitle_xform
+~~~~~~~~~~~~~~~~~~
 
-    Enable or disable the promotion of the title of a lone subsection
-    to a subtitle (docutils.transforms.frontmatter.SectSubTitle).
+Enable or disable the promotion of the title of a lone subsection
+to a subtitle (docutils.transforms.frontmatter.SectSubTitle).
 
-    Default: disabled (0).  Options: ``--section-subtitles,
-    --no-section-subtitles``.
+Default: disabled (0).  Options: ``--section-subtitles,
+--no-section-subtitles``.
 
 
 [pep reader]
-````````````
+------------
 
 The `pep_references`_ and `rfc_references`_ settings
 (`[restructuredtext parser]`_) are set on by default.
 
 
 [python reader]
-```````````````
+---------------
 
-Under construction.
+Not implemented.
 
 
 [writers]
----------
+=========
 
 [docutils_xml writer]
-`````````````````````
+---------------------
 
 .. Caution::
 
@@ -691,301 +779,321 @@ Under construction.
    * The XML declaration carries text encoding information, without which
      standard tools may be unable to read the generated XML.
 
-_`doctype_declaration`
-    Generate XML with a DOCTYPE declaration.
+doctype_declaration
+~~~~~~~~~~~~~~~~~~~
+
+Generate XML with a DOCTYPE declaration.
 
-    Default: do (1).  Options: ``--no-doctype``.
+Default: do (1).  Options: ``--no-doctype``.
 
-_`indents`
-    Generate XML with indents and newlines.
+indents
+~~~~~~~
 
-    Default: don't (None).  Options: ``--indents``.
+Generate XML with indents and newlines.
 
-_`newlines`
-    Generate XML with newlines before and after tags.
+Default: don't (None).  Options: ``--indents``.
 
-    Default: don't (None).  Options: ``--newlines``.
+newlines
+~~~~~~~~
+
+Generate XML with newlines before and after tags.
+
+Default: don't (None).  Options: ``--newlines``.
 
 .. _xml_declaration [docutils_xml writer]:
 
 xml_declaration
-    Generate XML with an XML declaration.  Also defined for the
-    `HTML Writer`__.
+~~~~~~~~~~~~~~~
+
+Generate XML with an XML declaration.  Also defined for the
+`HTML Writer`__.
 
-    Default: do (1).  Options: ``--no-xml-declaration``.
+Default: do (1).  Options: ``--no-xml-declaration``.
 
-    __ `xml_declaration [html4css1 writer]`_
+__ `xml_declaration [html4css1 writer]`_
 
 
 [html4css1 writer]
-``````````````````
+------------------
 
 .. _attribution [html4css1 writer]:
 
 attribution
-    Format for block quote attributions: one of "dash" (em-dash
-    prefix), "parentheses"/"parens", or "none".  Also defined for the
-    `LaTeX Writer`__.
+~~~~~~~~~~~
+
+Format for block quote attributions: one of "dash" (em-dash
+prefix), "parentheses"/"parens", or "none".  Also defined for the
+`LaTeX Writer`__.
+
+Default: "dash".  Options: ``--attribution``.
 
-    Default: "dash".  Options: ``--attribution``.
+__ `attribution [latex2e writer]`_
 
-    __ `attribution [latex2e writer]`_
+cloak_email_addresses
+~~~~~~~~~~~~~~~~~~~~~
 
-_`cloak_email_addresses`
-    Scramble email addresses to confuse harvesters.  In the reference
-    URI, the "@" will be replaced by %-escapes (as of RFC 1738).  In
-    the visible text (link text) of an email reference, the "@" and
-    all periods (".") will be surrounded by ``<span>`` tags.
-    Furthermore, HTML entities are used to encode these characters in
-    order to further complicate decoding the email address.  For
-    example, "abc@example.org" will be output as::
+Scramble email addresses to confuse harvesters.  In the reference
+URI, the "@" will be replaced by %-escapes (as of RFC 1738).  In
+the visible text (link text) of an email reference, the "@" and
+all periods (".") will be surrounded by ``<span>`` tags.
+Furthermore, HTML entities are used to encode these characters in
+order to further complicate decoding the email address.  For
+example, "abc@example.org" will be output as::
 
-        <a class="reference" href="mailto:abc&#37;&#52;&#48;example&#46;org">
-        abc<span>&#64;</span>example<span>&#46;</span>org</a>
+    <a class="reference" href="mailto:abc&#37;&#52;&#48;example&#46;org">
+    abc<span>&#64;</span>example<span>&#46;</span>org</a>
 
-    .. Note:: While cloaking email addresses will have little to no
-       impact on the rendering and usability of email links in most
-       browsers, some browsers (e.g. the ``links`` browser) may decode
-       cloaked email addresses incorrectly.
+.. Note:: While cloaking email addresses will have little to no
+   impact on the rendering and usability of email links in most
+   browsers, some browsers (e.g. the ``links`` browser) may decode
+   cloaked email addresses incorrectly.
 
-    Default: don't cloak (None).  Option: ``--cloak-email-addresses``.
+Default: don't cloak (None).  Option: ``--cloak-email-addresses``.
 
-_`compact_lists`
-    Remove extra vertical whitespace between items of bullet lists and
-    enumerated lists, when list items are all "simple" (i.e., items
-    each contain one paragraph and/or one "simple" sublist only).  The
-    behaviour can be specified directly via "class" attributes (values
-    "compact" and "open") in the document.
+compact_lists
+~~~~~~~~~~~~~
 
-    Default: enabled (1).  Options: ``--compact-lists,
-    --no-compact-lists``.
+Remove extra vertical whitespace between items of bullet lists and
+enumerated lists, when list items are all "simple" (i.e., items
+each contain one paragraph and/or one "simple" sublist only).  The
+behaviour can be specified directly via "class" attributes (values
+"compact" and "open") in the document.
 
-_`compact_field_lists`
-    Remove extra vertical whitespace between items of field lists that
-    are "simple" (i.e., all field bodies each contain at most one
-    paragraph).  The behaviour can be specified directly via "class"
-    attributes (values "compact" and "open") in the document.
+Default: enabled (1).
+Options: ``--compact-lists, --no-compact-lists``.
 
-    Default: enabled (1).  Options: ``--compact-field-lists,
-    --no-compact-field-lists``.
+compact_field_lists
+~~~~~~~~~~~~~~~~~~~
+
+Remove extra vertical whitespace between items of field lists that
+are "simple" (i.e., all field bodies each contain at most one
+paragraph).  The behaviour can be specified directly via "class"
+attributes (values "compact" and "open") in the document.
+
+Default: enabled (1).
+Options: ``--compact-field-lists, --no-compact-field-lists``.
 
 .. _embed_stylesheet [html4css1 writer]:
 
 embed_stylesheet
-    Embed the stylesheet in the output HTML file.  The stylesheet file
-    must specified by the stylesheet_path__ setting and must be
-    accessible during processing.
-    Also defined for the `LaTeX Writer`__.
+~~~~~~~~~~~~~~~~
+
+Embed the stylesheet in the output HTML file.  The stylesheet file
+must specified by the stylesheet_path__ setting and must be
+accessible during processing.
+Also defined for the `LaTeX Writer`__.
 
-    Default: enabled.  Options: ``--embed-stylesheet,
-    --link-stylesheet``.
+Default: enabled.  Options: ``--embed-stylesheet,
+--link-stylesheet``.
 
-    __ `stylesheet_path [html4css1 writer]`_
-    __ `embed_stylesheet [latex2e writer]`_
+__ `stylesheet_path [html4css1 writer]`_
+__ `embed_stylesheet [latex2e writer]`_
 
-_`field_name_limit`
-    The maximum width (in characters) for one-column field names.
-    Longer field names will span an entire row of the table used to
-    render the field list.  0 indicates "no limit".  See also
-    option_limit_.
+field_name_limit
+~~~~~~~~~~~~~~~~
 
-    Default: 14 characters.  Option: ``--field-name-limit``.
+The maximum width (in characters) for one-column field names. Longer
+field names will span an entire row of the table used to render the field
+list.  0 indicates "no limit".  See also option_limit_.
+
+Default: 14 (i.e. 14 characters).  Option: ``--field-name-limit``.
 
 .. _footnote_references [html4css1 writer]:
 
 footnote_references
-    Format for footnote references, one of "superscript" or
-    "brackets".  Also defined for the `LaTeX Writer`__.
+~~~~~~~~~~~~~~~~~~~
+
+Format for footnote references, one of "superscript" or
+"brackets".  Also defined for the `LaTeX Writer`__.
 
-    Overrides [#override]_ trim_footnote_reference_space_, if
-    applicable. [#footnote_space]_
+Overrides [#override]_ trim_footnote_reference_space_, if
+applicable. [#footnote_space]_
 
-    Default: "brackets".  Option: ``--footnote-references``.
+Default: "brackets".  Option: ``--footnote-references``.
 
-    __ `footnote_references [latex2e writer]`_
+__ `footnote_references [latex2e writer]`_
 
-_`initial_header_level`
-    The initial level for header elements.  This does not affect the
-    document title & subtitle; see doctitle_xform_.
+initial_header_level
+~~~~~~~~~~~~~~~~~~~~
 
-    Default: 1 (for "<h1>").  Option: ``--initial-header-level``.
+The initial level for header elements.  This does not affect the
+document title & subtitle; see doctitle_xform_.
 
-_`math_output`
-    The format of mathematical content (`math directive`_ and role) in
-    the output document. Supported values are (case insensitive):
+Default: 1 (for "<h1>").  Option: ``--initial-header-level``.
 
-    :MathJax:
-      Format math for display with MathJax_, a JavaScript-based math
-      rendering engine that uses HTML/CSS, JavaScript, and unicode
-      fonts for high-quality typesetting that is scalable and prints
-      at full resolution.
+math_output
+~~~~~~~~~~~
 
-      Pro:
-        Works 'out of the box' across multiple browsers and platforms.
+The format of mathematical content (`math directive`_ and role) in
+the output document. Supported values are (case insensitive):
 
-        Supports a large subset of LaTeX math commands and constructs
-        (see http://www.mathjax.org/docs/1.1/tex.html).
+:MathJax:
+  Format math for display with MathJax_, a JavaScript-based math
+  rendering engine that uses HTML/CSS, JavaScript, and unicode
+  fonts for high-quality typesetting that is scalable and prints
+  at full resolution.
 
-      Con:
-        Requires an Internet connection (or a local MathJax
-        installation and configuration).
+  Pro:
+    Works 'out of the box' across multiple browsers and platforms.
 
-        Downloads JavaScript code from a third-party site.
+    Supports a large subset of LaTeX math commands and constructs
+    (see http://www.mathjax.org/docs/1.1/tex.html).
 
-      A custom URI can be appended after whitespace,
-      for example a local installation ::
+  Con:
+    Requires an Internet connection (or a local MathJax
+    installation and configuration).
 
-        math-output: MathJax file:/usr/share/javascript/mathjax/MathJax.js
+    Downloads JavaScript code from a third-party site.
 
-      or a URI to `access the MathJax CDN using a https secure
-      connection`__.
+  A custom URI can be appended after whitespace,
+  for example a local installation ::
 
-      __ http://www.mathjax.org/resources/faqs/#problem-https
+    math-output: MathJax file:/usr/share/javascript/mathjax/MathJax.js
 
-    :HTML:
-      Format math in standard HTML enhanced by CSS rules
+  or a URI to `access the MathJax CDN using a https secure
+  connection`__.
 
-      Requires the ``math.css`` stylesheet (stored in the same
-      installation-dependent directory as the `default stylesheet`__).
+  __ http://www.mathjax.org/resources/faqs/#problem-https
 
-      .. __: `stylesheet_path [html4css1 writer]`_
+:HTML:
+  Format math in standard HTML enhanced by CSS rules
 
-    :MathML:
-      Embed math content as presentational MathML_.
+  Requires the ``math.css`` stylesheet (stored in the same
+  installation-dependent directory as the `default stylesheet`__).
 
-      Pro:
-        The W3C recommendation for math on the web.
+  .. __: `stylesheet_path [html4css1 writer]`_
 
-        Self-contained documents (no JavaScript, no external downloads).
+:MathML:
+  Embed math content as presentational MathML_.
 
-      Con:
-        Docutil's latex2mathml converter supports only a small
-        subset of LaTeX syntax.
+  Pro:
+    The W3C recommendation for math on the web.
 
-        With the "html4css1" writer, the resulting HTML document does
-        not validate, as there is no DTD for MathML + XHTML
-        Transitional. However, MathML-enabled browsers will render it
-        fine.
+    Self-contained documents (no JavaScript, no external downloads).
 
-    :LaTeX:
-      Include literal LaTeX code.
+  Con:
+    Docutil's latex2mathml converter supports only a small
+    subset of LaTeX syntax.
 
-      The failsave fallback.
+    With the "html4css1" writer, the resulting HTML document does
+    not validate, as there is no DTD for MathML + XHTML
+    Transitional. However, MathML-enabled browsers will render it
+    fine.
 
-    Default: MathJax  Option: ``--math-output``.
+:LaTeX:
+  Include literal LaTeX code.
 
-    New in Docutils 0.8.
+  The failsave fallback.
 
-    .. _math directive: ../ref/rst/directives.html#math
-    .. _MathJax: http://www.mathjax.org/
-    .. _MathPlayer: http://www.dessci.com/en/products/mathplayer/
-    .. _MathML: http://www.w3.org/TR/MathML/
+Default: MathJax.  Option: ``--math-output``.
 
-_`option_limit`
-    The maximum width (in characters) for options in option lists.
-    Longer options will span an entire row of the table used to render
-    the option list.  0 indicates "no limit".  See also
-    field_name_limit_.
+New in Docutils 0.8.
 
-    Default: 14 characters.  Option: ``--option-limit``.
+.. _math directive: ../ref/rst/directives.html#math
+.. _MathJax: http://www.mathjax.org/
+.. _MathPlayer: http://www.dessci.com/en/products/mathplayer/
+.. _MathML: http://www.w3.org/TR/MathML/
+
+option_limit
+~~~~~~~~~~~~
+
+The maximum width (in characters) for options in option lists.
+Longer options will span an entire row of the table used to render
+the option list.  0 indicates "no limit".  See also
+field_name_limit_.
+
+Default: 14 (i.e. 14 characters).  Option: ``--option-limit``.
 
 .. _stylesheet [html4css1 writer]:
 
 stylesheet
-    A comma-separated list of CSS stylesheet URLs, used verbatim.
-    Also defined for the `LaTeX Writer`__.
+~~~~~~~~~~
 
-    Overrides also stylesheet-path__. [#override]_
+A comma-separated list of CSS stylesheet URLs, used verbatim.
+Also defined for the `LaTeX Writer`__.
 
-    Default: None.  Options: ``--stylesheet``.
+Overrides also stylesheet-path__. [#override]_
 
-    __ `stylesheet [latex2e writer]`_
-    __ `stylesheet_path [html4css1 writer]`_
+Default: None.  Options: ``--stylesheet``.
+
+__ `stylesheet [latex2e writer]`_
+__ `stylesheet_path [html4css1 writer]`_
 
 .. _stylesheet_path [html4css1 writer]:
 
 stylesheet_path
-    A comma-separated list of paths [#pwd]_ to CSS stylesheets.
-    If embed_stylesheet__ is False, paths are rewritten relative to the
-    output HTML file. Also defined for the `LaTeX Writer`__.
+~~~~~~~~~~~~~~~
+
+A comma-separated list of paths [#pwd]_ to CSS stylesheets.
+If embed_stylesheet__ is False, paths are rewritten relative to the
+output HTML file. Also defined for the `LaTeX Writer`__.
 
-    Also overrides "stylesheet". [#override]_
-    Pass an empty string (to either "stylesheet" or "stylesheet_path") to
-    deactivate stylesheet inclusion.
+Also overrides "stylesheet". [#override]_
+Pass an empty string (to either "stylesheet" or "stylesheet_path") to
+deactivate stylesheet inclusion.
 
-    Default: "html4css1.css" in the docutils/writers/html4css1/
-    directory (installed automatically; for the exact machine-specific
-    path, use the ``--help`` option).  Options: ``--stylesheet-path``.
+Default: "html4css1.css" in the docutils/writers/html4css1/
+directory (installed automatically; for the exact machine-specific
+path, use the ``--help`` option).  Options: ``--stylesheet-path``.
 
-    __ `embed_stylesheet [html4css1 writer]`_
-    __ `stylesheet_path [latex2e writer]`_
+__ `embed_stylesheet [html4css1 writer]`_
+__ `stylesheet_path [latex2e writer]`_
 
 .. _table_style [html4css1 writer]:
 
 table_style
-    Added to standard table classes to allow styling with CSS.
-    The default sylesheet defines:
+~~~~~~~~~~~
 
-    borderless
-      no borders around the table.
+Added to standard table classes to allow styling with CSS.
+The default sylesheet defines:
 
-    .. TODO: booktabs
-               a line above and below the table and one after the head.
+borderless
+  no borders around the table.
 
-    Default: "".  Option: ``--table-style``.
+.. TODO: booktabs
+           a line above and below the table and one after the head.
+
+Default: "".  Option: ``--table-style``.
 
 .. _template [html4css1 writer]:
 
 template
-    Path to template file, which must be encoded in UTF-8 [#pwd]_.
-    Also defined for the `LaTeX Writer`__.
+~~~~~~~~
+
+Path to template file, which must be encoded in UTF-8 [#pwd]_.
+Also defined for the `LaTeX Writer`__.
 
-    Default: "template.txt" in the docutils/writers/html4css1/
-    directory (installed automatically; for the exact machine-specific
-    path, use the ``--help`` option).  Options: ``--template``.
+Default: "template.txt" in the docutils/writers/html4css1/
+directory (installed automatically; for the exact machine-specific
+path, use the ``--help`` option).  Options: ``--template``.
 
-    __ `template [latex2e writer]`_
+__ `template [latex2e writer]`_
 
 .. _xml_declaration [html4css1 writer]:
 
 xml_declaration
-    Generate XML with an XML declaration.  Also defined for the
-    `Docutils XML Writer`__.
+~~~~~~~~~~~~~~~
+
+Generate XML with an XML declaration.  Also defined for the
+`Docutils XML Writer`__.
 
-    .. Caution:: The XML declaration carries text encoding
-       information, without which standard tools may be unable to read
-       the generated XML.
+.. Caution:: The XML declaration carries text encoding
+   information, without which standard tools may be unable to read
+   the generated XML.
 
-    Default: do (1).  Options: ``--no-xml-declaration``.
+Default: do (1).  Options: ``--no-xml-declaration``.
 
-    __ `xml_declaration [docutils_xml writer]`_
+__ `xml_declaration [docutils_xml writer]`_
 
 
 [pep_html writer]
-.................
+-----------------
 
 The PEP/HTML Writer derives from the standard HTML Writer, and shares
 all settings defined in the `[html4css1 writer]`_ section.  The
 "[html4css1 writer]" section of configuration files is processed
 before the "[pep_html writer]" section.
 
-_`no_random`
-    Do not use a random banner image.  Mainly used to get predictable
-    results when testing.
-
-    Default: random enabled (None).  Options: ``--no-random``
-    (hidden).
-
-_`pep_home`
-    Home URL prefix for PEPs.
-
-    Default: current directory (".").  Options: ``--pep-home``.
-
-_`python_home`
-    Python's home URL.
-
-    Default: parent directory ("..").  Options: ``--python-home``.
-
 The PEP/HTML Writer's default for the following settings differ from
 those of the standard HTML Writer:
 
@@ -998,332 +1106,399 @@ those of the standard HTML Writer:
   directory.  For the exact machine-specific path, use the ``--help``
   option.
 
+no_random
+~~~~~~~~~
+Do not use a random banner image.  Mainly used to get predictable
+results when testing.
+
+Default: random enabled (None).  Options: ``--no-random`` (hidden).
+
+pep_home
+~~~~~~~~
+
+Home URL prefix for PEPs.
+
+Default: current directory (".").  Options: ``--pep-home``.
+
+python_home
+~~~~~~~~~~~
+Python's home URL.
+
+Default: parent directory ("..").  Options: ``--python-home``.
+
 
 [s5_html writer]
-.................
+----------------
 
 The S5/HTML Writer derives from the standard HTML Writer, and shares
 all settings defined in the `[html4css1 writer]`_ section.  The
 "[html4css1 writer]" section of configuration files is processed
 before the "[s5_html writer]" section.
 
-_`hidden_controls`
-    Auto-hide the presentation controls in slideshow mode, or or keep
-    them visible at all times.
+The S5/HTML Writer's default for the following settings differ
+from those of the standard HTML Writer:
 
-    Default: auto-hide (1).  Options: ``--hidden-controls``,
-    ``--visible-controls``.
+* ``compact_lists``: The default here is to disable compact lists.
 
-_`current_slide`
-    Enable or disable the current slide indicator ("1/15").
+* ``template``: The default is
+  ``docutils/writers/s5_html/template.txt`` in the installation
+  directory.  For the exact machine-specific path, use the ``--help``
+  option.
 
-    Default: disabled (None).  Options: ``--current-slide``,
-    ``--no-current-slide``.
 
-_`overwrite_theme_files`
-    Allow or prevent the overwriting of existing theme files in the
-    ``ui/<theme>`` directory.  This has no effect if "theme_url_" is
-    used.
+hidden_controls
+~~~~~~~~~~~~~~~
 
-    Default: keep existing theme files (None).  Options:
-    ``--keep-theme-files``, ``--overwrite-theme-files``.
+Auto-hide the presentation controls in slideshow mode, or or keep
+them visible at all times.
 
-_`theme`
-    Name of an installed S5 theme, to be copied into a ``ui/<theme>``
-    subdirectory, beside the destination file (output HTML).  Note
-    that existing theme files will not be overwritten; the existing
-    theme directory must be deleted manually.
-    Also overrides the "theme_url_" setting. [#override]_
+Default: auto-hide (1).  Options: ``--hidden-controls``,
+``--visible-controls``.
 
-    Default: "default".  Option: ``--theme``.
+current_slide
+~~~~~~~~~~~~~
 
-_`theme_url`
-    The URL of an S5 theme directory.  The destination file (output
-    HTML) will link to this theme; nothing will be copied.  Also overrides
-    the "theme_" setting. [#override]_
+Enable or disable the current slide indicator ("1/15").
 
-    Default: None.  Option: ``--theme-url``.
+Default: disabled (None).  Options: ``--current-slide``,
+``--no-current-slide``.
 
-_`view_mode`
-    The initial view mode, either "slideshow" or "outline".
+overwrite_theme_files
+~~~~~~~~~~~~~~~~~~~~~
 
-    Default: "slidewhow".  Option: ``--view-mode``.
+Allow or prevent the overwriting of existing theme files in the
+``ui/<theme>`` directory.  This has no effect if "theme_url_" is
+used.
 
-The S5/HTML Writer's default for the following settings differ
-from those of the standard HTML Writer:
+Default: keep existing theme files (None).  Options:
+``--keep-theme-files``, ``--overwrite-theme-files``.
 
-* ``compact_lists``: The default here is to disable compact lists.
+theme
+~~~~~
 
-* ``template``: The default is
-  ``docutils/writers/s5_html/template.txt`` in the installation
-  directory.  For the exact machine-specific path, use the ``--help``
-  option.
+Name of an installed S5 theme, to be copied into a ``ui/<theme>``
+subdirectory, beside the destination file (output HTML).  Note
+that existing theme files will not be overwritten; the existing
+theme directory must be deleted manually.
+Also overrides the "theme_url_" setting. [#override]_
+
+Default: "default".  Option: ``--theme``.
+
+theme_url
+~~~~~~~~~
+The URL of an S5 theme directory.  The destination file (output
+HTML) will link to this theme; nothing will be copied.  Also overrides
+the "theme_" setting. [#override]_
+
+Default: None.  Option: ``--theme-url``.
+
+view_mode
+~~~~~~~~~
+
+The initial view mode, either "slideshow" or "outline".
+
+Default: "slidewhow".  Option: ``--view-mode``.
 
 
 [latex2e writer]
-````````````````
+----------------
+
+use_latex_toc
+~~~~~~~~~~~~~
+
+To get pagenumbers in the table of contents the table of contents
+must be generated by LaTeX. Usually latex must be run twice to get
+numbers correct.
+
+Default: on.  Options: ``--use-latex-toc, --use-docutils-toc``.
+
+use_latex_docinfo
+~~~~~~~~~~~~~~~~~
+
+Attach author and date to the document title
+instead of the document info table.
+
+Default: off.  Options: ``--use-latex-docinfo, --use-docutils-docinfo``.
+
+docutils_footnotes
+~~~~~~~~~~~~~~~~~~
+Use the Docutils-specific macros ``\DUfootnote`` and
+``\DUfootnotetext`` for footnotes.
+
+Default: on.  Option: ``--docutils-footnotes``.
 
-_`use_latex_toc`
-    To get pagenumbers in the table of contents the table of contents
-    must be generated by LaTeX. Usually latex must be run twice to get
-    numbers correct.
+figure_footnotes
+~~~~~~~~~~~~~~~~
 
-    Default: on.  Options: ``--use-latex-toc, --use-docutils-toc``.
+Typeset footnote text in a figure float. This may lead to footnotes,
+citations, and figures being mixed at page foot.
 
-_`use_latex_docinfo`
-    Attach author and date to the document title
-    instead of the document info table.
+*Deprecated:* This setting will be removed in a future Docutils
+version.
 
-    Default: off.  Options: ``--use-latex-docinfo, --use-docutils-docinfo``
+Default: off.  Option: ``--figure-footnotes``.
 
-_`docutils_footnotes`
-    Use the Docutils-specific macros ``\DUfootnote`` and
-    ``\DUfootnotetext`` for footnotes.
+use_latex_citations
+~~~~~~~~~~~~~~~~~~~
 
-    Default: on.  Option: ``--docutils-footnotes``.
+Use \cite for citations instead of a simulation with figure-floats.
 
-_`use_latex_footnotes`
-    Backwards-compatibility alias for docutils_footnotes_ (deprecated).
+Default: off.  Options: ``--use-latex-citations, --figure-citations``.
 
-    *Note*: the planned new option _`latex_footnotes` will use the
-    ``\footnote`` command and footnote numbering by LaTeX.
+use_latex_abstract
+~~~~~~~~~~~~~~~~~~
 
-_`figure_footnotes`
-    Typeset footnote text in a figure float.
-    This may lead to footnotes, citations, and figures being
-    mixed at page foot.
+Use LaTeX abstract environment for the document's abstract.
 
-    *Deprecated:* This setting will be removed in a future Docutils
-    version.
+Default: off.  Options: ``--use-latex-abstract, --topic-abstract``.
 
-    Default: off.  Option: ``--figure-footnotes``.
+hyperlink_color
+~~~~~~~~~~~~~~~
 
-_`use_latex_citations`
-    Use \cite for citations instead of a simulation with figure-floats.
+Color of any hyperlinks embedded in text.
 
-    Default: off.  Options: ``--use-latex-citations, --figure-citations``.
+* "0" or "false" disable coloring of links. (Links will be marked
+  by red boxes that are not printed),
+* "black" results in “invisible“ links,
 
-_`use_latex_abstract`
-    Use LaTeX abstract environment for the document's abstract.
+Set hyperref_options_ to "draft" to completely disable hyperlinking.
 
-    Default: off.  Options: ``--use-latex-abstract, --topic-abstract``.
+Default: "blue".  Option: ``--hyperlink-color``.
 
-_`hyperlink_color`
-    Color of any hyperlinks embedded in text.
+hyperref_options
+~~~~~~~~~~~~~~~~
 
-    * "0" or "false" disable coloring of links. (Links will be marked
-      by red boxes that are not printed),
-    * "black" results in “invisible“ links,
+Options for the `hyperref TeX package`_. If hyperlink_color_ is
+not "false", the expansion of ::
 
-    Set hyperref_options_ to "draft" to completely disable
-    hyperlinking.
+  'colorlinks=true,linkcolor=%s,urlcolor=%s' % (
+     hyperlink_color, self.hyperlink_color
 
-    Default: "blue".  Option: ``--hyperlink-color``.
+is prepended.
 
-_`hyperref_options`
-    Options for the `hyperref TeX package`_. If hyperlink_color_ is
-    not "false", the expansion of ::
+Default: "".   Option: ``--hyperref-options``.
 
-      'colorlinks=true,linkcolor=%s,urlcolor=%s' % (
-         hyperlink_color, self.hyperlink_color
+.. _hyperref TeX package: http://tug.org/applications/hyperref/
 
-    is prepended. For documents typeset in Cyrillic script,
-    ``--hyperref-options=unicode`` is recommended.
+documentclass
+~~~~~~~~~~~~~
 
-    Default: "".   Option: ``--hyperref-options``.
+Specify latex documentclass.
 
-    .. _hyperref TeX package: http://tug.org/applications/hyperref/
+Default: "article".  Option: ``--documentclass``.
 
-_`documentclass`
-    Specify latex documentclass.
+documentoptions
+~~~~~~~~~~~~~~~
 
-    Default: "article".  Option: ``--documentclass``.
+Specify document options.  Multiple options can be given, separated by
+commas.
 
-_`documentoptions`
-    Specify document options.  Multiple options can be given, separated by
-    commas.
+Default: "a4paper".  Option: ``--documentoptions``.
 
-    Default: "a4paper".  Option: ``--documentoptions``.
+font_encoding
+~~~~~~~~~~~~~
 
-_`font_encoding`
-    Specify LaTeX font encoding. Multiple options can be given, separated
-    by commas. Possible values are "", "T1", "OT1", "LGR,T1" or any other
-    combination of `LaTeX font encodings`_.
+Specify LaTeX font encoding. Multiple options can be given, separated by
+commas. The last value becomes the document default.
+Possible values are "", "T1", "OT1", "LGR,T1" or any other combination of
+`LaTeX font encodings`_.
 
-    Default: "T1".  Option: ``--font-encoding``.
+Default: "T1".  Option: ``--font-encoding``.
 
-    .. _LaTeX font encodings:
-       http://mirror.ctan.org/macros/latex/doc/encguide.pdf
+.. _LaTeX font encodings:
+   http://mirror.ctan.org/macros/latex/doc/encguide.pdf
 
 .. _embed_stylesheet [latex2e writer]:
 
 embed_stylesheet
-    Embed the stylesheet(s) in the header of the output file.  The
-    stylesheets must be accessible during processing.  Currently, this
-    fails if the file is not available via the given path (i.e. the
-    file is *not* searched in the `TeX input path`_).
-    Also defined for the `HTML Writer`__ (with default *on*).
+~~~~~~~~~~~~~~~~
+
+Embed the stylesheet(s) in the header of the output file.  The
+stylesheets must be accessible during processing.  Currently, this
+fails if the file is not available via the given path (i.e. the
+file is *not* searched in the `TeX input path`_).
+Also defined for the `HTML Writer`__ (with default *on*).
 
-    Default: off.  Options: ``--embed-stylesheet, --link-stylesheet``.
+Default: off.  Options: ``--embed-stylesheet, --link-stylesheet``.
 
-    __ `embed_stylesheet [html4css1 writer]`_
+__ `embed_stylesheet [html4css1 writer]`_
 
 .. _stylesheet [latex2e writer]:
 
 stylesheet
-    A comma-separated list of style files.
-    Also defined for the `HTML Writer`__.
+~~~~~~~~~~
+
+A comma-separated list_ of style files.
+Also defined for the `HTML Writer`__.
 
-    Overrides also stylesheet_path__. [#override]_
+Overrides also stylesheet_path__. [#override]_
 
-    If `embed_stylesheet`__ is False (default), the stylesheet files are
-    referenced with ``\usepackage`` (extension ``.sty`` or no extension) or
-    ``\input`` (any other extension).
+If `embed_stylesheet`__ is False (default), the stylesheet files are
+referenced with ``\usepackage`` (extension ``.sty`` or no extension) or
+``\input`` (any other extension).
 
-    LaTeX will search the specified files in the `TeX input path`_.
+LaTeX will search the specified files in the `TeX input path`_.
 
-    Default: no stylesheet ("").  Option: ``--stylesheet``.
+Default: no stylesheet ("").  Option: ``--stylesheet``.
 
-    __ `stylesheet_path [latex2e writer]`_
-    __ `embed_stylesheet [latex2e writer]`_
-    __ `stylesheet [html4css1 writer]`_
-    .. _TeX input path:
-       http://www.tex.ac.uk/cgi-bin/texfaq2html?label=what-TDS
+__ `stylesheet_path [latex2e writer]`_
+__ `embed_stylesheet [latex2e writer]`_
+__ `stylesheet [html4css1 writer]`_
+.. _TeX input path:
+   http://www.tex.ac.uk/cgi-bin/texfaq2html?label=what-TDS
 
 
 .. _stylesheet_path [latex2e writer]:
 
 stylesheet_path
-    Similar to stylesheet__, however paths [#pwd]_ are rewritten relative to
-    the output file (if there is a common part in the given path and the
-    output file path). Also defined for the `HTML Writer`__.
+~~~~~~~~~~~~~~~
 
-    Run ``latex`` from the directory containing the output file. Fails for
-    files in the TEXINPUTS path; use stylesheet__ in this case.
+Similar to stylesheet__, however paths [#pwd]_ are rewritten relative to
+the output file (if there is a common part in the given path and the
+output file path). Also defined for the `HTML Writer`__.
 
-    Also overrides stylesheet__. [#override]_
+Run ``latex`` from the directory containing the output file. Fails for
+files in the TEXINPUTS path; use stylesheet__ in this case.
 
-    Default: no stylesheet ("").  Option: ``--stylesheet-path``.
+Also overrides stylesheet__. [#override]_
 
-    __ `stylesheet [latex2e writer]`_
-    __ `stylesheet_path [html4css1 writer]`_
-    __
-    __ `stylesheet [latex2e writer]`_
+Default: no stylesheet ("").  Option: ``--stylesheet-path``.
 
+__ `stylesheet [latex2e writer]`_
+__ `stylesheet_path [html4css1 writer]`_
+__
+__ `stylesheet [latex2e writer]`_
+
+
+latex_preamble
+~~~~~~~~~~~~~~
 
-_`latex_preamble`
-    LaTeX code that will be inserted in the document preamble.
-    Can be used to load packages with options or (re-) define LaTeX
-    macros without writing a custom style file (new in Docutils 0.7).
+LaTeX code that will be inserted in the document preamble.
+Can be used to load packages with options or (re-) define LaTeX
+macros without writing a custom style file (new in Docutils 0.7).
 
-    Default: Load the "PDF standard fonts" (Times, Helvetica,
-    Courier)::
+Default: Load the "PDF standard fonts" (Times, Helvetica,
+Courier)::
 
-      \usepackage{mathptmx} % Times
-      \usepackage[scaled=.90]{helvet}
-      \usepackage{courier}
+  \usepackage{mathptmx} % Times
+  \usepackage[scaled=.90]{helvet}
+  \usepackage{courier}
 
-    Option: ``--latex-preamble``
+Option: ``--latex-preamble``.
 
 
 .. _template [latex2e writer]:
 
 template
-    Path to template file, which must be encoded in UTF-8 [#pwd]_.
-    Also defined for the `HTML Writer`__.
+~~~~~~~~
 
-    Default: "default.tex" in the docutils/writers/latex2e/
-    directory (installed automatically; for the exact machine-specific
-    path, use the ``--help`` option).  Options: ``--template``.
+Path to template file, which must be encoded in UTF-8 [#pwd]_.
+Also defined for the `HTML Writer`__.
 
-    __ `template [html4css1 writer]`_
+Default: "default.tex" in the docutils/writers/latex2e/
+directory (installed automatically; for the exact machine-specific
+path, use the ``--help`` option).  Options: ``--template``.
+
+__ `template [html4css1 writer]`_
 
 .. _footnote_references [latex2e writer]:
 
 footnote_references
-    Format for footnote references: one of "superscript" or
-    "brackets".  Also defined for the `HTML Writer`__.
+~~~~~~~~~~~~~~~~~~~
+
+Format for footnote references: one of "superscript" or
+"brackets".  Also defined for the `HTML Writer`__.
 
-    Overrides [#override]_ trim_footnote_reference_space_, if
-    applicable [#footnote_space]_.
+Overrides [#override]_ trim_footnote_reference_space_, if
+applicable [#footnote_space]_.
 
-    Default: "superscript".  Option: ``--footnote-references``.
+Default: "superscript".  Option: ``--footnote-references``.
 
-    __ `footnote_references [html4css1 writer]`_
+__ `footnote_references [html4css1 writer]`_
 
 .. _attribution [latex2e writer]:
 
 attribution
-    Format for block quote attributions, the same as for the
-    html-writer: one of "dash" (em-dash prefix),
-    "parentheses"/"parens" or "none".  Also defined for the `HTML
-    Writer`__.
+~~~~~~~~~~~
+
+Format for block quote attributions, the same as for the `HTML writer`__:
+one of "dash" (em-dash prefix), "parentheses"/"parens" or "none".
+
+Default: "dash".  Option: ``--attribution``.
+
+__ `attribution [html4css1 writer]`_
+
+compound_enumerators
+~~~~~~~~~~~~~~~~~~~~
 
-    Default: "dash".  Option: ``--attribution``.
+Enable or disable compound enumerators for nested enumerated lists
+(e.g. "1.2.a.ii").
 
-    __ `attribution [html4css1 writer]`_
+Default: disabled (None).
+Options: ``--compound-enumerators``, ``--no-compound-enumerators``.
 
-_`compound_enumerators`
-    Enable or disable compound enumerators for nested enumerated lists
-    (e.g. "1.2.a.ii").
+literal_block_env
+~~~~~~~~~~~~~~~~~
 
-    Default: disabled (None).  Options: ``--compound-enumerators``,
-    ``--no-compound-enumerators``.
+When possibile\ [#]_, use the specified environment for literal-blocks.
 
-_`literal_block_env`
-    When possibile\ [#]_, use the specified environment for literal-blocks.
+Default: "" (quoting of whitespace and special chars).
+Option: ``--literal-block-env``.
 
-    Default: "" (quoting of whitespace and special chars)
-    Option: ``--literal-block-env``
+.. [#] A literal-block element, when processed by a Docutils writer might
+   have it's origin in literal block following "::" or a 
+   ``.. parsed-literal::`` directive.
 
-   .. [#] A literal-block element, when processed by a Docutils writer might
-      have it's origin in a markup with "::" syntax or a "..
-      parsed-literal::" directive.
+   A LaTeX verbatim environment is only usable if there is no other
+   markup contained in the literal-block.
 
-      A LaTeX verbatim environment is only usable if there is no other
-      markup contained in the literal-block.
 
+section_prefix_for_enumerators
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-_`section_prefix_for_enumerators`
-    Enable or disable section ("." subsection ...) prefixes for
-    compound enumerators.  This has no effect unless
-    `compound_enumerators`_ are enabled.
+Enable or disable section ("." subsection ...) prefixes for
+compound enumerators.  This has no effect unless
+`compound_enumerators`_ are enabled.
 
-    Default: disabled (None).  Options:
-    ``--section-prefix-for-enumerators``,
-    ``--no-section-prefix-for-enumerators``.
+Default: disabled (None).
+Options: ``--section-prefix-for-enumerators``, 
+``--no-section-prefix-for-enumerators``.
 
-_`section_enumerator_separator`
-    The separator between section number prefix and enumerator for
-    compound enumerated lists (see `compound_enumerators`_).
+section_enumerator_separator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    Generally it isn't recommended to use both sub-sections and nested
-    enumerated lists with compound enumerators.  This setting avoids
-    ambiguity in the situation where a section "1" has a list item
-    enumerated "1.1", and subsection "1.1" has list item "1".  With a
-    separator of ".", these both would translate into a final compound
-    enumerator of "1.1.1".  With a separator of "-", we get the
-    unambiguous "1-1.1" and "1.1-1".
+The separator between section number prefix and enumerator for
+compound enumerated lists (see `compound_enumerators`_).
 
-    Default: "-".  Option: ``--section-enumerator-separator``.
+Generally it isn't recommended to use both sub-sections and nested
+enumerated lists with compound enumerators.  This setting avoids
+ambiguity in the situation where a section "1" has a list item
+enumerated "1.1", and subsection "1.1" has list item "1".  With a
+separator of ".", these both would translate into a final compound
+enumerator of "1.1.1".  With a separator of "-", we get the
+unambiguous "1-1.1" and "1.1-1".
+
+Default: "-".  Option: ``--section-enumerator-separator``.
 
 .. _table_style [latex2e writer]:
 
 table_style
-    Specify the drawing of separation lines.
-    Supported values:
+~~~~~~~~~~~
+
+Specify the drawing of separation lines.
+Supported values:
 
-    standard
-      lines around and between cells.
-    booktabs
-      a line above and below the table and one after the head.
-    borderless
-      no lines.
+standard
+  lines around and between cells.
+booktabs
+  a line above and below the table and one after the head.
+borderless
+  no lines.
 
-    Default: "standard".  Option: ``--table-style``.
+Default: "standard".  Option: ``--table-style``.
 
 [xetex writer]
-.................
+--------------
 
 The xetex writer derives from the latex2e writer, and shares
 all settings defined in the `[latex2e writer]`_ section.  The
@@ -1333,169 +1508,209 @@ before the "[xetex writer]" section.
 The following settings differ from those of the latex2e writer:
 
 font_encoding
-    Disabled as XeTeX uses Unicode-encoded fonts.
+    Disabled  (XeTeX uses Unicode-encoded fonts).
 
 .. _latex_preamble [xetex writer]:
 
 latex_preamble
-    LaTeX code that will be inserted in the document preamble.
+~~~~~~~~~~~~~~
 
-    Default:
-      Font setup for `Linux Libertine`_,::
+LaTeX code that will be inserted in the document preamble.
 
-        % Linux Libertine (free, wide coverage, not only for Linux)
-        \setmainfont{Linux Libertine O}
-        \setsansfont{Linux Biolinum O}
-        \setmonofont[HyphenChar=None]{DejaVu Sans Mono}
+Default:
+  Font setup for `Linux Libertine`_,::
 
-      The optional argument ``HyphenChar=None`` to the monospace font
-      prevents word hyphenation in literal text.
+    % Linux Libertine (free, wide coverage, not only for Linux)
+    \setmainfont{Linux Libertine O}
+    \setsansfont{Linux Biolinum O}
+    \setmonofont[HyphenChar=None]{DejaVu Sans Mono}
 
+  The optional argument ``HyphenChar=None`` to the monospace font
+  prevents word hyphenation in literal text.
 
-    Option: ``--latex-preamble``
 
-    .. _Linux Libertine: http://www.linuxlibertine.org/
+Option: ``--latex-preamble``.
+
+.. _Linux Libertine: http://www.linuxlibertine.org/
 
 .. _template [xetex writer]:
 
 template
-    Path to template file.
+~~~~~~~~
 
-    Default: "xelatex.tex" in the ``docutils/writers/latex2e/``
-    directory (installed automatically; for the exact machine-specific
-    path, use the ``--help`` option).  Options: ``--template``.
+Path to template file.
 
+Default: "xelatex.tex" in the ``docutils/writers/latex2e/``
+directory (installed automatically; for the exact machine-specific
+path, use the ``--help`` option).  Options: ``--template``.
 
 
 [odf_odt writer]
-``````````````````
+----------------
 
 The following command line options are specific to ``odtwriter``:
 
-_`stylesheet=<URL>`
-    Specify a stylesheet URL, used verbatim.  Default:
-    writers/odf_odt/styles.odt in the installation directory.
+stylesheet
+~~~~~~~~~~
+
+Specify a stylesheet URL, used verbatim.  
+
+Default: writers/odf_odt/styles.odt in the installation directory.
+
+odf-config-file
+~~~~~~~~~~~~~~~
+
+Specify a configuration/mapping file relative to the current working
+directory for additional ODF options. In particular, this file may
+contain a section named "Formats" that maps default style names to names
+to be used in the resulting output file allowing for adhering to external
+standards. For more info and the format of the configuration/mapping
+file, see the `Odt Writer for Docutils`_ document.
+
+cloak-email-addresses
+~~~~~~~~~~~~~~~~~~~~~
+
+Obfuscate email addresses to confuse harvesters while still
+keeping email links usable with standards-compliant browsers.
 
-_`odf-config-file=<file>`
-    Specify a configuration/mapping file relative to the
-    current working directory for additional ODF options.
-    In particular, this file may contain a section named
-    "Formats" that maps default style names to names to be
-    used in the resulting output file allowing for
-    adhering to external standards. For more info and the
-    format of the configuration/mapping file, see the
-    `Odt Writer for Docutils`_ document.
+no-cloak-email-addresses
+~~~~~~~~~~~~~~~~~~~~~~~~
+Do not obfuscate email addresses.
 
-_`cloak-email-addresses`
-    Obfuscate email addresses to confuse harvesters while still
-    keeping email links usable with standards-compliant browsers.
+table-border-thickness
+~~~~~~~~~~~~~~~~~~~~~~
 
-_`no-cloak-email-addresses`
-    Do not obfuscate email addresses.
+Specify the thickness of table borders in thousands of a cm.
+Default is 35.
 
-_`table-border-thickness=<TABLE_BORDER_THICKNESS>`
-    Specify the thickness of table borders in thousands of a cm.
-    Default is 35.
+add-syntax-highlighting
+~~~~~~~~~~~~~~~~~~~~~~~
 
-_`add-syntax-highlighting`
-    Add syntax highlighting in literal code blocks.
+Add syntax highlighting in literal code blocks.
 
-_`no-syntax-highlighting`
-    Do not add syntax highlighting in literal code blocks.
-    (default)
+no-syntax-highlighting
+~~~~~~~~~~~~~~~~~~~~~~
 
-_`create-sections`
-    Create sections for headers.  (default)
+Do not add syntax highlighting in literal code blocks.
+(default)
 
-_`no-sections`
-    Do not create sections for headers.
+create-sections
+~~~~~~~~~~~~~~~
 
-_`create-links`
-    Create links.
+Create sections for headers.  (default)
 
-_`no-links`
-    Do not create links.  (default)
+no-sections
+~~~~~~~~~~~
 
-_`endnotes-end-doc`
-    Generate endnotes at end of document, not footnotes at bottom of
-    page.
+Do not create sections for headers.
 
-_`no-endnotes-end-doc`
-    Generate footnotes at bottom of page, not endnotes at end of
-    document. (default)
+create-links
+~~~~~~~~~~~~
+Create links.
 
-_`generate-list-toc`
-    Generate a bullet list table of contents, not an
-    ODF/``oowriter`` table of contents.
+no-links
+~~~~~~~~
 
-_`generate-oowriter-toc`
-    Generate an ODF/``oowriter`` table of contents, not a bullet
-    list.  (default) **Note:** ``odtwriter`` is not able to
-    determine page numbers, so you will need to open the generated
-    document in ``oowriter``, then right-click on the table of
-    contents and select "Update" to insert page numbers.
+Do not create links.  (default)
 
-_`custom-odt-header=<CUSTOM_HEADER>`
-    Specify the contents of a custom header line.  For details about
-    custom headers and about special field character sequences, see
-    section "Custom header/footers: inserting page numbers, date,
-    time, etc" in the `Odt Writer for Docutils`_ document for
-    details.
+endnotes-end-doc
+~~~~~~~~~~~~~~~~
 
-_`custom-odt-footer=<CUSTOM_FOOTER>`
-    Specify the contents of a custom footer line.  For details about
-    custom footers and about special field character sequences, see
-    section "Custom header/footers: inserting page numbers, date,
-    time, etc" in the `Odt Writer for Docutils`_ document for
-    details.
+Generate endnotes at end of document, not footnotes at bottom of page.
 
-.. _`Odt Writer for Docutils`: odt.html
+no-endnotes-end-doc
+~~~~~~~~~~~~~~~~~~~
+
+Generate footnotes at bottom of page, not endnotes at end of
+document. (default)
+
+generate-list-toc
+~~~~~~~~~~~~~~~~~
+
+Generate a bullet list table of contents, not an
+ODF/``oowriter`` table of contents.
+
+generate-oowriter-toc
+~~~~~~~~~~~~~~~~~~~~~
+
+Generate an ODF/``oowriter`` table of contents, not a bullet
+list.  (default) **Note:** ``odtwriter`` is not able to
+determine page numbers, so you will need to open the generated
+document in ``oowriter``, then right-click on the table of
+contents and select "Update" to insert page numbers.
+
+custom-odt-header
+~~~~~~~~~~~~~~~~~
+
+Specify the contents of a custom header line.  For details about
+custom headers and about special field character sequences, see
+section "Custom header/footers: inserting page numbers, date,
+time, etc" in the `Odt Writer for Docutils`_ document for
+details.
+
+custom-odt-footer
+~~~~~~~~~~~~~~~~~
+
+Specify the contents of a custom footer line.  For details about
+custom footers and about special field character sequences, see
+section "Custom header/footers: inserting page numbers, date,
+time, etc" in the `Odt Writer for Docutils`_ document for
+details.
+
+.. _Odt Writer for Docutils: odt.html
 
 
 [pseudoxml writer]
-``````````````````
+------------------
 
-No settings are defined for this Writer.
+This writer does not define specific settings.
 
 
 [applications]
---------------
+==============
 
 [buildhtml application]
-```````````````````````
+-----------------------
+
+ignore
+~~~~~~
+
+List_ of wildcard (shell globing) patterns, specifying files to silently
+ignore.  To specify multiple patterns, use colon-separated patterns (in
+configuration files or on the command line); on the command line, the
+option may also be used more than once.
 
-_`ignore`
-    List of wildcard (shell globing) patterns, specifying files to
-    silently ignore.  To specify multiple patterns, use
-    colon-separated patterns (in configuration files or on the command
-    line); on the command line, the option may also be used more than
-    once.
+Default: none.  Options: ``--ignore``.
 
-    Default: none ([]).  Options: ``--ignore``.
+prune
+~~~~~
 
-_`prune`
-    List of directories not to process.  To specify multiple
-    directories, use colon-separated paths (in configuration files or
-    on the command line); on the command line, the option may also be
-    used more than once.
+List_ of directories not to process.  To specify multiple
+directories, use colon-separated paths (in configuration files or
+on the command line); on the command line, the option may also be
+used more than once.
 
-    Default: ['.hg', '.bzr', '.git', '.svn', 'CVS'].  Options:
-    ``--prune``.
+Default: ['.hg', '.bzr', '.git', '.svn', 'CVS'].  Options:
+``--prune``.
 
-_`recurse`
-    Recursively scan subdirectories, or ignore subdirectories.
+recurse
+~~~~~~~
 
-    Default: recurse (1).  Options: ``--recurse, --local``.
+Recursively scan subdirectories, or ignore subdirectories.
 
-_`silent`
-    Work silently (no progress messages).  Independent of
-    "report_level".
+Default: recurse (1).  Options: ``--recurse, --local``.
 
-    Default: show progress (None).  Options: ``--silent``.
+silent
+~~~~~~
+
+Work silently (no progress messages).  Independent of
+"report_level".
+
+Default: show progress (None).  Options: ``--silent``.
 
 
 [docfactory application]
-````````````````````````
+------------------------
 
 (To be completed.)
 
@@ -1509,17 +1724,19 @@ Command-Line Only
 These settings are only effective as command-line options; setting
 them in configuration files has no effect.
 
-_`config`
-    Path to a configuration file to read (if it exists) [#pwd]_.
-    Settings may override defaults and earlier settings.  The config
-    file is processed immediately.  Multiple ``--config`` options may
-    be specified; each will be processed in turn.
+config
+~~~~~~
+
+Path to a configuration file to read (if it exists) [#pwd]_.
+Settings may override defaults and earlier settings.  The config
+file is processed immediately.  Multiple ``--config`` options may
+be specified; each will be processed in turn.
 
-    Filesystem path settings contained within the config file will be
-    interpreted relative to the config file's location (*not* relative
-    to the current working directory).
+Filesystem path settings contained within the config file will be
+interpreted relative to the config file's location (*not* relative
+to the current working directory).
 
-    Default: None.  Options: ``--config``.
+Default: None.  Options: ``--config``.
 
 
 Internal Settings
@@ -1529,33 +1746,43 @@ These settings are for internal use only; setting them in
 configuration files has no effect, and there are no corresponding
 command-line options.
 
-_`_config_files`
-    List of paths of applied configuration files.
+_config_files
+~~~~~~~~~~~~~
+
+List of paths of applied configuration files.
+
+Default: None.  No command-line options.
+
+_directories
+~~~~~~~~~~~~
+
+(``buildhtml.py`` front end.)  List of paths to source
+directories, set from positional arguments.
+
+Default: current working directory (None).  No command-line
+options.
 
-    Default: None.  No command-line options.
+_disable_config
+~~~~~~~~~~~~~~~
 
-_`_directories`
-    (``buildhtml.py`` front end.)  List of paths to source
-    directories, set from positional arguments.
+Prevent standard configuration files from being read.  For
+programmatic use only.
 
-    Default: current working directory (None).  No command-line
-    options.
+Default: config files enabled (None).  No command-line options.
 
-_`_disable_config`
-    Prevent standard configuration files from being read.  For
-    programmatic use only.
+_destination
+~~~~~~~~~~~~
 
-    Default: config files enabled (None).  No command-line options.
+Path to output destination, set from positional arguments.
 
-_`_destination`
-    Path to output destination, set from positional arguments.
+Default: stdout (None).  No command-line options.
 
-    Default: stdout (None).  No command-line options.
+_source
+~~~~~~~
 
-_`_source`
-    Path to input source, set from positional arguments.
+Path to input source, set from positional arguments.
 
-    Default: stdin (None).  No command-line options.
+Default: stdin (None).  No command-line options.
 
 
 .. _language tag: http://www.w3.org/International/articles/language-tags/