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 IDs generated within the
201 document, after id_prefix_.
204 Options: ``--auto-id-prefix`` (hidden, intended mainly for programmatic use).
209 Include a time/datestamp in the document footer. Contains a
210 format string for Python's ``time.strftime``. See the `time
211 module documentation`__.
214 Options: ``--date, -d, --time, -t, --no-datestamp``.
216 Configuration file entry examples::
218 # Equivalent to --date command-line option, results in
219 # ISO 8601 extended format datestamp, e.g. "2001-12-21":
222 # Equivalent to --time command-line option, results in
223 # date/timestamp like "2001-12-21 18:43 UTC":
224 datestamp: %Y-%m-%d %H:%M UTC
226 # Disables datestamp; equivalent to --no-datestamp:
229 __ http://www.python.org/doc/current/lib/module-time.html
234 Report debug-level system messages.
236 Default: don't (None). Options: ``--debug, --no-debug``.
241 At the end of processing, write all internal attributes of the
242 document (``document.__dict__``) to stderr.
244 Default: don't (None).
245 Options: ``--dump-internals`` (hidden, for development use only).
250 At the end of processing, write the pseudo-XML representation of
251 the document to stderr.
253 Default: don't (None).
254 Options: ``--dump-pseudo-xml`` (hidden, for development use only).
259 At the end of processing, write all Docutils settings to stderr.
261 Default: don't (None).
262 Options: ``--dump-settings`` (hidden, for development use only).
267 At the end of processing, write a list of all transforms applied
268 to the document to stderr.
270 Default: don't (None).
271 Options: ``--dump-transforms`` (hidden, for development use only).
276 The text encoding for error output.
278 Default: "ascii". Options: ``--error-encoding, -e``.
280 error_encoding_error_handler
281 ----------------------------
283 The error handler for unencodable characters in error output. See
284 output_encoding_error_handler_ for acceptable values.
286 Default: "backslashreplace"
287 Options: ``--error-encoding-error-handler, --error-encoding, -e``.
292 A system message level threshold; non-halting system messages at
293 or above this level will produce a non-zero exit status at normal
294 exit. Exit status is the maximum system message level plus 10 (11
297 Default: disabled (5). Options: ``--exit-status``.
302 List_ of internal attribues to expose as external attributes (with
303 "internal:" namespace prefix). To specify multiple attributes in
304 configuration files, use colons to separate names; on the command
305 line, the option may be used more than once.
307 Default: don't (None).
308 Options: ``--expose-internal-attribute`` (hidden, for development use only).
313 Enable or disable backlinks from footnotes and citations to their
316 Default: enabled (1).
317 Options: ``--footnote-backlinks, --no-footnote-backlinks``.
322 Include a "Generated by Docutils" credit and link in the document footer.
324 Default: off (None). Options: ``--generator, -g, --no-generator``.
329 The threshold at or above which system messages are converted to
330 exceptions, halting execution immediately. If `traceback`_ is set, the
331 exception will propagate; otherwise, Docutils will exit.
333 Default: severe (4). Options: ``--halt, --strict``.
338 Prefix prepended to all IDs generated within the document. See also
342 Options: ``--id-prefix`` (hidden, intended mainly for programmatic use).
347 The text encoding for input.
349 Default: auto-detect (None). Options: ``--input-encoding, -i``.
351 input_encoding_error_handler
352 ----------------------------
354 The error handler for undecodable characters in the input. Acceptable
358 Raise an exception in case of an encoding error.
360 Replace malformed data with the official Unicode replacement
363 Ignore malformed data and continue without further notice.
365 Acceptable values are the same as for the "error" parameter of
366 Python's ``unicode`` function; other values may be defined in
367 applications or in future versions of Python.
370 Options: ``--input-encoding-error-handler, --input-encoding, -i``.
375 Case-insensitive `language tag`_ as defined in `BCP 47`_.
377 Sets the document language, also used for localized directive and
378 role names as well as Docutils-generated text.
380 A typical language identifier consists of a 2-letter language code
381 from `ISO 639`_ (3-letter codes can be used if no 2-letter code
382 exists). The language identifier can have an optional subtag,
383 typically for variations based on country (from `ISO 3166`_
384 2-letter country codes). Avoid subtags except where they add
385 useful distinguishing information. Examples of language tags
386 include "fr", "en-GB", "pt-br" (the same as "pt-BR"), and
387 "de-1901" (German with pre-1996 spelling).
389 The language of document parts can be specified with a
390 "language-<language tag>" `class attribute`_, e.g.
391 ``.. class:: language-el-polyton`` for a quote in polytonic Greek.
393 Default: English ("en"). Options: ``--language, -l``.
395 .. _class attribute: ../ref/doctree.html#classes
400 The text encoding for output.
402 Default: "UTF-8". Options: ``--output-encoding, -o``.
404 output_encoding_error_handler
405 -----------------------------
407 The error handler for unencodable characters in the output. Acceptable
411 Raise an exception in case of an encoding error.
413 Replace malformed data with a suitable replacement marker,
416 Ignore malformed data and continue without further notice.
418 Replace with the appropriate XML character reference, such as
421 Replace with backslashed escape sequences, such as "``\u2020``".
423 Acceptable values are the same as for the "error" parameter of
424 Python's ``encode`` string method; other values may be defined in
425 applications or in future versions of Python.
428 Options: ``--output-encoding-error-handler, --output-encoding, -o``.
433 Path to a file where Docutils will write a list of files that were
434 required to generate the output, e.g. included files or embedded
435 stylesheets [#dependencies]_. [#pwd]_ The format is one path per
436 line with forward slashes as separator, the encoding is ``utf8``.
438 Set to ``-`` in order to write dependencies to stdout.
440 This option is particularly useful in conjunction with programs like
441 ``make`` using ``Makefile`` rules like::
443 ham.html: ham.txt $(shell cat hamdeps.txt)
444 rst2html.py --record-dependencies=hamdeps.txt ham.txt ham.html
446 If the filesystem encoding differs from utf8, replace the ``cat``
447 command with a call to a converter, e.g.::
449 $(shell iconv -f utf8 -t latin1 hamdeps.txt)
451 Default: None. Option: ``--record-dependencies``.
456 Report system messages at or higher than <level>:
464 Default: warning (2).
465 Options: ``--report, -r, --verbose, -v, --quiet, -q``.
470 Enable or disable automatic section numbering by Docutils
471 (docutils.transforms.parts.SectNum) associated with the `sectnum
474 If disabled, section numbers might be added to the output by the
475 renderer (e.g. LaTeX or via a CSS style definition).
477 Default: enabled (1).
478 Options: ``--section-numbering``, ``--no-section-numbering``.
480 .. _sectnum directive: ../ref/rst/directives.html#sectnum
485 Include a "View document source" link in the document footer. URL will
486 be relative to the destination.
488 Default: don't (None).
489 Options: ``--source-link, -s, --no-source-link``.
494 An explicit URL for a "View document source" link, used verbatim.
496 Default: compute if source_link (None).
497 Options: ``--source-url, --no-source-link``.
502 When processing a document tree with the Visitor pattern, raise an
503 error if a writer does not support a node type listed as optional. For
504 transitional development use.
506 Default: disabled (None).
507 Option: ``--strict-visitor`` (hidden, for development use only).
512 Comma-separated list_ of "classes" attribute values to remove from all
513 elements in the document tree. The command line option may be used more
516 .. WARNING:: Potentially dangerous; use with caution.
518 Default: disabled (None). Option: ``--strip-class``.
523 Enable the removal of comment elements from the document tree.
525 Default: disabled (None).
526 Options: ``--strip-comments``, ``--leave-comments``.
528 strip_elements_with_classes
529 ---------------------------
531 Comma-separated list_ of "classes" attribute values;
532 matching elements are removed from the document tree.
533 The command line option may be used more than once.
535 .. WARNING:: Potentially dangerous; use with caution.
537 Default: disabled (None). Option: ``--strip-element-with-class``.
542 The document title as metadata, which does not become part of the
543 document body. It overrides a document-supplied title. For
544 example, in HTML output the metadata document title appears in the
545 title bar of the browser window.
547 Default: none. Option: ``--title``.
552 Enable backlinks from section titles to table of contents entries
553 ("entry"), to the top of the TOC ("top"), or disable ("none").
556 Options: ``--toc-entry-backlinks, --toc-top-backlinks, --no-toc-backlinks``.
561 Enable Python tracebacks when halt-level system messages and other
562 exceptions occur. Useful for debugging, and essential for issue
563 reports. Exceptions are allowed to propagate, instead of being
564 caught and reported (in a user-friendly way) by Docutils.
566 Default: disabled (None) unless Docutils is run programmatically
567 using the `Publisher Interface`_.
568 Options: ``--traceback, --no-traceback``.
570 .. _Publisher Interface: ../api/publisher.html
575 Path to a file for the output of system messages (warnings) [#pwd]_.
577 Default: stderr (None). Options: ``--warnings``.
583 Docutils currently supports only one parser, for reStructuredText.
586 [restructuredtext parser]
587 -------------------------
589 file_insertion_enabled
590 ~~~~~~~~~~~~~~~~~~~~~~
592 Enable or disable directives that insert the contents of external
593 files, such as the "include_" & "raw_". A "warning" system
594 message (including the directive text) is inserted instead. (See
595 also raw_enabled_ for another security-relevant setting.)
597 Default: enabled (1).
598 Options: ``--file-insertion-enabled, --no-file-insertion``.
600 .. _include: ../ref/rst/directives.html#include
601 .. _raw: ../ref/rst/directives.html#raw
606 Recognize and link to standalone PEP references (like "PEP 258").
608 Default: disabled (None); enabled (1) in PEP Reader.
609 Options: ``--pep-references``.
613 Base URL for PEP references.
615 Default: "http://www.python.org/peps/".
616 Option: ``--pep-base-url``.
618 pep_file_url_template
619 ~~~~~~~~~~~~~~~~~~~~~
621 Template for PEP file part of URL, interpolated with the PEP
622 number and appended to pep_base_url_.
624 Default: "pep-%04d". Option: ``--pep-file-url``.
629 Enable or disable the "raw_" directive. A "warning" system message
630 (including the directive text) is inserted instead. (See also
631 file_insertion_enabled_ for another security-relevant setting.)
633 Default: enabled (1). Options: ``--raw-enabled, --no-raw``.
638 Recognize and link to standalone RFC references (like "RFC 822").
640 Default: disabled (None); enabled (1) in PEP Reader.
641 Options: ``--rfc-references``.
646 Base URL for RFC references.
648 Default: "http://www.faqs.org/rfcs/". Option: ``--rfc-base-url``.
653 Change straight quotation marks to typographic form. `Quote characters`_
654 are selected according to the language of the current block element (see
655 language_code_). Also changes consequtive runs of hyphen-minus and full
656 stops (``---``, ``--``, ``...``) to em-dash, en-dash and ellipsis Unicode
657 characters respectively.
664 alt (or "alternative")
665 Use alternative quote set (if defined for the language).
667 Default: "no". Option: ``--smart-quotes``.
669 New in Docutils 0.10.
671 .. _quote characters:
672 http://en.wikipedia.org/wiki/Non-English_usage_of_quotation_marks
677 Token type names used by Pygments_ when parsing contents of the code_
683 Use hierarchy of long token type names.
685 Use short token type names. (For use with
686 `Pygments-generated stylesheets`_.)
688 No code parsing. Use this to avoid the "Pygments not
689 found" warning when Pygments is not installed.
691 Default: "long". Option: ``--syntax-highlight``.
695 .. _Pygments: http://pygments.org/
696 .. _code: ../ref/rst/directives.html#code
697 .. _Pygments-generated stylesheets:
698 http://pygments.org/docs/cmdline/#generating-styles
703 Number of spaces for hard tab expansion.
705 Default: 8. Options: ``--tab-width``.
707 trim_footnote_reference_space
708 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
710 Remove spaces before footnote references.
712 Default: don't (None); may be overriden by a writer-specific
713 footnote_references__ default though.
715 Options: ``--trim-footnote-reference-space, --leave-footnote-reference-space``.
717 __ `footnote_references [latex2e writer]`_
730 Enable or disable the bibliographic field list transform
731 (docutils.transforms.frontmatter.DocInfo).
733 Default: enabled (1). Options: ``--no-doc-info``.
738 Enable or disable the promotion of a lone top-level section title
739 to document title (and subsequent section title to document
740 subtitle promotion; docutils.transforms.frontmatter.DocTitle).
742 Default: enabled (1). Options: ``--no-doc-title``.
747 Enable or disable the promotion of the title of a lone subsection
748 to a subtitle (docutils.transforms.frontmatter.SectSubTitle).
750 Default: disabled (0). Options: ``--section-subtitles,
751 --no-section-subtitles``.
757 The `pep_references`_ and `rfc_references`_ settings
758 (`[restructuredtext parser]`_) are set on by default.
770 [docutils_xml writer]
771 ---------------------
775 * In Python versions older than 2.7.3 and 3.2.3, the newlines_ and
776 indents_ options may adversely affect whitespace; use them only for
777 reading convenience (see http://bugs.python.org/issue4147).
779 * The XML declaration carries text encoding information, without which
780 standard tools may be unable to read the generated XML.
785 Generate XML with a DOCTYPE declaration.
787 Default: do (1). Options: ``--no-doctype``.
792 Generate XML with indents and newlines.
794 Default: don't (None). Options: ``--indents``.
799 Generate XML with newlines before and after tags.
801 Default: don't (None). Options: ``--newlines``.
803 .. _xml_declaration [docutils_xml writer]:
808 Generate XML with an XML declaration. Also defined for the
811 Default: do (1). Options: ``--no-xml-declaration``.
813 __ `xml_declaration [html4css1 writer]`_
819 .. _attribution [html4css1 writer]:
824 Format for block quote attributions: one of "dash" (em-dash
825 prefix), "parentheses"/"parens", or "none". Also defined for the
826 `LaTeX Writer <attribution [latex2e writer]_>`__.
828 Default: "dash". Options: ``--attribution``.
830 cloak_email_addresses
831 ~~~~~~~~~~~~~~~~~~~~~
833 Scramble email addresses to confuse harvesters. In the reference
834 URI, the "@" will be replaced by %-escapes (as of RFC 1738). In
835 the visible text (link text) of an email reference, the "@" and
836 all periods (".") will be surrounded by ``<span>`` tags.
837 Furthermore, HTML entities are used to encode these characters in
838 order to further complicate decoding the email address. For
839 example, "abc@example.org" will be output as::
841 <a class="reference" href="mailto:abc%40example.org">
842 abc<span>@</span>example<span>.</span>org</a>
844 .. Note:: While cloaking email addresses will have little to no
845 impact on the rendering and usability of email links in most
846 browsers, some browsers (e.g. the ``links`` browser) may decode
847 cloaked email addresses incorrectly.
849 Default: don't cloak (None). Option: ``--cloak-email-addresses``.
854 Remove extra vertical whitespace between items of bullet lists and
855 enumerated lists, when list items are all "simple" (i.e., items
856 each contain one paragraph and/or one "simple" sublist only). The
857 behaviour can be specified directly via "class" attributes (values
858 "compact" and "open") in the document.
860 Default: enabled (1).
861 Options: ``--compact-lists, --no-compact-lists``.
866 Remove extra vertical whitespace between items of field lists that
867 are "simple" (i.e., all field bodies each contain at most one
868 paragraph). The behaviour can be specified directly via "class"
869 attributes (values "compact" and "open") in the document.
871 Default: enabled (1).
872 Options: ``--compact-field-lists, --no-compact-field-lists``.
874 .. _embed_stylesheet [html4css1 writer]:
879 Embed the stylesheet in the output HTML file. The stylesheet file
880 must specified by the stylesheet_path__ setting and must be
881 accessible during processing.
882 Also defined for the `LaTeX Writer <embed_stylesheet [latex2e writer]_>`__.
884 Default: enabled. Options: ``--embed-stylesheet,
887 __ `stylesheet_path [html4css1 writer]`_
892 The maximum width (in characters) for one-column field names. Longer
893 field names will span an entire row of the table used to render the field
894 list. 0 indicates "no limit". See also option_limit_.
896 Default: 14 (i.e. 14 characters). Option: ``--field-name-limit``.
898 .. _footnote_references [html4css1 writer]:
903 Format for footnote references, one of "superscript" or "brackets".
904 Also defined for the `LaTeX Writer <footnote_references [latex2e writer]_>`__.
906 Overrides [#override]_ trim_footnote_reference_space_, if
907 applicable. [#footnote_space]_
909 Default: "brackets". Option: ``--footnote-references``.
914 The initial level for header elements. This does not affect the
915 document title & subtitle; see doctitle_xform_.
917 Default: 1 (for "<h1>"). Option: ``--initial-header-level``.
922 The format of mathematical content (`math directive`_ and role) in
923 the output document. Supported values are (case insensitive):
926 Format math in standard HTML enhanced by CSS rules.
927 Requires the ``math.css`` stylesheet (in the system
928 `stylesheet directory <stylesheet_dirs [html4css1 writer]_>`_
930 A `stylesheet_path <stylesheet_path [html4css1 writer]_>`_
931 can be appended after whitespace, the specified
932 stylesheet(s) will only be referenced or embedded, if required
933 (i.e. if there is mathematical content in the document).
936 Format math for display with MathJax_, a JavaScript-based math
937 rendering engine that uses HTML/CSS, JavaScript, and unicode
938 fonts for high-quality typesetting that is scalable and prints
942 Works 'out of the box' across multiple browsers and platforms.
944 Supports a large subset of LaTeX math commands and constructs
945 (see http://www.mathjax.org/docs/1.1/tex.html).
948 Requires an Internet connection (or a local MathJax
949 installation and configuration).
951 Downloads JavaScript code from a third-party site.
953 A custom URI can be appended after whitespace,
954 for example a local installation ::
956 math-output: MathJax file:/usr/share/javascript/mathjax/MathJax.js
958 or a URI to `access the MathJax CDN using a https secure
961 __ http://www.mathjax.org/resources/faqs/#problem-https
964 Embed math content as presentational MathML_.
967 The W3C recommendation for math on the web.
969 Self-contained documents (no JavaScript, no external downloads).
972 Docutil's latex2mathml converter supports only a small
973 subset of LaTeX syntax.
975 With the "html4css1" writer, the resulting HTML document does
976 not validate, as there is no DTD for MathML + XHTML
977 Transitional. However, MathML-enabled browsers will render it
981 Include literal LaTeX code.
983 The failsave fallback.
985 Default: "HTML math.css". Option: ``--math-output``.
989 .. _math directive: ../ref/rst/directives.html#math
990 .. _MathJax: http://www.mathjax.org/
991 .. _MathPlayer: http://www.dessci.com/en/products/mathplayer/
992 .. _MathML: http://www.w3.org/TR/MathML/
997 The maximum width (in characters) for options in option lists.
998 Longer options will span an entire row of the table used to render
999 the option list. 0 indicates "no limit". See also
1002 Default: 14 (i.e. 14 characters). Option: ``--option-limit``.
1004 .. _stylesheet [html4css1 writer]:
1009 A comma-separated list of CSS stylesheet URLs, used verbatim.
1010 Also defined for the `LaTeX Writer <stylesheet [latex2e writer]_>`__.
1012 Overrides also stylesheet-path__. [#override]_
1014 Default: None. Options: ``--stylesheet``.
1016 __ `stylesheet_path [html4css1 writer]`_
1018 .. _stylesheet_dirs [html4css1 writer]:
1023 A comma-separated list of directories where stylesheets can be found.
1024 Used by the stylesheet_path__ setting when expanding relative path arguments.
1026 Note: This setting defines a "search path" (similar to the PATH variable for
1027 executables). However, the term "path" is already used in the
1028 stylesheet_path__ setting with the meaning of a file location.
1031 __ `stylesheet_path [html4css1 writer]`_
1033 Default: the working directory of the process at launch and the directory
1034 with default stylesheet files (writer and installation specific).
1035 Use the ``--help`` option to get the exact value.
1036 Option: ``--stylesheet-directories``.
1038 .. _stylesheet_path [html4css1 writer]:
1043 A comma-separated list of paths to CSS stylesheets. Relative paths are
1044 expanded if a matching file is found in the stylesheet_dirs__.
1045 If embed_stylesheet__ is False, paths are rewritten relative to the
1046 output HTML file. Also defined for the `LaTeX Writer`__.
1048 Also overrides "stylesheet". [#override]_
1049 Pass an empty string (to either "stylesheet" or "stylesheet_path") to
1050 deactivate stylesheet inclusion.
1052 Default: "html4css1.css".
1053 Options: ``--stylesheet-path``.
1055 __ `embed_stylesheet [html4css1 writer]`_
1056 __ `stylesheet_path [latex2e writer]`_
1057 __ `stylesheet_dirs [html4css1 writer]`_
1059 .. _table_style [html4css1 writer]:
1064 Class value(s) added to tables to allow styling with CSS.
1065 The default sylesheet defines:
1068 No borders around the table.
1071 Lines above and below the table and a thin line after the head.
1073 Default: "". Option: ``--table-style``.
1075 .. _template [html4css1 writer]:
1080 Path to template file, which must be encoded in UTF-8 [#pwd]_.
1081 Also defined for the `LaTeX Writer`__.
1083 Default: "template.txt" in the docutils/writers/html4css1/
1084 directory (installed automatically; for the exact machine-specific
1085 path, use the ``--help`` option). Options: ``--template``.
1087 __ `template [latex2e writer]`_
1089 .. _xml_declaration [html4css1 writer]:
1094 Generate XML with an XML declaration. Also defined for the
1095 `Docutils XML Writer`__.
1097 .. Caution:: The XML declaration carries text encoding
1098 information, without which standard tools may be unable to read
1101 Default: do (1). Options: ``--no-xml-declaration``.
1103 __ `xml_declaration [docutils_xml writer]`_
1109 The PEP/HTML Writer derives from the standard HTML Writer, and shares
1110 all settings defined in the `[html4css1 writer]`_ section. The
1111 "[html4css1 writer]" section of configuration files is processed
1112 before the "[pep_html writer]" section.
1114 The PEP/HTML Writer's default for the following settings differ from
1115 those of the standard HTML Writer:
1117 `stylesheet_path <stylesheet_path [html4css1 writer]_>`_:
1120 `template <template [html4css1 writer]_>`_:
1121 Default: ``docutils/writers/pep_html/template.txt`` in the installation
1122 directory. For the exact machine-specific path, use the ``--help``
1127 Do not use a random banner image. Mainly used to get predictable
1128 results when testing.
1130 Default: random enabled (None). Options: ``--no-random`` (hidden).
1135 Home URL prefix for PEPs.
1137 Default: current directory ("."). Options: ``--pep-home``.
1143 Default: parent directory (".."). Options: ``--python-home``.
1149 The S5/HTML Writer derives from the standard HTML Writer, and shares
1150 all settings defined in the `[html4css1 writer]`_ section. The
1151 "[html4css1 writer]" section of configuration files is processed
1152 before the "[s5_html writer]" section.
1154 The S5/HTML Writer's default for the following settings differ
1155 from those of the standard HTML Writer:
1158 Default: disable compact lists.
1161 Default: ``docutils/writers/s5_html/template.txt`` in the installation
1162 directory. For the exact machine-specific path, use the ``--help``
1169 Auto-hide the presentation controls in slideshow mode, or or keep
1170 them visible at all times.
1172 Default: auto-hide (1). Options: ``--hidden-controls``,
1173 ``--visible-controls``.
1178 Enable or disable the current slide indicator ("1/15").
1180 Default: disabled (None). Options: ``--current-slide``,
1181 ``--no-current-slide``.
1183 overwrite_theme_files
1184 """""""""""""""""""""
1186 Allow or prevent the overwriting of existing theme files in the
1187 ``ui/<theme>`` directory. This has no effect if "theme_url_" is
1190 Default: keep existing theme files (None). Options:
1191 ``--keep-theme-files``, ``--overwrite-theme-files``.
1196 Name of an installed S5 theme, to be copied into a ``ui/<theme>``
1197 subdirectory, beside the destination file (output HTML). Note
1198 that existing theme files will not be overwritten; the existing
1199 theme directory must be deleted manually.
1200 Also overrides the "theme_url_" setting. [#override]_
1202 Default: "default". Option: ``--theme``.
1206 The URL of an S5 theme directory. The destination file (output
1207 HTML) will link to this theme; nothing will be copied. Also overrides
1208 the "theme_" setting. [#override]_
1210 Default: None. Option: ``--theme-url``.
1215 The initial view mode, either "slideshow" or "outline".
1217 Default: "slidewhow". Option: ``--view-mode``.
1226 To get pagenumbers in the table of contents the table of contents
1227 must be generated by LaTeX. Usually latex must be run twice to get
1230 Default: on. Options: ``--use-latex-toc, --use-docutils-toc``.
1235 Attach author and date to the document title
1236 instead of the document info table.
1238 Default: off. Options: ``--use-latex-docinfo, --use-docutils-docinfo``.
1242 Use the Docutils-specific macros ``\DUfootnote`` and
1243 ``\DUfootnotetext`` for footnotes.
1245 Default: on. Option: ``--docutils-footnotes``.
1250 Typeset footnote text in a figure float. This may lead to footnotes,
1251 citations, and figures being mixed at page foot.
1253 *Deprecated:* This setting will be removed in a future Docutils
1256 Default: off. Option: ``--figure-footnotes``.
1261 Use \cite for citations instead of a simulation with figure-floats.
1263 Default: off. Options: ``--use-latex-citations, --figure-citations``.
1268 Use LaTeX abstract environment for the document's abstract.
1270 Default: off. Options: ``--use-latex-abstract, --topic-abstract``.
1275 Color of any hyperlinks embedded in text.
1277 * "0" or "false" disable coloring of links. (Links will be marked
1278 by red boxes that are not printed),
1279 * "black" results in “invisible“ links,
1281 Set hyperref_options_ to "draft" to completely disable hyperlinking.
1283 Default: "blue". Option: ``--hyperlink-color``.
1288 Options for the `hyperref TeX package`_. If hyperlink_color_ is
1289 not "false", the expansion of ::
1291 'colorlinks=true,linkcolor=%s,urlcolor=%s' % (
1292 hyperlink_color, self.hyperlink_color
1296 Default: "". Option: ``--hyperref-options``.
1298 .. _hyperref TeX package: http://tug.org/applications/hyperref/
1303 Specify latex documentclass.
1305 Default: "article". Option: ``--documentclass``.
1310 Specify document options. Multiple options can be given, separated by
1313 Default: "a4paper". Option: ``--documentoptions``.
1318 Specify LaTeX font encoding. Multiple options can be given, separated by
1319 commas. The last value becomes the document default.
1320 Possible values are "", "T1", "OT1", "LGR,T1" or any other combination of
1321 `LaTeX font encodings`_.
1323 Default: "T1". Option: ``--font-encoding``.
1325 .. _LaTeX font encodings:
1326 http://mirror.ctan.org/macros/latex/doc/encguide.pdf
1328 .. _embed_stylesheet [latex2e writer]:
1333 Embed the stylesheet(s) in the header of the output file. The
1334 stylesheets must be accessible during processing. Currently, this
1335 fails if the file is not available via the given path (i.e. the
1336 file is *not* searched in the `TeX input path`_).
1337 Also defined for the `HTML Writer`__ (with default *on*).
1339 Default: off. Options: ``--embed-stylesheet, --link-stylesheet``.
1341 __ `embed_stylesheet [html4css1 writer]`_
1343 .. _stylesheet [latex2e writer]:
1348 A comma-separated list_ of style files.
1349 Also defined for the `HTML Writer`__.
1351 Overrides also stylesheet_path__. [#override]_
1353 If `embed_stylesheet`__ is False (default), the stylesheet files are
1354 referenced with ``\usepackage`` (extension ``.sty`` or no extension) or
1355 ``\input`` (any other extension).
1357 LaTeX will search the specified files in the `TeX input path`_.
1359 Default: no stylesheet (""). Option: ``--stylesheet``.
1361 __ `stylesheet_path [latex2e writer]`_
1362 __ `embed_stylesheet [latex2e writer]`_
1363 __ `stylesheet [html4css1 writer]`_
1365 http://www.tex.ac.uk/cgi-bin/texfaq2html?label=what-TDS
1368 .. _stylesheet_dirs [latex2e writer]:
1373 A comma-separated list of directories where stylesheets can be found.
1374 Used by the stylesheet_path__ setting.
1376 Note: This setting defines a "search path" (similar to the PATH variable for
1377 executables). However, the term "path" is already used in the
1378 stylesheet_path__ setting with the meaning of a file location.
1381 __ `stylesheet_path [latex2e writer]`_
1383 Default: the working directory of the process at launch and the directory
1384 with default stylesheet files (writer and installation specific).
1385 Use the ``--help`` option to get the exact value.
1386 Option: ``--stylesheet-directories``.
1388 .. _stylesheet_path [latex2e writer]:
1393 A comma-separated list of style files. Relative paths are expanded if a
1394 matching file is found in the stylesheet_dirs__.
1395 If embed_stylesheet__ is False, paths are rewritten relative to the
1396 output file path. Run ``latex`` from the directory containing
1399 The stylesheet__ option is preferred for files in the `TeX input path`_.
1401 Also defined for the
1402 `HTML Writer <stylesheet_path [html4css1 writer]_>`__.
1404 Also overrides stylesheet__. [#override]_
1406 Default: no stylesheet (""). Option: ``--stylesheet-path``.
1408 __ `stylesheet_dirs [latex2e writer]`_
1409 __ `embed_stylesheet [latex2e writer]`_
1411 __ `stylesheet [latex2e writer]`_
1417 LaTeX code that will be inserted in the document preamble.
1418 Can be used to load packages with options or (re-) define LaTeX
1419 macros without writing a custom style file (new in Docutils 0.7).
1421 Default: Load the "PDF standard fonts" (Times, Helvetica,
1424 \usepackage{mathptmx} % Times
1425 \usepackage[scaled=.90]{helvet}
1426 \usepackage{courier}
1428 Option: ``--latex-preamble``.
1431 .. _template [latex2e writer]:
1436 Path to template file, which must be encoded in UTF-8 [#pwd]_.
1437 Also defined for the `HTML Writer`__.
1439 Default: "default.tex" in the docutils/writers/latex2e/
1440 directory (installed automatically; for the exact machine-specific
1441 path, use the ``--help`` option). Options: ``--template``.
1443 __ `template [html4css1 writer]`_
1445 .. _footnote_references [latex2e writer]:
1450 Format for footnote references: one of "superscript" or
1451 "brackets". Also defined for the `HTML Writer`__.
1453 Overrides [#override]_ trim_footnote_reference_space_, if
1454 applicable [#footnote_space]_.
1456 Default: "superscript". Option: ``--footnote-references``.
1458 __ `footnote_references [html4css1 writer]`_
1460 .. _attribution [latex2e writer]:
1465 See `attribution [html4css1 writer]`_.
1467 compound_enumerators
1468 ~~~~~~~~~~~~~~~~~~~~
1470 Enable or disable compound enumerators for nested enumerated lists
1473 Default: disabled (None).
1474 Options: ``--compound-enumerators``, ``--no-compound-enumerators``.
1479 When possibile\ [#]_, use the specified environment for literal-blocks.
1481 Default: "" (quoting of whitespace and special chars).
1482 Option: ``--literal-block-env``.
1484 .. [#] A literal-block element, when processed by a Docutils writer might
1485 have it's origin in literal block following "::" or a
1486 ``.. parsed-literal::`` directive.
1488 A LaTeX verbatim environment is only usable if there is no other
1489 markup contained in the literal-block.
1492 section_prefix_for_enumerators
1493 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1495 Enable or disable section ("." subsection ...) prefixes for
1496 compound enumerators. This has no effect unless
1497 `compound_enumerators`_ are enabled.
1499 Default: disabled (None).
1500 Options: ``--section-prefix-for-enumerators``,
1501 ``--no-section-prefix-for-enumerators``.
1503 section_enumerator_separator
1504 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1506 The separator between section number prefix and enumerator for
1507 compound enumerated lists (see `compound_enumerators`_).
1509 Generally it isn't recommended to use both sub-sections and nested
1510 enumerated lists with compound enumerators. This setting avoids
1511 ambiguity in the situation where a section "1" has a list item
1512 enumerated "1.1", and subsection "1.1" has list item "1". With a
1513 separator of ".", these both would translate into a final compound
1514 enumerator of "1.1.1". With a separator of "-", we get the
1515 unambiguous "1-1.1" and "1.1-1".
1517 Default: "-". Option: ``--section-enumerator-separator``.
1519 .. _table_style [latex2e writer]:
1524 Specify the drawing of separation lines.
1528 lines around and between cells.
1530 a line above and below the table and one after the head.
1534 Default: "standard". Option: ``--table-style``.
1539 The xetex writer derives from the latex2e writer, and shares
1540 all settings defined in the `[latex2e writer]`_ section. The
1541 "[latex2e writer]" section of configuration files is processed
1542 before the "[xetex writer]" section.
1544 The following settings differ from those of the latex2e writer:
1547 Disabled (XeTeX uses Unicode-encoded fonts).
1550 Default: Font setup for `Linux Libertine`_,::
1552 % Linux Libertine (free, wide coverage, not only for Linux)
1553 \setmainfont{Linux Libertine O}
1554 \setsansfont{Linux Biolinum O}
1555 \setmonofont[HyphenChar=None]{DejaVu Sans Mono}
1557 The optional argument ``HyphenChar=None`` to the monospace font
1558 prevents word hyphenation in literal text.
1561 Default: "xelatex.tex"
1563 .. _Linux Libertine: http://www.linuxlibertine.org/
1564 __ `template [latex2e writer]`_
1570 The following command line options are specific to ``odtwriter``:
1575 Specify a stylesheet URL, used verbatim.
1577 Default: writers/odf_odt/styles.odt in the installation directory.
1582 Specify a configuration/mapping file relative to the current working
1583 directory for additional ODF options. In particular, this file may
1584 contain a section named "Formats" that maps default style names to names
1585 to be used in the resulting output file allowing for adhering to external
1586 standards. For more info and the format of the configuration/mapping
1587 file, see the `Odt Writer for Docutils`_ document.
1589 cloak-email-addresses
1590 ~~~~~~~~~~~~~~~~~~~~~
1592 Obfuscate email addresses to confuse harvesters while still
1593 keeping email links usable with standards-compliant browsers.
1595 no-cloak-email-addresses
1596 ~~~~~~~~~~~~~~~~~~~~~~~~
1597 Do not obfuscate email addresses.
1599 table-border-thickness
1600 ~~~~~~~~~~~~~~~~~~~~~~
1602 Specify the thickness of table borders in thousands of a cm.
1605 add-syntax-highlighting
1606 ~~~~~~~~~~~~~~~~~~~~~~~
1608 Add syntax highlighting in literal code blocks.
1610 no-syntax-highlighting
1611 ~~~~~~~~~~~~~~~~~~~~~~
1613 Do not add syntax highlighting in literal code blocks.
1619 Create sections for headers. (default)
1624 Do not create sections for headers.
1633 Do not create links. (default)
1638 Generate endnotes at end of document, not footnotes at bottom of page.
1643 Generate footnotes at bottom of page, not endnotes at end of
1649 Generate a bullet list table of contents, not an
1650 ODF/``oowriter`` table of contents.
1652 generate-oowriter-toc
1653 ~~~~~~~~~~~~~~~~~~~~~
1655 Generate an ODF/``oowriter`` table of contents, not a bullet
1656 list. (default) **Note:** ``odtwriter`` is not able to
1657 determine page numbers, so you will need to open the generated
1658 document in ``oowriter``, then right-click on the table of
1659 contents and select "Update" to insert page numbers.
1664 Specify the contents of a custom header line. For details about
1665 custom headers and about special field character sequences, see
1666 section "Custom header/footers: inserting page numbers, date,
1667 time, etc" in the `Odt Writer for Docutils`_ document for
1673 Specify the contents of a custom footer line. For details about
1674 custom footers and about special field character sequences, see
1675 section "Custom header/footers: inserting page numbers, date,
1676 time, etc" in the `Odt Writer for Docutils`_ document for
1679 .. _Odt Writer for Docutils: odt.html
1685 This writer does not define specific settings.
1691 [buildhtml application]
1692 -----------------------
1697 List_ of wildcard (shell globing) patterns, specifying files to silently
1698 ignore. To specify multiple patterns, use colon-separated patterns (in
1699 configuration files or on the command line); on the command line, the
1700 option may also be used more than once.
1702 Default: none. Options: ``--ignore``.
1707 List_ of directories not to process. To specify multiple
1708 directories, use colon-separated paths (in configuration files or
1709 on the command line); on the command line, the option may also be
1710 used more than once.
1712 Default: ['.hg', '.bzr', '.git', '.svn', 'CVS']. Options:
1718 Recursively scan subdirectories, or ignore subdirectories.
1720 Default: recurse (1). Options: ``--recurse, --local``.
1725 Work silently (no progress messages). Independent of
1728 Default: show progress (None). Options: ``--silent``.
1731 [docfactory application]
1732 ------------------------
1743 These settings are only effective as command-line options; setting
1744 them in configuration files has no effect.
1749 Path to a configuration file to read (if it exists) [#pwd]_.
1750 Settings may override defaults and earlier settings. The config
1751 file is processed immediately. Multiple ``--config`` options may
1752 be specified; each will be processed in turn.
1754 Filesystem path settings contained within the config file will be
1755 interpreted relative to the config file's location (*not* relative
1756 to the current working directory).
1758 Default: None. Options: ``--config``.
1764 These settings are for internal use only; setting them in
1765 configuration files has no effect, and there are no corresponding
1766 command-line options.
1771 List of paths of applied configuration files.
1773 Default: None. No command-line options.
1778 (``buildhtml.py`` front end.) List of paths to source
1779 directories, set from positional arguments.
1781 Default: current working directory (None). No command-line
1787 Prevent standard configuration files from being read. For
1788 programmatic use only.
1790 Default: config files enabled (None). No command-line options.
1795 Path to output destination, set from positional arguments.
1797 Default: stdout (None). No command-line options.
1802 Path to input source, set from positional arguments.
1804 Default: stdin (None). No command-line options.
1807 .. _language tag: http://www.w3.org/International/articles/language-tags/
1808 .. _BCP 47: http://www.rfc-editor.org/rfc/bcp/bcp47.txt
1809 .. _ISO 639: http://www.loc.gov/standards/iso639-2/php/English_list.php
1810 .. _ISO 3166: http://www.iso.ch/iso/en/prods-services/iso3166ma/
1811 02iso-3166-code-lists/index.html
1813 .. [#pwd] Path relative to the working directory of the process at
1816 .. [#override] The overridden setting will automatically be set to
1817 ``None`` for command-line options and config file settings. Client
1818 programs which specify defaults that override other settings must
1819 do the overriding explicitly, by assigning ``None`` to the other
1822 .. [#dependencies] Images are only added to the dependency list if the
1823 reStructuredText parser extracted image dimensions from the file.
1825 .. [#footnote_space] The footnote space is trimmed if the reference
1826 style is "superscript", and it is left if the reference style is
1829 The overriding only happens if the parser supports the
1830 trim_footnote_reference_space option.
1833 ------------------------------
1834 Old-Format Configuration Files
1835 ------------------------------
1837 Formerly, Docutils configuration files contained a single "[options]"
1838 section only. This was found to be inflexible, and in August 2003
1839 Docutils adopted the current component-based configuration file
1840 sections as described above. Docutils will still recognize the old
1841 "[options]" section, but complains with a deprecation warning.
1843 To convert existing config files, the easiest way is to change the
1844 section title: change "[options]" to "[general]". Most settings
1845 haven't changed. The only ones to watch out for are these:
1847 ===================== =====================================
1848 Old-Format Setting New Section & Setting
1849 ===================== =====================================
1850 pep_stylesheet [pep_html writer] stylesheet
1851 pep_stylesheet_path [pep_html writer] stylesheet_path
1852 pep_template [pep_html writer] template
1853 ===================== =====================================