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 dependencies, and the section specific to the
163 Writer used ("[... writer]"). For example, `[pep_html writer]`_
164 depends on `[html4css1 writer]`_.
166 5. `[applications]`_, application dependencies, and the section
167 specific to the Application (front-end tool) in use
168 ("[... application]").
170 Since any setting may be specified in any section, this ordering
171 allows component- or application-specific overrides of earlier
172 settings. For example, there may be Reader-specific overrides of
173 general settings; Writer-specific overrides of Parser settings;
174 Application-specific overrides of Writer settings; and so on.
176 If multiple configuration files are applicable, the process is
177 completed (all sections are applied in the order given) for each one
178 before going on to the next. For example, a "[pep_html writer]
179 stylesheet" setting in an earlier configuration file would be
180 overridden by an "[html4css1 writer] stylesheet" setting in a later
183 Some knowledge of Python_ is assumed for some attributes.
186 http://www.python.org/doc/current/lib/module-ConfigParser.html
187 .. _Python: http://www.python.org/
188 .. _RFC 822: http://www.rfc-editor.org/rfc/rfc822.txt
189 .. _Docutils application: tools.html
195 Settings in the "[general]" section are always applied.
200 Prefix prepended to all auto-generated `identifier keys` generated within
201 the document, after id_prefix_. Ensure the value conforms to the
202 restrictions on identifiers in the output format, as it is not subjected to
203 the `identifier normalization`_.
205 A trailing "%" is replaced with the tag name (new in Docutils 0.16).
207 Default: "id" (`will change to "%" in future`__).
208 Options: ``--auto-id-prefix`` (hidden, intended mainly for programmatic use).
210 .. _identifier normalization:
211 ../ref/rst/directives.html#identifier-normalization
212 __ ../../RELEASE-NOTES.html#future-changes
217 Include a time/datestamp in the document footer. Contains a
218 format string for Python's ``time.strftime``. See the `time
219 module documentation`__.
222 Options: ``--date, -d, --time, -t, --no-datestamp``.
224 Configuration file entry examples::
226 # Equivalent to --date command-line option, results in
227 # ISO 8601 extended format datestamp, e.g. "2001-12-21":
230 # Equivalent to --time command-line option, results in
231 # date/timestamp like "2001-12-21 18:43 UTC":
232 datestamp: %Y-%m-%d %H:%M UTC
234 # Disables datestamp; equivalent to --no-datestamp:
237 __ http://www.python.org/doc/current/lib/module-time.html
242 Report debug-level system messages.
244 Default: don't (None). Options: ``--debug, --no-debug``.
249 At the end of processing, write all internal attributes of the
250 document (``document.__dict__``) to stderr.
252 Default: don't (None).
253 Options: ``--dump-internals`` (hidden, for development use only).
258 At the end of processing, write the pseudo-XML representation of
259 the document to stderr.
261 Default: don't (None).
262 Options: ``--dump-pseudo-xml`` (hidden, for development use only).
267 At the end of processing, write all Docutils settings to stderr.
269 Default: don't (None).
270 Options: ``--dump-settings`` (hidden, for development use only).
275 At the end of processing, write a list of all transforms applied
276 to the document to stderr.
278 Default: don't (None).
279 Options: ``--dump-transforms`` (hidden, for development use only).
284 The text encoding for error output.
286 Default: "ascii". Options: ``--error-encoding, -e``.
288 error_encoding_error_handler
289 ----------------------------
291 The error handler for unencodable characters in error output. See
292 output_encoding_error_handler_ for acceptable values.
294 Default: "backslashreplace"
295 Options: ``--error-encoding-error-handler, --error-encoding, -e``.
300 A system message level threshold; non-halting system messages at
301 or above this level will produce a non-zero exit status at normal
302 exit. Exit status is the maximum system message level plus 10 (11
305 Default: disabled (5). Options: ``--exit-status``.
310 List_ of internal attribues to expose as external attributes (with
311 "internal:" namespace prefix). To specify multiple attributes in
312 configuration files, use colons to separate names; on the command
313 line, the option may be used more than once.
315 Default: don't (None).
316 Options: ``--expose-internal-attribute`` (hidden, for development use only).
321 Enable or disable backlinks from footnotes_ and citations_ to their
324 Default: enabled (True).
325 Options: ``--footnote-backlinks, --no-footnote-backlinks``.
330 Include a "Generated by Docutils" credit and link in the document footer.
332 Default: off (None). Options: ``--generator, -g, --no-generator``.
337 The threshold at or above which system messages are converted to
338 exceptions, halting execution immediately. If `traceback`_ is set, the
339 exception will propagate; otherwise, Docutils will exit.
341 Default: severe (4). Options: ``--halt, --strict``.
346 Prefix prepended to all identifier keys generated within the document.
347 Ensure the value conforms to the restrictions on identifiers in the output
348 format, as it is not subjected to the `identifier normalization`_.
349 See also auto_id_prefix_.
352 Options: ``--id-prefix`` (hidden, intended mainly for programmatic use).
357 The text encoding for input.
359 Default: auto-detect (None). Options: ``--input-encoding, -i``.
361 input_encoding_error_handler
362 ----------------------------
364 The error handler for undecodable characters in the input. Acceptable
368 Raise an exception in case of an encoding error.
370 Replace malformed data with the official Unicode replacement
373 Ignore malformed data and continue without further notice.
375 Acceptable values are the same as for the "error" parameter of
376 Python's ``unicode`` function; other values may be defined in
377 applications or in future versions of Python.
380 Options: ``--input-encoding-error-handler, --input-encoding, -i``.
385 Case-insensitive `language tag`_ as defined in `BCP 47`_.
387 Sets the document language, also used for localized directive and
388 role names as well as Docutils-generated text.
390 A typical language identifier consists of a 2-letter language code
391 from `ISO 639`_ (3-letter codes can be used if no 2-letter code
392 exists). The language identifier can have an optional subtag,
393 typically for variations based on country (from `ISO 3166`_
394 2-letter country codes). Avoid subtags except where they add
395 useful distinguishing information. Examples of language tags
396 include "fr", "en-GB", "pt-br" (the same as "pt-BR"), and
397 "de-1901" (German with pre-1996 spelling).
399 The language of document parts can be specified with a
400 "language-<language tag>" `class attribute`_, e.g.
401 ``.. class:: language-el-polyton`` for a quote in polytonic Greek.
403 Default: English ("en"). Options: ``--language, -l``.
405 .. _class attribute: ../ref/doctree.html#classes
410 The text encoding for output.
412 Default: "UTF-8". Options: ``--output-encoding, -o``.
414 output_encoding_error_handler
415 -----------------------------
417 The error handler for unencodable characters in the output. Acceptable
421 Raise an exception in case of an encoding error.
423 Replace malformed data with a suitable replacement marker,
426 Ignore malformed data and continue without further notice.
428 Replace with the appropriate XML character reference, such as
431 Replace with backslashed escape sequences, such as "``\u2020``".
433 Acceptable values are the same as for the "error" parameter of
434 Python's ``encode`` string method; other values may be defined in
435 applications or in future versions of Python.
438 Options: ``--output-encoding-error-handler, --output-encoding, -o``.
443 Path to a file where Docutils will write a list of files that were
444 required to generate the output, e.g. included files or embedded
445 stylesheets [#dependencies]_. [#pwd]_ The format is one path per
446 line with forward slashes as separator, the encoding is ``utf8``.
448 Set to ``-`` in order to write dependencies to stdout.
450 This option is particularly useful in conjunction with programs like
451 ``make`` using ``Makefile`` rules like::
453 ham.html: ham.txt $(shell cat hamdeps.txt)
454 rst2html.py --record-dependencies=hamdeps.txt ham.txt ham.html
456 If the filesystem encoding differs from utf8, replace the ``cat``
457 command with a call to a converter, e.g.::
459 $(shell iconv -f utf8 -t latin1 hamdeps.txt)
461 Default: None. Option: ``--record-dependencies``.
466 Report system messages at or higher than <level>:
474 Default: warning (2).
475 Options: ``--report, -r, --verbose, -v, --quiet, -q``.
480 Enable or disable automatic section numbering by Docutils
481 (docutils.transforms.parts.SectNum) associated with the `sectnum
484 If disabled, section numbers might be added to the output by the
485 renderer (e.g. by LaTeX or via a CSS style definition).
487 Default: enabled (True).
488 Options: ``--section-numbering``, ``--no-section-numbering``.
490 .. _sectnum directive: ../ref/rst/directives.html#sectnum
495 Include a "View document source" link in the document footer. URL will
496 be relative to the destination.
498 Default: don't (None).
499 Options: ``--source-link, -s, --no-source-link``.
504 An explicit URL for a "View document source" link, used verbatim.
506 Default: compute if source_link (None).
507 Options: ``--source-url, --no-source-link``.
512 When processing a document tree with the Visitor pattern, raise an
513 error if a writer does not support a node type listed as optional. For
514 transitional development use.
516 Default: disabled (None).
517 Option: ``--strict-visitor`` (hidden, for development use only).
522 Comma-separated list_ of "classes" attribute values to remove from all
523 elements in the document tree. The command line option may be used more
526 .. WARNING:: Potentially dangerous; use with caution.
528 Default: disabled (None). Option: ``--strip-class``.
533 Enable the removal of comment elements from the document tree.
535 Default: disabled (None).
536 Options: ``--strip-comments``, ``--leave-comments``.
538 strip_elements_with_classes
539 ---------------------------
541 Comma-separated list_ of "classes" attribute values;
542 matching elements are removed from the document tree.
543 The command line option may be used more than once.
545 .. WARNING:: Potentially dangerous; use with caution.
547 Default: disabled (None). Option: ``--strip-element-with-class``.
552 The `document title`_ as metadata, which does not become part of the
553 document body. It overrides a document-supplied title. For
554 example, in HTML output the metadata document title appears in the
555 title bar of the browser window.
557 Default: none. Option: ``--title``.
559 .. _document title: ../ref/rst/restructuredtext.html#document-title
564 Enable backlinks from section titles to table of contents entries
565 ("entry"), to the top of the TOC ("top"), or disable ("none").
568 Options: ``--toc-entry-backlinks, --toc-top-backlinks, --no-toc-backlinks``.
573 Enable Python tracebacks when halt-level system messages and other
574 exceptions occur. Useful for debugging, and essential for issue
575 reports. Exceptions are allowed to propagate, instead of being
576 caught and reported (in a user-friendly way) by Docutils.
578 Default: disabled (None) unless Docutils is run programmatically
579 using the `Publisher Interface`_.
580 Options: ``--traceback, --no-traceback``.
582 .. _Publisher Interface: ../api/publisher.html
587 Path to a file for the output of system messages (warnings). [#pwd]_
589 Default: stderr (None). Options: ``--warnings``.
595 Docutils currently supports only one parser, for reStructuredText.
598 [restructuredtext parser]
599 -------------------------
601 character_level_inline_markup
602 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
604 Experimental setting to relax the `inline markup recognition rules`_
605 requiring whitespace or punctuation around inline markup.
607 Allows character level inline markup without escaped whithespace and is
608 especially suited for langauges that do not use whitespace to separate words
609 (e.g. Japanese, Chinese).
611 .. WARNING:: Potentially dangerous; use with caution.
613 When changing this setting to "True", inline markup charactes in
614 URLs, names and formulas must be escaped to prevent recognition and
615 possible errors. Examples::
617 http://rST_for_all.html (hyperlinks to rST_ and for_)
618 x_2, inline_markup (hyperlinks to x_ and inline_)
619 2*x (starts emphasised text)
620 a|b (starts a substitution reference)
622 Default: disabled (False).
623 Options: ``--character-level-inline-markup, --word-level-inline-markup``.
625 New in Docutils 0.13.
627 file_insertion_enabled
628 ~~~~~~~~~~~~~~~~~~~~~~
630 Enable or disable directives that insert the contents of external
631 files, such as the "include_" & "raw_". A "warning" system
632 message (including the directive text) is inserted instead. (See
633 also raw_enabled_ for another security-relevant setting.)
635 Default: enabled (True).
636 Options: ``--file-insertion-enabled, --no-file-insertion``.
638 .. _include: ../ref/rst/directives.html#include
639 .. _raw: ../ref/rst/directives.html#raw
644 Recognize and link to standalone PEP references (like "PEP 258").
646 Default: disabled (None); enabled (True) in PEP Reader.
647 Options: ``--pep-references``.
651 Base URL for PEP references.
653 Default: "http://www.python.org/peps/".
654 Option: ``--pep-base-url``.
656 pep_file_url_template
657 ~~~~~~~~~~~~~~~~~~~~~
659 Template for PEP file part of URL, interpolated with the PEP
660 number and appended to pep_base_url_.
662 Default: "pep-%04d". Option: ``--pep-file-url``.
667 Enable or disable the "raw_" directive. A "warning" system message
668 (including the directive text) is inserted instead. (See also
669 file_insertion_enabled_ for another security-relevant setting.)
671 Default: enabled (True). Options: ``--raw-enabled, --no-raw``.
676 Recognize and link to standalone RFC references (like "RFC 822").
678 Default: disabled (None); enabled (True) in PEP Reader.
679 Options: ``--rfc-references``.
684 Base URL for RFC references.
686 Default: "http://www.faqs.org/rfcs/". Option: ``--rfc-base-url``.
691 Activate the experimental SmartQuotes_ transform to
692 change straight quotation marks to typographic form. `Quote characters`_
693 are selected according to the language of the current block element (see
694 language_code_, smartquotes_locales_, and the `pre-defined quote sets`__).
696 Also changes consecutive runs of hyphen-minus and full stops (``---``,
697 ``--``, ``...``) to em-dash, en-dash and ellipsis Unicode characters
705 alt (or "alternative")
706 Use alternative quote set (if defined for the language).
708 Default: "no". Option: ``--smart-quotes``.
710 New in Docutils 0.10.
712 .. _SmartQuotes: smartquotes.html
713 __ smartquotes.html#localization
714 .. _quote characters:
715 http://en.wikipedia.org/wiki/Non-English_usage_of_quotation_marks
721 Typographical quotes used by the SmartQuotes_ transform.
723 A comma-separated list_ with language tag and a set of four quotes (primary
724 open/close, secondary open/close)smartquotes_locales. (If more than one
725 character shall be used for a quote (e.g. padding in French quotes), a
726 colon-separated list may be used.)
729 Ensure a correct leading apostrophe in ``'s Gravenhage`` in Dutch (at the
730 cost of incorrect opening single quotes) and set French quotes to double
731 and single guillemets with inner padding::
733 smartquote-locales: nl: „”’’,
736 Default: None. Option: ``--smartquotes-locales``.
738 New in Docutils 0.14.
743 Token type names used by Pygments_ when parsing contents of the code_
749 Use hierarchy of long token type names.
751 Use short token type names. (For use with
752 `Pygments-generated stylesheets`_.)
754 No code parsing. Use this to avoid the "Pygments not
755 found" warning when Pygments is not installed.
757 Default: "long". Option: ``--syntax-highlight``.
761 .. _Pygments: http://pygments.org/
762 .. _code: ../ref/rst/directives.html#code
763 .. _Pygments-generated stylesheets:
764 http://pygments.org/docs/cmdline/#generating-styles
769 Number of spaces for hard tab expansion.
771 Default: 8. Options: ``--tab-width``.
773 trim_footnote_reference_space
774 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
776 Remove spaces before `footnote references`_.
778 Default: don't (None); may be overriden by a writer-specific
779 footnote_references__ default though.
781 Options: ``--trim-footnote-reference-space, --leave-footnote-reference-space``.
783 __ `footnote_references [latex writers]`_
796 Enable or disable the `bibliographic field list`_ transform
797 (docutils.transforms.frontmatter.DocInfo).
799 Default: enabled (True). Options: ``--no-doc-info``.
804 Enable or disable the promotion of a lone top-level section title
805 to `document title`_ (and subsequent section title to document
806 subtitle promotion; docutils.transforms.frontmatter.DocTitle).
808 Default: enabled (True). Options: ``--no-doc-title``.
813 Enable or disable the promotion of the title of a lone subsection
814 to a subtitle (docutils.transforms.frontmatter.SectSubTitle).
816 Default: disabled (0). Options: ``--section-subtitles,
817 --no-section-subtitles``.
823 The `pep_references`_ and `rfc_references`_ settings
824 (`[restructuredtext parser]`_) are set on by default.
836 [docutils_xml writer]
837 ---------------------
841 * In Python versions older than 2.7.3 and 3.2.3, the newlines_ and
842 indents_ options may adversely affect whitespace; use them only for
843 reading convenience (see http://bugs.python.org/issue4147).
845 * The XML declaration carries text encoding information. If the encoding
846 is not UTF-8 or ASCII and the XML declaration is missing, standard
847 tools may be unable to read the generated XML.
852 Generate XML with a DOCTYPE declaration.
854 Default: do (1). Options: ``--no-doctype``.
859 Generate XML with indents and newlines.
861 Default: don't (None). Options: ``--indents``.
866 Generate XML with newlines before and after tags.
868 Default: don't (None). Options: ``--newlines``.
870 .. _xml_declaration [docutils_xml writer]:
875 Generate XML with an XML declaration. Also defined for the
878 Default: do (1). Options: ``--no-xml-declaration``.
880 __ `xml_declaration [html4css1 writer]`_
886 .. _attribution [html4css1 writer]:
891 Format for `block quote`_ attributions: one of "dash" (em-dash
892 prefix), "parentheses"/"parens", or "none". Also defined for the
893 `LaTeX Writers <attribution [latex writers]_>`__.
895 Default: "dash". Options: ``--attribution``.
897 cloak_email_addresses
898 ~~~~~~~~~~~~~~~~~~~~~
900 Scramble email addresses to confuse harvesters. In the reference
901 URI, the "@" will be replaced by %-escapes (as of RFC 1738). In
902 the visible text (link text) of an email reference, the "@" and
903 all periods (".") will be surrounded by ``<span>`` tags.
904 Furthermore, HTML entities are used to encode these characters in
905 order to further complicate decoding the email address. For
906 example, "abc@example.org" will be output as::
908 <a class="reference" href="mailto:abc%40example.org">
909 abc<span>@</span>example<span>.</span>org</a>
911 .. Note:: While cloaking email addresses will have little to no
912 impact on the rendering and usability of email links in most
913 browsers, some browsers (e.g. the ``links`` browser) may decode
914 cloaked email addresses incorrectly.
916 Default: don't cloak (None). Option: ``--cloak-email-addresses``.
921 Remove extra vertical whitespace between items of bullet lists and
922 enumerated lists, when list items are all "simple" (i.e., items
923 each contain one paragraph and/or one "simple" sublist only). The
924 behaviour can be specified directly via "class" attributes (values
925 "compact" and "open") in the document.
927 Default: enabled (True).
928 Options: ``--compact-lists, --no-compact-lists``.
933 Remove extra vertical whitespace between items of `field lists`_ that
934 are "simple" (i.e., all field bodies each contain at most one
935 paragraph). The behaviour can be specified directly via "class"
936 attributes (values "compact" and "open") in the document.
938 Default: enabled (True).
939 Options: ``--compact-field-lists, --no-compact-field-lists``.
941 .. _embed_stylesheet [html4css1 writer]:
946 Embed the stylesheet in the output HTML file. The stylesheet file
947 must specified by the stylesheet_path__ setting and must be
948 accessible during processing.
949 Also defined for the `LaTeX Writers <embed_stylesheet [latex writers]_>`__.
951 Default: enabled. Options: ``--embed-stylesheet,
954 __ `stylesheet_path [html4css1 writer]`_
959 The maximum width (in characters) for one-column `field names`_. Longer
960 field names will span an entire row of the table used to render the field
961 list. 0 indicates "no limit". See also option_limit_.
963 Default: 14 (i.e. 14 characters). Option: ``--field-name-limit``.
965 .. _footnote_references [html4css1 writer]:
970 Format for `footnote references`_, one of "superscript" or "brackets".
971 Also defined for the `LaTeX Writers <footnote_references [latex writers]_>`__.
973 Overrides [#override]_ trim_footnote_reference_space_, if
974 applicable. [#footnote_space]_
976 Default: "brackets". Option: ``--footnote-references``.
981 The initial level for header elements. This does not affect the
982 document title & subtitle; see doctitle_xform_.
984 Default: 1 (for "<h1>"). Option: ``--initial-header-level``.
989 The format of mathematical content (`math directive`_ and role) in
990 the output document. Supported values are (case insensitive):
993 Format math in standard HTML enhanced by CSS rules.
994 Requires the ``math.css`` stylesheet (in the system
995 `stylesheet directory <stylesheet_dirs [html4css1 writer]_>`_)
997 A `stylesheet_path <stylesheet_path [html4css1 writer]_>`_
998 can be appended after whitespace, the specified
999 stylesheet(s) will only be referenced or embedded, if required
1000 (i.e. if there is mathematical content in the document).
1003 Format math for display with MathJax_, a JavaScript-based math rendering
1007 Works across multiple browsers and platforms.
1009 Large set of `supported LaTeX math commands and constructs`__
1011 __ http://docs.mathjax.org/en/latest/tex.html#supported-latex-commands
1014 Rendering requires JavaScript and an Internet connection or local
1015 MathJax installation.
1017 A URL pointing to a MathJax library should be appended after whitespace.
1018 A warning is given if this is missing.
1020 * It is recommended to install__ the MathJax library on the same
1021 server as the rest of the deployed site files.
1023 __ http://docs.mathjax.org/en/latest/installation.html
1025 Example: Install the library at the top level of the web
1026 server’s hierarchy in the directory ``MathJax`` and set::
1028 math-output: mathjax /MathJax/MathJax.js
1030 * The easiest way to use MathJax is to link directly to a public
1031 installation. In that case, there is no need to install MathJax locally.
1033 Downside: Downloads JavaScript code from a third-party site --- opens
1034 the door to cross-site scripting attacs!
1036 Example: MathJax.org recommends ``cdnjs.cloudflare.com``::
1038 math-output: mathjax
1039 https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js
1041 See https://cdnjs.com/about and https://www.cloudflare.com/terms/ for
1042 details and terms of use.
1044 * Use a local MathJax installation on the *client* machine, e.g.::
1046 math-output: MathJax file:/usr/share/javascript/mathjax/MathJax.js
1048 This is the fallback if no URL is specified.
1051 Embed math content as presentational MathML_.
1054 The W3C recommendation for math on the web.
1056 Self-contained documents (no JavaScript, no external downloads).
1059 Docutil's latex2mathml converter supports only a small
1060 subset of LaTeX syntax.
1062 With the "html4css1" writer, the resulting HTML document does
1063 not validate, as there is no DTD for `MathML + XHTML Transitional`.
1064 However, MathML-enabled browsers will render it fine.
1066 An external converter can be appended after whitespace, e.g.,
1067 ``--math-output="MathML latexml"``:
1070 Fast conversion, support for many symbols and environments, but no
1071 "align" (or other equation-aligning) environment. (C++)
1074 Comprehensive macro support but very slow. (Perl)
1077 No "matrix", "align" and "cases" environments. Support may be removed.
1080 Include literal LaTeX code.
1082 The failsave fallback.
1084 Default: "HTML math.css" (The `[html5 writer]`_ defaults to "MathML").
1085 Option: ``--math-output``.
1087 New in Docutils 0.8.
1089 .. _math directive: ../ref/rst/directives.html#math
1090 .. _MathJax: http://www.mathjax.org/
1091 .. _MathPlayer: http://www.dessci.com/en/products/mathplayer/
1092 .. _MathML: http://www.w3.org/TR/MathML/
1093 .. _blahtexml: http://gva.noekeon.org/blahtexml/
1094 .. _LaTeXML: http://dlmf.nist.gov/LaTeXML/
1095 .. _TtM: http://hutchinson.belmont.ma.us/tth/mml/
1100 The maximum width (in characters) for options in `option lists`_.
1101 Longer options will span an entire row of the table used to render
1102 the option list. 0 indicates "no limit". See also
1105 Default: 14 (i.e. 14 characters). Option: ``--option-limit``.
1107 .. _stylesheet [html4css1 writer]:
1112 A comma-separated list of CSS stylesheet URLs, used verbatim.
1113 Also defined for the `LaTeX Writer <stylesheet [latex writers]_>`__.
1115 Overrides also stylesheet-path__. [#override]_
1117 Default: None. Options: ``--stylesheet``.
1119 __ `stylesheet_path [html4css1 writer]`_
1121 .. _stylesheet_dirs [html4css1 writer]:
1126 A comma-separated list of directories where stylesheets can be found.
1127 Used by the stylesheet_path__ setting when expanding relative path arguments.
1129 Note: This setting defines a "search path" (similar to the PATH variable for
1130 executables). However, the term "path" is already used in the
1131 stylesheet_path__ setting with the meaning of a file location.
1134 __ `stylesheet_path [html4css1 writer]`_
1136 Default: the working directory of the process at launch and the directory
1137 with default stylesheet files (writer and installation specific).
1138 Use the ``--help`` option to get the exact value.
1139 Option: ``--stylesheet-directories``.
1141 .. _stylesheet_path [html4css1 writer]:
1146 A comma-separated list of paths to CSS stylesheets. Relative paths are
1147 expanded if a matching file is found in the stylesheet_dirs__.
1148 If embed_stylesheet__ is False, paths are rewritten relative to the
1149 output HTML file. Also defined for the `LaTeX Writer`__.
1151 Also overrides "stylesheet". [#override]_
1152 Pass an empty string (to either "stylesheet" or "stylesheet_path") to
1153 deactivate stylesheet inclusion.
1155 Default: "html4css1.css".
1156 Options: ``--stylesheet-path``.
1158 __ `embed_stylesheet [html4css1 writer]`_
1159 __ `stylesheet_path [latex writers]`_
1160 __ `stylesheet_dirs [html4css1 writer]`_
1162 .. _table_style [html4css1 writer]:
1167 Class value(s) added to all tables_.
1168 Also defined for the `LaTeX Writer`__.
1170 The default CSS sylesheet defines:
1173 No borders around the table.
1176 Lines above and below the table and a thin line after the head.
1178 align-left, align-center, align-right
1182 Delegate the determination of table column widths to the backend
1183 (Leave out the ``<colgroup>`` column specification.)
1185 Cf. the `table directive`_.
1187 Default: "". Option: ``--table-style``.
1189 __ `table_style [latex writers]`_
1190 .. _table directive: ../ref/rst/directives.html#table
1192 .. _template [html4css1 writer]:
1197 Path to template file, which must be encoded in UTF-8. [#pwd]_
1198 Also defined for the `LaTeX Writer`__.
1200 Default: "template.txt" in the docutils/writers/html4css1/
1201 directory (installed automatically; for the exact machine-specific
1202 path, use the ``--help`` option). Options: ``--template``.
1204 __ `template [latex writers]`_
1206 .. _xml_declaration [html4css1 writer]:
1211 Generate XML with an XML declaration. Also defined for the
1212 `Docutils XML Writer`__.
1214 .. Caution:: The XML declaration carries text encoding information. If the
1215 encoding is not UTF-8 or ASCII and the XML declaration is missing,
1216 standard tools may be unable to read the generated XHTML.
1218 Default: do (1). Options: ``--no-xml-declaration``.
1220 __ `xml_declaration [docutils_xml writer]`_
1226 The PEP/HTML Writer derives from the standard HTML Writer, and shares
1227 all settings defined in the `[html4css1 writer]`_ section. The
1228 "[html4css1 writer]" section of configuration files is processed
1229 before the "[pep_html writer]" section.
1231 The PEP/HTML Writer's default for the following settings differ from
1232 those of the standard HTML Writer:
1234 `stylesheet_path <stylesheet_path [html4css1 writer]_>`_:
1237 `template <template [html4css1 writer]_>`_:
1238 Default: ``docutils/writers/pep_html/template.txt`` in the installation
1239 directory. For the exact machine-specific path, use the ``--help``
1244 Do not use a random banner image. Mainly used to get predictable
1245 results when testing.
1247 Default: random enabled (None). Options: ``--no-random`` (hidden).
1252 Home URL prefix for PEPs.
1254 Default: current directory ("."). Options: ``--pep-home``.
1260 Default: parent directory (".."). Options: ``--python-home``.
1266 The S5/HTML Writer derives from the standard HTML Writer, and shares
1267 all settings defined in the `[html4css1 writer]`_ section. The
1268 "[html4css1 writer]" section of configuration files is processed
1269 before the "[s5_html writer]" section.
1271 The S5/HTML Writer's default for the following settings differ
1272 from those of the standard HTML Writer:
1275 Default: disable compact lists.
1278 Default: ``docutils/writers/s5_html/template.txt`` in the installation
1279 directory. For the exact machine-specific path, use the ``--help``
1286 Auto-hide the presentation controls in slideshow mode, or or keep
1287 them visible at all times.
1289 Default: auto-hide (1). Options: ``--hidden-controls``,
1290 ``--visible-controls``.
1295 Enable or disable the current slide indicator ("1/15").
1297 Default: disabled (None). Options: ``--current-slide``,
1298 ``--no-current-slide``.
1300 overwrite_theme_files
1301 """""""""""""""""""""
1303 Allow or prevent the overwriting of existing theme files in the
1304 ``ui/<theme>`` directory. This has no effect if "theme_url_" is
1307 Default: keep existing theme files (None). Options:
1308 ``--keep-theme-files``, ``--overwrite-theme-files``.
1313 Name of an installed S5 theme, to be copied into a ``ui/<theme>``
1314 subdirectory, beside the destination file (output HTML). Note
1315 that existing theme files will not be overwritten; the existing
1316 theme directory must be deleted manually.
1317 Also overrides the "theme_url_" setting. [#override]_
1319 Default: "default". Option: ``--theme``.
1323 The URL of an S5 theme directory. The destination file (output
1324 HTML) will link to this theme; nothing will be copied. Also overrides
1325 the "theme_" setting. [#override]_
1327 Default: None. Option: ``--theme-url``.
1332 The initial view mode, either "slideshow" or "outline".
1334 Default: "slidewhow". Option: ``--view-mode``.
1340 The `html5` writer uses the settings described in the `[html4css1
1341 writer]`_ section with the following exceptions:
1344 `field_name_limit`_, `option_limit`_.
1346 Different default for:
1351 `stylesheet_path <stylesheet_path [html4css1 writer]_>`_:
1352 Default: "minimal.css,plain.css"
1354 `stylesheet_dirs <stylesheet_dirs [html4css1 writer]_>`_:
1355 Default: Installation-dependent. Use the --help option to get the exact
1358 New in Docutils 0.13.
1364 Common settings for the `[latex2e writer]`_ and `[xetex writer]`_.
1369 To get pagenumbers in the `table of contents`_, it
1370 must be generated by LaTeX. Usually latex must be run twice to get
1373 Default: on. Options: ``--use-latex-toc, --use-docutils-toc``.
1378 Attach author and date to the `document title`_
1379 instead of the `bibliographic fields`_.
1381 Default: off. Options: ``--use-latex-docinfo, --use-docutils-docinfo``.
1385 Use the Docutils-specific macros ``\DUfootnote`` and
1386 ``\DUfootnotetext`` for footnotes_.
1388 Default: on. Option: ``--docutils-footnotes``.
1393 Use \cite for citations_ instead of a simulation with figure-floats.
1395 Default: off. Options: ``--use-latex-citations, --figure-citations``.
1400 Use LaTeX abstract environment for the document's abstract_.
1402 Default: off. Options: ``--use-latex-abstract, --topic-abstract``.
1407 Color of any hyperlinks embedded in text.
1409 * "0" or "false" disable coloring of links. (Links will be marked
1410 by red boxes that are not printed),
1411 * "black" results in “invisible“ links,
1413 Set hyperref_options_ to "draft" to completely disable hyperlinking.
1415 Default: "blue". Option: ``--hyperlink-color``.
1420 Options for the `hyperref TeX package`_. If hyperlink_color_ is
1421 not "false", the expansion of ::
1423 'colorlinks=true,linkcolor=%s,urlcolor=%s' % (
1424 hyperlink_color, self.hyperlink_color
1428 Default: "". Option: ``--hyperref-options``.
1430 .. _hyperref TeX package: http://tug.org/applications/hyperref/
1435 Specify LaTeX documentclass.
1437 Default: "article". Option: ``--documentclass``.
1442 Specify document options. Multiple options can be given, separated by
1445 Default: "a4paper". Option: ``--documentoptions``.
1448 .. _embed_stylesheet [latex writers]:
1453 Embed the stylesheet(s) in the header of the output file. The
1454 stylesheets must be accessible during processing. Currently, this
1455 fails if the file is not available via the given path (i.e. the
1456 file is *not* searched in the `TeX input path`_).
1457 Also defined for the `HTML Writer`__ (with default *on*).
1459 Default: off. Options: ``--embed-stylesheet, --link-stylesheet``.
1461 __ `embed_stylesheet [html4css1 writer]`_
1463 .. _stylesheet [latex writers]:
1468 A comma-separated list_ of style files.
1469 Also defined for the `HTML Writer`__.
1471 Overrides also stylesheet_path__. [#override]_
1473 If `embed_stylesheet`__ is False (default), the stylesheet files are
1474 referenced with ``\usepackage`` (extension ``.sty`` or no extension) or
1475 ``\input`` (any other extension).
1477 LaTeX will search the specified files in the `TeX input path`_.
1479 Default: no stylesheet (""). Option: ``--stylesheet``.
1481 __ `stylesheet_path [latex writers]`_
1482 __ `embed_stylesheet [latex writers]`_
1483 __ `stylesheet [html4css1 writer]`_
1485 http://www.tex.ac.uk/cgi-bin/texfaq2html?label=what-TDS
1488 .. _stylesheet_dirs [latex writers]:
1493 A comma-separated list of directories where stylesheets can be found.
1494 Used by the stylesheet_path__ setting.
1496 Note: This setting defines a "search path" (similar to the PATH variable for
1497 executables). However, the term "path" is already used in the
1498 stylesheet_path__ setting with the meaning of a file location.
1501 __ `stylesheet_path [latex writers]`_
1503 Default: the working directory of the process at launch and the directory
1504 with default stylesheet files (writer and installation specific).
1505 Use the ``--help`` option to get the exact value.
1506 Option: ``--stylesheet-directories``.
1508 .. _stylesheet_path [latex writers]:
1513 A comma-separated list of style files. Relative paths are expanded if a
1514 matching file is found in the stylesheet_dirs__.
1515 If embed_stylesheet__ is False, paths are rewritten relative to the
1516 output file path. Run ``latex`` from the directory containing
1519 The stylesheet__ option is preferred for files in the `TeX input path`_.
1521 Also defined for the
1522 `HTML Writer <stylesheet_path [html4css1 writer]_>`__.
1524 Also overrides stylesheet__. [#override]_
1526 Default: no stylesheet (""). Option: ``--stylesheet-path``.
1528 __ `stylesheet_dirs [latex writers]`_
1529 __ `embed_stylesheet [latex writers]`_
1531 __ `stylesheet [latex writers]`_
1537 LaTeX code that will be inserted in the document preamble.
1538 Can be used to load packages with options or (re-) define LaTeX
1539 macros without writing a custom style file (new in Docutils 0.7).
1541 Default: writer dependent (see `[latex2e writer]`_, `[xetex writer]`_).
1542 Option: ``--latex-preamble``.
1544 .. _footnote_references [latex writers]:
1549 Format for `footnote references`_: one of "superscript" or
1550 "brackets". Also defined for the `HTML Writer`__.
1552 Overrides [#override]_ trim_footnote_reference_space_, if
1553 applicable [#footnote_space]_.
1555 Default: "superscript". Option: ``--footnote-references``.
1557 __ `footnote_references [html4css1 writer]`_
1559 .. _attribution [latex writers]:
1564 See `attribution [html4css1 writer]`_.
1566 compound_enumerators
1567 ~~~~~~~~~~~~~~~~~~~~
1569 Enable or disable compound enumerators for nested `enumerated lists`_
1572 Default: disabled (None).
1573 Options: ``--compound-enumerators``, ``--no-compound-enumerators``.
1578 When possible\ [#]_, use the specified environment for `literal blocks`_.
1580 Default: "" (quoting of whitespace and special chars).
1581 Option: ``--literal-block-env``.
1583 .. [#] A literal-block element, when processed by a Docutils writer might
1584 have it's origin in literal block following "::" or a
1585 ``.. parsed-literal::`` directive.
1587 A LaTeX verbatim environment is only usable if there is no other
1588 markup contained in the literal-block.
1591 section_prefix_for_enumerators
1592 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1594 Enable or disable section ("." subsection ...) prefixes for
1595 compound enumerators. This has no effect unless
1596 `compound_enumerators`_ are enabled.
1598 Default: disabled (None).
1599 Options: ``--section-prefix-for-enumerators``,
1600 ``--no-section-prefix-for-enumerators``.
1602 section_enumerator_separator
1603 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1605 The separator between section number prefix and enumerator for
1606 compound enumerated lists (see `compound_enumerators`_).
1608 Generally it isn't recommended to use both sub-sections and nested
1609 enumerated lists with compound enumerators. This setting avoids
1610 ambiguity in the situation where a section "1" has a list item
1611 enumerated "1.1", and subsection "1.1" has list item "1". With a
1612 separator of ".", these both would translate into a final compound
1613 enumerator of "1.1.1". With a separator of "-", we get the
1614 unambiguous "1-1.1" and "1.1-1".
1616 Default: "-". Option: ``--section-enumerator-separator``.
1618 .. _table_style [latex writers]:
1623 Specify the default style for tables_
1624 Also defined for the `HTML Writer`__.
1629 Borders around all cells.
1631 A line above and below the table and one after the head.
1635 align-left, align-center, align-right
1638 colwidths-auto, colwidths-given
1639 Default value for column width determination by
1641 Override with the `table directive`_'s :widths: option.
1645 ``colwidths-auto`` is only suited for tables with simple cell content.
1647 LaTeX puts the content of auto-sized columns on one line (merging
1648 paragraphs) and may fail with complex content.
1650 Default: "standard". Option: ``--table-style``.
1652 __ `table_style [html4css1 writer]`_
1655 .. _template [latex writers]:
1660 Path [#pwd]_ to template file, which must be encoded in UTF-8.
1661 Also defined for the `HTML Writer`__.
1663 Default: writer dependent (see `[latex2e writer]`_, `[xetex writer]`_).
1664 Options: ``--template``.
1666 __ `template [html4css1 writer]`_
1672 The `LaTeX2e writer`_ generates a LaTeX source for compilation with 8-bit
1673 LaTeX (pdfTeX_). It shares all settings defined in the `[latex writers]`_
1674 `configuration section`_.
1676 .. _LaTeX2e writer: latex.html#latex2e-writer
1677 .. _pdfTeX: https://www.tug.org/applications/pdftex/
1678 .. _configuration section: `Configuration File Sections & Entries`_
1681 Writer Specific Defaults
1682 """"""""""""""""""""""""
1685 Load the "PDF standard fonts" (Times, Helvetica, Courier)::
1687 \usepackage{mathptmx} % Times
1688 \usepackage[scaled=.90]{helvet}
1689 \usepackage{courier}
1692 "default.tex" in the ``docutils/writers/latex2e/`` directory
1693 (installed automatically).
1695 __ `template [latex writers]`_
1701 Specify `LaTeX font encoding`_. Multiple options can be given, separated by
1702 commas. The last value becomes the document default.
1703 Possible values are "", "T1", "OT1", "LGR,T1" or any other combination of
1704 `LaTeX font encodings`_.
1706 Default: "T1". Option: ``--font-encoding``.
1708 .. _LaTeX font encoding: latex.html#font-encoding
1709 .. _LaTeX font encodings:
1710 http://mirror.ctan.org/macros/latex/doc/encguide.pdf
1716 The `XeTeX writer`_ generates a LaTeX source for compilation with `XeTeX or
1717 LuaTeX`_. It derives from the latex2e writer, and shares all settings
1718 defined in the `[latex writers]`_ and `[latex2e writer]`_ `configuration
1721 .. _XeTeX writer: latex.html#xetex-writer
1722 .. _XeTeX or LuaTeX: https://texfaq.org/FAQ-xetex-luatex
1723 .. _configuration sections: `Configuration File Sections & Entries`_
1725 Writer Specific Defaults
1726 """"""""""""""""""""""""
1729 Font setup for `Linux Libertine`_,::
1731 % Linux Libertine (free, wide coverage, not only for Linux)
1732 \setmainfont{Linux Libertine O}
1733 \setsansfont{Linux Biolinum O}
1734 \setmonofont[HyphenChar=None]{DejaVu Sans Mono}
1736 The optional argument ``HyphenChar=None`` to the monospace font
1737 prevents word hyphenation in literal text.
1739 .. _Linux Libertine: http://www.linuxlibertine.org/
1742 "xelatex.tex" in the ``docutils/writers/latex2e/`` directory
1743 (installed automatically).
1745 .. TODO: show full path with --help (like in the HTML writers) and
1746 add the following line:
1747 for the exact machine-specific path, use the ``--help`` option).
1749 __ `template [latex writers]`_
1755 The following command line options are specific to ``odtwriter``:
1760 Specify a stylesheet URL, used verbatim.
1762 Default: writers/odf_odt/styles.odt in the installation directory.
1767 Specify a configuration/mapping file relative to the current working
1768 directory for additional ODF options. In particular, this file may
1769 contain a section named "Formats" that maps default style names to names
1770 to be used in the resulting output file allowing for adhering to external
1771 standards. For more info and the format of the configuration/mapping
1772 file, see the `Odt Writer for Docutils`_ document.
1774 cloak-email-addresses
1775 ~~~~~~~~~~~~~~~~~~~~~
1777 Obfuscate email addresses to confuse harvesters while still
1778 keeping email links usable with standards-compliant browsers.
1780 no-cloak-email-addresses
1781 ~~~~~~~~~~~~~~~~~~~~~~~~
1782 Do not obfuscate email addresses.
1784 table-border-thickness
1785 ~~~~~~~~~~~~~~~~~~~~~~
1787 Specify the thickness of table borders in thousands of a cm.
1790 add-syntax-highlighting
1791 ~~~~~~~~~~~~~~~~~~~~~~~
1793 Add syntax highlighting in literal code blocks.
1795 no-syntax-highlighting
1796 ~~~~~~~~~~~~~~~~~~~~~~
1798 Do not add syntax highlighting in literal code blocks.
1804 Create sections for headers. (default)
1809 Do not create sections for headers.
1818 Do not create links. (default)
1823 Generate endnotes at end of document, not footnotes at bottom of page.
1828 Generate footnotes at bottom of page, not endnotes at end of
1834 Generate a bullet list table of contents, not an
1835 ODF/``oowriter`` table of contents.
1837 generate-oowriter-toc
1838 ~~~~~~~~~~~~~~~~~~~~~
1840 Generate an ODF/``oowriter`` table of contents, not a bullet
1841 list. (default) **Note:** ``odtwriter`` is not able to
1842 determine page numbers, so you will need to open the generated
1843 document in ``oowriter``, then right-click on the table of
1844 contents and select "Update" to insert page numbers.
1849 Specify the contents of a custom header line. For details about
1850 custom headers and about special field character sequences, see
1851 section "Custom header/footers: inserting page numbers, date,
1852 time, etc" in the `Odt Writer for Docutils`_ document for
1858 Specify the contents of a custom footer line. For details about
1859 custom footers and about special field character sequences, see
1860 section "Custom header/footers: inserting page numbers, date,
1861 time, etc" in the `Odt Writer for Docutils`_ document for
1864 .. _Odt Writer for Docutils: odt.html
1870 This writer does not define specific settings.
1876 [buildhtml application]
1877 -----------------------
1882 List_ of wildcard (shell globing) patterns, specifying files to silently
1883 ignore. To specify multiple patterns, use colon-separated patterns (in
1884 configuration files or on the command line); on the command line, the
1885 option may also be used more than once.
1887 Default: none. Options: ``--ignore``.
1892 List_ of directories not to process. To specify multiple
1893 directories, use colon-separated paths (in configuration files or
1894 on the command line); on the command line, the option may also be
1895 used more than once.
1897 Default: ['.hg', '.bzr', '.git', '.svn', 'CVS']. Options:
1903 Recursively scan subdirectories, or ignore subdirectories.
1905 Default: recurse (1). Options: ``--recurse, --local``.
1910 Work silently (no progress messages). Independent of
1913 Default: show progress (None). Options: ``--silent``.
1916 [docfactory application]
1917 ------------------------
1928 These settings are only effective as command-line options; setting
1929 them in configuration files has no effect.
1934 Path to a configuration file to read (if it exists). [#pwd]_
1935 Settings may override defaults and earlier settings. The config
1936 file is processed immediately. Multiple ``--config`` options may
1937 be specified; each will be processed in turn.
1939 Filesystem path settings contained within the config file will be
1940 interpreted relative to the config file's location (*not* relative
1941 to the current working directory).
1943 Default: None. Options: ``--config``.
1949 These settings are for internal use only; setting them in
1950 configuration files has no effect, and there are no corresponding
1951 command-line options.
1956 List of paths of applied configuration files.
1958 Default: None. No command-line options.
1963 (``buildhtml.py`` front end.) List of paths to source
1964 directories, set from positional arguments.
1966 Default: current working directory (None). No command-line
1972 Prevent standard configuration files from being read. For
1973 programmatic use only.
1975 Default: config files enabled (None). No command-line options.
1980 Path to output destination, set from positional arguments.
1982 Default: stdout (None). No command-line options.
1987 Path to input source, set from positional arguments.
1989 Default: stdin (None). No command-line options.
1992 .. _language tag: http://www.w3.org/International/articles/language-tags/
1993 .. _BCP 47: http://www.rfc-editor.org/rfc/bcp/bcp47.txt
1994 .. _ISO 639: http://www.loc.gov/standards/iso639-2/php/English_list.php
1995 .. _ISO 3166: http://www.iso.ch/iso/en/prods-services/iso3166ma/
1996 02iso-3166-code-lists/index.html
1998 .. [#pwd] Path relative to the working directory of the process at
2001 .. [#override] The overridden setting will automatically be set to
2002 ``None`` for command-line options and config file settings. Client
2003 programs which specify defaults that override other settings must
2004 do the overriding explicitly, by assigning ``None`` to the other
2007 .. [#dependencies] Images are only added to the dependency list if the
2008 reStructuredText parser extracted image dimensions from the file.
2010 .. [#footnote_space] The footnote space is trimmed if the reference
2011 style is "superscript", and it is left if the reference style is
2014 The overriding only happens if the parser supports the
2015 trim_footnote_reference_space option.
2018 ------------------------------
2019 Old-Format Configuration Files
2020 ------------------------------
2022 Formerly, Docutils configuration files contained a single "[options]"
2023 section only. This was found to be inflexible, and in August 2003
2024 Docutils adopted the current component-based configuration file
2025 sections as described above. Docutils will still recognize the old
2026 "[options]" section, but complains with a deprecation warning.
2028 To convert existing config files, the easiest way is to change the
2029 section title: change "[options]" to "[general]". Most settings
2030 haven't changed. The only ones to watch out for are these:
2032 ===================== =====================================
2033 Old-Format Setting New Section & Setting
2034 ===================== =====================================
2035 pep_stylesheet [pep_html writer] stylesheet
2036 pep_stylesheet_path [pep_html writer] stylesheet_path
2037 pep_template [pep_html writer] template
2038 ===================== =====================================
2043 .. _bibliographic field list:
2044 .. _bibliographic fields:
2045 ../ref/rst/restructuredtext.html#bibliographic-fields
2046 .. _block quote: ../ref/rst/restructuredtext.html#block-quotes
2047 .. _citations: ../ref/rst/restructuredtext.html#citations
2048 .. _enumerated lists: ../ref/rst/restructuredtext.html#enumerated-lists
2049 .. _field lists: ../ref/rst/restructuredtext.html#field-lists
2050 .. _field names: ../ref/rst/restructuredtext.html#field-names
2051 .. _footnotes: ../ref/rst/restructuredtext.html#footnotes
2052 .. _footnote references: ../ref/rst/restructuredtext.html#footnote-references
2053 .. _inline markup recognition rules:
2054 ../ref/rst/restructuredtext.html#inline-markup-recognition-rules
2055 .. _literal blocks: ../ref/rst/restructuredtext.html#literal-blocks
2056 .. _option lists: ../ref/rst/restructuredtext.html#option-lists
2057 .. _tables: ../ref/rst/restructuredtext.html#tables
2059 .. _table of contents: ../ref/rst/directives.html#contents