Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[9538] trunk/docutils
|
From: <mi...@us...> - 2024-02-14 17:43:01
|
Revision: 9538
http://sourceforge.net/p/docutils/code/9538
Author: milde
Date: 2024-02-14 17:42:58 +0000 (Wed, 14 Feb 2024)
Log Message:
-----------
Documentation update.
Harmonize wording and markup in "Docutils Configuration" doc.
Use field-list for "Default" and "Option(s)" when they don't fit
on one line.
Fix broken links.
Small fixes in FAQ.
Modified Paths:
--------------
trunk/docutils/FAQ.txt
trunk/docutils/RELEASE-NOTES.txt
trunk/docutils/docs/user/config.txt
trunk/docutils/docs/user/tools.txt
trunk/docutils/docutils/writers/html5_polyglot/__init__.py
trunk/docutils/test/data/help/docutils.txt
Modified: trunk/docutils/FAQ.txt
===================================================================
--- trunk/docutils/FAQ.txt 2024-02-01 21:10:43 UTC (rev 9537)
+++ trunk/docutils/FAQ.txt 2024-02-14 17:42:58 UTC (rev 9538)
@@ -941,8 +941,8 @@
Unexpected results from ``rst2html``: H1, H1 instead of H1, H2. Why?
--------------------------------------------------------------------------
-This only regards output from the `html4css1`_ writer.
-The `html5 writer`_ uses H1, H2, ...
+This only regards output from the `html4css1`_ writer and is configurable
+via the initial_header_level_ setting.
.. class:: details
Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt 2024-02-01 21:10:43 UTC (rev 9537)
+++ trunk/docutils/RELEASE-NOTES.txt 2024-02-14 17:42:58 UTC (rev 9538)
@@ -82,6 +82,9 @@
- Change the default value for math_output_ to "MathML" in Docutils 0.22.
+ - Change the default value of the initial_header_level_ setting to None
+ (<h2> if there is a document title, else <h1>) in Docutils 1.0.
+
- Remove option ``--embed-images`` (obsoleted by "image_loading_")
in Docutils 2.0.
Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt 2024-02-01 21:10:43 UTC (rev 9537)
+++ trunk/docutils/docs/user/config.txt 2024-02-14 17:42:58 UTC (rev 9538)
@@ -12,15 +12,32 @@
.. sidebar:: Docutils Security for Web Applications
- For details about securing web applications, please see `Deploying
- Docutils Securely <../howto/security.html>`_.
+ For a discussion about securing web applications, please see
+ `Deploying Docutils Securely <../howto/security.html>`_.
.. contents::
+.. raw:: html
+ <style type="text/css"><!--
+ dl.field-list {--field-indent: 4.7em;}
+ --></style>
+
+
Introduction
============
+Settings priority
+-----------------
+
+Configuration file settings override the built-in defaults, and
+command-line options override all.
+Some settings override also an associated setting; [#override]_
+others append values from the various sources. [#append-values]_
+
+For the technicalities, see `Docutils Runtime Settings`_.
+
+
Configuration Files
-------------------
@@ -27,9 +44,6 @@
Configuration files are used for persistent customization;
they can be set once and take effect every time you use a component,
e.g., via a `front-end tool`_.
-Configuration file settings override the built-in defaults, and
-command-line options override all.
-For the technicalities, see `Docutils Runtime Settings`_.
By default, Docutils checks the following places for configuration
files, in the following order:
@@ -38,23 +52,21 @@
applicable to all Docutils processing on the system.
2. ``./docutils.conf``: This is a project-specific configuration file,
- located in the current directory. The Docutils front end has to be
- executed from the directory containing this configuration file for
- it to take effect (note that this may have nothing to do with the
- location of the source files). Settings in the project-specific
- configuration file will override corresponding settings in the
- system-wide file.
+ located in the current directory.
+ The Docutils front end has to be executed from the directory
+ containing this configuration file for it to take effect (note that
+ this may have nothing to do with the location of the source files).
3. ``~/.docutils``: This is a user-specific configuration file,
- located in the user's home directory. Settings in this file will
- override corresponding settings in both the system-wide and
- project-specific configuration files.
+ located in the user's home directory.
-If more than one configuration file is found, all will be read but
-later entries will override earlier ones. For example, a "stylesheet"
-entry in a user-specific configuration file will override a
-"stylesheet" entry in the system-wide file.
+If more than one configuration file is found, all will be read and
+**later entries** will **override earlier ones**. [#append-values]_
+For example, a "stylesheet" entry in a user-specific configuration file
+will override a "stylesheet" entry in the system-wide file.
+.. _DOCUTILSCONFIG:
+
The default implicit config file paths can be overridden by the
``DOCUTILSCONFIG`` environment variable. ``DOCUTILSCONFIG`` should
contain a colon-separated (semicolon-separated on Windows) sequence of
@@ -63,8 +75,10 @@
Paths are interpreted relative to the current working directory.
Empty path items are ignored.
-In addition, a configuration file may be explicitly specified with the
-``--config`` command-line option. This configuration file is read after
+.. |config| replace:: ``--config``
+
+In addition, configuration files may be explicitly specified with the
+|config|_ command-line option. These configuration files are read after
the three implicit ones listed above (or the ones defined by the
``DOCUTILSCONFIG`` environment variable), and its entries will have
priority.
@@ -73,9 +87,9 @@
Configuration File Syntax
-------------------------
-Configuration files are UTF-8-encoded text files. The
-ConfigParser.py_ module from Python_'s standard library is used to
-read them. From its documentation:
+Configuration files are UTF-8-encoded text files. The ConfigParser.py_
+module from Python_'s standard library is used to read them.
+From its documentation:
The configuration file consists of sections, lead by a "[section]"
header and followed by "name: value" entries, with continuations
@@ -86,43 +100,48 @@
.. Note:: No format string interpolation is done.
-* Configuration file **entry names** correspond to internal runtime
- settings. Underscores ("_") and hyphens ("-") can be used
- interchangeably in entry names; hyphens are automatically converted to
- underscores.
+The following conventions apply to Docutils configuration files:
-* For on/off switch settings (_`booleans`), the following values are
- recognized:
-
+* Configuration file **entry names** correspond to internal `runtime
+ settings`_. Underscores ("_") and hyphens ("-") can be used interchangeably
+ in entry names; hyphens are automatically converted to underscores.
+ Entries with non-applicable or misspelled entry names are silently ignored.
+
+ .. _boolean:
+
+* For **boolean** settings (switches), the following values are
+ recognized (case-independent):
+
.. class:: narrow
:on: "true", "yes", "on", "1"
:off: "false", "no", "off", "0", "" (no value)
-.. _list:
+.. _comma-separated:
-* **List values** are either comma- or colon-delimited:
+* **Lists** are specified either comma- or _`colon-separated`:
- comma-delimited:
+ *comma-separated*:
strip_classes_, strip_elements_with_classes_, smartquotes_locales_,
- stylesheet, stylesheet_dirs, stylesheet_path, legacy_class_functions_,
- use_bibtex_
-
+ stylesheet_, stylesheet_dirs_, stylesheet_path_, use_bibtex_
+
Whitespace around list values is stripped, so you can write, e.g., ::
-
+
strip-classes: ham,eggs,
strip-elements-with-classes: sugar, salt, flour
stylesheet: html4css1.css,
math.css,
- style with spaces.css
-
- colon-delimited:
- expose_internals_, ignore_, prune_
-
+ style sheet with spaces.css
+
+
+ *colon-separated*:
+ ignore_, prune_, expose_internals_
+
Whitespace around the delimiter is not stripped. Write, e.g., ::
-
- expose_internals: b:c:d
+ expose_internals: source:line
+
+
Example
~~~~~~~
@@ -154,19 +173,22 @@
Configuration File Sections & Entries
-------------------------------------
-Below are the Docutils runtime settings, listed by config file
-section.
+Below are the Docutils `runtime settings`_, listed by config file section.
+Sections correspond to Docutils components (module name
+or alias; section names are always in lowercase letters).
.. important:: Any setting may be specified in any section, but only
- settings from *active sections* will be used.
+ settings from "`active sections`_" will be used.
-Sections correspond to
-Docutils components (module name or alias; section names are always in
-lowercase letters). Each Docutils application_ uses a specific set
-of components; corresponding configuration file sections are applied
-when the application is used. Configuration sections are applied in
-general-to-specific order, as follows:
+.. _active sections:
+
+Each Docutils application_ uses a specific set of components;
+`corresponding configuration file sections`__ are "active" when the
+application is used.
+
+Configuration sections are applied in general-to-specific order:
+
1. `[general]`_
2. `[parsers]`_, parser dependencies, and the section specific to the
@@ -182,7 +204,7 @@
on `[html writers]`_ and `[html4css1 writer]`_.
5. `[applications]`_, application dependencies, and the section
- specific to the Application (front-end tool) in use
+ specific to the Application (`front-end tool`_) in use
("[... application]").
Since any setting may be specified in any section, this ordering
@@ -208,7 +230,9 @@
.. _Python: https://www.python.org/
.. _RFC 822: https://www.rfc-editor.org/rfc/rfc822.txt
.. _front-end tool:
+.. _front-end tools:
.. _application: tools.html
+__ ../api/runtime-settings.html#active-sections
[general]
@@ -227,8 +251,8 @@
A trailing "%" is replaced with the tag name (new in Docutils 0.16).
-| *Default*: "%" (changed in 0.18 from "id").
-| *Option*: ``--auto-id-prefix`` (hidden, intended mainly for programmatic use).
+:Default: "%" (changed in 0.18 from "id").
+:Option: ``--auto-id-prefix`` (hidden, intended mainly for programmatic use).
.. _identifier normalization:
../ref/rst/directives.html#identifier-normalization
@@ -240,9 +264,6 @@
Include a time/datestamp in the document footer. Contains a
format string for Python's `time.strftime()`__.
-| *Default*: None.
-| *Options*: ``--date, -d, --time, -t, --no-datestamp``.
-
Configuration file entry examples::
# Equivalent to --date command-line option, results in
@@ -256,6 +277,9 @@
# Disables datestamp; equivalent to --no-datestamp:
datestamp:
+:Default: None.
+:Options: ``--date``, ``-d``, ``--time``, ``-t``, ``--no-datestamp``.
+
__ https://docs.python.org/3/library/time.html#time.strftime
@@ -264,7 +288,7 @@
Report debug-level system messages.
-*Default*: don't (None). *Options*: ``--debug, --no-debug``.
+*Default*: None (disabled). *Options*: ``--debug``, ``--no-debug``.
dump_internals
@@ -273,7 +297,7 @@
At the end of processing, write all internal attributes of the
document (``document.__dict__``) to stderr.
-*Default*: don't (None).
+*Default*: None (disabled).
*Option*: ``--dump-internals`` (hidden, for development use only).
@@ -283,7 +307,7 @@
At the end of processing, write the pseudo-XML representation of
the document to stderr.
-*Default*: don't (None).
+*Default*: None (disabled).
*Option*: ``--dump-pseudo-xml`` (hidden, for development use only).
@@ -292,7 +316,7 @@
At the end of processing, write all Docutils settings to stderr.
-*Default*: don't (None).
+*Default*: None (disabled).
*Option*: ``--dump-settings`` (hidden, for development use only).
@@ -302,7 +326,7 @@
At the end of processing, write a list of all transforms applied
to the document to stderr.
-*Default*: don't (None).
+*Default*: None (disabled).
*Option*: ``--dump-transforms`` (hidden, for development use only).
@@ -311,9 +335,8 @@
The text encoding for error output.
-| *Default*: The encoding reported by ``sys.stderr``, locale encoding,
- or "ascii".
-| *Options*: ``--error-encoding, -e``.
+:Default: The encoding reported by ``sys.stderr``, locale encoding, or "ascii".
+:Options: ``--error-encoding``, ``-e``.
error_encoding_error_handler
@@ -323,8 +346,8 @@
Acceptable values are the `Error Handlers`_ of Python's "codecs" module.
See also output_encoding_error_handler_.
-| *Default*: "backslashreplace"
-| *Options*: ``--error-encoding-error-handler, --error-encoding, -e``.
+:Default: "backslashreplace"
+:Options: ``--error-encoding-error-handler``, ``--error-encoding``, ``-e``.
exit_status_level
@@ -335,18 +358,17 @@
exit. Exit status is the maximum system message level plus 10 (11
for INFO, etc.).
-*Default*: disabled (5). *Option*: ``--exit-status``.
+*Default*: 5 (disabled). *Option*: ``--exit-status``.
expose_internals
----------------
-List_ of internal attributes to expose as external attributes (with
-"internal:" namespace prefix). To specify multiple attributes in
-configuration files, use colons to separate names; on the command
-line, the option may be used more than once.
+List of internal attributes (colon-separated_) to expose
+as external attributes (with "internal:" namespace prefix).
+Values are appended. [#append-values]_
-*Default*: don't (None).
+*Default*: ``[]``.
*Option*: ``--expose-internal-attribute`` (hidden, for development use only).
@@ -353,11 +375,10 @@
footnote_backlinks
------------------
-Enable or disable backlinks from footnotes_ and citations_ to their
-references.
+Enable backlinks from footnotes_ and citations_ to their references.
-| *Default*: enabled (True).
-| *Options*: ``--footnote-backlinks, --no-footnote-backlinks``.
+:Default: True.
+:Options: ``--footnote-backlinks``, ``--no-footnote-backlinks``.
generator
@@ -365,7 +386,8 @@
Include a "Generated by Docutils" credit and link in the document footer.
-*Default*: off (None). *Options*: ``--generator, -g, --no-generator``.
+:Default: None (disabled).
+:Options: ``--generator``, ``-g``, ``--no-generator``.
halt_level
@@ -377,7 +399,7 @@
See also report_level_.
-*Default*: severe (4). *Options*: ``--halt, --strict``.
+*Default*: 4 (severe). *Options*: ``--halt``, ``--strict``.
id_prefix
@@ -388,7 +410,7 @@
format, as it is not subjected to the `identifier normalization`_.
See also auto_id_prefix_.
-*Default*: "" (empty).
+*Default*: "" (no prefix).
*Option*: ``--id-prefix`` (hidden, intended mainly for programmatic use).
@@ -397,8 +419,8 @@
The text encoding for input (use the empty string to restore the default).
-*Default*: auto-detect_ (None). [#]_
-*Options*: ``--input-encoding, -i``. [#i-o-options]_
+*Default*: None (auto-detect_). [#]_
+*Options*: ``--input-encoding``, ``-i``. [#i-o-options]_
.. [#] The default will change to "utf-8" in Docutils 0.22.
.. [#i-o-options] The short options ``-i`` and ``-o`` `will be removed`__
@@ -451,7 +473,7 @@
"language-<language tag>" `class attribute`_, e.g.
``.. class:: language-el-polyton`` for a quote in polytonic Greek.
-*Default*: English ("en"). *Options*: ``--language, -l``.
+*Default*: "en" (English). *Options*: ``--language``, ``-l``.
.. _class attribute: ../ref/doctree.html#classes
@@ -459,9 +481,9 @@
output
------
-The path of the output destination. Use ``-`` for stdout.
+The path of the output destination. Use "-" for `stdout`.
-Obsoletes the ``<destination>`` positional argument
+Obsoletes the `\<destination>`_ positional argument
(cf. `Future changes`_ in the RELEASE-NOTES).
*Default*: None (stdout). *Option*: ``--output``.
@@ -482,7 +504,7 @@
This setting is ignored by the `ODF/ODT Writer`_ which always usues UTF-8.
-*Default*: "utf-8". *Options*: ``--output-encoding, -o``. [#i-o-options]_
+*Default*: "utf-8". *Options*: ``--output-encoding``, ``-o``. [#i-o-options]_
output_encoding_error_handler
@@ -521,13 +543,13 @@
stylesheets. [#dependencies]_ [#pwd]_ The format is one path per
line with forward slashes as separator, the encoding is UTF-8.
-Set it to "``-``" in order to write dependencies to stdout.
+Set it to "-" in order to write dependencies to stdout.
This option is particularly useful in conjunction with programs like
``make`` using ``Makefile`` rules like::
ham.html: ham.txt $(shell cat hamdeps.txt)
- rst2html --record-dependencies=hamdeps.txt ham.txt ham.html
+ rst2html --record-dependencies=hamdeps.txt ham.txt > ham.html
If the filesystem encoding differs from UTF-8, replace the ``cat``
command with a call to a converter, e.g.::
@@ -534,7 +556,7 @@
$(shell iconv -f utf-8 -t latin1 hamdeps.txt)
-*Default*: None. *Option*: ``--record-dependencies``.
+*Default*: None (disabled). *Option*: ``--record-dependencies``.
.. [#dependencies] Images are only added to the dependency list if they
are embedded into the output or the reStructuredText parser extracted
@@ -554,8 +576,8 @@
See also halt_level_.
-| *Default*: warning (2).
-| *Options*: ``--report, -r, --verbose, -v, --quiet, -q``.
+:Default: 2 (warning).
+:Options: ``--report``, ``-r``, ``--verbose``, ``-v``, ``--quiet``, ``-q``.
root_prefix
@@ -567,29 +589,27 @@
Also applied when a writer converts an image URI__ to a local filesystem
path in order to determine the image size or embed the image in the output.
-*Default*: "/" (no change).
-*Option*: ``--root-prefix``
+:Default: "/" (keep paths unchanged).
+:Option: ``--root-prefix``
New in Docutils 0.21.
__ ../ref/rst/directives.html#path
__ ../ref/rst/directives.html#uri
-.. _image: ../ref/rst/directives.html#image
-.. _figure: ../ref/rst/directives.html#figure
sectnum_xform
-------------
-Enable or disable automatic section numbering by Docutils
-(docutils.transforms.parts.SectNum) associated with the `sectnum
-directive`_.
+Enable automatic section numbering by Docutils
+(`docutils.transforms.parts.SectNum`) associated
+with the `sectnum directive`_.
If disabled, section numbers might be added to the output by the
renderer (e.g. by LaTeX or via a CSS style definition).
-| *Default*: enabled (True).
-| *Options*: ``--section-numbering``, ``--no-section-numbering``.
+:Default: True.
+:Options: ``--section-numbering``, ``--no-section-numbering``.
.. _sectnum directive: ../ref/rst/directives.html#sectnum
@@ -600,8 +620,8 @@
Include a "View document source" link in the document footer. URL will
be relative to the destination.
-*Default*: don't (None).
-*Options*: ``--source-link, -s, --no-source-link``.
+:Default: None (disabled).
+:Options: ``--source-link``, ``-s``, ``--no-source-link``.
source_url
@@ -609,8 +629,8 @@
An explicit URL for a "View document source" link, used verbatim.
-| *Default*: compute if source_link (None).
-| *Options*: ``--source-url, --no-source-link``.
+:Default: None (compute from source_link_).
+:Options: ``--source-url``, ``--no-source-link``.
strict_visitor
@@ -617,47 +637,49 @@
--------------
When processing a document tree with the Visitor pattern, raise an
-error if a writer does not support a node type listed as optional. For
-transitional development use.
+error if a writer does not support a node type listed as optional.
+For transitional development use.
-| *Default*: disabled (None).
-| *Option*: ``--strict-visitor`` (hidden, for development use only).
+:Default: None (disabled).
+:Option: ``--strict-visitor`` (hidden, for development use only).
strip_classes
-------------
-Comma-separated list_ of "classes" attribute values to remove from all
-elements in the document tree. The command line option may be used more
-than once.
+List of "classes" attribute values (comma-separated_) that will be
+removed from all elements in the document tree.
+Values are appended. [#append-values]_
+Allows eliding class values that interfere with, e.g, CSS rules from 3rd
+party tools/frameworks.
+
.. WARNING:: Some standard class values are required in order to achieve
the expected output rendering; use with caution.
-*Default*: disabled (None). *Option*: ``--strip-class``.
+*Default*: ``[]``. *Option*: ``--strip-class``.
strip_comments
--------------
-Enable the removal of comment elements from the document tree.
+Enable or disable the removal of comment elements from the document tree.
-*Default*: disabled (None).
-*Options*: ``--strip-comments``, ``--leave-comments``.
+:Default: None (disabled).
+:Options: ``--strip-comments``, ``--leave-comments``.
strip_elements_with_classes
---------------------------
-Comma-separated list_ of "classes" attribute values.
+List of "classes" attribute values (comma-separated_).
+Values are appended. [#append-values]_
Matching elements are removed from the document tree.
-The command line option may be used more than once.
.. WARNING:: Potentially dangerous: may lead to an invalid document tree
- and subsequent writer errors.
- Use with caution.
+ and subsequent writer errors. Use with caution.
-*Default*: disabled (None). *Option*: ``--strip-element-with-class``.
+*Default*: ``[]``. *Option*: ``--strip-element-with-class``.
title
@@ -671,7 +693,8 @@
This setting overrides a displayed `document title`_ and
is overridden by a `"title" directive`_.
-*Default*: none. *Option*: ``--title``.
+:Default: None (the displayed `document title`_).
+:Option: ``--title``.
.. _title attribute: ../ref/doctree.html#title-attribute
.. _document title: ../ref/rst/restructuredtext.html#document-title
@@ -682,24 +705,27 @@
-------------
Enable backlinks from section titles to table of contents entries
-("entry"), to the top of the TOC ("top"), or disable ("none").
+("entry"), to the top of the ToC ("top"), or disable ("none").
-| *Default*: "entry".
-| *Options*: ``--toc-entry-backlinks, --toc-top-backlinks, --no-toc-backlinks``.
+:Default: "entry".
+:Options: ``--toc-entry-backlinks``, ``--toc-top-backlinks``,
+ ``--no-toc-backlinks``.
traceback
---------
-Enable Python tracebacks when halt-level system messages and other
-exceptions occur. Useful for debugging, and essential for issue
+Enable or disable Python tracebacks when halt-level system messages and
+other exceptions occur. Useful for debugging, and essential for issue
reports. Exceptions are allowed to propagate, instead of being
caught and reported (in a user-friendly way) by Docutils.
-| *Default*: disabled (None) unless Docutils is run programmatically
- using the `Publisher Interface`_.
-| *Options*: ``--traceback, --no-traceback``.
+:Default: None (disabled). [#]_
+:Options: ``--traceback``, ``--no-traceback``.
+.. [#] unless Docutils is run programmatically
+ using the `Publisher Interface`_
+
.. _Publisher Interface: ../api/publisher.html
@@ -708,7 +734,7 @@
Path to a file for the output of system messages (warnings). [#pwd]_
-*Default*: stderr (None). *Option*: ``--warnings``.
+*Default*: None (stderr). *Option*: ``--warnings``.
[parsers]
@@ -719,14 +745,14 @@
file_insertion_enabled
----------------------
-Enable or disable directives inserting the contents of
+Enable directives inserting the contents of
external files, such as "include_" directive
or the "raw_" and "csv-table_" directives with option "url" or "file".
A "warning" system message (including the directive text) is inserted
instead. (See also raw_enabled_ for another security-relevant setting.)
-| *Default*: enabled (True).
-| *Options*: ``--file-insertion-enabled, --no-file-insertion``.
+:Default: True.
+:Options: ``--file-insertion-enabled``, ``--no-file-insertion``.
.. _include: ../ref/rst/directives.html#include
.. _raw: ../ref/rst/directives.html#raw
@@ -752,11 +778,11 @@
raw_enabled
-----------
-Enable or disable the "raw_" directive. A "warning" system message
+Enable the "raw_" directive. A "warning" system message
(including the directive text) is inserted instead. See also
file_insertion_enabled_ for another security-relevant setting.
-*Default*: enabled (True). *Options*: ``--raw-enabled, --no-raw``.
+*Default*: True. *Options*: ``--raw-enabled``, ``--no-raw``.
[restructuredtext parser]
@@ -775,16 +801,21 @@
When changing this setting to "True", inline markup characters in
URLs, names and formulas must be escaped to prevent recognition and
- possible errors. Examples::
+ possible errors.
- http://rST_for_all.html (hyperlinks to rST_ and for_)
- x_2, inline_markup (hyperlinks to x_ and inline_)
- 2*x (starts emphasised text)
- a|b (starts a substitution reference)
+ Examples:
+ .. class:: borderless
-| *Default*: disabled (False).
-| *Options*: ``--character-level-inline-markup, --word-level-inline-markup``.
+ =========================== ====================================
+ ``http://rST_for_all.html`` hyperlinks to ``rST_`` and ``for_``
+ ``x_2, inline_markup`` hyperlinks to ``x_`` and ``inline_``
+ ``2*x`` starts emphasised text
+ ``a|b`` starts a substitution reference
+ =========================== ====================================
+:Default: False.
+:Options: ``--character-level-inline-markup``, ``--word-level-inline-markup``.
+
New in Docutils 0.13.
pep_references
@@ -791,10 +822,9 @@
~~~~~~~~~~~~~~
Recognize and link to standalone PEP references (like "PEP 258").
-*Default*: disabled (None); enabled (True) in PEP Reader.
+:Default: None (disabled); True in PEP Reader.
+:Option: ``--pep-references``.
-*Option*: ``--pep-references``.
-
pep_base_url
~~~~~~~~~~~~
Base URL for PEP references.
@@ -813,10 +843,9 @@
~~~~~~~~~~~~~~
Recognize and link to standalone RFC references (like "RFC 822").
-*Default*: disabled (None); enabled (True) in PEP Reader.
+:Default: None (disabled); True in PEP Reader.
+:Option: ``--rfc-references``.
-*Option*: ``--rfc-references``.
-
rfc_base_url
~~~~~~~~~~~~
Base URL for RFC references.
@@ -828,7 +857,7 @@
Activate the SmartQuotes_ transform to
change straight quotation marks to typographic form. `Quote characters`_
are selected according to the language of the current block element (see
-language_code_, smartquotes_locales_, and the `pre-defined quote sets`__).
+language_code_, smartquotes_locales_, and the `pre-defined quote sets`_).
Also changes consecutive runs of hyphen-minus and full stops (``---``,
``--``, ``...``) to em-dash, en-dash, and ellipsis Unicode characters
@@ -836,42 +865,41 @@
Supported values:
-booleans_ (yes/no)
- Use smart quotes?
+:boolean_: Use smart quotes?
+:alt: Use alternative quote set (if defined for the language).
-alt (or "alternative")
- Use alternative quote set (if defined for the language).
+*Default*: None (disabled). *Option*: ``--smart-quotes``.
-*Default*: "no". *Option*: ``--smart-quotes``.
-
New in Docutils 0.10.
.. _SmartQuotes: smartquotes.html
-__ smartquotes.html#localization
+.. _pre-defined quote sets: smartquotes.html#localization
.. _quote characters:
https://en.wikipedia.org/wiki/Non-English_usage_of_quotation_marks
smartquotes_locales
~~~~~~~~~~~~~~~~~~~
-Typographical quotes used by the SmartQuotes_ transform.
-A comma-separated list_ with language tag and a string of four quotes
-(primary open/close, secondary open/close). [#]_
+List with language tag and a string of four typographical quote
+characters (primary open/close, secondary open/close) for use by
+the SmartQuotes_ transform.
+Values are appended. [#append-values]_
Example:
Ensure a correct leading apostrophe in ``'s Gravenhage`` in Dutch (at the
cost of incorrect opening single quotes) and set French quotes to double
- and single guillemets with inner padding::
+ and single guillemets with inner padding [#]_::
smartquote-locales: nl: „”’’,
fr: « : »:‹ : ›
-*Default*: None. *Option*: ``--smartquotes-locales``.
+:Default: SmartQuotes' `pre-defined quote sets`_.
+:Option: ``--smartquotes-locales``.
New in Docutils 0.14.
.. [#] If more than one character per quote is required (e.g. padding in
- French quotes), a colon-separated list may be used as value.
+ French quotes), a colon-separated list may be used for the quote set.
syntax_highlight
~~~~~~~~~~~~~~~~
@@ -880,14 +908,11 @@
Supported values:
-long
- Use hierarchy of long token type names.
-short
- Use short token type names. (For use with
- `Pygments-generated stylesheets`_.)
-none
- No code parsing. Use this to avoid the "Pygments not
- found" warning when Pygments is not installed.
+:long: Use hierarchy of long token type names.
+:short: Use short token type names.
+ (For use with `Pygments-generated stylesheets`_.)
+:none: No code parsing. Use this to avoid the "Pygments not
+ found" warning when Pygments is not installed.
*Default*: "long". *Option*: ``--syntax-highlight``.
@@ -910,12 +935,12 @@
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Remove spaces before `footnote references`_?
-| *Default*: None [#]_
-| *Options*: ``--trim-footnote-reference-space, --leave-footnote-reference-space``.
+:Default: None (depends on the `footnote_references setting`_ [#]_).
+:Options: ``--trim-footnote-reference-space``,
+ ``--leave-footnote-reference-space``.
-.. [#] Depending on the writer-specific `footnote_references setting`_.
- The footnote space is trimmed if the reference style is "superscript",
- and it is left if the reference style is "brackets".
+.. [#] The footnote space is trimmed if the reference style is "superscript",
+ and it is left if the reference style is "brackets".
.. _myst:
@@ -924,8 +949,8 @@
-------------
Provided by the 3rd party package `myst-docutils`_.
-See `MyST with Docutils`_ and its `Sphinx configuration options`_
-(some settings are not available with Docutils).
+See `MyST with Docutils`_ and MyST's `Sphinx configuration options`_
+(some settings are not applicable with Docutils).
.. _myst-docutils: https://pypi.org/project/myst-docutils/
.. _MyST with Docutils:
@@ -950,7 +975,10 @@
[recommonmark parser]
---------------------
-Provisional, depends on (deprecated) 3rd-party package recommonmark__.
+.. admonition:: Provisional
+
+ Depends on deprecated 3rd-party package recommonmark__.
+
Currently no configuration settings.
__ https://pypi.org/project/recommonmark/
@@ -964,26 +992,26 @@
docinfo_xform
~~~~~~~~~~~~~
-Enable or disable the `bibliographic field list`_ transform
+Enable the `bibliographic field list`_ transform
(docutils.transforms.frontmatter.DocInfo).
-*Default*: enabled (True). *Options*: ``--no-doc-info``.
+*Default*: True. *Options*: ``--no-doc-info``.
doctitle_xform
~~~~~~~~~~~~~~
-Enable or disable the promotion of a lone top-level section title
+Enable the promotion of a lone top-level section title
to `document title`_ (and subsequent section title to document
subtitle promotion; docutils.transforms.frontmatter.DocTitle).
-*Default*: enabled (True). *Options*: ``--no-doc-title``.
+*Default*: True. *Options*: ``--no-doc-title``.
sectsubtitle_xform
~~~~~~~~~~~~~~~~~~
-Enable or disable the promotion of the title of a lone subsection
+Enable the promotion of the title of a lone subsection
to a subtitle (docutils.transforms.frontmatter.SectSubTitle).
-| *Default*: disabled (False).
-| *Options*: ``--section-subtitles, --no-section-subtitles``.
+:Default: False.
+:Options: ``--section-subtitles``, ``--no-section-subtitles``.
[pep reader]
@@ -1009,19 +1037,19 @@
~~~~~~~~~~~~~~~~~~~
Generate XML with a DOCTYPE declaration.
-*Default*: do (True). *Options*: ``--no-doctype``.
+*Default*: True. *Options*: ``--no-doctype``.
indents
~~~~~~~
Generate XML with indents and newlines.
-*Default*: don't (None). *Options*: ``--indents``.
+*Default*: None (disabled). *Options*: ``--indents``.
newlines
~~~~~~~~
Generate XML with newlines before and after block-level tags.
-*Default*: don't (None). *Options*: ``--newlines``.
+*Default*: None (disabled). *Options*: ``--newlines``.
.. _xml_declaration [docutils_xml writer]:
@@ -1035,7 +1063,7 @@
If the encoding is not UTF-8 or ASCII and the XML declaration is
missing, standard tools may be unable to read the generated XML.
-*Default*: do (True). *Option*: ``--no-xml-declaration``.
+*Default*: True. *Option*: ``--no-xml-declaration``.
[html writers]
@@ -1070,28 +1098,30 @@
browsers, some browsers (e.g. the ``links`` browser) may decode
cloaked email addresses incorrectly.
-*Default*: don't cloak (None). *Option*: ``--cloak-email-addresses``.
+*Default*: None (disabled). *Option*: ``--cloak-email-addresses``.
compact_lists
~~~~~~~~~~~~~
Remove extra vertical whitespace between items of `bullet lists`_ and
`enumerated lists`_, when list items are all "simple" (i.e., items
-each contain one paragraph and/or one "simple" sub-list only). The
-behaviour can be specified directly via "class" attributes (values
-"compact" and "open") in the document.
+each contain one paragraph and/or one "simple" sub-list only).
+With the "html5" writer, the setting can be overridden for individual
+lists using the `"class" directive`_ (values "compact" and "open").
-| *Default*: enabled (True).
-| *Options*: ``--compact-lists, --no-compact-lists``.
+:Default: True.
+:Options: ``--compact-lists``, ``--no-compact-lists``.
+.. _"class" directive: ../ref/rst/directives.html#class
+
compact_field_lists
~~~~~~~~~~~~~~~~~~~
Remove extra vertical whitespace between items of `field lists`_ that
-are "simple" (i.e., all field bodies each contain at most one
-paragraph). The behaviour can be specified directly via "class"
-attributes (values "compact" and "open") in the document.
+are "simple" (i.e., all field bodies each contain at most one paragraph).
+With the "html5" writer, the setting can be overridden for individual
+lists using the `"class" directive`_ (values "compact" and "open").
-| *Default*: enabled (True).
-| *Options*: ``--compact-field-lists, --no-compact-field-lists``.
+:Default: True.
+:Options: ``--compact-field-lists``, ``--no-compact-field-lists``.
.. _embed_stylesheet [html writers]:
@@ -1103,8 +1133,8 @@
accessible during processing.
See also `embed_stylesheet [latex writers]`_.
-*Default*: enabled.
-*Options*: ``--embed-stylesheet, --link-stylesheet``.
+:Default: True.
+:Options: ``--embed-stylesheet``, ``--link-stylesheet``.
.. _footnote_references setting:
@@ -1115,8 +1145,8 @@
Format for `footnote references`_, one of "superscript" or "brackets".
See also `footnote_references [latex writers]`_.
-Overrides [#override]_ trim_footnote_reference_space_,
-if the parser supports this option.
+Overrides also trim_footnote_reference_space_,
+if the parser supports this option. [#override]_
*Default*: "brackets". *Option*: ``--footnote-references``.
@@ -1125,9 +1155,9 @@
The initial level for section header elements. This does not affect the
document title & subtitle; see doctitle_xform_.
-| *Default*: writer dependent
- (see `[html4css1 writer]`_, `[html5 writer]`_, `[pep_html writer]`_).
-| *Option*: ``--initial-header-level``.
+:Default: writer dependent
+ (see `[html4css1 writer]`_, `[html5 writer]`_, `[pep_html writer]`_).
+:Option: ``--initial-header-level``.
math_output
@@ -1163,19 +1193,16 @@
An external converter can be appended after whitespace, e.g.,
``--math-output="MathML blahtexml"``:
- :blahtexml_:
- Fast conversion, support for many symbols and environments, but no
- "align" (or other equation-aligning) environment. (C++)
+ .. class:: run-in narrow
- :LaTeXML_:
- Comprehensive macro support but **very** slow. (Perl)
+ :blahtexml_: Fast conversion, support for many symbols and environments,
+ but no "align" (or other equation-aligning) environment. (C++)
+ :LaTeXML_: Comprehensive macro support but **very** slow. (Perl)
+ :TtM_: No "matrix", "align" and "cases" environments.
+ Support may be removed.
+ :Pandoc_: Comprehensive macro support, fast, but a large install size.
+ (Haskell)
- :TtM_:
- No "matrix", "align" and "cases" environments. Support may be removed.
-
- :Pandoc_:
- Comprehensive macro support, fast, but a large install size. (Haskell)
-
__ https://developer.mozilla.org/en-US/docs/Web/MathML#browser_compatibility
__ ../ref/rst/mathematics.html
@@ -1229,14 +1256,14 @@
The failsafe fallback.
-*Default*: HTML math.css. *Option*: ``--math-output``.
+:Default: "HTML math.css". The default for the HTML5 writer will change
+ to "MathML" in Docutils 0.22.
+:Option: ``--math-output``.
New in Docutils 0.8.
-The default for the HTML5 writer will change to "MathML" in Docutils 0.22.
.. _math directive: ../ref/rst/directives.html#math
.. _MathJax: http://www.mathjax.org/
-.. _MathPlayer: http://www.dessci.com/en/products/mathplayer/
.. _MathML: https://www.w3.org/TR/MathML/
.. _blahtexml: http://gva.noekeon.org/blahtexml/
.. _LaTeXML: http://dlmf.nist.gov/LaTeXML/
@@ -1244,55 +1271,59 @@
.. _Pandoc: https://pandoc.org/
+.. _stylesheet:
.. _stylesheet [html writers]:
stylesheet
~~~~~~~~~~
-A comma-separated list of CSS stylesheet URLs, used verbatim.
-See also `stylesheet [latex writers]`_.
+List of CSS stylesheet URLs (comma-separated_). Used verbatim.
Overrides also stylesheet_path_. [#override]_
+See also `stylesheet [latex writers]`_.
-*Default*: None. *Option*: ``--stylesheet``.
+*Default*: ``[]``. *Option*: ``--stylesheet``.
+.. _stylesheet_dirs:
.. _stylesheet_dirs [html writers]:
stylesheet_dirs
~~~~~~~~~~~~~~~
-A comma-separated list of directories where stylesheets can be found.
+List of directories where stylesheets can be found (comma-separated_).
Used by the stylesheet_path_ setting when expanding relative path arguments.
+See also `stylesheet_dirs [latex writers]`_.
+
Note: This setting defines a "search path" (similar to the PATH variable for
executables). However, the term "path" is already used in the
stylesheet_path_ setting with the meaning of a file location.
+:Default: the working directory of the process at launch
+ and the directory with default stylesheet files
+ (writer and installation specific).
+ Use the ``--help`` option to get the exact value.
+:Option: ``--stylesheet-dirs``.
-| *Default*: the working directory of the process at launch and the directory
- with default stylesheet files (writer and installation specific).
- Use the ``--help`` option to get the exact value.
-| *Option*: ``--stylesheet-dirs``.
-
.. _stylesheet_path:
.. _stylesheet_path [html writers]:
stylesheet_path
~~~~~~~~~~~~~~~
-A comma-separated list of paths to CSS stylesheets. Relative paths are
+List of paths to CSS stylesheets (comma-separated_). Relative paths are
expanded if a matching file is found in the stylesheet_dirs__.
If embed_stylesheet__ is False, paths are rewritten relative to
-the output HTML file (if output_ or ``<destination>`` are specified)
-or the current work directory.
+the output_ file (if specified) or the current work directory.
+
See also `stylesheet_path [latex writers]`_.
-Also overrides "stylesheet". [#override]_
+Overrides also stylesheet_. [#override]_
Pass an empty string (to either "stylesheet" or "stylesheet_path") to
deactivate stylesheet inclusion.
-| *Default*: writer dependent
- (see `[html4css1 writer]`_, `[html5 writer]`_, `[pep_html writer]`_).
-| *Option*: ``--stylesheet-path``.
+:Default: writer dependent (see `[html4css1 writer]`_,
+ `[html5 writer]`_, `[pep_html writer]`_).
+:Option: ``--stylesheet-path``.
__ `embed_stylesheet [html writers]`_
__ `stylesheet_dirs [html writers]`_
@@ -1307,29 +1338,23 @@
The default CSS sylesheets define:
- borderless
- No borders around table cells.
+:borderless: no borders around table cells,
+:align-left, align-center, align-right: align table.
- align-left, align-center, align-right
- Align table as indicated.
-
The HTML5 stylesheets also define:
- booktabs
+:booktabs:
Only lines above and below the table and a thin line after the head.
+:captionbelow:
+ Place the table caption below the table (new in Docutils 0.17).
- captionbelow
- Place the table caption below the table
- (New in Docutils 0.17).
+In addition, the HTML writers process:
-In addition, the HTML writers support:
-
- colwidths-auto
+:colwidths-auto:
Delegate the determination of table column widths to the back-end
(leave out the ``<colgroup>`` column specification).
Overridden by the "widths" option of the `table directive`_.
-
- colwidths-grid
+:colwidths-grid:
Write column widths determined from the source to the HTML file.
Overridden by the "widths" option of the `table directive`_.
@@ -1342,12 +1367,12 @@
template
~~~~~~~~
-Path to template file, which must be encoded in UTF-8. [#pwd]_
+Path [#pwd]_ to template file, which must be encoded in UTF-8.
See also `template [latex writers]`_.
-| *Default*: "template.txt" in the writer's directory (installed automatically;
- for the exact machine-specific path, use the ``--help`` option).
-| *Option*: ``--template``.
+:Default: "template.txt" in the writer's directory (installed automatically)
+ For the exact machine-specific path, use the ``--help`` option).
+:Option: ``--template``.
.. _xml_declaration [html writers]:
@@ -1361,8 +1386,8 @@
encoding is not UTF-8 or ASCII and the XML declaration is missing,
standard XML tools may be unable to read the generated XHTML.
-| *Default*: writer dependent.
-| *Options*: ``--xml-declaration``, ``--no-xml-declaration``.
+:Default: writer dependent.
+:Options: ``--xml-declaration``, ``--no-xml-declaration``.
[html4css1 writer]
@@ -1375,15 +1400,12 @@
Writer Specific Defaults
""""""""""""""""""""""""
-`initial_header_level`_
- 1 (for "<h1>")
+.. class:: run-in narrow
-`stylesheet_path <stylesheet_path [html writers]_>`__:
- "html4css1.css"
+:`initial_header_level`_: 1 (for "<h1>").
+:`stylesheet_path <stylesheet_path [html writers]_>`__: "html4css1.css".
+:`xml_declaration <xml_declaration [html writers]_>`__: True.
-`xml_declaration <xml_declaration [html writers]_>`__
- enabled (True)
-
.. _HTML4/CSS1 Writer: html.html#html4css1
.. _XHTML 1 Transitional: https://www.w3.org/TR/xhtml1/
@@ -1394,7 +1416,7 @@
field names will span an entire row of the table used to render the field
list. 0 indicates "no limit". See also option_limit_.
-*Default*: 14 (i.e. 14 characters). *Option*: ``--field-name-limit``.
+*Default*: 14. *Option*: ``--field-name-limit``.
option_limit
@@ -1404,7 +1426,7 @@
the option list. 0 indicates "no limit".
See also field_name_limit_.
-*Default*: 14 (i.e. 14 characters). *Option*: ``--option-limit``.
+*Default*: 14. *Option*: ``--option-limit``.
[html5 writer]
@@ -1421,19 +1443,21 @@
Writer Specific Defaults
""""""""""""""""""""""""
-`initial_header_level`_
- 2 (for "<h2>", cf. "`Headings and outlines`__" in the HTML Standard)
+.. class:: run-in narrow
-`stylesheet_path <stylesheet_path [html writers]_>`__:
- "minimal.css, plain.css"
+:initial_header_level_: 2 (reserve <h1> for the `document title`_). [#]_
+:`stylesheet_path <stylesheet_path [html writers]_>`__:
+ "minimal.css, plain.css".
+:`xml_declaration <xml_declaration [html writers]_>`__: False.
+.. [#] Documents without (visible) document title may have <h2> as highest
+ heading level, which is not recommended but valid (cf. "`Headings and
+ outlines`__" in the HTML Standard). The default will change to None
+ (<h2> if there is a document title, else <h1>) in Docutils 1.0.
+
__ https://html.spec.whatwg.org/multipage/sections.html
#headings-and-outlines-2
-embed_images
-""""""""""""
-Deprecated. Obsoleted by image_loading_.
-
image_loading
"""""""""""""
Indicate at which point images should be loaded.
@@ -1440,17 +1464,15 @@
Overridden by the `"image" directive`_'s ``:loading:`` option.
Supported values:
- embed:
- Embed still images into the HTML document
- (ignored for videos).
- link:
- Refer to images in the HTML document (default).
- lazy:
- Refer to images. Additionally specify the
- `lazy loading attribute`_ to defer fetching the image.
-*Default*: "link". *Option*: ``--image-loading``.
+:embed: Embed still images into the HTML document
+ (ignored for videos).
+:link: Refer to images in the HTML document (default).
+:lazy: Refer to images. Additionally specify the
+ `lazy loading attribute`_ to defer fetching the image.
+*Default*: "link". *Option*: ``--image-loading``.
+
New in Docutils 0.18.
.. _"image" directive: ../ref/rst/directives.html#image
@@ -1463,8 +1485,8 @@
section headings. See ``responsive.css`` for an example how this can be
styled to show a symbol allowing users to copy the section's URL.
-| *Default*: disabled (False).
-| *Options*: ``--section-self-link``, ``--no-section-self-link``.
+:Default: False.
+:Options: ``--section-self-link``, ``--no-section-self-link``.
New in Docutils 0.18.
@@ -1477,35 +1499,32 @@
Writer Specific Defaults
""""""""""""""""""""""""
-`initial_header_level`_
- 1 (for "<h1>")
+.. class:: run-in narrow
-`stylesheet_path <stylesheet_path [html writers]_>`__:
- "pep.css"
+:`initial_header_level`_: 1 (for "<h1>").
+:`stylesheet_path <stylesheet_path [html writers]_>`__: "pep.css".
+:`template <template [html writers]_>`__:
+ ``docutils/writers/pep_html/template.txt`` in the installation directory.
+ For the exact machine-specific path, use the ``--help`` option.
-`template <template [html writers]_>`__:
- ``docutils/writers/pep_html/template.txt`` in the installation
- directory. For the exact machine-specific path, use the ``--help``
- option.
-
no_random
"""""""""
Do not use a random banner image. Mainly used to get predictable
results when testing.
-*Default*: random enabled (None). *Options*: ``--no-random`` (hidden).
+*Default*: None (use random banner). *Options*: ``--no-random`` (hidden).
pep_home
""""""""
Home URL prefix for PEPs.
-*Default*: current directory ("."). *Option*: ``--pep-home``.
+*Default*: "." (current directory). *Option*: ``--pep-home``.
python_home
"""""""""""
Python's home URL.
-*Default*: https://www.python.org. *Option*: ``--python-home``.
+*Default*: "https://www.python.org". *Option*: ``--python-home``.
[s5_html writer]
@@ -1516,13 +1535,12 @@
Writer Specific Defaults
""""""""""""""""""""""""
-compact_lists_:
- disable compact lists.
+.. class:: run-in narrow
-template__:
- ``docutils/writers/s5_html/template.txt`` in the installation
- directory. For the exact machine-specific path, use the ``--help``
- option.
+:compact_lists_: disable compact lists.
+:template__: ``docutils/writers/s5_html/template.txt`` in the
+ installation directory. For the exact machine-specific
+ path, use the ``--help`` option.
__ `template [html writers]`_
@@ -1529,18 +1547,18 @@
hidden_controls
"""""""""""""""
-Auto-hide the presentation controls in slideshow mode, or or keep
+Auto-hide the presentation controls in slideshow mode, or keep
them visible at all times.
-| *Default*: auto-hide (True).
-| *Options*: ``--hidden-controls``, ``--visible-controls``.
+:Default: True (auto-hide).
+:Options: ``--hidden-controls``, ``--visible-controls``.
current_slide
"""""""""""""
Enable or disable the current slide indicator ("1/15").
-| *Default*: disabled (None).
-| *Options*: ``--current-slide``, ``--no-current-slide``.
+:Default: None (disabled).
+:Options: ``--current-slide``, ``--no-current-slide``.
overwrite_theme_files
"""""""""""""""""""""
@@ -1548,8 +1566,8 @@
``ui/<theme>`` directory. This has no effect if "theme_url_" is
used.
-| *Default*: keep existing theme files (None).
-| *Options*: ``--keep-theme-files``, ``--overwrite-theme-files``.
+:Default: None (keep existing theme files).
+:Options: ``--keep-theme-files``, ``--overwrite-theme-files``.
theme
"""""
@@ -1557,7 +1575,7 @@
subdirectory, beside the destination file (output HTML). Note
that existing theme files will not be overwritten; the existing
theme directory must be deleted manually.
-Also overrides the "theme_url_" setting. [#override]_
+Overrides also theme_url_. [#override]_
*Default*: "default". *Option*: ``--theme``.
@@ -1564,8 +1582,8 @@
theme_url
"""""""""
The URL of an S5 theme directory. The destination file (output
-HTML) will link to this theme; nothing will be copied. Also overrides
-the "theme_" setting. [#override]_
+HTML) will link to this theme; nothing will be copied.
+Overrides also theme_. [#override]_
*Default*: None. *Option*: ``--theme-url``.
@@ -1590,15 +1608,19 @@
attribution
~~~~~~~~~~~
-See `attribution [html writers]`_.
+Format for `block quote`_ attributions: one of "dash" (em-dash
+prefix), "parentheses"/"parens", or "none".
+See also `attribution [html writers]`_.
+*Default*: "dash". *Option*: ``--attribution``.
+
compound_enumerators
~~~~~~~~~~~~~~~~~~~~
Enable or disable compound enumerators for nested `enumerated lists`_
(e.g. "1.2.a.ii").
-| *Default*: disabled (None).
-| *Options*: ``--compound-enumerators``, ``--no-compound-enumerators``.
+:Default: None (disabled).
+:Options: ``--compound-enumerators``, ``--no-compound-enumerators``.
documentclass
~~~~~~~~~~~~~
@@ -1619,9 +1641,9 @@
Use the Docutils-specific macros ``\DUfootnote`` and
``\DUfootnotetext`` for footnotes_.
-TODO: The alternative, "use_latex_footnotes" is not implemented yet.
+TODO: The alternative, "latex_footnotes" is not implemented yet.
-*Default*: on. *Option*: ``--docutils-footnotes``.
+*Default*: True. *Option*: ``--docutils-footnotes``.
.. _embed_stylesheet [latex writers]:
@@ -1634,7 +1656,8 @@
file is *not* searched in the `TeX input path`_).
See also `embed_stylesheet [html writers]`_.
-*Default*: off. *Options*: ``--embed-stylesheet, --link-stylesheet``.
+:Default: False (link to stylesheet).
+:Options: ``--embed-stylesheet``, ``--link-stylesheet``.
.. _footnote_references [latex writers]:
@@ -1644,8 +1667,8 @@
Format for `footnote references`_: one of "superscript" or "brackets".
See also `footnote_references [html writers]`_.
-Overrides [#override]_ trim_footnote_reference_space_,
-if the parser supports this option.
+Overrides also trim_footnote_reference_space_,
+if the parser supports this option. [#override]_
*Default*: "superscript". *Option*: ``--footnote-references``.
@@ -1660,12 +1683,16 @@
hyperlink_color
~~~~~~~~~~~~~~~
-Color of any hyperlinks embedded in text.
+Color of any hyperlinks embedded in text.
-* "0" or "false" disable coloring of links (links will be marked
- by red boxes that are not printed).
-* "black" results in “invisible“ links.
+Special values:
+.. class:: run-in narrow
+
+:"0" or "false": disables coloring of links
+ (links will be marked by red boxes that are not printed).
+:"black": results in “invisible“ links.
+
Set hyperref_options_ to "draft" to completely disable hyperlinking.
*Default*: "blue". *Option*: ``--hyperlink-color``.
@@ -1672,9 +1699,10 @@
hyperref_options
~~~~~~~~~~~~~~~~
-Options for the `hyperref TeX package`_. If hyperlink_color_ is
-not "false", the expansion of ::
+Options for the `hyperref TeX package`_.
+If hyperlink_color_ is not "false", the expansion of ::
+
'colorlinks=true,linkcolor=%s,urlcolor=%s' % (
hyperlink_color, hyperlink_color)
@@ -1691,8 +1719,8 @@
Can be used to load packages with options or (re-) define LaTeX
macros without writing a custom style file (new in Docutils 0.7).
-*Default*: writer dependent (see `[latex2e writer]`_, `[xetex writer]`_).
-*Option*: ``--latex-preamble``.
+:Default: writer dependent (see `[latex2e writer]`_, `[xetex writer]`_).
+:Option: ``--latex-preamble``.
legacy_class_functions
@@ -1702,10 +1730,10 @@
values are handled with wrappers and admonitions use the ``DUadmonition``
environment. See `Generating LaTeX with Docutils`__ for details.
-| *Default*: False (since Docutils 0.18).
-| *Options*: ``--legacy-class-functions``, ``--new-class-functions``.
+:Default: False (default changed in Docutils 0.18).
+:Options: ``--legacy-class-functions``, ``--new-class-functions``.
-New in Docutils 0.17.
+New in Docutils 0.17
__ latex.html#classes
@@ -1712,7 +1740,8 @@
legacy_column_widths
~~~~~~~~~~~~~~~~~~~~
-Use "legacy algorithm" or new algorithm to determine table column widths.
+Use "legacy algorithm" to determine table column widths (for backwards
+compatibility).
The new algorithm limits the table width to the text width or specified
table width and keeps the ratio of specified column widths.
@@ -1720,8 +1749,8 @@
Custom table and/or column widths can be set with the respective options
of the `table directive`_. See also `Generating LaTeX with Docutils`__.
-| *Default*: True (will change to False in Docutils 1.0).
-| *Options*: ``--legacy-column-widths``, ``--new-column-widths``.
+:Default: True (will change to False in Docutils 1.0).
+:Options: ``--legacy-column-widths``, ``--new-column-widths``.
New in Docutils 0.18.
@@ -1730,13 +1759,18 @@
literal_block_env
~~~~~~~~~~~~~~~~~
-When possible\ [#]_, use the specified environment for `literal blocks`_.
+Environment for `literal blocks`_. Used when the block does not contain
+inline elements. [#]_
-| *Default*: "" (quoting of whitespace and special chars).
-| *Option*: ``--literal-block-env``.
+The values "lstlisting", "listing", "verbatim", "Verbatim", and
+"verbatimtab" work out of the box; required LaTeX package are
+automatically loaded.
+:Default: "" (use "alltt" with quoting of whitespace and special chars).
+:Option: ``--literal-block-env``.
+
.. [#] A <literal-block> element originating from a `parsed literal`_ or
- code_ directive may contain inline elements. LaTeX verbatim
+ code_ directive may contain inline elements. LaTeX' verbatim-like
environments cannot be used in this case.
.. _parsed literal: ../ref/rst/directives.html#parsed-literal
@@ -1746,7 +1780,7 @@
~~~~~~~~~~~~~~~
Per default the LaTeX writer uses ``\hyperref`` for `hyperlink
references`_ to internal__ or implicit__ targets.
-Specify an alternative reference command, e.g., "ref" or "pageref"
+Specify an alternative reference command name, e.g., "ref" or "pageref"
to get the section number or the page number as reference text.
.. Caution::
@@ -1754,11 +1788,14 @@
* Experimental. Not sufficiently tested.
* Fails, e.g., with section numbering by Docutils (cf. sectnum_xform_)
or tables without caption.
- * Provisional: to be replaced by a dedicated
- `interpreted text role`_ for references (cf. TODO__).
-*Default*: "" (use "hyperref"). *Option*: ``--reference-label``.
+.. admonition:: Provisional
+ To be replaced by a dedicated `interpreted text role`_ for references
+ (cf. TODO__).
+
+*Default*: "" (use ``\hyperref``). *Option*: ``--reference-label``.
+
__ ../ref/rst/restructuredtext.html#internal-hyperlink-targets
__ ../ref/rst/restructuredtext.html#implicit-hyperlink-targets
__ ../dev/todo.html#object-numbering-and-object-references
@@ -1770,8 +1807,8 @@
The separator between section number prefix and enumerator for
compound enumerated lists (see `compound_enumerators`_).
-Generally it isn't recommended to use both sub-sections and nested
-enumerated lists with compound enumerators. This setting avoids
+Generally it isn't recommended to use both, numbered sub-sections and
+nested enumerated lists with compound enumerators. This setting avoids
ambiguity in the situation where a section "1" has a list item
enumerated "1.1", and subsection "1.1" has list item "1". With a
separator of ".", these both would translate into a final compound
@@ -1786,8 +1823,8 @@
compound enumerators. This has no effect unless
`compound_enumerators`_ are enabled.
-| *Default*: disabled (None).
-| *Options*: ``--section-prefix-for-enumerators``,
+:Default: None (disabled).
+:Options: ``--section-prefix-for-enumerators``,
``--no-section-prefix-for-enumerators``.
@@ -1795,25 +1832,21 @@
stylesheet
~~~~~~~~~~
-A comma-separated list_ of style files.
-Used without path adaption (cf. `stylesheet_path [latex writers]`_).
-Under Windows, path separators are normalized to forward slashes (``/``).
+List of style files (comma-separated_). Used verbatim
+(under Windows, path separators are normalized to forward slashes).
+Overrides also stylesheet_path__. [#override]_
See also `stylesheet [html writers]`_.
-Overrides also stylesheet_path__. [#override]_
-
If `embed_stylesheet`__ is False (default), the stylesheet files are
-referenced with ``\usepackage`` (extension ``.sty`` or no extension) or
-``\input`` (any other extension).
-
+referenced with ``\usepackage`` (values with extension ``.sty`` or no
+extension) or ``\input`` (any other extension).
LaTeX will search the specified files in the `TeX input path`_.
-*Default*: no stylesheet (""). *Option*: ``--stylesheet``.
+*Default*: ``[]``. *Option*: ``--stylesheet``.
__ `stylesheet_path [latex writers]`_
__ `embed_stylesheet [latex writers]`_
-.. _TeX input path:
- http://www.tex.ac.uk/cgi-bin/texfaq2html?label=what-TDS
+.. _TeX input path: https://texfaq.org/FAQ-tds
.. _stylesheet_dirs [latex writers]:
@@ -1820,39 +1853,37 @@
stylesheet_dirs
~~~~~~~~~~~~~~~
-A comma-separated list of directories where stylesheets can be found.
+List of directories where stylesheets can be found (comma-separated_).
Used by the stylesheet_path__ setting.
-Note: This setting defines a "search path" (similar to the PATH variable for
-executables). However, the term "path" is already used in the
+Note: This setting defines a "search path" (similar to the PATH variable
+for executables). However, the term "path" is already used in the
stylesheet_path__ setting with the meaning of a file location.
+:Default: the working directory of the process at launch.
+:Option: ``--stylesheet-dirs``.
+
__
__ `stylesheet_path [latex writers]`_
-| *Default*: the working directory of the process at launch and the directory
- with default stylesheet files (writer and installation specific).
- Use the ``--help`` option to get the exact value.
-| *Option*: ``--stylesheet-dirs``.
-
.. _stylesheet_path [latex writers]:
stylesheet_path
~~~~~~~~~~~~~~~
-A comma-separated list of style files. Relative paths are expanded if a
+List of style files (comma-separated_). Relative paths are expanded if a
matching file is found in the stylesheet_dirs__.
If embed_stylesheet__ is False, paths are rewritten relative to
-the output file (if output_ or ``<destination>`` are specified)
+the output file (if output_ or `\<destination>`_ are specified)
or the current work directory.
+Overrides also stylesheet__. [#override]_
See also `stylesheet_path [html writers]`_.
For files in the `TeX input path`_, the stylesheet__ option is recommended.
-Also overrides stylesheet__. [#override]_
+*Default*: ``[]``. *Option*: ``--stylesheet-path``.
-*Default*: no stylesheet (""). *Option*: ``--stylesheet-path``.
-
+.. _<destination>: tools.html#usage-pattern
__ `stylesheet_dirs [latex writers]`_
__ `embed_stylesheet [latex writers]`_
__
@@ -1881,60 +1912,64 @@
Path [#pwd]_ to template file, which must be encoded in UTF-8.
See also `template [html writers]`_.
-| *Default*: writer dependent (see `[latex2e writer]`_, `[xetex writer]`_).
-| *Option*: ``--template``.
+:Default: writer dependent (see `[latex2e writer]`_, `[xetex writer]`_).
+:Option: ``--template``.
use_bibtex
~~~~~~~~~~
-Provisional, name, values, and beha...
[truncated message content] |
