Usage
=====

  html.py [options] [<source> [<destination>]]

Generates (X)HTML documents from standalone reStructuredText sources.  Reads
from <source> (default is stdin) and writes to <destination> (default is
stdout).

options
=======

General Docutils Options
------------------------

--generator, -g         Include a "Generated by Docutils" credit and link at
                        the end of the document.
--no-generator          Do not include a generator credit.
--date, -d              Include the date at the end of the document (UTC).
--time, -t              Include the time & date at the end of the document
                        (UTC).
--no-datestamp          Do not include a datestamp of any kind.
--source-link, -s       Include a "View document source" link (relative to
                        destination).
--source-url=<URL>      Use the supplied <URL> verbatim for a "View document
                        source" link; implies --source-link.
--no-source-link        Do not include a "View document source" link.
--toc-entry-backlinks   Enable backlinks from section headers to table of
                        contents entries.  This is the default.
--toc-top-backlinks     Enable backlinks from section headers to the top of
                        the table of contents.
--no-toc-backlinks      Disable backlinks to the table of contents.
--footnote-backlinks    Enable backlinks from footnotes and citations to their
                        references.  This is the default.
--no-footnote-backlinks
                        Disable backlinks from footnotes and citations.
--report=<level>, -r<level>
                        Set verbosity threshold; report system messages at or
                        higher than <level> (by name or number: "info" or "1",
                        warning/2, error/3, severe/4; also, "none" or "5").
                        Default is 2 (warning).
--verbose, -v           Report all system messages, info-level and higher.
                        (Same as "--report=info".)
--quiet, -q             Do not report any system messages.  (Same as "--
                        report=none".)
--halt=<level>          Set the threshold (<level>) at or above which system
                        messages are converted to exceptions, halting
                        execution immediately.  Levels as in --report.
                        Default is 4 (severe).
--strict                Same as "--halt=info": halt processing at the
                        slightest problem.
--exit=<level>          Enable a non-zero exit status for normal exit if non-
                        halting system messages (at or above <level>) were
                        generated.  Levels as in --report.  Default is 5
                        (disabled).  Exit status is the maximum system message
                        level plus 10 (11 for INFO, etc.).
--debug                 Report debug-level system messages and generate
                        diagnostic output.
--no-debug              Do not report debug-level system messages or generate
                        diagnostic output.
--warnings=<file>       Send the output of system messages (warnings) to
                        <file>.
--traceback             Enable Python tracebacks when an error occurs.
--no-traceback          Disable Python tracebacks when errors occur; report
                        just the error instead.  This is the default.
--input-encoding=<name>, -i<name>
                        Specify the encoding of input text.  Default is
                        locale-dependent.
--output-encoding=<name[:handler]>, -o<name[:handler]>
                        Specify the text encoding for output.  Default is
                        UTF-8.  Optionally also specify the encoding error
                        handler for unencodable characters (see "--error-
                        encoding"); default is "strict".
--error-encoding=<name[:handler]>, -e<name[:handler]>
                        Specify the text encoding for error output.  Default
                        is ASCII.  Optionally also specify the encoding error
                        handler for unencodable characters, after a colon
                        (":").  Acceptable values are the same as for the
                        "error" parameter of Python's ``encode`` string
                        method.  Default is "replace".
--language=<name>, -l<name>
                        Specify the language of input text (ISO 639 2-letter
                        identifier).  Default is "en" (English).
--config=<file>         Read configuration settings from <file>, if it exists.
--version, -V           Show this program's version number and exit.
--help, -h              Show this help message and exit.

reStructuredText Parser Options
-------------------------------
--pep-references        Recognize and link to PEP references (like "PEP 258").
--rfc-references        Recognize and link to RFC references (like "RFC 822").
--tab-width=<width>     Set number of spaces for tab expansion (default 8).
--trim-footnote-reference-space
                        Remove spaces before footnote references.

Standalone Reader
-----------------
--no-doc-title          Disable the promotion of a lone top-level section
                        title to document title (and subsequent section title
                        to document subtitle promotion; enabled by default).
--no-doc-info           Disable the bibliographic field list transform
                        (enabled by default).

HTML-Specific Options
---------------------
--stylesheet=<URL>      Specify a stylesheet URL, used verbatim.  Default is
                        "default.css".  Overridden by --stylesheet-path.
--stylesheet-path=<file>
                        Specify a stylesheet file, relative to the current
                        working directory.  The path is adjusted relative to
                        the output HTML file.  Overrides --stylesheet.
--link-stylesheet       Link to the stylesheet in the output HTML file.  This
                        is the default.
--embed-stylesheet      Embed the stylesheet in the output HTML file.  The
                        stylesheet file must be accessible during processing (
                        --stylesheet-path is recommended).  The stylesheet is
                        embedded inside a comment, so it must not contain the
                        text "--" (two hyphens).  Default: link the
                        stylesheet, do not embed it.
--footnote-references=<format>
                        Format for footnote references: one of "superscript"
                        or "brackets".  Default is "superscript".
--attribution=<format>  Format for block quote attributions: one of "dash" (
                        em-dash prefix), "parentheses"/"parens", or "none".
                        Default is "dash".
--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.
--no-compact-lists      Disable compact simple bullet and enumerated lists.
--no-xml-declaration    Omit the XML declaration.  Use with caution.