From 8a046b37599004fc6409daaf009eec358223052d Mon Sep 17 00:00:00 2001 From: milde Date: Wed, 3 May 2023 11:01:03 +0000 Subject: Documentation update. git-svn-id: https://svn.code.sf.net/p/docutils/code/trunk@9370 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docutils/HISTORY.txt | 2 +- docutils/RELEASE-NOTES.txt | 149 +++++++++++++++++++++++-------------------- docutils/docs/user/tools.txt | 136 +++++++++++++++++++-------------------- 3 files changed, 150 insertions(+), 137 deletions(-) diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt index 48de19fdb..f26450e40 100644 --- a/docutils/HISTORY.txt +++ b/docutils/HISTORY.txt @@ -28,7 +28,7 @@ Release 0.20 (unpublished) * docutils/frontend.py - - New configuration setting output_. Obsoletes the ```` + - New configuration setting "output_". Obsoletes the ```` positional argument (cf. `Future changes` in the RELEASE-NOTES_). * docutils/languages/ diff --git a/docutils/RELEASE-NOTES.txt b/docutils/RELEASE-NOTES.txt index 6a5bfc35a..1c076a394 100644 --- a/docutils/RELEASE-NOTES.txt +++ b/docutils/RELEASE-NOTES.txt @@ -12,7 +12,7 @@ :Copyright: This document has been placed in the public domain. -This document summarizes the major changes in recent and upcoming releases. +This document summarizes the major changes in previous and upcoming releases. For a more detailed list of changes, please see the Docutils `HISTORY`_. .. contents:: @@ -22,61 +22,44 @@ Future changes Drop support for Python 3.7 and 3.8 in Docutils 0.21. -* Usage: +Command line interface +---------------------- - - Docutils 0.21 will provide ``rst2*`` `"console_scripts" entry - points`_ (without the ``.py`` extension) instead of installing the - ``rst2*.py`` `front end tools`_ in the binary PATH. [#]_ +* Docutils 0.21 will provide ``rst2*`` "console_scripts" `entry points`_ + (without the ``.py`` extension) instead of installing the + ``rst2*.py`` `front end tools`_ in the binary PATH. [#]_ - You may use the ``docutils`` `generic command line front end tool`_ - as a future-proof command, for example: + You may use the ``docutils`` `generic command line front end tool`_ + as a future-proof command, for example: - .. code:: diff - - - rst2latex.py --use-latex-abstract FAQ.txt > FAQ.tex - + docutils --writer=latex --use-latex-abstract FAQ.txt > FAQ.tex - - Exceptions: - The auxilliary script ``rst2odt_prepstyles.py`` will become - available via ``python -m docutils.writers.odf_odt.prepstyles``. - - The ``rstpep2html.py`` script will be retired. - Use ``docutils --reader=pep --writer=pep_html`` for a PEP preview - (the final rendering is done by a Sphinx-based build system, - cf. :PEP:`676`). - - - .. [#] Some Linux distributions already use the short names. - - .. _"console_scripts" entry points: - https://packaging.python.org/en/latest/specifications/entry-points/ + .. code:: diff - - The `default HTML writer`__ will change in Docutils 2.0: + - rst2latex.py --use-latex-abstract FAQ.txt > FAQ.tex + + docutils --writer=latex --use-latex-abstract FAQ.txt > FAQ.tex - The rst2html_ front end and ``get_writer_by_name('html')`` select - "html4css1" now and will select "html5" in Docutils 2.0 and later. + Exceptions: + The auxilliary script ``rst2odt_prepstyles.py`` will become + available via ``python -m docutils.writers.odf_odt.prepstyles``. - * Use rst2html4_, ``docutils --writer=html4``, or - ``get_writer_by_name('html4')`` if you depend on stability of the - generated HTML code, e.g. because you use a custom style sheet or - post-processing that may break otherwise. - * Use rst2html5_, ``docutils`` or ``get_writer_by_name('html5')`` - if you want a HTML5 document. + The ``rstpep2html.py`` script will be retired. + Use ``docutils --reader=pep --writer=pep_html`` for a PEP preview + (the final rendering is done by a Sphinx-based build system, + cf. :PEP:`676`). - __ docs/user/html.html#html + .. [#] Some Linux distributions already use the short names. * The _`command-line usage pattern` will change: .. code:: diff - - [options] [ []] - + [options] source [source2 [source3 [...]]] + - COMMAND [OPTIONS] [SOURCE [DESTINATION]] + + COMMAND [OPTIONS] [SOURCE [SOURCE2 [...]]] [>DESTINATION] * Remove short options ``-i`` and ``-o`` in Docutils 0.22. Use the long equivalents ``--input-encoding`` and ``--output-encoding``. - * Stop accepting the `` positional argument in Docutils 1.0. - Use output redirection ``>`` or the option ``--output=`` + * Stop accepting the DESTINATION positional argument in Docutils 1.0. + Use output redirection or the option ``--output=DESTINATION`` (available since Docutils 0.20). * Accept more than one source document and the short option @@ -84,35 +67,45 @@ Drop support for Python 3.7 and 3.8 in Docutils 0.21. For the rationale, see https://clig.dev/#arguments-and-flags. -* `Input encoding`_: +.. _entry points: + https://packaging.python.org/en/latest/specifications/entry-points/ - - Raise UnicodeError (instead of falling back to the locale encoding) - if decoding the source with the default encoding (UTF-8) fails and - Python is started in `UTF-8 mode`_. (Docutils 0.21) - Raise UnicodeError (instead of falling back to "latin1") if both, - default and locale encoding, fail. (Docutils 0.21) +`Input encoding`_ +----------------- - - Only remove BOM (U+FEFF ZWNBSP at start of data), no other ZWNBSPs. - Only remove BOM with `input_encoding`_ values None, '', 'utf-8-sig', - 'utf-16', and 'utf-32'. (Docutils 0.21) +* Raise UnicodeError (instead of falling back to the locale encoding) + if decoding the source with the default encoding (UTF-8) fails and + Python is started in `UTF-8 mode`_. (Docutils 0.21) - - Change the default input encoding from ``None`` (auto-detect) to - "utf-8" in Docutils 0.22. + Raise UnicodeError (instead of falling back to "latin1") if both, + default and locale encoding, fail. (Docutils 0.21) - - Remove the input encoding auto-detection code in Docutils 1.0 or later. +* Only remove BOM (U+FEFF ZWNBSP at start of data), no other ZWNBSPs. + Only remove BOM with `input_encoding`_ values None, '', 'utf-8-sig', + 'utf-16', and 'utf-32'. (Docutils 0.21) -* "csv-table_" directive: +* Change the default input encoding from ``None`` (auto-detect) to + "utf-8" in Docutils 0.22. - - Use the same CSV format for the main CSV data and the :header: option - (as specified in the documentation since addition of "csv-table_") - in Docutils 0.21. +* Remove the input encoding auto-detection code in Docutils 1.0 or later. - - Move `parsers.rst.directives.Table.process_header_option()` to - `parsers.rst.directives.CSVTable` in Docutils 0.21. +Writers +------- - - Remove `parsers.rst.directives.CSVTable.HeaderDialect` - in Docutils 0.22. +* The `default HTML writer`__ will change in Docutils 2.0: + + The rst2html_ front end and ``get_writer_by_name('html')`` select + "html4css1" now and will select "html5" in Docutils 2.0 and later. + + - Use rst2html4_, ``docutils --writer=html4``, or + ``get_writer_by_name('html4')`` if you depend on stability of the + generated HTML code, e.g. because you use a custom style sheet or + post-processing that may break otherwise. + - Use rst2html5_, ``docutils`` or ``get_writer_by_name('html5')`` + if you want a HTML5 document. + + __ docs/user/html.html#html * "html5" writer: @@ -147,28 +140,49 @@ Drop support for Python 3.7 and 3.8 in Docutils 0.21. * "null" writer: output will change to the empty string in Docutils 0.22. -* Remove the "rawsource" argument from `nodes.Text.__init__()` - (deprecated and ignored since Docutils 0.18) in Docutils 2.0. +Misc +---- + +* "csv-table_" directive: + + - Use the same CSV format for the main CSV data and the :header: option + (as specified in the documentation since addition of "csv-table_") + in Docutils 0.21. + + - Move `parsers.rst.directives.Table.process_header_option()` to + `parsers.rst.directives.CSVTable` in Docutils 0.21. + + - Remove `parsers.rst.directives.CSVTable.HeaderDialect` + in Docutils 0.22. * Remove the compatibility hacks `nodes.reprunicode` and `nodes.ensure_str()` in Docutils 0.21 or later. They are not required with Python 3.x. -* Drop support for `old-format configuration files`_ in Docutils 2.0. - * Remove file ``install.py`` in Docutils 0.21. See README.txt__ for alternatives. __ README.html#installation -* Move math format conversion from docutils/utils/math (called from - docutils/writers/_html_base.py) to a transform__. +* Remove the "rawsource" argument from `nodes.Text.__init__()` + in Docutils 2.0. - __ docs/ref/transforms.html +* Drop support for `old-format configuration files`_ in Docutils 2.0. * Remove the ``--html-writer`` option of the `buildhtml.py`_ application (obsoleted by the `"writer" setting`_ since Docutils 0.18) in Docutils 2.0. +* Revise the `String I/O`__ interface used by the `publish_string()` + and `publish_from_doctree()` publisher convenience functions. + (In Python 3, name and behaviour no longer match.) + + __ docs/api/publisher.html#string-i-o + +* Move math format conversion from docutils/utils/math (called from + docutils/writers/_html_base.py) to a transform__. + + __ docs/ref/transforms.html + .. _front end tools: docs/user/tools.html .. _input encoding: .. _input_encoding: docs/user/config.html#input-encoding @@ -187,7 +201,6 @@ Drop support for Python 3.7 and 3.8 in Docutils 0.21. .. _buildhtml.py: docs/user/tools.html#buildhtml-py .. _csv-table: docs/ref/rst/directives.html#csv-table - Release 0.20 (unpublished) ========================== diff --git a/docutils/docs/user/tools.txt b/docutils/docs/user/tools.txt index 99979f242..1e521d1bb 100644 --- a/docutils/docs/user/tools.txt +++ b/docutils/docs/user/tools.txt @@ -12,26 +12,12 @@ .. contents:: -.. note:: - Docutils front-end tool names, install details and the set of - auto-installed tools will change in Docutils 0.21. - - The command line usage pattern will change over the next releases. - - See `Future changes`__ in the RELEASE-NOTES. - -__ RELEASE-NOTES.html#future-changes - - -------------- Introduction -------------- -Once the Docutils package is unpacked, you will discover a ``tools/`` -directory containing several front ends for common Docutils -processing. -In addition to the `generic command line front end`_, Docutils has -many small front ends, each specialized for a specific "Reader" (which +In addition to the `generic command line front end`_, Docutils installs +several 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). @@ -54,6 +40,16 @@ input (stdin) is used for the source. .. [#] The exceptions are buildhtml.py_ and rst2odt_prepstyles.py_. +.. note:: + Docutils front-end tool names, install details and the set of + auto-installed tools will change in Docutils 0.21. + + The command line usage pattern will change over the next releases. + + See `Future changes`_ in the RELEASE-NOTES. + +.. _future changes: ../../RELEASE-NOTES.html#future-changes + Getting Help ============ @@ -110,47 +106,6 @@ to get the correct list of supported command-line options. Example:: HTML-Generating Tools ===================== -buildhtml.py ------------- - -:Readers: Standalone, PEP -:Parser: reStructuredText -:Writers: html_, html5_, pep_html_ -:Config_: `[buildhtml application]`_ - -Use ``buildhtml.py`` to generate ``*.html`` from all the ``*.txt`` files -(including PEPs) in each given, and their subdirectories -too. (Use the ``--local`` option to skip subdirectories.) - -Usage:: - - buildhtml.py [options] [ ...] - -After unpacking the Docutils package, the following shell commands -will generate HTML for all included documentation:: - - cd docutils/tools - buildhtml.py .. - -For official releases, the directory may be called "docutils-X.Y", -where "X.Y" is the release version. Alternatively:: - - cd docutils - tools/buildhtml.py --config=tools/docutils.conf - -The current directory (and all subdirectories) is chosen by default if -no directory is named. Some files may generate system messages -(docs/user/rst/demo.txt contains intentional errors); use the -``--quiet`` option to suppress all warnings. The ``--config`` option -ensures that the correct settings are in place (a ``docutils.conf`` -`configuration file`_ in the current directory is picked up -automatically). Command-line options may be used to override config -file settings or replace them altogether. - -.. _[buildhtml application]: config.html#buildhtml-application -.. _configuration file: `configuration files`_ - - .. _rst2html: rst2html.py @@ -216,11 +171,11 @@ or "`-\-stylesheet-path`_" options. To experiment with styles, please see the `guide to writing HTML (CSS) stylesheets for Docutils`__. +.. _XHTML 1.0 Transitional: https://www.w3.org/TR/xhtml1/ .. _html4css1: html.html#html4css1 .. _link-stylesheet: config.html#embed-stylesheet .. _--stylesheet: config.html#stylesheet .. _--stylesheet-path: config.html#stylesheet-path - __ ../howto/html-stylesheets.html @@ -240,6 +195,8 @@ CSS style sheet. The provided style sheets ``minimal.css`` and ``plain.css`` define required and optional styling rules respectively. .. _html5: html.html#html5 +.. _HTML 5: https://www.w3.org/TR/html5/ + rstpep2html.py -------------- @@ -267,7 +224,6 @@ The same result can be achieved with the genric front end:: The rendering of published PEPs is done by a Sphinx-based build system (see :PEP:`676`). - .. _pep_html: html.html#pep-html @@ -378,10 +334,51 @@ For details, please see `Easy Slide Shows With reStructuredText & S5 `_. -.. _HTML 5: https://www.w3.org/TR/html5/ -.. _HTML 4.1: https://www.w3.org/TR/html401/ -.. _XHTML 1.0 Transitional: https://www.w3.org/TR/xhtml1/ -.. _XHTML 1.1: https://www.w3.org/TR/xhtml1/ +buildhtml.py +------------ + +:Readers: Standalone, PEP +:Parser: reStructuredText +:Writers: html_, html5_, pep_html_ +:Config_: `[buildhtml application]`_ + +The ``buildhtml.py`` script can be found in the ``/tools`` directory of +the "docutils" source. It is not included in binary packages. [#]_ + +Use ``buildhtml.py`` to generate ``*.html`` from all the ``*.txt`` files +(including PEPs) in each given, and their subdirectories +too. (Use the ``--local`` option to skip subdirectories.) + +Usage:: + + buildhtml.py [options] [ ...] + +After unpacking the Docutils source package, the following shell commands +will generate HTML for all included documentation:: + + cd docutils/tools + buildhtml.py .. + +For official releases, the directory may be called "docutils-X.Y", +where "X.Y" is the release version. Alternatively:: + + cd docutils + tools/buildhtml.py --config=tools/docutils.conf + +The current directory (and all subdirectories) is chosen by default if +no directory is named. Some files may generate system messages +(docs/user/rst/demo.txt contains intentional errors); use the +``--quiet`` option to suppress all warnings. The ``--config`` option +ensures that the correct settings are in place (a ``docutils.conf`` +`configuration file`_ in the current directory is picked up +automatically). Command-line options may be used to override config +file settings or replace them altogether. + +.. [#] The Debian package "python3-docutils" includes the script + under the name ``rst-builthtml``. + +.. _[buildhtml application]: config.html#buildhtml-application +.. _configuration file: `configuration files`_ LaTeX-Generating Tools @@ -452,8 +449,8 @@ files and produces troff_ sources for Unix man pages. .. _troff: https://troff.org/ -ODF/OpenOffice-Generating Tools -=============================== +OpenDocument-Generating Tools +============================= rst2odt.py ---------- @@ -478,13 +475,16 @@ For details, see `Odt Writer for Docutils`_. rst2odt_prepstyles.py ````````````````````` -A helper tool to fix a word-processor-generated STYLE_FILE.odt for -odtwriter use:: +A helper tool to prepare a word-processor-generated STYLE_FILE.odt for +use with the "odt" writer: [#]_ :: - rst2odt_prepstyles STYLE_FILE.odt + rst2odt_prepstyles.py STYLE_FILE.odt See `Odt Writer for Docutils`__ for details. +.. [#] The call pattern will change in Docutils 0.20, see + `Future changes`_ in the RELEASE-NOTES. + __ odt.html#page-size -- cgit v1.2.1