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 can be comma- or colon-delimited.
97 strip_classes_, strip_elements_with_classes_, stylesheet, and
98 stylesheet_path use the comma as delimiter,
99 whitespace around list values is stripped. ::
101 strip-classes: ham,eggs,
102 strip-elements-with-classes: sugar, salt, flour
103 stylesheet: html4css1.css,
105 style with spaces.css
106 stylesheet-path: ../styles/my.css, ../styles/funny.css
108 expose_internals_, ignore_ and prune_ use the colon as delimiter and do not
111 expose_internals: b:c:d
117 This is the contents of the ``tools/docutils.conf`` configuration file
118 supplied with Docutils::
120 # These entries affect all processing:
123 datestamp: %Y-%m-%d %H:%M UTC
126 # These entries affect HTML output:
128 # Required for docutils-update, the website build system:
129 stylesheet-path: ../docutils/writers/html4css1/html4css1.css
133 Individual configuration sections and settings are described in the
137 -------------------------------------
138 Configuration File Sections & Entries
139 -------------------------------------
141 Below are the Docutils runtime settings, listed by config file
142 section. Any setting may be specified in any section, but only
143 settings from active sections will be used. Sections correspond to
144 Docutils components (module name or alias; section names are always in
145 lowercase letters). Each `Docutils application`_ uses a specific set
146 of components; corresponding configuration file sections are applied
147 when the application is used. Configuration sections are applied in
148 general-to-specific order, as follows:
152 2. `[parsers]`_, parser dependencies, and the section specific to the
153 Parser used ("[... parser]"). Currently, only `[restructuredtext
154 parser]`_ is applicable.
156 3. `[readers]`_, reader dependencies, and the section specific to the
157 Reader used ("[... reader]"). For example, `[pep reader]`_ depends
158 on `[standalone reader]`_.
160 4. `[writers]`_, writer dependencies, and the section specific to the
161 Writer used ("[... writer]"). For example, `[pep_html writer]`_
162 depends on `[html4css1 writer]`_.
164 5. `[applications]`_, application dependencies, and the section
165 specific to the Application (front-end tool) in use
166 ("[... application]").
168 Since any setting may be specified in any section, this ordering
169 allows component- or application-specific overrides of earlier
170 settings. For example, there may be Reader-specific overrides of
171 general settings; Writer-specific overrides of Parser settings;
172 Application-specific overrides of Writer settings; and so on.
174 If multiple configuration files are applicable, the process is
175 completed (all sections are applied in the order given) for each one
176 before going on to the next. For example, a "[pep_html writer]
177 stylesheet" setting in an earlier configuration file would be
178 overridden by an "[html4css1 writer] stylesheet" setting in a later
181 Some knowledge of Python_ is assumed for some attributes.
184 http://www.python.org/doc/current/lib/module-ConfigParser.html
185 .. _Python: http://www.python.org/
186 .. _RFC 822: http://www.rfc-editor.org/rfc/rfc822.txt
187 .. _Docutils application: tools.html
193 Settings in the "[general]" section are always applied.
196 Prefix prepended to all auto-generated IDs generated within the
197 document, after id_prefix_.
199 Default: "id". Options: ``--auto-id-prefix`` (hidden, intended
200 mainly for programmatic use).
203 Include a time/datestamp in the document footer. Contains a
204 format string for Python's ``time.strftime``. See the `time
205 module documentation`__.
207 Default: None. Options: ``--date, -d, --time, -t,
210 Configuration file entry examples::
212 # Equivalent to --date command-line option, results in
213 # ISO 8601 extended format datestamp, e.g. "2001-12-21":
216 # Equivalent to --time command-line option, results in
217 # date/timestamp like "2001-12-21 18:43 UTC":
218 datestamp: %Y-%m-%d %H:%M UTC
220 # Disables datestamp; equivalent to --no-datestamp:
223 __ http://www.python.org/doc/current/lib/module-time.html
226 Report debug-level system messages.
228 Default: don't (None). Options: ``--debug, --no-debug``.
231 At the end of processing, write all internal attributes of the
232 document (``document.__dict__``) to stderr.
234 Default: don't (None). Options: ``--dump-internals`` (hidden, for
235 development use only).
238 At the end of processing, write the pseudo-XML representation of
239 the document to stderr.
241 Default: don't (None). Options: ``--dump-pseudo-xml`` (hidden,
242 for development use only).
245 At the end of processing, write all Docutils settings to stderr.
247 Default: don't (None). Options: ``--dump-settings`` (hidden, for
248 development use only).
251 At the end of processing, write a list of all transforms applied
252 to the document to stderr.
254 Default: don't (None). Options: ``--dump-transforms`` (hidden,
255 for development use only).
258 The text encoding for error output.
260 Default: "ascii". Options: ``--error-encoding, -e``.
262 _`error_encoding_error_handler`
263 The error handler for unencodable characters in error output. See
264 output_encoding_error_handler_ for acceptable values.
266 Default: "backslashreplace"
267 Options: ``--error-encoding-error-handler,
268 --error-encoding, -e``.
271 A system message level threshold; non-halting system messages at
272 or above this level will produce a non-zero exit status at normal
273 exit. Exit status is the maximum system message level plus 10 (11
276 Default: disabled (5). Options: ``--exit-status``.
279 List of internal attribues to expose as external attributes (with
280 "internal:" namespace prefix). To specify multiple attributes in
281 configuration files, use colons to separate names; on the command
282 line, the option may be used more than once.
284 Default: don't (None). Options: ``--expose-internal-attribute``
285 (hidden, for development use only).
287 _`footnote_backlinks`
288 Enable or disable backlinks from footnotes and citations to their
291 Default: enabled (1). Options: ``--footnote-backlinks,
292 --no-footnote-backlinks``.
295 Include a "Generated by Docutils" credit and link in the document
298 Default: off (None). Options: ``--generator, -g,
302 The threshold at or above which system messages are converted to
303 exceptions, halting execution immediately. If `traceback`_ is
304 set, the exception will propagate; otherwise, Docutils will exit.
306 Default: severe (4). Options: ``--halt, --strict``.
309 Prefix prepended to all IDs generated within the document. See
310 also auto_id_prefix_.
312 Default: "" (empty). Options: ``--id-prefix`` (hidden, intended
313 mainly for programmatic use).
316 The text encoding for input.
318 Default: auto-detect (None). Options: ``--input-encoding, -i``.
320 _`input_encoding_error_handler`
321 The error handler for undecodable characters in the input.
322 Acceptable values include:
325 Raise an exception in case of an encoding error.
327 Replace malformed data with the official Unicode replacement
330 Ignore malformed data and continue without further notice.
332 Acceptable values are the same as for the "error" parameter of
333 Python's ``unicode`` function; other values may be defined in
334 applications or in future versions of Python.
336 Default: "strict". Options: ``--input-encoding-error-handler,
337 --input-encoding, -i``.
340 Case-insensitive `language tag`_ as defined in `BCP 47`_.
342 Sets the document language, also used for localized directive and
343 role names as well as Docutils-generated text.
345 A typical language identifier consists of a 2-letter language code
346 from `ISO 639`_ (3-letter codes can be used if no 2-letter code
347 exists). The language identifier can have an optional subtag,
348 typically for variations based on country (from `ISO 3166`_
349 2-letter country codes). Avoid subtags except where they add
350 useful distinguishing information. Examples of language tags
351 include "fr", "en-GB", "pt_br" (the same as "pt-BR"), and
352 "de-1901" (German with pre-1998 spelling).
354 The language of document parts can be specified with a
355 "language-<language tag>" `class attribute`_, e.g.
356 ``.. class:: language-el-polyton`` for a quote in polytonic Greek.
358 Default: English ("en"). Options: ``--language, -l``.
360 .. _class attribute: ../ref/doctree.html#classes
363 The text encoding for output.
365 Default: "UTF-8". Options: ``--output-encoding, -o``.
367 _`output_encoding_error_handler`
368 The error handler for unencodable characters in the output.
369 Acceptable values include:
372 Raise an exception in case of an encoding error.
374 Replace malformed data with a suitable replacement marker,
377 Ignore malformed data and continue without further notice.
379 Replace with the appropriate XML character reference, such as
382 Replace with backslashed escape sequences, such as "``\u2020``".
384 Acceptable values are the same as for the "error" parameter of
385 Python's ``encode`` string method; other values may be defined in
386 applications or in future versions of Python.
388 Default: "strict". Options: ``--output-encoding-error-handler,
389 --output-encoding, -o``.
391 _`record_dependencies`
392 Path to a file where Docutils will write a list of files that were
393 required to generate the output, e.g. included files or embedded
394 stylesheets [#dependencies]_. [#pwd]_ The format is one path per
395 line with forward slashes as separator, the encoding is ``utf8``.
397 Set to ``-`` in order to write dependencies to stdout.
399 This option is particularly useful in conjunction with programs like
400 ``make`` using ``Makefile`` rules like::
402 ham.html: ham.txt $(shell cat hamdeps.txt)
403 rst2html.py --record-dependencies=hamdeps.txt ham.txt ham.html
405 If the filesystem encoding differs from utf8, replace the ``cat``
406 command with a call to a converter, e.g.::
408 $(shell iconv -f utf8 -t latin1 hamdeps.txt)
410 Default: None. Option: ``--record-dependencies``.
413 Report system messages at or higher than <level>:
421 Default: warning (2). Options: ``--report, -r, --verbose, -v,
425 Enable or disable automatic section numbering by Docutils
426 (docutils.transforms.parts.SectNum) associated with the `sectnum
429 If disabled, section numbers might be added to the output by the
430 renderer (e.g. LaTeX or via a CSS style definition).
432 Default: enabled (1). Options: ``--section-numbering``,
433 ``--no-section-numbering``.
435 .. _sectnum directive: ../ref/rst/directives.html#sectnum
438 Include a "View document source" link in the document footer. URL
439 will be relative to the destination.
441 Default: don't (None). Options: ``--source-link, -s,
445 An explicit URL for a "View document source" link, used verbatim.
447 Default: compute if source_link (None). Options: ``--source-url,
451 When processing a document tree with the Visitor pattern, raise an
452 error if a writer does not support a node type listed as optional.
453 For transitional development use.
455 Default: disabled (None). Option: ``--strict-visitor`` (hidden,
456 for development use only).
459 Comma-separated list of "classes" attribute values to remove from
460 all elements in the document tree.
461 The command line option may be used more than once.
463 .. WARNING:: Potentially dangerous; use with caution.
465 Default: disabled (None). Option: ``--strip-class``.
468 Enable the removal of comment elements from the document tree.
470 Default: disabled (None). Options: ``--strip-comments``,
471 ``--leave-comments``.
473 _`strip_elements_with_classes`
474 Comma-separated list of "classes" attribute values;
475 matching elements are removed from the document tree.
476 The command line option may be used more than once.
478 .. WARNING:: Potentially dangerous; use with caution.
480 Default: disabled (None). Option: ``--strip-element-with-class``.
483 The document title as metadata, which does not become part of the
484 document body. It overrides a document-supplied title. For
485 example, in HTML output the metadata document title appears in the
486 title bar of the browser window.
488 Default: none. Option: ``--title``.
491 Enable backlinks from section titles to table of contents entries
492 ("entry"), to the top of the TOC ("top"), or disable ("none").
494 Default: "entry". Options: ``--toc-entry-backlinks,
495 --toc-top-backlinks, --no-toc-backlinks``.
498 Enable Python tracebacks when halt-level system messages and other
499 exceptions occur. Useful for debugging, and essential for issue
500 reports. Exceptions are allowed to propagate, instead of being
501 caught and reported (in a user-friendly way) by Docutils.
503 Default: disabled (None) unless Docutils is run programmatically
504 using the `Publisher Interface`_. Options: ``--traceback,
507 .. _Publisher Interface: ../api/publisher.html
510 Path to a file for the output of system messages (warnings)
513 Default: stderr (None). Options: ``--warnings``.
519 Docutils currently supports only one parser, for reStructuredText.
522 [restructuredtext parser]
523 `````````````````````````
525 _`file_insertion_enabled`
526 Enable or disable directives that insert the contents of external
527 files, such as the "include_" & "raw_". A "warning" system
528 message (including the directive text) is inserted instead. (See
529 also raw_enabled_ for another security-relevant setting.)
531 Default: enabled (1). Options: ``--file-insertion-enabled,
532 --no-file-insertion``.
534 .. _include: ../ref/rst/directives.html#include
535 .. _raw: ../ref/rst/directives.html#raw
538 Recognize and link to standalone PEP references (like "PEP 258").
540 Default: disabled (None); enabled (1) in PEP Reader. Options:
541 ``--pep-references``.
544 Base URL for PEP references.
546 Default: "http://www.python.org/peps/". Option:
549 _`pep_file_url_template`
550 Template for PEP file part of URL, interpolated with the PEP
551 number and appended to pep_base_url_.
553 Default: "pep-%04d". Option: ``--pep-file-url``.
556 Enable or disable the "raw_" directive. A "warning" system
557 message (including the directive text) is inserted instead. (See
558 also file_insertion_enabled_ for another security-relevant
561 Default: enabled (1). Options: ``--raw-enabled, --no-raw``.
564 Recognize and link to standalone RFC references (like "RFC 822").
566 Default: disabled (None); enabled (1) in PEP Reader. Options:
567 ``--rfc-references``.
570 Base URL for RFC references.
572 Default: "http://www.faqs.org/rfcs/". Option: ``--rfc-base-url``.
575 Number of spaces for hard tab expansion.
577 Default: 8. Options: ``--tab-width``.
579 _`trim_footnote_reference_space`
580 Remove spaces before footnote references.
582 Default: don't (None); may be overriden by a writer-specific
583 footnote_references__ default though. Options:
584 ``--trim-footnote-reference-space,
585 --leave-footnote-reference-space``.
587 __ `footnote_references [latex2e writer]`_
591 Token type names used by Pygments_ when parsing contents of the code_
597 Use hierarchy of long token type names.
599 Use short token type names. (For use with
600 `Pygments-generated stylesheets`_.)
602 No code parsing. Use this to avoid the "Pygments not
603 found" warning when Pygments is not installed.
605 Default: "long". Option: ``--syntax-highlight``.
609 .. _Pygments: http://pygments.org/
610 .. _code: ../ref/rst/directives.html#code
611 .. _Pygments-generated stylesheets:
612 http://pygments.org/docs/cmdline/#generating-styles
615 Change straight quotation marks to typographic form. `Quote characters`_
616 are selected according to the language of the current block element (see
617 language_code_). Also changes consequtive runs of hyphen-minus and full
618 stops (``---``, ``--``, ``...``) to em-dash, en-dash and ellipsis
619 Unicode characters respectively.
626 alt (or "alternative")
627 Use alternative quote set (if defined for the language).
629 Default: "no". Option: ``--smart-quotes``.
631 New in Docutils 0.10.
633 .. _quote characters:
634 http://en.wikipedia.org/wiki/Non-English_usage_of_quotation_marks
645 Enable or disable the bibliographic field list transform
646 (docutils.transforms.frontmatter.DocInfo).
648 Default: enabled (1). Options: ``--no-doc-info``.
651 Enable or disable the promotion of a lone top-level section title
652 to document title (and subsequent section title to document
653 subtitle promotion; docutils.transforms.frontmatter.DocTitle).
655 Default: enabled (1). Options: ``--no-doc-title``.
657 _`sectsubtitle_xform`
659 Enable or disable the promotion of the title of a lone subsection
660 to a subtitle (docutils.transforms.frontmatter.SectSubTitle).
662 Default: disabled (0). Options: ``--section-subtitles,
663 --no-section-subtitles``.
669 The `pep_references`_ and `rfc_references`_ settings
670 (`[restructuredtext parser]`_) are set on by default.
682 [docutils_xml writer]
683 `````````````````````
687 * In Python versions older than 2.7.3 and 3.2.3, the newlines_ and
688 indents_ options may adversely affect whitespace; use them only for
689 reading convenience (see http://bugs.python.org/issue4147).
691 * The XML declaration carries text encoding information, without which
692 standard tools may be unable to read the generated XML.
694 _`doctype_declaration`
695 Generate XML with a DOCTYPE declaration.
697 Default: do (1). Options: ``--no-doctype``.
700 Generate XML with indents and newlines.
702 Default: don't (None). Options: ``--indents``.
705 Generate XML with newlines before and after tags.
707 Default: don't (None). Options: ``--newlines``.
709 .. _xml_declaration [docutils_xml writer]:
712 Generate XML with an XML declaration. Also defined for the
715 Default: do (1). Options: ``--no-xml-declaration``.
717 __ `xml_declaration [html4css1 writer]`_
723 .. _attribution [html4css1 writer]:
726 Format for block quote attributions: one of "dash" (em-dash
727 prefix), "parentheses"/"parens", or "none". Also defined for the
730 Default: "dash". Options: ``--attribution``.
732 __ `attribution [latex2e writer]`_
734 _`cloak_email_addresses`
735 Scramble email addresses to confuse harvesters. In the reference
736 URI, the "@" will be replaced by %-escapes (as of RFC 1738). In
737 the visible text (link text) of an email reference, the "@" and
738 all periods (".") will be surrounded by ``<span>`` tags.
739 Furthermore, HTML entities are used to encode these characters in
740 order to further complicate decoding the email address. For
741 example, "abc@example.org" will be output as::
743 <a class="reference" href="mailto:abc%40example.org">
744 abc<span>@</span>example<span>.</span>org</a>
746 .. Note:: While cloaking email addresses will have little to no
747 impact on the rendering and usability of email links in most
748 browsers, some browsers (e.g. the ``links`` browser) may decode
749 cloaked email addresses incorrectly.
751 Default: don't cloak (None). Option: ``--cloak-email-addresses``.
754 Remove extra vertical whitespace between items of bullet lists and
755 enumerated lists, when list items are all "simple" (i.e., items
756 each contain one paragraph and/or one "simple" sublist only). The
757 behaviour can be specified directly via "class" attributes (values
758 "compact" and "open") in the document.
760 Default: enabled (1). Options: ``--compact-lists,
761 --no-compact-lists``.
763 _`compact_field_lists`
764 Remove extra vertical whitespace between items of field lists that
765 are "simple" (i.e., all field bodies each contain at most one
766 paragraph). The behaviour can be specified directly via "class"
767 attributes (values "compact" and "open") in the document.
769 Default: enabled (1). Options: ``--compact-field-lists,
770 --no-compact-field-lists``.
772 .. _embed_stylesheet [html4css1 writer]:
775 Embed the stylesheet in the output HTML file. The stylesheet file
776 must specified by the stylesheet_path__ setting and must be
777 accessible during processing.
778 Also defined for the `LaTeX Writer`__.
780 Default: enabled. Options: ``--embed-stylesheet,
783 __ `stylesheet_path [html4css1 writer]`_
784 __ `embed_stylesheet [latex2e writer]`_
787 The maximum width (in characters) for one-column field names.
788 Longer field names will span an entire row of the table used to
789 render the field list. 0 indicates "no limit". See also
792 Default: 14 characters. Option: ``--field-name-limit``.
794 .. _footnote_references [html4css1 writer]:
797 Format for footnote references, one of "superscript" or
798 "brackets". Also defined for the `LaTeX Writer`__.
800 Overrides [#override]_ trim_footnote_reference_space_, if
801 applicable. [#footnote_space]_
803 Default: "brackets". Option: ``--footnote-references``.
805 __ `footnote_references [latex2e writer]`_
807 _`initial_header_level`
808 The initial level for header elements. This does not affect the
809 document title & subtitle; see doctitle_xform_.
811 Default: 1 (for "<h1>"). Option: ``--initial-header-level``.
814 The format of mathematical content (`math directive`_ and role) in
815 the output document. Supported values are (case insensitive):
818 Format math for display with MathJax_, a JavaScript-based math
819 rendering engine that uses HTML/CSS, JavaScript, and unicode
820 fonts for high-quality typesetting that is scalable and prints
823 A custom URL can be appended after whitespace,
824 for example a local install
825 ``MathJax file:/usr/share/javascript/mathjax/MathJax.js`` or
826 `access the MathJax CDN using a https secure connection`__
827 ``mathjax https://c328740.ssl.cf1.rackcdn.com/mathjax/latest/MathJax.js?config=config=TeX-AMS-MML_HTMLorMML``.
829 __ http://www.mathjax.org/resources/faqs/#problem-https
832 Works 'out of the box' across multiple browsers and platforms.
834 Supports a large subset of LaTeX math commands and constructs
835 (see http://www.mathjax.org/docs/1.1/tex.html).
838 Requires an Internet connection (or a local MathJax
839 installation and configuration).
841 Downloads JavaScript code from a third-party site.
844 Format math in standard HTML enhanced by CSS rules
846 Requires the ``math.css`` stylesheet (stored in the same
847 installation-dependent directory as the `default stylesheet`__).
849 .. __: `stylesheet_path [html4css1 writer]`_
852 Embed math content as presentational MathML_.
855 The W3C recommendation for math on the web.
857 Self-contained documents (no JavaScript, no external downloads).
860 Docutil's latex2mathml converter supports only a small
861 subset of LaTeX syntax.
863 With the "html4css1" writer, the resulting HTML document does
864 not validate, as there is no DTD for MathML + XHTML
865 Transitional. However, MathML-enabled browsers will render it
869 Include literal LaTeX code.
871 The failsave fallback.
873 Default: MathJax Option: ``--math-output``.
877 .. _math directive: ../ref/rst/directives.html#math
878 .. _MathJax: http://www.mathjax.org/
879 .. _MathPlayer: http://www.dessci.com/en/products/mathplayer/
880 .. _MathML: http://www.w3.org/TR/MathML/
883 The maximum width (in characters) for options in option lists.
884 Longer options will span an entire row of the table used to render
885 the option list. 0 indicates "no limit". See also
888 Default: 14 characters. Option: ``--option-limit``.
890 .. _stylesheet [html4css1 writer]:
893 A comma-separated list of CSS stylesheet URLs, used verbatim.
894 Also defined for the `LaTeX Writer`__.
896 Overrides also stylesheet-path__. [#override]_
898 Default: None. Options: ``--stylesheet``.
900 __ `stylesheet [latex2e writer]`_
901 __ `stylesheet_path [html4css1 writer]`_
903 .. _stylesheet_path [html4css1 writer]:
906 A comma-separated list of paths [#pwd]_ to CSS stylesheets.
907 If embed_stylesheet__ is False, paths are rewritten relative to the
908 output HTML file. Also defined for the `LaTeX Writer`__.
910 Also overrides "stylesheet". [#override]_
911 Pass an empty string (to either "stylesheet" or "stylesheet_path") to
912 deactivate stylesheet inclusion.
914 Default: "html4css1.css" in the docutils/writers/html4css1/
915 directory (installed automatically; for the exact machine-specific
916 path, use the ``--help`` option). Options: ``--stylesheet-path``.
918 __ `embed_stylesheet [html4css1 writer]`_
919 __ `stylesheet_path [latex2e writer]`_
921 .. _table_style [html4css1 writer]:
924 Added to standard table classes to allow styling with CSS.
925 The default sylesheet defines:
928 no borders around the table.
931 a line above and below the table and one after the head.
933 Default: "". Option: ``--table-style``.
935 .. _template [html4css1 writer]:
938 Path to template file, which must be encoded in UTF-8 [#pwd]_.
939 Also defined for the `LaTeX Writer`__.
941 Default: "template.txt" in the docutils/writers/html4css1/
942 directory (installed automatically; for the exact machine-specific
943 path, use the ``--help`` option). Options: ``--template``.
945 __ `template [latex2e writer]`_
947 .. _xml_declaration [html4css1 writer]:
950 Generate XML with an XML declaration. Also defined for the
951 `Docutils XML Writer`__.
953 .. Caution:: The XML declaration carries text encoding
954 information, without which standard tools may be unable to read
957 Default: do (1). Options: ``--no-xml-declaration``.
959 __ `xml_declaration [docutils_xml writer]`_
965 The PEP/HTML Writer derives from the standard HTML Writer, and shares
966 all settings defined in the `[html4css1 writer]`_ section. The
967 "[html4css1 writer]" section of configuration files is processed
968 before the "[pep_html writer]" section.
971 Do not use a random banner image. Mainly used to get predictable
972 results when testing.
974 Default: random enabled (None). Options: ``--no-random``
978 Home URL prefix for PEPs.
980 Default: current directory ("."). Options: ``--pep-home``.
985 Default: parent directory (".."). Options: ``--python-home``.
987 The PEP/HTML Writer's default for the following settings differ from
988 those of the standard HTML Writer:
990 * ``stylesheet_path``: The default is
991 ``docutils/writers/pep_html/pep.css`` in the installation directory.
992 For the exact machine-specific path, use the ``--help`` option.
994 * ``template``: The default is
995 ``docutils/writers/pep_html/template.txt`` in the installation
996 directory. For the exact machine-specific path, use the ``--help``
1003 The S5/HTML Writer derives from the standard HTML Writer, and shares
1004 all settings defined in the `[html4css1 writer]`_ section. The
1005 "[html4css1 writer]" section of configuration files is processed
1006 before the "[s5_html writer]" section.
1009 Auto-hide the presentation controls in slideshow mode, or or keep
1010 them visible at all times.
1012 Default: auto-hide (1). Options: ``--hidden-controls``,
1013 ``--visible-controls``.
1016 Enable or disable the current slide indicator ("1/15").
1018 Default: disabled (None). Options: ``--current-slide``,
1019 ``--no-current-slide``.
1021 _`overwrite_theme_files`
1022 Allow or prevent the overwriting of existing theme files in the
1023 ``ui/<theme>`` directory. This has no effect if "theme_url_" is
1026 Default: keep existing theme files (None). Options:
1027 ``--keep-theme-files``, ``--overwrite-theme-files``.
1030 Name of an installed S5 theme, to be copied into a ``ui/<theme>``
1031 subdirectory, beside the destination file (output HTML). Note
1032 that existing theme files will not be overwritten; the existing
1033 theme directory must be deleted manually.
1034 Also overrides the "theme_url_" setting. [#override]_
1036 Default: "default". Option: ``--theme``.
1039 The URL of an S5 theme directory. The destination file (output
1040 HTML) will link to this theme; nothing will be copied. Also overrides
1041 the "theme_" setting. [#override]_
1043 Default: None. Option: ``--theme-url``.
1046 The initial view mode, either "slideshow" or "outline".
1048 Default: "slidewhow". Option: ``--view-mode``.
1050 The S5/HTML Writer's default for the following settings differ
1051 from those of the standard HTML Writer:
1053 * ``compact_lists``: The default here is to disable compact lists.
1055 * ``template``: The default is
1056 ``docutils/writers/s5_html/template.txt`` in the installation
1057 directory. For the exact machine-specific path, use the ``--help``
1065 To get pagenumbers in the table of contents the table of contents
1066 must be generated by LaTeX. Usually latex must be run twice to get
1069 Default: on. Options: ``--use-latex-toc, --use-docutils-toc``.
1071 _`use_latex_docinfo`
1072 Attach author and date to the document title
1073 instead of the document info table.
1075 Default: off. Options: ``--use-latex-docinfo, --use-docutils-docinfo``
1077 _`docutils_footnotes`
1078 Use the Docutils-specific macros ``\DUfootnote`` and
1079 ``\DUfootnotetext`` for footnotes.
1081 Default: on. Option: ``--docutils-footnotes``.
1083 _`use_latex_footnotes`
1084 Backwards-compatibility alias for docutils_footnotes_ (deprecated).
1086 *Note*: the planned new option _`latex_footnotes` will use the
1087 ``\footnote`` command and footnote numbering by LaTeX.
1090 Typeset footnote text in a figure float.
1091 This may lead to footnotes, citations, and figures being
1094 *Deprecated:* This setting will be removed in a future Docutils
1097 Default: off. Option: ``--figure-footnotes``.
1099 _`use_latex_citations`
1100 Use \cite for citations instead of a simulation with figure-floats.
1102 Default: off. Options: ``--use-latex-citations, --figure-citations``.
1104 _`use_latex_abstract`
1105 Use LaTeX abstract environment for the document's abstract.
1107 Default: off. Options: ``--use-latex-abstract, --topic-abstract``.
1110 Color of any hyperlinks embedded in text.
1112 * "0" or "false" disable coloring of links. (Links will be marked
1113 by red boxes that are not printed),
1114 * "black" results in “invisible“ links,
1116 Set hyperref_options_ to "draft" to completely disable
1119 Default: "blue". Option: ``--hyperlink-color``.
1122 Options for the `hyperref TeX package`_. If hyperlink_color_ is
1123 not "false", the expansion of ::
1125 'colorlinks=true,linkcolor=%s,urlcolor=%s' % (
1126 hyperlink_color, self.hyperlink_color
1128 is prepended. For documents typeset in Cyrillic script,
1129 ``--hyperref-options=unicode`` is recommended.
1131 Default: "". Option: ``--hyperref-options``.
1133 .. _hyperref TeX package: http://tug.org/applications/hyperref/
1136 Specify latex documentclass.
1138 Default: "article". Option: ``--documentclass``.
1141 Specify document options. Multiple options can be given, separated by
1144 Default: "a4paper". Option: ``--documentoptions``.
1147 Specify LaTeX font encoding. Multiple options can be given, separated
1148 by commas. Possible values are "", "T1", "OT1", "LGR,T1" or any other
1149 combination of `LaTeX font encodings`_.
1151 Default: "T1". Option: ``--font-encoding``.
1153 .. _LaTeX font encodings:
1154 http://mirror.ctan.org/macros/latex/doc/encguide.pdf
1156 .. _embed_stylesheet [latex2e writer]:
1159 Embed the stylesheet(s) in the header of the output file. The
1160 stylesheets must be accessible during processing. Currently, this
1161 fails if the file is not available via the given path (i.e. the
1162 file is *not* searched in the `TeX input path`_).
1163 Also defined for the `HTML Writer`__ (with default *on*).
1165 Default: off. Options: ``--embed-stylesheet, --link-stylesheet``.
1167 __ `embed_stylesheet [html4css1 writer]`_
1169 .. _stylesheet [latex2e writer]:
1172 A comma-separated list of style files.
1173 Also defined for the `HTML Writer`__.
1175 Overrides also stylesheet_path__. [#override]_
1177 If `embed_stylesheet`__ is False (default), the stylesheet files are
1178 referenced with ``\usepackage`` (extension ``.sty`` or no extension) or
1179 ``\input`` (any other extension).
1181 LaTeX will search the specified files in the `TeX input path`_.
1183 Default: no stylesheet (""). Option: ``--stylesheet``.
1185 __ `stylesheet_path [latex2e writer]`_
1186 __ `embed_stylesheet [latex2e writer]`_
1187 __ `stylesheet [html4css1 writer]`_
1189 http://www.tex.ac.uk/cgi-bin/texfaq2html?label=what-TDS
1192 .. _stylesheet_path [latex2e writer]:
1195 Similar to stylesheet__, however paths [#pwd]_ are rewritten relative to
1196 the output file (if there is a common part in the given path and the
1197 output file path). Also defined for the `HTML Writer`__.
1199 Run ``latex`` from the directory containing the output file. Fails for
1200 files in the TEXINPUTS path; use stylesheet__ in this case.
1202 Also overrides stylesheet__. [#override]_
1204 Default: no stylesheet (""). Option: ``--stylesheet-path``.
1206 __ `stylesheet [latex2e writer]`_
1207 __ `stylesheet_path [html4css1 writer]`_
1209 __ `stylesheet [latex2e writer]`_
1213 LaTeX code that will be inserted in the document preamble.
1214 Can be used to load packages with options or (re-) define LaTeX
1215 macros without writing a custom style file (new in Docutils 0.7).
1217 Default: Load the "PDF standard fonts" (Times, Helvetica,
1220 \usepackage{mathptmx} % Times
1221 \usepackage[scaled=.90]{helvet}
1222 \usepackage{courier}
1224 Option: ``--latex-preamble``
1227 .. _template [latex2e writer]:
1230 Path to template file, which must be encoded in UTF-8 [#pwd]_.
1231 Also defined for the `HTML Writer`__.
1233 Default: "default.tex" in the docutils/writers/latex2e/
1234 directory (installed automatically; for the exact machine-specific
1235 path, use the ``--help`` option). Options: ``--template``.
1237 __ `template [html4css1 writer]`_
1239 .. _footnote_references [latex2e writer]:
1242 Format for footnote references: one of "superscript" or
1243 "brackets". Also defined for the `HTML Writer`__.
1245 Overrides [#override]_ trim_footnote_reference_space_, if
1246 applicable [#footnote_space]_.
1248 Default: "superscript". Option: ``--footnote-references``.
1250 __ `footnote_references [html4css1 writer]`_
1252 .. _attribution [latex2e writer]:
1255 Format for block quote attributions, the same as for the
1256 html-writer: one of "dash" (em-dash prefix),
1257 "parentheses"/"parens" or "none". Also defined for the `HTML
1260 Default: "dash". Option: ``--attribution``.
1262 __ `attribution [html4css1 writer]`_
1264 _`compound_enumerators`
1265 Enable or disable compound enumerators for nested enumerated lists
1268 Default: disabled (None). Options: ``--compound-enumerators``,
1269 ``--no-compound-enumerators``.
1271 _`literal_block_env`
1272 When possibile\ [#]_, use the specified environment for literal-blocks.
1274 Default: "" (quoting of whitespace and special chars)
1275 Option: ``--literal-block-env``
1277 .. [#] A literal-block element, when processed by a Docutils writer might
1278 have it's origin in a markup with "::" syntax or a "..
1279 parsed-literal::" directive.
1281 A LaTeX verbatim environment is only usable if there is no other
1282 markup contained in the literal-block.
1285 _`section_prefix_for_enumerators`
1286 Enable or disable section ("." subsection ...) prefixes for
1287 compound enumerators. This has no effect unless
1288 `compound_enumerators`_ are enabled.
1290 Default: disabled (None). Options:
1291 ``--section-prefix-for-enumerators``,
1292 ``--no-section-prefix-for-enumerators``.
1294 _`section_enumerator_separator`
1295 The separator between section number prefix and enumerator for
1296 compound enumerated lists (see `compound_enumerators`_).
1298 Generally it isn't recommended to use both sub-sections and nested
1299 enumerated lists with compound enumerators. This setting avoids
1300 ambiguity in the situation where a section "1" has a list item
1301 enumerated "1.1", and subsection "1.1" has list item "1". With a
1302 separator of ".", these both would translate into a final compound
1303 enumerator of "1.1.1". With a separator of "-", we get the
1304 unambiguous "1-1.1" and "1.1-1".
1306 Default: "-". Option: ``--section-enumerator-separator``.
1308 .. _table_style [latex2e writer]:
1311 Specify the drawing of separation lines.
1315 lines around and between cells.
1317 a line above and below the table and one after the head.
1321 Default: "standard". Option: ``--table-style``.
1326 The xetex writer derives from the latex2e writer, and shares
1327 all settings defined in the `[latex2e writer]`_ section. The
1328 "[latex2e writer]" section of configuration files is processed
1329 before the "[xetex writer]" section.
1331 The following settings differ from those of the latex2e writer:
1334 Disabled as XeTeX uses Unicode-encoded fonts.
1336 .. _latex_preamble [xetex writer]:
1339 LaTeX code that will be inserted in the document preamble.
1342 Font setup for `Linux Libertine`_,::
1344 % Linux Libertine (free, wide coverage, not only for Linux)
1345 \setmainfont{Linux Libertine O}
1346 \setsansfont{Linux Biolinum O}
1347 \setmonofont[HyphenChar=None]{DejaVu Sans Mono}
1349 The optional argument ``HyphenChar=None`` to the monospace font
1350 prevents word hyphenation in literal text.
1353 Option: ``--latex-preamble``
1355 .. _Linux Libertine: http://www.linuxlibertine.org/
1357 .. _template [xetex writer]:
1360 Path to template file.
1362 Default: "xelatex.tex" in the ``docutils/writers/latex2e/``
1363 directory (installed automatically; for the exact machine-specific
1364 path, use the ``--help`` option). Options: ``--template``.
1371 The following command line options are specific to ``odtwriter``:
1374 Specify a stylesheet URL, used verbatim. Default:
1375 writers/odf_odt/styles.odt in the installation directory.
1377 _`odf-config-file=<file>`
1378 Specify a configuration/mapping file relative to the
1379 current working directory for additional ODF options.
1380 In particular, this file may contain a section named
1381 "Formats" that maps default style names to names to be
1382 used in the resulting output file allowing for
1383 adhering to external standards. For more info and the
1384 format of the configuration/mapping file, see the
1385 `Odt Writer for Docutils`_ document.
1387 _`cloak-email-addresses`
1388 Obfuscate email addresses to confuse harvesters while still
1389 keeping email links usable with standards-compliant browsers.
1391 _`no-cloak-email-addresses`
1392 Do not obfuscate email addresses.
1394 _`table-border-thickness=<TABLE_BORDER_THICKNESS>`
1395 Specify the thickness of table borders in thousands of a cm.
1398 _`add-syntax-highlighting`
1399 Add syntax highlighting in literal code blocks.
1401 _`no-syntax-highlighting`
1402 Do not add syntax highlighting in literal code blocks.
1406 Create sections for headers. (default)
1409 Do not create sections for headers.
1415 Do not create links. (default)
1418 Generate endnotes at end of document, not footnotes at bottom of
1421 _`no-endnotes-end-doc`
1422 Generate footnotes at bottom of page, not endnotes at end of
1425 _`generate-list-toc`
1426 Generate a bullet list table of contents, not an
1427 ODF/``oowriter`` table of contents.
1429 _`generate-oowriter-toc`
1430 Generate an ODF/``oowriter`` table of contents, not a bullet
1431 list. (default) **Note:** ``odtwriter`` is not able to
1432 determine page numbers, so you will need to open the generated
1433 document in ``oowriter``, then right-click on the table of
1434 contents and select "Update" to insert page numbers.
1436 _`custom-odt-header=<CUSTOM_HEADER>`
1437 Specify the contents of a custom header line. For details about
1438 custom headers and about special field character sequences, see
1439 section "Custom header/footers: inserting page numbers, date,
1440 time, etc" in the `Odt Writer for Docutils`_ document for
1443 _`custom-odt-footer=<CUSTOM_FOOTER>`
1444 Specify the contents of a custom footer line. For details about
1445 custom footers and about special field character sequences, see
1446 section "Custom header/footers: inserting page numbers, date,
1447 time, etc" in the `Odt Writer for Docutils`_ document for
1450 .. _`Odt Writer for Docutils`: odt.html
1456 No settings are defined for this Writer.
1462 [buildhtml application]
1463 ```````````````````````
1466 List of wildcard (shell globing) patterns, specifying files to
1467 silently ignore. To specify multiple patterns, use
1468 colon-separated patterns (in configuration files or on the command
1469 line); on the command line, the option may also be used more than
1472 Default: none ([]). Options: ``--ignore``.
1475 List of directories not to process. To specify multiple
1476 directories, use colon-separated paths (in configuration files or
1477 on the command line); on the command line, the option may also be
1478 used more than once.
1480 Default: ['.hg', '.bzr', '.git', '.svn', 'CVS']. Options:
1484 Recursively scan subdirectories, or ignore subdirectories.
1486 Default: recurse (1). Options: ``--recurse, --local``.
1489 Work silently (no progress messages). Independent of
1492 Default: show progress (None). Options: ``--silent``.
1495 [docfactory application]
1496 ````````````````````````
1507 These settings are only effective as command-line options; setting
1508 them in configuration files has no effect.
1511 Path to a configuration file to read (if it exists) [#pwd]_.
1512 Settings may override defaults and earlier settings. The config
1513 file is processed immediately. Multiple ``--config`` options may
1514 be specified; each will be processed in turn.
1516 Filesystem path settings contained within the config file will be
1517 interpreted relative to the config file's location (*not* relative
1518 to the current working directory).
1520 Default: None. Options: ``--config``.
1526 These settings are for internal use only; setting them in
1527 configuration files has no effect, and there are no corresponding
1528 command-line options.
1531 List of paths of applied configuration files.
1533 Default: None. No command-line options.
1536 (``buildhtml.py`` front end.) List of paths to source
1537 directories, set from positional arguments.
1539 Default: current working directory (None). No command-line
1543 Prevent standard configuration files from being read. For
1544 programmatic use only.
1546 Default: config files enabled (None). No command-line options.
1549 Path to output destination, set from positional arguments.
1551 Default: stdout (None). No command-line options.
1554 Path to input source, set from positional arguments.
1556 Default: stdin (None). No command-line options.
1559 .. _language tag: http://www.w3.org/International/articles/language-tags/
1560 .. _BCP 47: http://www.rfc-editor.org/rfc/bcp/bcp47.txt
1561 .. _ISO 639: http://www.loc.gov/standards/iso639-2/php/English_list.php
1562 .. _ISO 3166: http://www.iso.ch/iso/en/prods-services/iso3166ma/
1563 02iso-3166-code-lists/index.html
1565 .. [#pwd] Path relative to the working directory of the process at
1568 .. [#override] The overridden setting will automatically be set to
1569 ``None`` for command-line options and config file settings. Client
1570 programs which specify defaults that override other settings must
1571 do the overriding explicitly, by assigning ``None`` to the other
1574 .. [#dependencies] Images are only added to the dependency list if the
1575 reStructuredText parser extracted image dimensions from the file.
1577 .. [#footnote_space] The footnote space is trimmed if the reference
1578 style is "superscript", and it is left if the reference style is
1581 The overriding only happens if the parser supports the
1582 trim_footnote_reference_space option.
1585 ------------------------------
1586 Old-Format Configuration Files
1587 ------------------------------
1589 Formerly, Docutils configuration files contained a single "[options]"
1590 section only. This was found to be inflexible, and in August 2003
1591 Docutils adopted the current component-based configuration file
1592 sections as described above. Docutils will still recognize the old
1593 "[options]" section, but complains with a deprecation warning.
1595 To convert existing config files, the easiest way is to change the
1596 section title: change "[options]" to "[general]". Most settings
1597 haven't changed. The only ones to watch out for are these:
1599 ===================== =====================================
1600 Old-Format Setting New Section & Setting
1601 ===================== =====================================
1602 pep_stylesheet [pep_html writer] stylesheet
1603 pep_stylesheet_path [pep_html writer] stylesheet_path
1604 pep_template [pep_html writer] template
1605 ===================== =====================================