docs/user/config.txt

   1 ========================
   2  Docutils Configuration
   3 ========================
   4
   5 :Author: David Goodger
   6 :Contact: goodger@python.org
   7 :Revision: $Revision$
   8 :Date: $Date$
   9 :Copyright: This document has been placed in the public domain.
  10
  11 .. sidebar:: Docutils Security for Web Applications
  12
  13    For details about securing web applications, please see `Deploying
  14    Docutils Securely <../howto/security.html>`_.
  15
  16 .. contents::
  17
  18
  19 -------------------
  20 Configuration Files
  21 -------------------
  22
  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.
  27
  28 By default, Docutils checks the following places for configuration
  29 files, in the following order:
  30
  31 1. ``/etc/docutils.conf``: This is a system-wide configuration file,
  32    applicable to all Docutils processing on the system.
  33
  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.
  41
  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.
  46
  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.
  51
  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.
  59
  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.
  65
  66
  67 -------------------------
  68 Configuration File Syntax
  69 -------------------------
  70
  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:
  74
  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.
  81
  82 .. Note:: No format string interpolation is done.
  83
  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.
  88
  89 For on/off switch settings (booleans), the following values are
  90 recognized:
  91
  92 * On: "true", "yes", "on", "1"
  93 * Off: "false", "no", "off", "0", "" (no value)
  94
  95
  96 Example
  97 =======
  98
  99 This is the contents of the ``tools/docutils.conf`` configuration file
 100 supplied with Docutils::
 101
 102     # These entries affect all processing:
 103     [general]
 104     source-link: yes
 105     datestamp: %Y-%m-%d %H:%M UTC
 106     generator: on
 107
 108     # These entries affect HTML output:
 109     [html4css1 writer]
 110     # Required for docutils-update, the website build system:
 111     stylesheet-path: ../docutils/writers/html4css1/html4css1.css
 112     embed-stylesheet: no
 113     field-name-limit: 20
 114
 115 Individual configuration sections and settings are described in the
 116 following section.
 117
 118
 119 -------------------------------------
 120 Configuration File Sections & Entries
 121 -------------------------------------
 122
 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:
 131
 132 1. `[general]`_
 133
 134 2. `[parsers]`_, parser dependencies, and the section specific to the
 135    Parser used ("[... parser]").  Currently, only `[restructuredtext
 136    parser]`_ is applicable.
 137
 138 3. `[readers]`_, reader dependencies, and the section specific to the
 139    Reader used ("[... reader]").  For example, `[pep reader]`_ depends
 140    on `[standalone reader]`_.
 141
 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]`_.
 145
 146 5. `[applications]`_, application dependencies, and the section
 147     specific to the Application (front-end tool) in use
 148     ("[... application]").
 149
 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.
 155
 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
 161 file.
 162
 163 Some knowledge of Python_ is assumed for some attributes.
 164
 165 .. _ConfigParser.py:
 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
 170
 171
 172 [general]
 173 =========
 174
 175 Settings in the "[general]" section are always applied.
 176
 177 _`auto_id_prefix`
 178     Prefix prepended to all auto-generated IDs generated within the
 179     document, after id_prefix_.
 180
 181     Default: "id".  Options: ``--auto-id-prefix`` (hidden, intended
 182     mainly for programmatic use).
 183
 184 _`datestamp`
 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`__.
 188
 189     Default: None.  Options: ``--date, -d, --time, -t,
 190     --no-datestamp``.
 191
 192     Configuration file entry examples::
 193
 194         # Equivalent to --date command-line option, results in
 195         # ISO 8601 extended format datestamp, e.g. "2001-12-21":
 196         datestamp: %Y-%m-%d
 197
 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
 201
 202         # Disables datestamp; equivalent to --no-datestamp:
 203         datestamp:
 204
 205     __ http://www.python.org/doc/current/lib/module-time.html
 206
 207 _`debug`
 208     Report debug-level system messages.
 209
 210     Default: don't (None).  Options: ``--debug, --no-debug``.
 211
 212 _`dump_internals`
 213     At the end of processing, write all internal attributes of the
 214     document (``document.__dict__``) to stderr.
 215
 216     Default: don't (None).  Options: ``--dump-internals`` (hidden, for
 217     development use only).
 218
 219 _`dump_pseudo_xml`
 220     At the end of processing, write the pseudo-XML representation of
 221     the document to stderr.
 222
 223     Default: don't (None).  Options: ``--dump-pseudo-xml`` (hidden,
 224     for development use only).
 225
 226 _`dump_settings`
 227     At the end of processing, write all Docutils settings to stderr.
 228
 229     Default: don't (None).  Options: ``--dump-settings`` (hidden, for
 230     development use only).
 231
 232 _`dump_transforms`
 233     At the end of processing, write a list of all transforms applied
 234     to the document to stderr.
 235
 236     Default: don't (None).  Options: ``--dump-transforms`` (hidden,
 237     for development use only).
 238
 239 _`error_encoding`
 240     The text encoding for error output.
 241
 242     Default: "ascii".  Options: ``--error-encoding, -e``.
 243
 244 _`error_encoding_error_handler`
 245     The error handler for unencodable characters in error output.  See
 246     output_encoding_error_handler_ for acceptable values.
 247
 248     Default: "backslashreplace" for Python 2.3 and later; "replace"
 249     otherwise.  Options: ``--error-encoding-error-handler,
 250     --error-encoding, -e``.
 251
 252 _`exit_status_level`
 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
 256     for INFO, etc.).
 257
 258     Default: disabled (5).  Options: ``--exit-status``.
 259
 260 _`expose_internals`
 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.
 265
 266     Default: don't (None).  Options: ``--expose-internal-attribute``
 267     (hidden, for development use only).
 268
 269 _`footnote_backlinks`
 270     Enable or disable backlinks from footnotes and citations to their
 271     references.
 272
 273     Default: enabled (1).  Options: ``--footnote-backlinks,
 274     --no-footnote-backlinks``.
 275
 276 _`generator`
 277     Include a "Generated by Docutils" credit and link in the document
 278     footer.
 279
 280     Default: off (None).  Options: ``--generator, -g,
 281     --no-generator``.
 282
 283 _`halt_level`
 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.
 287
 288     Default: severe (4).  Options: ``--halt, --strict``.
 289
 290 _`id_prefix`
 291     Prefix prepended to all IDs generated within the document.  See
 292     also auto_id_prefix_.
 293
 294     Default: "" (empty).  Options: ``--id-prefix`` (hidden, intended
 295     mainly for programmatic use).
 296
 297 _`input_encoding`
 298     The text encoding for input.
 299
 300     Default: auto-detect (None).  Options: ``--input-encoding, -i``.
 301
 302 _`input_encoding_error_handler`
 303     The error handler for undecodable characters in the input.
 304     Acceptable values include:
 305
 306     strict
 307         Raise an exception in case of an encoding error.
 308     replace
 309         Replace malformed data with the official Unicode replacement
 310         character, U+FFFD.
 311     ignore
 312         Ignore malformed data and continue without further notice.
 313
 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.
 317
 318     Default: "strict".  Options: ``--input-encoding-error-handler,
 319     --input-encoding, -i``.
 320
 321 _`language_code`
 322     `ISO 639`_ 2-letter language code (3-letter codes used only if no
 323     2-letter code exists).
 324
 325     Default: English ("en").  Options: ``--language, -l``.
 326
 327 _`output_encoding`
 328     The text encoding for output.
 329
 330     Default: "UTF-8".  Options: ``--output-encoding, -o``.
 331
 332 _`output_encoding_error_handler`
 333     The error handler for unencodable characters in the output.
 334     Acceptable values include:
 335
 336     strict
 337         Raise an exception in case of an encoding error.
 338     replace
 339         Replace malformed data with a suitable replacement marker,
 340         such as "?".
 341     ignore
 342         Ignore malformed data and continue without further notice.
 343     xmlcharrefreplace
 344         Replace with the appropriate XML character reference, such as
 345         "``&#8224;``".
 346     backslashreplace
 347         (Python 2.3+)  Replace with backslashed escape sequences, such
 348         as "``\u2020``".
 349
 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.
 353
 354     Default: "strict".  Options: ``--output-encoding-error-handler,
 355     --output-encoding, -o``.
 356
 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
 362     ``make``.
 363
 364     Set to ``-`` in order to write dependencies to stdout.
 365
 366     Default: None.  Option: ``--record-dependencies``.
 367
 368 _`report_level`
 369     Verbosity threshold at or above which system messages are
 370     reported.
 371
 372     Default: warning (2).  Options: ``--report, -r, --verbose, -v,
 373     --quiet, -q``.
 374
 375 _`sectnum_xform`
 376     Enable or disable the section numbering transform
 377     (docutils.transforms.parts.SectNum).
 378
 379     Default: enabled (1).  Options: ``--section-numbering``,
 380     ``--no-section-numbering``.
 381
 382 _`source_link`
 383     Include a "View document source" link in the document footer.  URL
 384     will be relative to the destination.
 385
 386     Default: don't (None).  Options: ``--source-link, -s,
 387     --no-source-link``.
 388
 389 _`source_url`
 390     An explicit URL for a "View document source" link, used verbatim.
 391
 392     Default: compute if source_link (None).  Options: ``--source-url,
 393     --no-source-link``.
 394
 395 _`strict_visitor`
 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.
 399
 400     Default: disabled (None).  Option: ``--strict-visitor`` (hidden,
 401     for development use only).
 402
 403 _`strip_classes`
 404     List of "classes" attribute values to remove from all elements in
 405     the document tree.
 406
 407     Default: disabled (None).  Option: ``--strip-class``.
 408
 409 _`strip_comments`
 410     Enable the removal of comment elements from the document tree.
 411
 412     Default: disabled (None).  Options: ``--strip-comment``,
 413     ``--leave-comments``.
 414
 415 _`strip_elements_with_classes`
 416     List of "classes" attribute values; matching elements to be
 417     removed from the document tree.
 418
 419     Default: disabled (None).  Option: ``--strip-element-with-class``.
 420
 421 _`title`
 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.
 426
 427     Default: none.  Option: ``--title``.
 428
 429 _`toc_backlinks`
 430     Enable backlinks from section titles to table of contents entries
 431     ("entry"), to the top of the TOC ("top"), or disable ("none").
 432
 433     Default: "entry".  Options: ``--toc-entry-backlinks,
 434     --toc-top-backlinks, --no-toc-backlinks``.
 435
 436 _`traceback`
 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.
 441
 442     Default: disabled (None) unless Docutils is run programmatically
 443     using the `Publisher Interface`_.  Options: ``--traceback,
 444     --no-traceback``.
 445
 446     .. _Publisher Interface: ../api/publisher.html
 447
 448 _`warning_stream`
 449     Path to a file for the output of system messages (warnings)
 450     [#pwd]_.
 451
 452     Default: stderr (None).  Options: ``--warnings``.
 453
 454
 455 [parsers]
 456 ---------
 457
 458 Docutils currently supports only one parser, for reStructuredText.
 459
 460
 461 [restructuredtext parser]
 462 `````````````````````````
 463
 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.)
 469
 470     Default: enabled (1).  Options: ``--file-insertion-enabled,
 471     --no-file-insertion``.
 472
 473     .. _include: ../ref/rst/directives.html#include
 474     .. _raw: ../ref/rst/directives.html#raw
 475
 476 _`pep_references`
 477     Recognize and link to standalone PEP references (like "PEP 258").
 478
 479     Default: disabled (None); enabled (1) in PEP Reader.  Options:
 480     ``--pep-references``.
 481
 482 _`pep_base_url`
 483     Base URL for PEP references.
 484
 485     Default: "http://www.python.org/peps/".  Option:
 486     ``--pep-base-url``.
 487
 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_.
 491
 492     Default: "pep-%04d".  Option: ``--pep-file-url``.
 493
 494 _`raw_enabled`
 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
 498     setting.)
 499
 500     Default: enabled (1).  Options: ``--raw-enabled, --no-raw``.
 501
 502 _`rfc_references`
 503     Recognize and link to standalone RFC references (like "RFC 822").
 504
 505     Default: disabled (None); enabled (1) in PEP Reader.  Options:
 506     ``--rfc-references``.
 507
 508 _`rfc_base_url`
 509     Base URL for RFC references.
 510
 511     Default: "http://www.faqs.org/rfcs/".  Option: ``--rfc-base-url``.
 512
 513 _`tab_width`
 514     Number of spaces for hard tab expansion.
 515
 516     Default: 8.  Options: ``--tab-width``.
 517
 518 _`trim_footnote_reference_space`
 519     Remove spaces before footnote references.
 520
 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``.
 525
 526 __ `footnote_references [latex2e writer]`_
 527
 528
 529 [readers]
 530 ---------
 531
 532
 533 [standalone reader]
 534 ```````````````````
 535
 536 _`docinfo_xform`
 537     Enable or disable the bibliographic field list transform
 538     (docutils.transforms.frontmatter.DocInfo).
 539
 540     Default: enabled (1).  Options: ``--no-doc-info``.
 541
 542 _`doctitle_xform`
 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).
 546
 547     Default: enabled (1).  Options: ``--no-doc-title``.
 548
 549 _`sectsubtitle_xform`
 550
 551     Enable or disable the promotion of the title of a lone subsection
 552     to a subtitle (docutils.transforms.frontmatter.SectSubTitle).
 553
 554     Default: disabled (0).  Options: ``--section-subtitles,
 555     --no-section-subtitles``.
 556
 557
 558 [pep reader]
 559 ````````````
 560
 561 The `pep_references`_ and `rfc_references`_ settings
 562 (`[restructuredtext parser]`_) are set on by default.
 563
 564
 565 [python reader]
 566 ```````````````
 567
 568 Under construction.
 569
 570
 571 [writers]
 572 ---------
 573
 574 [docutils_xml writer]
 575 `````````````````````
 576
 577 _`doctype_declaration`
 578     Generate XML with a DOCTYPE declaration.
 579
 580     Default: do (1).  Options: ``--no-doctype``.
 581
 582 _`indents`
 583     Generate XML with indents and newlines.
 584
 585     Default: don't (None).  Options: ``--indents``.
 586
 587 _`newlines`
 588     Generate XML with newlines before and after tags.
 589
 590     Default: don't (None).  Options: ``--newlines``.
 591
 592 .. _xml_declaration [docutils_xml writer]:
 593
 594 xml_declaration
 595     Generate XML with an XML declaration.  Also defined for the
 596     `HTML Writer`__.
 597
 598     .. Caution:: The XML declaration carries text encoding
 599        information, without which standard tools may be unable to read
 600        the generated XML.
 601
 602     Default: do (1).  Options: ``--no-xml-declaration``.
 603
 604     __ `xml_declaration [html4css1 writer]`_
 605
 606
 607 [html4css1 writer]
 608 ``````````````````
 609
 610 .. _attribution [html4css1 writer]:
 611
 612 attribution
 613     Format for block quote attributions: one of "dash" (em-dash
 614     prefix), "parentheses"/"parens", or "none".  Also defined for the
 615     `LaTeX Writer`__.
 616
 617     Default: "dash".  Options: ``--attribution``.
 618
 619     __ `attribution [latex2e writer]`_
 620
 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::
 629
 630         <a class="reference" href="mailto:abc&#37;&#52;&#48;example&#46;org">
 631         abc<span>&#64;</span>example<span>&#46;</span>org</a>
 632
 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.
 637
 638     Default: don't cloak (None).  Option: ``--cloak-email-addresses``.
 639
 640 _`compact_lists`
 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.
 646
 647     Default: enabled (1).  Options: ``--compact-lists,
 648     --no-compact-lists``.
 649
 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.
 655
 656     Default: enabled (1).  Options: ``--compact-field-lists,
 657     --no-compact-field-lists``.
 658
 659 _`embed_stylesheet`
 660     Embed the stylesheet in the output HTML file.  The stylesheet file
 661     must be accessible during processing.
 662
 663     Default: enabled.  Options: ``--embed-stylesheet,
 664     --link-stylesheet``.
 665
 666 _`field_name_limit`
 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
 670     option_limit_.
 671
 672     Default: 14 characters.  Option: ``--field-name-limit``.
 673
 674 .. _footnote_references [html4css1 writer]:
 675
 676 footnote_references
 677     Format for footnote references, one of "superscript" or
 678     "brackets".  Also defined for the `LaTeX Writer`__.
 679
 680     Overrides [#override]_ trim_footnote_reference_space_, if
 681     applicable. [#footnote_space]_
 682
 683     Default: "brackets".  Option: ``--footnote-references``.
 684
 685     __ `footnote_references [latex2e writer]`_
 686
 687 _`initial_header_level`
 688     The initial level for header elements.  This does not affect the
 689     document title & subtitle; see doctitle_xform_.
 690
 691     Default: 1 (for "<h1>").  Option: ``--initial-header-level``.
 692
 693 _`option_limit`
 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
 697     field_name_limit_.
 698
 699     Default: 14 characters.  Option: ``--option-limit``.
 700
 701 .. _stylesheet [html4css1 writer]:
 702
 703 stylesheet
 704     CSS stylesheet URL, used verbatim.  Overrides the
 705     "stylesheet_path" setting [#override]_.  Pass an empty string to
 706     deactivate stylesheet inclusion.
 707
 708     Default: None.  Options: ``--stylesheet``.
 709
 710     (Setting also defined for the `LaTeX Writer`__.)
 711
 712     __ `stylesheet [latex2e writer]`_
 713
 714 .. _stylesheet_path [html4css1 writer]:
 715
 716 stylesheet_path
 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`__.
 720
 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``.
 724
 725     __ `stylesheet_path [latex2e writer]`_
 726
 727 _`template`
 728     Path to template file, which must be encoded in UTF-8 [#pwd]_.
 729
 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``.
 733
 734 .. _xml_declaration [html4css1 writer]:
 735
 736 xml_declaration
 737     Generate XML with an XML declaration.  Also defined for the
 738     `Docutils XML Writer`__.
 739
 740     .. Caution:: The XML declaration carries text encoding
 741        information, without which standard tools may be unable to read
 742        the generated XML.
 743
 744     Default: do (1).  Options: ``--no-xml-declaration``.
 745
 746     __ `xml_declaration [docutils_xml writer]`_
 747
 748
 749 [pep_html writer]
 750 .................
 751
 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.
 756
 757 _`no_random`
 758     Do not use a random banner image.  Mainly used to get predictable
 759     results when testing.
 760
 761     Default: random enabled (None).  Options: ``--no-random``
 762     (hidden).
 763
 764 _`pep_home`
 765     Home URL prefix for PEPs.
 766
 767     Default: current directory (".").  Options: ``--pep-home``.
 768
 769 _`python_home`
 770     Python's home URL.
 771
 772     Default: parent directory ("..").  Options: ``--python-home``.
 773
 774 The PEP/HTML Writer's default for the following settings differ from
 775 those of the standard HTML Writer:
 776
 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.
 780
 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``
 784   option.
 785
 786
 787 [s5_html writer]
 788 .................
 789
 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.
 794
 795 _`hidden_controls`
 796     Auto-hide the presentation controls in slideshow mode, or or keep
 797     them visible at all times.
 798
 799     Default: auto-hide (1).  Options: ``--hidden-controls``,
 800     ``--visible-controls``.
 801
 802 _`current_slide`
 803     Enable or disable the current slide indicator ("1/15").
 804
 805     Default: disabled (None).  Options: ``--current-slide``,
 806     ``--no-current-slide``.
 807
 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
 811     used.
 812
 813     Default: keep existing theme files (None).  Options:
 814     ``--keep-theme-files``, ``--overwrite-theme-files``.
 815
 816 _`theme`
 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]_.
 822
 823     Default: "default".  Option: ``--theme``.
 824
 825 _`theme_url`
 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]_.
 829
 830     Default: None.  Option: ``--theme-url``.
 831
 832 _`view_mode`
 833     The initial view mode, either "slideshow" or "outline".
 834
 835     Default: "slidewhow".  Option: ``--view-mode``.
 836
 837 The S5/HTML Writer's default for the following settings differ
 838 from those of the standard HTML Writer:
 839
 840 * ``compact_lists``: The default here is to disable compact lists.
 841
 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``
 845   option.
 846
 847
 848 [latex2e writer]
 849 ````````````````
 850
 851 _`use_latex_toc`
 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
 854     numbers correct.
 855
 856     *Note:* LaTeX will number the sections, which might be a bug in
 857     this case.
 858
 859     Default: off.  Option: ``--use-latex-toc``.
 860
 861 .. XXX Missing: use_latex_docinfo
 862
 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.
 867
 868     Default: off.  Option: ``--use-latex-footnotes``.
 869
 870 _`hyperlink_color`
 871     Color of any hyperlinks embedded in text. Use "0" to disable
 872     coloring of links.
 873
 874     Default: "blue".  Option: ``--hyperlink-color``.
 875
 876 _`documentclass`
 877     Specify latex documentclass, *but* beaware that books have chapters
 878     articles not.
 879
 880     Default: "article".  Option: ``--documentclass``.
 881
 882 _`documentoptions`
 883     Specify document options.  Multiple options can be given, separated by
 884     commas.
 885
 886     Default: "10pt,a4paper".  Option: ``--documentoptions``.
 887
 888 .. _stylesheet [latex2e writer]:
 889
 890 stylesheet
 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`__.
 894
 895     Default: no stylesheet ("").  Option: ``--stylesheet``.
 896
 897     __ `stylesheet [html4css1 writer]`_
 898
 899 .. _stylesheet_path [latex2e writer]:
 900
 901 stylesheet_path
 902     Path to stylesheet [#pwd]_.  Overrides "stylesheet" setting
 903     (``--stylesheet``) [#override]_.
 904
 905     Please note that you will have to run ``latex`` from the directory
 906     containing the output file; otherwise the stylesheet reference
 907     will be invalid.
 908
 909     This setting is also defined for the `HTML Writer`__.
 910
 911     Default: None.  Option: ``--stylesheet-path``.
 912
 913     __ `stylesheet_path [html4css1 writer]`_
 914
 915 .. XXX Missing: embed_stylesheet
 916
 917 .. _footnote_references [latex2e writer]:
 918
 919 footnote_references
 920     Format for footnote references: one of "superscript" or
 921     "brackets".  Also defined for the `HTML Writer`__.
 922
 923     Overrides [#override]_ trim_footnote_reference_space_, if
 924     applicable. [#footnote_space]_
 925
 926     Default: "superscript".  Option: ``--footnote-references``.
 927
 928     __ `footnote_references [html4css1 writer]`_
 929
 930 .. _attribution [latex2e writer]:
 931
 932 attribution
 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
 936     Writer`__.
 937
 938     Default: "dash".  Option: ``--attribution``.
 939
 940     __ `attribution [html4css1 writer]`_
 941
 942 _`compound_enumerators`
 943     Enable or disable compound enumerators for nested enumerated lists
 944     (e.g. "1.2.a.ii").
 945
 946     Default: disabled (None).  Options: ``--compound-enumerators``,
 947     ``--no-compound-enumerators``.
 948
 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.
 953
 954     Default: disabled (None).  Options:
 955     ``--section-prefix-for-enumerators``,
 956     ``--no-section-prefix-for-enumerators``.
 957
 958 _`section_enumerator_separator`
 959     The separator between section number prefix and enumerator for
 960     compound enumerated lists (see `compound_enumerators`_).
 961
 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".
 969
 970     Default: "-".  Option: ``--section-enumerator-separator``.
 971
 972 _`table_style`
 973     Specify the drawing of separation lines.
 974
 975     - "standard" lines around and between cells.
 976     - "booktabs" a line above and below the table and one after the
 977       head.
 978     - "nolines".
 979
 980     Default: "standard".  Option: ``--table-style``.
 981
 982
 983 [pseudoxml writer]
 984 ``````````````````
 985
 986 No settings are defined for this Writer.
 987
 988
 989 [applications]
 990 --------------
 991
 992 [buildhtml application]
 993 ```````````````````````
 994
 995 _`ignore`
 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
 999     used more than once.
1000
1001     Default: ['.svn', 'CVS'].  Options: ``--ignore``.
1002
1003 _`prune`
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.
1007
1008     Default: none ([]).  Options: ``--prune``.
1009
1010 _`recurse`
1011     Recursively scan subdirectories, or ignore subdirectories.
1012
1013     Default: recurse (1).  Options: ``--recurse, --local``.
1014
1015 _`silent`
1016     Work silently (no progress messages).  Independent of
1017     "report_level".
1018
1019     Default: show progress (None).  Options: ``--silent``.
1020
1021
1022 [docfactory application]
1023 ````````````````````````
1024
1025 (To be completed.)
1026
1027
1028 Other Settings
1029 ==============
1030
1031 Command-Line Only
1032 -----------------
1033
1034 These settings are only effective as command-line options; setting
1035 them in configuration files has no effect.
1036
1037 _`config`
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.
1042
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).
1046
1047     Default: None.  Options: ``--config``.
1048
1049
1050 Internal Settings
1051 -----------------
1052
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.
1056
1057 _`_config_files`
1058     List of paths of applied configuration files.
1059
1060     Default: None.  No command-line options.
1061
1062 _`_directories`
1063     (``buildhtml.py`` front end.)  List of paths to source
1064     directories, set from positional arguments.
1065
1066     Default: current working directory (None).  No command-line
1067     options.
1068
1069 _`_disable_config`
1070     Prevent standard configuration files from being read.  For
1071     programmatic use only.
1072
1073     Default: config files enabled (None).  No command-line options.
1074
1075 _`_destination`
1076     Path to output destination, set from positional arguments.
1077
1078     Default: stdout (None).  No command-line options.
1079
1080 _`_source`
1081     Path to input source, set from positional arguments.
1082
1083     Default: stdin (None).  No command-line options.
1084
1085
1086 .. _ISO 639: http://www.loc.gov/standards/iso639-2/englangn.html
1087
1088 .. [#pwd] Path relative to the working directory of the process at
1089    launch.
1090
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
1095    settings.
1096
1097 .. [#dependencies] Some notes on the dependency recorder:
1098
1099    * Images are only added to the dependency list if the
1100      reStructuredText parser extracted image dimensions from the file.
1101
1102    * Stylesheets are only added if they are embedded.
1103
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.
1110
1111 .. [#footnote_space] The footnote space is trimmed if the reference
1112    style is "superscript", and it is left if the reference style is
1113    "brackets".
1114
1115    The overriding only happens if the parser supports the
1116    trim_footnote_reference_space option.
1117
1118
1119 ------------------------------
1120 Old-Format Configuration Files
1121 ------------------------------
1122
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.
1128
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:
1132
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 =====================  =====================================