1 ========================
3 ========================
6 :Contact: goodger@python.org
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)
99 This is the contents of the ``tools/docutils.conf`` configuration file
100 supplied with Docutils::
102 # These entries affect all processing:
105 datestamp: %Y-%m-%d %H:%M UTC
108 # These entries affect HTML output:
110 # Required for docutils-update, the website build system:
111 stylesheet-path: ../docutils/writers/html4css1/html4css1.css
115 Individual configuration sections and settings are described in the
119 -------------------------------------
120 Configuration File Sections & Entries
121 -------------------------------------
123 Below are the Docutils runtime settings, listed by config file
124 section. Any setting may be specified in any section, but only
125 settings from active sections will be used. Sections correspond to
126 Docutils components (module name or alias; section names are always in
127 lowercase letters). Each `Docutils application`_ uses a specific set
128 of components; corresponding configuration file sections are applied
129 when the application is used. Configuration sections are applied in
130 general-to-specific order, as follows:
134 2. `[parsers]`_, parser dependencies, and the section specific to the
135 Parser used ("[... parser]"). Currently, only `[restructuredtext
136 parser]`_ is applicable.
138 3. `[readers]`_, reader dependencies, and the section specific to the
139 Reader used ("[... reader]"). For example, `[pep reader]`_ depends
140 on `[standalone reader]`_.
142 4. `[writers]`_, writer dependencies, and the section specific to the
143 Writer used ("[... writer]"). For example, `[pep_html writer]`_
144 depends on `[html4css1 writer]`_.
146 5. `[applications]`_, application dependencies, and the section
147 specific to the Application (front-end tool) in use
148 ("[... application]").
150 Since any setting may be specified in any section, this ordering
151 allows component- or application-specific overrides of earlier
152 settings. For example, there may be Reader-specific overrides of
153 general settings; Writer-specific overrides of Parser settings;
154 Application-specific overrides of Writer settings; and so on.
156 If multiple configuration files are applicable, the process is
157 completed (all sections are applied in the order given) for each one
158 before going on to the next. For example, a "[pep_html writer]
159 stylesheet" setting in an earlier configuration file would be
160 overridden by an "[html4css1 writer] stylesheet" setting in a later
163 Some knowledge of Python_ is assumed for some attributes.
166 http://www.python.org/doc/current/lib/module-ConfigParser.html
167 .. _Python: http://www.python.org/
168 .. _RFC 822: http://www.rfc-editor.org/rfc/rfc822.txt
169 .. _Docutils application: tools.html
175 Settings in the "[general]" section are always applied.
178 Prefix prepended to all auto-generated IDs generated within the
179 document, after id_prefix_.
181 Default: "id". Options: ``--auto-id-prefix`` (hidden, intended
182 mainly for programmatic use).
185 Include a time/datestamp in the document footer. Contains a
186 format string for Python's ``time.strftime``. See the `time
187 module documentation`__.
189 Default: None. Options: ``--date, -d, --time, -t,
192 Configuration file entry examples::
194 # Equivalent to --date command-line option, results in
195 # ISO 8601 extended format datestamp, e.g. "2001-12-21":
198 # Equivalent to --time command-line option, results in
199 # date/timestamp like "2001-12-21 18:43 UTC":
200 datestamp: %Y-%m-%d %H:%M UTC
202 # Disables datestamp; equivalent to --no-datestamp:
205 __ http://www.python.org/doc/current/lib/module-time.html
208 Report debug-level system messages.
210 Default: don't (None). Options: ``--debug, --no-debug``.
213 At the end of processing, write all internal attributes of the
214 document (``document.__dict__``) to stderr.
216 Default: don't (None). Options: ``--dump-internals`` (hidden, for
217 development use only).
220 At the end of processing, write the pseudo-XML representation of
221 the document to stderr.
223 Default: don't (None). Options: ``--dump-pseudo-xml`` (hidden,
224 for development use only).
227 At the end of processing, write all Docutils settings to stderr.
229 Default: don't (None). Options: ``--dump-settings`` (hidden, for
230 development use only).
233 At the end of processing, write a list of all transforms applied
234 to the document to stderr.
236 Default: don't (None). Options: ``--dump-transforms`` (hidden,
237 for development use only).
240 The text encoding for error output.
242 Default: "ascii". Options: ``--error-encoding, -e``.
244 _`error_encoding_error_handler`
245 The error handler for unencodable characters in error output. See
246 output_encoding_error_handler_ for acceptable values.
248 Default: "backslashreplace" for Python 2.3 and later; "replace"
249 otherwise. Options: ``--error-encoding-error-handler,
250 --error-encoding, -e``.
253 A system message level threshold; non-halting system messages at
254 or above this level will produce a non-zero exit status at normal
255 exit. Exit status is the maximum system message level plus 10 (11
258 Default: disabled (5). Options: ``--exit-status``.
261 List of internal attribues to expose as external attributes (with
262 "internal:" namespace prefix). To specify multiple attributes in
263 configuration files, use colons to separate names; on the command
264 line, the option may be used more than once.
266 Default: don't (None). Options: ``--expose-internal-attribute``
267 (hidden, for development use only).
269 _`footnote_backlinks`
270 Enable or disable backlinks from footnotes and citations to their
273 Default: enabled (1). Options: ``--footnote-backlinks,
274 --no-footnote-backlinks``.
277 Include a "Generated by Docutils" credit and link in the document
280 Default: off (None). Options: ``--generator, -g,
284 The threshold at or above which system messages are converted to
285 exceptions, halting execution immediately. If `traceback`_ is
286 set, the exception will propagate; otherwise, Docutils will exit.
288 Default: severe (4). Options: ``--halt, --strict``.
291 Prefix prepended to all IDs generated within the document. See
292 also auto_id_prefix_.
294 Default: "" (empty). Options: ``--id-prefix`` (hidden, intended
295 mainly for programmatic use).
298 The text encoding for input.
300 Default: auto-detect (None). Options: ``--input-encoding, -i``.
302 _`input_encoding_error_handler`
303 The error handler for undecodable characters in the input.
304 Acceptable values include:
307 Raise an exception in case of an encoding error.
309 Replace malformed data with the official Unicode replacement
312 Ignore malformed data and continue without further notice.
314 Acceptable values are the same as for the "error" parameter of
315 Python's ``unicode`` function; other values may be defined in
316 applications or in future versions of Python.
318 Default: "strict". Options: ``--input-encoding-error-handler,
319 --input-encoding, -i``.
322 Case-insensitive `language tag`_ as defined in `BCP 47`_.
324 Sets the document language, also used for localized directive and
325 role names as well as Docutils-generated text.
327 A typical language identifier consists of a 2-letter language code
328 from `ISO 639`_ (3-letter codes can be used if no 2-letter code
329 exists). The language identifier can have an optional subtag,
330 typically for variations based on country (from `ISO 3166`_
331 2-letter country codes). Avoid subtags except where they add
332 useful distinguishing information. Examples of language tags
333 include "fr", "en-GB", "pt_br" (the same as "pt-BR"), and
334 "de-1901" (German with pre-1998 spelling).
336 The language of document parts can be specified with a
337 "language-<language tag>" `class attribute`_, e.g.
338 ``.. class:: language-el-polyton`` for a quote in polytonic Greek.
340 Default: English ("en"). Options: ``--language, -l``.
342 .. _class attribute: ../ref/doctree.html#classes
345 The text encoding for output.
347 Default: "UTF-8". Options: ``--output-encoding, -o``.
349 _`output_encoding_error_handler`
350 The error handler for unencodable characters in the output.
351 Acceptable values include:
354 Raise an exception in case of an encoding error.
356 Replace malformed data with a suitable replacement marker,
359 Ignore malformed data and continue without further notice.
361 Replace with the appropriate XML character reference, such as
364 (Python 2.3+) Replace with backslashed escape sequences, such
367 Acceptable values are the same as for the "error" parameter of
368 Python's ``encode`` string method; other values may be defined in
369 applications or in future versions of Python.
371 Default: "strict". Options: ``--output-encoding-error-handler,
372 --output-encoding, -o``.
374 _`record_dependencies`
375 Path to a file where Docutils will write a list of files that the
376 input and output depend on [#dependencies]_, e.g. due to file
377 inclusion. [#pwd]_ The format is one filename per line. This
378 option is particularly useful in conjunction with programs like
381 Set to ``-`` in order to write dependencies to stdout.
383 Default: None. Option: ``--record-dependencies``.
386 Verbosity threshold at or above which system messages are
389 Default: warning (2). Options: ``--report, -r, --verbose, -v,
393 Enable or disable automatic section numbering by Docutils
394 (docutils.transforms.parts.SectNum) associated with the `sectnum
397 If disabled, section numbers might be added to the output by the
398 renderer (e.g. LaTeX or via a CSS style definition).
400 Default: enabled (1). Options: ``--section-numbering``,
401 ``--no-section-numbering``.
403 .. _sectnum directive: ../ref/rst/directives.html#sectnum
406 Include a "View document source" link in the document footer. URL
407 will be relative to the destination.
409 Default: don't (None). Options: ``--source-link, -s,
413 An explicit URL for a "View document source" link, used verbatim.
415 Default: compute if source_link (None). Options: ``--source-url,
419 When processing a document tree with the Visitor pattern, raise an
420 error if a writer does not support a node type listed as optional.
421 For transitional development use.
423 Default: disabled (None). Option: ``--strict-visitor`` (hidden,
424 for development use only).
427 List of "classes" attribute values to remove from all elements in
430 .. WARNING:: Potentially dangerous; use with caution.
432 Default: disabled (None). Option: ``--strip-class``.
435 Enable the removal of comment elements from the document tree.
437 Default: disabled (None). Options: ``--strip-comments``,
438 ``--leave-comments``.
440 _`strip_elements_with_classes`
441 List of "classes" attribute values; matching elements to be
442 removed from the document tree.
444 .. WARNING:: Potentially dangerous; use with caution.
446 Default: disabled (None). Option: ``--strip-element-with-class``.
449 The document title as metadata, which does not become part of the
450 document body. It overrides a document-supplied title. For
451 example, in HTML output the metadata document title appears in the
452 title bar of the browser window.
454 Default: none. Option: ``--title``.
457 Enable backlinks from section titles to table of contents entries
458 ("entry"), to the top of the TOC ("top"), or disable ("none").
460 Default: "entry". Options: ``--toc-entry-backlinks,
461 --toc-top-backlinks, --no-toc-backlinks``.
464 Enable Python tracebacks when halt-level system messages and other
465 exceptions occur. Useful for debugging, and essential for issue
466 reports. Exceptions are allowed to propagate, instead of being
467 caught and reported (in a user-friendly way) by Docutils.
469 Default: disabled (None) unless Docutils is run programmatically
470 using the `Publisher Interface`_. Options: ``--traceback,
473 .. _Publisher Interface: ../api/publisher.html
476 Path to a file for the output of system messages (warnings)
479 Default: stderr (None). Options: ``--warnings``.
485 Docutils currently supports only one parser, for reStructuredText.
488 [restructuredtext parser]
489 `````````````````````````
491 _`file_insertion_enabled`
492 Enable or disable directives that insert the contents of external
493 files, such as the "include_" & "raw_". A "warning" system
494 message (including the directive text) is inserted instead. (See
495 also raw_enabled_ for another security-relevant setting.)
497 Default: enabled (1). Options: ``--file-insertion-enabled,
498 --no-file-insertion``.
500 .. _include: ../ref/rst/directives.html#include
501 .. _raw: ../ref/rst/directives.html#raw
504 Recognize and link to standalone PEP references (like "PEP 258").
506 Default: disabled (None); enabled (1) in PEP Reader. Options:
507 ``--pep-references``.
510 Base URL for PEP references.
512 Default: "http://www.python.org/peps/". Option:
515 _`pep_file_url_template`
516 Template for PEP file part of URL, interpolated with the PEP
517 number and appended to pep_base_url_.
519 Default: "pep-%04d". Option: ``--pep-file-url``.
522 Enable or disable the "raw_" directive. A "warning" system
523 message (including the directive text) is inserted instead. (See
524 also file_insertion_enabled_ for another security-relevant
527 Default: enabled (1). Options: ``--raw-enabled, --no-raw``.
530 Recognize and link to standalone RFC references (like "RFC 822").
532 Default: disabled (None); enabled (1) in PEP Reader. Options:
533 ``--rfc-references``.
536 Base URL for RFC references.
538 Default: "http://www.faqs.org/rfcs/". Option: ``--rfc-base-url``.
541 Number of spaces for hard tab expansion.
543 Default: 8. Options: ``--tab-width``.
545 _`trim_footnote_reference_space`
546 Remove spaces before footnote references.
548 Default: don't (None); may be overriden by a writer-specific
549 footnote_references__ default though. Options:
550 ``--trim-footnote-reference-space,
551 --leave-footnote-reference-space``.
553 __ `footnote_references [latex2e writer]`_
564 Enable or disable the bibliographic field list transform
565 (docutils.transforms.frontmatter.DocInfo).
567 Default: enabled (1). Options: ``--no-doc-info``.
570 Enable or disable the promotion of a lone top-level section title
571 to document title (and subsequent section title to document
572 subtitle promotion; docutils.transforms.frontmatter.DocTitle).
574 Default: enabled (1). Options: ``--no-doc-title``.
576 _`sectsubtitle_xform`
578 Enable or disable the promotion of the title of a lone subsection
579 to a subtitle (docutils.transforms.frontmatter.SectSubTitle).
581 Default: disabled (0). Options: ``--section-subtitles,
582 --no-section-subtitles``.
588 The `pep_references`_ and `rfc_references`_ settings
589 (`[restructuredtext parser]`_) are set on by default.
601 [docutils_xml writer]
602 `````````````````````
604 _`doctype_declaration`
605 Generate XML with a DOCTYPE declaration.
607 Default: do (1). Options: ``--no-doctype``.
610 Generate XML with indents and newlines.
612 Default: don't (None). Options: ``--indents``.
615 Generate XML with newlines before and after tags.
617 Default: don't (None). Options: ``--newlines``.
619 .. _xml_declaration [docutils_xml writer]:
622 Generate XML with an XML declaration. Also defined for the
625 .. Caution:: The XML declaration carries text encoding
626 information, without which standard tools may be unable to read
629 Default: do (1). Options: ``--no-xml-declaration``.
631 __ `xml_declaration [html4css1 writer]`_
637 .. _attribution [html4css1 writer]:
640 Format for block quote attributions: one of "dash" (em-dash
641 prefix), "parentheses"/"parens", or "none". Also defined for the
644 Default: "dash". Options: ``--attribution``.
646 __ `attribution [latex2e writer]`_
648 _`cloak_email_addresses`
649 Scramble email addresses to confuse harvesters. In the reference
650 URI, the "@" will be replaced by %-escapes (as of RFC 1738). In
651 the visible text (link text) of an email reference, the "@" and
652 all periods (".") will be surrounded by ``<span>`` tags.
653 Furthermore, HTML entities are used to encode these characters in
654 order to further complicate decoding the email address. For
655 example, "abc@example.org" will be output as::
657 <a class="reference" href="mailto:abc%40example.org">
658 abc<span>@</span>example<span>.</span>org</a>
660 .. Note:: While cloaking email addresses will have little to no
661 impact on the rendering and usability of email links in most
662 browsers, some browsers (e.g. the ``links`` browser) may decode
663 cloaked email addresses incorrectly.
665 Default: don't cloak (None). Option: ``--cloak-email-addresses``.
668 Remove extra vertical whitespace between items of bullet lists and
669 enumerated lists, when list items are all "simple" (i.e., items
670 each contain one paragraph and/or one "simple" sublist only). The
671 behaviour can be specified directly via "class" attributes (values
672 "compact" and "open") in the document.
674 Default: enabled (1). Options: ``--compact-lists,
675 --no-compact-lists``.
677 _`compact_field_lists`
678 Remove extra vertical whitespace between items of field lists that
679 are "simple" (i.e., all field bodies each contain at most one
680 paragraph). The behaviour can be specified directly via "class"
681 attributes (values "compact" and "open") in the document.
683 Default: enabled (1). Options: ``--compact-field-lists,
684 --no-compact-field-lists``.
686 .. _embed_stylesheet [html4css1 writer]:
689 Embed the stylesheet in the output HTML file. The stylesheet file
690 must specified by the stylesheet_path__ setting and must be
691 accessible during processing.
692 Also defined for the `LaTeX Writer`__.
694 Default: enabled. Options: ``--embed-stylesheet,
697 __ `stylesheet_path [html4css1 writer]`_
698 __ `embed_stylesheet [latex2e writer]`_
701 The maximum width (in characters) for one-column field names.
702 Longer field names will span an entire row of the table used to
703 render the field list. 0 indicates "no limit". See also
706 Default: 14 characters. Option: ``--field-name-limit``.
708 .. _footnote_references [html4css1 writer]:
711 Format for footnote references, one of "superscript" or
712 "brackets". Also defined for the `LaTeX Writer`__.
714 Overrides [#override]_ trim_footnote_reference_space_, if
715 applicable. [#footnote_space]_
717 Default: "brackets". Option: ``--footnote-references``.
719 __ `footnote_references [latex2e writer]`_
721 _`initial_header_level`
722 The initial level for header elements. This does not affect the
723 document title & subtitle; see doctitle_xform_.
725 Default: 1 (for "<h1>"). Option: ``--initial-header-level``.
728 The format of mathematical content (`math directive`_ and role) in
729 the output document. Supported values are:
732 Format math for display with MathJax_, a JavaScript-based math
733 rendering engine that uses HTML/CSS, JavaScript, and unicode
734 fonts for high-quality typesetting that is scalable and prints
738 Works 'out of the box' across multiple browsers and platforms.
740 Supports a large subset of LaTeX math commands and constructs
741 (see http://www.mathjax.org/docs/1.1/tex.html).
744 Requires an Internet connection or a local MathJax
748 Format math in standard HTML enhanced by CSS rules
750 Requires the ``math.css`` stylesheet (stored in the same
751 installation-dependent directory as the `default stylesheet
752 <stylesheet_path [html4css1 writer]>`__
755 Embed math content as presentational MathML_.
758 The W3C recommendation for math on the web.
760 Self-contained documents (no JavaScript, no external downloads).
763 Docutil's latex2mathml converter supports only a small
764 subset of LaTeX syntax.
766 With the "html4css1" writer, the resulting HTML document does
767 not validate, as there is no DTD for MathML + XHTML
768 Transitional. However, MathML-enabled browsers will render it
772 Include literal LaTeX code.
774 The failsave fallback.
778 .. _math directive: ../ref/rst/directives.html#math
779 .. _MathJax: http://www.mathjax.org/
780 .. _MathPlayer: http://www.dessci.com/en/products/mathplayer/
781 .. _MathML: http://www.mathweb.org/wiki/MathML
784 The maximum width (in characters) for options in option lists.
785 Longer options will span an entire row of the table used to render
786 the option list. 0 indicates "no limit". See also
789 Default: 14 characters. Option: ``--option-limit``.
791 .. _stylesheet [html4css1 writer]:
794 A comma-separated list of CSS stylesheet URLs, used verbatim.
795 Also defined for the `LaTeX Writer`__.
797 Overrides also stylesheet-path__. [#override]_
799 Default: None. Options: ``--stylesheet``.
801 __ `stylesheet_path [html4css1 writer]`_
802 __ `stylesheet [latex2e writer]`_
804 .. _stylesheet_path [html4css1 writer]:
807 A comma-separated list of paths [#pwd]_ to CSS stylesheets.
808 If embed_stylesheet__ is False, paths are rewritten relative to the
809 output HTML file. Also defined for the `LaTeX Writer`__.
811 Also overrides "stylesheet". [#override]_
812 Pass an empty string (to either "stylesheet" or "stylesheet_path") to
813 deactivate stylesheet inclusion.
815 Default: "html4css1.css" in the docutils/writers/html4css1/
816 directory (installed automatically; for the exact machine-specific
817 path, use the ``--help`` option). Options: ``--stylesheet-path``.
819 __ `embed_stylesheet [html4css1 writer]`_
820 __ `stylesheet_path [latex2e writer]`_
822 .. _table_style [html4css1 writer]:
825 Added to standard table classes to allow styling with CSS.
826 The default sylesheet defines:
829 no borders around the table.
832 a line above and below the table and one after the head.
834 Default: "". Option: ``--table-style``.
836 .. _template [html4css1 writer]:
839 Path to template file, which must be encoded in UTF-8 [#pwd]_.
840 Also defined for the `LaTeX Writer`__.
842 Default: "template.txt" in the docutils/writers/html4css1/
843 directory (installed automatically; for the exact machine-specific
844 path, use the ``--help`` option). Options: ``--template``.
846 __ `template [latex2e writer]`_
848 .. _xml_declaration [html4css1 writer]:
851 Generate XML with an XML declaration. Also defined for the
852 `Docutils XML Writer`__.
854 .. Caution:: The XML declaration carries text encoding
855 information, without which standard tools may be unable to read
858 Default: do (1). Options: ``--no-xml-declaration``.
860 __ `xml_declaration [docutils_xml writer]`_
866 The PEP/HTML Writer derives from the standard HTML Writer, and shares
867 all settings defined in the `[html4css1 writer]`_ section. The
868 "[html4css1 writer]" section of configuration files is processed
869 before the "[pep_html writer]" section.
872 Do not use a random banner image. Mainly used to get predictable
873 results when testing.
875 Default: random enabled (None). Options: ``--no-random``
879 Home URL prefix for PEPs.
881 Default: current directory ("."). Options: ``--pep-home``.
886 Default: parent directory (".."). Options: ``--python-home``.
888 The PEP/HTML Writer's default for the following settings differ from
889 those of the standard HTML Writer:
891 * ``stylesheet_path``: The default is
892 ``docutils/writers/pep_html/pep.css`` in the installation directory.
893 For the exact machine-specific path, use the ``--help`` option.
895 * ``template``: The default is
896 ``docutils/writers/pep_html/template.txt`` in the installation
897 directory. For the exact machine-specific path, use the ``--help``
904 The S5/HTML Writer derives from the standard HTML Writer, and shares
905 all settings defined in the `[html4css1 writer]`_ section. The
906 "[html4css1 writer]" section of configuration files is processed
907 before the "[s5_html writer]" section.
910 Auto-hide the presentation controls in slideshow mode, or or keep
911 them visible at all times.
913 Default: auto-hide (1). Options: ``--hidden-controls``,
914 ``--visible-controls``.
917 Enable or disable the current slide indicator ("1/15").
919 Default: disabled (None). Options: ``--current-slide``,
920 ``--no-current-slide``.
922 _`overwrite_theme_files`
923 Allow or prevent the overwriting of existing theme files in the
924 ``ui/<theme>`` directory. This has no effect if "theme_url_" is
927 Default: keep existing theme files (None). Options:
928 ``--keep-theme-files``, ``--overwrite-theme-files``.
931 Name of an installed S5 theme, to be copied into a ``ui/<theme>``
932 subdirectory, beside the destination file (output HTML). Note
933 that existing theme files will not be overwritten; the existing
934 theme directory must be deleted manually.
935 Also overrides the "theme_url_" setting. [#override]_
937 Default: "default". Option: ``--theme``.
940 The URL of an S5 theme directory. The destination file (output
941 HTML) will link to this theme; nothing will be copied. Also overrides
942 the "theme_" setting. [#override]_
944 Default: None. Option: ``--theme-url``.
947 The initial view mode, either "slideshow" or "outline".
949 Default: "slidewhow". Option: ``--view-mode``.
951 The S5/HTML Writer's default for the following settings differ
952 from those of the standard HTML Writer:
954 * ``compact_lists``: The default here is to disable compact lists.
956 * ``template``: The default is
957 ``docutils/writers/s5_html/template.txt`` in the installation
958 directory. For the exact machine-specific path, use the ``--help``
966 To get pagenumbers in the table of contents the table of contents
967 must be generated by LaTeX. Usually latex must be run twice to get
970 Default: on. Options: ``--use-latex-toc, --use-docutils-toc``.
973 Attach author and date to the document title
974 instead of the document info table.
976 Default: off. Options: ``--use-latex-docinfo, --use-docutils-docinfo``
978 _`docutils_footnotes`
979 Use the Docutils-specific macros ``\DUfootnote`` and
980 ``\DUfootnotetext`` for footnotes.
982 Default: on. Option: ``--docutils-footnotes``.
984 _`use_latex_footnotes`
985 Backwards-compatibility alias for docutils_footnotes_ (deprecated).
987 *Note*: the planned new option _`latex_footnotes` will use the
988 ``\footnote`` command and footnote numbering by LaTeX.
991 Typeset footnote text in a figure float.
992 This may lead to footnotes, citations, and figures being
995 *Deprecated:* This setting will be removed in a future Docutils
998 Default: off. Option: ``--figure-footnotes``.
1000 _`use_latex_citations`
1001 Use \cite for citations instead of a simulation with figure-floats.
1003 Default: off. Options: ``--use-latex-citations, --figure-citations``.
1005 _`use_latex_abstract`
1006 Use LaTeX abstract environment for the document's abstract.
1008 Default: off. Options: ``--use-latex-abstract, --topic-abstract``.
1011 Color of any hyperlinks embedded in text.
1013 * "0" or "false" disable coloring of links. (Links will be marked
1014 by red boxes that are not printed),
1015 * "black" results in “invisible“ links,
1017 Set hyperref_options_ to "draft" to completely disable
1020 Default: "blue". Option: ``--hyperlink-color``.
1023 Options for the `hyperref TeX package`_. If hyperlink_color_ is
1024 not "false", the expansion of ::
1026 'colorlinks=true,linkcolor=%s,urlcolor=%s' % (
1027 hyperlink_color, self.hyperlink_color
1029 is prepended. For documents typeset in Cyrillic script,
1030 ``--hyperref-options=unicode`` is recommended.
1032 Default: "". Option: ``--hyperref-options``.
1034 .. _hyperref TeX package: http://tug.org/applications/hyperref/
1037 Specify latex documentclass.
1039 Default: "article". Option: ``--documentclass``.
1042 Specify document options. Multiple options can be given, separated by
1045 Default: "a4paper". Option: ``--documentoptions``.
1048 Specify LaTeX font encoding. Multiple options can be given, separated
1049 by commas. Possible values are "", "T1", "OT1", "LGR,T1" or any other
1050 combination of `LaTeX font encodings`_.
1052 Default: "T1". Option: ``--font-encoding``.
1054 .. _LaTeX font encodings:
1055 http://mirror.ctan.org/macros/latex/doc/encguide.pdf
1057 .. _embed_stylesheet [latex2e writer]:
1060 Embed the stylesheet(s) in the header of the output file. The
1061 stylesheets must be accessible during processing. Currently, this
1062 fails if the file is not available via the given path (i.e. the
1063 file is *not* searched in the `TeX input path`_).
1064 Also defined for the `HTML Writer`__ (with default *on*).
1066 Default: off. Options: ``--embed-stylesheet, --link-stylesheet``.
1068 __ `embed_stylesheet [html4css1 writer]`_
1070 .. _stylesheet [latex2e writer]:
1073 A comma-separated list of style files.
1074 Also defined for the `HTML Writer`__.
1076 Overrides also stylesheet_path__. [#override]_
1078 If `embed_stylesheet`__ is False (default), the stylesheet files are
1079 referenced with ``\usepackage`` (extension ``.sty`` or no extension) or
1080 ``\input`` (any other extension).
1082 LaTeX will search the specified files in the `TeX input path`_.
1084 Default: no stylesheet (""). Option: ``--stylesheet``.
1086 __ `stylesheet_path [latex2e writer]`_
1087 __ `embed_stylesheet [latex2e writer]`_
1088 __ `stylesheet [html4css1 writer]`_
1090 http://www.tex.ac.uk/cgi-bin/texfaq2html?label=what-TDS
1093 .. _stylesheet_path [latex2e writer]:
1096 Similar to stylesheet__, however paths [#pwd]_ are rewritten relative to
1097 the output file (if there is a common part in the given path and the
1098 output file path). Also defined for the `HTML Writer`__.
1100 Run ``latex`` from the directory containing the output file. Fails for
1101 files in the TEXINPUTS path; use stylesheet__ in this case.
1103 Also overrides stylesheet__. [#override]_
1105 Default: no stylesheet (""). Option: ``--stylesheet-path``.
1107 __ `stylesheet [latex2e writer]`_
1108 __ `stylesheet_path [html4css1 writer]`_
1110 __ `stylesheet [latex2e writer]`_
1114 LaTeX code that will be inserted in the document preamble.
1115 Can be used to load packages with options or (re-) define LaTeX
1116 macros without writing a custom style file (new in Docutils 0.7).
1118 Default: Load the "PDF standard fonts" (Times, Helvetica,
1121 \usepackage{mathptmx} % Times
1122 \usepackage[scaled=.90]{helvet}
1123 \usepackage{courier}
1125 Option: ``--latex-preamble``
1128 .. _template [latex2e writer]:
1131 Path to template file, which must be encoded in UTF-8 [#pwd]_.
1132 Also defined for the `HTML Writer`__.
1134 Default: "default.tex" in the docutils/writers/latex2e/
1135 directory (installed automatically; for the exact machine-specific
1136 path, use the ``--help`` option). Options: ``--template``.
1138 __ `template [html4css1 writer]`_
1140 .. _footnote_references [latex2e writer]:
1143 Format for footnote references: one of "superscript" or
1144 "brackets". Also defined for the `HTML Writer`__.
1146 Overrides [#override]_ trim_footnote_reference_space_, if
1147 applicable [#footnote_space]_.
1149 Default: "superscript". Option: ``--footnote-references``.
1151 __ `footnote_references [html4css1 writer]`_
1153 .. _attribution [latex2e writer]:
1156 Format for block quote attributions, the same as for the
1157 html-writer: one of "dash" (em-dash prefix),
1158 "parentheses"/"parens" or "none". Also defined for the `HTML
1161 Default: "dash". Option: ``--attribution``.
1163 __ `attribution [html4css1 writer]`_
1165 _`compound_enumerators`
1166 Enable or disable compound enumerators for nested enumerated lists
1169 Default: disabled (None). Options: ``--compound-enumerators``,
1170 ``--no-compound-enumerators``.
1172 _`literal_block_env`
1173 When possibile\ [#]_, use the specified environment for literal-blocks.
1175 Default: "" (quoting of whitespace and special chars)
1176 Option: ``--literal-block-env``
1178 .. [#] A literal-block element, when processed by a Docutils writer might
1179 have it's origin in a markup with "::" syntax or a "..
1180 parsed-literal::" directive.
1182 A LaTeX verbatim environment is only usable if there is no other
1183 markup contained in the literal-block.
1186 _`section_prefix_for_enumerators`
1187 Enable or disable section ("." subsection ...) prefixes for
1188 compound enumerators. This has no effect unless
1189 `compound_enumerators`_ are enabled.
1191 Default: disabled (None). Options:
1192 ``--section-prefix-for-enumerators``,
1193 ``--no-section-prefix-for-enumerators``.
1195 _`section_enumerator_separator`
1196 The separator between section number prefix and enumerator for
1197 compound enumerated lists (see `compound_enumerators`_).
1199 Generally it isn't recommended to use both sub-sections and nested
1200 enumerated lists with compound enumerators. This setting avoids
1201 ambiguity in the situation where a section "1" has a list item
1202 enumerated "1.1", and subsection "1.1" has list item "1". With a
1203 separator of ".", these both would translate into a final compound
1204 enumerator of "1.1.1". With a separator of "-", we get the
1205 unambiguous "1-1.1" and "1.1-1".
1207 Default: "-". Option: ``--section-enumerator-separator``.
1209 .. _table_style [latex2e writer]:
1212 Specify the drawing of separation lines.
1216 lines around and between cells.
1218 a line above and below the table and one after the head.
1222 Default: "standard". Option: ``--table-style``.
1227 The xetex writer derives from the latex2e writer, and shares
1228 all settings defined in the `[latex2e writer]`_ section. The
1229 "[latex2e writer]" section of configuration files is processed
1230 before the "[xetex writer]" section.
1232 The following settings differ from those of the latex2e writer:
1235 Disabled as XeTeX uses Unicode-encoded fonts.
1237 .. _latex_preamble [xetex writer]:
1240 LaTeX code that will be inserted in the document preamble.
1243 Font setup for `Linux Libertine`_,::
1245 % Linux Libertine (free, wide coverage, not only for Linux)
1246 \setmainfont{Linux Libertine O}
1247 \setsansfont{Linux Biolinum O}
1248 \setmonofont[HyphenChar=None]{DejaVu Sans Mono}
1250 The optional argument ``HyphenChar=None`` to the monospace font
1251 prevents word hyphenation in literal text.
1254 Option: ``--latex-preamble``
1256 .. _Linux Libertine: http://www.linuxlibertine.org/
1258 .. _template [xetex writer]:
1261 Path to template file.
1263 Default: "xelatex.tex" in the ``docutils/writers/latex2e/``
1264 directory (installed automatically; for the exact machine-specific
1265 path, use the ``--help`` option). Options: ``--template``.
1271 No settings are defined for this Writer.
1277 [buildhtml application]
1278 ```````````````````````
1281 List of wildcard (shell globing) patterns to silently ignore. To
1282 specify multiple patterns in configuration files, use
1283 colon-separated patterns; on the command line, the option may be
1284 used more than once.
1286 Default: ['.svn', 'CVS']. Options: ``--ignore``.
1289 List of directories not to process. To specify multiple
1290 directories in configuration files, use colon-separated paths; on
1291 the command line, the option may be used more than once.
1293 Default: none ([]). Options: ``--prune``.
1296 Recursively scan subdirectories, or ignore subdirectories.
1298 Default: recurse (1). Options: ``--recurse, --local``.
1301 Work silently (no progress messages). Independent of
1304 Default: show progress (None). Options: ``--silent``.
1307 [docfactory application]
1308 ````````````````````````
1319 These settings are only effective as command-line options; setting
1320 them in configuration files has no effect.
1323 Path to a configuration file to read (if it exists) [#pwd]_.
1324 Settings may override defaults and earlier settings. The config
1325 file is processed immediately. Multiple ``--config`` options may
1326 be specified; each will be processed in turn.
1328 Filesystem path settings contained within the config file will be
1329 interpreted relative to the config file's location (*not* relative
1330 to the current working directory).
1332 Default: None. Options: ``--config``.
1338 These settings are for internal use only; setting them in
1339 configuration files has no effect, and there are no corresponding
1340 command-line options.
1343 List of paths of applied configuration files.
1345 Default: None. No command-line options.
1348 (``buildhtml.py`` front end.) List of paths to source
1349 directories, set from positional arguments.
1351 Default: current working directory (None). No command-line
1355 Prevent standard configuration files from being read. For
1356 programmatic use only.
1358 Default: config files enabled (None). No command-line options.
1361 Path to output destination, set from positional arguments.
1363 Default: stdout (None). No command-line options.
1366 Path to input source, set from positional arguments.
1368 Default: stdin (None). No command-line options.
1371 .. _language tag: http://www.w3.org/International/articles/language-tags/
1372 .. _BCP 47: http://www.rfc-editor.org/rfc/bcp/bcp47.txt
1373 .. _ISO 639: http://www.loc.gov/standards/iso639-2/php/English_list.php
1374 .. _ISO 3166: http://www.iso.ch/iso/en/prods-services/iso3166ma/
1375 02iso-3166-code-lists/index.html
1377 .. [#pwd] Path relative to the working directory of the process at
1380 .. [#override] The overridden setting will automatically be set to
1381 ``None`` for command-line options and config file settings. Client
1382 programs which specify defaults that override other settings must
1383 do the overriding explicitly, by assigning ``None`` to the other
1386 .. [#dependencies] Some notes on the dependency recorder:
1388 * Images are only added to the dependency list if the
1389 reStructuredText parser extracted image dimensions from the file.
1391 * Stylesheets are only added if they are embedded.
1393 * For practical reasons, the output of the LaTeX writer is
1394 considered merely an *intermediate* processing stage. The
1395 dependency recorder records all files the *rendered* file
1396 (e.g. in PDF or DVI format) depends on. Thus, images and
1397 stylesheets are both unconditionally recorded as dependencies
1398 when using the LaTeX writer.
1400 .. [#footnote_space] The footnote space is trimmed if the reference
1401 style is "superscript", and it is left if the reference style is
1404 The overriding only happens if the parser supports the
1405 trim_footnote_reference_space option.
1408 ------------------------------
1409 Old-Format Configuration Files
1410 ------------------------------
1412 Formerly, Docutils configuration files contained a single "[options]"
1413 section only. This was found to be inflexible, and in August 2003
1414 Docutils adopted the current component-based configuration file
1415 sections as described above. Docutils will still recognize the old
1416 "[options]" section, but complains with a deprecation warning.
1418 To convert existing config files, the easiest way is to change the
1419 section title: change "[options]" to "[general]". Most settings
1420 haven't changed. The only ones to watch out for are these:
1422 ===================== =====================================
1423 Old-Format Setting New Section & Setting
1424 ===================== =====================================
1425 pep_stylesheet [pep_html writer] stylesheet
1426 pep_stylesheet_path [pep_html writer] stylesheet_path
1427 pep_template [pep_html writer] template
1428 ===================== =====================================