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 .. contents::
  12
  13
  14 --------------------
  15 Command-line Options
  16 --------------------
  17
  18 The command-line options you can pass to the `Docutils front-end
  19 tools`_ are described in the section `Configuration File Sections &
  20 Entries`_ below.  Following is an index of all command-line options.
  21
  22 .. _Docutils front-end tools: tools.html
  23
  24 * General Docutils Options
  25
  26   - `--title=TITLE`__
  27
  28     __ title_
  29
  30   - `--generator, -g`__
  31
  32     __ generator_
  33
  34   - `--no-generator`__
  35
  36     __ generator_
  37
  38   - `--date, -d`__
  39
  40     __ datestamp_
  41
  42   - `--time, -t`__
  43
  44     __ datestamp_
  45
  46   - `--no-datestamp`__
  47
  48     __ datestamp_
  49
  50   - `--source-link, -s`__
  51
  52     __ source_link_
  53
  54   - `--source-url=<URL>`__
  55
  56     __ source_url_
  57
  58   - `--no-source-link`__
  59
  60     __ source_link_
  61
  62   - `--toc-entry-backlinks`__
  63
  64     __ toc_backlinks_
  65
  66   - `--toc-top-backlinks`__
  67
  68     __ toc_backlinks_
  69
  70   - `--no-toc-backlinks`__
  71
  72     __ toc_backlinks_
  73
  74   - `--footnote-backlinks`__
  75
  76     __ footnote_backlinks_
  77
  78   - `--footnote-backlinks`__
  79
  80     __ footnote_backlinks_
  81
  82   - `--section-numbering`__
  83
  84     __ sectnum_xform_
  85
  86   - `--no-section-numbering`__
  87
  88     __ sectnum_xform_
  89
  90   - `--strip-comments`__
  91
  92     __ strip_comments_
  93
  94   - `--leave-comments`__
  95
  96     __ strip_comments_
  97
  98   - `--report=<level>, -r<level>`__
  99
 100     __ report_level_
 101
 102   - `--verbose, -v`__
 103
 104     __ report_level_
 105
 106   - `--quiet, -q`__
 107
 108     __ report_level_
 109
 110   - `--halt=<level>`__
 111
 112     __ halt_level_
 113
 114   - `--strict`__
 115
 116     __ halt_level_
 117
 118   - `--exit-status=<level>`__
 119
 120     __ exit_status_level_
 121
 122   - `--debug`__
 123
 124     __ debug_
 125
 126   - `--no-debug`__
 127
 128     __ debug_
 129
 130   - `--warnings=<file>`__
 131
 132     __ warning_stream_
 133
 134   - `--traceback`__
 135
 136     __ traceback_
 137
 138   - `--no-traceback`__
 139
 140     __ traceback_
 141
 142   - `--input-encoding=<name[:handler]>, -i<name[:handler]>`__
 143
 144     __ input_encoding_
 145
 146   - `--input-encoding-error-handler=INPUT_ENCODING_ERROR_HANDLER`__
 147
 148     __ input_encoding_error_handler_
 149
 150   - `--output-encoding=<name[:handler]>, -o<name[:handler]>`__
 151
 152     __ output_encoding_
 153
 154   - `--output-encoding-error-handler=OUTPUT_ENCODING_ERROR_HANDLER`__
 155
 156     __ output_encoding_error_handler_
 157
 158   - `--error-encoding=<name[:handler]>, -e<name[:handler]>`__
 159
 160     __ error_encoding_
 161
 162   - `--error-encoding-error-handler=ERROR_ENCODING_ERROR_HANDLER`__
 163
 164     __ error_encoding_error_handler_
 165
 166   - `--language=<name>, -l<name>`__
 167
 168     __ language_code_
 169
 170   - `--record-dependencies=<file>`__
 171
 172     __ record_dependencies_
 173
 174   - `--config=<file>`__
 175
 176     __ config_
 177
 178   - --version, -V
 179
 180   - --help, -h
 181
 182 * to be completed ...
 183
 184 .. * reStructuredText Parser Options
 185
 186      - `--pep-references`__
 187
 188        __ pep_references_
 189
 190      - `--pep-base-url=<URL>`__
 191
 192        __ pep_base_url_
 193
 194      - `--rfc-references`__
 195
 196        __ rfc_references_
 197
 198      - `--rfc-base-url=<URL>`__
 199
 200        __ rfc_base_url_
 201
 202      - `--tab-width=<width>`__
 203
 204        __ tab_width_
 205
 206      - `--trim-footnote-reference-space`__
 207
 208        __ trim_footnote_reference_space_
 209
 210      - `--leave-footnote-reference-space`__
 211
 212        __ leave_footnote_reference_space_
 213
 214      - `--no-file-insertion`__
 215
 216        __ no_file_insertion_
 217
 218      - `--file-insertion-enabled`__
 219
 220        __ file_insertion_enabled_
 221
 222      - `--no-raw`__
 223
 224        __ no_raw_
 225
 226      - `--raw-enabled`__
 227
 228        __ raw_enabled_
 229
 230
 231    * Standalone Reader
 232
 233      - `--no-doc-title`__
 234
 235        __ no_doc_title_
 236
 237      - `--no-doc-info`__
 238
 239        __ no_doc_info_
 240
 241      - `--section-subtitles`__
 242
 243        __ section_subtitles_
 244
 245      - `--no-section-subtitles`__
 246
 247        __ no_section_subtitles_
 248
 249
 250    * HTML-Specific Options
 251
 252      - `--stylesheet=<URL>`__
 253
 254        __ stylesheet_
 255
 256      - `--stylesheet-path=<file>`__
 257
 258        __ stylesheet_path_
 259
 260      - `--embed-stylesheet`__
 261
 262        __ embed_stylesheet_
 263
 264      - `--link-stylesheet`__
 265
 266        __ link_stylesheet_
 267
 268      - `--initial-header-level=<level>`__
 269
 270        __ initial_header_level_
 271
 272      - `--field-name-limit=<level>`__
 273
 274        __ field_name_limit_
 275
 276      - `--option-limit=<level>`__
 277
 278        __ option_limit_
 279
 280      - `--footnote-references=<format>`__
 281
 282        __ footnote_references_
 283
 284      - `--attribution=<format>`__
 285
 286        __ attribution_
 287
 288      - `--compact-lists`__
 289
 290        __ compact_lists_
 291
 292      - `--no-compact-lists`__
 293
 294        __ no_compact_lists_
 295
 296      - `--compact-field-lists`__
 297
 298        __ compact_field_lists_
 299
 300      - `--no-compact-field-lists`__
 301
 302        __ no_compact_field_lists_
 303
 304      - `--no-xml-declaration`__
 305
 306        __ no_xml_declaration_
 307
 308      - `--cloak-email-addresses`__
 309
 310        __ cloak_email_addresses_
 311
 312
 313 -------------------
 314 Configuration Files
 315 -------------------
 316
 317 Configuration files are used for persistent customization; they can be
 318 set once and take effect every time you use a front-end tool.
 319 Configuration file settings override the built-in defaults, and
 320 command-line options override all.
 321
 322 By default, Docutils checks the following places for configuration
 323 files, in the following order:
 324
 325 1. ``/etc/docutils.conf``: This is a system-wide configuration file,
 326    applicable to all Docutils processing on the system.
 327
 328 2. ``./docutils.conf``: This is a project-specific configuration file,
 329    located in the current directory.  The Docutils front end has to be
 330    executed from the directory containing this configuration file for
 331    it to take effect (note that this may have nothing to do with the
 332    location of the source files).  Settings in the project-specific
 333    configuration file will override corresponding settings in the
 334    system-wide file.
 335
 336 3. ``~/.docutils``: This is a user-specific configuration file,
 337    located in the user's home directory.  Settings in this file will
 338    override corresponding settings in both the system-wide and
 339    project-specific configuration files.
 340
 341 If more than one configuration file is found, all will be read but
 342 later entries will override earlier ones.  For example, a "stylesheet"
 343 entry in a user-specific configuration file will override a
 344 "stylesheet" entry in the system-wide file.
 345
 346 The default implicit config file paths can be overridden by the
 347 ``DOCUTILSCONFIG`` environment variable.  ``DOCUTILSCONFIG`` should
 348 contain a colon-separated (semicolon-separated on Windows) sequence of
 349 config file paths to search for; leave it empty to disable implicit
 350 config files altogether.  Tilde-expansion is performed on paths.
 351 Paths are interpreted relative to the current working directory.
 352 Empty path items are ignored.
 353
 354 In addition, a configuration file may be explicitly specified with the
 355 "--config" command-line option.  This configuration file is read after
 356 the three implicit ones listed above (or the ones defined by the
 357 ``DOCUTILSCONFIG`` environment variable), and its entries will have
 358 priority.
 359
 360
 361 -------------------------
 362 Configuration File Syntax
 363 -------------------------
 364
 365 Configuration files are UTF-8-encoded text files.  The
 366 ConfigParser.py_ module from Python_'s standard library is used to
 367 read them.  From its documentation:
 368
 369     The configuration file consists of sections, lead by a "[section]"
 370     header and followed by "name: value" entries, with continuations
 371     in the style of `RFC 822`_; "name=value" is also accepted.  Note
 372     that leading whitespace is removed from values.  ...  Lines
 373     beginning with "#" or ";" are ignored and may be used to provide
 374     comments.
 375
 376 .. Note:: No format string interpolation is done.
 377
 378 Configuration file entry names correspond to internal runtime
 379 settings.  Underscores ("_") and hyphens ("-") can be used
 380 interchangably in entry names; hyphens are automatically converted to
 381 underscores.
 382
 383 For on/off switch settings (booleans), the following values are
 384 recognized:
 385
 386 * On: "true", "yes", "on", "1"
 387 * Off: "false", "no", "off", "0", "" (no value)
 388
 389
 390 -------------------------------------
 391 Configuration File Sections & Entries
 392 -------------------------------------
 393
 394 Below are the Docutils runtime settings, listed by config file
 395 section.  Any setting may be specified in any section, but only
 396 settings from active sections will be used.  Sections correspond to
 397 Docutils components (module name or alias; section names are always in
 398 lowercase letters).  Each `Docutils application`_ uses a specific set
 399 of components; corresponding configuration file sections are applied
 400 when the application is used.  Configuration sections are applied in
 401 general-to-specific order, as follows:
 402
 403 1. `[general]`_
 404
 405 2. `[parsers]`_, parser dependencies, and the section specific to the
 406    Parser used ("[... parser]").  Currently, only `[restructuredtext
 407    parser]`_ is applicable.
 408
 409 3. `[readers]`_, reader dependencies, and the section specific to the
 410    Reader used ("[... reader]").  For example, `[pep reader]`_ depends
 411    on `[standalone reader]`_.
 412
 413 4. `[writers]`_, writer dependencies, and the section specific to the
 414    Writer used ("[... writer]").  For example, `[pep_html writer]`_
 415    depends on `[html4css1 writer]`_.
 416
 417 5. `[applications]`_, application dependencies, and the section
 418     specific to the Application (front-end tool) in use
 419     ("[... application]").
 420
 421 Since any setting may be specified in any section, this ordering
 422 allows component- or application-specific overrides of earlier
 423 settings.  For example, there may be Reader-specific overrides of
 424 general settings; Writer-specific overrides of Parser settings;
 425 Application-specific overrides of Writer settings; and so on.
 426
 427 If multiple configuration files are applicable, the process is
 428 completed (all sections are applied in the order given) for each one
 429 before going on to the next.  For example, a "[pep_html writer]
 430 stylesheet" setting in an earlier configuration file would be
 431 overridden by an "[html4css1 writer] stylesheet" setting in a later
 432 file.
 433
 434 Some knowledge of Python_ is assumed for some attributes.
 435
 436 .. _ConfigParser.py:
 437    http://www.python.org/doc/current/lib/module-ConfigParser.html
 438 .. _Python: http://www.python.org/
 439 .. _RFC 822: http://www.rfc-editor.org/rfc/rfc822.txt
 440 .. _Docutils application: tools.html
 441
 442
 443 [general]
 444 =========
 445
 446 Settings in the "[general]" section are always applied.
 447
 448 _`auto_id_prefix`
 449     Prefix prepended to all auto-generated IDs generated within the
 450     document, after id_prefix_.
 451
 452     Default: "id".  Options: ``--auto-id-prefix`` (hidden, intended
 453     mainly for programmatic use).
 454
 455 _`datestamp`
 456     Include a time/datestamp in the document footer.  Contains a
 457     format string for Python's ``time.strftime``.  See the `time
 458     module documentation`__.
 459
 460     Default: None.  Options: ``--date, -d, --time, -t,
 461     --no-datestamp``.
 462
 463     Configuration file entry examples::
 464
 465         # Equivalent to --date command-line option, results in
 466         # ISO 8601 extended format datestamp, e.g. "2001-12-21":
 467         datestamp: %Y-%m-%d
 468
 469         # Equivalent to --time command-line option, results in
 470         # date/timestamp like "2001-12-21 18:43 UTC":
 471         datestamp: %Y-%m-%d %H:%M UTC
 472
 473         # Disables datestamp; equivalent to --no-datestamp:
 474         datestamp:
 475
 476     __ http://www.python.org/doc/current/lib/module-time.html
 477
 478 _`debug`
 479     Report debug-level system messages.
 480
 481     Default: don't (None).  Options: ``--debug, --no-debug``.
 482
 483 _`dump_internals`
 484     At the end of processing, write all internal attributes of the
 485     document (``document.__dict__``) to stderr.
 486
 487     Default: don't (None).  Options: ``--dump-internals`` (hidden, for
 488     development use only).
 489
 490 _`dump_pseudo_xml`
 491     At the end of processing, write the pseudo-XML representation of
 492     the document to stderr.
 493
 494     Default: don't (None).  Options: ``--dump-pseudo-xml`` (hidden,
 495     for development use only).
 496
 497 _`dump_settings`
 498     At the end of processing, write all Docutils settings to stderr.
 499
 500     Default: don't (None).  Options: ``--dump-settings`` (hidden, for
 501     development use only).
 502
 503 _`dump_transforms`
 504     At the end of processing, write a list of all transforms applied
 505     to the document to stderr.
 506
 507     Default: don't (None).  Options: ``--dump-transforms`` (hidden,
 508     for development use only).
 509
 510 _`error_encoding`
 511     The text encoding for error output.
 512
 513     Default: "ascii".  Options: ``--error-encoding, -e``.
 514
 515 _`error_encoding_error_handler`
 516     The error handler for unencodable characters in error output.  See
 517     output_encoding_error_handler_ for acceptable values.
 518
 519     Default: "backslashreplace" for Python 2.3 and later; "replace"
 520     otherwise.  Options: ``--error-encoding-error-handler,
 521     --error-encoding, -e``.
 522
 523 _`exit_status_level`
 524     A system message level threshold; non-halting system messages at
 525     or above this level will produce a non-zero exit status at normal
 526     exit.  Exit status is the maximum system message level plus 10 (11
 527     for INFO, etc.).
 528
 529     Default: disabled (5).  Options: ``--exit-status``.
 530
 531 _`expose_internals`
 532     List of internal attribues to expose as external attributes (with
 533     "internal:" namespace prefix).  To specify multiple attributes in
 534     configuration files, use colons to separate names; on the command
 535     line, the option may be used more than once.
 536
 537     Default: don't (None).  Options: ``--expose-internal-attribute``
 538     (hidden, for development use only).
 539
 540 _`footnote_backlinks`
 541     Enable or disable backlinks from footnotes and citations to their
 542     references.
 543
 544     Default: enabled (1).  Options: ``--footnote-backlinks,
 545     --no-footnote-backlinks``.
 546
 547 _`generator`
 548     Include a "Generated by Docutils" credit and link in the document
 549     footer.
 550
 551     Default: off (None).  Options: ``--generator, -g,
 552     --no-generator``.
 553
 554 _`halt_level`
 555     The threshold at or above which system messages are converted to
 556     exceptions, halting execution immediately.  If `traceback`_ is
 557     set, the exception will propagate; otherwise, Docutils will exit.
 558
 559     Default: severe (4).  Options: ``--halt, --strict``.
 560
 561 _`id_prefix`
 562     Prefix prepended to all IDs generated within the document.  See
 563     also auto_id_prefix_.
 564
 565     Default: "" (empty).  Options: ``--id-prefix`` (hidden, intended
 566     mainly for programmatic use).
 567
 568 _`input_encoding`
 569     The text encoding for input.
 570
 571     Default: auto-detect (None).  Options: ``--input-encoding, -i``.
 572
 573 _`input_encoding_error_handler`
 574     The error handler for undecodable characters in the input.
 575     Acceptable values include:
 576
 577     strict
 578         Raise an exception in case of an encoding error.
 579     replace
 580         Replace malformed data with the official Unicode replacement
 581         character, U+FFFD.
 582     ignore
 583         Ignore malformed data and continue without further notice.
 584
 585     Acceptable values are the same as for the "error" parameter of
 586     Python's ``unicode`` function; other values may be defined in
 587     applications or in future versions of Python.
 588
 589     Default: "strict".  Options: ``--input-encoding-error-handler,
 590     --input-encoding, -i``.
 591
 592 _`language_code`
 593     `ISO 639`_ 2-letter language code (3-letter codes used only if no
 594     2-letter code exists).
 595
 596     Default: English ("en").  Options: ``--language, -l``.
 597
 598 _`output_encoding`
 599     The text encoding for output.
 600
 601     Default: "UTF-8".  Options: ``--output-encoding, -o``.
 602
 603 _`output_encoding_error_handler`
 604     The error handler for unencodable characters in the output.
 605     Acceptable values include:
 606
 607     strict
 608         Raise an exception in case of an encoding error.
 609     replace
 610         Replace malformed data with a suitable replacement marker,
 611         such as "?".
 612     ignore
 613         Ignore malformed data and continue without further notice.
 614     xmlcharrefreplace
 615         Replace with the appropriate XML character reference, such as
 616         "``&#8224;``".
 617     backslashreplace
 618         (Python 2.3+)  Replace with backslashed escape sequences, such
 619         as "``\u2020``".
 620
 621     Acceptable values are the same as for the "error" parameter of
 622     Python's ``encode`` string method; other values may be defined in
 623     applications or in future versions of Python.
 624
 625     Default: "strict".  Options: ``--output-encoding-error-handler,
 626     --output-encoding, -o``.
 627
 628 _`record_dependencies`
 629     Path to a file where Docutils will write a list of files that the
 630     input and output depend on [#dependencies]_, e.g. due to file
 631     inclusion. [#pwd]_ The format is one filename per line.  This
 632     option is particularly useful in conjunction with programs like
 633     ``make``.
 634
 635     Set to ``-`` in order to write dependencies to stdout.
 636
 637     Default: None.  Option: ``--record-dependencies``.
 638
 639 _`report_level`
 640     Verbosity threshold at or above which system messages are
 641     reported.
 642
 643     Default: warning (2).  Options: ``--report, -r, --verbose, -v,
 644     --quiet, -q``.
 645
 646 _`sectnum_xform`
 647     Enable or disable the section numbering transform
 648     (docutils.transforms.parts.SectNum).
 649
 650     Default: enabled (1).  Options: ``--section-numbering``,
 651     ``--no-section-numbering``.
 652
 653 _`source_link`
 654     Include a "View document source" link in the document footer.  URL
 655     will be relative to the destination.
 656
 657     Default: don't (None).  Options: ``--source-link, -s,
 658     --no-source-link``.
 659
 660 _`source_url`
 661     An explicit URL for a "View document source" link, used verbatim.
 662
 663     Default: compute if source_link (None).  Options: ``--source-url,
 664     --no-source-link``.
 665
 666 _`strict_visitor`
 667     When processing a document tree with the Visitor pattern, raise an
 668     error if a writer does not support a node type listed as optional.
 669     For transitional development use.
 670
 671     Default: disabled (None).  Option: ``--strict-visitor`` (hidden,
 672     for development use only).
 673
 674 _`strip_comments`
 675     Enable the removal of comment elements from the document tree.
 676
 677     Default: disabled (None).  Options: ``--strip-comment``,
 678     ``--leave-comments``.
 679
 680 _`title`
 681     The document title as metadata, which does not become part of the
 682     document body.  It overrides a document-supplied title.  For
 683     example, in HTML output the metadata document title appears in the
 684     title bar of the browser window.
 685
 686     Default: none.  Option: ``--title``.
 687
 688 _`toc_backlinks`
 689     Enable backlinks from section titles to table of contents entries
 690     ("entry"), to the top of the TOC ("top"), or disable ("none").
 691
 692     Default: "entry".  Options: ``--toc-entry-backlinks,
 693     --toc-top-backlinks, --no-toc-backlinks``.
 694
 695 _`traceback`
 696     Enable Python tracebacks when halt-level system messages and other
 697     exceptions occur.  Useful for debugging, and essential for issue
 698     reports.  Exceptions are allowed to propagate, instead of being
 699     caught and reported (in a user-friendly way) by Docutils.
 700
 701     Default: disabled (None) unless Docutils is run programmatically
 702     using the `Publisher Interface`_.  Options: ``--traceback,
 703     --no-traceback``.
 704
 705     .. _Publisher Interface: ../api/publisher.html
 706
 707 _`warning_stream`
 708     Path to a file for the output of system messages (warnings)
 709     [#pwd]_.
 710
 711     Default: stderr (None).  Options: ``--warnings``.
 712
 713
 714 [parsers]
 715 ---------
 716
 717 Docutils currently supports only one parser, for reStructuredText.
 718
 719
 720 [restructuredtext parser]
 721 `````````````````````````
 722
 723 _`file_insertion_enabled`
 724     Enable or disable directives that insert the contents of external
 725     files, such as the "include_" & "raw_".  A "warning" system
 726     message (including the directive text) is inserted instead.  (See
 727     also raw_enabled_ for another security-relevant setting.)
 728
 729     Default: enabled (1).  Options: ``--file-insertion-enabled,
 730     --no-file-insertion``.
 731
 732     .. _include: ../ref/rst/directives.html#include
 733     .. _raw: ../ref/rst/directives.html#raw
 734
 735 _`pep_references`
 736     Recognize and link to standalone PEP references (like "PEP 258").
 737
 738     Default: disabled (None); enabled (1) in PEP Reader.  Options:
 739     ``--pep-references``.
 740
 741 _`pep_base_url`
 742     Base URL for PEP references.
 743
 744     Default: "http://www.python.org/peps/".  Option:
 745     ``--pep-base-url``.
 746
 747 _`pep_file_url_template`
 748     Template for PEP file part of URL, interpolated with the PEP
 749     number and appended to pep_base_url_.
 750
 751     Default: "pep-%04d".  Option: ``--pep-file-url``.
 752
 753 _`raw_enabled`
 754     Enable or disable the "raw_" directive.  A "warning" system
 755     message (including the directive text) is inserted instead.  (See
 756     also file_insertion_enabled_ for another security-relevant
 757     setting.)
 758
 759     Default: enabled (1).  Options: ``--raw-enabled, --no-raw``.
 760
 761 _`rfc_references`
 762     Recognize and link to standalone RFC references (like "RFC 822").
 763
 764     Default: disabled (None); enabled (1) in PEP Reader.  Options:
 765     ``--rfc-references``.
 766
 767 _`rfc_base_url`
 768     Base URL for RFC references.
 769
 770     Default: "http://www.faqs.org/rfcs/".  Option: ``--rfc-base-url``.
 771
 772 _`tab_width`
 773     Number of spaces for hard tab expansion.
 774
 775     Default: 8.  Options: ``--tab-width``.
 776
 777 _`trim_footnote_reference_space`
 778     Remove spaces before footnote references.
 779
 780     Default: don't (None); may be overriden by a writer-specific
 781     footnote_references__ default though.  Options:
 782     ``--trim-footnote-reference-space,
 783     --leave-footnote-reference-space``.
 784
 785 __ `footnote_references [latex2e writer]`_
 786
 787
 788 [readers]
 789 ---------
 790
 791
 792 [standalone reader]
 793 ```````````````````
 794
 795 _`docinfo_xform`
 796     Enable or disable the bibliographic field list transform
 797     (docutils.transforms.frontmatter.DocInfo).
 798
 799     Default: enabled (1).  Options: ``--no-doc-info``.
 800
 801 _`doctitle_xform`
 802     Enable or disable the promotion of a lone top-level section title
 803     to document title (and subsequent section title to document
 804     subtitle promotion; docutils.transforms.frontmatter.DocTitle).
 805
 806     Default: enabled (1).  Options: ``--no-doc-title``.
 807
 808 _`sectsubtitle_xform`
 809
 810     Enable or disable the promotion of the title of a lone subsection
 811     to a subtitle (docutils.transforms.frontmatter.SectSubTitle).
 812
 813     Default: disabled (0).  Options: ``--section-subtitles,
 814     --no-section-subtitles``.
 815
 816
 817 [pep reader]
 818 ````````````
 819
 820 The `pep_references`_ and `rfc_references`_ settings
 821 (`[restructuredtext parser]`_) are set on by default.
 822
 823
 824 [python reader]
 825 ```````````````
 826
 827 Under construction.
 828
 829
 830 [writers]
 831 ---------
 832
 833 [docutils_xml writer]
 834 `````````````````````
 835
 836 _`doctype_declaration`
 837     Generate XML with a DOCTYPE declaration.
 838
 839     Default: do (1).  Options: ``--no-doctype``.
 840
 841 _`indents`
 842     Generate XML with indents and newlines.
 843
 844     Default: don't (None).  Options: ``--indents``.
 845
 846 _`newlines`
 847     Generate XML with newlines before and after tags.
 848
 849     Default: don't (None).  Options: ``--newlines``.
 850
 851 .. _xml_declaration [docutils_xml writer]:
 852
 853 xml_declaration
 854     Generate XML with an XML declaration.  Also defined for the
 855     `HTML Writer`__.
 856
 857     .. Caution:: The XML declaration carries text encoding
 858        information, without which standard tools may be unable to read
 859        the generated XML.
 860
 861     Default: do (1).  Options: ``--no-xml-declaration``.
 862
 863     __ `xml_declaration [html4css1 writer]`_
 864
 865
 866 [html4css1 writer]
 867 ``````````````````
 868
 869 .. _attribution [html4css1 writer]:
 870
 871 attribution
 872     Format for block quote attributions: one of "dash" (em-dash
 873     prefix), "parentheses"/"parens", or "none".  Also defined for the
 874     `LaTeX Writer`__.
 875
 876     Default: "dash".  Options: ``--attribution``.
 877
 878     __ `attribution [latex2e writer]`_
 879
 880 _`cloak_email_addresses`
 881     Scramble email addresses to confuse harvesters.  In the reference
 882     URI, the "@" will be replaced by %-escapes (as of RFC 1738).  In
 883     the visible text (link text) of an email reference, the "@" and
 884     all periods (".") will be surrounded by ``<span>`` tags.
 885     Furthermore, HTML entities are used to encode these characters in
 886     order to further complicate decoding the email address.  For
 887     example, "abc@example.org" will be output as::
 888
 889         <a class="reference" href="mailto:abc&#37;&#52;&#48;example&#46;org">
 890         abc<span>&#64;</span>example<span>&#46;</span>org</a>
 891
 892     .. Note:: While cloaking email addresses will have little to no
 893        impact on the rendering and usability of email links in most
 894        browsers, some browsers (e.g. the ``links`` browser) may decode
 895        cloaked email addresses incorrectly.
 896
 897     Default: don't cloak (None).  Option: ``--cloak-email-addresses``.
 898
 899 _`compact_lists`
 900     Remove extra vertical whitespace between items of bullet lists and
 901     enumerated lists, when list items are all "simple" (i.e., items
 902     each contain one paragraph and/or one "simple" sublist only).  The
 903     behaviour can be specified directly via "class" attributes (values
 904     "compact" and "open") in the document.
 905
 906     Default: enabled (1).  Options: ``--compact-lists,
 907     --no-compact-lists``.
 908
 909 _`compact_field_lists`
 910     Remove extra vertical whitespace between items of field lists that
 911     are "simple" (i.e., all field bodies each contain at most one
 912     paragraph).  The behaviour can be specified directly via "class"
 913     attributes (values "compact" and "open") in the document.
 914
 915     Default: enabled (1).  Options: ``--compact-field-lists,
 916     --no-compact-field-lists``.
 917
 918 _`embed_stylesheet`
 919     Embed the stylesheet in the output HTML file.  The stylesheet file
 920     must be accessible during processing.
 921
 922     Default: enabled.  Options: ``--embed-stylesheet,
 923     --link-stylesheet``.
 924
 925 _`field_name_limit`
 926     The maximum width (in characters) for one-column field names.
 927     Longer field names will span an entire row of the table used to
 928     render the field list.  0 indicates "no limit".  See also
 929     option_limit_.
 930
 931     Default: 14 characters.  Option: ``--field-name-limit``.
 932
 933 .. _footnote_references [html4css1 writer]:
 934
 935 footnote_references
 936     Format for footnote references, one of "superscript" or
 937     "brackets".  Also defined for the `LaTeX Writer`__.
 938
 939     Overrides [#override]_ trim_footnote_reference_space_, if
 940     applicable. [#footnote_space]_
 941
 942     Default: "brackets".  Option: ``--footnote-references``.
 943
 944     __ `footnote_references [latex2e writer]`_
 945
 946 _`initial_header_level`
 947     The initial level for header elements.  This does not affect the
 948     document title & subtitle; see doctitle_xform_.
 949
 950     Default: 1 (for "<h1>").  Option: ``--initial-header-level``.
 951
 952 _`option_limit`
 953     The maximum width (in characters) for options in option lists.
 954     Longer options will span an entire row of the table used to render
 955     the option list.  0 indicates "no limit".  See also
 956     field_name_limit_.
 957
 958     Default: 14 characters.  Option: ``--option-limit``.
 959
 960 .. _stylesheet [html4css1 writer]:
 961
 962 stylesheet
 963     CSS stylesheet URL, used verbatim.  Overrides the
 964     "stylesheet_path" setting [#override]_.  Pass an empty string to
 965     deactivate stylesheet inclusion.
 966
 967     Default: None.  Options: ``--stylesheet``.
 968
 969     (Setting also defined for the `LaTeX Writer`__.)
 970
 971     __ `stylesheet [latex2e writer]`_
 972
 973 .. _stylesheet_path [html4css1 writer]:
 974
 975 stylesheet_path
 976     Path to CSS stylesheet [#pwd]_.  Overrides the "stylesheet" URL
 977     setting [#override]_.  Path is adjusted relative to the output
 978     HTML file.  Also defined for the `LaTeX Writer`__.
 979
 980     Default: "html4css1.css" in the docutils/writers/html4css1/
 981     directory (installed automatically; for the exact machine-specific
 982     path, use the ``--help`` option).  Options: ``--stylesheet-path``.
 983
 984     __ `stylesheet_path [latex2e writer]`_
 985
 986 _`template`
 987     Path to template file, which must be encoded in UTF-8 [#pwd]_.
 988
 989     Default: "template.txt" in the docutils/writers/html4css1/
 990     directory (installed automatically; for the exact machine-specific
 991     path, use the ``--help`` option).  Options: ``--template``.
 992
 993 .. _xml_declaration [html4css1 writer]:
 994
 995 xml_declaration
 996     Generate XML with an XML declaration.  Also defined for the
 997     `Docutils XML Writer`__.
 998
 999     .. Caution:: The XML declaration carries text encoding
1000        information, without which standard tools may be unable to read
1001        the generated XML.
1002
1003     Default: do (1).  Options: ``--no-xml-declaration``.
1004
1005     __ `xml_declaration [docutils_xml writer]`_
1006
1007
1008 [pep_html writer]
1009 .................
1010
1011 The PEP/HTML Writer derives from the standard HTML Writer, and shares
1012 all settings defined in the `[html4css1 writer]`_ section.  The
1013 "[html4css1 writer]" section of configuration files is processed
1014 before the "[pep_html writer]" section.
1015
1016 _`no_random`
1017     Do not use a random banner image.  Mainly used to get predictable
1018     results when testing.
1019
1020     Default: random enabled (None).  Options: ``--no-random``
1021     (hidden).
1022
1023 _`pep_home`
1024     Home URL prefix for PEPs.
1025
1026     Default: current directory (".").  Options: ``--pep-home``.
1027
1028 _`python_home`
1029     Python's home URL.
1030
1031     Default: parent directory ("..").  Options: ``--python-home``.
1032
1033 The PEP/HTML Writer's default for the following settings differ from
1034 those of the standard HTML Writer:
1035
1036 * ``stylesheet_path``: The default is
1037   ``docutils/writers/pep_html/pep.css`` in the installation directory.
1038   For the exact machine-specific path, use the ``--help`` option.
1039
1040 * ``template``: The default is
1041   ``docutils/writers/pep_html/template.txt`` in the installation
1042   directory.  For the exact machine-specific path, use the ``--help``
1043   option.
1044
1045
1046 [s5_html writer]
1047 .................
1048
1049 The S5/HTML Writer derives from the standard HTML Writer, and shares
1050 all settings defined in the `[html4css1 writer]`_ section.  The
1051 "[html4css1 writer]" section of configuration files is processed
1052 before the "[s5_html writer]" section.
1053
1054 _`hidden_controls`
1055     Auto-hide the presentation controls in slideshow mode, or or keep
1056     them visible at all times.
1057
1058     Default: auto-hide (1).  Options: ``--hidden-controls``,
1059     ``--visible-controls``.
1060
1061 _`current_slide`
1062     Enable or disable the current slide indicator ("1/15").
1063
1064     Default: disabled (None).  Options: ``--current-slide``,
1065     ``--no-current-slide``.
1066
1067 _`overwrite_theme_files`
1068     Allow or prevent the overwriting of existing theme files in the
1069     ``ui/<theme>`` directory.  This has no effect if "theme_url_" is
1070     used.
1071
1072     Default: keep existing theme files (None).  Options:
1073     ``--keep-theme-files``, ``--overwrite-theme-files``.
1074
1075 _`theme`
1076     Name of an installed S5 theme, to be copied into a ``ui/<theme>``
1077     subdirectory, beside the destination file (output HTML).  Note
1078     that existing theme files will not be overwritten; the existing
1079     theme directory you must be deleted manually.  Overrides the
1080     "theme_url_" setting [#override]_.
1081
1082     Default: "default".  Option: ``--theme``.
1083
1084 _`theme_url`
1085     The URL of an S5 theme directory.  The destination file (output
1086     HTML) will link to this theme; nothing will be copied.  Overrides
1087     the "theme_" setting [#override]_.
1088
1089     Default: None.  Option: ``--theme-url``.
1090
1091 _`view_mode`
1092     The initial view mode, either "slideshow" or "outline".
1093
1094     Default: "slidewhow".  Option: ``--view-mode``.
1095
1096 The S5/HTML Writer's default for the following settings differ
1097 from those of the standard HTML Writer:
1098
1099 * ``compact_lists``: The default here is to disable compact lists.
1100
1101 * ``template``: The default is
1102   ``docutils/writers/s5_html/template.txt`` in the installation
1103   directory.  For the exact machine-specific path, use the ``--help``
1104   option.
1105
1106
1107 [latex2e writer]
1108 ````````````````
1109
1110 _`use_latex_toc`
1111     To get pagenumbers in the table of contents the table of contents
1112     must be generated by latex. Usually latex must be run twice to get
1113     numbers correct.
1114
1115     *Note:* LaTeX will number the sections, which might be a bug in
1116     this case.
1117
1118     Default: off.  Option: ``--use-latex-toc``.
1119
1120 .. XXX Missing: use_latex_docinfo
1121
1122 _`use_latex_footnotes`
1123     Use LaTeX-footnotes not a figure simulation. This might give no
1124     Hyperrefs on /to footnotes, but should be able to handle an
1125     unlimited number of footnotes.
1126
1127     Default: off.  Option: ``--use-latex-footnotes``.
1128
1129 _`hyperlink_color`
1130     Color of any hyperlinks embedded in text. Use "0" to disable
1131     coloring of links.
1132
1133     Default: "blue".  Option: ``--hyperlink-color``.
1134
1135 _`documentclass`
1136     Specify latex documentclass, *but* beaware that books have chapters
1137     articles not.
1138
1139     Default: "article".  Option: ``--documentclass``.
1140
1141 _`documentoptions`
1142     Specify document options.  Multiple options can be given, separated by
1143     commas.
1144
1145     Default: "10pt,a4paper".  Option: ``--documentoptions``.
1146
1147 .. _stylesheet [latex2e writer]:
1148
1149 stylesheet
1150     Specify a stylesheet file.  Overrides stylesheet_path
1151     [#override]_.  The file will be ``\input`` by latex in the
1152     document header.  Also defined for the `HTML Writer`__.
1153
1154     Default: no stylesheet ("").  Option: ``--stylesheet``.
1155
1156     __ `stylesheet [html4css1 writer]`_
1157
1158 .. _stylesheet_path [latex2e writer]:
1159
1160 stylesheet_path
1161     Path to stylesheet [#pwd]_.  Overrides "stylesheet" setting
1162     (``--stylesheet``) [#override]_.
1163
1164     Please note that you will have to run ``latex`` from the directory
1165     containing the output file; otherwise the stylesheet reference
1166     will be invalid.
1167
1168     This setting is also defined for the `HTML Writer`__.
1169
1170     Default: None.  Option: ``--stylesheet-path``.
1171
1172     __ `stylesheet_path [html4css1 writer]`_
1173
1174 .. XXX Missing: embed_stylesheet
1175
1176 .. _footnote_references [latex2e writer]:
1177
1178 footnote_references
1179     Format for footnote references: one of "superscript" or
1180     "brackets".  Also defined for the `HTML Writer`__.
1181
1182     Overrides [#override]_ trim_footnote_reference_space_, if
1183     applicable. [#footnote_space]_
1184
1185     Default: "superscript".  Option: ``--footnote-references``.
1186
1187     __ `footnote_references [html4css1 writer]`_
1188
1189 .. _attribution [latex2e writer]:
1190
1191 attribution
1192     Format for block quote attributions, the same as for the
1193     html-writer: one of "dash" (em-dash prefix),
1194     "parentheses"/"parens" or "none".  Also defined for the `HTML
1195     Writer`__.
1196
1197     Default: "dash".  Option: ``--attribution``.
1198
1199     __ `attribution [html4css1 writer]`_
1200
1201 _`compound_enumerators`
1202     Enable or disable compound enumerators for nested enumerated lists
1203     (e.g. "1.2.a.ii").
1204
1205     Default: disabled (None).  Options: ``--compound-enumerators``,
1206     ``--no-compound-enumerators``.
1207
1208 _`section_prefix_for_enumerators`
1209     Enable or disable section ("." subsection ...) prefixes for
1210     compound enumerators.  This has no effect unless
1211     `compound_enumerators`_ are enabled.
1212
1213     Default: disabled (None).  Options:
1214     ``--section-prefix-for-enumerators``,
1215     ``--no-section-prefix-for-enumerators``.
1216
1217 _`section_enumerator_separator`
1218     The separator between section number prefix and enumerator for
1219     compound enumerated lists (see `compound_enumerators`_).
1220
1221     Generally it isn't recommended to use both sub-sections and nested
1222     enumerated lists with compound enumerators.  This setting avoids
1223     ambiguity in the situation where a section "1" has a list item
1224     enumerated "1.1", and subsection "1.1" has list item "1".  With a
1225     separator of ".", these both would translate into a final compound
1226     enumerator of "1.1.1".  With a separator of "-", we get the
1227     unambiguous "1-1.1" and "1.1-1".
1228
1229     Default: "-".  Option: ``--section-enumerator-separator``.
1230
1231 _`table_style`
1232     Specify the drawing of separation lines.
1233
1234     - "standard" lines around and between cells.
1235     - "booktabs" a line above and below the table and one after the
1236       head.
1237     - "nolines".
1238
1239     Default: "standard".  Option: ``--table-style``.
1240
1241
1242 [pseudoxml writer]
1243 ``````````````````
1244
1245 No settings are defined for this Writer.
1246
1247
1248 [applications]
1249 --------------
1250
1251 [buildhtml application]
1252 ```````````````````````
1253
1254 _`prune`
1255     List of directories not to process.  To specify multiple
1256     directories in configuration files, use colon-separated paths; on
1257     the command line, the option may be used more than once.
1258
1259     Default: none ([]).  Options: ``--prune``.
1260
1261 _`recurse`
1262     Recursively scan subdirectories, or ignore subdirectories.
1263
1264     Default: recurse (1).  Options: ``--recurse, --local``.
1265
1266 _`silent`
1267     Work silently (no progress messages).  Independent of
1268     "report_level".
1269
1270     Default: show progress (None).  Options: ``--silent``.
1271
1272
1273 [docfactory application]
1274 ````````````````````````
1275
1276 (To be completed.)
1277
1278
1279 Other Settings
1280 ==============
1281
1282 Command-Line Only
1283 -----------------
1284
1285 These settings are only effective as command-line options; setting
1286 them in configuration files has no effect.
1287
1288 _`config`
1289     Path to a configuration file to read (if it exists) [#pwd]_.
1290     Settings may override defaults and earlier settings.  The config
1291     file is processed immediately.  Multiple ``--config`` options may
1292     be specified; each will be processed in turn.
1293
1294     Filesystem path settings contained within the config file will be
1295     interpreted relative to the config file's location (*not* relative
1296     to the current working directory).
1297
1298     Default: None.  Options: ``--config``.
1299
1300
1301 Internal Settings
1302 -----------------
1303
1304 These settings are for internal use only; setting them in
1305 configuration files has no effect, and there are no corresponding
1306 command-line options.
1307
1308 _`_config_files`
1309     List of paths of applied configuration files.
1310
1311     Default: None.  No command-line options.
1312
1313 _`_directories`
1314     (``buildhtml.py`` front end.)  List of paths to source
1315     directories, set from positional arguments.
1316
1317     Default: current working directory (None).  No command-line
1318     options.
1319
1320 _`_disable_config`
1321     Prevent standard configuration files from being read.  For
1322     programmatic use only.
1323
1324     Default: config files enabled (None).  No command-line options.
1325
1326 _`_destination`
1327     Path to output destination, set from positional arguments.
1328
1329     Default: stdout (None).  No command-line options.
1330
1331 _`_source`
1332     Path to input source, set from positional arguments.
1333
1334     Default: stdin (None).  No command-line options.
1335
1336
1337 .. _ISO 639: http://www.loc.gov/standards/iso639-2/englangn.html
1338
1339 .. [#pwd] Path relative to the working directory of the process at
1340    launch.
1341
1342 .. [#override] The overridden setting will automatically be set to
1343    ``None`` for command-line options and config file settings.  Client
1344    programs which specify defaults that override other settings must
1345    do the overriding explicitly, by assigning ``None`` to the other
1346    settings.
1347
1348 .. [#dependencies] Some notes on the dependency recorder:
1349
1350    * Images are only added to the dependency list if the
1351      reStructuredText parser extracted image dimensions from the file.
1352
1353    * Stylesheets are only added if they are embedded.
1354
1355    * For practical reasons, the output of the LaTeX writer is
1356      considered merely an *intermediate* processing stage.  The
1357      dependency recorder records all files the *rendered* file
1358      (e.g. in PDF or DVI format) depends on.  Thus, images and
1359      stylesheets are both unconditionally recorded as dependencies
1360      when using the LaTeX writer.
1361
1362 .. [#footnote_space] The footnote space is trimmed if the reference
1363    style is "superscript", and it is left if the reference style is
1364    "brackets".
1365
1366    The overriding only happens if the parser supports the
1367    trim_footnote_reference_space option.
1368
1369
1370 ------------------------------
1371 Old-Format Configuration Files
1372 ------------------------------
1373
1374 Formerly, Docutils configuration files contained a single "[options]"
1375 section only.  This was found to be inflexible, and in August 2003
1376 Docutils adopted the current component-based configuration file
1377 sections as described above.  Docutils will still recognize the old
1378 "[options]" section, but complains with a deprecation warning.
1379
1380 To convert existing config files, the easiest way is to change the
1381 section title: change "[options]" to "[general]".  Most settings
1382 haven't changed.  The only ones to watch out for are these:
1383
1384 =====================  =====================================
1385 Old-Format Setting     New Section & Setting
1386 =====================  =====================================
1387 pep_stylesheet         [pep_html writer] stylesheet
1388 pep_stylesheet_path    [pep_html writer] stylesheet_path
1389 pep_template           [pep_html writer] template
1390 =====================  =====================================