"SfR Fresh" - the SfR Freeware/Shareware Archive 
Member "docutils-0.5/docs/user/config.txt" of archive docutils-0.5.tar.gz:
As a special service "SfR Fresh" has tried to format the requested source page into HTML format using source code syntax highlighting with prefixed line numbers.
Alternatively you can here view or download the uninterpreted source code file.
That can be also achieved for any archive member file by clicking within an archive contents listing on the first character of the file(path) respectively on the according byte size field.
1 ========================
2 Docutils Configuration
3 ========================
4
5 :Author: David Goodger
6 :Contact: goodger@python.org
7 :Revision: $Revision: 5505 $
8 :Date: $Date: 2008-01-26 02:50:57 +0100 (Sam, 26 Jän 2008) $
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 "``†``".
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 .. WARNING:: Potentially dangerous; use with caution.
408
409 Default: disabled (None). Option: ``--strip-class``.
410
411 _`strip_comments`
412 Enable the removal of comment elements from the document tree.
413
414 Default: disabled (None). Options: ``--strip-comments``,
415 ``--leave-comments``.
416
417 _`strip_elements_with_classes`
418 List of "classes" attribute values; matching elements to be
419 removed from the document tree.
420
421 .. WARNING:: Potentially dangerous; use with caution.
422
423 Default: disabled (None). Option: ``--strip-element-with-class``.
424
425 _`title`
426 The document title as metadata, which does not become part of the
427 document body. It overrides a document-supplied title. For
428 example, in HTML output the metadata document title appears in the
429 title bar of the browser window.
430
431 Default: none. Option: ``--title``.
432
433 _`toc_backlinks`
434 Enable backlinks from section titles to table of contents entries
435 ("entry"), to the top of the TOC ("top"), or disable ("none").
436
437 Default: "entry". Options: ``--toc-entry-backlinks,
438 --toc-top-backlinks, --no-toc-backlinks``.
439
440 _`traceback`
441 Enable Python tracebacks when halt-level system messages and other
442 exceptions occur. Useful for debugging, and essential for issue
443 reports. Exceptions are allowed to propagate, instead of being
444 caught and reported (in a user-friendly way) by Docutils.
445
446 Default: disabled (None) unless Docutils is run programmatically
447 using the `Publisher Interface`_. Options: ``--traceback,
448 --no-traceback``.
449
450 .. _Publisher Interface: ../api/publisher.html
451
452 _`warning_stream`
453 Path to a file for the output of system messages (warnings)
454 [#pwd]_.
455
456 Default: stderr (None). Options: ``--warnings``.
457
458
459 [parsers]
460 ---------
461
462 Docutils currently supports only one parser, for reStructuredText.
463
464
465 [restructuredtext parser]
466 `````````````````````````
467
468 _`file_insertion_enabled`
469 Enable or disable directives that insert the contents of external
470 files, such as the "include_" & "raw_". A "warning" system
471 message (including the directive text) is inserted instead. (See
472 also raw_enabled_ for another security-relevant setting.)
473
474 Default: enabled (1). Options: ``--file-insertion-enabled,
475 --no-file-insertion``.
476
477 .. _include: ../ref/rst/directives.html#include
478 .. _raw: ../ref/rst/directives.html#raw
479
480 _`pep_references`
481 Recognize and link to standalone PEP references (like "PEP 258").
482
483 Default: disabled (None); enabled (1) in PEP Reader. Options:
484 ``--pep-references``.
485
486 _`pep_base_url`
487 Base URL for PEP references.
488
489 Default: "http://www.python.org/peps/". Option:
490 ``--pep-base-url``.
491
492 _`pep_file_url_template`
493 Template for PEP file part of URL, interpolated with the PEP
494 number and appended to pep_base_url_.
495
496 Default: "pep-%04d". Option: ``--pep-file-url``.
497
498 _`raw_enabled`
499 Enable or disable the "raw_" directive. A "warning" system
500 message (including the directive text) is inserted instead. (See
501 also file_insertion_enabled_ for another security-relevant
502 setting.)
503
504 Default: enabled (1). Options: ``--raw-enabled, --no-raw``.
505
506 _`rfc_references`
507 Recognize and link to standalone RFC references (like "RFC 822").
508
509 Default: disabled (None); enabled (1) in PEP Reader. Options:
510 ``--rfc-references``.
511
512 _`rfc_base_url`
513 Base URL for RFC references.
514
515 Default: "http://www.faqs.org/rfcs/". Option: ``--rfc-base-url``.
516
517 _`tab_width`
518 Number of spaces for hard tab expansion.
519
520 Default: 8. Options: ``--tab-width``.
521
522 _`trim_footnote_reference_space`
523 Remove spaces before footnote references.
524
525 Default: don't (None); may be overriden by a writer-specific
526 footnote_references__ default though. Options:
527 ``--trim-footnote-reference-space,
528 --leave-footnote-reference-space``.
529
530 __ `footnote_references [latex2e writer]`_
531
532
533 [readers]
534 ---------
535
536
537 [standalone reader]
538 ```````````````````
539
540 _`docinfo_xform`
541 Enable or disable the bibliographic field list transform
542 (docutils.transforms.frontmatter.DocInfo).
543
544 Default: enabled (1). Options: ``--no-doc-info``.
545
546 _`doctitle_xform`
547 Enable or disable the promotion of a lone top-level section title
548 to document title (and subsequent section title to document
549 subtitle promotion; docutils.transforms.frontmatter.DocTitle).
550
551 Default: enabled (1). Options: ``--no-doc-title``.
552
553 _`sectsubtitle_xform`
554
555 Enable or disable the promotion of the title of a lone subsection
556 to a subtitle (docutils.transforms.frontmatter.SectSubTitle).
557
558 Default: disabled (0). Options: ``--section-subtitles,
559 --no-section-subtitles``.
560
561
562 [pep reader]
563 ````````````
564
565 The `pep_references`_ and `rfc_references`_ settings
566 (`[restructuredtext parser]`_) are set on by default.
567
568
569 [python reader]
570 ```````````````
571
572 Under construction.
573
574
575 [writers]
576 ---------
577
578 [docutils_xml writer]
579 `````````````````````
580
581 _`doctype_declaration`
582 Generate XML with a DOCTYPE declaration.
583
584 Default: do (1). Options: ``--no-doctype``.
585
586 _`indents`
587 Generate XML with indents and newlines.
588
589 Default: don't (None). Options: ``--indents``.
590
591 _`newlines`
592 Generate XML with newlines before and after tags.
593
594 Default: don't (None). Options: ``--newlines``.
595
596 .. _xml_declaration [docutils_xml writer]:
597
598 xml_declaration
599 Generate XML with an XML declaration. Also defined for the
600 `HTML Writer`__.
601
602 .. Caution:: The XML declaration carries text encoding
603 information, without which standard tools may be unable to read
604 the generated XML.
605
606 Default: do (1). Options: ``--no-xml-declaration``.
607
608 __ `xml_declaration [html4css1 writer]`_
609
610
611 [html4css1 writer]
612 ``````````````````
613
614 .. _attribution [html4css1 writer]:
615
616 attribution
617 Format for block quote attributions: one of "dash" (em-dash
618 prefix), "parentheses"/"parens", or "none". Also defined for the
619 `LaTeX Writer`__.
620
621 Default: "dash". Options: ``--attribution``.
622
623 __ `attribution [latex2e writer]`_
624
625 _`cloak_email_addresses`
626 Scramble email addresses to confuse harvesters. In the reference
627 URI, the "@" will be replaced by %-escapes (as of RFC 1738). In
628 the visible text (link text) of an email reference, the "@" and
629 all periods (".") will be surrounded by ``<span>`` tags.
630 Furthermore, HTML entities are used to encode these characters in
631 order to further complicate decoding the email address. For
632 example, "abc@example.org" will be output as::
633
634 <a class="reference" href="mailto:abc%40example.org">
635 abc<span>@</span>example<span>.</span>org</a>
636
637 .. Note:: While cloaking email addresses will have little to no
638 impact on the rendering and usability of email links in most
639 browsers, some browsers (e.g. the ``links`` browser) may decode
640 cloaked email addresses incorrectly.
641
642 Default: don't cloak (None). Option: ``--cloak-email-addresses``.
643
644 _`compact_lists`
645 Remove extra vertical whitespace between items of bullet lists and
646 enumerated lists, when list items are all "simple" (i.e., items
647 each contain one paragraph and/or one "simple" sublist only). The
648 behaviour can be specified directly via "class" attributes (values
649 "compact" and "open") in the document.
650
651 Default: enabled (1). Options: ``--compact-lists,
652 --no-compact-lists``.
653
654 _`compact_field_lists`
655 Remove extra vertical whitespace between items of field lists that
656 are "simple" (i.e., all field bodies each contain at most one
657 paragraph). The behaviour can be specified directly via "class"
658 attributes (values "compact" and "open") in the document.
659
660 Default: enabled (1). Options: ``--compact-field-lists,
661 --no-compact-field-lists``.
662
663 _`embed_stylesheet`
664 Embed the stylesheet in the output HTML file. The stylesheet file
665 must be accessible during processing.
666
667 Default: enabled. Options: ``--embed-stylesheet,
668 --link-stylesheet``.
669
670 _`field_name_limit`
671 The maximum width (in characters) for one-column field names.
672 Longer field names will span an entire row of the table used to
673 render the field list. 0 indicates "no limit". See also
674 option_limit_.
675
676 Default: 14 characters. Option: ``--field-name-limit``.
677
678 .. _footnote_references [html4css1 writer]:
679
680 footnote_references
681 Format for footnote references, one of "superscript" or
682 "brackets". Also defined for the `LaTeX Writer`__.
683
684 Overrides [#override]_ trim_footnote_reference_space_, if
685 applicable. [#footnote_space]_
686
687 Default: "brackets". Option: ``--footnote-references``.
688
689 __ `footnote_references [latex2e writer]`_
690
691 _`initial_header_level`
692 The initial level for header elements. This does not affect the
693 document title & subtitle; see doctitle_xform_.
694
695 Default: 1 (for "<h1>"). Option: ``--initial-header-level``.
696
697 _`option_limit`
698 The maximum width (in characters) for options in option lists.
699 Longer options will span an entire row of the table used to render
700 the option list. 0 indicates "no limit". See also
701 field_name_limit_.
702
703 Default: 14 characters. Option: ``--option-limit``.
704
705 .. _stylesheet [html4css1 writer]:
706
707 stylesheet
708 CSS stylesheet URL, used verbatim. Overrides the
709 "stylesheet_path" setting [#override]_. Pass an empty string to
710 deactivate stylesheet inclusion.
711
712 Default: None. Options: ``--stylesheet``.
713
714 (Setting also defined for the `LaTeX Writer`__.)
715
716 __ `stylesheet [latex2e writer]`_
717
718 .. _stylesheet_path [html4css1 writer]:
719
720 stylesheet_path
721 Path to CSS stylesheet [#pwd]_. Overrides the "stylesheet" URL
722 setting [#override]_. Path is adjusted relative to the output
723 HTML file. Also defined for the `LaTeX Writer`__.
724
725 Default: "html4css1.css" in the docutils/writers/html4css1/
726 directory (installed automatically; for the exact machine-specific
727 path, use the ``--help`` option). Options: ``--stylesheet-path``.
728
729 __ `stylesheet_path [latex2e writer]`_
730
731 _`template`
732 Path to template file, which must be encoded in UTF-8 [#pwd]_.
733
734 Default: "template.txt" in the docutils/writers/html4css1/
735 directory (installed automatically; for the exact machine-specific
736 path, use the ``--help`` option). Options: ``--template``.
737
738 .. _xml_declaration [html4css1 writer]:
739
740 xml_declaration
741 Generate XML with an XML declaration. Also defined for the
742 `Docutils XML Writer`__.
743
744 .. Caution:: The XML declaration carries text encoding
745 information, without which standard tools may be unable to read
746 the generated XML.
747
748 Default: do (1). Options: ``--no-xml-declaration``.
749
750 __ `xml_declaration [docutils_xml writer]`_
751
752
753 [pep_html writer]
754 .................
755
756 The PEP/HTML Writer derives from the standard HTML Writer, and shares
757 all settings defined in the `[html4css1 writer]`_ section. The
758 "[html4css1 writer]" section of configuration files is processed
759 before the "[pep_html writer]" section.
760
761 _`no_random`
762 Do not use a random banner image. Mainly used to get predictable
763 results when testing.
764
765 Default: random enabled (None). Options: ``--no-random``
766 (hidden).
767
768 _`pep_home`
769 Home URL prefix for PEPs.
770
771 Default: current directory ("."). Options: ``--pep-home``.
772
773 _`python_home`
774 Python's home URL.
775
776 Default: parent directory (".."). Options: ``--python-home``.
777
778 The PEP/HTML Writer's default for the following settings differ from
779 those of the standard HTML Writer:
780
781 * ``stylesheet_path``: The default is
782 ``docutils/writers/pep_html/pep.css`` in the installation directory.
783 For the exact machine-specific path, use the ``--help`` option.
784
785 * ``template``: The default is
786 ``docutils/writers/pep_html/template.txt`` in the installation
787 directory. For the exact machine-specific path, use the ``--help``
788 option.
789
790
791 [s5_html writer]
792 .................
793
794 The S5/HTML Writer derives from the standard HTML Writer, and shares
795 all settings defined in the `[html4css1 writer]`_ section. The
796 "[html4css1 writer]" section of configuration files is processed
797 before the "[s5_html writer]" section.
798
799 _`hidden_controls`
800 Auto-hide the presentation controls in slideshow mode, or or keep
801 them visible at all times.
802
803 Default: auto-hide (1). Options: ``--hidden-controls``,
804 ``--visible-controls``.
805
806 _`current_slide`
807 Enable or disable the current slide indicator ("1/15").
808
809 Default: disabled (None). Options: ``--current-slide``,
810 ``--no-current-slide``.
811
812 _`overwrite_theme_files`
813 Allow or prevent the overwriting of existing theme files in the
814 ``ui/<theme>`` directory. This has no effect if "theme_url_" is
815 used.
816
817 Default: keep existing theme files (None). Options:
818 ``--keep-theme-files``, ``--overwrite-theme-files``.
819
820 _`theme`
821 Name of an installed S5 theme, to be copied into a ``ui/<theme>``
822 subdirectory, beside the destination file (output HTML). Note
823 that existing theme files will not be overwritten; the existing
824 theme directory you must be deleted manually. Overrides the
825 "theme_url_" setting [#override]_.
826
827 Default: "default". Option: ``--theme``.
828
829 _`theme_url`
830 The URL of an S5 theme directory. The destination file (output
831 HTML) will link to this theme; nothing will be copied. Overrides
832 the "theme_" setting [#override]_.
833
834 Default: None. Option: ``--theme-url``.
835
836 _`view_mode`
837 The initial view mode, either "slideshow" or "outline".
838
839 Default: "slidewhow". Option: ``--view-mode``.
840
841 The S5/HTML Writer's default for the following settings differ
842 from those of the standard HTML Writer:
843
844 * ``compact_lists``: The default here is to disable compact lists.
845
846 * ``template``: The default is
847 ``docutils/writers/s5_html/template.txt`` in the installation
848 directory. For the exact machine-specific path, use the ``--help``
849 option.
850
851
852 [latex2e writer]
853 ````````````````
854
855 _`use_latex_toc`
856 To get pagenumbers in the table of contents the table of contents
857 must be generated by latex. Usually latex must be run twice to get
858 numbers correct.
859
860 *Note:* LaTeX will number the sections, which might be a bug in
861 this case.
862
863 Default: off. Option: ``--use-latex-toc``.
864
865 .. XXX Missing: use_latex_docinfo
866
867 _`use_latex_footnotes`
868 Use LaTeX-footnotes not a figure simulation. This might give no
869 Hyperrefs on /to footnotes, but should be able to handle an
870 unlimited number of footnotes.
871
872 Default: off. Option: ``--use-latex-footnotes``.
873
874 _`hyperlink_color`
875 Color of any hyperlinks embedded in text. Use "0" to disable
876 coloring of links.
877
878 Default: "blue". Option: ``--hyperlink-color``.
879
880 _`documentclass`
881 Specify latex documentclass, *but* beaware that books have chapters
882 articles not.
883
884 Default: "article". Option: ``--documentclass``.
885
886 _`documentoptions`
887 Specify document options. Multiple options can be given, separated by
888 commas.
889
890 Default: "10pt,a4paper". Option: ``--documentoptions``.
891
892 .. _stylesheet [latex2e writer]:
893
894 stylesheet
895 Specify a stylesheet file. Overrides stylesheet_path
896 [#override]_. The file will be ``\input`` by latex in the
897 document header. Also defined for the `HTML Writer`__.
898
899 Default: no stylesheet (""). Option: ``--stylesheet``.
900
901 __ `stylesheet [html4css1 writer]`_
902
903 .. _stylesheet_path [latex2e writer]:
904
905 stylesheet_path
906 Path to stylesheet [#pwd]_. Overrides "stylesheet" setting
907 (``--stylesheet``) [#override]_.
908
909 Please note that you will have to run ``latex`` from the directory
910 containing the output file; otherwise the stylesheet reference
911 will be invalid.
912
913 This setting is also defined for the `HTML Writer`__.
914
915 Default: None. Option: ``--stylesheet-path``.
916
917 __ `stylesheet_path [html4css1 writer]`_
918
919 .. XXX Missing: embed_stylesheet
920
921 .. _footnote_references [latex2e writer]:
922
923 footnote_references
924 Format for footnote references: one of "superscript" or
925 "brackets". Also defined for the `HTML Writer`__.
926
927 Overrides [#override]_ trim_footnote_reference_space_, if
928 applicable. [#footnote_space]_
929
930 Default: "superscript". Option: ``--footnote-references``.
931
932 __ `footnote_references [html4css1 writer]`_
933
934 .. _attribution [latex2e writer]:
935
936 attribution
937 Format for block quote attributions, the same as for the
938 html-writer: one of "dash" (em-dash prefix),
939 "parentheses"/"parens" or "none". Also defined for the `HTML
940 Writer`__.
941
942 Default: "dash". Option: ``--attribution``.
943
944 __ `attribution [html4css1 writer]`_
945
946 _`compound_enumerators`
947 Enable or disable compound enumerators for nested enumerated lists
948 (e.g. "1.2.a.ii").
949
950 Default: disabled (None). Options: ``--compound-enumerators``,
951 ``--no-compound-enumerators``.
952
953 _`section_prefix_for_enumerators`
954 Enable or disable section ("." subsection ...) prefixes for
955 compound enumerators. This has no effect unless
956 `compound_enumerators`_ are enabled.
957
958 Default: disabled (None). Options:
959 ``--section-prefix-for-enumerators``,
960 ``--no-section-prefix-for-enumerators``.
961
962 _`section_enumerator_separator`
963 The separator between section number prefix and enumerator for
964 compound enumerated lists (see `compound_enumerators`_).
965
966 Generally it isn't recommended to use both sub-sections and nested
967 enumerated lists with compound enumerators. This setting avoids
968 ambiguity in the situation where a section "1" has a list item
969 enumerated "1.1", and subsection "1.1" has list item "1". With a
970 separator of ".", these both would translate into a final compound
971 enumerator of "1.1.1". With a separator of "-", we get the
972 unambiguous "1-1.1" and "1.1-1".
973
974 Default: "-". Option: ``--section-enumerator-separator``.
975
976 _`table_style`
977 Specify the drawing of separation lines.
978
979 - "standard" lines around and between cells.
980 - "booktabs" a line above and below the table and one after the
981 head.
982 - "nolines".
983
984 Default: "standard". Option: ``--table-style``.
985
986
987 [pseudoxml writer]
988 ``````````````````
989
990 No settings are defined for this Writer.
991
992
993 [applications]
994 --------------
995
996 [buildhtml application]
997 ```````````````````````
998
999 _`ignore`
1000 List of wildcard (shell globing) patterns to silently ignore. To
1001 specify multiple patterns in configuration files, use
1002 colon-separated patterns; on the command line, the option may be
1003 used more than once.
1004
1005 Default: ['.svn', 'CVS']. Options: ``--ignore``.
1006
1007 _`prune`
1008 List of directories not to process. To specify multiple
1009 directories in configuration files, use colon-separated paths; on
1010 the command line, the option may be used more than once.
1011
1012 Default: none ([]). Options: ``--prune``.
1013
1014 _`recurse`
1015 Recursively scan subdirectories, or ignore subdirectories.
1016
1017 Default: recurse (1). Options: ``--recurse, --local``.
1018
1019 _`silent`
1020 Work silently (no progress messages). Independent of
1021 "report_level".
1022
1023 Default: show progress (None). Options: ``--silent``.
1024
1025
1026 [docfactory application]
1027 ````````````````````````
1028
1029 (To be completed.)
1030
1031
1032 Other Settings
1033 ==============
1034
1035 Command-Line Only
1036 -----------------
1037
1038 These settings are only effective as command-line options; setting
1039 them in configuration files has no effect.
1040
1041 _`config`
1042 Path to a configuration file to read (if it exists) [#pwd]_.
1043 Settings may override defaults and earlier settings. The config
1044 file is processed immediately. Multiple ``--config`` options may
1045 be specified; each will be processed in turn.
1046
1047 Filesystem path settings contained within the config file will be
1048 interpreted relative to the config file's location (*not* relative
1049 to the current working directory).
1050
1051 Default: None. Options: ``--config``.
1052
1053
1054 Internal Settings
1055 -----------------
1056
1057 These settings are for internal use only; setting them in
1058 configuration files has no effect, and there are no corresponding
1059 command-line options.
1060
1061 _`_config_files`
1062 List of paths of applied configuration files.
1063
1064 Default: None. No command-line options.
1065
1066 _`_directories`
1067 (``buildhtml.py`` front end.) List of paths to source
1068 directories, set from positional arguments.
1069
1070 Default: current working directory (None). No command-line
1071 options.
1072
1073 _`_disable_config`
1074 Prevent standard configuration files from being read. For
1075 programmatic use only.
1076
1077 Default: config files enabled (None). No command-line options.
1078
1079 _`_destination`
1080 Path to output destination, set from positional arguments.
1081
1082 Default: stdout (None). No command-line options.
1083
1084 _`_source`
1085 Path to input source, set from positional arguments.
1086
1087 Default: stdin (None). No command-line options.
1088
1089
1090 .. _ISO 639: http://www.loc.gov/standards/iso639-2/englangn.html
1091
1092 .. [#pwd] Path relative to the working directory of the process at
1093 launch.
1094
1095 .. [#override] The overridden setting will automatically be set to
1096 ``None`` for command-line options and config file settings. Client
1097 programs which specify defaults that override other settings must
1098 do the overriding explicitly, by assigning ``None`` to the other
1099 settings.
1100
1101 .. [#dependencies] Some notes on the dependency recorder:
1102
1103 * Images are only added to the dependency list if the
1104 reStructuredText parser extracted image dimensions from the file.
1105
1106 * Stylesheets are only added if they are embedded.
1107
1108 * For practical reasons, the output of the LaTeX writer is
1109 considered merely an *intermediate* processing stage. The
1110 dependency recorder records all files the *rendered* file
1111 (e.g. in PDF or DVI format) depends on. Thus, images and
1112 stylesheets are both unconditionally recorded as dependencies
1113 when using the LaTeX writer.
1114
1115 .. [#footnote_space] The footnote space is trimmed if the reference
1116 style is "superscript", and it is left if the reference style is
1117 "brackets".
1118
1119 The overriding only happens if the parser supports the
1120 trim_footnote_reference_space option.
1121
1122
1123 ------------------------------
1124 Old-Format Configuration Files
1125 ------------------------------
1126
1127 Formerly, Docutils configuration files contained a single "[options]"
1128 section only. This was found to be inflexible, and in August 2003
1129 Docutils adopted the current component-based configuration file
1130 sections as described above. Docutils will still recognize the old
1131 "[options]" section, but complains with a deprecation warning.
1132
1133 To convert existing config files, the easiest way is to change the
1134 section title: change "[options]" to "[general]". Most settings
1135 haven't changed. The only ones to watch out for are these:
1136
1137 ===================== =====================================
1138 Old-Format Setting New Section & Setting
1139 ===================== =====================================
1140 pep_stylesheet [pep_html writer] stylesheet
1141 pep_stylesheet_path [pep_html writer] stylesheet_path
1142 pep_template [pep_html writer] template
1143 ===================== =====================================