[Docutils-checkins] SF.net SVN: docutils:[9061] trunk/docutils

[<mi...@us...>]

Revision: 9061
          http://sourceforge.net/p/docutils/code/9061
Author:   milde
Date:     2022-05-30 16:54:46 +0000 (Mon, 30 May 2022)
Log Message:
-----------
Command line "entry point" to the docutils package. Part 2/2.

Support ``python -m docutils`` with new module `docutils.__main__`.

Support ``docutils`` CLI command via "entry point" in setup.py.

Keep tools/docutils-cli.py for backwards compatibility
and manual installation.
Calls `docutils.__main__.main()`.

Thanks to Adam Turner for contributions and review.

Modified Paths:
--------------
    trunk/docutils/COPYING.txt
    trunk/docutils/HISTORY.txt
    trunk/docutils/README.txt
    trunk/docutils/RELEASE-NOTES.txt
    trunk/docutils/docs/dev/todo.txt
    trunk/docutils/docs/user/config.txt
    trunk/docutils/docs/user/tools.txt
    trunk/docutils/docutils/__main__.py
    trunk/docutils/docutils/core.py
    trunk/docutils/setup.py

Added Paths:
-----------
    trunk/docutils/test/data/help/
    trunk/docutils/test/data/help/docutils.txt
    trunk/docutils/tools/docutils-cli.py

Modified: trunk/docutils/COPYING.txt
===================================================================
--- trunk/docutils/COPYING.txt	2022-05-30 16:54:33 UTC (rev 9060)
+++ trunk/docutils/COPYING.txt	2022-05-30 16:54:46 UTC (rev 9061)
@@ -99,13 +99,18 @@
 
   .. _eLyXer: https://github.com/alexfernandez/elyxer
 
-* docutils/parsers/recommonmark_wrapper.py,
+* docutils/__main__.py,
+  docutils/parsers/commonmark_wrapper.py,
+  docutils/parsers/recommonmark_wrapper.py,
   docutils/utils/error_reporting.py,
   docutils/utils/math/__init__.py,
   docutils/utils/math/latex2mathml.py,
   docutils/utils/math/tex2mathml_extern.py,
   docutils/utils/punctuation_chars.py,
+  docutils/utils/smartquotes.py,
   docutils/writers/html5_polyglot/__init__.py,
