| blob | faebbdddc420054a358412829cffcd1cd6931ee9 |
1 .. -*- rst-mode -*-
3 .. Help text generated with ``rst2html_trans --help``.
5 .. contents::
7 Usage
8 =====
9 rst2html_trans.py [options] [<source> [<destination>]]
11 Generates (X)HTML documents from standalone reStructuredText sources that do
12 not require a CSS stylesheet. Reads from <source> (default is stdin) and
13 writes to <destination> (default is stdout).
15 options
16 =======
17 General Docutils Options
18 ------------------------
19 --title=TITLE Specify the document title as metadata (not part of
20 the document body). Overrides a document-provided
21 title. There is no default.
22 --generator, -g Include a "Generated by Docutils" credit and link at
23 the end of the document.
24 --no-generator Do not include a generator credit.
25 --date, -d Include the date at the end of the document (UTC).
26 --time, -t Include the time & date at the end of the document
27 (UTC).
28 --no-datestamp Do not include a datestamp of any kind.
29 --source-link, -s Include a "View document source" link (relative to
30 destination).
31 --source-url=<URL> Use the supplied <URL> verbatim for a "View document
32 source" link; implies --source-link.
33 --no-source-link Do not include a "View document source" link.
34 --toc-entry-backlinks Enable backlinks from section headers to table of
35 contents entries. This is the default.
36 --toc-top-backlinks Enable backlinks from section headers to the top of
37 the table of contents.
38 --no-toc-backlinks Disable backlinks to the table of contents.
39 --footnote-backlinks Enable backlinks from footnotes and citations to their
40 references. This is the default.
41 --no-footnote-backlinks
42 Disable backlinks from footnotes and citations.
43 --section-numbering Enable Docutils section numbering (default: enabled).
44 --no-section-numbering Disable Docutils section numbering (default: enabled).
45 --strip-comments Remove comment elements from the document tree
46 (default: leave them).
47 --leave-comments Leave comment elements in the document tree (this is
48 the default).
49 --report=<level>, -r <level>
50 Set verbosity threshold; report system messages at or
51 higher than <level> (by name or number: "info" or "1",
52 warning/2, error/3, severe/4; also, "none" or "5").
53 Default is 2 (warning).
54 --verbose, -v Report all system messages, info-level and higher.
55 (Same as "--report=info".)
56 --quiet, -q Do not report any system messages. (Same as "--
57 report=none".)
58 --halt=<level> Set the threshold (<level>) at or above which system
59 messages are converted to exceptions, halting
60 execution immediately by exiting (or propagating the
61 exception if --traceback set). Levels as in --report.
62 Default is 4 (severe).
63 --strict Same as "--halt=info": halt processing at the
64 slightest problem.
65 --exit-status=<level> Enable a non-zero exit status for normal exit if non-
66 halting system messages (at or above <level>) were
67 generated. Levels as in --report. Default is 5
68 (disabled). Exit status is the maximum system message
69 level plus 10 (11 for INFO, etc.).
70 --debug Report debug-level system messages and generate
71 diagnostic output.
72 --no-debug Do not report debug-level system messages or generate
73 diagnostic output.
74 --warnings=<file> Send the output of system messages (warnings) to
75 <file>.
76 --traceback Enable Python tracebacks when halt-level system
77 messages and other exceptions occur. Useful for
78 debugging, and essential for issue reports.
79 --no-traceback Disable Python tracebacks when errors occur; report
80 just the error instead. This is the default.
81 --input-encoding=<name[:handler]>, -i <name[:handler]>
82 Specify the encoding of input text. Default is
83 locale-dependent. Optionally also specify the error
84 handler for undecodable characters, after a colon
85 (":"); default is "strict". (See "--intput-encoding-
86 error-handler".)
87 --input-encoding-error-handler=INPUT_ENCODING_ERROR_HANDLER
88 Specify the error handler for undecodable characters
89 in the input. Acceptable values include "strict",
90 "ignore", and "replace". Default is "strict".
91 Usually specified as part of --input-encoding.
92 --output-encoding=<name[:handler]>, -o <name[:handler]>
93 Specify the text encoding for output. Default is
94 UTF-8. Optionally also specify the error handler for
95 unencodable characters, after a colon (":"); default
96 is "strict". (See "--output-encoding-error-handler".)
97 --output-encoding-error-handler=OUTPUT_ENCODING_ERROR_HANDLER
98 Specify the error handler for unencodable characters
99 in the output. Acceptable values include "strict",
100 "ignore", "replace", "xmlcharrefreplace", and
101 "backslashreplace" (in Python 2.3+). Default is
102 "strict". Usually specified as part of --output-
103 encoding.
104 --error-encoding=<name[:handler]>, -e <name[:handler]>
105 Specify the text encoding for error output. Default
106 is ASCII. Optionally also specify the error handler
107 for unencodable characters, after a colon (":");
108 default is "backslashreplace". (See "--output-
109 encoding-error-handler".)
110 --error-encoding-error-handler=ERROR_ENCODING_ERROR_HANDLER
111 Specify the error handler for unencodable characters
112 in error output. See --output-encoding-error-handler
113 for acceptable values. Default is "backslashreplace".
114 Usually specified as part of --error-encoding.
115 --language=<name>, -l <name>
116 Specify the language of input text (ISO 639 2-letter
117 identifier). Default is "en" (English).
118 --record-dependencies=<file>
119 Write dependencies (caused e.g. by file inclusions) to
120 <file>. Useful in conjunction with programs like
121 "make".
122 --config=<file> Read configuration settings from <file>, if it exists.
123 --version, -V Show this program's version number and exit.
124 --help, -h Show this help message and exit.
126 reStructuredText Parser Options
127 -------------------------------
128 --pep-references Recognize and link to standalone PEP references (like
129 "PEP 258").
130 --pep-base-url=<URL> Base URL for PEP references (default
131 "http://www.python.org/peps/").
132 --rfc-references Recognize and link to standalone RFC references (like
133 "RFC 822").
134 --rfc-base-url=<URL> Base URL for RFC references (default
135 "http://www.faqs.org/rfcs/").
136 --tab-width=<width> Set number of spaces for tab expansion (default 8).
137 --trim-footnote-reference-space
138 Remove spaces before footnote references.
139 --leave-footnote-reference-space
140 Leave spaces before footnote references.
141 --no-file-insertion Disable directives that insert the contents of
142 external file ("include" & "raw"); replaced with a
143 "warning" system message.
144 --file-insertion-enabled
145 Enable directives that insert the contents of external
146 file ("include" & "raw"). Enabled by default.
147 --no-raw Disable the "raw" directives; replaced with a
148 "warning" system message.
149 --raw-enabled Enable the "raw" directive. Enabled by default.
151 Standalone Reader
152 -----------------
153 --no-doc-title Disable the promotion of a lone top-level section
154 title to document title (and subsequent section title
155 to document subtitle promotion; enabled by default).
156 --no-doc-info Disable the bibliographic field list transform
157 (enabled by default).
158 --section-subtitles Activate the promotion of lone subsection titles to
159 section subtitles (disabled by default).
160 --no-section-subtitles Deactivate the promotion of lone subsection titles.
162 HTML-Specific Options
163 ---------------------
164 --stylesheet=<URL> Specify a stylesheet URL, used verbatim. Overrides
165 --stylesheet-path.
166 --stylesheet-path=<file>
167 Specify a stylesheet file, relative to the current
168 working directory. The path is adjusted relative to
169 the output HTML file. Overrides --stylesheet.
170 Default: "../../../../lib/python2.4/site-
171 packages/docutils/writers/html4css1/html4css1.css"
172 --embed-stylesheet Embed the stylesheet in the output HTML file. The
173 stylesheet file must be accessible during processing
174 (--stylesheet-path is recommended). This is the
175 default.
176 --link-stylesheet Link to the stylesheet in the output HTML file.
177 Default: embed the stylesheet, do not link to it.
178 --initial-header-level=<level>
179 Specify the initial header level. Default is 1 for
180 "<h1>". Does not affect document title & subtitle
181 (see --no-doc-title).
182 --field-name-limit=<level>
183 Specify the maximum width (in characters) for one-
184 column field names. Longer field names will span an
185 entire row of the table used to render the field list.
186 Default is 14 characters. Use 0 for "no limit".
187 --option-limit=<level> Specify the maximum width (in characters) for options
188 in option lists. Longer options will span an entire
189 row of the table used to render the option list.
190 Default is 14 characters. Use 0 for "no limit".
191 --footnote-references=<format>
192 Format for footnote references: one of "superscript"
193 or "brackets". Default is "brackets".
194 --attribution=<format> Format for block quote attributions: one of "dash"
195 (em-dash prefix), "parentheses"/"parens", or "none".
196 Default is "dash".
197 --compact-lists Remove extra vertical whitespace between items of
198 "simple" bullet lists and enumerated lists. Default:
199 enabled.
200 --no-compact-lists Disable compact simple bullet and enumerated lists.
201 --compact-field-lists Remove extra vertical whitespace between items of
202 simple field lists. Default: enabled.
203 --no-compact-field-lists
204 Disable compact simple field lists.
205 --no-xml-declaration Omit the XML declaration. Use with caution.
206 --cloak-email-addresses
207 Obfuscate email addresses to confuse harvesters while
208 still keeping email links usable with standards-
209 compliant browsers.