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)
95 List values are comma-delimited. Whitespace around list values is
98 strip-classes: ham,eggs,
99 strip-elements-with-classes: sugar, salt, flour
100 stylesheet: html4css1.css,
102 style with spaces.css
103 stylesheet-path: ../styles/my.css, ../styles/funny.css
105 expose_internals_ and prune_ use the colon as delimiter and do not strip
108 expose_internals: b:c:d
114 This is the contents of the ``tools/docutils.conf`` configuration file
115 supplied with Docutils::
117 # These entries affect all processing:
120 datestamp: %Y-%m-%d %H:%M UTC
123 # These entries affect HTML output:
125 # Required for docutils-update, the website build system:
126 stylesheet-path: ../docutils/writers/html4css1/html4css1.css
130 Individual configuration sections and settings are described in the
134 -------------------------------------
135 Configuration File Sections & Entries
136 -------------------------------------
138 Below are the Docutils runtime settings, listed by config file
139 section. Any setting may be specified in any section, but only
140 settings from active sections will be used. Sections correspond to
141 Docutils components (module name or alias; section names are always in
142 lowercase letters). Each `Docutils application`_ uses a specific set
143 of components; corresponding configuration file sections are applied
144 when the application is used. Configuration sections are applied in
145 general-to-specific order, as follows:
149 2. `[parsers]`_, parser dependencies, and the section specific to the
150 Parser used ("[... parser]"). Currently, only `[restructuredtext
151 parser]`_ is applicable.
153 3. `[readers]`_, reader dependencies, and the section specific to the
154 Reader used ("[... reader]"). For example, `[pep reader]`_ depends
155 on `[standalone reader]`_.
157 4. `[writers]`_, writer dependencies, and the section specific to the
158 Writer used ("[... writer]"). For example, `[pep_html writer]`_
159 depends on `[html4css1 writer]`_.
161 5. `[applications]`_, application dependencies, and the section
162 specific to the Application (front-end tool) in use
163 ("[... application]").
165 Since any setting may be specified in any section, this ordering
166 allows component- or application-specific overrides of earlier
167 settings. For example, there may be Reader-specific overrides of
168 general settings; Writer-specific overrides of Parser settings;
169 Application-specific overrides of Writer settings; and so on.
171 If multiple configuration files are applicable, the process is
172 completed (all sections are applied in the order given) for each one
173 before going on to the next. For example, a "[pep_html writer]
174 stylesheet" setting in an earlier configuration file would be
175 overridden by an "[html4css1 writer] stylesheet" setting in a later
178 Some knowledge of Python_ is assumed for some attributes.
181 http://www.python.org/doc/current/lib/module-ConfigParser.html
182 .. _Python: http://www.python.org/
183 .. _RFC 822: http://www.rfc-editor.org/rfc/rfc822.txt
184 .. _Docutils application: tools.html
190 Settings in the "[general]" section are always applied.
193 Prefix prepended to all auto-generated IDs generated within the
194 document, after id_prefix_.
196 Default: "id". Options: ``--auto-id-prefix`` (hidden, intended
197 mainly for programmatic use).
200 Include a time/datestamp in the document footer. Contains a
201 format string for Python's ``time.strftime``. See the `time
202 module documentation`__.
204 Default: None. Options: ``--date, -d, --time, -t,
207 Configuration file entry examples::
209 # Equivalent to --date command-line option, results in
210 # ISO 8601 extended format datestamp, e.g. "2001-12-21":
213 # Equivalent to --time command-line option, results in
214 # date/timestamp like "2001-12-21 18:43 UTC":
215 datestamp: %Y-%m-%d %H:%M UTC
217 # Disables datestamp; equivalent to --no-datestamp:
220 __ http://www.python.org/doc/current/lib/module-time.html
223 Report debug-level system messages.
225 Default: don't (None). Options: ``--debug, --no-debug``.
228 At the end of processing, write all internal attributes of the
229 document (``document.__dict__``) to stderr.
231 Default: don't (None). Options: ``--dump-internals`` (hidden, for
232 development use only).
235 At the end of processing, write the pseudo-XML representation of
236 the document to stderr.
238 Default: don't (None). Options: ``--dump-pseudo-xml`` (hidden,
239 for development use only).
242 At the end of processing, write all Docutils settings to stderr.
244 Default: don't (None). Options: ``--dump-settings`` (hidden, for
245 development use only).
248 At the end of processing, write a list of all transforms applied
249 to the document to stderr.
251 Default: don't (None). Options: ``--dump-transforms`` (hidden,
252 for development use only).
255 The text encoding for error output.
257 Default: "ascii". Options: ``--error-encoding, -e``.
259 _`error_encoding_error_handler`
260 The error handler for unencodable characters in error output. See
261 output_encoding_error_handler_ for acceptable values.
263 Default: "backslashreplace"
264 Options: ``--error-encoding-error-handler,
265 --error-encoding, -e``.
268 A system message level threshold; non-halting system messages at
269 or above this level will produce a non-zero exit status at normal
270 exit. Exit status is the maximum system message level plus 10 (11
273 Default: disabled (5). Options: ``--exit-status``.
276 List of internal attribues to expose as external attributes (with
277 "internal:" namespace prefix). To specify multiple attributes in
278 configuration files, use colons to separate names; on the command
279 line, the option may be used more than once.
281 Default: don't (None). Options: ``--expose-internal-attribute``
282 (hidden, for development use only).
284 _`footnote_backlinks`
285 Enable or disable backlinks from footnotes and citations to their
288 Default: enabled (1). Options: ``--footnote-backlinks,
289 --no-footnote-backlinks``.
292 Include a "Generated by Docutils" credit and link in the document
295 Default: off (None). Options: ``--generator, -g,
299 The threshold at or above which system messages are converted to
300 exceptions, halting execution immediately. If `traceback`_ is
301 set, the exception will propagate; otherwise, Docutils will exit.
303 Default: severe (4). Options: ``--halt, --strict``.
306 Prefix prepended to all IDs generated within the document. See
307 also auto_id_prefix_.
309 Default: "" (empty). Options: ``--id-prefix`` (hidden, intended
310 mainly for programmatic use).
313 The text encoding for input.
315 Default: auto-detect (None). Options: ``--input-encoding, -i``.
317 _`input_encoding_error_handler`
318 The error handler for undecodable characters in the input.
319 Acceptable values include:
322 Raise an exception in case of an encoding error.
324 Replace malformed data with the official Unicode replacement
327 Ignore malformed data and continue without further notice.
329 Acceptable values are the same as for the "error" parameter of
330 Python's ``unicode`` function; other values may be defined in
331 applications or in future versions of Python.
333 Default: "strict". Options: ``--input-encoding-error-handler,
334 --input-encoding, -i``.
337 Case-insensitive `language tag`_ as defined in `BCP 47`_.
339 Sets the document language, also used for localized directive and
340 role names as well as Docutils-generated text.
342 A typical language identifier consists of a 2-letter language code
343 from `ISO 639`_ (3-letter codes can be used if no 2-letter code
344 exists). The language identifier can have an optional subtag,
345 typically for variations based on country (from `ISO 3166`_
346 2-letter country codes). Avoid subtags except where they add
347 useful distinguishing information. Examples of language tags
348 include "fr", "en-GB", "pt_br" (the same as "pt-BR"), and
349 "de-1901" (German with pre-1998 spelling).
351 The language of document parts can be specified with a
352 "language-<language tag>" `class attribute`_, e.g.
353 ``.. class:: language-el-polyton`` for a quote in polytonic Greek.
355 Default: English ("en"). Options: ``--language, -l``.
357 .. _class attribute: ../ref/doctree.html#classes
360 The text encoding for output.
362 Default: "UTF-8". Options: ``--output-encoding, -o``.
364 _`output_encoding_error_handler`
365 The error handler for unencodable characters in the output.
366 Acceptable values include:
369 Raise an exception in case of an encoding error.
371 Replace malformed data with a suitable replacement marker,
374 Ignore malformed data and continue without further notice.
376 Replace with the appropriate XML character reference, such as
379 Replace with backslashed escape sequences, such as "``\u2020``".
381 Acceptable values are the same as for the "error" parameter of
382 Python's ``encode`` string method; other values may be defined in
383 applications or in future versions of Python.
385 Default: "strict". Options: ``--output-encoding-error-handler,
386 --output-encoding, -o``.
388 _`record_dependencies`
389 Path to a file where Docutils will write a list of files that were
390 required to generate the output, e.g. included files or embedded
391 stylesheets [#dependencies]_. [#pwd]_ The format is one path per
392 line with forward slashes as separator, the encoding is ``utf8``.
394 Set to ``-`` in order to write dependencies to stdout.
396 This option is particularly useful in conjunction with programs like
397 ``make`` using ``Makefile`` rules like::
399 ham.html: ham.txt $(shell cat hamdeps.txt)
400 rst2html.py --record-dependencies=hamdeps.txt ham.txt ham.html
402 If the filesystem encoding differs from utf8, replace the ``cat``
403 command with a call to a converter, e.g.::
405 $(shell iconv -f utf8 -t latin1 hamdeps.txt)
407 Default: None. Option: ``--record-dependencies``.
410 Report system messages at or higher than <level>:
418 Default: warning (2). Options: ``--report, -r, --verbose, -v,
422 Enable or disable automatic section numbering by Docutils
423 (docutils.transforms.parts.SectNum) associated with the `sectnum
426 If disabled, section numbers might be added to the output by the
427 renderer (e.g. LaTeX or via a CSS style definition).
429 Default: enabled (1). Options: ``--section-numbering``,
430 ``--no-section-numbering``.
432 .. _sectnum directive: ../ref/rst/directives.html#sectnum
435 Include a "View document source" link in the document footer. URL
436 will be relative to the destination.
438 Default: don't (None). Options: ``--source-link, -s,
442 An explicit URL for a "View document source" link, used verbatim.
444 Default: compute if source_link (None). Options: ``--source-url,
448 When processing a document tree with the Visitor pattern, raise an
449 error if a writer does not support a node type listed as optional.
450 For transitional development use.
452 Default: disabled (None). Option: ``--strict-visitor`` (hidden,
453 for development use only).
456 Comma-separated list of "classes" attribute values to remove from
457 all elements in the document tree.
458 The command line option may be used more than once.
460 .. WARNING:: Potentially dangerous; use with caution.
462 Default: disabled (None). Option: ``--strip-class``.
465 Enable the removal of comment elements from the document tree.
467 Default: disabled (None). Options: ``--strip-comments``,
468 ``--leave-comments``.
470 _`strip_elements_with_classes`
471 Comma-separated list of "classes" attribute values;
472 matching elements are removed from the document tree.
473 The command line option may be used more than once.
475 .. WARNING:: Potentially dangerous; use with caution.
477 Default: disabled (None). Option: ``--strip-element-with-class``.
480 The document title as metadata, which does not become part of the
481 document body. It overrides a document-supplied title. For
482 example, in HTML output the metadata document title appears in the
483 title bar of the browser window.
485 Default: none. Option: ``--title``.
488 Enable backlinks from section titles to table of contents entries
489 ("entry"), to the top of the TOC ("top"), or disable ("none").
491 Default: "entry". Options: ``--toc-entry-backlinks,
492 --toc-top-backlinks, --no-toc-backlinks``.
495 Enable Python tracebacks when halt-level system messages and other
496 exceptions occur. Useful for debugging, and essential for issue
497 reports. Exceptions are allowed to propagate, instead of being
498 caught and reported (in a user-friendly way) by Docutils.
500 Default: disabled (None) unless Docutils is run programmatically
501 using the `Publisher Interface`_. Options: ``--traceback,
504 .. _Publisher Interface: ../api/publisher.html
507 Path to a file for the output of system messages (warnings)
510 Default: stderr (None). Options: ``--warnings``.
516 Docutils currently supports only one parser, for reStructuredText.
519 [restructuredtext parser]
520 `````````````````````````
522 _`file_insertion_enabled`
523 Enable or disable directives that insert the contents of external
524 files, such as the "include_" & "raw_". A "warning" system
525 message (including the directive text) is inserted instead. (See
526 also raw_enabled_ for another security-relevant setting.)
528 Default: enabled (1). Options: ``--file-insertion-enabled,
529 --no-file-insertion``.
531 .. _include: ../ref/rst/directives.html#include
532 .. _raw: ../ref/rst/directives.html#raw
535 Recognize and link to standalone PEP references (like "PEP 258").
537 Default: disabled (None); enabled (1) in PEP Reader. Options:
538 ``--pep-references``.
541 Base URL for PEP references.
543 Default: "http://www.python.org/peps/". Option:
546 _`pep_file_url_template`
547 Template for PEP file part of URL, interpolated with the PEP
548 number and appended to pep_base_url_.
550 Default: "pep-%04d". Option: ``--pep-file-url``.
553 Enable or disable the "raw_" directive. A "warning" system
554 message (including the directive text) is inserted instead. (See
555 also file_insertion_enabled_ for another security-relevant
558 Default: enabled (1). Options: ``--raw-enabled, --no-raw``.
561 Recognize and link to standalone RFC references (like "RFC 822").
563 Default: disabled (None); enabled (1) in PEP Reader. Options:
564 ``--rfc-references``.
567 Base URL for RFC references.
569 Default: "http://www.faqs.org/rfcs/". Option: ``--rfc-base-url``.
572 Number of spaces for hard tab expansion.
574 Default: 8. Options: ``--tab-width``.
576 _`trim_footnote_reference_space`
577 Remove spaces before footnote references.
579 Default: don't (None); may be overriden by a writer-specific
580 footnote_references__ default though. Options:
581 ``--trim-footnote-reference-space,
582 --leave-footnote-reference-space``.
584 __ `footnote_references [latex2e writer]`_
589 Token type names used by Pygments_ when parsing contents of the code_
595 Use hierarchy of long token type names.
597 Use short token type names. (For use with
598 `Pygments-generated stylesheets`_.)
600 No code parsing. Use this to avoid the "Pygments not
601 found" warning when Pygments is not installed.
603 Default: "long". Option: ``--syntax-highlight``.
605 .. _Pygments: http://pygments.org/
606 .. _code: ../ref/rst/directives.html#code
607 .. _Pygments-generated stylesheets:
608 http://pygments.org/docs/cmdline/#generating-styles
619 Enable or disable the bibliographic field list transform
620 (docutils.transforms.frontmatter.DocInfo).
622 Default: enabled (1). Options: ``--no-doc-info``.
625 Enable or disable the promotion of a lone top-level section title
626 to document title (and subsequent section title to document
627 subtitle promotion; docutils.transforms.frontmatter.DocTitle).
629 Default: enabled (1). Options: ``--no-doc-title``.
631 _`sectsubtitle_xform`
633 Enable or disable the promotion of the title of a lone subsection
634 to a subtitle (docutils.transforms.frontmatter.SectSubTitle).
636 Default: disabled (0). Options: ``--section-subtitles,
637 --no-section-subtitles``.
643 The `pep_references`_ and `rfc_references`_ settings
644 (`[restructuredtext parser]`_) are set on by default.
656 [docutils_xml writer]
657 `````````````````````
661 * In Python versions older than 2.7.3 and 3.2.3, the newlines_ and
662 indents_ options may adversely affect whitespace; use them only for
663 reading convenience (see http://bugs.python.org/issue4147).
665 * The XML declaration carries text encoding information, without which
666 standard tools may be unable to read the generated XML.
668 _`doctype_declaration`
669 Generate XML with a DOCTYPE declaration.
671 Default: do (1). Options: ``--no-doctype``.
674 Generate XML with indents and newlines.
676 Default: don't (None). Options: ``--indents``.
679 Generate XML with newlines before and after tags.
681 Default: don't (None). Options: ``--newlines``.
683 .. _xml_declaration [docutils_xml writer]:
686 Generate XML with an XML declaration. Also defined for the
689 Default: do (1). Options: ``--no-xml-declaration``.
691 __ `xml_declaration [html4css1 writer]`_
697 .. _attribution [html4css1 writer]:
700 Format for block quote attributions: one of "dash" (em-dash
701 prefix), "parentheses"/"parens", or "none". Also defined for the
704 Default: "dash". Options: ``--attribution``.
706 __ `attribution [latex2e writer]`_
708 _`cloak_email_addresses`
709 Scramble email addresses to confuse harvesters. In the reference
710 URI, the "@" will be replaced by %-escapes (as of RFC 1738). In
711 the visible text (link text) of an email reference, the "@" and
712 all periods (".") will be surrounded by ``<span>`` tags.
713 Furthermore, HTML entities are used to encode these characters in
714 order to further complicate decoding the email address. For
715 example, "abc@example.org" will be output as::
717 <a class="reference" href="mailto:abc%40example.org">
718 abc<span>@</span>example<span>.</span>org</a>
720 .. Note:: While cloaking email addresses will have little to no
721 impact on the rendering and usability of email links in most
722 browsers, some browsers (e.g. the ``links`` browser) may decode
723 cloaked email addresses incorrectly.
725 Default: don't cloak (None). Option: ``--cloak-email-addresses``.
728 Remove extra vertical whitespace between items of bullet lists and
729 enumerated lists, when list items are all "simple" (i.e., items
730 each contain one paragraph and/or one "simple" sublist only). The
731 behaviour can be specified directly via "class" attributes (values
732 "compact" and "open") in the document.
734 Default: enabled (1). Options: ``--compact-lists,
735 --no-compact-lists``.
737 _`compact_field_lists`
738 Remove extra vertical whitespace between items of field lists that
739 are "simple" (i.e., all field bodies each contain at most one
740 paragraph). The behaviour can be specified directly via "class"
741 attributes (values "compact" and "open") in the document.
743 Default: enabled (1). Options: ``--compact-field-lists,
744 --no-compact-field-lists``.
746 .. _embed_stylesheet [html4css1 writer]:
749 Embed the stylesheet in the output HTML file. The stylesheet file
750 must specified by the stylesheet_path__ setting and must be
751 accessible during processing.
752 Also defined for the `LaTeX Writer`__.
754 Default: enabled. Options: ``--embed-stylesheet,
757 __ `stylesheet_path [html4css1 writer]`_
758 __ `embed_stylesheet [latex2e writer]`_
761 The maximum width (in characters) for one-column field names.
762 Longer field names will span an entire row of the table used to
763 render the field list. 0 indicates "no limit". See also
766 Default: 14 characters. Option: ``--field-name-limit``.
768 .. _footnote_references [html4css1 writer]:
771 Format for footnote references, one of "superscript" or
772 "brackets". Also defined for the `LaTeX Writer`__.
774 Overrides [#override]_ trim_footnote_reference_space_, if
775 applicable. [#footnote_space]_
777 Default: "brackets". Option: ``--footnote-references``.
779 __ `footnote_references [latex2e writer]`_
781 _`initial_header_level`
782 The initial level for header elements. This does not affect the
783 document title & subtitle; see doctitle_xform_.
785 Default: 1 (for "<h1>"). Option: ``--initial-header-level``.
788 The format of mathematical content (`math directive`_ and role) in
789 the output document. Supported values are (case insensitive):
792 Format math for display with MathJax_, a JavaScript-based math
793 rendering engine that uses HTML/CSS, JavaScript, and unicode
794 fonts for high-quality typesetting that is scalable and prints
798 Works 'out of the box' across multiple browsers and platforms.
800 Supports a large subset of LaTeX math commands and constructs
801 (see http://www.mathjax.org/docs/1.1/tex.html).
804 Requires an Internet connection (or a local MathJax
805 installation and configuration).
807 Downloads JavaScript code from a third-party site.
810 Format math in standard HTML enhanced by CSS rules
812 Requires the ``math.css`` stylesheet (stored in the same
813 installation-dependent directory as the `default stylesheet`__).
815 .. __: `stylesheet_path [html4css1 writer]`_
818 Embed math content as presentational MathML_.
821 The W3C recommendation for math on the web.
823 Self-contained documents (no JavaScript, no external downloads).
826 Docutil's latex2mathml converter supports only a small
827 subset of LaTeX syntax.
829 With the "html4css1" writer, the resulting HTML document does
830 not validate, as there is no DTD for MathML + XHTML
831 Transitional. However, MathML-enabled browsers will render it
835 Include literal LaTeX code.
837 The failsave fallback.
839 Default: MathJax Option: ``--math-output``.
843 .. _math directive: ../ref/rst/directives.html#math
844 .. _MathJax: http://www.mathjax.org/
845 .. _MathPlayer: http://www.dessci.com/en/products/mathplayer/
846 .. _MathML: http://www.w3.org/TR/MathML/
849 The maximum width (in characters) for options in option lists.
850 Longer options will span an entire row of the table used to render
851 the option list. 0 indicates "no limit". See also
854 Default: 14 characters. Option: ``--option-limit``.
856 .. _stylesheet [html4css1 writer]:
859 A comma-separated list of CSS stylesheet URLs, used verbatim.
860 Also defined for the `LaTeX Writer`__.
862 Overrides also stylesheet-path__. [#override]_
864 Default: None. Options: ``--stylesheet``.
866 __ `stylesheet [latex2e writer]`_
867 __ `stylesheet_path [html4css1 writer]`_
869 .. _stylesheet_path [html4css1 writer]:
872 A comma-separated list of paths [#pwd]_ to CSS stylesheets.
873 If embed_stylesheet__ is False, paths are rewritten relative to the
874 output HTML file. Also defined for the `LaTeX Writer`__.
876 Also overrides "stylesheet". [#override]_
877 Pass an empty string (to either "stylesheet" or "stylesheet_path") to
878 deactivate stylesheet inclusion.
880 Default: "html4css1.css" in the docutils/writers/html4css1/
881 directory (installed automatically; for the exact machine-specific
882 path, use the ``--help`` option). Options: ``--stylesheet-path``.
884 __ `embed_stylesheet [html4css1 writer]`_
885 __ `stylesheet_path [latex2e writer]`_
887 .. _table_style [html4css1 writer]:
890 Added to standard table classes to allow styling with CSS.
891 The default sylesheet defines:
894 no borders around the table.
897 a line above and below the table and one after the head.
899 Default: "". Option: ``--table-style``.
901 .. _template [html4css1 writer]:
904 Path to template file, which must be encoded in UTF-8 [#pwd]_.
905 Also defined for the `LaTeX Writer`__.
907 Default: "template.txt" in the docutils/writers/html4css1/
908 directory (installed automatically; for the exact machine-specific
909 path, use the ``--help`` option). Options: ``--template``.
911 __ `template [latex2e writer]`_
913 .. _xml_declaration [html4css1 writer]:
916 Generate XML with an XML declaration. Also defined for the
917 `Docutils XML Writer`__.
919 .. Caution:: The XML declaration carries text encoding
920 information, without which standard tools may be unable to read
923 Default: do (1). Options: ``--no-xml-declaration``.
925 __ `xml_declaration [docutils_xml writer]`_
931 The PEP/HTML Writer derives from the standard HTML Writer, and shares
932 all settings defined in the `[html4css1 writer]`_ section. The
933 "[html4css1 writer]" section of configuration files is processed
934 before the "[pep_html writer]" section.
937 Do not use a random banner image. Mainly used to get predictable
938 results when testing.
940 Default: random enabled (None). Options: ``--no-random``
944 Home URL prefix for PEPs.
946 Default: current directory ("."). Options: ``--pep-home``.
951 Default: parent directory (".."). Options: ``--python-home``.
953 The PEP/HTML Writer's default for the following settings differ from
954 those of the standard HTML Writer:
956 * ``stylesheet_path``: The default is
957 ``docutils/writers/pep_html/pep.css`` in the installation directory.
958 For the exact machine-specific path, use the ``--help`` option.
960 * ``template``: The default is
961 ``docutils/writers/pep_html/template.txt`` in the installation
962 directory. For the exact machine-specific path, use the ``--help``
969 The S5/HTML Writer derives from the standard HTML Writer, and shares
970 all settings defined in the `[html4css1 writer]`_ section. The
971 "[html4css1 writer]" section of configuration files is processed
972 before the "[s5_html writer]" section.
975 Auto-hide the presentation controls in slideshow mode, or or keep
976 them visible at all times.
978 Default: auto-hide (1). Options: ``--hidden-controls``,
979 ``--visible-controls``.
982 Enable or disable the current slide indicator ("1/15").
984 Default: disabled (None). Options: ``--current-slide``,
985 ``--no-current-slide``.
987 _`overwrite_theme_files`
988 Allow or prevent the overwriting of existing theme files in the
989 ``ui/<theme>`` directory. This has no effect if "theme_url_" is
992 Default: keep existing theme files (None). Options:
993 ``--keep-theme-files``, ``--overwrite-theme-files``.
996 Name of an installed S5 theme, to be copied into a ``ui/<theme>``
997 subdirectory, beside the destination file (output HTML). Note
998 that existing theme files will not be overwritten; the existing
999 theme directory must be deleted manually.
1000 Also overrides the "theme_url_" setting. [#override]_
1002 Default: "default". Option: ``--theme``.
1005 The URL of an S5 theme directory. The destination file (output
1006 HTML) will link to this theme; nothing will be copied. Also overrides
1007 the "theme_" setting. [#override]_
1009 Default: None. Option: ``--theme-url``.
1012 The initial view mode, either "slideshow" or "outline".
1014 Default: "slidewhow". Option: ``--view-mode``.
1016 The S5/HTML Writer's default for the following settings differ
1017 from those of the standard HTML Writer:
1019 * ``compact_lists``: The default here is to disable compact lists.
1021 * ``template``: The default is
1022 ``docutils/writers/s5_html/template.txt`` in the installation
1023 directory. For the exact machine-specific path, use the ``--help``
1031 To get pagenumbers in the table of contents the table of contents
1032 must be generated by LaTeX. Usually latex must be run twice to get
1035 Default: on. Options: ``--use-latex-toc, --use-docutils-toc``.
1037 _`use_latex_docinfo`
1038 Attach author and date to the document title
1039 instead of the document info table.
1041 Default: off. Options: ``--use-latex-docinfo, --use-docutils-docinfo``
1043 _`docutils_footnotes`
1044 Use the Docutils-specific macros ``\DUfootnote`` and
1045 ``\DUfootnotetext`` for footnotes.
1047 Default: on. Option: ``--docutils-footnotes``.
1049 _`use_latex_footnotes`
1050 Backwards-compatibility alias for docutils_footnotes_ (deprecated).
1052 *Note*: the planned new option _`latex_footnotes` will use the
1053 ``\footnote`` command and footnote numbering by LaTeX.
1056 Typeset footnote text in a figure float.
1057 This may lead to footnotes, citations, and figures being
1060 *Deprecated:* This setting will be removed in a future Docutils
1063 Default: off. Option: ``--figure-footnotes``.
1065 _`use_latex_citations`
1066 Use \cite for citations instead of a simulation with figure-floats.
1068 Default: off. Options: ``--use-latex-citations, --figure-citations``.
1070 _`use_latex_abstract`
1071 Use LaTeX abstract environment for the document's abstract.
1073 Default: off. Options: ``--use-latex-abstract, --topic-abstract``.
1076 Color of any hyperlinks embedded in text.
1078 * "0" or "false" disable coloring of links. (Links will be marked
1079 by red boxes that are not printed),
1080 * "black" results in “invisible“ links,
1082 Set hyperref_options_ to "draft" to completely disable
1085 Default: "blue". Option: ``--hyperlink-color``.
1088 Options for the `hyperref TeX package`_. If hyperlink_color_ is
1089 not "false", the expansion of ::
1091 'colorlinks=true,linkcolor=%s,urlcolor=%s' % (
1092 hyperlink_color, self.hyperlink_color
1094 is prepended. For documents typeset in Cyrillic script,
1095 ``--hyperref-options=unicode`` is recommended.
1097 Default: "". Option: ``--hyperref-options``.
1099 .. _hyperref TeX package: http://tug.org/applications/hyperref/
1102 Specify latex documentclass.
1104 Default: "article". Option: ``--documentclass``.
1107 Specify document options. Multiple options can be given, separated by
1110 Default: "a4paper". Option: ``--documentoptions``.
1113 Specify LaTeX font encoding. Multiple options can be given, separated
1114 by commas. Possible values are "", "T1", "OT1", "LGR,T1" or any other
1115 combination of `LaTeX font encodings`_.
1117 Default: "T1". Option: ``--font-encoding``.
1119 .. _LaTeX font encodings:
1120 http://mirror.ctan.org/macros/latex/doc/encguide.pdf
1122 .. _embed_stylesheet [latex2e writer]:
1125 Embed the stylesheet(s) in the header of the output file. The
1126 stylesheets must be accessible during processing. Currently, this
1127 fails if the file is not available via the given path (i.e. the
1128 file is *not* searched in the `TeX input path`_).
1129 Also defined for the `HTML Writer`__ (with default *on*).
1131 Default: off. Options: ``--embed-stylesheet, --link-stylesheet``.
1133 __ `embed_stylesheet [html4css1 writer]`_
1135 .. _stylesheet [latex2e writer]:
1138 A comma-separated list of style files.
1139 Also defined for the `HTML Writer`__.
1141 Overrides also stylesheet_path__. [#override]_
1143 If `embed_stylesheet`__ is False (default), the stylesheet files are
1144 referenced with ``\usepackage`` (extension ``.sty`` or no extension) or
1145 ``\input`` (any other extension).
1147 LaTeX will search the specified files in the `TeX input path`_.
1149 Default: no stylesheet (""). Option: ``--stylesheet``.
1151 __ `stylesheet_path [latex2e writer]`_
1152 __ `embed_stylesheet [latex2e writer]`_
1153 __ `stylesheet [html4css1 writer]`_
1155 http://www.tex.ac.uk/cgi-bin/texfaq2html?label=what-TDS
1158 .. _stylesheet_path [latex2e writer]:
1161 Similar to stylesheet__, however paths [#pwd]_ are rewritten relative to
1162 the output file (if there is a common part in the given path and the
1163 output file path). Also defined for the `HTML Writer`__.
1165 Run ``latex`` from the directory containing the output file. Fails for
1166 files in the TEXINPUTS path; use stylesheet__ in this case.
1168 Also overrides stylesheet__. [#override]_
1170 Default: no stylesheet (""). Option: ``--stylesheet-path``.
1172 __ `stylesheet [latex2e writer]`_
1173 __ `stylesheet_path [html4css1 writer]`_
1175 __ `stylesheet [latex2e writer]`_
1179 LaTeX code that will be inserted in the document preamble.
1180 Can be used to load packages with options or (re-) define LaTeX
1181 macros without writing a custom style file (new in Docutils 0.7).
1183 Default: Load the "PDF standard fonts" (Times, Helvetica,
1186 \usepackage{mathptmx} % Times
1187 \usepackage[scaled=.90]{helvet}
1188 \usepackage{courier}
1190 Option: ``--latex-preamble``
1193 .. _template [latex2e writer]:
1196 Path to template file, which must be encoded in UTF-8 [#pwd]_.
1197 Also defined for the `HTML Writer`__.
1199 Default: "default.tex" in the docutils/writers/latex2e/
1200 directory (installed automatically; for the exact machine-specific
1201 path, use the ``--help`` option). Options: ``--template``.
1203 __ `template [html4css1 writer]`_
1205 .. _footnote_references [latex2e writer]:
1208 Format for footnote references: one of "superscript" or
1209 "brackets". Also defined for the `HTML Writer`__.
1211 Overrides [#override]_ trim_footnote_reference_space_, if
1212 applicable [#footnote_space]_.
1214 Default: "superscript". Option: ``--footnote-references``.
1216 __ `footnote_references [html4css1 writer]`_
1218 .. _attribution [latex2e writer]:
1221 Format for block quote attributions, the same as for the
1222 html-writer: one of "dash" (em-dash prefix),
1223 "parentheses"/"parens" or "none". Also defined for the `HTML
1226 Default: "dash". Option: ``--attribution``.
1228 __ `attribution [html4css1 writer]`_
1230 _`compound_enumerators`
1231 Enable or disable compound enumerators for nested enumerated lists
1234 Default: disabled (None). Options: ``--compound-enumerators``,
1235 ``--no-compound-enumerators``.
1237 _`literal_block_env`
1238 When possibile\ [#]_, use the specified environment for literal-blocks.
1240 Default: "" (quoting of whitespace and special chars)
1241 Option: ``--literal-block-env``
1243 .. [#] A literal-block element, when processed by a Docutils writer might
1244 have it's origin in a markup with "::" syntax or a "..
1245 parsed-literal::" directive.
1247 A LaTeX verbatim environment is only usable if there is no other
1248 markup contained in the literal-block.
1251 _`section_prefix_for_enumerators`
1252 Enable or disable section ("." subsection ...) prefixes for
1253 compound enumerators. This has no effect unless
1254 `compound_enumerators`_ are enabled.
1256 Default: disabled (None). Options:
1257 ``--section-prefix-for-enumerators``,
1258 ``--no-section-prefix-for-enumerators``.
1260 _`section_enumerator_separator`
1261 The separator between section number prefix and enumerator for
1262 compound enumerated lists (see `compound_enumerators`_).
1264 Generally it isn't recommended to use both sub-sections and nested
1265 enumerated lists with compound enumerators. This setting avoids
1266 ambiguity in the situation where a section "1" has a list item
1267 enumerated "1.1", and subsection "1.1" has list item "1". With a
1268 separator of ".", these both would translate into a final compound
1269 enumerator of "1.1.1". With a separator of "-", we get the
1270 unambiguous "1-1.1" and "1.1-1".
1272 Default: "-". Option: ``--section-enumerator-separator``.
1274 .. _table_style [latex2e writer]:
1277 Specify the drawing of separation lines.
1281 lines around and between cells.
1283 a line above and below the table and one after the head.
1287 Default: "standard". Option: ``--table-style``.
1292 The xetex writer derives from the latex2e writer, and shares
1293 all settings defined in the `[latex2e writer]`_ section. The
1294 "[latex2e writer]" section of configuration files is processed
1295 before the "[xetex writer]" section.
1297 The following settings differ from those of the latex2e writer:
1300 Disabled as XeTeX uses Unicode-encoded fonts.
1302 .. _latex_preamble [xetex writer]:
1305 LaTeX code that will be inserted in the document preamble.
1308 Font setup for `Linux Libertine`_,::
1310 % Linux Libertine (free, wide coverage, not only for Linux)
1311 \setmainfont{Linux Libertine O}
1312 \setsansfont{Linux Biolinum O}
1313 \setmonofont[HyphenChar=None]{DejaVu Sans Mono}
1315 The optional argument ``HyphenChar=None`` to the monospace font
1316 prevents word hyphenation in literal text.
1319 Option: ``--latex-preamble``
1321 .. _Linux Libertine: http://www.linuxlibertine.org/
1323 .. _template [xetex writer]:
1326 Path to template file.
1328 Default: "xelatex.tex" in the ``docutils/writers/latex2e/``
1329 directory (installed automatically; for the exact machine-specific
1330 path, use the ``--help`` option). Options: ``--template``.
1336 No settings are defined for this Writer.
1342 [buildhtml application]
1343 ```````````````````````
1346 List of wildcard (shell globing) patterns, specifying files to
1347 silently ignore. To specify multiple patterns, use
1348 colon-separated patterns (in configuration files or on the command
1349 line); on the command line, the option may also be used more than
1352 Default: none ([]). Options: ``--ignore``.
1355 List of directories not to process. To specify multiple
1356 directories, use colon-separated paths (in configuration files or
1357 on the command line); on the command line, the option may also be
1358 used more than once.
1360 Default: ['.hg', '.bzr', '.git', '.svn', 'CVS']. Options:
1364 Recursively scan subdirectories, or ignore subdirectories.
1366 Default: recurse (1). Options: ``--recurse, --local``.
1369 Work silently (no progress messages). Independent of
1372 Default: show progress (None). Options: ``--silent``.
1375 [docfactory application]
1376 ````````````````````````
1387 These settings are only effective as command-line options; setting
1388 them in configuration files has no effect.
1391 Path to a configuration file to read (if it exists) [#pwd]_.
1392 Settings may override defaults and earlier settings. The config
1393 file is processed immediately. Multiple ``--config`` options may
1394 be specified; each will be processed in turn.
1396 Filesystem path settings contained within the config file will be
1397 interpreted relative to the config file's location (*not* relative
1398 to the current working directory).
1400 Default: None. Options: ``--config``.
1406 These settings are for internal use only; setting them in
1407 configuration files has no effect, and there are no corresponding
1408 command-line options.
1411 List of paths of applied configuration files.
1413 Default: None. No command-line options.
1416 (``buildhtml.py`` front end.) List of paths to source
1417 directories, set from positional arguments.
1419 Default: current working directory (None). No command-line
1423 Prevent standard configuration files from being read. For
1424 programmatic use only.
1426 Default: config files enabled (None). No command-line options.
1429 Path to output destination, set from positional arguments.
1431 Default: stdout (None). No command-line options.
1434 Path to input source, set from positional arguments.
1436 Default: stdin (None). No command-line options.
1439 .. _language tag: http://www.w3.org/International/articles/language-tags/
1440 .. _BCP 47: http://www.rfc-editor.org/rfc/bcp/bcp47.txt
1441 .. _ISO 639: http://www.loc.gov/standards/iso639-2/php/English_list.php
1442 .. _ISO 3166: http://www.iso.ch/iso/en/prods-services/iso3166ma/
1443 02iso-3166-code-lists/index.html
1445 .. [#pwd] Path relative to the working directory of the process at
1448 .. [#override] The overridden setting will automatically be set to
1449 ``None`` for command-line options and config file settings. Client
1450 programs which specify defaults that override other settings must
1451 do the overriding explicitly, by assigning ``None`` to the other
1454 .. [#dependencies] Images are only added to the dependency list if the
1455 reStructuredText parser extracted image dimensions from the file.
1457 .. [#footnote_space] The footnote space is trimmed if the reference
1458 style is "superscript", and it is left if the reference style is
1461 The overriding only happens if the parser supports the
1462 trim_footnote_reference_space option.
1465 ------------------------------
1466 Old-Format Configuration Files
1467 ------------------------------
1469 Formerly, Docutils configuration files contained a single "[options]"
1470 section only. This was found to be inflexible, and in August 2003
1471 Docutils adopted the current component-based configuration file
1472 sections as described above. Docutils will still recognize the old
1473 "[options]" section, but complains with a deprecation warning.
1475 To convert existing config files, the easiest way is to change the
1476 section title: change "[options]" to "[general]". Most settings
1477 haven't changed. The only ones to watch out for are these:
1479 ===================== =====================================
1480 Old-Format Setting New Section & Setting
1481 ===================== =====================================
1482 pep_stylesheet [pep_html writer] stylesheet
1483 pep_stylesheet_path [pep_html writer] stylesheet_path
1484 pep_template [pep_html writer] template
1485 ===================== =====================================