+  docutils/writers/html5_polyglot/*.css,
+  docutils/writers/latex2e/docutils.sty,
   docutils/writers/xetex/__init__.py,
   test/test_parsers/test_recommonmark/\*.py,
   test/test_parsers/test_rst/test_directives/test__init__.py,

Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt	2022-05-30 16:54:33 UTC (rev 9060)
+++ trunk/docutils/HISTORY.txt	2022-05-30 16:54:46 UTC (rev 9061)
@@ -21,10 +21,15 @@
   - Code cleanup,
     check PEP 8 conformity with `flake8` (exceptions in file tox.ini).
 
+* docutils/__main__.py
+
+  - New module. Support for ``python -m docutils``.
+    Also used for the ``docutils`` console script `entry point`.
+    
 * docutils/core.py:
 
-  `Publisher.publish()`: Print info and prompt when waiting for input from
-  a terminal cf. https://clig.dev/#interactivity.
+  Let `Publisher.publish()` print info and prompt when waiting for input
+  from a terminal (cf. https://clig.dev/#interactivity).
 
 * docutils/parsers/__init__.py
 
@@ -65,7 +70,8 @@
 
 * docutils/transforms/universal.py
 
-  - Fix bug 435: invalid references in `problematic` nodes with report_level=4.
+  - Fix bug #435: invalid references in `problematic` nodes
+    with report_level=4.
 
 * docutils/utils/__init__.py
 
@@ -79,9 +85,8 @@
 
 * docutils/writers/_html_base.py
 
-  - Add 'html writers' to `config_section_dependencies`. Fixes bug #443.
+  - Add "html writers" to `config_section_dependencies`. Fixes bug #443.
   - Write table column widths with 3 digits precision. Fixes bug #444.
-  - Stop writing an empty line before the "footer" closing tag.
 
 * docutils/writers/html5_polyglot/__init__.py
 
@@ -93,7 +98,13 @@
 
   - Use "https:" scheme in "python_home" URL default.
   - Fix links in template.txt.
+  
+* setup.py:
 
+  - New "docutils" console script `entry point`__. Fixes bug #447.
+    
+    __ https://packaging.python.org/en/latest/specifications/entry-points/
+
 * test/DocutilsTestSupport.py
 
   - `exception_data()` now returns None if no exception was raised.
@@ -107,6 +118,7 @@
 
   - Allow 3rd-party drop-in components for reader and parser, too.
   - Fix help output.
+  - Actual code moved to docutils.__main__.py.
 
 
 Release 0.18.1

Modified: trunk/docutils/README.txt
===================================================================
--- trunk/docutils/README.txt	2022-05-30 16:54:33 UTC (rev 9060)
+++ trunk/docutils/README.txt	2022-05-30 16:54:46 UTC (rev 9061)
@@ -149,7 +149,6 @@
     (**not** directly in Python's ``site-packages``) first.
 
   * Run ``setup.py install``.
-    On Windows systems it may be sufficient to double-click ``install.py``.
     See also OS-specific installation instructions below.
 
 * For installing "by hand" or in "development mode", see the

Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt	2022-05-30 16:54:33 UTC (rev 9060)
+++ trunk/docutils/RELEASE-NOTES.txt	2022-05-30 16:54:46 UTC (rev 9061)
@@ -20,11 +20,15 @@
 Future changes
 ==============
 
-* Setup: 
+* Setup:
 
   - Do not install the auxilliary script ``tools/rst2odt_prepstyles.py``
     in the binary PATH.
 
+  - Remove file ``install.py``. There are better ways, see README.txt__.
+
+    __ README.html#installation
+
 * `html5` writer:
 
   - Stop setting the "footnote-reference" class value for footnote
@@ -102,6 +106,11 @@
 
 * Drop support for Python 2.7, 3.5, and 3.6.
 
+* After package installation, the CLI commands ``python -m docutils`` and
+  ``docutils`` start the `generic command line front end tool`__.
+
+  __ docs/user/tools.html#generic-command-line-front-end
+
 * Support parsing "Markdown" input with 3rd party parsers
   myst_, pycmark_, or recommonmark_.
 

Modified: trunk/docutils/docs/dev/todo.txt
===================================================================
--- trunk/docutils/docs/dev/todo.txt	2022-05-30 16:54:33 UTC (rev 9060)
+++ trunk/docutils/docs/dev/todo.txt	2022-05-30 16:54:46 UTC (rev 9061)
@@ -488,7 +488,7 @@
      http://thread.gmane.org/gmane.text.docutils.user/1112
 
 * Add a "disable_transforms" setting? Would allow for easy syntax
-  checking. Where ("null" writer, generic, parser(s), docutils-cli.py)?
+  checking. Where ("null" writer, generic, parser(s))?
   Cf. the `2004-02-18 "rest checking and source path"`_ thread.
 
 * Add a generic meta-stylesheet mechanism?  An external file could
@@ -2834,45 +2834,6 @@
 Front-End Tools
 ===============
 
-* What about if we don't know which Reader and/or Writer we are
-  going to use?  If the Reader/Writer is specified on the
-  command-line?
-
-  The dynamic_ front end ``tools/docutils-cli.py`` (new in 0.17) is an
-  implementation of concept d) below. It uses 2-stage argument parsing
-  via the `argparse` module's `partial parsing`_. It still needs some
-  polishing.
-
-  Perhaps have different types of front ends:
-
-  a) _`Fully qualified`: Reader and Writer are hard-coded into the
-     front end (e.g. ``pep2html [options]``, ``pysource2pdf
-     [options]``).
-
-  b) _`Partially qualified`: Reader is hard-coded, and the Writer is
-     specified a sub-command (e.g. ``pep2 html [options]``,
-     ``pysource2 pdf [options]``).  The Writer is known before option
-     processing happens, allowing the OptionParser to be built
-     dynamically.  Alternatively, the Writer could be hard-coded and
-     the Reader specified as a sub-command (e.g. ``htmlfrom pep
-     [options]``).
-
-  c) _`Unqualified`: Reader and Writer are specified as subcommands
-     (e.g. ``publish pep html [options]``, ``publish pysource pdf
-     [options]``).  A single front end would be sufficient, but
-     probably only useful for testing purposes.
-
-  d) _`Dynamic`: Reader and/or Writer are specified by options, with
-     defaults if unspecified (e.g. ``publish --writer manpage
-     [options]``).
-
-  Allow common options before subcommands, as in CVS?  Or group all
-  options together?  In the case of the `fully qualified`_
-  front ends, all the options will have to be grouped together
-  anyway, so there's no advantage (we can't use it to avoid
-  conflicts) to splitting common and component-specific options
-  apart.
-
 * Parameterize help text & defaults somehow?  Perhaps a callback?  Or
   initialize ``settings_spec`` in ``__init__`` or ``init_options``?
 

Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt	2022-05-30 16:54:33 UTC (rev 9060)
+++ trunk/docutils/docs/user/config.txt	2022-05-30 16:54:46 UTC (rev 9061)
@@ -849,7 +849,6 @@
 __ https://pypi.org/project/pycmark/
 
 
-
 .. _recommonmark:
 
 [recommonmark parser]
@@ -2164,10 +2163,11 @@
 .. _HTML writer: html.html
 
 
-[docutils-cli application]
+[docutils application]
 --------------------------
 
 New in 0.17. Config file support added in 0.18.
+Renamed in 0.19 (the old name "docutils-cli application" is kept as alias).
 Support for reader/parser import names added in 0.19.
 
 reader
@@ -2190,8 +2190,11 @@
 Default: "rst".
 Option: ``--parser``
 
-.. _writer [docutils-cli application]:
+.. _CommonMark: https://spec.commonmark.org/0.30/
 
+
+.. _writer [docutils application]:
+
 writer
 ~~~~~~
 Writer component name.
@@ -2202,9 +2205,7 @@
 Default: "html5".
 Option: ``--writer``
 
-.. _CommonMark: https://spec.commonmark.org/0.30/
 
-
 Other Settings
 ==============
 

Modified: trunk/docutils/docs/user/tools.txt
===================================================================
--- trunk/docutils/docs/user/tools.txt	2022-05-30 16:54:33 UTC (rev 9060)
+++ trunk/docutils/docs/user/tools.txt	2022-05-30 16:54:46 UTC (rev 9061)
@@ -17,10 +17,10 @@
  Introduction
 --------------
 
-Once the Docutils package is unpacked, you will discover a "``tools``"
+Once the Docutils package is unpacked, you will discover a ``tools/``
 directory containing several front ends for common Docutils
 processing.
-In addition to the all-purpose program docutils-cli.py_, Docutils has
+In addition to the `generic command line front end`_, Docutils has
 many 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
@@ -27,11 +27,10 @@
 to generate a specific data format).
 
 Most [#]_ front ends have common options and the same command-line usage
-pattern::
+pattern (see `the tools`_ below for concrete examples)::
 
     toolname [options] [<source> [<destination>]]
 
-See rst2html4.py_ for examples.
 Each tool has a "``--help``" option which lists the
 `command-line options`_ and arguments it supports.
 Processing can also be customized with `configuration files`_.
@@ -70,35 +69,38 @@
 Generic Command Line Front End
 ==============================
 
-docutils-cli.py
----------------
-
 :Readers: Standalone, PEP
-:Parser: reStructuredText, Markdown (reCommonMark)
+:Parsers: reStructuredText, Markdown (requires 3rd party packages)
 :Writers: html_, html4css1_, html5_, latex__, manpage_,
           odt_, pep_html_, pseudo-xml_, s5_html_, xelatex_, xml_,
-:Config_: See `[docutils-cli application]`_
+:Config_: See `[docutils application]`_
 
-The ``docutils-cli.py`` front allows combining reader, parser, and
-writer components.
+The generic front end allows combining "reader", "parser", and
+"writer" components from the Docutils package or 3rd party plug-ins.
 
+Since Docutils 0.19, it can be called by Python's ``-m`` option,
+the ``docutils`` script installed in the binary PATH, or the
+``docutils-cli.py`` script in the ``tools/`` directory.
+
 For example, to process a Markdown_ file "``test.md``" into
 Pseudo-XML_ ::
 
-    docutils-cli.py --parser=markdown --writer=pseudoxml\
+    python3 -m docutils --parser=markdown --writer=pseudoxml\
       test.md test.txt
 
 Use the "--help" option together with the component-selection options
 to get the correct list of supported command-line options. Example::
 
-    docutils-cli.py --parser=markdown --writer=xml --help
+    docutils --parser=markdown --writer=xml --help
 
+
+
 __
 .. _latex2e:
 .. _Generating LaTeX with Docutils: latex.html
 .. _manpage: manpage.html
 .. _Markdown: https://www.markdownguide.org/
-.. _[docutils-cli application]: config.html#docutils-cli-application
+.. _[docutils application]: config.html#docutils-application
 
 
 HTML-Generating Tools
@@ -157,15 +159,12 @@
 Docutils, and the web. Currently, it is html4css1_.
 
 .. caution::
-   Use docutils-cli.py_ with the `"writer" option`__ or
-   a specific front end like rst2html4.py_ or rst2html5.py_,
+   Use a specific front end like rst2html4.py_ or rst2html5.py_,
    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).
 
-   __ config.html#writer-docutils-cli-application
 
-
 rst2html4.py
 ------------
 

Modified: trunk/docutils/docutils/__main__.py
===================================================================
--- trunk/docutils/docutils/__main__.py	2022-05-30 16:54:33 UTC (rev 9060)
+++ trunk/docutils/docutils/__main__.py	2022-05-30 16:54:46 UTC (rev 9061)
@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-# :Copyright: © 2020 Günter Milde.
+# :Copyright: © 2020, 2022 Günter Milde.
 # :License: Released under the terms of the `2-Clause BSD license`_, in short:
 #
 #    Copying and distribution of this file, with or without modification,
@@ -12,9 +12,11 @@
 # Revision: $Revision$
 # Date: $Date$
 
+"""Generic command line interface for the `docutils` package.
+
+See also
+https://docs.python.org/3/library/__main__.html#main-py-in-python-packages
 """
-A generic front end to the Docutils Publisher.
-"""
 
 import argparse
 import locale
@@ -21,69 +23,55 @@
 import sys
 
 import docutils
-from docutils.core import Publisher, publish_cmdline
+from docutils.core import Publisher, publish_cmdline, default_description
 
 
 class CliSettingsSpec(docutils.SettingsSpec):
-    """Runtime settings & command-line options for the generic CLI."""
+    """Runtime settings & command-line options for the generic CLI.
 
+    Configurable reader, parser, and writer components.
+
+    The "--writer" default will change to 'html' when this becomes
+    an alias for 'html5'.
+    """
+
     settings_spec = (
-        'Docutils CLI Options',
-        None,
+        'Docutils Application Options',
+        'Reader, writer, and parser settings influence the available options. '
+        'Example: use `--help --writer=latex` to see LaTeX writer options. ',
         # options: ('help text', [<option strings>], {<keyword arguments>})
-        (('Reader name (default/current: "%default").',
-          ['--reader'], {'metavar': '<reader>'}),
-         ('Parser name (default/current: "%default").',
-          ['--parser'], {'metavar': '<parser>'}),
-         ('Writer name (default/current: "%default").',
-          ['--writer'], {'metavar': '<writer>'}),
+        (('Reader name (currently: "%default").',
+          ['--reader'], {'default': 'standalone', 'metavar': '<reader>'}),
+         ('Parser name (currently: "%default").',
+          ['--parser'], {'default': 'rst', 'metavar': '<parser>'}),
+         ('Writer name (currently: "%default").',
+          ['--writer'], {'default': 'html5', 'metavar': '<writer>'}),
          )
     )
-    config_section = 'docutils-cli application'
-    config_section_dependencies = ('applications',)
+    config_section = 'docutils application'
+    config_section_dependencies = ('docutils-cli application',  # back-compat
+                                   'applications')
 
 
-def main(settings_spec=CliSettingsSpec,
-         reader='standalone', parser='rst', writer='html'):
+def main():
     """Generic command line interface for the Docutils Publisher.
     """
     locale.setlocale(locale.LC_ALL, '')
 
-    description = ('Convert plaintext documentation into useful formats.  '
-                   'Available options depend on the selected reader, '
-                   'writer, and parser.  '
-                   + docutils.core.default_description)
+    description = ('Convert documents into useful formats.  '
+                   + default_description)
 
-    default_settings = Publisher().get_settings(settings_spec=settings_spec,
-                                                reader=reader,
-                                                parser=parser,
-                                                writer=writer)
+    # Update component selection from config file(s)
+    components = Publisher().get_settings(settings_spec=CliSettingsSpec)
 
-    # Pre-parse the command-line with "argparse" for component-setting options
-    argparser = argparse.ArgumentParser(add_help=False)
-    argparser.add_argument('--reader', default=default_settings.reader)
-    argparser.add_argument('--parser', default=default_settings.parser)
-    argparser.add_argument('--writer', default=default_settings.writer)
+    # Update component selection from command-line
+    argparser = argparse.ArgumentParser(add_help=False, allow_abbrev=False)
+    argparser.add_argument('--reader', default=components.reader)
+    argparser.add_argument('--parser', default=components.parser)
+    argparser.add_argument('--writer', default=components.writer)
+    # other options are parsed in a second pass via `publish_cmdline()`
     (args, remainder) = argparser.parse_known_args()
-
-    # TODO: require source ('-' for stdin)
-    # argparser.add_argument('source')
-    # argparser.add_argument('destination', nargs='?')
-    #
-    # print usage if there is no arg
-    # (always or if sys.stdout.isatty() ?)
-    # Alternatively, print a log message to stderr.
-    #
-    # Display output on success, but keep it brief.
-    # provide a -q option to suppress all non-essential output.
-    #
-    # Consider chaining several args as input
-    # and use --output (or redirection) for output
-    # argparser.add_argument('source', nargs='+')
-    #
-    # -- https://clig.dev/#help
-
-    # Update defaults (shown in help):
+    # Ensure the current component selections are shown in help:
     CliSettingsSpec.settings_default_overrides = args.__dict__
 
     try:
@@ -90,7 +78,7 @@
         publish_cmdline(reader_name=args.reader,
                         parser_name=args.parser,
                         writer_name=args.writer,
-                        settings_spec=settings_spec,
+                        settings_spec=CliSettingsSpec,
                         description=description,
                         argv=remainder)
     except ImportError as error:
@@ -102,5 +90,7 @@
 
 
 if __name__ == '__main__':
-    # backwards compatibility: docutils-cli.py defaults to "html5" writer:
-    main(writer='html5')
+    if sys.argv[0].endswith('__main__.py'):
+        # fix "usage" message
+        sys.argv[0] = '%s -m docutils' % sys.executable
+    main()

Modified: trunk/docutils/docutils/core.py
===================================================================
--- trunk/docutils/docutils/core.py	2022-05-30 16:54:33 UTC (rev 9060)
+++ trunk/docutils/docutils/core.py	2022-05-30 16:54:46 UTC (rev 9061)
@@ -277,7 +277,7 @@
         except AttributeError:
             return
         eot_key = 'Ctrl+Z' if os.name == 'nt' else 'Ctrl+D on an empty line'
-        in_format = 'plaintext'
+        in_format = ''
         out_format = 'useful formats'
         try:
             in_format = self.parser.supported[0]
@@ -350,12 +350,20 @@
 
 default_usage = '%prog [options] [<source> [<destination>]]'
 default_description = (
-    'Reads from <source> (default is stdin) and writes to <destination> '
-    '(default is stdout). '
+    'Reads from <source> (default is stdin) '
+    'and writes to <destination> (default is stdout).  '
     'See https://docutils.sourceforge.io/docs/user/config.html '
-    ' for the full reference.')
+    'for a detailed settings reference.')
 
 
+# TODO: or not to do?  cf. https://clig.dev/#help
+#
+# Display output on success, but keep it brief.
+#
+# Provide a -q option to suppress all non-essential output.
+# Chain several args as input and use --output or redirection for output:
+#   argparser.add_argument('source', nargs='+')
+#
 def publish_cmdline(reader=None, reader_name='standalone',
                     parser=None, parser_name='restructuredtext',
                     writer=None, writer_name='pseudoxml',

Modified: trunk/docutils/setup.py
===================================================================
--- trunk/docutils/setup.py	2022-05-30 16:54:33 UTC (rev 9060)
+++ trunk/docutils/setup.py	2022-05-30 16:54:46 UTC (rev 9061)
@@ -67,6 +67,9 @@
         'docutils.writers.xetex',
         'docutils.writers.odf_odt',
     ],
+    'entry_points': {
+        'console_scripts': ['docutils=docutils.__main__:main']
+    },
     'scripts': [
         'tools/rst2html.py',
         'tools/rst2html4.py',

Added: trunk/docutils/test/data/help/docutils.txt
===================================================================
--- trunk/docutils/test/data/help/docutils.txt	                        (rev 0)
+++ trunk/docutils/test/data/help/docutils.txt	2022-05-30 16:54:46 UTC (rev 9061)
@@ -0,0 +1,216 @@
+Usage
+=====
+  docutils [options] [<source> [<destination>]]
+
+Convert documents into useful formats.  Reads from <source> (default is stdin)
+and writes to <destination> (default is stdout).  See
+https://docutils.sourceforge.io/docs/user/config.html for a detailed settings
+reference.
+
+Options
+=======
+General Docutils Options
+------------------------
+--title=TITLE           Specify the document title as metadata.
+--generator, -g         Include a "Generated by Docutils" credit and link.
+--no-generator          Do not include a generator credit.
+--date, -d              Include the date at the end of the document (UTC).
+--time, -t              Include the time & date (UTC).
+--no-datestamp          Do not include a datestamp of any kind.
+--source-link, -s       Include a "View document source" link.
+--source-url=<URL>      Use <URL> for a source link; implies --source-link.
+--no-source-link        Do not include a "View document source" link.
+--toc-entry-backlinks   Link from section headers to TOC entries.  (default)
+--toc-top-backlinks     Link from section headers to the top of the TOC.
+--no-toc-backlinks      Disable backlinks to the table of contents.
+--footnote-backlinks    Link from footnotes/citations to references. (default)
+--no-footnote-backlinks
+                        Disable backlinks from footnotes and citations.
+--section-numbering     Enable section numbering by Docutils.  (default)
+--no-section-numbering  Disable section numbering by Docutils.
+--strip-comments        Remove comment elements from the document tree.
+--leave-comments        Leave comment elements in the document tree. (default)
+--strip-elements-with-class=<class>
+                        Remove all elements with classes="<class>" from the
+                        document tree. Warning: potentially dangerous; use
+                        with caution. (Multiple-use option.)
+--strip-class=<class>   Remove all classes="<class>" attributes from elements
+                        in the document tree. Warning: potentially dangerous;
+                        use with caution. (Multiple-use option.)
+--report=<level>, -r <level>
+                        Report system messages at or higher than <level>:
+                        "info" or "1", "warning"/"2" (default), "error"/"3",
+                        "severe"/"4", "none"/"5"
+--verbose, -v           Report all system messages.  (Same as "--report=1".)
+--quiet, -q             Report no system messages.  (Same as "--report=5".)
+--halt=<level>          Halt execution at system messages at or above <level>.
+                        Levels as in --report.  Default: 4 (severe).
+--strict                Halt at the slightest problem.  Same as "--halt=info".
+--exit-status=<level>   Enable a non-zero exit status for non-halting system
+                        messages at or above <level>.  Default: 5 (disabled).
+--debug                 Enable debug-level system messages and diagnostics.
+--no-debug              Disable debug output.  (default)
+--warnings=<file>       Send the output of system messages to <file>.
+--traceback             Enable Python tracebacks when Docutils is halted.
+--no-traceback          Disable Python tracebacks.  (default)
+--input-encoding=<name[:handler]>, -i <name[:handler]>
+                        Specify the encoding and optionally the error handler
+                        of input text.  Default: <locale-dependent>:strict.
+--input-encoding-error-handler=INPUT_ENCODING_ERROR_HANDLER
+                        Specify the error handler for undecodable characters.
+                        Choices: "strict" (default), "ignore", and "replace".
+--output-encoding=<name[:handler]>, -o <name[:handler]>
+                        Specify the text encoding and optionally the error
+                        handler for output.  Default: UTF-8:strict.
+--output-encoding-error-handler=OUTPUT_ENCODING_ERROR_HANDLER
+                        Specify error handler for unencodable output
+                        characters; "strict" (default), "ignore", "replace",
+                        "xmlcharrefreplace", "backslashreplace".
+--error-encoding=<name[:handler]>, -e <name[:handler]>
+                        Specify text encoding and error handler for error
+                        output.  Default: utf-8:backslashreplace.
+--error-encoding-error-handler=ERROR_ENCODING_ERROR_HANDLER
+                        Specify the error handler for unencodable characters
+                        in error output.  Default: backslashreplace.
+--language=<name>, -l <name>
+                        Specify the language (as BCP 47 language tag).
+                        Default: en.
+--record-dependencies=<file>
+                        Write output file dependencies to <file>.
+--config=<file>         Read configuration settings from <file>, if it exists.
+--version, -V           Show this program's version number and exit.
+--help, -h              Show this help message and exit.
+
+Generic Parser Options
+----------------------
+--no-file-insertion     Disable directives that insert the contents of an
+                        external file; replaced with a "warning" system
+                        message.
+--file-insertion-enabled
+                        Enable directives that insert the contents of an
+                        external file. (default)
+--no-raw                Disable the "raw" directive; replaced with a "warning"
+                        system message.
+--raw-enabled           Enable the "raw" directive. (default)
+--line-length-limit=<length>
+                        Maximal number of characters in an input line. Default
+                        10 000.
+
+reStructuredText Parser Options
+-------------------------------
+--pep-references        Recognize and link to standalone PEP references (like
+                        "PEP 258").
+--pep-base-url=<URL>    Base URL for PEP references (default
+                        "https://peps.python.org/").
+--pep-file-url-template=<URL>
+                        Template for PEP file part of URL. (default
+                        "pep-%04d")
+--rfc-references        Recognize and link to standalone RFC references (like
+                        "RFC 822").
+--rfc-base-url=<URL>    Base URL for RFC references (default
+                        "https://tools.ietf.org/html/").
+--tab-width=<width>     Set number of spaces for tab expansion (default 8).
+--trim-footnote-reference-space
+                        Remove spaces before footnote references.
+--leave-footnote-reference-space
+                        Leave spaces before footnote references.
+--syntax-highlight=<format>
+                        Token name set for parsing code with Pygments: one of
+                        "long", "short", or "none" (no parsing). Default is
+                        "long".
+--smart-quotes=<yes/no/alt>
+                        Change straight quotation marks to typographic form:
+                        one of "yes", "no", "alt[ernative]" (default "no").
+--smartquotes-locales=<language:quotes[,language:quotes,...]>
+                        Characters to use as "smart quotes" for <language>.
+--word-level-inline-markup
+                        Inline markup recognized at word boundaries only
+                        (adjacent to punctuation or whitespace). Force
+                        character-level inline markup recognition with "\ "
+                        (backslash + space). Default.
+--character-level-inline-markup
+                        Inline markup recognized anywhere, regardless of
+                        surrounding characters. Backslash-escapes must be used
+                        to avoid unwanted markup recognition. Useful for East
+                        Asian languages. Experimental.
+
+Standalone Reader Options
+-------------------------
+--no-doc-title          Disable the promotion of a lone top-level section
+                        title to document title (and subsequent section title
+                        to document subtitle promotion; enabled by default).
+--no-doc-info           Disable the bibliographic field list transform
+                        (enabled by default).
+--section-subtitles     Activate the promotion of lone subsection titles to
+                        section subtitles (disabled by default).
+--no-section-subtitles  Deactivate the promotion of lone subsection titles.
+
+HTML Writer Options
+-------------------
+--template=<file>       Template file. (UTF-8 encoded, default: [...])
+--stylesheet=<URL[,URL,...]>
+                        Comma separated list of stylesheet URLs. Overrides
+                        previous --stylesheet and --stylesheet-path settings.
+--stylesheet-path=<file[,file,...]>
+                        Comma separated list of stylesheet paths. Relative
+                        paths are expanded if a matching file is found in the
+                        --stylesheet-dirs. With --link-stylesheet, the path is
+                        rewritten relative to the output HTML file. (default:
+                        "minimal.css,plain.css")
+--stylesheet-dirs=<dir[,dir,...]>
+                        Comma-separated list of directories where stylesheets
+                        are found. Used by --stylesheet-path when expanding
+                        relative path arguments. (default: [...])
+--embed-stylesheet      Embed the stylesheet(s) in the output HTML file.  The
+                        stylesheet files must be accessible during processing.
+                        (default)
+--link-stylesheet       Link to the stylesheet(s) in the output HTML file.
+--initial-header-level=<level>
+                        Specify the initial header level. Does not affect
+                        document title & subtitle (see --no-doc-title).
+                        (default: 2 for "<h2>")
+--footnote-references=<format>
+                        Format for footnote references: one of "superscript"
+                        or "brackets". (default: "brackets")
+--attribution=<format>  Format for block quote attributions: one of "dash"
+                        (em-dash prefix), "parentheses"/"parens", or "none".
+                        (default: "dash")
+--compact-lists         Remove extra vertical whitespace between items of
+                        "simple" bullet lists and enumerated lists. (default)
+--no-compact-lists      Disable compact simple bullet and enumerated lists.
+--compact-field-lists   Remove extra vertical whitespace between items of
+                        simple field lists. (default)
+--no-compact-field-lists
+                        Disable compact simple field lists.
+--table-style=TABLE_STYLE
+                        Added to standard table classes. Defined styles:
+                        borderless, booktabs, align-left, align-center, align-
+                        right, colwidths-auto, colwidths-grid.
+--math-output=MATH_OUTPUT
+                        Math output format (one of "MathML", "HTML",
+                        "MathJax", or "LaTeX") and option(s). (default: "HTML
+                        math.css")
+--xml-declaration       Prepend an XML declaration.
+--no-xml-declaration    Omit the XML declaration.
+--cloak-email-addresses
+                        Obfuscate email addresses to confuse harvesters while
+                        still keeping email links usable with standards-
+                        compliant browsers.
+
+HTML5 Writer Options
+--------------------
+--image-loading=IMAGE_LOADING
+                        Suggest at which point images should be loaded:
+                        "embed", "link" (default), or "lazy".
+--section-self-link     Append a self-link to section headings.
+--no-section-self-link  Do not append a self-link to section headings.
+                        (default)
+
+Docutils Application Options
+----------------------------
+Reader, writer, and parser settings influence the available options.
+Example: use `--help --writer=latex` to see LaTeX writer options.
+
+--reader=<reader>       Reader name (currently: "standalone").
+--parser=<parser>       Parser name (currently: "rst").
+--writer=<writer>       Writer name (currently: "html5").


Property changes on: trunk/docutils/test/data/help/docutils.txt
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: svn:keywords
## -0,0 +1 ##
+Author Date Id Revision
\ No newline at end of property
Added: trunk/docutils/tools/docutils-cli.py
===================================================================
--- trunk/docutils/tools/docutils-cli.py	                        (rev 0)
+++ trunk/docutils/tools/docutils-cli.py	2022-05-30 16:54:46 UTC (rev 9061)
@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+# :Copyright: © 2022 Günter Milde.
+# :License: Released under the terms of the `2-Clause BSD license`_, in short:
+#
+#    Copying and distribution of this file, with or without modification,
+#    are permitted in any medium without royalty provided the copyright
+#    notice and this notice are preserved.
+#    This file is offered as-is, without any warranty.
+#
+# .. _2-Clause BSD license: https://opensource.org/licenses/BSD-2-Clause
+#
+# Revision: $Revision$
+# Date: $Date$
+
+"""Generic command line interface for the `docutils` package.
+
+Deprecated:
+Call `docutils` (generated in the binary PATH during package installation)
+or `python3 -m docutils` to get the generic Docutils CLI.
+"""
+
+from docutils import __main__
+
+__main__.main()


Property changes on: trunk/docutils/tools/docutils-cli.py
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: svn:executable
## -0,0 +1 ##
+*
\ No newline at end of property
Added: svn:keywords
## -0,0 +1 ##
+Author Date Id Revision
\ No newline at end of property
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.