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 `ISO 639`_ 2-letter language code (3-letter codes used only if no
323 2-letter code exists).
325 Default: English ("en"). Options: ``--language, -l``.
328 The text encoding for output.
330 Default: "UTF-8". Options: ``--output-encoding, -o``.
332 _`output_encoding_error_handler`
333 The error handler for unencodable characters in the output.
334 Acceptable values include:
337 Raise an exception in case of an encoding error.
339 Replace malformed data with a suitable replacement marker,
342 Ignore malformed data and continue without further notice.
344 Replace with the appropriate XML character reference, such as
347 (Python 2.3+) Replace with backslashed escape sequences, such
350 Acceptable values are the same as for the "error" parameter of
351 Python's ``encode`` string method; other values may be defined in
352 applications or in future versions of Python.
354 Default: "strict". Options: ``--output-encoding-error-handler,
355 --output-encoding, -o``.
357 _`record_dependencies`
358 Path to a file where Docutils will write a list of files that the
359 input and output depend on [#dependencies]_, e.g. due to file
360 inclusion. [#pwd]_ The format is one filename per line. This
361 option is particularly useful in conjunction with programs like
364 Set to ``-`` in order to write dependencies to stdout.
366 Default: None. Option: ``--record-dependencies``.
369 Verbosity threshold at or above which system messages are
372 Default: warning (2). Options: ``--report, -r, --verbose, -v,
376 Enable or disable the section numbering transform
377 (docutils.transforms.parts.SectNum).
379 Default: enabled (1). Options: ``--section-numbering``,
380 ``--no-section-numbering``.
383 Include a "View document source" link in the document footer. URL
384 will be relative to the destination.
386 Default: don't (None). Options: ``--source-link, -s,
390 An explicit URL for a "View document source" link, used verbatim.
392 Default: compute if source_link (None). Options: ``--source-url,
396 When processing a document tree with the Visitor pattern, raise an
397 error if a writer does not support a node type listed as optional.
398 For transitional development use.
400 Default: disabled (None). Option: ``--strict-visitor`` (hidden,
401 for development use only).
404 List of "classes" attribute values to remove from all elements in
407 Default: disabled (None). Option: ``--strip-class``.
410 Enable the removal of comment elements from the document tree.
412 Default: disabled (None). Options: ``--strip-comment``,
413 ``--leave-comments``.
415 _`strip_elements_with_classes`
416 List of "classes" attribute values; matching elements to be
417 removed from the document tree.
419 Default: disabled (None). Option: ``--strip-element-with-class``.
422 The document title as metadata, which does not become part of the
423 document body. It overrides a document-supplied title. For
424 example, in HTML output the metadata document title appears in the
425 title bar of the browser window.
427 Default: none. Option: ``--title``.
430 Enable backlinks from section titles to table of contents entries
431 ("entry"), to the top of the TOC ("top"), or disable ("none").
433 Default: "entry". Options: ``--toc-entry-backlinks,
434 --toc-top-backlinks, --no-toc-backlinks``.
437 Enable Python tracebacks when halt-level system messages and other
438 exceptions occur. Useful for debugging, and essential for issue
439 reports. Exceptions are allowed to propagate, instead of being
440 caught and reported (in a user-friendly way) by Docutils.
442 Default: disabled (None) unless Docutils is run programmatically
443 using the `Publisher Interface`_. Options: ``--traceback,
446 .. _Publisher Interface: ../api/publisher.html
449 Path to a file for the output of system messages (warnings)
452 Default: stderr (None). Options: ``--warnings``.
458 Docutils currently supports only one parser, for reStructuredText.
461 [restructuredtext parser]
462 `````````````````````````
464 _`file_insertion_enabled`
465 Enable or disable directives that insert the contents of external
466 files, such as the "include_" & "raw_". A "warning" system
467 message (including the directive text) is inserted instead. (See
468 also raw_enabled_ for another security-relevant setting.)
470 Default: enabled (1). Options: ``--file-insertion-enabled,
471 --no-file-insertion``.
473 .. _include: ../ref/rst/directives.html#include
474 .. _raw: ../ref/rst/directives.html#raw
477 Recognize and link to standalone PEP references (like "PEP 258").
479 Default: disabled (None); enabled (1) in PEP Reader. Options:
480 ``--pep-references``.
483 Base URL for PEP references.
485 Default: "http://www.python.org/peps/". Option:
488 _`pep_file_url_template`
489 Template for PEP file part of URL, interpolated with the PEP
490 number and appended to pep_base_url_.
492 Default: "pep-%04d". Option: ``--pep-file-url``.
495 Enable or disable the "raw_" directive. A "warning" system
496 message (including the directive text) is inserted instead. (See
497 also file_insertion_enabled_ for another security-relevant
500 Default: enabled (1). Options: ``--raw-enabled, --no-raw``.
503 Recognize and link to standalone RFC references (like "RFC 822").
505 Default: disabled (None); enabled (1) in PEP Reader. Options:
506 ``--rfc-references``.
509 Base URL for RFC references.
511 Default: "http://www.faqs.org/rfcs/". Option: ``--rfc-base-url``.
514 Number of spaces for hard tab expansion.
516 Default: 8. Options: ``--tab-width``.
518 _`trim_footnote_reference_space`
519 Remove spaces before footnote references.
521 Default: don't (None); may be overriden by a writer-specific
522 footnote_references__ default though. Options:
523 ``--trim-footnote-reference-space,
524 --leave-footnote-reference-space``.
526 __ `footnote_references [latex2e writer]`_
537 Enable or disable the bibliographic field list transform
538 (docutils.transforms.frontmatter.DocInfo).
540 Default: enabled (1). Options: ``--no-doc-info``.
543 Enable or disable the promotion of a lone top-level section title
544 to document title (and subsequent section title to document
545 subtitle promotion; docutils.transforms.frontmatter.DocTitle).
547 Default: enabled (1). Options: ``--no-doc-title``.
549 _`sectsubtitle_xform`
551 Enable or disable the promotion of the title of a lone subsection
552 to a subtitle (docutils.transforms.frontmatter.SectSubTitle).
554 Default: disabled (0). Options: ``--section-subtitles,
555 --no-section-subtitles``.
561 The `pep_references`_ and `rfc_references`_ settings
562 (`[restructuredtext parser]`_) are set on by default.
574 [docutils_xml writer]
575 `````````````````````
577 _`doctype_declaration`
578 Generate XML with a DOCTYPE declaration.
580 Default: do (1). Options: ``--no-doctype``.
583 Generate XML with indents and newlines.
585 Default: don't (None). Options: ``--indents``.
588 Generate XML with newlines before and after tags.
590 Default: don't (None). Options: ``--newlines``.
592 .. _xml_declaration [docutils_xml writer]:
595 Generate XML with an XML declaration. Also defined for the
598 .. Caution:: The XML declaration carries text encoding
599 information, without which standard tools may be unable to read
602 Default: do (1). Options: ``--no-xml-declaration``.
604 __ `xml_declaration [html4css1 writer]`_
610 .. _attribution [html4css1 writer]:
613 Format for block quote attributions: one of "dash" (em-dash
614 prefix), "parentheses"/"parens", or "none". Also defined for the
617 Default: "dash". Options: ``--attribution``.
619 __ `attribution [latex2e writer]`_
621 _`cloak_email_addresses`
622 Scramble email addresses to confuse harvesters. In the reference
623 URI, the "@" will be replaced by %-escapes (as of RFC 1738). In
624 the visible text (link text) of an email reference, the "@" and
625 all periods (".") will be surrounded by ``<span>`` tags.
626 Furthermore, HTML entities are used to encode these characters in
627 order to further complicate decoding the email address. For
628 example, "abc@example.org" will be output as::
630 <a class="reference" href="mailto:abc%40example.org">
631 abc<span>@</span>example<span>.</span>org</a>
633 .. Note:: While cloaking email addresses will have little to no
634 impact on the rendering and usability of email links in most
635 browsers, some browsers (e.g. the ``links`` browser) may decode
636 cloaked email addresses incorrectly.
638 Default: don't cloak (None). Option: ``--cloak-email-addresses``.
641 Remove extra vertical whitespace between items of bullet lists and
642 enumerated lists, when list items are all "simple" (i.e., items
643 each contain one paragraph and/or one "simple" sublist only). The
644 behaviour can be specified directly via "class" attributes (values
645 "compact" and "open") in the document.
647 Default: enabled (1). Options: ``--compact-lists,
648 --no-compact-lists``.
650 _`compact_field_lists`
651 Remove extra vertical whitespace between items of field lists that
652 are "simple" (i.e., all field bodies each contain at most one
653 paragraph). The behaviour can be specified directly via "class"
654 attributes (values "compact" and "open") in the document.
656 Default: enabled (1). Options: ``--compact-field-lists,
657 --no-compact-field-lists``.
660 Embed the stylesheet in the output HTML file. The stylesheet file
661 must be accessible during processing.
663 Default: enabled. Options: ``--embed-stylesheet,
667 The maximum width (in characters) for one-column field names.
668 Longer field names will span an entire row of the table used to
669 render the field list. 0 indicates "no limit". See also
672 Default: 14 characters. Option: ``--field-name-limit``.
674 .. _footnote_references [html4css1 writer]:
677 Format for footnote references, one of "superscript" or
678 "brackets". Also defined for the `LaTeX Writer`__.
680 Overrides [#override]_ trim_footnote_reference_space_, if
681 applicable. [#footnote_space]_
683 Default: "brackets". Option: ``--footnote-references``.
685 __ `footnote_references [latex2e writer]`_
687 _`initial_header_level`
688 The initial level for header elements. This does not affect the
689 document title & subtitle; see doctitle_xform_.
691 Default: 1 (for "<h1>"). Option: ``--initial-header-level``.
694 The maximum width (in characters) for options in option lists.
695 Longer options will span an entire row of the table used to render
696 the option list. 0 indicates "no limit". See also
699 Default: 14 characters. Option: ``--option-limit``.
701 .. _stylesheet [html4css1 writer]:
704 CSS stylesheet URL, used verbatim. Overrides the
705 "stylesheet_path" setting [#override]_. Pass an empty string to
706 deactivate stylesheet inclusion.
708 Default: None. Options: ``--stylesheet``.
710 (Setting also defined for the `LaTeX Writer`__.)
712 __ `stylesheet [latex2e writer]`_
714 .. _stylesheet_path [html4css1 writer]:
717 Path to CSS stylesheet [#pwd]_. Overrides the "stylesheet" URL
718 setting [#override]_. Path is adjusted relative to the output
719 HTML file. Also defined for the `LaTeX Writer`__.
721 Default: "html4css1.css" in the docutils/writers/html4css1/
722 directory (installed automatically; for the exact machine-specific
723 path, use the ``--help`` option). Options: ``--stylesheet-path``.
725 __ `stylesheet_path [latex2e writer]`_
728 Path to template file, which must be encoded in UTF-8 [#pwd]_.
730 Default: "template.txt" in the docutils/writers/html4css1/
731 directory (installed automatically; for the exact machine-specific
732 path, use the ``--help`` option). Options: ``--template``.
734 .. _xml_declaration [html4css1 writer]:
737 Generate XML with an XML declaration. Also defined for the
738 `Docutils XML Writer`__.
740 .. Caution:: The XML declaration carries text encoding
741 information, without which standard tools may be unable to read
744 Default: do (1). Options: ``--no-xml-declaration``.
746 __ `xml_declaration [docutils_xml writer]`_
752 The PEP/HTML Writer derives from the standard HTML Writer, and shares
753 all settings defined in the `[html4css1 writer]`_ section. The
754 "[html4css1 writer]" section of configuration files is processed
755 before the "[pep_html writer]" section.
758 Do not use a random banner image. Mainly used to get predictable
759 results when testing.
761 Default: random enabled (None). Options: ``--no-random``
765 Home URL prefix for PEPs.
767 Default: current directory ("."). Options: ``--pep-home``.
772 Default: parent directory (".."). Options: ``--python-home``.
774 The PEP/HTML Writer's default for the following settings differ from
775 those of the standard HTML Writer:
777 * ``stylesheet_path``: The default is
778 ``docutils/writers/pep_html/pep.css`` in the installation directory.
779 For the exact machine-specific path, use the ``--help`` option.
781 * ``template``: The default is
782 ``docutils/writers/pep_html/template.txt`` in the installation
783 directory. For the exact machine-specific path, use the ``--help``
790 The S5/HTML Writer derives from the standard HTML Writer, and shares
791 all settings defined in the `[html4css1 writer]`_ section. The
792 "[html4css1 writer]" section of configuration files is processed
793 before the "[s5_html writer]" section.
796 Auto-hide the presentation controls in slideshow mode, or or keep
797 them visible at all times.
799 Default: auto-hide (1). Options: ``--hidden-controls``,
800 ``--visible-controls``.
803 Enable or disable the current slide indicator ("1/15").
805 Default: disabled (None). Options: ``--current-slide``,
806 ``--no-current-slide``.
808 _`overwrite_theme_files`
809 Allow or prevent the overwriting of existing theme files in the
810 ``ui/<theme>`` directory. This has no effect if "theme_url_" is
813 Default: keep existing theme files (None). Options:
814 ``--keep-theme-files``, ``--overwrite-theme-files``.
817 Name of an installed S5 theme, to be copied into a ``ui/<theme>``
818 subdirectory, beside the destination file (output HTML). Note
819 that existing theme files will not be overwritten; the existing
820 theme directory you must be deleted manually. Overrides the
821 "theme_url_" setting [#override]_.
823 Default: "default". Option: ``--theme``.
826 The URL of an S5 theme directory. The destination file (output
827 HTML) will link to this theme; nothing will be copied. Overrides
828 the "theme_" setting [#override]_.
830 Default: None. Option: ``--theme-url``.
833 The initial view mode, either "slideshow" or "outline".
835 Default: "slidewhow". Option: ``--view-mode``.
837 The S5/HTML Writer's default for the following settings differ
838 from those of the standard HTML Writer:
840 * ``compact_lists``: The default here is to disable compact lists.
842 * ``template``: The default is
843 ``docutils/writers/s5_html/template.txt`` in the installation
844 directory. For the exact machine-specific path, use the ``--help``
852 To get pagenumbers in the table of contents the table of contents
853 must be generated by latex. Usually latex must be run twice to get
856 *Note:* LaTeX will number the sections, which might be a bug in
859 Default: off. Option: ``--use-latex-toc``.
861 .. XXX Missing: use_latex_docinfo
863 _`use_latex_footnotes`
864 Use LaTeX-footnotes not a figure simulation. This might give no
865 Hyperrefs on /to footnotes, but should be able to handle an
866 unlimited number of footnotes.
868 Default: off. Option: ``--use-latex-footnotes``.
871 Color of any hyperlinks embedded in text. Use "0" to disable
874 Default: "blue". Option: ``--hyperlink-color``.
877 Specify latex documentclass, *but* beaware that books have chapters
880 Default: "article". Option: ``--documentclass``.
883 Specify document options. Multiple options can be given, separated by
886 Default: "10pt,a4paper". Option: ``--documentoptions``.
888 .. _stylesheet [latex2e writer]:
891 Specify a stylesheet file. Overrides stylesheet_path
892 [#override]_. The file will be ``\input`` by latex in the
893 document header. Also defined for the `HTML Writer`__.
895 Default: no stylesheet (""). Option: ``--stylesheet``.
897 __ `stylesheet [html4css1 writer]`_
899 .. _stylesheet_path [latex2e writer]:
902 Path to stylesheet [#pwd]_. Overrides "stylesheet" setting
903 (``--stylesheet``) [#override]_.
905 Please note that you will have to run ``latex`` from the directory
906 containing the output file; otherwise the stylesheet reference
909 This setting is also defined for the `HTML Writer`__.
911 Default: None. Option: ``--stylesheet-path``.
913 __ `stylesheet_path [html4css1 writer]`_
915 .. XXX Missing: embed_stylesheet
917 .. _footnote_references [latex2e writer]:
920 Format for footnote references: one of "superscript" or
921 "brackets". Also defined for the `HTML Writer`__.
923 Overrides [#override]_ trim_footnote_reference_space_, if
924 applicable. [#footnote_space]_
926 Default: "superscript". Option: ``--footnote-references``.
928 __ `footnote_references [html4css1 writer]`_
930 .. _attribution [latex2e writer]:
933 Format for block quote attributions, the same as for the
934 html-writer: one of "dash" (em-dash prefix),
935 "parentheses"/"parens" or "none". Also defined for the `HTML
938 Default: "dash". Option: ``--attribution``.
940 __ `attribution [html4css1 writer]`_
942 _`compound_enumerators`
943 Enable or disable compound enumerators for nested enumerated lists
946 Default: disabled (None). Options: ``--compound-enumerators``,
947 ``--no-compound-enumerators``.
949 _`section_prefix_for_enumerators`
950 Enable or disable section ("." subsection ...) prefixes for
951 compound enumerators. This has no effect unless
952 `compound_enumerators`_ are enabled.
954 Default: disabled (None). Options:
955 ``--section-prefix-for-enumerators``,
956 ``--no-section-prefix-for-enumerators``.
958 _`section_enumerator_separator`
959 The separator between section number prefix and enumerator for
960 compound enumerated lists (see `compound_enumerators`_).
962 Generally it isn't recommended to use both sub-sections and nested
963 enumerated lists with compound enumerators. This setting avoids
964 ambiguity in the situation where a section "1" has a list item
965 enumerated "1.1", and subsection "1.1" has list item "1". With a
966 separator of ".", these both would translate into a final compound
967 enumerator of "1.1.1". With a separator of "-", we get the
968 unambiguous "1-1.1" and "1.1-1".
970 Default: "-". Option: ``--section-enumerator-separator``.
973 Specify the drawing of separation lines.
975 - "standard" lines around and between cells.
976 - "booktabs" a line above and below the table and one after the
980 Default: "standard". Option: ``--table-style``.
986 No settings are defined for this Writer.
992 [buildhtml application]
993 ```````````````````````
996 List of wildcard (shell globing) patterns to silently ignore. To
997 specify multiple patterns in configuration files, use
998 colon-separated patterns; on the command line, the option may be
1001 Default: ['.svn', 'CVS']. Options: ``--ignore``.
1004 List of directories not to process. To specify multiple
1005 directories in configuration files, use colon-separated paths; on
1006 the command line, the option may be used more than once.
1008 Default: none ([]). Options: ``--prune``.
1011 Recursively scan subdirectories, or ignore subdirectories.
1013 Default: recurse (1). Options: ``--recurse, --local``.
1016 Work silently (no progress messages). Independent of
1019 Default: show progress (None). Options: ``--silent``.
1022 [docfactory application]
1023 ````````````````````````
1034 These settings are only effective as command-line options; setting
1035 them in configuration files has no effect.
1038 Path to a configuration file to read (if it exists) [#pwd]_.
1039 Settings may override defaults and earlier settings. The config
1040 file is processed immediately. Multiple ``--config`` options may
1041 be specified; each will be processed in turn.
1043 Filesystem path settings contained within the config file will be
1044 interpreted relative to the config file's location (*not* relative
1045 to the current working directory).
1047 Default: None. Options: ``--config``.
1053 These settings are for internal use only; setting them in
1054 configuration files has no effect, and there are no corresponding
1055 command-line options.
1058 List of paths of applied configuration files.
1060 Default: None. No command-line options.
1063 (``buildhtml.py`` front end.) List of paths to source
1064 directories, set from positional arguments.
1066 Default: current working directory (None). No command-line
1070 Prevent standard configuration files from being read. For
1071 programmatic use only.
1073 Default: config files enabled (None). No command-line options.
1076 Path to output destination, set from positional arguments.
1078 Default: stdout (None). No command-line options.
1081 Path to input source, set from positional arguments.
1083 Default: stdin (None). No command-line options.
1086 .. _ISO 639: http://www.loc.gov/standards/iso639-2/englangn.html
1088 .. [#pwd] Path relative to the working directory of the process at
1091 .. [#override] The overridden setting will automatically be set to
1092 ``None`` for command-line options and config file settings. Client
1093 programs which specify defaults that override other settings must
1094 do the overriding explicitly, by assigning ``None`` to the other
1097 .. [#dependencies] Some notes on the dependency recorder:
1099 * Images are only added to the dependency list if the
1100 reStructuredText parser extracted image dimensions from the file.
1102 * Stylesheets are only added if they are embedded.
1104 * For practical reasons, the output of the LaTeX writer is
1105 considered merely an *intermediate* processing stage. The
1106 dependency recorder records all files the *rendered* file
1107 (e.g. in PDF or DVI format) depends on. Thus, images and
1108 stylesheets are both unconditionally recorded as dependencies
1109 when using the LaTeX writer.
1111 .. [#footnote_space] The footnote space is trimmed if the reference
1112 style is "superscript", and it is left if the reference style is
1115 The overriding only happens if the parser supports the
1116 trim_footnote_reference_space option.
1119 ------------------------------
1120 Old-Format Configuration Files
1121 ------------------------------
1123 Formerly, Docutils configuration files contained a single "[options]"
1124 section only. This was found to be inflexible, and in August 2003
1125 Docutils adopted the current component-based configuration file
1126 sections as described above. Docutils will still recognize the old
1127 "[options]" section, but complains with a deprecation warning.
1129 To convert existing config files, the easiest way is to change the
1130 section title: change "[options]" to "[general]". Most settings
1131 haven't changed. The only ones to watch out for are these:
1133 ===================== =====================================
1134 Old-Format Setting New Section & Setting
1135 ===================== =====================================
1136 pep_stylesheet [pep_html writer] stylesheet
1137 pep_stylesheet_path [pep_html writer] stylesheet_path
1138 pep_template [pep_html writer] template
1139 ===================== =====================================