re-added docutils-0.3.9 tag one level deeper (without web/ and sandboxes/)docutils-0.3.9

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

1 files changed, 959 insertions, 0 deletions

diff --git a/docs/user/config.txt b/docs/user/config.txt
new file mode 100644
index 000000000..1b52511b4
--- /dev/null
+++ b/docs/user/config.txt
@@ -0,0 +1,959 @@
+==============================
+ Docutils Configuration Files
+==============================
+
+:Author: David Goodger
+:Contact: goodger@python.org
+:Revision: $Revision$
+:Date: $Date$
+:Copyright: This document has been placed in the public domain.
+
+.. contents::
+
+.. Cross-reference command-line options with configuration file
+   settings?  Make alphabetical indexes of both.
+
+Configuration files are used for persistent customization; they can be
+set once and take effect every time you use a front-end tool.
+Configuration file settings override the built-in defaults, and
+command-line options override all.
+
+By default, Docutils checks the following places for configuration
+files, in the following order:
+
+1. ``/etc/docutils.conf``: This is a system-wide configuration file,
+   applicable to all Docutils processing on the system.
+
+2. ``./docutils.conf``: This is a project-specific configuration file,
+   located in the current directory.  The Docutils front end has to be
+   executed from the directory containing this configuration file for
+   it to take effect (note that this may have nothing to do with the
+   location of the source files).  Settings in the project-specific
+   configuration file will override corresponding settings in the
+   system-wide file.
+
+3. ``~/.docutils``: This is a user-specific configuration file,
+   located in the user's home directory.  Settings in this file will
+   override corresponding settings in both the system-wide and
+   project-specific configuration files.
+
+If more than one configuration file is found, all will be read but
+later entries will override earlier ones.  For example, a "stylesheet"
+entry in a user-specific configuration file will override a
+"stylesheet" entry in the system-wide file.
+
+The default implicit config file paths can be overridden by the
+``DOCUTILSCONFIG`` environment variable.  ``DOCUTILSCONFIG`` should
+contain a colon-separated (semicolon-separated on Windows) sequence of
+config file paths to search for; leave it empty to disable implicit
+config files altogether.  Tilde-expansion is performed on paths.
+Paths are interpreted relative to the current working directory.
+Empty path items are ignored.
+
+In addition, a configuration file may be explicitly specified with the
+"--config" command-line option.  This configuration file is read after
+the three implicit ones listed above (or the ones defined by the
+``DOCUTILSCONFIG`` environment variable), and its entries will have
+priority.
+
+
+-------------------------
+Configuration File Syntax
+-------------------------
+
+Configuration files use the standard ConfigParser.py_ Python_ module.
+From its documentation:
+
+    The configuration file consists of sections, lead by a "[section]"
+    header and followed by "name: value" entries, with continuations
+    in the style of `RFC 822`_; "name=value" is also accepted.  Note
+    that leading whitespace is removed from values.  ...  Lines
+    beginning with "#" or ";" are ignored and may be used to provide
+    comments.
+
+.. Note:: No format string interpolation is done.
+
+Configuration file entry names correspond to internal runtime
+settings.  Underscores ("_") and hyphens ("-") can be used
+interchangably in entry names; hyphens are automatically converted to
+underscores.
+
+For on/off switch settings (booleans), the following values are
+recognized:
+
+* On: "true", "yes", "on", "1"
+* Off: "false", "no", "off", "0", "" (no value)
+
+
+-------------------------------------
+Configuration File Sections & Entries
+-------------------------------------
+
+Below are the Docutils runtime settings, listed by config file
+section.  Any setting may be specified in any section, but only
+settings from active sections will be used.  Sections correspond to
+Docutils components (module name or alias; section names are always in
+lowercase letters).  Each `Docutils application`_ uses a specific set
+of components; corresponding configuration file sections are applied
+when the application is used.  Configuration sections are applied in
+general-to-specific order, as follows:
+
+1. `[general]`_
+
+2. `[parsers]`_, parser dependencies, and the section specific to the
+   Parser used ("[... parser]").  Currently, only `[restructuredtext
+   parser]`_ is applicable.
+
+3. `[readers]`_, reader dependencies, and the section specific to the
+   Reader used ("[... reader]").  For example, `[pep reader]`_ depends
+   on `[standalone reader]`_.
+
+4. `[writers]`_, writer dependencies, and the section specific to the
+   Writer used ("[... writer]").  For example, `[pep_html writer]`_
+   depends on `[html4css1 writer]`_.
+
+5. `[applications]`_, application dependencies, and the section
+    specific to the Application (front-end tool) in use
+    ("[... application]").
+
+Since any setting may be specified in any section, this ordering
+allows component- or application-specific overrides of earlier
+settings.  For example, there may be Reader-specific overrides of
+general settings; Writer-specific overrides of Parser settings;
+Application-specific overrides of Writer settings; and so on.
+
+If multiple configuration files are applicable, the process is
+completed (all sections are applied in the order given) for each one
+before going on to the next.  For example, a "[pep_html writer]
+stylesheet" setting in an earlier configuration file would be
+overridden by an "[html4css1 writer] stylesheet" setting in a later
+file.
+
+Some knowledge of Python_ is assumed for some attributes.
+
+.. _ConfigParser.py:
+   http://www.python.org/doc/current/lib/module-ConfigParser.html
+.. _Python: http://www.python.org/
+.. _RFC 822: http://www.rfc-editor.org/rfc/rfc822.txt
+.. _Docutils application: tools.html
+
+
+[general]
+=========
+
+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_.
+
+    Default: "id".  Options: ``--auto-id-prefix`` (hidden, intended
+    mainly for programmatic use).
+    
+_`datestamp`
+    Include a time/datestamp in the document footer.  Contains a
+    format string for Python's ``time.strftime``.  See the `time
+    module documentation`__.
+
+    Default: None.  Options: ``--date, -d, --time, -t,
+    --no-datestamp``.
+
+    Configuration file entry examples::
+
+        # Equivalent to --date command-line option, results in
+        # ISO 8601 extended format datestamp, e.g. "2001-12-21":
+        datestamp: %Y-%m-%d
+
+        # Equivalent to --time command-line option, results in
+        # date/timestamp like "2001-12-21 18:43 UTC":
+        datestamp: %Y-%m-%d %H:%M UTC
+
+        # Disables datestamp; equivalent to --no-datestamp:
+        datestamp:
+
+    __ http://www.python.org/doc/current/lib/module-time.html
+
+_`debug`
+    Report debug-level system messages.
+
+    Default: don't (None).  Options: ``--debug, --no-debug``.
+
+_`dump_internals`
+    At the end of processing, write all internal attributes of the
+    document (``document.__dict__``) to stderr.
+
+    Default: don't (None).  Options: ``--dump-internals`` (hidden, for
+    development use only).
+
+_`dump_pseudo_xml`
+    At the end of processing, write the pseudo-XML representation of
+    the document to stderr.
+
+    Default: don't (None).  Options: ``--dump-pseudo-xml`` (hidden,
+    for development use only).
+
+_`dump_settings`
+    At the end of processing, write all Docutils settings to stderr.
+
+    Default: don't (None).  Options: ``--dump-settings`` (hidden, for
+    development use only).
+
+_`dump_transforms`
+    At the end of processing, write a list of all transforms applied
+    to the document to stderr.
+
+    Default: don't (None).  Options: ``--dump-transforms`` (hidden,
+    for development use only).
+
+_`error_encoding`
+    The text encoding for error output.
+
+    Default: "ascii".  Options: ``--error-encoding, -e``.
+
+_`error_encoding_error_handler`
+    The error handler for unencodable characters in error output.  See
+    output_encoding_error_handler_ for acceptable values.
+
+    Default: "backslashreplace" for Python 2.3 and later; "replace"
+    otherwise.  Options: ``--error-encoding-error-handler,
+    --error-encoding, -e``.
+
+_`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.).
+
+    Default: disabled (5).  Options: ``--exit-status``.
+
+_`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: ``--expose-internal-attribute``
+    (hidden, for development use only).
+
+_`footnote_backlinks`
+    Enable or disable backlinks from footnotes and citations to their
+    references.
+
+    Default: enabled (1).  Options: ``--footnote-backlinks,
+    --no-footnote-backlinks``.
+
+_`generator`
+    Include a "Generated by Docutils" credit and link in the document
+    footer.
+
+    Default: off (None).  Options: ``--generator, -g,
+    --no-generator``.
+
+_`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: severe (4).  Options: ``--halt, --strict``.
+
+_`id_prefix`
+    Prefix prepended to all IDs generated within the document.  See
+    also auto_id_prefix_.
+
+    Default: "" (empty).  Options: ``--id-prefix`` (hidden, intended
+    mainly for programmatic use).
+    
+_`input_encoding`
+    The text encoding for input.
+
+    Default: auto-detect (None).  Options: ``--input-encoding, -i``.
+
+_`input_encoding_error_handler`
+    The error handler for undecodable characters in the input.
+    Acceptable values include:
+
+    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.
+
+    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.
+
+    Default: "strict".  Options: ``--input-encoding-error-handler,
+    --input-encoding, -i``.
+
+_`language_code`
+    `ISO 639`_ 2-letter language code (3-letter codes used only if no
+    2-letter code exists).
+
+    Default: English ("en").  Options: ``--language, -l``.
+
+_`output_encoding`
+    The text encoding for output.
+
+    Default: "UTF-8".  Options: ``--output-encoding, -o``.
+
+_`output_encoding_error_handler`
+    The error handler for unencodable characters in the output.
+    Acceptable values include:
+
+    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
+        "``†``".
+    backslashreplace
+        (Python 2.3+)  Replace with backslashed escape sequences, such
+        as "``\u2020``".
+
+    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: "strict".  Options: ``--output-encoding-error-handler,
+    --output-encoding, -o``.
+
+_`record_dependencies`
+
+    Path to a file to which Docutils writes a list of files the input
+    file(s) depends on [#dependencies]_, e.g. due to file
+    inclusion. [#pwd]_ The format is one filename per line.  This
+    option is particularly useful in conjunction with programs like
+    ``make``.
+
+    Set to ``-`` in order to write dependencies to stdout.
+
+    Default: None.  Option: ``--record-dependencies``.
+
+_`report_level`
+    Verbosity threshold at or above which system messages are
+    reported.
+
+    Default: warning (2).  Options: ``--report, -r, --verbose, -v,
+    --quiet, -q``.
+
+_`sectnum_xform`
+    Enable or disable the section numbering transform
+    (docutils.transforms.parts.SectNum).
+
+    Default: enabled (1).  Options: ``--no-section-numbering``.
+
+_`source_link`
+    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).
+
+_`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.)
+
+    Default: enabled (1).  Options: ``--file-insertion-enabled,
+    --no-file-insertion``.
+
+    .. _include: ../ref/rst/directives.html#include
+    .. _raw: ../ref/rst/directives.html#raw
+
+_`pep_references`
+    Recognize and link to standalone PEP references (like "PEP 258").
+
+    Default: disabled (None); enabled (1) in PEP Reader.  Options:
+    ``--pep-references``.
+
+_`pep_base_url`
+    Base URL for PEP references.  
+
+    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.)
+
+    Default: enabled (1).  Options: ``--raw-enabled, --no-raw``.
+
+_`rfc_references`
+    Recognize and link to standalone RFC references (like "RFC 822").
+
+    Default: disabled (None); enabled (1) in PEP Reader.  Options:
+    ``--rfc-references``.
+
+_`rfc_base_url`
+    Base URL for RFC references.  
+
+    Default: "http://www.faqs.org/rfcs/".  Option: ``--rfc-base-url``.
+
+_`tab_width`
+    Number of spaces for hard tab expansion.
+
+    Default: 8.  Options: ``--tab-width``.
+
+_`trim_footnote_reference_space`
+    Remove spaces before footnote 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``.
+
+__ `footnote_references [latex2e writer]`_
+
+
+[readers]
+---------
+
+
+[standalone reader]
+```````````````````
+
+_`docinfo_xform`
+    Enable or disable the bibliographic field list transform
+    (docutils.transforms.frontmatter.DocInfo).
+
+    Default: enabled (1).  Options: ``--no-doc-info``.
+
+_`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).
+
+    Default: enabled (1).  Options: ``--no-doc-title``.
+
+_`sectsubtitle_xform`
+
+    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``.
+
+
+[pep reader]
+````````````
+
+The `pep_references`_ and `rfc_references`_ options
+(`[restructuredtext parser]`_) are set on by default.
+
+
+[python reader]
+```````````````
+
+Under construction.
+
+
+[writers]
+---------
+
+[docutils_xml writer]
+`````````````````````
+
+_`doctype_declaration`
+    Generate XML with a DOCTYPE declaration.
+
+    Default: do (1).  Options: ``--no-doctype``.
+
+_`indents`
+    Generate XML with indents and newlines.
+
+    Default: don't (None).  Options: ``--indents``.
+
+_`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`__.
+
+    .. 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``.
+
+    __ `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`__.
+
+    Default: "dash".  Options: ``--attribution``.
+
+    __ `attribution [latex2e writer]`_
+
+_`cloak_email_addresses`
+    Scramble email addresses to confuse harvesters.  In the visible
+    text of an email address, the "@" will be replaced by "at", and
+    all periods (".") will be replaced by "dot", with spaces added.
+    In the reference URI, the address will be replaced by %-escapes.
+    For example, "abc@example.org" will be output as::
+
+        <a class="reference"
+         href="mailto:%61%62%63%40%65%78%61%6D%70%6C%65%2E%6F%72%67">
+        abc at example dot org</a>
+
+    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 "simple" (i.e., all items
+    each contain one paragraph and/or one "simple" sublist only).
+
+    Default: enabled (1).  Options: ``--compact-lists,
+    --no-compact-lists``.
+
+_`embed_stylesheet`
+    Embed the stylesheet in the output HTML file.  The stylesheet file
+    must be accessible during processing.
+
+    Default: link, don't embed (None).  Options: ``--embed-stylesheet,
+    --link-stylesheet``.
+
+_`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 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`__.
+
+    Overrides [#override]_ trim_footnote_reference_space_, if
+    applicable. [#footnote_space]_
+
+    Default: "brackets".  Option: ``--footnote-references``.
+
+    __ `footnote_references [latex2e writer]`_
+
+_`initial_header_level`
+    The initial level for header elements.  This does not affect the
+    document title & subtitle; see doctitle_xform_.
+
+    Default: 1 (for "<h1>").  Option: ``--initial-header-level``.
+
+.. _stylesheet [html4css1 writer]:
+
+_`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 characters.  Option: ``--option-limit``.
+
+stylesheet
+    CSS stylesheet URL, used verbatim.  Overrides stylesheet_path
+    [#override]_.
+
+    Default: "default.css".  Options: ``--stylesheet``.
+
+    (Setting also defined for the `LaTeX Writer`__.)
+
+    __ `stylesheet [latex2e writer]`_
+
+.. _stylesheet_path [html4css1 writer]:
+
+stylesheet_path
+    Path to CSS stylesheet [#pwd]_.  Overrides "stylesheet" URL
+    setting (``--stylesheet``) [#override]_.  Path is adjusted
+    relative to the output HTML file.  Also defined for the `LaTeX
+    Writer`__.
+
+    Default: None.  Options: ``--stylesheet-path``.
+
+    __ `stylesheet_path [latex2e writer]`_
+
+.. _xml_declaration [html4css1 writer]:
+
+xml_declaration
+    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.
+
+    Default: do (1).  Options: ``--no-xml-declaration``.
+
+    __ `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 is processed before "[pep_html writer]".
+
+_`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``.
+
+_`template`
+    Path to PEP template file [#pwd]_.
+
+    Default: "pep-html-template" (in current directory).  Options:
+    ``--template``.
+
+_`python_home`
+    Python's home URL.
+
+    Default: parent directory ("..").  Options: ``--python-home``.
+
+
+[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.
+
+    *Note:* LaTeX will number the sections, which might be a bug in
+    this case.
+
+    Default: off.  Option: ``--use-latex-toc``.
+
+.. XXX Missing: use_latex_docinfo
+
+_`use_latex_footnotes`
+    Use LaTeX-footnotes not a figure simulation. This might give no
+    Hyperrefs on /to footnotes, but should be able to handle an
+    unlimited number of footnotes.
+
+    Default: off.  Option: ``--use-latex-footnotes``.
+
+_`hyperlink_color`
+    Color of any hyperlinks embedded in text. Use "0" to disable
+    coloring of links.
+
+    Default: "blue".  Option: ``--hyperlink-color``.
+
+_`documentclass`
+    Specify latex documentclass, *but* beaware that books have chapters
+    articles not.
+
+    Default: "article".  Option: ``--documentclass``.
+
+_`documentoptions`
+    Specify document options.  Multiple options can be given, separated by
+    commas.
+
+    Default: "10pt,a4paper".  Option: ``--documentoptions``.
+
+.. _stylesheet [latex2e writer]:
+
+stylesheet
+    Specify a stylesheet file.  Overrides stylesheet_path
+    [#override]_.  The file will be ``\input`` by latex in the
+    document header.  Also defined for the `HTML Writer`__.
+
+    Default: no stylesheet ("").  Option: ``--stylesheet``.
+
+    __ `stylesheet [html4css1 writer]`_
+
+.. _stylesheet_path [latex2e writer]:
+
+stylesheet_path
+    Path to stylesheet [#pwd]_.  Overrides "stylesheet" setting
+    (``--stylesheet``) [#override]_.
+
+    Please note that you will have to run ``latex`` from the directory
+    containing the output file; otherwise the stylesheet reference
+    will be invalid.
+
+    This setting is also defined for the `HTML Writer`__.
+
+    Default: None.  Option: ``--stylesheet-path``.
+
+    __ `stylesheet_path [html4css1 writer]`_
+
+.. XXX Missing: embed_stylesheet
+
+.. _footnote_references [latex2e writer]:
+
+footnote_references
+    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]_
+
+    Default: "superscript".  Option: ``--footnote-references``.
+
+    __ `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`__.
+
+    Default: "dash".  Option: ``--attribution``.
+
+    __ `attribution [html4css1 writer]`_
+
+_`compound_enumerators`
+    Enable or disable compound enumerators for nested enumerated lists
+    (e.g. "1.2.a.ii").
+
+    Default: disabled (None).  Options: ``--compound-enumerators``,
+    ``--no-compound-enumerators``.
+
+_`section_prefix_for_enumerators`
+    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``.
+
+_`section_enumerator_separator`
+    The separator between section number prefix and enumerator for
+    compound enumerated lists (see `compound_enumerators`_).
+
+    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`
+    Specify the drawing of separation lines.
+
+    - "standard" lines around and between cells.
+    - "booktabs" a line above and below the table and one after the
+      head.
+    - "nolines".
+
+    Default: "standard".  Option: ``--table-style``.
+
+
+[pseudoxml writer]
+``````````````````
+
+No settings are defined for this Writer.
+
+
+[applications]
+--------------
+
+[buildhtml application]
+```````````````````````
+
+_`prune`
+    List of directories not to process.  To specify multiple
+    directories in configuration files, use colon-separated paths; on
+    the command line, the option may be used more than once.
+
+    Default: none ([]).  Options: ``--prune``.
+
+_`recurse`
+    Recursively scan subdirectories, or ignore subdirectories.
+
+    Default: recurse (1).  Options: ``--recurse, --local``.
+
+_`silent`
+    Work silently (no progress messages).  Independent of
+    "report_level".
+
+    Default: show progress (None).  Options: ``--silent``.
+
+
+[docfactory application]
+````````````````````````
+
+(To be completed.)
+
+
+Other Settings
+==============
+
+These settings are only effective as command-line options, positional
+arguments, or for internal use; 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.
+
+    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``.
+
+_`_directories`
+    (``buildhtml.py`` front end.)  List of paths to source
+    directories, set from positional arguments.
+
+    Default: current working directory (None).  No command-line
+    options.
+
+_`_disable_config`
+    Prevent standard configuration files from being read.  For
+    internal use only.
+
+    Default: config files enabled (None).  No command-line options.
+
+_`_destination`
+    Path to output destination, set from positional arguments.
+
+    Default: stdout (None).  No command-line options.
+
+_`_source`
+    Path to input source, set from positional arguments.
+
+    Default: stdin (None).  No command-line options.
+
+
+.. _ISO 639: http://lcweb.loc.gov/standards/iso639-2/englangn.html
+
+.. [#pwd] Path relative to the working directory of the process at
+   launch.
+
+.. [#override] The overridden setting will automatically be set to
+   ``None`` for command-line options and config file settings.  Client
+   programs which specify defaults that override other settings must
+   do the overriding explicitly, by assigning ``None`` to the other
+   settings.
+
+.. [#dependencies] Some notes on the dependency recorder:
+
+   * Images are only added to the dependency list if the
+     reStructuredText parser extracted image dimensions from the file.
+
+   * Stylesheets are only added if they are embedded.
+
+   * For practical reasons, the output of the LaTeX writer is
+     considered merely an *intermediate* processing stage.  The
+     dependency recorder records all files the *rendered* file
+     (e.g. in PDF or DVI format) depends on.  Thus, images and
+     stylesheets are both unconditionally recorded as dependencies
+     when using the LaTeX writer.
+   
+.. [#footnote_space] The footnote space is trimmed if the reference
+   style is "superscript", and it is left if the reference style is
+   "brackets".
+
+   The overriding only happens if the parser supports the
+   trim_footnote_reference_space option.
+
+
+------------------------------
+Old-Format Configuration Files
+------------------------------
+
+Formerly, Docutils configuration files contained a single "[options]"
+section only.  This was found to be inflexible, and in August 2003
+Docutils adopted the current component-based configuration file
+sections as described above.  Docutils will still recognize the old
+"[options]" section, but complains with a deprecation warning.
+
+To convert existing config files, the easiest way is to change the
+section title: change "[options]" to "[general]".  Most settings
+haven't changed.  The only ones to watch out for are these:
+
+=====================  =====================================
+Old-Format Setting     New Section & Setting
+=====================  =====================================
+pep_stylesheet         [pep_html writer] stylesheet
+pep_stylesheet_path    [pep_html writer] stylesheet_path
+pep_template           [pep_html writer] template
+=====================  =====================================