SF.net SVN: docutils:[9777 ] trunk/docutils/docs
milde--- via Docutils-checkins <[email protected]>
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 9777
http://sourceforge.net/p/docutils/code/9777
Author: milde
Date: 2024-07-22 11:51:25 +0000 (Mon, 22 Jul 2024)
Log Message:
-----------
Documentation update.
Review and edit "The Docutils Publisher":
Document `core.publish_*()` arguments.
(Replaces the "convenience functions" section in "Runtime Settings".)
Refactor "parts" descriptions.
Small section about "Entry Point Functions"
Merge "Configuarion" section with "Docutils Runtime Settings" guide.
Move "Encodings" to "Docutils Configuration" guide.
Fix typos and omissions.
Add/fix links.
Modified Paths:
--------------
trunk/docutils/docs/api/publisher.txt
trunk/docutils/docs/api/runtime-settings.txt
trunk/docutils/docs/api/transforms.txt
trunk/docutils/docs/dev/runtime-settings-processing.txt
trunk/docutils/docs/howto/cmdline-tool.txt
trunk/docutils/docs/ref/doctree.txt
trunk/docutils/docs/user/config.txt
trunk/docutils/docs/user/tools.txt
Modified: trunk/docutils/docs/api/publisher.txt
===================================================================
--- trunk/docutils/docs/api/publisher.txt 2024-07-22 09:48:35 UTC (rev 9776)
+++ trunk/docutils/docs/api/publisher.txt 2024-07-22 11:51:25 UTC (rev 9777)
@@ -11,30 +11,33 @@
:Copyright: This document has been placed in the public domain.
.. contents::
+ :depth: 2
+.. _Publisher:
The ``docutils.core.Publisher`` class is the core of Docutils,
-managing all the processing and relationships between components. See
-`PEP 258`_ for an overview of Docutils components.
-Configuration is done via `runtime settings`_ assembled from several sources.
-The *Publisher convenience functions* are the normal entry points for
-using Docutils as a library.
+managing all the processing and relationships between components. [#]_
-.. _PEP 258: ../peps/pep-0258.html
+The `Publisher convenience functions`_ are the normal entry points
+for using Docutils as a library.
+`Entry point functions`_ with pre-set components are provided
+for use in `"console_scripts" entry points`_.
+Configuration is done via `convenience function arguments`_ and
+`runtime settings`_ assembled from several sources.
+.. [#] See the `Docutils Project Model`_ in PEP 258 for an overview.
+.. _Docutils Project Model: ../peps/pep-0258.html#docutils-project-model
+
Publisher Convenience Functions
===============================
There are several convenience functions in the ``docutils.core`` module.
Each of these functions sets up a `docutils.core.Publisher` object,
-then calls its ``publish()`` method. ``docutils.core.Publisher.publish()``
-handles everything else.
+then calls its `publish()` method which handles everything else.
+For details, see the `argument reference`_, the function docstrings
+and the source file `core.py`_.
-See the module docstring, ``help(docutils.core)``, and the function
-docstrings, e.g., ``help(docutils.core.publish_string)``, for details and
-a description of the function arguments.
-
.. TODO: generate API documentation with Sphinx and add links to it.
@@ -41,67 +44,127 @@
publish_cmdline()
-----------------
-Function for custom `command-line front-end tools`_
-(like ``tools/rst2html.py``) or "console_scripts" `entry points`_
-(like `core.rst2html()`) with file I/O.
-In addition to writing the output document to a file-like object, also
-returns it as `str` instance (rsp. `bytes` for binary output document
-formats).
+Function for custom `command-line applications`_.
-.. _command-line front-end tools: ../howto/cmdline-tool.html
-.. _entry points:
- https://packaging.python.org/en/latest/specifications/entry-points/
+.. parsed-literal::
+ def publish_cmdline(reader_\ =None, reader_name=None, [#component-names]_
+ parser_\ =None, parser_name=None, [#component-names]_
+ writer_\ =None, writer_name=None, [#component-names]_
+ settings_\ =None, settings_spec_\ =None,
+ settings_overrides_\ =None, config_section_\ =None,
+ enable_exit_status_\ =False,
+ argv=None, usage=default_usage,
+ description=default_description) -> str | bytes
+The function reads input from `sys.stdin` or a file specified on the
+command line, writes the output document to a file, and also returns it
+as `str` instance. [#binary-output]_
+
+See the `entry point functions`_ in `core.py`_, the scripts in the
+`tools/`_ directory, and `Inside A Docutils Command-Line Front-End Tool`_
+for usage examples.
+
+.. [#binary-output] Documents in binary formats (currently only ODT_)
+ are returned as a `bytes` instance.
+
+
publish_file()
--------------
-For programmatic use with file I/O. In addition to writing the output
-document to a file-like object, also returns it as `str` instance
-(rsp. `bytes` for binary output document formats).
+For programmatic use with `file I/O`_.
+.. parsed-literal::
+ def publish_file(source__\ =None, source_path__\ =None,
+ destination_\ =None, destination_path__\ =None,
+ reader_\ =None, reader_name=None, [#component-names]_
+ parser_\ =None, parser_name=None, [#component-names]_
+ writer_\ =None, writer_name=None, [#component-names]_
+ settings_\ =None, settings_spec_\ =None,
+ settings_overrides_\ =None, config_section_\ =None,
+ enable_exit_status_\ =False) -> str | bytes
+
+Read input from a file-like object.
+Write the output document to a file-like object and also return it as
+`str` instance. [#binary-output]_
+
+__ `source (file I/O)`_
+__ `source_path (file I/O)`_
+__ `destination_path (file I/O)`_
+
+
publish_string()
----------------
-For programmatic use with _`string I/O`:
+For programmatic use with `string I/O`_.
-Input
- can be a `str` or `bytes` instance.
- `bytes` are decoded with input_encoding_.
+.. parsed-literal::
-Output
- is handled similar to `xml.etree.ElementTree.tostring()`__:
+ def publish_string(source__, source_path__\ =None,
+ destination_path__\ =None,
+ reader_\ =None, reader_name=None, [#component-names]_
+ parser_\ =None, parser_name=None, [#component-names]_
+ writer_\ =None, writer_name=None, [#component-names]_
+ settings_\ =None, settings_spec_\ =None,
+ settings_overrides_\ =None, config_section_\ =None,
+ enable_exit_status_\ =False) -> bytes | str
- * return a `bytes` instance, if output_encoding_ is set to an encoding
- registered with Python's "codecs_" module (default: "utf-8"),
- * return `str` instance, if output_encoding_ is set to the special value
- ``"unicode"``.
+__ `source (string I/O)`_
+__ `source_path (string I/O)`_
+__ `destination_path (string I/O)`_
-__ https://docs.python.org/3/library/xml.etree.elementtree.html
- #xml.etree.ElementTree.tostring
+Get the input from the `source <source (string I/O)_>`__ argument
+(a `str` or `bytes` instance).
+Return the output document as a **bytes** instance unless the
+output_encoding_ runtime setting has the special value ``"unicode"``. [#]_
+Example:
+ Return a Docutils XML version of the source as `str` instance::
+
+ publish_string(source, writer='xml',
+ settings_overrides={'output_encoding': 'unicode'})
+
+
.. Caution::
- The "output_encoding" and "output_encoding_error_handler" `runtime
- settings`_ may affect the content of the output document:
- Some document formats contain an *encoding declaration*,
- some formats use substitutions for non-encodable characters.
+ The output_encoding_ and output_encoding_error_handler_ runtime
+ settings may affect the content of the output document:
+ Some document formats contain an *encoding declaration*,
+ some formats use substitutions for non-encodable characters.
- Use `publish_parts()`_ to get a `str` instance of the output document
- as well as the values of the output_encoding_ and
- output_encoding_error_handler_ runtime settings.
+ Use `publish_parts()`_ to get a `str` instance of the output document
+ together with values of the "output_encoding" and
+ "output_encoding_error_handler" settings.
-*This function is provisional* because in Python 3 the name and behaviour
-no longer match.
+The `publish_str()` function is *provisional* because in Python 3 the
+name and default return type no longer match.
-.. _codecs: https://docs.python.org/3/library/codecs.html
+.. [#] similar to `xml.etree.ElementTree.tostring()`__
+__ https://docs.python.org/3/library/xml.etree.elementtree.html
+ #xml.etree.ElementTree.tostring
publish_doctree()
-----------------
-Parse string input (cf. `string I/O`_) into a `Docutils document tree`_ data
-structure (doctree). The doctree can be modified, pickled & unpickled,
+For programmatic use with `string input`_.
+Parse input into a `Docutils Document Tree`_ data structure.
+Return a `nodes.document`_ instance.
+
+.. parsed-literal::
+
+ publish_doctree(source__, source_path__\ =None,
+ source_class_\ =io.StringInput,
+ reader_\ =None, reader_name=None, [#component-names]_
+ parser_\ =None, parser_name=None, [#component-names]_
+ settings_\ =None, settings_spec_\ =None,
+ settings_overrides_\ =None, config_section_\ =None,
+ enable_exit_status_\ =False) -> nodes.document_
+
+__ `source (string I/O)`_
+__ `source_path (string I/O)`_
+
+The Document Tree can be modified, pickled & unpickled,
etc., and then reprocessed with `publish_from_doctree()`_.
@@ -108,35 +171,64 @@
publish_from_doctree()
----------------------
-Render from an existing `document tree`_ data structure (doctree).
-Returns the output document as a memory object (cf. `string I/O`_).
+For programmatic use with `string output`_.
+Render from an existing Document Tree data structure
+(nodes.document_ instance).
+Return the output document as a `bytes` or `str` instance
+(cf. `publish_string()`_).
-*This function is provisional* because in Python 3 the name and behaviour
-of the *string output* interface no longer match.
+.. parsed-literal::
+ publish_from_doctree(document, destination_path__\ =None,
+ writer_\ =None, writer_name=None, [#component-names]_
+ settings_\ =None, settings_spec_\ =None,
+ settings_overrides_\ =None, config_section_\ =None,
+ enable_exit_status_\ =False) -> bytes | str
-publish_programmatically()
---------------------------
+__ `destination_path (string I/O)`_
-Auxilliary function used by `publish_file()`_, `publish_string()`_,
-`publish_doctree()`_, and `publish_parts()`_.
-Applications should not need to call this function directly.
+The `publish_from_doctree()` function is *provisional* because in
+Python 3 the name and default return type of the `string I/O`_ interface
+no longer match.
+
.. _publish-parts-details:
publish_parts()
---------------
-For programmatic use with string input (cf. `string I/O`_).
-Returns a dictionary of document parts as `str` instances. [#binary-output]_
+For programmatic use. With `string input`_ (default) or `file input`_
+(depending on the value of the source_class_ argument).
+Returns a dictionary of document parts.
+
+.. parsed-literal::
+
+ def publish_parts(source__, source_path__\ =None,
+ source_class_\ =io.StringInput,
+ destination_path__\ =None,
+ reader_\ =None, reader_name=None, [#component-names]_
+ parser_\ =None, parser_name=None, [#component-names]_
+ writer_\ =None, writer_name=None, [#component-names]_
+ settings_\ =None, settings_spec_\ =None,
+ settings_overrides_\ =None, config_section_\ =None,
+ enable_exit_status_\ =False) -> dict
+
+__ `source (string I/O)`_
+__ `source_path (string I/O)`_
+__ `destination_path (string I/O)`_
+
+
Dictionary keys are the part names.
-Each Writer component may publish a different set of document parts,
-described below.
+Each Writer component may publish a different set of document parts:
-Example: post-process the output document with a custom function
-``post_process()`` before encoding with user-customizable encoding
-and errors ::
+.. contents::
+ :local:
+Example:
+ post-process the output document with a custom function
+ ``post_process()`` before encoding with user-customizable
+ encoding and errors::
+
def publish_bytes_with_postprocessing(*args, **kwargs):
parts = publish_parts(*args, **kwargs)
out_str = post_process(parts['whole'])
@@ -148,56 +240,54 @@
.. _ODT: ../user/odt.html
-Parts Provided By All Writers
+Parts Provided by All Writers
`````````````````````````````
-_`encoding`
+_`"encoding"` : str
The `output_encoding`_ setting.
-_`errors`
+_`"errors"` : str
The `output_encoding_error_handler`_ setting.
-_`version`
+_`"version"` : str
The version of Docutils used.
-_`whole`
- Contains the entire formatted document. [#binary-output]_
+_`"whole"` : str | bytes
+ The entire formatted document. [#binary-output]_
- .. [#binary-output] Output documents in binary formats (e.g. ODT_)
- are stored as a `bytes` instance.
-
-Parts Provided By the HTML Writers
+Parts Provided by the HTML Writers
``````````````````````````````````
+All parts returned by the HTML writers are of data type `str`.
+
HTML4 Writer
^^^^^^^^^^^^
-_`body`
- ``parts['body']`` is equivalent to parts['fragment_']. It is
- *not* equivalent to parts['html_body_'].
+_`"body"`
+ Equivalent to `"fragment"`_. It is *not* equivalent to `"html_body"`_.
-_`body_prefix`
- ``parts['body_prefix']`` contains::
+_`"body_prefix"`
+ Contains ::
</head>
<body>
<div class="document" ...>
- and, if applicable::
+ and, if applicable ::
<div class="header">
...
</div>
-_`body_pre_docinfo`
- ``parts['body_pre_docinfo]`` contains (as applicable)::
+_`"body_pre_docinfo"`
+ Contains (as applicable)::
<h1 class="title">...</h1>
<h2 class="subtitle" id="...">...</h2>
-_`body_suffix`
- ``parts['body_suffix']`` contains::
+_`"body_suffix"`
+ Contains ::
</div>
@@ -208,90 +298,94 @@
...
</div>
- and::
+ and ::
</body>
</html>
-_`docinfo`
- ``parts['docinfo']`` contains the document bibliographic data, the
- docinfo field list rendered as a table.
+_`"docinfo"`
+ Bibliographic data, i.e. the `\<docinfo>`_ element's content, [#]_
+ rendered as a table.
-_`footer`
- ``parts['footer']`` contains the document footer content, meant to
+ .. [#] Abstract and dedication are included in
+ the `"body"`_/`"fragment"`_ part.
+
+_`"footer"`
+ The document footer content, meant to
appear at the bottom of a web page, or repeated at the bottom of
every printed page.
-_`fragment`
- ``parts['fragment']`` contains the document body (*not* the HTML
- ``<body>``). In other words, it contains the entire document,
- less the document title, subtitle, docinfo, header, and footer.
+_`"fragment"`
+ The document body (*not* the HTML ``<body>``).
+ In other words, ``part['fragment']`` contains the entire document,
+ less the document `"title"`_, `"subtitle"`_, `"docinfo"`_,
+ `"header"`_, and `"footer"`_. Equivalent to part `"body"`_.
-_`head`
- ``parts['head']`` contains ``<meta ... />`` tags and the document
- ``<title>...</title>``.
+_`"head"`
+ Contains ``<meta ... />`` tags and the document
+ ``<title>...</title>``. See also `"html_head"`_.
-_`head_prefix`
- ``parts['head_prefix']`` contains the XML declaration, the DOCTYPE
- declaration, the ``<html ...>`` start tag and the ``<head>`` start
- tag.
+_`"head_prefix"`
+ The XML declaration, the DOCTYPE declaration,
+ the ``<html ...>`` start tag, and the ``<head>`` start tag.
-_`header`
- ``parts['header']`` contains the document header content, meant to
- appear at the top of a web page, or repeated at the top of every
- printed page.
+_`"header"`
+ The document header content, meant to appear at the top
+ of a web page, or repeated at the top of every printed page.
-_`html_body`
- ``parts['html_body']`` contains the HTML ``<body>`` content, less
- the ``<body>`` and ``</body>`` tags themselves.
+_`"html_body"`
+ The HTML ``<body>`` content,
+ less the ``<body>`` and ``</body>`` tags themselves.
-_`html_head`
- ``parts['html_head']`` contains the HTML ``<head>`` content, less
- the stylesheet link and the ``<head>`` and ``</head>`` tags
- themselves. Since `publish_parts()` returns `str` instances which
- do not know about the output encoding, the "Content-Type" meta
- tag's "charset" value is left unresolved, as "%s"::
+_`"html_head"`
+ The HTML ``<head>`` content, less the `"stylesheet"`_
+ and the ``<head>`` and ``</head>`` tags themselves.
+ The "Content-Type" meta tag's "charset" value is left unresolved,
+ as ``%s``::
+
<meta http-equiv="Content-Type" content="text/html; charset=%s" />
The interpolation should be done by client code.
+ Alternatively, use part `"head"`_ which interpolates
+ the "charset" value with `"encoding"`_.
-_`html_prolog`
- ``parts['html_prolog]`` contains the XML declaration and the
- doctype declaration. The XML declaration's "encoding" attribute's
- value is left unresolved, as "%s"::
+_`"html_prolog"`
+ The XML declaration and the doctype declaration.
+ The XML declaration's "encoding" attribute's value is left unresolved,
+ as "%s"::
<?xml version="1.0" encoding="%s" ?>
The interpolation should be done by client code.
-_`html_subtitle`
- ``parts['html_subtitle']`` contains the document subtitle,
- including the enclosing ``<h2 class="subtitle">`` and ``</h2>``
- tags.
+_`"html_subtitle"`
+ The document subtitle, including the
+ enclosing ``<h2 class="subtitle">`` and ``</h2>`` tags.
-_`html_title`
- ``parts['html_title']`` contains the document title, including the
+_`"html_title"`
+ The document title, including the
enclosing ``<h1 class="title">`` and ``</h1>`` tags.
-_`meta`
- ``parts['meta']`` contains all ``<meta ... />`` tags.
+_`"meta"`
+ Contains all ``<meta ... />`` tags.
-_`stylesheet`
- ``parts['stylesheet']`` contains the embedded stylesheet or
- stylesheet link.
+_`"stylesheet"`
+ The embedded stylesheet or stylesheet link.
-_`subtitle`
- ``parts['subtitle']`` contains the document subtitle text and any
- inline markup. It does not include the enclosing ``<h2>`` and
- ``</h2>`` tags.
+_`"subtitle"`
+ The document subtitle text and any inline markup.
+ It does not include the enclosing ``<h2>`` and ``</h2>`` tags.
-_`title`
- ``parts['title']`` contains the document title text and any inline
- markup. It does not include the enclosing ``<h1>`` and ``</h1>``
- tags.
+_`"title"`
+ The document title text and any inline markup.
+ It does not include the enclosing ``<h1>`` and ``</h1>`` tags.
+The default template_ joins `"head_prefix"`_, `"head"`_, `"stylesheet"`_,
+`"body_prefix"`_, `"body_pre_docinfo"`_, `"docinfo"`_, `"body"`_, and
+`"body_suffix"`_ to get part `"whole"`_.
+
PEP/HTML Writer
^^^^^^^^^^^^^^^
@@ -298,9 +392,8 @@
The PEP/HTML writer provides the same parts as the `HTML4 writer`_,
plus the following:
-_`pepnum`
- ``parts['pepnum']`` contains the PEP number
- (extracted from the `header preamble`__).
+_`"pepnum"`
+ The PEP number (extracted from the `header preamble`__).
__ https://peps.python.org/pep-0001/#pep-header-preamble
@@ -315,205 +408,284 @@
^^^^^^^^^^^^
The HTML5 writer provides the same parts as the `HTML4 writer`_.
-However, it uses semantic HTML5 elements for the document, header and
-footer.
+However, it uses semantic HTML5 elements for the document, `"header"`_, and
+`"footer"`_ and a description list for the `"docinfo"`_ part.
-Parts Provided by the "LaTeX2e" and "XeTeX" Writers
-```````````````````````````````````````````````````
+Parts Provided by the (Xe)LaTeX Writers
+```````````````````````````````````````
-See the template files default.tex_, titlepage.tex_, titlingpage.tex_,
-and xelatex.tex_ for examples how these parts can be combined
-into a valid LaTeX document.
+All parts returned by the (Xe)LaTeX writers are of data type `str`.
-abstract
- ``parts['abstract']`` contains the formatted content of the
- 'abstract' docinfo field.
+_`"abstract"`
+ Formatted content of the "abstract" `bibliographic field`_.
-body
- ``parts['body']`` contains the document's content. In other words, it
- contains the entire document, except the document title, subtitle, and
+"body"
+ The document's content. In other words, ``parts['body']`` contains
+ the entire document, except the document title, subtitle, and
docinfo.
This part can be included into another LaTeX document body using the
``\input{}`` command.
-body_pre_docinfo
- ``parts['body_pre_docinfo]`` contains the ``\maketitle`` command.
+"body_pre_docinfo"
+ The ``\maketitle`` command.
-dedication
- ``parts['dedication']`` contains the formatted content of the
- 'dedication' docinfo field.
+_`"dedication"`
+ Formatted content of the "dedication" `bibliographic field`_.
-docinfo
- ``parts['docinfo']`` contains the document bibliographic data, the
- docinfo field list rendered as a table.
+"docinfo"
+ Bibliographic data, i.e. the `\<docinfo>`_ element's content,
+ rendered as a table.
- With ``--use-latex-docinfo`` 'author', 'organization', 'contact',
- 'address' and 'date' info is moved to titledata.
+ With ``--use-latex-docinfo`` the <author>, <organization>,
+ <contact>, <address" and <date> are moved to `"titledata"`_.
- 'dedication' and 'abstract' are always moved to separate parts.
+"fallbacks"
+ Fallback definitions for Docutils-specific LaTeX commands and environments.
-fallbacks
- ``parts['fallbacks']`` contains fallback definitions for
- Docutils-specific commands and environments.
+"head_prefix"
+ The declaration of documentclass and document options.
-head_prefix
- ``parts['head_prefix']`` contains the declaration of
- documentclass and document options.
+"latex_preamble"
+ The argument of the ``--latex-preamble`` option.
-latex_preamble
- ``parts['latex_preamble']`` contains the argument of the
- ``--latex-preamble`` option.
+"pdfsetup"
+ PDF properties ("hyperref" package setup).
-pdfsetup
- ``parts['pdfsetup']`` contains the PDF properties
- ("hyperref" package setup).
+"requirements"
+ Required packages and setup before the stylesheet inclusion.
-requirements
- ``parts['requirements']`` contains required packages and setup
- before the stylesheet inclusion.
+"stylesheet"
+ The embedded stylesheet(s) or stylesheet loading command(s).
-stylesheet
- ``parts['stylesheet']`` contains the embedded stylesheet(s) or
- stylesheet loading command(s).
+"subtitle"
+ Document subtitle text and any inline markup.
-subtitle
- ``parts['subtitle']`` contains the document subtitle text and any
- inline markup.
+"title"
+ Document title text and any inline markup.
-title
- ``parts['title']`` contains the document title text and any inline
- markup.
+_`"titledata"`
+ The combined title data in ``\title``, ``\author``, and ``\date`` macros.
-titledata
- ``parts['titledata]`` contains the combined title data in
- ``\title``, ``\author``, and ``\date`` macros.
+ With ``--use-latex-docinfo``, this includes the <author>,
+ <organization>, <contact>, <address" and <date> docinfo items.
- With ``--use-latex-docinfo``, this includes the 'author',
- 'organization', 'contact', 'address' and 'date' docinfo items.
+See the template files default.tex_, titlepage.tex_, titlingpage.tex_,
+and xelatex.tex_ for examples how these parts are combined
+into a valid LaTeX document.
-.. _default.tex:
- https://docutils.sourceforge.io/docutils/writers/latex2e/default.tex
-.. _titlepage.tex:
- https://docutils.sourceforge.io/docutils/writers/latex2e/titlepage.tex
-.. _titlingpage.tex:
- https://docutils.sourceforge.io/docutils/writers/latex2e/titlingpage.tex
-.. _xelatex.tex:
- https://docutils.sourceforge.io/docutils/writers/latex2e/xelatex.tex
+.. _default.tex: ../../docutils/writers/latex2e/default.tex
+.. _titlepage.tex: ../../docutils/writers/latex2e/titlepage.tex
+.. _titlingpage.tex: ../../docutils/writers/latex2e/titlingpage.tex
+.. _xelatex.tex: ../../docutils/writers/latex2e/xelatex.tex
-.. _runtime settings:
+publish_programmatically()
+--------------------------
-Configuration
-=============
+Auxiliary function used by `publish_file()`_, `publish_string()`_,
+`publish_doctree()`_, and `publish_parts()`_.
+Applications should not need to call this function directly.
-Docutils is configured by *runtime settings* assembled from several
-sources:
-* *settings specifications* of the selected components (reader, parser,
- writer),
-* the ``settings_overrides`` argument of the `Publisher convenience
- functions`_ (see below),
-* *configuration files* (unless disabled), and
-* *command-line options* (if enabled).
+Entry Point Functions
+---------------------
-Docutils overlays default and explicitly specified values from these
-sources such that settings behave the way we want and expect them to
-behave. For details, see `Docutils Runtime Settings`_.
-The individual settings are described in `Docutils Configuration`_.
+The functions rst2html(), rst2html4(), rst2html5(), rst2latex(),
+rst2man(), rst2odt(), rst2pseudoxml(), rst2s5(), rst2xetex(),
+and rst2xml() are wrappers around `publish_cmdline()`_ used in
+`"console_scripts" entry points`_ for eponymous `command-line applications`_.
-To pass application-specific setting defaults to the Publisher
-convenience functions, use the ``settings_overrides`` parameter. Pass
-a dictionary of setting names & values, like this::
+.. _"console_scripts" entry points:
+ https://packaging.python.org/en/latest/specifications/entry-points/
- app_defaults = {'input_encoding': 'ascii',
- 'output_encoding': 'latin-1'}
- output = publish_string(..., settings_overrides=app_defaults)
-Settings from command-line options override configuration file
-settings, and they override application defaults.
+.. _convenience function arguments:
-See `Docutils Runtime Settings`_ or the docstring of
-`publish_programmatically()` for a description of all `configuration
-arguments`_ of the Publisher convenience functions.
+Argument Reference
+==================
-.. _configuration arguments: runtime-settings.html#convenience-functions
+.. _file input:
+File I/O
+--------
-Encodings
-=========
+The function `publish_file()`_ uses the file I/O interface;
+`publish_parts()`_ can be configured to use file input
+by setting the `source_class`_ argument to `docutils.io.FileInput`.
-Docutils supports all `standard encodings`_ and encodings registered__
-with the codecs_ module.
-The special value "unicode" can be used with `publish_string()`_ to skip
-encoding and return a `str` instance instead of `bytes`.
+.. _source (file I/O):
-__ https://docs.python.org/3/library/codecs.html#codecs.register
+source : file-like
+ A file-like object holding the document source
+ (must have `read()` and `close()` methods).
+ Default: None (open `source_path <source_path (file I/O)_>`__
+ or use `sys.stdin`).
-The **input encoding** can be specified with the `input_encoding`_ setting.
-The default is "utf-8".
-The **output encoding** can be specified with the `output_encoding`_ setting.
-The default is "utf-8", too.
+ .. _source_path (file I/O):
-.. Caution:: Docutils may introduce non-ASCII text if you use
- `auto-symbol footnotes`_.
- In non-English documents, also auto-generated labels
- may contain non-ASCII characters.
+source_path : str | pathlib.Path
+ Path to the source file,
+ opened if `source <source (file I/O)_>`__ is None.
-auto-detection
---------------
+ Default: None (use `source <source (file I/O)_>`__).
-Up to Docutils 0.21, the input encoding was detected from a `Unicode byte
-order mark` (BOM_) or an *encoding declaration* [#magic-comment]_ in the
-source unless an input_encoding_ was specified.
+_`destination` : file-like
+ A file-like object that will receive the output document
+ (must have `write()` and `close()` methods).
-The default input encoding changed to "utf-8" in Docutils 0.22.
-Currently, auto-detection can be selected with an input_encoding_ value
-``None`` (rsp. an empty string in a configuration file).
-However, input encoding "auto-detection_" is deprecated and **will be
-removed** in Docutils 1.0. See the `inspecting_codecs`_ package for a
-possible replacement.
+ Default: None (open `destination_path <destination_path (file I/O)_>`__
+ or use `sys.stdout`).
-.. [#magic-comment] A comment like ::
+ .. _destination_path (file I/O):
- .. text encoding: <encoding name>
+destination_path : str | pathlib.Path
+ Path to the destination file, opened if destination_ is None.
- on the first or second line of a reStructuredText source
- defines `<encoding name>` as the source's input encoding.
+ Default: None (use destination_).
- Examples: (using formats recognized by popular editors) ::
- .. -*- mode: rst -*-
- -*- coding: latin1 -*-
+.. _string input:
+.. _string output:
- or::
+String I/O
+----------
- .. vim: set fileencoding=cp737 :
+The functions `publish_string()`_, `publish_doctree()`_,
+`publish_from_doctree()`_, and `publish_parts()`_ use the
+string I/O interface provided by the `docutils.io.StringInput`
+and `docutils.io.StringOutput` classes.
- More precisely, the first and second line are searched for the following
- regular expression::
+.. _source (string I/O):
- coding[:=]\s*([-\w.]+)
+source : str | bytes
+ The document source. `bytes` are decoded with the encoding
+ specified in the input_encoding_ setting.
- The first group of this expression is then interpreted as encoding name.
- If the first line matches the second line is ignored.
+ Required.
+ .. _source_path (string I/O):
+source_path : str
+ Path to the file or name of the object that produced
+ `source <source (string I/O)_>`__.
+ Used as `"source" attribute`_ in diagnostic output.
-.. _codecs: https://docs.python.org/3/library/codecs.html
-.. _standard encodings:
- https://docs.python.org/3/library/codecs.html#standard-encodings
+ Default: None.
+
+_`source_class` : docutils.io.Input
+ Change the semantics of the "source" and "source_path" arguments.
+ The value `docutils.io.FileInput` lets "source" and "source_path"
+ behave as described in `file I/O`_.
+
+ Default: `docutils.io.StringInput`.
+
+ .. _destination_path (string I/O):
+
+destination_path : str
+ Path to the file or name of the object which will receive the output.
+ Used for determining relative paths (stylesheets, source links, etc.)
+
+ Default: None.
+
+Component Specification
+-----------------------
+
+_`reader` : str | docutils.readers.Reader
+ `Reader component name`_ or instance. [#component-names]_
+
+ Default: "standalone".
+
+_`parser` : str | docutils.parsers.Parser
+ `Parser component name`_ or instance. [#component-names]_
+
+ Default: "restructuredtext".
+
+_`writer` : str | docutils.parsers.Writer
+ `Writer component name`_ or instance. [#component-names]_
+
+ Default: "pseudoxml".
+
+.. [#component-names] Up to Docutils 0.21, component *names* were specified
+ with the "_`reader_name`", "_`parser_name`", and "_`writer_name`" arguments.
+ These arguments are deprecated and will be removed in Docutils 2.0.
+
+
+Settings Specification
+----------------------
+
+See also `Runtime Settings`_.
+
+_`settings` : docutils.frontend.Values
+ Runtime settings object.
+ If `settings` is passed, it's assumed to be the end result of
+ `runtime settings processing`_ and no further setting/config/option
+ processing is done.
+
+ Default: None.
+
+_`settings_spec` : docutils.SettingsSpec_
+ Application-specific settings definitions, independent of components.
+ In other words, the application becomes a component, and its settings
+ data is processed after the other components.
+ Used only if settings_ is None.
+
+ Default: None.
+
+_`settings_overrides` : dict
+ Application-specific settings defaults that override the defaults
+ of other components. Used only if settings_ is None.
+
+ Default: None.
+
+_`config_section` : str
+ Name of the configuration file section for this application.
+
+ Can be specified instead of settings_spec_ (a new
+ docutils.SettingsSpec_ will be created) or in addition to
+ settings_spec_ (overriding its `config_section` attribute).
+ Used only if settings_ is None.
+
+ Default: None.
+
+_`enable_exit_status` : bool
+ Set "system exit status" at end of processing?
+
+ Default: False.
+
+
+.. References
+ ----------
+
+.. _runtime settings processing:
+.. _Runtime Settings: runtime-settings.html
+.. _docutils.SettingsSpec: runtime-settings.html#settingsspec
+
+.. _Inside A Docutils Command-Line Front-End Tool: ../howto/cmdline-tool.html
+
+.. _Document Tree:
+.. _Docutils Document Tree: ../ref/doctree.html
+.. _<docinfo>: ../ref/doctree.html#docinfo
+.. _nodes.document: ../ref/doctree.html#document
+.. _"source" attribute: ../ref/doctree.html#source
+
+.. _bibliographic field:
+ ../ref/rst/restructuredtext.html#bibliographic-fields
+
+.. _Docutils Configuration: ../user/config.html
+.. _configuration files: ../user/config.html#configuration-files
.. _input_encoding: ../user/config.html#input-encoding
-.. _BOM: https://docs.python.org/3/library/codecs.html#codecs.BOM
.. _output_encoding: ../user/config.html#output-encoding
.. _output_encoding_error_handler:
- ../user/config.html#output-encoding-error-handler
-.. _auto-symbol footnotes:
- ../ref/rst/restructuredtext.html#auto-symbol-footnotes
-.. _document tree:
-.. _Docutils document tree: ../ref/doctree.html
-.. _Docutils Runtime Settings: ./runtime-settings.html
-.. _Docutils Configuration: ../user/config.html
-.. _inspecting_codecs: https://codeberg.org/milde/inspecting-codecs
+ ../user/config.html#output-encoding-error-handler
+.. _template: ../user/config.html#template
+.. _reader component name: ../user/config.html#reader
+.. _parser component name: ../user/config.html#parser
+.. _writer component name: ../user/config.html#writer-docutils-application
+
+.. _command-line applications: ../user/tools.html
+
+.. _core.py: ../../docutils/core.py
+.. _tools/: ../../tools/
Modified: trunk/docutils/docs/api/runtime-settings.txt
===================================================================
--- trunk/docutils/docs/api/runtime-settings.txt 2024-07-22 09:48:35 UTC (rev 9776)
+++ trunk/docutils/docs/api/runtime-settings.txt 2024-07-22 11:51:25 UTC (rev 9777)
@@ -22,15 +22,13 @@
* `configuration files`_ (if enabled), and
* command-line options (if enabled).
-Docutils overlays default and explicitly specified values from these
-sources such that settings behave the way we want and expect them to
-behave.
+The individual settings are described in `Docutils Configuration`_.
Settings priority
=================
-The sources are overlaid in the following order (later sources
+Docutils overlays settings in the following order (later sources
overwrite earlier ones):
1. Defaults specified in the `settings_spec`__ and
@@ -44,11 +42,10 @@
__ SettingsSpec.settings_default_overrides_
-3. Settings specified in the `settings_overrides`__ parameter of the
- `convenience functions`_ resp. the `settings_overrides` attribute of
- a `Publisher`_ instance.
+3. Application defaults specified in the `settings_overrides`__ argument
+ of the `Publisher convenience functions`_.
- __ `settings_overrides parameter`_
+ __ publisher.html#settings-overrides
4. Settings specified in `active sections`_ of the `configuration files`_
in the order described in `Configuration File Sections & Entries`_
@@ -56,6 +53,9 @@
5. Command line options (if enabled).
+Applications may opt-out of the standard settings processing providing
+their own set of settings.
+
For details see the ``docutils/__init__.py``, ``docutils/core.py``, and
``docutils.frontend.py`` modules and the implementation description in
`Runtime Settings Processing`_.
@@ -71,9 +71,11 @@
deprecated optparse_ module with argparse_.
The `docutils.SettingsSpec` base class is inherited by Docutils
-components_ and `frontend.OptionParser`.
-It defines the following six **attributes**:
+components_ and `frontend.OptionParser`. It defines six attributes:
+attributes
+----------
+
.. _SettingsSpec.settings_spec:
`settings_spec`
@@ -109,8 +111,6 @@
`relative_path_settings`
listing settings containing filesystem paths.
- .. _active sections:
-
`config_section`
the configuration file section specific to this
component.
@@ -119,10 +119,13 @@
lists configuration files sections
that should also be read (before the `config_section`).
-The last two attributes define which configuration file sections are
-"active". See also `Configuration File Sections & Entries`_.
+.. _active sections:
+The last two attributes define which configuration file sections are "active".
+See also `Configuration File Sections & Entries`_ in the `Docutils
+Configuration`_ guide.
+
Glossary
========
@@ -131,8 +134,8 @@
components
----------
-Docutils front-ends and applications combine a selection of
-*components* of the `Docutils Project Model`_.
+Docutils front-ends and applications combine a selection of *components*
+of the `Docutils Project Model`_ (reader, parser, writer).
All components inherit the `SettingsSpec`_ base class.
This means that all instances of ``readers.Reader``, ``parsers.Parser``, and
@@ -139,70 +142,29 @@
``writers.Writer`` are also instances of ``docutils.SettingsSpec``.
For the determination of runtime settings, ``frontend.OptionParser`` and
-the `settings_spec parameter`_ in application settings specifications
+applications providing a `SettingsSpec`_ instance via the `settings
+specification arguments`_ of the `Publisher convenience functions`_
are treated as components as well.
-.. _convenience function:
-
-convenience functions
----------------------
-
-Applications usually deploy Docutils by one of the
-`Publisher convenience functions`_.
-
-All convenience functions accept the following optional parameters:
-
-.. _settings parameter:
-
-`settings`
- a ``frontend.Values`` instance.
- If present, it must be complete.
-
- No further runtime settings processing is done and the
- following parameters have no effect.
-
- .. _settings_spec parameter:
-
-`settings_spec`
- a `SettingsSpec`_ subclass or instance containing the settings
- specification for the "Application" itself.
- The instance is added to the components_ (after the generic
- settings, parser, reader, and writer).
-
- .. _settings_overrides parameter:
-
-`settings_overrides`
- a dictionary which is used to update the
- defaults of the components' settings specifications.
-
- .. _config_section parameter:
-
-`config_section`
- the name of an application-specific
- `configuration file section`_ for this application.
-
- Can be specified instead of a `settings_spec` (a new SettingsSpec_
- instance that just defines a configuration section will be created)
- or in addition to a `settings_spec`
- (overriding its `config_section` attribute).
-
-
settings_spec
-------------
The name ``settings_spec`` may refer to
-a) an instance of the SettingsSpec_ class, or
+a) an instance of the SettingsSpec_ class,
b) the data structure `SettingsSpec.settings_spec`_ which is used to
- store settings details.
+ store settings details, or
+c) the `"settings_spec" argument`_ of the Publisher convenience functions.
.. References:
-.. _Publisher: publisher.html
+.. _Publisher: publisher.html#publisher
.. _Publisher convenience functions:
publisher.html#publisher-convenience-functions
+.. _settings specification arguments: publisher.html#settings-specification
+.. _"settings_spec" argument: publisher.html#settings-spec
.. _front-end tools: ../user/tools.html
.. _configuration files:
.. _Docutils Configuration: ../user/config.html#configuration-files
Modified: trunk/docutils/docs/api/transforms.txt
===================================================================
--- trunk/docutils/docs/api/transforms.txt 2024-07-22 09:48:35 UTC (rev 9776)
+++ trunk/docutils/docs/api/transforms.txt 2024-07-22 11:51:25 UTC (rev 9777)
@@ -235,7 +235,7 @@
Given a document starting [#pre-docinfo]_ with a field list, the DocInfo
transform converts fields with registered `bibliographic field`_ names to
the corresponding document tree elements becoming child elements of the
-`\<docinfo>`_ element (except for a "dedication" and "abstract", which
+`\<docinfo>`_ element (except for "dedication" and "abstract", which
become `\<topic>`_ elements after <docinfo>).
.. [#pre-docinfo] A document title and subtitle, header and footer,
Modified: trunk/docutils/docs/dev/runtime-settings-processing.txt
===================================================================
--- trunk/docutils/docs/dev/runtime-settings-processing.txt 2024-07-22 09:48:35 UTC (rev 9776)
+++ trunk/docutils/docs/dev/runtime-settings-processing.txt 2024-07-22 11:51:25 UTC (rev 9777)
@@ -56,9 +56,9 @@
__ ../api/runtime-settings.html#settingsspec-settings-default-overrides
__ component.settings_default_overrides_
-3. Settings specified in the `settings_overrides parameter`_ of the
- `convenience functions`_ rsp. the `settings_overrides` attribute of
- a `core.Publisher` instance.
+3. Settings specified in the `"settings_overrides" argument`_ of the
+ `Publisher convenience functions`_ rsp. the `settings_overrides`
+ attribute of a `core.Publisher` instance.
(details__)
__ OptionParser.defaults_
@@ -76,7 +76,7 @@
__ `Publisher.process_command_line()`_
-Settings assigned to the `settings parameter`_ of the
+Settings assigned to the `"settings" argument`_ of the
`convenience functions`_ or the ``Publisher.settings`` attribute
are used **instead of** the above sources
(see below for details for `command-line tools`__ and
@@ -91,7 +91,7 @@
==================================================
The command-line `front-end tools`_ usually import and call
-the `convenience function`_ ``docutils.core.publish_cmdline()``.
+the Publisher convenience function `publish_cmdline()`_.
1. ``docutils.core.publish_cmdline()`` creates a `Publisher`_ instance::
@@ -122,7 +122,7 @@
4. ``publisher.setup_option_parser()``
- - merges the value of the `config_section parameter`_ into
+ - merges the value of the `"config_section" argument`_ into
`settings_spec` and
- creates an `OptionParser` instance ::
@@ -277,26 +277,19 @@
.. _Docutils Runtime Settings:
../api/runtime-settings.html
-.. _active sections:
- ../api/runtime-settings.html#active-sections
-.. _SettingsSpec:
- ../api/runtime-settings.html#settingsspec
+.. _active sections: ../api/runtime-settings.html#active-sections
+.. _SettingsSpec: ../api/runtime-settings.html#settingsspec
.. _component:
-.. _components:
- ../api/runtime-settings.html#components
-.. _application settings specifications:
-.. _convenience function:
+.. _components: ../api/runtime-settings.html#components
+
.. _convenience functions:
- ../api/runtime-settings.html#convenience-functions
-.. _settings_overrides parameter:
- ../api/runtime-settings.html#settings-overrides-parameter
-.. _settings parameter:
- ../api/runtime-settings.html#settings-parameter
-.. _config_section parameter:
- ../api/runtime-settings.html#config-section-parameter
-
.. _Publisher convenience functions:
../api/publisher.html#publisher-convenience-functions
+.. _publish_cmdline(): ../api/publisher.html#publish-cmdline
+.. _"settings" argument: ../api/publisher.html#settings
+.. _"settings_overrides" argument: ../api/publisher.html#settings-overrides
+.. _"config_section" argument: ../api/publisher.html#config-section
+
.. _front-end tools: ../user/tools.html
.. _configuration file:
.. _configuration files:
Modified: trunk/docutils/docs/howto/cmdline-tool.txt
===================================================================
--- trunk/docutils/docs/howto/cmdline-tool.txt 2024-07-22 09:48:35 UTC (rev 9776)
+++ trunk/docutils/docs/howto/cmdline-tool.txt 2024-07-22 11:51:25 UTC (rev 9777)
@@ -67,7 +67,7 @@
"reStructuredText" Parser, etc.). The HTML Writer is chosen by name,
and a description for command-line help is passed in::
- publish_cmdline(writer_name='html', description=description)
+ publish_cmdline(writer='html', description=description)
That's it! `The Docutils Publisher`_ takes care of the rest.
Modified: trunk/docutils/docs/ref/doctree.txt
===================================================================
--- trunk/docutils/docs/ref/doctree.txt 2024-07-22 09:48:35 UTC (rev 9776)
+++ trunk/docutils/docs/ref/doctree.txt 2024-07-22 11:51:25 UTC (rev 9777)
@@ -1472,12 +1472,13 @@
generic ``field`` element. Also note that the "RCSfile" keyword
syntax has been stripped from the "Filename" data.
-See `\<field_list>`_ for an example in a non-bibliographic context. Also
-see the individual examples for the various `bibliographic elements`_.
+See `\<field_list>`_ for a `reStructuredText field list`_ example
+in a non-bibliographic context. Also see the individual examples
+for the various `bibliographic elements`_.
.. [#abstract-dedication] Exceptions are the fields "abstract" and
- "dedication" that are transformed to `\<topic>`_ elements adjacent to
- the <docinfo>.
+ "dedication" that are transformed to `\<topic>`_ elements
+ adjacent to the <docinfo>.
<doctest_block>
@@ -4646,7 +4647,8 @@
source text that was used to produce the document tree.
It is one of the `common attributes`_, declared for all Docutils
-elements but typically only used on the `root element`_.
+elements but typically only used with the `\<document>`_ and
+`\<system_message>`_ elements.
.. note:: All ``docutils.nodes.Node`` instances also support an
*internal* ``source`` attribute that is used when reporting
@@ -5317,6 +5319,7 @@
.. _option list: rst/restructuredtext.html#option-lists
.. _RCS Keywords: rst/restructuredtext.html#rcs-keywords
.. _rST document: rst/restructuredtext.html#document
+.. _reStructuredText field list:
.. _rST field list: rst/restructuredtext.html#field-lists
.. _rST reference names: rst/restructuredtext.html#reference-names
.. _rST tables: rst/restructuredtext.html#tables
Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt 2024-07-22 09:48:35 UTC (rev 9776)
+++ trunk/docutils/docs/user/config.txt 2024-07-22 11:51:25 UTC (rev 9777)
@@ -228,7 +228,6 @@
.. _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
@@ -249,7 +248,7 @@
A trailing "%" is replaced with the tag name (new in Docutils 0.16).
-:Default: "%" (changed in 0.18 from "id").
+:Default: "%" (changed from "id" in Docutils 0.18).
:Option: ``--auto-id-prefix`` (hidden, intended mainly for programmatic use).
.. _identifier normalization:
@@ -331,7 +330,7 @@
error_encoding
--------------
-The text encoding for error output.
+The text encoding [#encodings]_ for error output.
:Default: The encoding reported by ``sys.stderr``, locale encoding, or "ascii".
:Options: ``--error-encoding``, ``-e``.
@@ -415,19 +414,12 @@
input_encoding
--------------
-The text encoding for input.
+The text encoding [#encodings]_ for input.
-*Default*: utf-8. [#]_
-*Option*: ``--input-encoding`` [#i-o-options]_
+:Default: utf-8 (changed from None (auto-detect_) in Docutils 0.22).
+:Option: ``--input-encoding`` (shortcut ``-i`` removed in Docutils 0.22).
-.. [#] The default changed from None (auto-detect_) to "utf-8" in
- Docutils 0.22.
-.. [#i-o-options] The short options ``-i`` and ``-o`` were removed
- in Docutils 0.22.
-.. _auto-detect: ../api/publisher.html#encodings
-
-
input_encoding_error_handler
----------------------------
@@ -496,15 +488,25 @@
output_encoding
---------------
-The text encoding for output.
+The text encoding [#encodings]_ for output.
+The special value "unicode" can be used with
+the Publisher convenience functions `publish_string()`_ and
+`publish_from_doctree()`_ to skip encoding and return a `str` instance
+instead of `bytes`.
-The "output_encoding" setting may also affect the content of the output
-(e.g. an encoding declaration in HTML or XML or the representation of
-characters as LaTeX macro vs. literal character).
+.. Note::
+ * The "output_encoding" setting may affect the content of the output
+ (e.g. an encoding declaration in HTML or XML or the representation
+ of characters as LaTeX macro vs. literal character).
+ * Docutils may introduce non-ASCII text if you use
+ `auto-symbol footnotes`_.
+ In non-English documents, also auto-generated labels
+ may contain non-ASCII characters.
This setting is ignored by the `ODF/ODT Writer`_ which always usues UTF-8.
-*Default*: "utf-8". *Option*: ``--output-encoding``. [#i-o-options]_
+:Default: "utf-8".
+:Option: ``--output-encoding`` (shortcut ``-o`` removed in Docutils 0.22).
output_encoding_error_handler
@@ -1449,7 +1451,7 @@
.. class:: run-in narrow
:initial_header_level_: 2 (reserve <h1> for the `document title`_). [#]_
-:`math_output`_: "MathML" (changed in Docutils 0.22).
+:`math_output`_: "MathML" (changed from "HTML math.css"in Docutils 0.22).
:`stylesheet_path <stylesheet_path [html writers]_>`__:
"minimal.css, plain.css".
:`xml_declaration <xml_declaration [html writers]_>`__: False.
@@ -2302,8 +2304,8 @@
parser
~~~~~~
Parser component name.
-Either "`rst <[restructuredtext parser]_>`__" (default),
-"`xml <[xml parser]_>`__", or the import name of a plug-in parser module.
+Either "`rst <[restructuredtext parser]_>`__", "`xml <[xml parser]_>`__",
+or the import name of a plug-in parser module.
Parsers for CommonMark_ known to work with Docutils include
"`pycmark <[pycmark parser]_>`__", "`myst <[myst parser]_>`__",
@@ -2404,6 +2406,9 @@
sources to a list instead of overriding previous values.
The corresponding command line options may be used more than once.
+.. [#encodings] Docutils supports all `standard encodings`_ and encodings
+ registered__ with the codecs_ module.
+
.. [#pwd] Filesystem path relative to the working directory of the
process at launch.
Exception: Path settings in configuration files specified by the
@@ -2411,7 +2416,9 @@
buildhtml_ application are resolved relative to the directory of
the respective configuration file.
+__ https://docs.python.org/3/library/codecs.html#codecs.register
+
Old-Format Configuration Files
==============================
@@ -2434,6 +2441,53 @@
pep_template [pep_html writer] template
===================== =====================================
+
+.. _auto-detect:
+
+Input Encoding Auto-Detection
+=============================
+
+Up to Docutils 0.21, the input_encoding_ default value was ``None`` and
+the actual input encoding detected from a `Unicode byte order mark` (BOM_)
+or an `encoding declaration`_ in the source.
+
+The default input encoding changed to "utf-8" in Docutils 0.22.
+Currently, auto-detection can be selected with an input_encoding_ value
+``None`` (rsp. an empty string in a configuration file).
+However, **this feature** is deprecated and **will be removed** in
+Docutils 1.0. See the `inspecting_codecs`_ package for a replacement.
+
+Encoding Declaration
+--------------------
+
+Input encoding auto-detection scans the source for an
+*encoding declaration* inspired by :PEP:`263`:
+
+A comment like ::
+
+ .. text encoding: <encoding name>
+
+on the first or second line defines `<encoding name>`
+as the source's input encoding.
+
+Examples: (using formats recognized by popular editors) ::
+
+ .. -*- mode: rst -*-
+ -*- coding: latin1 -*-
+
+or::
+
+ .. vim: set fileencoding=cp737 :
+
+More precisely, the first and second line are searched for the following
+regular expression::
+
+ coding[:=]\s*([-\w.]+)
+
+The first group of this expression is then interpreted as encoding name.
+If the first line matches the second line is ignored.
+
+
.. References
.. _Docutils Document Tree:
@@ -2443,6 +2497,8 @@
.. _runtime settings: ../api/runtime-settings.html
.. _Publisher Interface: ../api/publisher.html
+.. _publish_string(): ../api/publisher.html#publish-string
+.. _publish_from_doctree(): ../api/publisher.html#publish-from-doctree
.. RestructuredText Directives
.. _"class" directive: ../ref/rst/directives.html#class
@@ -2461,6 +2517,8 @@
.. _table of contents: ../ref/rst/directives.html#table-of-contents
.. RestructuredText Markup Specification
+.. _auto-symbol footnotes:
+ ../ref/rst/restructuredtext.html#auto-symbol-footnotes
.. _abstract:
.. _bibliographic field list:
.. _bibliographic fields:
@@ -2490,3 +2548,9 @@
.. _ISO 3166: http://www.iso.ch/iso/en/prods-services/iso3166ma/
02iso-3166-code-lists/index.html
.. _language tag: https://www.w3.org/International/articles/language-tags/
+
+.. _codecs: https://docs.python.org/3/library/codecs.html
+.. _standard encodings:
+ https://docs.python.org/3/library/codecs.html#standard-encodings
+.. _BOM: https://docs.python.org/3/library/codecs.html#codecs.BOM
+.. _inspecting_codecs: https://codeberg.org/milde/inspecting-codecs
Modified: trunk/docutils/docs/user/tools.txt
===================================================================
--- trunk/docutils/docs/user/tools.txt 2024-07-22 09:48:35 UTC (rev 9776)
+++ trunk/docutils/docs/user/tools.txt 2024-07-22 11:51:25 UTC (rev 9777)
@@ -16,11 +16,11 @@
Introduction
--------------
-In addition to the `generic command line front end`_, Docutils installs
-a set of small front ends, each specialized for a specific "Reader" (which
-knows how to interpret a file in context), a "Parser" (which
-understands the syntax of the text), and a "Writer" (which knows how
-to generate a specific data format).
+In addition to the generic "docutils_" application, Docutils installs
+a set of small front ends, each specialized for a specific
+"Reader" (which knows how to interpret a file in context),
+"Parser" (which understands the syntax of the text), and
+"Writer" (which knows how to generate a specific data format).
.. note::
Docutils front-end tool names, install details and the set of
@@ -78,6 +78,9 @@
Generic Command Line Front End
==============================
+docutils
+--------
+
:CLI name: ``docutils``
:Readers: Standalone (default), PEP
:Parsers: reStructuredText (default), Markdown (requires 3rd party packages)
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
_______________________________________________
Docutils-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-checkins