Documentation update. Warn about file overwriting.
[docutils.git] / docutils / docs / user / config.txt
blob3a7c36617bc4acbfbe023afa2d23d2634aa8a7c6
1 ========================
2  Docutils Configuration
3 ========================
5 :Author: David Goodger
6 :Contact: docutils-develop@lists.sourceforge.net
7 :Revision: $Revision$
8 :Date: $Date$
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>`_.
16 .. contents::
19 -------------------
20 Configuration Files
21 -------------------
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
40    system-wide file.
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
64 priority.
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
80     comments.
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
87 underscores.
89 For on/off switch settings (_`booleans`), the following values are
90 recognized:
92 :On: "true", "yes", "on", "1"
93 :Off: "false", "no", "off", "0", "" (no value)
95 .. _list:
97 List values can be comma- or colon-delimited.
99 strip_classes_, strip_elements_with_classes_, stylesheet, and
100 stylesheet_path use the comma as delimiter,
101 whitespace around list values is stripped. ::
103     strip-classes: ham,eggs,
104     strip-elements-with-classes: sugar, salt, flour
105     stylesheet: html4css1.css,
106                 math.css,
107                 style with spaces.css
108     stylesheet-path: ../styles/my.css, ../styles/funny.css
110 expose_internals_, ignore_ and prune_ use the colon as delimiter and do not
111 strip whitespace::
113     expose_internals: b:c:d
116 Example
117 =======
119 This is the contents of the ``tools/docutils.conf`` configuration file
120 supplied with Docutils::
122     # These entries affect all processing:
123     [general]
124     source-link: yes
125     datestamp: %Y-%m-%d %H:%M UTC
126     generator: on
128     # These entries affect HTML output:
129     [html4css1 writer]
130     # Required for docutils-update, the website build system:
131     stylesheet-path: ../docutils/writers/html4css1/html4css1.css
132     embed-stylesheet: no
133     field-name-limit: 20
135 Individual configuration sections and settings are described in the
136 following section.
139 -------------------------------------
140 Configuration File Sections & Entries
141 -------------------------------------
143 Below are the Docutils runtime settings, listed by config file
144 section.  Any setting may be specified in any section, but only
145 settings from active sections will be used.  Sections correspond to
146 Docutils components (module name or alias; section names are always in
147 lowercase letters).  Each `Docutils application`_ uses a specific set
148 of components; corresponding configuration file sections are applied
149 when the application is used.  Configuration sections are applied in
150 general-to-specific order, as follows:
152 1. `[general]`_
154 2. `[parsers]`_, parser dependencies, and the section specific to the
155    Parser used ("[... parser]").  Currently, only `[restructuredtext
156    parser]`_ is applicable.
158 3. `[readers]`_, reader dependencies, and the section specific to the
159    Reader used ("[... reader]").  For example, `[pep reader]`_ depends
160    on `[standalone reader]`_.
162 4. `[writers]`_, writer family ("[... writers]"; if applicable),
163    writer dependencies, and the section specific to the writer used
164    ("[... writer]").  For example, `[pep_html writer]`_ depends
165    on `[html4css1 writer]`_.
167 5. `[applications]`_, application dependencies, and the section
168    specific to the Application (front-end tool) in use
169    ("[... application]").
171 Since any setting may be specified in any section, this ordering
172 allows component- or application-specific overrides of earlier
173 settings.  For example, there may be Reader-specific overrides of
174 general settings; Writer-specific overrides of Parser settings;
175 Application-specific overrides of Writer settings; and so on.
177 If multiple configuration files are applicable, the process is
178 completed (all sections are applied in the order given) for each one
179 before going on to the next.  For example, a "[pep_html writer]
180 stylesheet" setting in an earlier configuration file would be
181 overridden by an "[html4css1 writer] stylesheet" setting in a later
182 file.
184 Some knowledge of Python_ is assumed for some attributes.
186 .. _ConfigParser.py:
187    http://www.python.org/doc/current/lib/module-ConfigParser.html
188 .. _Python: http://www.python.org/
189 .. _RFC 822: http://www.rfc-editor.org/rfc/rfc822.txt
190 .. _Docutils application: tools.html
193 [general]
194 =========
196 Settings in the "[general]" section are always applied.
198 auto_id_prefix
199 --------------
201 Prefix prepended to all auto-generated `identifier keys` generated within
202 the document, after id_prefix_. Ensure the value conforms to the
203 restrictions on identifiers in the output format, as it is not subjected to
204 the `identifier normalization`_.
206 A trailing "%" is replaced with the tag name (new in Docutils 0.16).
208 Default: "id" (`will change to "%" in future`__).
209 Options: ``--auto-id-prefix`` (hidden, intended mainly for programmatic use).
211 .. _identifier normalization:
212    ../ref/rst/directives.html#identifier-normalization
213 __ ../../RELEASE-NOTES.html#future-changes
215 datestamp
216 ---------
218 Include a time/datestamp in the document footer.  Contains a
219 format string for Python's ``time.strftime``.  See the `time
220 module documentation`__.
222 Default: None.
223 Options: ``--date, -d, --time, -t, --no-datestamp``.
225 Configuration file entry examples::
227     # Equivalent to --date command-line option, results in
228     # ISO 8601 extended format datestamp, e.g. "2001-12-21":
229     datestamp: %Y-%m-%d
231     # Equivalent to --time command-line option, results in
232     # date/timestamp like "2001-12-21 18:43 UTC":
233     datestamp: %Y-%m-%d %H:%M UTC
235     # Disables datestamp; equivalent to --no-datestamp:
236     datestamp:
238 __ http://www.python.org/doc/current/lib/module-time.html
240 debug
241 -----
243 Report debug-level system messages.
245 Default: don't (None).  Options: ``--debug, --no-debug``.
247 dump_internals
248 --------------
250 At the end of processing, write all internal attributes of the
251 document (``document.__dict__``) to stderr.
253 Default: don't (None).
254 Options: ``--dump-internals`` (hidden, for development use only).
256 dump_pseudo_xml
257 ---------------
259 At the end of processing, write the pseudo-XML representation of
260 the document to stderr.
262 Default: don't (None).
263 Options: ``--dump-pseudo-xml`` (hidden, for development use only).
265 dump_settings
266 -------------
268 At the end of processing, write all Docutils settings to stderr.
270 Default: don't (None).
271 Options: ``--dump-settings`` (hidden, for development use only).
273 dump_transforms
274 ---------------
276 At the end of processing, write a list of all transforms applied
277 to the document to stderr.
279 Default: don't (None).
280 Options: ``--dump-transforms`` (hidden, for development use only).
282 error_encoding
283 --------------
285 The text encoding for error output.
287 Default: "ascii".  Options: ``--error-encoding, -e``.
289 error_encoding_error_handler
290 ----------------------------
292 The error handler for unencodable characters in error output.  See
293 output_encoding_error_handler_ for acceptable values.
295 Default: "backslashreplace"
296 Options: ``--error-encoding-error-handler, --error-encoding, -e``.
298 exit_status_level
299 -----------------
301 A system message level threshold; non-halting system messages at
302 or above this level will produce a non-zero exit status at normal
303 exit.  Exit status is the maximum system message level plus 10 (11
304 for INFO, etc.).
306 Default: disabled (5).  Options: ``--exit-status``.
308 expose_internals
309 ----------------
311 List_ of internal attribues to expose as external attributes (with
312 "internal:" namespace prefix).  To specify multiple attributes in
313 configuration files, use colons to separate names; on the command
314 line, the option may be used more than once.
316 Default: don't (None).
317 Options: ``--expose-internal-attribute`` (hidden, for development use only).
319 footnote_backlinks
320 ------------------
322 Enable or disable backlinks from footnotes_ and citations_ to their
323 references.
325 Default: enabled (True).
326 Options: ``--footnote-backlinks, --no-footnote-backlinks``.
328 generator
329 ---------
331 Include a "Generated by Docutils" credit and link in the document footer.
333 Default: off (None).  Options: ``--generator, -g, --no-generator``.
335 halt_level
336 ----------
338 The threshold at or above which system messages are converted to
339 exceptions, halting execution immediately.  If `traceback`_ is set, the
340 exception will propagate; otherwise, Docutils will exit.
342 Default: severe (4).  Options: ``--halt, --strict``.
344 id_prefix
345 ---------
347 Prefix prepended to all identifier keys generated within the document.
348 Ensure the value conforms to the restrictions on identifiers in the output
349 format, as it is not subjected to the `identifier normalization`_.
350 See also auto_id_prefix_.
352 Default: "" (empty).
353 Options: ``--id-prefix`` (hidden, intended mainly for programmatic use).
355 input_encoding
356 --------------
358 The text encoding for input.
360 Default: auto-detect (None).  Options: ``--input-encoding, -i``.
362 input_encoding_error_handler
363 ----------------------------
365 The error handler for undecodable characters in the input. Acceptable
366 values include:
368 strict
369     Raise an exception in case of an encoding error.
370 replace
371     Replace malformed data with the official Unicode replacement
372     character, U+FFFD.
373 ignore
374     Ignore malformed data and continue without further notice.
376 Acceptable values are the same as for the "error" parameter of
377 Python's ``unicode`` function; other values may be defined in
378 applications or in future versions of Python.
380 Default: "strict".
381 Options: ``--input-encoding-error-handler, --input-encoding, -i``.
383 language_code
384 -------------
386 Case-insensitive `language tag`_ as defined in `BCP 47`_.
388 Sets the document language, also used for localized directive and
389 role names as well as Docutils-generated text.
391 A typical language identifier consists of a 2-letter language code
392 from `ISO 639`_ (3-letter codes can be used if no 2-letter code
393 exists). The language identifier can have an optional subtag,
394 typically for variations based on country (from `ISO 3166`_
395 2-letter country codes).  Avoid subtags except where they add
396 useful distinguishing information. Examples of language tags
397 include "fr", "en-GB", "pt-br" (the same as "pt-BR"), and
398 "de-1901" (German with pre-1996 spelling).
400 The language of document parts can be specified with a
401 "language-<language tag>" `class attribute`_, e.g.
402 ``.. class:: language-el-polyton`` for a quote in polytonic Greek.
404 Default: English ("en").  Options: ``--language, -l``.
406 .. _class attribute: ../ref/doctree.html#classes
408 output_encoding
409 ---------------
411 The text encoding for output.
413 Default: "UTF-8".  Options: ``--output-encoding, -o``.
415 output_encoding_error_handler
416 -----------------------------
418 The error handler for unencodable characters in the output. Acceptable
419 values include:
421 strict
422     Raise an exception in case of an encoding error.
423 replace
424     Replace malformed data with a suitable replacement marker,
425     such as "?".
426 ignore
427     Ignore malformed data and continue without further notice.
428 xmlcharrefreplace
429     Replace with the appropriate XML character reference, such as
430     "``&#8224;``".
431 backslashreplace
432     Replace with backslashed escape sequences, such as "``\u2020``".
434 Acceptable values are the same as for the "error" parameter of
435 Python's ``encode`` string method; other values may be defined in
436 applications or in future versions of Python.
438 Default: "strict".
439 Options: ``--output-encoding-error-handler, --output-encoding, -o``.
441 record_dependencies
442 -------------------
444 Path to a file where Docutils will write a list of files that were
445 required to generate the output, e.g. included files or embedded
446 stylesheets [#dependencies]_. [#pwd]_ The format is one path per
447 line with forward slashes as separator, the encoding is ``utf8``.
449 Set to ``-`` in order to write dependencies to stdout.
451 This option is particularly useful in conjunction with programs like
452 ``make`` using ``Makefile`` rules like::
454   ham.html: ham.txt $(shell cat hamdeps.txt)
455     rst2html.py --record-dependencies=hamdeps.txt ham.txt ham.html
457 If the filesystem encoding differs from utf8, replace the ``cat``
458 command with a call to a converter, e.g.::
460   $(shell iconv -f utf8 -t latin1 hamdeps.txt)
462 Default: None.  Option: ``--record-dependencies``.
464 report_level
465 ------------
467 Report system messages at or higher than <level>:
469 1  info
470 2  warning
471 3  error
472 4  severe
473 5  none
475 Default: warning (2).
476 Options: ``--report, -r, --verbose, -v, --quiet, -q``.
478 sectnum_xform
479 -------------
481 Enable or disable automatic section numbering by Docutils
482 (docutils.transforms.parts.SectNum) associated with the `sectnum
483 directive`_.
485 If disabled, section numbers might be added to the output by the
486 renderer (e.g. by LaTeX or via a CSS style definition).
488 Default: enabled (True).
489 Options: ``--section-numbering``, ``--no-section-numbering``.
491 .. _sectnum directive: ../ref/rst/directives.html#sectnum
493 source_link
494 -----------
496 Include a "View document source" link in the document footer.  URL will
497 be relative to the destination.
499 Default: don't (None).
500 Options: ``--source-link, -s, --no-source-link``.
502 source_url
503 ----------
505 An explicit URL for a "View document source" link, used verbatim.
507 Default: compute if source_link (None).
508 Options: ``--source-url, --no-source-link``.
510 strict_visitor
511 --------------
513 When processing a document tree with the Visitor pattern, raise an
514 error if a writer does not support a node type listed as optional. For
515 transitional development use.
517 Default: disabled (None).
518 Option: ``--strict-visitor`` (hidden, for development use only).
520 strip_classes
521 -------------
523 Comma-separated list_ of "classes" attribute values to remove from all
524 elements in the document tree. The command line option may be used more
525 than once.
527 .. WARNING:: Potentially dangerous; use with caution.
529 Default: disabled (None).  Option: ``--strip-class``.
531 strip_comments
532 --------------
534 Enable the removal of comment elements from the document tree.
536 Default: disabled (None).
537 Options: ``--strip-comments``, ``--leave-comments``.
539 strip_elements_with_classes
540 ---------------------------
542 Comma-separated list_ of "classes" attribute values;
543 matching elements are removed from the document tree.
544 The command line option may be used more than once.
546 .. WARNING:: Potentially dangerous; use with caution.
548 Default: disabled (None).  Option: ``--strip-element-with-class``.
550 title
551 -----
553 The `document title`_ as metadata, which does not become part of the
554 document body.  It overrides a document-supplied title.  For
555 example, in HTML output the metadata document title appears in the
556 title bar of the browser window.
558 Default: none.  Option: ``--title``.
560 .. _document title: ../ref/rst/restructuredtext.html#document-title
562 toc_backlinks
563 -------------
565 Enable backlinks from section titles to table of contents entries
566 ("entry"), to the top of the TOC ("top"), or disable ("none").
568 Default: "entry".
569 Options: ``--toc-entry-backlinks, --toc-top-backlinks, --no-toc-backlinks``.
571 traceback
572 ---------
574 Enable Python tracebacks when halt-level system messages and other
575 exceptions occur.  Useful for debugging, and essential for issue
576 reports.  Exceptions are allowed to propagate, instead of being
577 caught and reported (in a user-friendly way) by Docutils.
579 Default: disabled (None) unless Docutils is run programmatically
580 using the `Publisher Interface`_.
581 Options: ``--traceback, --no-traceback``.
583 .. _Publisher Interface: ../api/publisher.html
585 warning_stream
586 --------------
588 Path to a file for the output of system messages (warnings). [#pwd]_
590 Default: stderr (None).  Options: ``--warnings``.
593 [parsers]
594 =========
596 Docutils currently supports only one parser, for reStructuredText.
599 [restructuredtext parser]
600 -------------------------
602 character_level_inline_markup
603 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
605 Experimental setting to relax the `inline markup recognition rules`_
606 requiring whitespace or punctuation around inline markup.
608 Allows character level inline markup without escaped whithespace and is
609 especially suited for langauges that do not use whitespace to separate words
610 (e.g. Japanese, Chinese).
612 .. WARNING:: Potentially dangerous; use with caution.
614    When changing this setting to "True", inline markup charactes in
615    URLs, names and formulas must be escaped to prevent recognition and
616    possible errors. Examples::
618      http://rST_for_all.html (hyperlinks to rST_ and for_)
619      x_2, inline_markup      (hyperlinks to x_ and inline_)
620      2*x                     (starts emphasised text)
621      a|b                     (starts a substitution reference)
623 Default: disabled (False).
624 Options: ``--character-level-inline-markup, --word-level-inline-markup``.
626 New in Docutils 0.13.
628 file_insertion_enabled
629 ~~~~~~~~~~~~~~~~~~~~~~
631 Enable or disable directives that insert the contents of external
632 files, such as the "include_" & "raw_".  A "warning" system
633 message (including the directive text) is inserted instead.  (See
634 also raw_enabled_ for another security-relevant setting.)
636 Default: enabled (True).
637 Options: ``--file-insertion-enabled, --no-file-insertion``.
639 .. _include: ../ref/rst/directives.html#include
640 .. _raw: ../ref/rst/directives.html#raw
642 line_length_limit
643 ~~~~~~~~~~~~~~~~~
645 Maximal number of characters in an input line or `substitution`_
646 definition. To prevent extraordinary high processing times or memory
647 usage for certain input constructs, a "warning" system message is
648 inserted instead.
649           
650 Default: 10 000.
651 Option: ``--line-length-limit``
653 New in Docutils 0.17.
655 .. _substitution: ../ref/rst/directives.html#substitution
657 pep_references
658 ~~~~~~~~~~~~~~
660 Recognize and link to standalone PEP references (like "PEP 258").
662 Default: disabled (None); enabled (True) in PEP Reader.
663 Options: ``--pep-references``.
665 pep_base_url
666 ~~~~~~~~~~~~
667 Base URL for PEP references.
669 Default: "http://www.python.org/peps/".
670 Option: ``--pep-base-url``.
672 pep_file_url_template
673 ~~~~~~~~~~~~~~~~~~~~~
675 Template for PEP file part of URL, interpolated with the PEP
676 number and appended to pep_base_url_.
678 Default: "pep-%04d".  Option: ``--pep-file-url``.
680 raw_enabled
681 ~~~~~~~~~~~
683 Enable or disable the "raw_" directive.  A "warning" system message
684 (including the directive text) is inserted instead.  See also
685 file_insertion_enabled_ for another security-relevant setting.
687 Default: enabled (True).  Options: ``--raw-enabled, --no-raw``.
689 rfc_references
690 ~~~~~~~~~~~~~~
692 Recognize and link to standalone RFC references (like "RFC 822").
694 Default: disabled (None); enabled (True) in PEP Reader.
695 Options: ``--rfc-references``.
697 rfc_base_url
698 ~~~~~~~~~~~~
700 Base URL for RFC references.
702 Default: "http://www.faqs.org/rfcs/".  Option: ``--rfc-base-url``.
704 smart_quotes
705 ~~~~~~~~~~~~
707 Activate the experimental SmartQuotes_ transform to
708 change straight quotation marks to typographic form. `Quote characters`_
709 are selected according to the language of the current block element (see
710 language_code_, smartquotes_locales_, and the `pre-defined quote sets`__).
712 Also changes consecutive runs of hyphen-minus and full stops (``---``,
713 ``--``, ``...``) to em-dash, en-dash, and ellipsis Unicode characters
714 respectively.
716 Supported values:
718 booleans_ (yes/no)
719   Use smart quotes?
721 alt (or "alternative")
722   Use alternative quote set (if defined for the language).
724 Default: "no". Option: ``--smart-quotes``.
726 New in Docutils 0.10.
728 .. _SmartQuotes: smartquotes.html
729 __ smartquotes.html#localization
730 .. _quote characters:
731    http://en.wikipedia.org/wiki/Non-English_usage_of_quotation_marks
734 smartquotes_locales
735 ~~~~~~~~~~~~~~~~~~~
737 Typographical quotes used by the SmartQuotes_ transform.
739 A comma-separated list_ with language tag and a set of four quotes (primary
740 open/close, secondary open/close)smartquotes_locales. (If more than one
741 character shall be used for a quote (e.g. padding in French quotes), a
742 colon-separated list may be used.)
744 Example:
745   Ensure a correct leading apostrophe in ``'s Gravenhage`` in Dutch (at the
746   cost of incorrect opening single quotes) and set French quotes to double
747   and single guillemets with inner padding::
749           smartquote-locales: nl: „”’’,
750                               fr: « : »:‹ : ›
752 Default: None. Option: ``--smartquotes-locales``.
754 New in Docutils 0.14.
756 syntax_highlight
757 ~~~~~~~~~~~~~~~~
759 Token type names used by Pygments_ when parsing contents of the code_
760 directive and role.
762 Supported values:
764 long
765   Use hierarchy of long token type names.
766 short
767   Use short token type names. (For use with
768   `Pygments-generated stylesheets`_.)
769 none
770   No code parsing. Use this to avoid the "Pygments not
771   found" warning when Pygments is not installed.
773 Default: "long".  Option: ``--syntax-highlight``.
775 New in Docutils 0.9.
777 .. _Pygments: http://pygments.org/
778 .. _code: ../ref/rst/directives.html#code
779 .. _Pygments-generated stylesheets:
780    http://pygments.org/docs/cmdline/#generating-styles
782 tab_width
783 ~~~~~~~~~
785 Number of spaces for hard tab expansion.
787 Default: 8.  Options: ``--tab-width``.
789 trim_footnote_reference_space
790 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
792 Remove spaces before `footnote references`_. [#]_
794 Default: don't (None) rsp. depending on the writer-specific
795 `footnote_references setting`_. [#footnote_space]_
797 Options: ``--trim-footnote-reference-space, --leave-footnote-reference-space``.
799 .. [#] The footnote space is trimmed if the reference style is
800    "superscript", and it is left if the reference style is "brackets".
804 [readers]
805 =========
808 [standalone reader]
809 -------------------
811 docinfo_xform
812 ~~~~~~~~~~~~~
814 Enable or disable the `bibliographic field list`_ transform
815 (docutils.transforms.frontmatter.DocInfo).
817 Default: enabled (True).  Options: ``--no-doc-info``.
819 doctitle_xform
820 ~~~~~~~~~~~~~~
822 Enable or disable the promotion of a lone top-level section title
823 to `document title`_ (and subsequent section title to document
824 subtitle promotion; docutils.transforms.frontmatter.DocTitle).
826 Default: enabled (True).  Options: ``--no-doc-title``.
828 sectsubtitle_xform
829 ~~~~~~~~~~~~~~~~~~
831 Enable or disable the promotion of the title of a lone subsection
832 to a subtitle (docutils.transforms.frontmatter.SectSubTitle).
834 Default: disabled (False).  Options: ``--section-subtitles,
835 --no-section-subtitles``.
838 [pep reader]
839 ------------
841 The `pep_references`_ and `rfc_references`_ settings
842 (`[restructuredtext parser]`_) are set on by default.
845 .. [python reader]
846    ---------------
848    Not implemented.
851 [writers]
852 =========
854 [docutils_xml writer]
855 ---------------------
857 .. Caution::
859    * In Python versions older than 2.7.3 and 3.2.3, the newlines_ and
860      indents_ options may adversely affect whitespace; use them only for
861      reading convenience (see http://bugs.python.org/issue4147).
863    * The XML declaration carries text encoding information. If the encoding
864      is not UTF-8 or ASCII and the XML declaration is missing, standard
865      tools may be unable to read the generated XML.
867 doctype_declaration
868 ~~~~~~~~~~~~~~~~~~~
870 Generate XML with a DOCTYPE declaration.
872 Default: do (True).  Options: ``--no-doctype``.
874 indents
875 ~~~~~~~
877 Generate XML with indents and newlines.
879 Default: don't (None).  Options: ``--indents``.
881 newlines
882 ~~~~~~~~
884 Generate XML with newlines before and after tags.
886 Default: don't (None).  Options: ``--newlines``.
889 .. _xml_declaration [docutils_xml writer]:
891 xml_declaration
892 ~~~~~~~~~~~~~~~
894 Generate XML with an XML declaration.
895 See also `xml_declaration [html writers]`_.
897 Default: do (True).  Options: ``--no-xml-declaration``.
900 [html writers]
901 --------------
903 .. _attribution [html writers]:
905 attribution
906 ~~~~~~~~~~~
908 Format for `block quote`_ attributions: one of "dash" (em-dash
909 prefix), "parentheses"/"parens", or "none".
910 See also `attribution [latex writers]`_.
912 Default: "dash".  Options: ``--attribution``.
915 cloak_email_addresses
916 ~~~~~~~~~~~~~~~~~~~~~
918 Scramble email addresses to confuse harvesters.  In the reference
919 URI, the "@" will be replaced by %-escapes (as of RFC 1738).  In
920 the visible text (link text) of an email reference, the "@" and
921 all periods (".") will be surrounded by ``<span>`` tags.
922 Furthermore, HTML entities are used to encode these characters in
923 order to further complicate decoding the email address.  For
924 example, "abc@example.org" will be output as::
926     <a class="reference" href="mailto:abc&#37;&#52;&#48;example&#46;org">
927     abc<span>&#64;</span>example<span>&#46;</span>org</a>
929 .. Note:: While cloaking email addresses will have little to no
930    impact on the rendering and usability of email links in most
931    browsers, some browsers (e.g. the ``links`` browser) may decode
932    cloaked email addresses incorrectly.
934 Default: don't cloak (None).  Option: ``--cloak-email-addresses``.
936 compact_lists
937 ~~~~~~~~~~~~~
939 Remove extra vertical whitespace between items of bullet lists and
940 enumerated lists, when list items are all "simple" (i.e., items
941 each contain one paragraph and/or one "simple" sublist only).  The
942 behaviour can be specified directly via "class" attributes (values
943 "compact" and "open") in the document.
945 Default: enabled (True).
946 Options: ``--compact-lists, --no-compact-lists``.
948 compact_field_lists
949 ~~~~~~~~~~~~~~~~~~~
951 Remove extra vertical whitespace between items of `field lists`_ that
952 are "simple" (i.e., all field bodies each contain at most one
953 paragraph).  The behaviour can be specified directly via "class"
954 attributes (values "compact" and "open") in the document.
956 Default: enabled (True).
957 Options: ``--compact-field-lists, --no-compact-field-lists``.
960 .. _embed_stylesheet [html writers]:
962 embed_stylesheet
963 ~~~~~~~~~~~~~~~~
965 Embed the stylesheet in the output HTML file.  The stylesheet file
966 must specified by the stylesheet_path_ setting and must be
967 accessible during processing.
968 See also `embed_stylesheet [latex writers]`_.
970 Default: enabled.  Options: ``--embed-stylesheet,
971 --link-stylesheet``.
974 .. _footnote_references setting:
975 .. _footnote_references [html writers]:
977 footnote_references
978 ~~~~~~~~~~~~~~~~~~~
980 Format for `footnote references`_, one of "superscript" or "brackets".
981 See also `footnote_references [latex writers]`_.
983 Overrides [#override]_ trim_footnote_reference_space_, if
984 applicable. [#footnote_space]_
986 Default: "brackets".  Option: ``--footnote-references``.
988 initial_header_level
989 ~~~~~~~~~~~~~~~~~~~~
991 The initial level for header elements.  This does not affect the
992 document title & subtitle; see doctitle_xform_.
994 Default: writer dependent (see `[html4css1 writer]`_, `[html5 writer]`_,
995 `[pep_html writer]`_).
996 Option: ``--initial-header-level``.
999 math_output
1000 ~~~~~~~~~~~
1002 The format of mathematical content (`math directive`_ and role) in
1003 the output document. Supported values are (case insensitive):
1005 :HTML:
1006   Format math in standard HTML enhanced by CSS rules.
1007   Requires the ``math.css`` stylesheet (in the system
1008   `stylesheet directory <stylesheet_dirs [html writers]_>`__)
1010   A `stylesheet_path <stylesheet_path [html writers]_>`__
1011   can be appended after whitespace, the specified
1012   stylesheet(s) will only be referenced or embedded, if required
1013   (i.e. if there is mathematical content in the document).
1015 :MathJax:
1016   Format math for display with MathJax_, a JavaScript-based math rendering
1017   engine.
1019   Pro:
1020     Works across multiple browsers and platforms.
1022     Large set of `supported LaTeX math commands and constructs`__
1024     __ http://docs.mathjax.org/en/latest/tex.html#supported-latex-commands
1026   Con:
1027     Rendering requires JavaScript and an Internet connection or local
1028     MathJax installation.
1030   A URL pointing to a MathJax library should be appended after whitespace.
1031   A warning is given if this is missing.
1033   * It is recommended to install__ the MathJax library on the same
1034     server as the rest of the deployed site files.
1036     __ https://www.mathjax.org/#installnow
1038     Example: Install the library at the top level of the web
1039     server’s hierarchy in the directory ``MathJax`` and set::
1041       math-output: mathjax /MathJax/MathJax.js
1043   * The easiest way to use MathJax is to link directly to a public
1044     installation. In that case, there is no need to install MathJax locally.
1046     Downside: Downloads JavaScript code from a third-party site --- opens
1047     the door to cross-site scripting attacs!
1049     Example: MathJax `getting started`__ documentation uses::
1051       math-output: mathjax
1052          https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
1054     See https://www.jsdelivr.com/ for details and terms of use.
1055     
1056     __ https://www.mathjax.org/#gettingstarted
1058   * Use a local MathJax installation on the *client* machine, e.g.::
1060       math-output: MathJax file:/usr/share/javascript/mathjax/MathJax.js
1062     This is the fallback if no URL is specified.
1064 :MathML:
1065   Embed math content as presentational MathML_.
1067   Pro:
1068     The W3C recommendation for math on the web.
1070     Self-contained documents (no JavaScript, no external downloads).
1072   Con:
1073     Docutil's latex2mathml converter supports only a small
1074     subset of LaTeX syntax.
1076     With the "html4css1" writer, the resulting HTML document does
1077     not validate, as there is no DTD for `MathML + XHTML Transitional`.
1078     However, MathML-enabled browsers will render it fine.
1080   An external converter can be appended after whitespace, e.g.,
1081   ``--math-output="MathML latexml"``:
1083   blahtexml_
1084     Fast conversion, support for many symbols and environments, but no
1085     "align" (or other equation-aligning) environment. (C++)
1087   LaTeXML_
1088     Comprehensive macro support but very slow. (Perl)
1090   TtM_
1091     No "matrix", "align" and  "cases" environments. Support may be removed.
1093 :LaTeX:
1094   Include literal LaTeX code.
1096   The failsave fallback.
1098 Default: HTML math.css.  Option: ``--math-output``.
1100 New in Docutils 0.8.
1102 .. _math directive: ../ref/rst/directives.html#math
1103 .. _MathJax: http://www.mathjax.org/
1104 .. _MathPlayer: http://www.dessci.com/en/products/mathplayer/
1105 .. _MathML: http://www.w3.org/TR/MathML/
1106 .. _blahtexml: http://gva.noekeon.org/blahtexml/
1107 .. _LaTeXML: http://dlmf.nist.gov/LaTeXML/
1108 .. _TtM: http://hutchinson.belmont.ma.us/tth/mml/
1111 .. _stylesheet [html writers]:
1113 stylesheet
1114 ~~~~~~~~~~
1116 A comma-separated list of CSS stylesheet URLs, used verbatim.
1117 See also `stylesheet [latex writers]`_.
1119 Overrides also stylesheet_path_. [#override]_
1121 Default: None.  Options: ``--stylesheet``.
1124 .. _stylesheet_dirs [html writers]:
1126 stylesheet_dirs
1127 ~~~~~~~~~~~~~~~
1129 A comma-separated list of directories where stylesheets can be found.
1130 Used by the stylesheet_path_ setting when expanding relative path arguments.
1132 Note: This setting defines a "search path" (similar to the PATH variable for
1133 executables). However, the term "path" is already used in the
1134 stylesheet_path_ setting with the meaning of a file location.
1137 Default: the working directory of the process at launch and the directory
1138 with default stylesheet files (writer and installation specific).
1139 Use the ``--help`` option to get the exact value.
1140 Option: ``--stylesheet-directories``.
1143 .. _stylesheet_path:
1144 .. _stylesheet_path [html writers]:
1146 stylesheet_path
1147 ~~~~~~~~~~~~~~~
1149 A comma-separated list of paths to CSS stylesheets. Relative paths are
1150 expanded if a matching file is found in the stylesheet_dirs__.
1151 If embed_stylesheet__ is False, paths are rewritten relative to the
1152 output HTML file.
1153 See also `stylesheet_path [latex writers]`_.
1155 Also overrides "stylesheet". [#override]_
1156 Pass an empty string (to either "stylesheet" or "stylesheet_path") to
1157 deactivate stylesheet inclusion.
1159 Default: writer dependent (see `[html4css1 writer]`_, `[html5 writer]`_,
1160 `[pep_html writer]`_).
1161 Options: ``--stylesheet-path``.
1163 __ `embed_stylesheet [html writers]`_
1164 __ `stylesheet_dirs [html writers]`_
1167 .. _table_style [html writers]:
1169 table_style
1170 ~~~~~~~~~~~
1172 Class value(s) added to all tables_.
1173 See also `table_style [latex writers]`_.
1175 The default CSS sylesheet defines:
1177   borderless
1178     No borders around the table.
1179   
1180   booktabs
1181     Lines above and below the table and a thin line after the head.
1182   
1183   align-left, align-center, align-right
1184     Align the tables
1185     
1186   colwidths-auto
1187     Delegate the determination of table column widths to the backend
1188     (leave out the ``<colgroup>`` column specification).
1189     See also the "widths" option of the `table directive`_.
1190   
1191   captionbelow
1192     Place the table caption below the table
1193     (only with the `HTML5 writer`_, new in 0.17).
1195 Default: "".  Option: ``--table-style``.
1197 .. _table directive: ../ref/rst/directives.html#table
1200 .. _template [html writers]:
1202 template
1203 ~~~~~~~~
1205 Path to template file, which must be encoded in UTF-8. [#pwd]_
1206 See also `template [latex writers]`_.
1208 Default: "template.txt" in the docutils/writers/html4css1/
1209 directory (installed automatically; for the exact machine-specific
1210 path, use the ``--help`` option).  Options: ``--template``.
1213 .. _xml_declaration [html writers]:
1215 xml_declaration
1216 ~~~~~~~~~~~~~~~
1218 Generate XML with an XML declaration.
1219 See also `xml_declaration [docutils_xml writer]`_.
1221 .. Caution:: The XML declaration carries text encoding information.  If the
1222    encoding is not UTF-8 or ASCII and the XML declaration is missing,
1223    standard tools may be unable to read the generated XHTML.
1225 Default: do (True).  Options: ``--no-xml-declaration``.
1229 [html4css1 writer]
1230 ~~~~~~~~~~~~~~~~~~
1232 The `HTML4/CSS1 Writer`_ generates output that conforms to the
1233 `XHTML 1 Transitional`_ specification.
1234 It shares all settings defined in the `[html writers]`_
1235 `configuration section`_.
1238 Writer specific defaults:
1240 `initial_header_level`_
1241   1 (for "<h1>")
1243 `stylesheet_path <stylesheet_path [html writers]_>`__:
1244   "html4css1.css"
1246 .. _HTML4/CSS1 Writer: html.html#html4css1
1247 .. _XHTML 1 Transitional: http://www.w3.org/TR/xhtml1/
1250 field_name_limit
1251 """"""""""""""""
1253 The maximum width (in characters) for one-column `field names`_. Longer
1254 field names will span an entire row of the table used to render the field
1255 list.  0 indicates "no limit".  See also option_limit_.
1257 Default: 14 (i.e. 14 characters).  Option: ``--field-name-limit``.
1260 option_limit
1261 """"""""""""
1263 The maximum width (in characters) for options in `option lists`_.
1264 Longer options will span an entire row of the table used to render
1265 the option list.  0 indicates "no limit".
1266 See also field_name_limit_.
1268 Default: 14 (i.e. 14 characters).  Option: ``--option-limit``.
1271 [html5 writer]
1272 ~~~~~~~~~~~~~~
1274 The `HTML5 Writer`_ generates valid XML that is compatible with `HTML5`_.
1275 It shares all settings defined in the `[html writers]`_
1276 `configuration section`_.
1278 Writer specific defaults:
1280 `initial_header_level`_
1281   2 (for "<h2>", cf. the `HTML5.3 Working Draft`__)
1283 `stylesheet_path <stylesheet_path [html writers]_>`__:
1284   "minimal.css,plain.css"
1286 New in Docutils 0.13.
1288 __  https://www.w3.org/TR/html53/sections.html#the-h1-h2-h3-h4-h5-and-h6-elements
1289 .. _HTML5 Writer: html.html#html5-polyglot
1290 .. _HTML5: http://www.w3.org/TR/html5/
1293 embed_images
1294 """"""""""""
1296 Embed images in the output HTML file. If the image can be read from
1297 the local file system and its MIME type can be determined, it is
1298 base64_ encoded and included as a `data URI`_.
1300 Default: disabled (False).
1301 Options: ``--embed-images``, ``--link-images``
1303 New in Docutils 0.17.
1305 .. _base64: https://en.wikipedia.org/wiki/Base64
1306 .. _data URI: https://en.wikipedia.org/wiki/Data_URI_scheme
1309 [pep_html writer]
1310 ~~~~~~~~~~~~~~~~~
1312 The PEP/HTML Writer derives from the HTML4/CSS1 Writer, and shares
1313 all settings defined in the `[html writers]`_ and `[html4css1 writer]`_
1314 `configuration sections`_.
1316 Writer specific defaults:
1318 `initial_header_level`_
1319   1 (for "<h1>")
1321 `stylesheet_path <stylesheet_path [html writers]_>`__:
1322   "pep.css"
1324 `template <template [html writers]_>`__:
1325   ``docutils/writers/pep_html/template.txt`` in the installation
1326   directory.  For the exact machine-specific path, use the ``--help``
1327   option.
1329 no_random
1330 """""""""
1331 Do not use a random banner image.  Mainly used to get predictable
1332 results when testing.
1334 Default: random enabled (None).  Options: ``--no-random`` (hidden).
1336 pep_home
1337 """"""""
1339 Home URL prefix for PEPs.
1341 Default: current directory (".").  Options: ``--pep-home``.
1343 python_home
1344 """""""""""
1345 Python's home URL.
1347 Default: parent directory ("..").  Options: ``--python-home``.
1350 [s5_html writer]
1351 ~~~~~~~~~~~~~~~~
1353 The S5/HTML Writer derives from the HTML4/CSS1 Writer, and shares
1354 all settings defined in the `[html writers]`_ and `[html4css1 writer]`_
1355 `configuration sections`_.
1357 Writer specific defaults:
1359 compact_lists_:
1360   disable compact lists.
1362 template__:
1363   ``docutils/writers/s5_html/template.txt`` in the installation
1364   directory.  For the exact machine-specific path, use the ``--help``
1365   option.
1367 __ `template [html writers]`_
1370 hidden_controls
1371 """""""""""""""
1373 Auto-hide the presentation controls in slideshow mode, or or keep
1374 them visible at all times.
1376 Default: auto-hide (True).  Options: ``--hidden-controls``,
1377 ``--visible-controls``.
1379 current_slide
1380 """""""""""""
1382 Enable or disable the current slide indicator ("1/15").
1384 Default: disabled (None).  Options: ``--current-slide``,
1385 ``--no-current-slide``.
1387 overwrite_theme_files
1388 """""""""""""""""""""
1390 Allow or prevent the overwriting of existing theme files in the
1391 ``ui/<theme>`` directory.  This has no effect if "theme_url_" is
1392 used.
1394 Default: keep existing theme files (None).  Options:
1395 ``--keep-theme-files``, ``--overwrite-theme-files``.
1397 theme
1398 """""
1400 Name of an installed S5 theme, to be copied into a ``ui/<theme>``
1401 subdirectory, beside the destination file (output HTML).  Note
1402 that existing theme files will not be overwritten; the existing
1403 theme directory must be deleted manually.
1404 Also overrides the "theme_url_" setting. [#override]_
1406 Default: "default".  Option: ``--theme``.
1408 theme_url
1409 """""""""
1411 The URL of an S5 theme directory.  The destination file (output
1412 HTML) will link to this theme; nothing will be copied.  Also overrides
1413 the "theme_" setting. [#override]_
1415 Default: None.  Option: ``--theme-url``.
1417 view_mode
1418 """""""""
1420 The initial view mode, either "slideshow" or "outline".
1422 Default: "slidewhow".  Option: ``--view-mode``.
1424 .. ------------------------------------------------------------
1426 [latex writers]
1427 ----------------
1429 Common settings for the `LaTeX writers`_
1430 `[latex2e writer]`_ and `[xetex writer]`_.
1432 .. _LaTeX writers: latex.html
1435 .. _attribution [latex writers]:
1437 attribution
1438 ~~~~~~~~~~~
1440 See `attribution [html writers]`_.
1442 compound_enumerators
1443 ~~~~~~~~~~~~~~~~~~~~
1445 Enable or disable compound enumerators for nested `enumerated lists`_
1446 (e.g. "1.2.a.ii").
1448 Default: disabled (None).
1449 Options: ``--compound-enumerators``, ``--no-compound-enumerators``.
1451 documentclass
1452 ~~~~~~~~~~~~~
1454 Specify LaTeX documentclass.
1456 Default: "article".  Option: ``--documentclass``.
1458 documentoptions
1459 ~~~~~~~~~~~~~~~
1461 Specify document options.  Multiple options can be given, separated by
1462 commas.
1464 Default: "a4paper".  Option: ``--documentoptions``.
1467 docutils_footnotes
1468 ~~~~~~~~~~~~~~~~~~
1469 Use the Docutils-specific macros ``\DUfootnote`` and
1470 ``\DUfootnotetext`` for footnotes_.
1472 TODO: The alternative, "use_latex_footnotes" is not implemented yet.
1474 Default: on.  Option: ``--docutils-footnotes``.
1477 .. _embed_stylesheet [latex writers]:
1479 embed_stylesheet
1480 ~~~~~~~~~~~~~~~~
1482 Embed the stylesheet(s) in the header of the output file.  The
1483 stylesheets must be accessible during processing.  Currently, this
1484 fails if the file is not available via the given path (i.e. the
1485 file is *not* searched in the `TeX input path`_).
1486 See also `embed_stylesheet [html writers]`_.
1488 Default: off.  Options: ``--embed-stylesheet, --link-stylesheet``.
1491 .. _footnote_references [latex writers]:
1493 footnote_references
1494 ~~~~~~~~~~~~~~~~~~~
1496 Format for `footnote references`_: one of "superscript" or "brackets".
1497 See also `footnote_references [html writers]`_.
1499 Overrides [#override]_ trim_footnote_reference_space_, if
1500 applicable. [#footnote_space]_
1502 Default: "superscript".  Option: ``--footnote-references``.
1505 graphicx_option
1506 ~~~~~~~~~~~~~~~
1508 LaTeX graphicx package option.
1510 Possible values are "dvips", "pdftex", "dvipdfmx".
1512 Default: "".  Option: ``--graphicx-option``.
1514 hyperlink_color
1515 ~~~~~~~~~~~~~~~
1517 Color of any hyperlinks embedded in text.
1519 * "0" or "false" disable coloring of links. (Links will be marked
1520   by red boxes that are not printed),
1521 * "black" results in “invisible“ links,
1523 Set hyperref_options_ to "draft" to completely disable hyperlinking.
1525 Default: "blue".  Option: ``--hyperlink-color``.
1527 hyperref_options
1528 ~~~~~~~~~~~~~~~~
1530 Options for the `hyperref TeX package`_. If hyperlink_color_ is
1531 not "false", the expansion of ::
1533   'colorlinks=true,linkcolor=%s,urlcolor=%s' % (
1534      hyperlink_color, self.hyperlink_color
1536 is prepended.
1538 Default: "".   Option: ``--hyperref-options``.
1540 .. _hyperref TeX package: http://tug.org/applications/hyperref/
1542 latex_preamble
1543 ~~~~~~~~~~~~~~
1545 LaTeX code that will be inserted in the document preamble.
1546 Can be used to load packages with options or (re-) define LaTeX
1547 macros without writing a custom style file (new in Docutils 0.7).
1549 Default: writer dependent (see `[latex2e writer]`_, `[xetex writer]`_).
1550 Option: ``--latex-preamble``.
1553 legacy_class_functions
1554 ~~~~~~~~~~~~~~~~~~~~~~
1556 Use legacy functions ``\DUtitle`` and ``\DUadmonition`` with a
1557 comma-separated list of class values as optional argument. If `False`, class
1558 values are handled with wrappers and admonitions use the ``DUadmonition``
1559 environment. See `Generating LaTeX with Docutils`__ for details.
1561 Default: True (this will change to False in version 0.18).
1562 Options: ``--legacy-class-functions``, ``--new-class-functions``.
1564 New in Docutils 0.17.
1566 __ latex.html#classes
1568 literal_block_env
1569 ~~~~~~~~~~~~~~~~~
1571 When possible\ [#]_, use the specified environment for `literal blocks`_.
1573 Default: "" (quoting of whitespace and special chars).
1574 Option: ``--literal-block-env``.
1576 .. [#] A literal-block element may originate from a `parsed literal`_.
1577    A LaTeX verbatim environment is only usable it does not contain
1578    inline elements.
1580 .. _parsed literal: ../ref/rst/directives.html#parsed-literal
1582 reference_label
1583 ~~~~~~~~~~~~~~~
1585 Per default the latex-writer puts the reference title into
1586 hyperreferences. Specify "ref*" or "pageref*" to get the section
1587 number or the page number.
1589 Default: "" (use hyperreferences).  Option: ``--reference-label``.
1590 section_enumerator_separator
1591 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1593 The separator between section number prefix and enumerator for
1594 compound enumerated lists (see `compound_enumerators`_).
1596 Generally it isn't recommended to use both sub-sections and nested
1597 enumerated lists with compound enumerators.  This setting avoids
1598 ambiguity in the situation where a section "1" has a list item
1599 enumerated "1.1", and subsection "1.1" has list item "1".  With a
1600 separator of ".", these both would translate into a final compound
1601 enumerator of "1.1.1".  With a separator of "-", we get the
1602 unambiguous "1-1.1" and "1.1-1".
1604 Default: "-".  Option: ``--section-enumerator-separator``.
1608 section_prefix_for_enumerators
1609 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1611 Enable or disable section ("." subsection ...) prefixes for
1612 compound enumerators.  This has no effect unless
1613 `compound_enumerators`_ are enabled.
1615 Default: disabled (None).
1616 Options: ``--section-prefix-for-enumerators``,
1617 ``--no-section-prefix-for-enumerators``.
1620 .. _stylesheet [latex writers]:
1622 stylesheet
1623 ~~~~~~~~~~
1625 A comma-separated list_ of style files.
1626 See also `stylesheet [html writers]`_.
1628 Overrides also stylesheet_path__. [#override]_
1630 If `embed_stylesheet`__ is False (default), the stylesheet files are
1631 referenced with ``\usepackage`` (extension ``.sty`` or no extension) or
1632 ``\input`` (any other extension).
1634 LaTeX will search the specified files in the `TeX input path`_.
1636 Default: no stylesheet ("").  Option: ``--stylesheet``.
1638 __ `stylesheet_path [latex writers]`_
1639 __ `embed_stylesheet [latex writers]`_
1640 .. _TeX input path:
1641    http://www.tex.ac.uk/cgi-bin/texfaq2html?label=what-TDS
1644 .. _stylesheet_dirs [latex writers]:
1646 stylesheet_dirs
1647 ~~~~~~~~~~~~~~~
1649 A comma-separated list of directories where stylesheets can be found.
1650 Used by the stylesheet_path__ setting.
1652 Note: This setting defines a "search path" (similar to the PATH variable for
1653 executables). However, the term "path" is already used in the
1654 stylesheet_path__ setting with the meaning of a file location.
1657 __ `stylesheet_path [latex writers]`_
1659 Default: the working directory of the process at launch and the directory
1660 with default stylesheet files (writer and installation specific).
1661 Use the ``--help`` option to get the exact value.
1662 Option: ``--stylesheet-directories``.
1665 .. _stylesheet_path [latex writers]:
1667 stylesheet_path
1668 ~~~~~~~~~~~~~~~
1670 A comma-separated list of style files. Relative paths are expanded if a
1671 matching file is found in the stylesheet_dirs__.
1672 If embed_stylesheet__ is False, paths are rewritten relative to the
1673 output file path. Run ``latex`` from the directory containing
1674 the output file.
1675 See also `stylesheet_path [html writers]`_.
1677 The stylesheet__  option is preferred for files in the `TeX input path`_.
1679 Also overrides stylesheet__. [#override]_
1681 Default: no stylesheet ("").  Option: ``--stylesheet-path``.
1683 __ `stylesheet_dirs [latex writers]`_
1684 __ `embed_stylesheet [latex writers]`_
1686 __ `stylesheet [latex writers]`_
1689 .. _table_style [latex writers]:
1691 table_style
1692 ~~~~~~~~~~~
1694 Specify the default style for tables_.
1695 See also `table_style [html writers]`_.
1697 Supported values:
1699 standard
1700   Borders around all cells.
1701 booktabs
1702   A line above and below the table and one after the head.
1703 borderless
1704   No borders.
1706 align-left, align-center, align-right
1707   Align tables.
1709 colwidths-auto, colwidths-given
1710   Default value for column width determination by
1711   LaTeX or Docutils.
1712   Override with the `table directive`_'s :widths: option.
1714   .. warning::
1716     ``colwidths-auto`` is only suited for tables with simple cell content.
1718     LaTeX puts the content of auto-sized columns on one line (merging
1719     paragraphs) and may fail with complex content.
1721 Default: "standard".  Option: ``--table-style``.
1724 .. _template [latex writers]:
1726 template
1727 ~~~~~~~~
1729 Path [#pwd]_ to template file, which must be encoded in UTF-8.
1730 See also `template [html writers]`_.
1732 Default: writer dependent (see `[latex2e writer]`_, `[xetex writer]`_).
1733 Options: ``--template``.
1736 use_bibtex
1737 ~~~~~~~~~~
1738 Specify style and database for the experimental `BibTeX` support, for
1739 example::
1741   --use-bibtex=mystyle,mydb1,mydb2
1743 Default: "" (don't use BibTeX).  Option ``--use-bibtex``.
1745 use_latex_abstract
1746 ~~~~~~~~~~~~~~~~~~
1748 Use LaTeX abstract environment for the document's abstract_.
1750 Default: off.  Options: ``--use-latex-abstract, --topic-abstract``.
1752 use_latex_citations
1753 ~~~~~~~~~~~~~~~~~~~
1755 Use \cite for citations_ instead of a simulation with figure-floats.
1757 Default: off.  Options: ``--use-latex-citations, --figure-citations``.
1759 use_latex_docinfo
1760 ~~~~~~~~~~~~~~~~~
1762 Attach author and date to the `document title`_
1763 instead of the `bibliographic fields`_.
1765 Default: off.  Options: ``--use-latex-docinfo, --use-docutils-docinfo``.
1767 use_latex_toc
1768 ~~~~~~~~~~~~~
1770 To get pagenumbers in the `table of contents`_, it
1771 must be generated by LaTeX. Usually latex must be run twice to get
1772 numbers correct.
1774 Default: on.  Options: ``--use-latex-toc, --use-docutils-toc``.
1776 use_part_section
1777 ~~~~~~~~~~~~~~~~
1779 Add parts on top of the section hierarchy.
1781 Default: don't (None).  Option: ``--use-part-section``.
1783 [latex2e writer]
1784 ~~~~~~~~~~~~~~~~
1786 The `LaTeX2e writer`_ generates a LaTeX source for compilation with 8-bit
1787 LaTeX (pdfTeX_). It shares all settings defined in the `[latex writers]`_
1788 `configuration section`_.
1790 .. _LaTeX2e writer: latex.html#latex2e-writer
1791 .. _pdfTeX: https://www.tug.org/applications/pdftex/
1792 .. _configuration section: `Configuration File Sections & Entries`_
1795 Writer Specific Defaults
1796 """"""""""""""""""""""""
1798 latex_preamble_
1799    Load the "PDF standard fonts" (Times, Helvetica, Courier)::
1801     \usepackage{mathptmx} % Times
1802     \usepackage[scaled=.90]{helvet}
1803     \usepackage{courier}
1805 template__
1806   "default.tex" in the ``docutils/writers/latex2e/`` directory
1807   (installed automatically).
1809   __ `template [latex writers]`_
1812 font_encoding
1813 """""""""""""
1815 Specify `LaTeX font encoding`_. Multiple options can be given, separated by
1816 commas. The last value becomes the document default.
1817 Possible values are "", "T1", "OT1", "LGR,T1" or any other combination of
1818 `LaTeX font encodings`_.
1820 Default: "T1".  Option: ``--font-encoding``.
1822 .. _LaTeX font encoding: latex.html#font-encoding
1823 .. _LaTeX font encodings:
1824    http://mirror.ctan.org/macros/latex/doc/encguide.pdf
1826 [xetex writer]
1827 ~~~~~~~~~~~~~~
1829 The `XeTeX writer`_ generates a LaTeX source for compilation with `XeTeX or
1830 LuaTeX`_. It derives from the latex2e writer, and shares all settings
1831 defined in the `[latex writers]`_ and `[latex2e writer]`_ `configuration
1832 sections`_.
1834 .. _XeTeX writer: latex.html#xetex-writer
1835 .. _XeTeX or LuaTeX: https://texfaq.org/FAQ-xetex-luatex
1836 .. _configuration sections: `Configuration File Sections & Entries`_
1838 Writer Specific Defaults
1839 """"""""""""""""""""""""
1841 latex_preamble_:
1842   Font setup for `Linux Libertine`_,::
1844       % Linux Libertine (free, wide coverage, not only for Linux)
1845       \setmainfont{Linux Libertine O}
1846       \setsansfont{Linux Biolinum O}
1847       \setmonofont[HyphenChar=None]{DejaVu Sans Mono}
1849   The optional argument ``HyphenChar=None`` to the monospace font
1850   prevents word hyphenation in literal text.
1852 .. _Linux Libertine: http://www.linuxlibertine.org/
1854 template__:
1855   "xelatex.tex" in the ``docutils/writers/latex2e/`` directory
1856   (installed automatically).
1858   .. TODO: show full path with ``--help`` (like in the HTML writers)
1859      and add the following line:
1860      for the exact machine-specific path, use the ``--help`` option).
1862   __ `template [latex writers]`_
1865 [odf_odt writer]
1866 ----------------
1868 The following command line options are specific to ``odtwriter``:
1870 stylesheet
1871 ~~~~~~~~~~
1873 Specify a stylesheet URL, used verbatim.
1875 Default: writers/odf_odt/styles.odt in the installation directory.
1877 odf-config-file
1878 ~~~~~~~~~~~~~~~
1880 Specify a configuration/mapping file relative to the current working
1881 directory for additional ODF options. In particular, this file may
1882 contain a section named "Formats" that maps default style names to names
1883 to be used in the resulting output file allowing for adhering to external
1884 standards. For more info and the format of the configuration/mapping
1885 file, see the `Odt Writer for Docutils`_ document.
1887 cloak-email-addresses
1888 ~~~~~~~~~~~~~~~~~~~~~
1890 Obfuscate email addresses to confuse harvesters while still
1891 keeping email links usable with standards-compliant browsers.
1893 no-cloak-email-addresses
1894 ~~~~~~~~~~~~~~~~~~~~~~~~
1895 Do not obfuscate email addresses.
1897 table-border-thickness
1898 ~~~~~~~~~~~~~~~~~~~~~~
1900 Specify the thickness of table borders in thousands of a cm.
1901 Default is 35.
1903 add-syntax-highlighting
1904 ~~~~~~~~~~~~~~~~~~~~~~~
1906 Add syntax highlighting in literal code blocks.
1908 no-syntax-highlighting
1909 ~~~~~~~~~~~~~~~~~~~~~~
1911 Do not add syntax highlighting in literal code blocks.
1912 (default)
1914 create-sections
1915 ~~~~~~~~~~~~~~~
1917 Create sections for headers.  (default)
1919 no-sections
1920 ~~~~~~~~~~~
1922 Do not create sections for headers.
1924 create-links
1925 ~~~~~~~~~~~~
1926 Create links.
1928 no-links
1929 ~~~~~~~~
1931 Do not create links.  (default)
1933 endnotes-end-doc
1934 ~~~~~~~~~~~~~~~~
1936 Generate endnotes at end of document, not footnotes at bottom of page.
1938 no-endnotes-end-doc
1939 ~~~~~~~~~~~~~~~~~~~
1941 Generate footnotes at bottom of page, not endnotes at end of
1942 document. (default)
1944 generate-list-toc
1945 ~~~~~~~~~~~~~~~~~
1947 Generate a bullet list table of contents, not an
1948 ODF/``oowriter`` table of contents.
1950 generate-oowriter-toc
1951 ~~~~~~~~~~~~~~~~~~~~~
1953 Generate an ODF/``oowriter`` table of contents, not a bullet
1954 list.  (default) **Note:** ``odtwriter`` is not able to
1955 determine page numbers, so you will need to open the generated
1956 document in ``oowriter``, then right-click on the table of
1957 contents and select "Update" to insert page numbers.
1959 custom-odt-header
1960 ~~~~~~~~~~~~~~~~~
1962 Specify the contents of a custom header line.  For details about
1963 custom headers and about special field character sequences, see
1964 section "Custom header/footers: inserting page numbers, date,
1965 time, etc" in the `Odt Writer for Docutils`_ document for
1966 details.
1968 custom-odt-footer
1969 ~~~~~~~~~~~~~~~~~
1971 Specify the contents of a custom footer line.  For details about
1972 custom footers and about special field character sequences, see
1973 section "Custom header/footers: inserting page numbers, date,
1974 time, etc" in the `Odt Writer for Docutils`_ document for
1975 details.
1977 .. _Odt Writer for Docutils: odt.html
1980 [pseudoxml writer]
1981 ------------------
1983 detailled
1984 ~~~~~~~~~
1986 Pretty-print <#text> nodes.
1988 Default:  False.  Options: ``--detailled``.
1991 [applications]
1992 ==============
1994 [buildhtml application]
1995 -----------------------
1997 dry_run
1998 ~~~~~~~
2000 Do not process files, show files that would be processed.
2002 Default:  False.  Options: ``--dry-run``.
2004 html_writer
2005 ~~~~~~~~~~~
2007 `HTML writer`_ version. One of "html", "html4", "html5".
2009 Default: "html" (use Docutils' default HTML writer).
2010 Options: ``--html-writer``
2012 .. _HTML writer: html.html
2014 ignore
2015 ~~~~~~
2017 List_ of wildcard (shell globing) patterns, specifying files to silently
2018 ignore.  To specify multiple patterns, use colon-separated patterns (in
2019 configuration files or on the command line); on the command line, the
2020 option may also be used more than once.
2022 Default: None.  Options: ``--ignore``.
2024 prune
2025 ~~~~~
2027 List_ of directories not to process.  To specify multiple
2028 directories, use colon-separated paths (in configuration files or
2029 on the command line); on the command line, the option may also be
2030 used more than once.
2032 Default: ['.hg', '.bzr', '.git', '.svn', 'CVS'].  Options:
2033 ``--prune``.
2035 recurse
2036 ~~~~~~~
2038 Recursively scan subdirectories, or ignore subdirectories.
2040 Default: recurse (True).  Options: ``--recurse, --local``.
2042 silent
2043 ~~~~~~
2045 Work silently (no progress messages).  Independent of
2046 "report_level".
2048 Default: show progress (None).  Options: ``--silent``.
2051 [docfactory application]
2052 ------------------------
2054 (To be completed.)
2057 Other Settings
2058 ==============
2060 Command-Line Only
2061 -----------------
2063 These settings are only effective as command-line options; setting
2064 them in configuration files has no effect.
2066 config
2067 ~~~~~~
2069 Path to a configuration file to read (if it exists). [#pwd]_
2070 Settings may override defaults and earlier settings.  The config
2071 file is processed immediately.  Multiple ``--config`` options may
2072 be specified; each will be processed in turn.
2074 Filesystem path settings contained within the config file will be
2075 interpreted relative to the config file's location (*not* relative
2076 to the current working directory).
2078 Default: None.  Options: ``--config``.
2081 Internal Settings
2082 -----------------
2084 These settings are for internal use only; setting them in
2085 configuration files has no effect, and there are no corresponding
2086 command-line options.
2088 _config_files
2089 ~~~~~~~~~~~~~
2091 List of paths of applied configuration files.
2093 Default: None.  No command-line options.
2095 _directories
2096 ~~~~~~~~~~~~
2098 (``buildhtml.py`` front end.)  List of paths to source
2099 directories, set from positional arguments.
2101 Default: current working directory (None).  No command-line
2102 options.
2104 _disable_config
2105 ~~~~~~~~~~~~~~~
2107 Prevent standard configuration files from being read.  For
2108 programmatic use only.
2110 Default: config files enabled (None).  No command-line options.
2112 _destination
2113 ~~~~~~~~~~~~
2115 Path to output destination, set from positional arguments.
2117 Default: stdout (None).  No command-line options.
2119 _source
2120 ~~~~~~~
2122 Path to input source, set from positional arguments.
2124 Default: stdin (None).  No command-line options.
2127 .. _language tag: http://www.w3.org/International/articles/language-tags/
2128 .. _BCP 47: http://www.rfc-editor.org/rfc/bcp/bcp47.txt
2129 .. _ISO 639: http://www.loc.gov/standards/iso639-2/php/English_list.php
2130 .. _ISO 3166: http://www.iso.ch/iso/en/prods-services/iso3166ma/
2131    02iso-3166-code-lists/index.html
2133 .. [#pwd] Path relative to the working directory of the process at
2134    launch.
2136 .. [#override] The overridden setting will automatically be set to
2137    ``None`` for command-line options and config file settings.  Client
2138    programs which specify defaults that override other settings must
2139    do the overriding explicitly, by assigning ``None`` to the other
2140    settings.
2142 .. [#dependencies] Images are only added to the dependency list if the
2143    reStructuredText parser extracted image dimensions from the file.
2145 .. [#footnote_space] The overriding only happens if the parser supports
2146    the trim_footnote_reference_space option.
2149 ------------------------------
2150 Old-Format Configuration Files
2151 ------------------------------
2153 Formerly, Docutils configuration files contained a single "[options]"
2154 section only.  This was found to be inflexible, and in August 2003
2155 Docutils adopted the current component-based configuration file
2156 sections as described above.  Docutils will still recognize the old
2157 "[options]" section, but complains with a deprecation warning.
2159 To convert existing config files, the easiest way is to change the
2160 section title: change "[options]" to "[general]".  Most settings
2161 haven't changed.  The only ones to watch out for are these:
2163 =====================  =====================================
2164 Old-Format Setting     New Section & Setting
2165 =====================  =====================================
2166 pep_stylesheet         [pep_html writer] stylesheet
2167 pep_stylesheet_path    [pep_html writer] stylesheet_path
2168 pep_template           [pep_html writer] template
2169 =====================  =====================================
2171 .. References
2173 .. _abstract:
2174 .. _bibliographic field list:
2175 .. _bibliographic fields:
2176    ../ref/rst/restructuredtext.html#bibliographic-fields
2177 .. _block quote: ../ref/rst/restructuredtext.html#block-quotes
2178 .. _citations: ../ref/rst/restructuredtext.html#citations
2179 .. _enumerated lists: ../ref/rst/restructuredtext.html#enumerated-lists
2180 .. _field lists: ../ref/rst/restructuredtext.html#field-lists
2181 .. _field names: ../ref/rst/restructuredtext.html#field-names
2182 .. _footnotes: ../ref/rst/restructuredtext.html#footnotes
2183 .. _footnote references: ../ref/rst/restructuredtext.html#footnote-references
2184 .. _inline markup recognition rules:
2185     ../ref/rst/restructuredtext.html#inline-markup-recognition-rules
2186 .. _literal blocks: ../ref/rst/restructuredtext.html#literal-blocks
2187 .. _option lists: ../ref/rst/restructuredtext.html#option-lists
2188 .. _tables: ../ref/rst/restructuredtext.html#tables
2190 .. _table of contents: ../ref/rst/directives.html#contents