1 ========================
3 ========================
6 :Contact: docutils-develop@lists.sourceforge.net
9 :Copyright: This document has been placed in the public domain.
11 .. sidebar:: Docutils Security for Web Applications
13 For details about securing web applications, please see `Deploying
14 Docutils Securely <../howto/security.html>`_.
23 Configuration files are used for persistent customization; they can be
24 set once and take effect every time you use a front-end tool.
25 Configuration file settings override the built-in defaults, and
26 command-line options override all.
28 By default, Docutils checks the following places for configuration
29 files, in the following order:
31 1. ``/etc/docutils.conf``: This is a system-wide configuration file,
32 applicable to all Docutils processing on the system.
34 2. ``./docutils.conf``: This is a project-specific configuration file,
35 located in the current directory. The Docutils front end has to be
36 executed from the directory containing this configuration file for
37 it to take effect (note that this may have nothing to do with the
38 location of the source files). Settings in the project-specific
39 configuration file will override corresponding settings in the
42 3. ``~/.docutils``: This is a user-specific configuration file,
43 located in the user's home directory. Settings in this file will
44 override corresponding settings in both the system-wide and
45 project-specific configuration files.
47 If more than one configuration file is found, all will be read but
48 later entries will override earlier ones. For example, a "stylesheet"
49 entry in a user-specific configuration file will override a
50 "stylesheet" entry in the system-wide file.
52 The default implicit config file paths can be overridden by the
53 ``DOCUTILSCONFIG`` environment variable. ``DOCUTILSCONFIG`` should
54 contain a colon-separated (semicolon-separated on Windows) sequence of
55 config file paths to search for; leave it empty to disable implicit
56 config files altogether. Tilde-expansion is performed on paths.
57 Paths are interpreted relative to the current working directory.
58 Empty path items are ignored.
60 In addition, a configuration file may be explicitly specified with the
61 ``--config`` command-line option. This configuration file is read after
62 the three implicit ones listed above (or the ones defined by the
63 ``DOCUTILSCONFIG`` environment variable), and its entries will have
67 -------------------------
68 Configuration File Syntax
69 -------------------------
71 Configuration files are UTF-8-encoded text files. The
72 ConfigParser.py_ module from Python_'s standard library is used to
73 read them. From its documentation:
75 The configuration file consists of sections, lead by a "[section]"
76 header and followed by "name: value" entries, with continuations
77 in the style of `RFC 822`_; "name=value" is also accepted. Note
78 that leading whitespace is removed from values. ... Lines
79 beginning with "#" or ";" are ignored and may be used to provide
82 .. Note:: No format string interpolation is done.
84 Configuration file entry names correspond to internal runtime
85 settings. Underscores ("_") and hyphens ("-") can be used
86 interchangably in entry names; hyphens are automatically converted to
89 For on/off switch settings (_`booleans`), the following values are
92 :On: "true", "yes", "on", "1"
93 :Off: "false", "no", "off", "0", "" (no value)
97 List values can be comma- or colon-delimited.
99 strip_classes_, strip_elements_with_classes_, stylesheet, and
100 stylesheet_path use the comma as delimiter,
101 whitespace around list values is stripped. ::
103 strip-classes: ham,eggs,
104 strip-elements-with-classes: sugar, salt, flour
105 stylesheet: html4css1.css,
107 style with spaces.css
108 stylesheet-path: ../styles/my.css, ../styles/funny.css
110 expose_internals_, ignore_ and prune_ use the colon as delimiter and do not
113 expose_internals: b:c:d
119 This is the contents of the ``tools/docutils.conf`` configuration file
120 supplied with Docutils::
122 # These entries affect all processing:
125 datestamp: %Y-%m-%d %H:%M UTC
128 # These entries affect HTML output:
130 # Required for docutils-update, the website build system:
131 stylesheet-path: ../docutils/writers/html4css1/html4css1.css
135 Individual configuration sections and settings are described in the
139 -------------------------------------
140 Configuration File Sections & Entries
141 -------------------------------------
143 Below are the Docutils runtime settings, listed by config file
144 section. Any setting may be specified in any section, but only
145 settings from active sections will be used. Sections correspond to
146 Docutils components (module name or alias; section names are always in
147 lowercase letters). Each `Docutils application`_ uses a specific set
148 of components; corresponding configuration file sections are applied
149 when the application is used. Configuration sections are applied in
150 general-to-specific order, as follows:
154 2. `[parsers]`_, parser dependencies, and the section specific to the
155 Parser used ("[... parser]"). Currently, only `[restructuredtext
156 parser]`_ is applicable.
158 3. `[readers]`_, reader dependencies, and the section specific to the
159 Reader used ("[... reader]"). For example, `[pep reader]`_ depends
160 on `[standalone reader]`_.
162 4. `[writers]`_, writer family ("[... writers]"; if applicable),
163 writer dependencies, and the section specific to the writer used
164 ("[... writer]"). For example, `[pep_html writer]`_ depends
165 on `[html4css1 writer]`_.
167 5. `[applications]`_, application dependencies, and the section
168 specific to the Application (front-end tool) in use
169 ("[... application]").
171 Since any setting may be specified in any section, this ordering
172 allows component- or application-specific overrides of earlier
173 settings. For example, there may be Reader-specific overrides of
174 general settings; Writer-specific overrides of Parser settings;
175 Application-specific overrides of Writer settings; and so on.
177 If multiple configuration files are applicable, the process is
178 completed (all sections are applied in the order given) for each one
179 before going on to the next. For example, a "[pep_html writer]
180 stylesheet" setting in an earlier configuration file would be
181 overridden by an "[html4css1 writer] stylesheet" setting in a later
184 Some knowledge of Python_ is assumed for some attributes.
187 http://www.python.org/doc/current/lib/module-ConfigParser.html
188 .. _Python: http://www.python.org/
189 .. _RFC 822: http://www.rfc-editor.org/rfc/rfc822.txt
190 .. _Docutils application: tools.html
196 Settings in the "[general]" section are always applied.
201 Prefix prepended to all auto-generated `identifier keys` generated within
202 the document, after id_prefix_. Ensure the value conforms to the
203 restrictions on identifiers in the output format, as it is not subjected to
204 the `identifier normalization`_.
206 A trailing "%" is replaced with the tag name (new in Docutils 0.16).
208 Default: "id" (`will change to "%" in future`__).
209 Options: ``--auto-id-prefix`` (hidden, intended mainly for programmatic use).
211 .. _identifier normalization:
212 ../ref/rst/directives.html#identifier-normalization
213 __ ../../RELEASE-NOTES.html#future-changes
218 Include a time/datestamp in the document footer. Contains a
219 format string for Python's ``time.strftime``. See the `time
220 module documentation`__.
223 Options: ``--date, -d, --time, -t, --no-datestamp``.
225 Configuration file entry examples::
227 # Equivalent to --date command-line option, results in
228 # ISO 8601 extended format datestamp, e.g. "2001-12-21":
231 # Equivalent to --time command-line option, results in
232 # date/timestamp like "2001-12-21 18:43 UTC":
233 datestamp: %Y-%m-%d %H:%M UTC
235 # Disables datestamp; equivalent to --no-datestamp:
238 __ http://www.python.org/doc/current/lib/module-time.html
243 Report debug-level system messages.
245 Default: don't (None). Options: ``--debug, --no-debug``.
250 At the end of processing, write all internal attributes of the
251 document (``document.__dict__``) to stderr.
253 Default: don't (None).
254 Options: ``--dump-internals`` (hidden, for development use only).
259 At the end of processing, write the pseudo-XML representation of
260 the document to stderr.
262 Default: don't (None).
263 Options: ``--dump-pseudo-xml`` (hidden, for development use only).
268 At the end of processing, write all Docutils settings to stderr.
270 Default: don't (None).
271 Options: ``--dump-settings`` (hidden, for development use only).
276 At the end of processing, write a list of all transforms applied
277 to the document to stderr.
279 Default: don't (None).
280 Options: ``--dump-transforms`` (hidden, for development use only).
285 The text encoding for error output.
287 Default: "ascii". Options: ``--error-encoding, -e``.
289 error_encoding_error_handler
290 ----------------------------
292 The error handler for unencodable characters in error output. See
293 output_encoding_error_handler_ for acceptable values.
295 Default: "backslashreplace"
296 Options: ``--error-encoding-error-handler, --error-encoding, -e``.
301 A system message level threshold; non-halting system messages at
302 or above this level will produce a non-zero exit status at normal
303 exit. Exit status is the maximum system message level plus 10 (11
306 Default: disabled (5). Options: ``--exit-status``.
311 List_ of internal attribues to expose as external attributes (with
312 "internal:" namespace prefix). To specify multiple attributes in
313 configuration files, use colons to separate names; on the command
314 line, the option may be used more than once.
316 Default: don't (None).
317 Options: ``--expose-internal-attribute`` (hidden, for development use only).
322 Enable or disable backlinks from footnotes_ and citations_ to their
325 Default: enabled (True).
326 Options: ``--footnote-backlinks, --no-footnote-backlinks``.
331 Include a "Generated by Docutils" credit and link in the document footer.
333 Default: off (None). Options: ``--generator, -g, --no-generator``.
338 The threshold at or above which system messages are converted to
339 exceptions, halting execution immediately. If `traceback`_ is set, the
340 exception will propagate; otherwise, Docutils will exit.
342 Default: severe (4). Options: ``--halt, --strict``.
347 Prefix prepended to all identifier keys generated within the document.
348 Ensure the value conforms to the restrictions on identifiers in the output
349 format, as it is not subjected to the `identifier normalization`_.
350 See also auto_id_prefix_.
353 Options: ``--id-prefix`` (hidden, intended mainly for programmatic use).
358 The text encoding for input.
360 Default: auto-detect (None). Options: ``--input-encoding, -i``.
362 input_encoding_error_handler
363 ----------------------------
365 The error handler for undecodable characters in the input. Acceptable
369 Raise an exception in case of an encoding error.
371 Replace malformed data with the official Unicode replacement
374 Ignore malformed data and continue without further notice.
376 Acceptable values are the same as for the "error" parameter of
377 Python's ``unicode`` function; other values may be defined in
378 applications or in future versions of Python.
381 Options: ``--input-encoding-error-handler, --input-encoding, -i``.
386 Case-insensitive `language tag`_ as defined in `BCP 47`_.
388 Sets the document language, also used for localized directive and
389 role names as well as Docutils-generated text.
391 A typical language identifier consists of a 2-letter language code
392 from `ISO 639`_ (3-letter codes can be used if no 2-letter code
393 exists). The language identifier can have an optional subtag,
394 typically for variations based on country (from `ISO 3166`_
395 2-letter country codes). Avoid subtags except where they add
396 useful distinguishing information. Examples of language tags
397 include "fr", "en-GB", "pt-br" (the same as "pt-BR"), and
398 "de-1901" (German with pre-1996 spelling).
400 The language of document parts can be specified with a
401 "language-<language tag>" `class attribute`_, e.g.
402 ``.. class:: language-el-polyton`` for a quote in polytonic Greek.
404 Default: English ("en"). Options: ``--language, -l``.
406 .. _class attribute: ../ref/doctree.html#classes
411 The text encoding for output.
413 Default: "UTF-8". Options: ``--output-encoding, -o``.
415 output_encoding_error_handler
416 -----------------------------
418 The error handler for unencodable characters in the output. Acceptable
422 Raise an exception in case of an encoding error.
424 Replace malformed data with a suitable replacement marker,
427 Ignore malformed data and continue without further notice.
429 Replace with the appropriate XML character reference, such as
432 Replace with backslashed escape sequences, such as "``\u2020``".
434 Acceptable values are the same as for the "error" parameter of
435 Python's ``encode`` string method; other values may be defined in
436 applications or in future versions of Python.
439 Options: ``--output-encoding-error-handler, --output-encoding, -o``.
444 Path to a file where Docutils will write a list of files that were
445 required to generate the output, e.g. included files or embedded
446 stylesheets [#dependencies]_. [#pwd]_ The format is one path per
447 line with forward slashes as separator, the encoding is ``utf8``.
449 Set to ``-`` in order to write dependencies to stdout.
451 This option is particularly useful in conjunction with programs like
452 ``make`` using ``Makefile`` rules like::
454 ham.html: ham.txt $(shell cat hamdeps.txt)
455 rst2html.py --record-dependencies=hamdeps.txt ham.txt ham.html
457 If the filesystem encoding differs from utf8, replace the ``cat``
458 command with a call to a converter, e.g.::
460 $(shell iconv -f utf8 -t latin1 hamdeps.txt)
462 Default: None. Option: ``--record-dependencies``.
467 Report system messages at or higher than <level>:
475 Default: warning (2).
476 Options: ``--report, -r, --verbose, -v, --quiet, -q``.
481 Enable or disable automatic section numbering by Docutils
482 (docutils.transforms.parts.SectNum) associated with the `sectnum
485 If disabled, section numbers might be added to the output by the
486 renderer (e.g. by LaTeX or via a CSS style definition).
488 Default: enabled (True).
489 Options: ``--section-numbering``, ``--no-section-numbering``.
491 .. _sectnum directive: ../ref/rst/directives.html#sectnum
496 Include a "View document source" link in the document footer. URL will
497 be relative to the destination.
499 Default: don't (None).
500 Options: ``--source-link, -s, --no-source-link``.
505 An explicit URL for a "View document source" link, used verbatim.
507 Default: compute if source_link (None).
508 Options: ``--source-url, --no-source-link``.
513 When processing a document tree with the Visitor pattern, raise an
514 error if a writer does not support a node type listed as optional. For
515 transitional development use.
517 Default: disabled (None).
518 Option: ``--strict-visitor`` (hidden, for development use only).
523 Comma-separated list_ of "classes" attribute values to remove from all
524 elements in the document tree. The command line option may be used more
527 .. WARNING:: Potentially dangerous; use with caution.
529 Default: disabled (None). Option: ``--strip-class``.
534 Enable the removal of comment elements from the document tree.
536 Default: disabled (None).
537 Options: ``--strip-comments``, ``--leave-comments``.
539 strip_elements_with_classes
540 ---------------------------
542 Comma-separated list_ of "classes" attribute values;
543 matching elements are removed from the document tree.
544 The command line option may be used more than once.
546 .. WARNING:: Potentially dangerous; use with caution.
548 Default: disabled (None). Option: ``--strip-element-with-class``.
553 The `document title`_ as metadata, which does not become part of the
554 document body. It overrides a document-supplied title. For
555 example, in HTML output the metadata document title appears in the
556 title bar of the browser window.
558 Default: none. Option: ``--title``.
560 .. _document title: ../ref/rst/restructuredtext.html#document-title
565 Enable backlinks from section titles to table of contents entries
566 ("entry"), to the top of the TOC ("top"), or disable ("none").
569 Options: ``--toc-entry-backlinks, --toc-top-backlinks, --no-toc-backlinks``.
574 Enable Python tracebacks when halt-level system messages and other
575 exceptions occur. Useful for debugging, and essential for issue
576 reports. Exceptions are allowed to propagate, instead of being
577 caught and reported (in a user-friendly way) by Docutils.
579 Default: disabled (None) unless Docutils is run programmatically
580 using the `Publisher Interface`_.
581 Options: ``--traceback, --no-traceback``.
583 .. _Publisher Interface: ../api/publisher.html
588 Path to a file for the output of system messages (warnings). [#pwd]_
590 Default: stderr (None). Options: ``--warnings``.
596 Docutils currently supports only one parser, for reStructuredText.
599 [restructuredtext parser]
600 -------------------------
602 character_level_inline_markup
603 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
605 Experimental setting to relax the `inline markup recognition rules`_
606 requiring whitespace or punctuation around inline markup.
608 Allows character level inline markup without escaped whithespace and is
609 especially suited for langauges that do not use whitespace to separate words
610 (e.g. Japanese, Chinese).
612 .. WARNING:: Potentially dangerous; use with caution.
614 When changing this setting to "True", inline markup charactes in
615 URLs, names and formulas must be escaped to prevent recognition and
616 possible errors. Examples::
618 http://rST_for_all.html (hyperlinks to rST_ and for_)
619 x_2, inline_markup (hyperlinks to x_ and inline_)
620 2*x (starts emphasised text)
621 a|b (starts a substitution reference)
623 Default: disabled (False).
624 Options: ``--character-level-inline-markup, --word-level-inline-markup``.
626 New in Docutils 0.13.
628 file_insertion_enabled
629 ~~~~~~~~~~~~~~~~~~~~~~
631 Enable or disable directives that insert the contents of external
632 files, such as the "include_" & "raw_". A "warning" system
633 message (including the directive text) is inserted instead. (See
634 also raw_enabled_ for another security-relevant setting.)
636 Default: enabled (True).
637 Options: ``--file-insertion-enabled, --no-file-insertion``.
639 .. _include: ../ref/rst/directives.html#include
640 .. _raw: ../ref/rst/directives.html#raw
645 Maximal number of characters in an input line or `substitution`_
646 definition. To prevent extraordinary high processing times or memory
647 usage for certain input constructs, a "warning" system message is
651 Option: ``--line-length-limit``
653 New in Docutils 0.17.
655 .. _substitution: ../ref/rst/directives.html#substitution
660 Recognize and link to standalone PEP references (like "PEP 258").
662 Default: disabled (None); enabled (True) in PEP Reader.
663 Options: ``--pep-references``.
667 Base URL for PEP references.
669 Default: "http://www.python.org/peps/".
670 Option: ``--pep-base-url``.
672 pep_file_url_template
673 ~~~~~~~~~~~~~~~~~~~~~
675 Template for PEP file part of URL, interpolated with the PEP
676 number and appended to pep_base_url_.
678 Default: "pep-%04d". Option: ``--pep-file-url``.
683 Enable or disable the "raw_" directive. A "warning" system message
684 (including the directive text) is inserted instead. See also
685 file_insertion_enabled_ for another security-relevant setting.
687 Default: enabled (True). Options: ``--raw-enabled, --no-raw``.
692 Recognize and link to standalone RFC references (like "RFC 822").
694 Default: disabled (None); enabled (True) in PEP Reader.
695 Options: ``--rfc-references``.
700 Base URL for RFC references.
702 Default: "http://www.faqs.org/rfcs/". Option: ``--rfc-base-url``.
707 Activate the experimental SmartQuotes_ transform to
708 change straight quotation marks to typographic form. `Quote characters`_
709 are selected according to the language of the current block element (see
710 language_code_, smartquotes_locales_, and the `pre-defined quote sets`__).
712 Also changes consecutive runs of hyphen-minus and full stops (``---``,
713 ``--``, ``...``) to em-dash, en-dash, and ellipsis Unicode characters
721 alt (or "alternative")
722 Use alternative quote set (if defined for the language).
724 Default: "no". Option: ``--smart-quotes``.
726 New in Docutils 0.10.
728 .. _SmartQuotes: smartquotes.html
729 __ smartquotes.html#localization
730 .. _quote characters:
731 http://en.wikipedia.org/wiki/Non-English_usage_of_quotation_marks
737 Typographical quotes used by the SmartQuotes_ transform.
739 A comma-separated list_ with language tag and a set of four quotes (primary
740 open/close, secondary open/close)smartquotes_locales. (If more than one
741 character shall be used for a quote (e.g. padding in French quotes), a
742 colon-separated list may be used.)
745 Ensure a correct leading apostrophe in ``'s Gravenhage`` in Dutch (at the
746 cost of incorrect opening single quotes) and set French quotes to double
747 and single guillemets with inner padding::
749 smartquote-locales: nl: „”’’,
752 Default: None. Option: ``--smartquotes-locales``.
754 New in Docutils 0.14.
759 Token type names used by Pygments_ when parsing contents of the code_
765 Use hierarchy of long token type names.
767 Use short token type names. (For use with
768 `Pygments-generated stylesheets`_.)
770 No code parsing. Use this to avoid the "Pygments not
771 found" warning when Pygments is not installed.
773 Default: "long". Option: ``--syntax-highlight``.
777 .. _Pygments: http://pygments.org/
778 .. _code: ../ref/rst/directives.html#code
779 .. _Pygments-generated stylesheets:
780 http://pygments.org/docs/cmdline/#generating-styles
785 Number of spaces for hard tab expansion.
787 Default: 8. Options: ``--tab-width``.
789 trim_footnote_reference_space
790 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
792 Remove spaces before `footnote references`_. [#]_
794 Default: don't (None) rsp. depending on the writer-specific
795 `footnote_references setting`_. [#footnote_space]_
797 Options: ``--trim-footnote-reference-space, --leave-footnote-reference-space``.
799 .. [#] The footnote space is trimmed if the reference style is
800 "superscript", and it is left if the reference style is "brackets".
814 Enable or disable the `bibliographic field list`_ transform
815 (docutils.transforms.frontmatter.DocInfo).
817 Default: enabled (True). Options: ``--no-doc-info``.
822 Enable or disable the promotion of a lone top-level section title
823 to `document title`_ (and subsequent section title to document
824 subtitle promotion; docutils.transforms.frontmatter.DocTitle).
826 Default: enabled (True). Options: ``--no-doc-title``.
831 Enable or disable the promotion of the title of a lone subsection
832 to a subtitle (docutils.transforms.frontmatter.SectSubTitle).
834 Default: disabled (False). Options: ``--section-subtitles,
835 --no-section-subtitles``.
841 The `pep_references`_ and `rfc_references`_ settings
842 (`[restructuredtext parser]`_) are set on by default.
854 [docutils_xml writer]
855 ---------------------
859 * In Python versions older than 2.7.3 and 3.2.3, the newlines_ and
860 indents_ options may adversely affect whitespace; use them only for
861 reading convenience (see http://bugs.python.org/issue4147).
863 * The XML declaration carries text encoding information. If the encoding
864 is not UTF-8 or ASCII and the XML declaration is missing, standard
865 tools may be unable to read the generated XML.
870 Generate XML with a DOCTYPE declaration.
872 Default: do (True). Options: ``--no-doctype``.
877 Generate XML with indents and newlines.
879 Default: don't (None). Options: ``--indents``.
884 Generate XML with newlines before and after tags.
886 Default: don't (None). Options: ``--newlines``.
889 .. _xml_declaration [docutils_xml writer]:
894 Generate XML with an XML declaration.
895 See also `xml_declaration [html writers]`_.
897 Default: do (True). Options: ``--no-xml-declaration``.
903 .. _attribution [html writers]:
908 Format for `block quote`_ attributions: one of "dash" (em-dash
909 prefix), "parentheses"/"parens", or "none".
910 See also `attribution [latex writers]`_.
912 Default: "dash". Options: ``--attribution``.
915 cloak_email_addresses
916 ~~~~~~~~~~~~~~~~~~~~~
918 Scramble email addresses to confuse harvesters. In the reference
919 URI, the "@" will be replaced by %-escapes (as of RFC 1738). In
920 the visible text (link text) of an email reference, the "@" and
921 all periods (".") will be surrounded by ``<span>`` tags.
922 Furthermore, HTML entities are used to encode these characters in
923 order to further complicate decoding the email address. For
924 example, "abc@example.org" will be output as::
926 <a class="reference" href="mailto:abc%40example.org">
927 abc<span>@</span>example<span>.</span>org</a>
929 .. Note:: While cloaking email addresses will have little to no
930 impact on the rendering and usability of email links in most
931 browsers, some browsers (e.g. the ``links`` browser) may decode
932 cloaked email addresses incorrectly.
934 Default: don't cloak (None). Option: ``--cloak-email-addresses``.
939 Remove extra vertical whitespace between items of bullet lists and
940 enumerated lists, when list items are all "simple" (i.e., items
941 each contain one paragraph and/or one "simple" sublist only). The
942 behaviour can be specified directly via "class" attributes (values
943 "compact" and "open") in the document.
945 Default: enabled (True).
946 Options: ``--compact-lists, --no-compact-lists``.
951 Remove extra vertical whitespace between items of `field lists`_ that
952 are "simple" (i.e., all field bodies each contain at most one
953 paragraph). The behaviour can be specified directly via "class"
954 attributes (values "compact" and "open") in the document.
956 Default: enabled (True).
957 Options: ``--compact-field-lists, --no-compact-field-lists``.
960 .. _embed_stylesheet [html writers]:
965 Embed the stylesheet in the output HTML file. The stylesheet file
966 must specified by the stylesheet_path_ setting and must be
967 accessible during processing.
968 See also `embed_stylesheet [latex writers]`_.
970 Default: enabled. Options: ``--embed-stylesheet,
974 .. _footnote_references setting:
975 .. _footnote_references [html writers]:
980 Format for `footnote references`_, one of "superscript" or "brackets".
981 See also `footnote_references [latex writers]`_.
983 Overrides [#override]_ trim_footnote_reference_space_, if
984 applicable. [#footnote_space]_
986 Default: "brackets". Option: ``--footnote-references``.
991 The initial level for header elements. This does not affect the
992 document title & subtitle; see doctitle_xform_.
994 Default: writer dependent (see `[html4css1 writer]`_, `[html5 writer]`_,
995 `[pep_html writer]`_).
996 Option: ``--initial-header-level``.
1002 The format of mathematical content (`math directive`_ and role) in
1003 the output document. Supported values are (case insensitive):
1006 Format math in standard HTML enhanced by CSS rules.
1007 Requires the ``math.css`` stylesheet (in the system
1008 `stylesheet directory <stylesheet_dirs [html writers]_>`__)
1010 A `stylesheet_path <stylesheet_path [html writers]_>`__
1011 can be appended after whitespace, the specified
1012 stylesheet(s) will only be referenced or embedded, if required
1013 (i.e. if there is mathematical content in the document).
1016 Format math for display with MathJax_, a JavaScript-based math rendering
1020 Works across multiple browsers and platforms.
1022 Large set of `supported LaTeX math commands and constructs`__
1024 __ http://docs.mathjax.org/en/latest/tex.html#supported-latex-commands
1027 Rendering requires JavaScript and an Internet connection or local
1028 MathJax installation.
1030 A URL pointing to a MathJax library should be appended after whitespace.
1031 A warning is given if this is missing.
1033 * It is recommended to install__ the MathJax library on the same
1034 server as the rest of the deployed site files.
1036 __ https://www.mathjax.org/#installnow
1038 Example: Install the library at the top level of the web
1039 server’s hierarchy in the directory ``MathJax`` and set::
1041 math-output: mathjax /MathJax/MathJax.js
1043 * The easiest way to use MathJax is to link directly to a public
1044 installation. In that case, there is no need to install MathJax locally.
1046 Downside: Downloads JavaScript code from a third-party site --- opens
1047 the door to cross-site scripting attacs!
1049 Example: MathJax `getting started`__ documentation uses::
1051 math-output: mathjax
1052 https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
1054 See https://www.jsdelivr.com/ for details and terms of use.
1056 __ https://www.mathjax.org/#gettingstarted
1058 * Use a local MathJax installation on the *client* machine, e.g.::
1060 math-output: MathJax file:/usr/share/javascript/mathjax/MathJax.js
1062 This is the fallback if no URL is specified.
1065 Embed math content as presentational MathML_.
1068 The W3C recommendation for math on the web.
1070 Self-contained documents (no JavaScript, no external downloads).
1073 Docutil's latex2mathml converter supports only a small
1074 subset of LaTeX syntax.
1076 With the "html4css1" writer, the resulting HTML document does
1077 not validate, as there is no DTD for `MathML + XHTML Transitional`.
1078 However, MathML-enabled browsers will render it fine.
1080 An external converter can be appended after whitespace, e.g.,
1081 ``--math-output="MathML latexml"``:
1084 Fast conversion, support for many symbols and environments, but no
1085 "align" (or other equation-aligning) environment. (C++)
1088 Comprehensive macro support but very slow. (Perl)
1091 No "matrix", "align" and "cases" environments. Support may be removed.
1094 Include literal LaTeX code.
1096 The failsave fallback.
1098 Default: HTML math.css. Option: ``--math-output``.
1100 New in Docutils 0.8.
1102 .. _math directive: ../ref/rst/directives.html#math
1103 .. _MathJax: http://www.mathjax.org/
1104 .. _MathPlayer: http://www.dessci.com/en/products/mathplayer/
1105 .. _MathML: http://www.w3.org/TR/MathML/
1106 .. _blahtexml: http://gva.noekeon.org/blahtexml/
1107 .. _LaTeXML: http://dlmf.nist.gov/LaTeXML/
1108 .. _TtM: http://hutchinson.belmont.ma.us/tth/mml/
1111 .. _stylesheet [html writers]:
1116 A comma-separated list of CSS stylesheet URLs, used verbatim.
1117 See also `stylesheet [latex writers]`_.
1119 Overrides also stylesheet_path_. [#override]_
1121 Default: None. Options: ``--stylesheet``.
1124 .. _stylesheet_dirs [html writers]:
1129 A comma-separated list of directories where stylesheets can be found.
1130 Used by the stylesheet_path_ setting when expanding relative path arguments.
1132 Note: This setting defines a "search path" (similar to the PATH variable for
1133 executables). However, the term "path" is already used in the
1134 stylesheet_path_ setting with the meaning of a file location.
1137 Default: the working directory of the process at launch and the directory
1138 with default stylesheet files (writer and installation specific).
1139 Use the ``--help`` option to get the exact value.
1140 Option: ``--stylesheet-directories``.
1143 .. _stylesheet_path:
1144 .. _stylesheet_path [html writers]:
1149 A comma-separated list of paths to CSS stylesheets. Relative paths are
1150 expanded if a matching file is found in the stylesheet_dirs__.
1151 If embed_stylesheet__ is False, paths are rewritten relative to the
1153 See also `stylesheet_path [latex writers]`_.
1155 Also overrides "stylesheet". [#override]_
1156 Pass an empty string (to either "stylesheet" or "stylesheet_path") to
1157 deactivate stylesheet inclusion.
1159 Default: writer dependent (see `[html4css1 writer]`_, `[html5 writer]`_,
1160 `[pep_html writer]`_).
1161 Options: ``--stylesheet-path``.
1163 __ `embed_stylesheet [html writers]`_
1164 __ `stylesheet_dirs [html writers]`_
1167 .. _table_style [html writers]:
1172 Class value(s) added to all tables_.
1173 See also `table_style [latex writers]`_.
1175 The default CSS sylesheet defines:
1178 No borders around the table.
1181 Lines above and below the table and a thin line after the head.
1183 align-left, align-center, align-right
1187 Delegate the determination of table column widths to the backend
1188 (leave out the ``<colgroup>`` column specification).
1189 See also the "widths" option of the `table directive`_.
1192 Place the table caption below the table
1193 (only with the `HTML5 writer`_, new in 0.17).
1195 Default: "". Option: ``--table-style``.
1197 .. _table directive: ../ref/rst/directives.html#table
1200 .. _template [html writers]:
1205 Path to template file, which must be encoded in UTF-8. [#pwd]_
1206 See also `template [latex writers]`_.
1208 Default: "template.txt" in the docutils/writers/html4css1/
1209 directory (installed automatically; for the exact machine-specific
1210 path, use the ``--help`` option). Options: ``--template``.
1213 .. _xml_declaration [html writers]:
1218 Generate XML with an XML declaration.
1219 See also `xml_declaration [docutils_xml writer]`_.
1221 .. Caution:: The XML declaration carries text encoding information. If the
1222 encoding is not UTF-8 or ASCII and the XML declaration is missing,
1223 standard tools may be unable to read the generated XHTML.
1225 Default: do (True). Options: ``--no-xml-declaration``.
1232 The `HTML4/CSS1 Writer`_ generates output that conforms to the
1233 `XHTML 1 Transitional`_ specification.
1234 It shares all settings defined in the `[html writers]`_
1235 `configuration section`_.
1238 Writer specific defaults:
1240 `initial_header_level`_
1243 `stylesheet_path <stylesheet_path [html writers]_>`__:
1246 .. _HTML4/CSS1 Writer: html.html#html4css1
1247 .. _XHTML 1 Transitional: http://www.w3.org/TR/xhtml1/
1253 The maximum width (in characters) for one-column `field names`_. Longer
1254 field names will span an entire row of the table used to render the field
1255 list. 0 indicates "no limit". See also option_limit_.
1257 Default: 14 (i.e. 14 characters). Option: ``--field-name-limit``.
1263 The maximum width (in characters) for options in `option lists`_.
1264 Longer options will span an entire row of the table used to render
1265 the option list. 0 indicates "no limit".
1266 See also field_name_limit_.
1268 Default: 14 (i.e. 14 characters). Option: ``--option-limit``.
1274 The `HTML5 Writer`_ generates valid XML that is compatible with `HTML5`_.
1275 It shares all settings defined in the `[html writers]`_
1276 `configuration section`_.
1278 Writer specific defaults:
1280 `initial_header_level`_
1281 2 (for "<h2>", cf. the `HTML5.3 Working Draft`__)
1283 `stylesheet_path <stylesheet_path [html writers]_>`__:
1284 "minimal.css,plain.css"
1286 New in Docutils 0.13.
1288 __ https://www.w3.org/TR/html53/sections.html#the-h1-h2-h3-h4-h5-and-h6-elements
1289 .. _HTML5 Writer: html.html#html5-polyglot
1290 .. _HTML5: http://www.w3.org/TR/html5/
1296 Embed images in the output HTML file. If the image can be read from
1297 the local file system and its MIME type can be determined, it is
1298 base64_ encoded and included as a `data URI`_.
1300 Default: disabled (False).
1301 Options: ``--embed-images``, ``--link-images``
1303 New in Docutils 0.17.
1305 .. _base64: https://en.wikipedia.org/wiki/Base64
1306 .. _data URI: https://en.wikipedia.org/wiki/Data_URI_scheme
1312 The PEP/HTML Writer derives from the HTML4/CSS1 Writer, and shares
1313 all settings defined in the `[html writers]`_ and `[html4css1 writer]`_
1314 `configuration sections`_.
1316 Writer specific defaults:
1318 `initial_header_level`_
1321 `stylesheet_path <stylesheet_path [html writers]_>`__:
1324 `template <template [html writers]_>`__:
1325 ``docutils/writers/pep_html/template.txt`` in the installation
1326 directory. For the exact machine-specific path, use the ``--help``
1331 Do not use a random banner image. Mainly used to get predictable
1332 results when testing.
1334 Default: random enabled (None). Options: ``--no-random`` (hidden).
1339 Home URL prefix for PEPs.
1341 Default: current directory ("."). Options: ``--pep-home``.
1347 Default: parent directory (".."). Options: ``--python-home``.
1353 The S5/HTML Writer derives from the HTML4/CSS1 Writer, and shares
1354 all settings defined in the `[html writers]`_ and `[html4css1 writer]`_
1355 `configuration sections`_.
1357 Writer specific defaults:
1360 disable compact lists.
1363 ``docutils/writers/s5_html/template.txt`` in the installation
1364 directory. For the exact machine-specific path, use the ``--help``
1367 __ `template [html writers]`_
1373 Auto-hide the presentation controls in slideshow mode, or or keep
1374 them visible at all times.
1376 Default: auto-hide (True). Options: ``--hidden-controls``,
1377 ``--visible-controls``.
1382 Enable or disable the current slide indicator ("1/15").
1384 Default: disabled (None). Options: ``--current-slide``,
1385 ``--no-current-slide``.
1387 overwrite_theme_files
1388 """""""""""""""""""""
1390 Allow or prevent the overwriting of existing theme files in the
1391 ``ui/<theme>`` directory. This has no effect if "theme_url_" is
1394 Default: keep existing theme files (None). Options:
1395 ``--keep-theme-files``, ``--overwrite-theme-files``.
1400 Name of an installed S5 theme, to be copied into a ``ui/<theme>``
1401 subdirectory, beside the destination file (output HTML). Note
1402 that existing theme files will not be overwritten; the existing
1403 theme directory must be deleted manually.
1404 Also overrides the "theme_url_" setting. [#override]_
1406 Default: "default". Option: ``--theme``.
1411 The URL of an S5 theme directory. The destination file (output
1412 HTML) will link to this theme; nothing will be copied. Also overrides
1413 the "theme_" setting. [#override]_
1415 Default: None. Option: ``--theme-url``.
1420 The initial view mode, either "slideshow" or "outline".
1422 Default: "slidewhow". Option: ``--view-mode``.
1424 .. ------------------------------------------------------------
1429 Common settings for the `LaTeX writers`_
1430 `[latex2e writer]`_ and `[xetex writer]`_.
1432 .. _LaTeX writers: latex.html
1435 .. _attribution [latex writers]:
1440 See `attribution [html writers]`_.
1442 compound_enumerators
1443 ~~~~~~~~~~~~~~~~~~~~
1445 Enable or disable compound enumerators for nested `enumerated lists`_
1448 Default: disabled (None).
1449 Options: ``--compound-enumerators``, ``--no-compound-enumerators``.
1454 Specify LaTeX documentclass.
1456 Default: "article". Option: ``--documentclass``.
1461 Specify document options. Multiple options can be given, separated by
1464 Default: "a4paper". Option: ``--documentoptions``.
1469 Use the Docutils-specific macros ``\DUfootnote`` and
1470 ``\DUfootnotetext`` for footnotes_.
1472 TODO: The alternative, "use_latex_footnotes" is not implemented yet.
1474 Default: on. Option: ``--docutils-footnotes``.
1477 .. _embed_stylesheet [latex writers]:
1482 Embed the stylesheet(s) in the header of the output file. The
1483 stylesheets must be accessible during processing. Currently, this
1484 fails if the file is not available via the given path (i.e. the
1485 file is *not* searched in the `TeX input path`_).
1486 See also `embed_stylesheet [html writers]`_.
1488 Default: off. Options: ``--embed-stylesheet, --link-stylesheet``.
1491 .. _footnote_references [latex writers]:
1496 Format for `footnote references`_: one of "superscript" or "brackets".
1497 See also `footnote_references [html writers]`_.
1499 Overrides [#override]_ trim_footnote_reference_space_, if
1500 applicable. [#footnote_space]_
1502 Default: "superscript". Option: ``--footnote-references``.
1508 LaTeX graphicx package option.
1510 Possible values are "dvips", "pdftex", "dvipdfmx".
1512 Default: "". Option: ``--graphicx-option``.
1517 Color of any hyperlinks embedded in text.
1519 * "0" or "false" disable coloring of links. (Links will be marked
1520 by red boxes that are not printed),
1521 * "black" results in “invisible“ links,
1523 Set hyperref_options_ to "draft" to completely disable hyperlinking.
1525 Default: "blue". Option: ``--hyperlink-color``.
1530 Options for the `hyperref TeX package`_. If hyperlink_color_ is
1531 not "false", the expansion of ::
1533 'colorlinks=true,linkcolor=%s,urlcolor=%s' % (
1534 hyperlink_color, self.hyperlink_color
1538 Default: "". Option: ``--hyperref-options``.
1540 .. _hyperref TeX package: http://tug.org/applications/hyperref/
1545 LaTeX code that will be inserted in the document preamble.
1546 Can be used to load packages with options or (re-) define LaTeX
1547 macros without writing a custom style file (new in Docutils 0.7).
1549 Default: writer dependent (see `[latex2e writer]`_, `[xetex writer]`_).
1550 Option: ``--latex-preamble``.
1553 legacy_class_functions
1554 ~~~~~~~~~~~~~~~~~~~~~~
1556 Use legacy functions ``\DUtitle`` and ``\DUadmonition`` with a
1557 comma-separated list of class values as optional argument. If `False`, class
1558 values are handled with wrappers and admonitions use the ``DUadmonition``
1559 environment. See `Generating LaTeX with Docutils`__ for details.
1561 Default: True (this will change to False in version 0.18).
1562 Options: ``--legacy-class-functions``, ``--new-class-functions``.
1564 New in Docutils 0.17.
1566 __ latex.html#classes
1571 When possible\ [#]_, use the specified environment for `literal blocks`_.
1573 Default: "" (quoting of whitespace and special chars).
1574 Option: ``--literal-block-env``.
1576 .. [#] A literal-block element may originate from a `parsed literal`_.
1577 A LaTeX verbatim environment is only usable it does not contain
1580 .. _parsed literal: ../ref/rst/directives.html#parsed-literal
1585 Per default the latex-writer puts the reference title into
1586 hyperreferences. Specify "ref*" or "pageref*" to get the section
1587 number or the page number.
1589 Default: "" (use hyperreferences). Option: ``--reference-label``.
1590 section_enumerator_separator
1591 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1593 The separator between section number prefix and enumerator for
1594 compound enumerated lists (see `compound_enumerators`_).
1596 Generally it isn't recommended to use both sub-sections and nested
1597 enumerated lists with compound enumerators. This setting avoids
1598 ambiguity in the situation where a section "1" has a list item
1599 enumerated "1.1", and subsection "1.1" has list item "1". With a
1600 separator of ".", these both would translate into a final compound
1601 enumerator of "1.1.1". With a separator of "-", we get the
1602 unambiguous "1-1.1" and "1.1-1".
1604 Default: "-". Option: ``--section-enumerator-separator``.
1608 section_prefix_for_enumerators
1609 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1611 Enable or disable section ("." subsection ...) prefixes for
1612 compound enumerators. This has no effect unless
1613 `compound_enumerators`_ are enabled.
1615 Default: disabled (None).
1616 Options: ``--section-prefix-for-enumerators``,
1617 ``--no-section-prefix-for-enumerators``.
1620 .. _stylesheet [latex writers]:
1625 A comma-separated list_ of style files.
1626 See also `stylesheet [html writers]`_.
1628 Overrides also stylesheet_path__. [#override]_
1630 If `embed_stylesheet`__ is False (default), the stylesheet files are
1631 referenced with ``\usepackage`` (extension ``.sty`` or no extension) or
1632 ``\input`` (any other extension).
1634 LaTeX will search the specified files in the `TeX input path`_.
1636 Default: no stylesheet (""). Option: ``--stylesheet``.
1638 __ `stylesheet_path [latex writers]`_
1639 __ `embed_stylesheet [latex writers]`_
1641 http://www.tex.ac.uk/cgi-bin/texfaq2html?label=what-TDS
1644 .. _stylesheet_dirs [latex writers]:
1649 A comma-separated list of directories where stylesheets can be found.
1650 Used by the stylesheet_path__ setting.
1652 Note: This setting defines a "search path" (similar to the PATH variable for
1653 executables). However, the term "path" is already used in the
1654 stylesheet_path__ setting with the meaning of a file location.
1657 __ `stylesheet_path [latex writers]`_
1659 Default: the working directory of the process at launch and the directory
1660 with default stylesheet files (writer and installation specific).
1661 Use the ``--help`` option to get the exact value.
1662 Option: ``--stylesheet-directories``.
1665 .. _stylesheet_path [latex writers]:
1670 A comma-separated list of style files. Relative paths are expanded if a
1671 matching file is found in the stylesheet_dirs__.
1672 If embed_stylesheet__ is False, paths are rewritten relative to the
1673 output file path. Run ``latex`` from the directory containing
1675 See also `stylesheet_path [html writers]`_.
1677 The stylesheet__ option is preferred for files in the `TeX input path`_.
1679 Also overrides stylesheet__. [#override]_
1681 Default: no stylesheet (""). Option: ``--stylesheet-path``.
1683 __ `stylesheet_dirs [latex writers]`_
1684 __ `embed_stylesheet [latex writers]`_
1686 __ `stylesheet [latex writers]`_
1689 .. _table_style [latex writers]:
1694 Specify the default style for tables_.
1695 See also `table_style [html writers]`_.
1700 Borders around all cells.
1702 A line above and below the table and one after the head.
1706 align-left, align-center, align-right
1709 colwidths-auto, colwidths-given
1710 Default value for column width determination by
1712 Override with the `table directive`_'s :widths: option.
1716 ``colwidths-auto`` is only suited for tables with simple cell content.
1718 LaTeX puts the content of auto-sized columns on one line (merging
1719 paragraphs) and may fail with complex content.
1721 Default: "standard". Option: ``--table-style``.
1724 .. _template [latex writers]:
1729 Path [#pwd]_ to template file, which must be encoded in UTF-8.
1730 See also `template [html writers]`_.
1732 Default: writer dependent (see `[latex2e writer]`_, `[xetex writer]`_).
1733 Options: ``--template``.
1738 Specify style and database for the experimental `BibTeX` support, for
1741 --use-bibtex=mystyle,mydb1,mydb2
1743 Default: "" (don't use BibTeX). Option ``--use-bibtex``.
1748 Use LaTeX abstract environment for the document's abstract_.
1750 Default: off. Options: ``--use-latex-abstract, --topic-abstract``.
1755 Use \cite for citations_ instead of a simulation with figure-floats.
1757 Default: off. Options: ``--use-latex-citations, --figure-citations``.
1762 Attach author and date to the `document title`_
1763 instead of the `bibliographic fields`_.
1765 Default: off. Options: ``--use-latex-docinfo, --use-docutils-docinfo``.
1770 To get pagenumbers in the `table of contents`_, it
1771 must be generated by LaTeX. Usually latex must be run twice to get
1774 Default: on. Options: ``--use-latex-toc, --use-docutils-toc``.
1779 Add parts on top of the section hierarchy.
1781 Default: don't (None). Option: ``--use-part-section``.
1786 The `LaTeX2e writer`_ generates a LaTeX source for compilation with 8-bit
1787 LaTeX (pdfTeX_). It shares all settings defined in the `[latex writers]`_
1788 `configuration section`_.
1790 .. _LaTeX2e writer: latex.html#latex2e-writer
1791 .. _pdfTeX: https://www.tug.org/applications/pdftex/
1792 .. _configuration section: `Configuration File Sections & Entries`_
1795 Writer Specific Defaults
1796 """"""""""""""""""""""""
1799 Load the "PDF standard fonts" (Times, Helvetica, Courier)::
1801 \usepackage{mathptmx} % Times
1802 \usepackage[scaled=.90]{helvet}
1803 \usepackage{courier}
1806 "default.tex" in the ``docutils/writers/latex2e/`` directory
1807 (installed automatically).
1809 __ `template [latex writers]`_
1815 Specify `LaTeX font encoding`_. Multiple options can be given, separated by
1816 commas. The last value becomes the document default.
1817 Possible values are "", "T1", "OT1", "LGR,T1" or any other combination of
1818 `LaTeX font encodings`_.
1820 Default: "T1". Option: ``--font-encoding``.
1822 .. _LaTeX font encoding: latex.html#font-encoding
1823 .. _LaTeX font encodings:
1824 http://mirror.ctan.org/macros/latex/doc/encguide.pdf
1829 The `XeTeX writer`_ generates a LaTeX source for compilation with `XeTeX or
1830 LuaTeX`_. It derives from the latex2e writer, and shares all settings
1831 defined in the `[latex writers]`_ and `[latex2e writer]`_ `configuration
1834 .. _XeTeX writer: latex.html#xetex-writer
1835 .. _XeTeX or LuaTeX: https://texfaq.org/FAQ-xetex-luatex
1836 .. _configuration sections: `Configuration File Sections & Entries`_
1838 Writer Specific Defaults
1839 """"""""""""""""""""""""
1842 Font setup for `Linux Libertine`_,::
1844 % Linux Libertine (free, wide coverage, not only for Linux)
1845 \setmainfont{Linux Libertine O}
1846 \setsansfont{Linux Biolinum O}
1847 \setmonofont[HyphenChar=None]{DejaVu Sans Mono}
1849 The optional argument ``HyphenChar=None`` to the monospace font
1850 prevents word hyphenation in literal text.
1852 .. _Linux Libertine: http://www.linuxlibertine.org/
1855 "xelatex.tex" in the ``docutils/writers/latex2e/`` directory
1856 (installed automatically).
1858 .. TODO: show full path with ``--help`` (like in the HTML writers)
1859 and add the following line:
1860 for the exact machine-specific path, use the ``--help`` option).
1862 __ `template [latex writers]`_
1868 The following command line options are specific to ``odtwriter``:
1873 Specify a stylesheet URL, used verbatim.
1875 Default: writers/odf_odt/styles.odt in the installation directory.
1880 Specify a configuration/mapping file relative to the current working
1881 directory for additional ODF options. In particular, this file may
1882 contain a section named "Formats" that maps default style names to names
1883 to be used in the resulting output file allowing for adhering to external
1884 standards. For more info and the format of the configuration/mapping
1885 file, see the `Odt Writer for Docutils`_ document.
1887 cloak-email-addresses
1888 ~~~~~~~~~~~~~~~~~~~~~
1890 Obfuscate email addresses to confuse harvesters while still
1891 keeping email links usable with standards-compliant browsers.
1893 no-cloak-email-addresses
1894 ~~~~~~~~~~~~~~~~~~~~~~~~
1895 Do not obfuscate email addresses.
1897 table-border-thickness
1898 ~~~~~~~~~~~~~~~~~~~~~~
1900 Specify the thickness of table borders in thousands of a cm.
1903 add-syntax-highlighting
1904 ~~~~~~~~~~~~~~~~~~~~~~~
1906 Add syntax highlighting in literal code blocks.
1908 no-syntax-highlighting
1909 ~~~~~~~~~~~~~~~~~~~~~~
1911 Do not add syntax highlighting in literal code blocks.
1917 Create sections for headers. (default)
1922 Do not create sections for headers.
1931 Do not create links. (default)
1936 Generate endnotes at end of document, not footnotes at bottom of page.
1941 Generate footnotes at bottom of page, not endnotes at end of
1947 Generate a bullet list table of contents, not an
1948 ODF/``oowriter`` table of contents.
1950 generate-oowriter-toc
1951 ~~~~~~~~~~~~~~~~~~~~~
1953 Generate an ODF/``oowriter`` table of contents, not a bullet
1954 list. (default) **Note:** ``odtwriter`` is not able to
1955 determine page numbers, so you will need to open the generated
1956 document in ``oowriter``, then right-click on the table of
1957 contents and select "Update" to insert page numbers.
1962 Specify the contents of a custom header line. For details about
1963 custom headers and about special field character sequences, see
1964 section "Custom header/footers: inserting page numbers, date,
1965 time, etc" in the `Odt Writer for Docutils`_ document for
1971 Specify the contents of a custom footer line. For details about
1972 custom footers and about special field character sequences, see
1973 section "Custom header/footers: inserting page numbers, date,
1974 time, etc" in the `Odt Writer for Docutils`_ document for
1977 .. _Odt Writer for Docutils: odt.html
1986 Pretty-print <#text> nodes.
1988 Default: False. Options: ``--detailled``.
1994 [buildhtml application]
1995 -----------------------
2000 Do not process files, show files that would be processed.
2002 Default: False. Options: ``--dry-run``.
2007 `HTML writer`_ version. One of "html", "html4", "html5".
2009 Default: "html" (use Docutils' default HTML writer).
2010 Options: ``--html-writer``
2012 .. _HTML writer: html.html
2017 List_ of wildcard (shell globing) patterns, specifying files to silently
2018 ignore. To specify multiple patterns, use colon-separated patterns (in
2019 configuration files or on the command line); on the command line, the
2020 option may also be used more than once.
2022 Default: None. Options: ``--ignore``.
2027 List_ of directories not to process. To specify multiple
2028 directories, use colon-separated paths (in configuration files or
2029 on the command line); on the command line, the option may also be
2030 used more than once.
2032 Default: ['.hg', '.bzr', '.git', '.svn', 'CVS']. Options:
2038 Recursively scan subdirectories, or ignore subdirectories.
2040 Default: recurse (True). Options: ``--recurse, --local``.
2045 Work silently (no progress messages). Independent of
2048 Default: show progress (None). Options: ``--silent``.
2051 [docfactory application]
2052 ------------------------
2063 These settings are only effective as command-line options; setting
2064 them in configuration files has no effect.
2069 Path to a configuration file to read (if it exists). [#pwd]_
2070 Settings may override defaults and earlier settings. The config
2071 file is processed immediately. Multiple ``--config`` options may
2072 be specified; each will be processed in turn.
2074 Filesystem path settings contained within the config file will be
2075 interpreted relative to the config file's location (*not* relative
2076 to the current working directory).
2078 Default: None. Options: ``--config``.
2084 These settings are for internal use only; setting them in
2085 configuration files has no effect, and there are no corresponding
2086 command-line options.
2091 List of paths of applied configuration files.
2093 Default: None. No command-line options.
2098 (``buildhtml.py`` front end.) List of paths to source
2099 directories, set from positional arguments.
2101 Default: current working directory (None). No command-line
2107 Prevent standard configuration files from being read. For
2108 programmatic use only.
2110 Default: config files enabled (None). No command-line options.
2115 Path to output destination, set from positional arguments.
2117 Default: stdout (None). No command-line options.
2122 Path to input source, set from positional arguments.
2124 Default: stdin (None). No command-line options.
2127 .. _language tag: http://www.w3.org/International/articles/language-tags/
2128 .. _BCP 47: http://www.rfc-editor.org/rfc/bcp/bcp47.txt
2129 .. _ISO 639: http://www.loc.gov/standards/iso639-2/php/English_list.php
2130 .. _ISO 3166: http://www.iso.ch/iso/en/prods-services/iso3166ma/
2131 02iso-3166-code-lists/index.html
2133 .. [#pwd] Path relative to the working directory of the process at
2136 .. [#override] The overridden setting will automatically be set to
2137 ``None`` for command-line options and config file settings. Client
2138 programs which specify defaults that override other settings must
2139 do the overriding explicitly, by assigning ``None`` to the other
2142 .. [#dependencies] Images are only added to the dependency list if the
2143 reStructuredText parser extracted image dimensions from the file.
2145 .. [#footnote_space] The overriding only happens if the parser supports
2146 the trim_footnote_reference_space option.
2149 ------------------------------
2150 Old-Format Configuration Files
2151 ------------------------------
2153 Formerly, Docutils configuration files contained a single "[options]"
2154 section only. This was found to be inflexible, and in August 2003
2155 Docutils adopted the current component-based configuration file
2156 sections as described above. Docutils will still recognize the old
2157 "[options]" section, but complains with a deprecation warning.
2159 To convert existing config files, the easiest way is to change the
2160 section title: change "[options]" to "[general]". Most settings
2161 haven't changed. The only ones to watch out for are these:
2163 ===================== =====================================
2164 Old-Format Setting New Section & Setting
2165 ===================== =====================================
2166 pep_stylesheet [pep_html writer] stylesheet
2167 pep_stylesheet_path [pep_html writer] stylesheet_path
2168 pep_template [pep_html writer] template
2169 ===================== =====================================
2174 .. _bibliographic field list:
2175 .. _bibliographic fields:
2176 ../ref/rst/restructuredtext.html#bibliographic-fields
2177 .. _block quote: ../ref/rst/restructuredtext.html#block-quotes
2178 .. _citations: ../ref/rst/restructuredtext.html#citations
2179 .. _enumerated lists: ../ref/rst/restructuredtext.html#enumerated-lists
2180 .. _field lists: ../ref/rst/restructuredtext.html#field-lists
2181 .. _field names: ../ref/rst/restructuredtext.html#field-names
2182 .. _footnotes: ../ref/rst/restructuredtext.html#footnotes
2183 .. _footnote references: ../ref/rst/restructuredtext.html#footnote-references
2184 .. _inline markup recognition rules:
2185 ../ref/rst/restructuredtext.html#inline-markup-recognition-rules
2186 .. _literal blocks: ../ref/rst/restructuredtext.html#literal-blocks
2187 .. _option lists: ../ref/rst/restructuredtext.html#option-lists
2188 .. _tables: ../ref/rst/restructuredtext.html#tables
2190 .. _table of contents: ../ref/rst/directives.html#contents