PY-59463: Update 'docutils' package to the latest version 0.21.2

(cherry picked from commit 779fab1c1ef58ea84f197ff4f14a6e88bef1ab3b)

IJ-CR-147140

GitOrigin-RevId: d8a6a7b3952aae2bc4e0ab64b9d1086baf3cc5b3

python/helpers/py3only/docutils/__init__.py

@@ -1,4 +1,4 @@
-# $Id: __init__.py 7756 2014-07-06 11:48:05Z grubert $
+# $Id: __init__.py 9649 2024-04-23 18:54:26Z grubert $
 # Author: David Goodger <goodger@python.org>
 # Copyright: This module has been placed in the public domain.
 
@@ -35,8 +35,8 @@ Subpackages:
 - readers: Context-specific input handlers which understand the data
   source and manage a parser.
 
-- transforms: Modules used by readers and writers to modify DPS
-  doctrees.
+- transforms: Modules used by readers and writers to modify
+  the Docutils document tree.
 
 - utils: Contains the ``Reporter`` system warning class and miscellaneous
   utilities used by readers, writers, and transforms.
@@ -50,30 +50,85 @@ Subpackages:
 - writers: Format-specific output translators.
 """
 
+from collections import namedtuple
+
 __docformat__ = 'reStructuredText'
 
-__version__ = '0.12'
-"""``major.minor.micro`` version number.  The micro number is bumped for API
-changes, for new functionality, and for interim project releases.  The minor
-number is bumped whenever there is a significant project release.  The major
-number will be bumped when the project is feature-complete, and perhaps if
-there is a major change in the design."""
+__version__ = '0.21.2'
+"""Docutils version identifier (complies with PEP 440)::
 
-__version_details__ = 'release'
-"""Extra version details (e.g. 'snapshot 2005-05-29, r3410', 'repository',
-'release'), modified automatically & manually."""
+    major.minor[.micro][releaselevel[serial]][.dev]
 
-import sys
+For version comparison operations, use `__version_info__` (see, below)
+rather than parsing the text of `__version__`.
 
-class ApplicationError(Exception):
-    # Workaround:
-    # In Python < 2.6, unicode(<exception instance>) calls `str` on the
-    # arg and therefore, e.g., unicode(StandardError(u'\u234')) fails
-    # with UnicodeDecodeError.
-    if sys.version_info < (2,6):
-        def __unicode__(self):
-            return ', '.join(self.args)
+https://docutils.sourceforge.io/docs/dev/policies.html#version-identification
+"""
 
+__version_details__ = ''
+"""Optional extra version details (e.g. 'snapshot 2005-05-29, r3410').
+
+For development and release status, use `__version__ and `__version_info__`.
+"""
+
+
+class VersionInfo(namedtuple('VersionInfo',
+                             'major minor micro releaselevel serial release')):
+
+    def __new__(cls, major=0, minor=0, micro=0,
+                releaselevel='final', serial=0, release=True):
+        releaselevels = ('alpha', 'beta', 'candidate', 'final')
+        if releaselevel not in releaselevels:
+            raise ValueError('releaselevel must be one of %r.'
+                             % (releaselevels, ))
+        if releaselevel == 'final':
+            if not release:
+                raise ValueError('releaselevel "final" must not be used '
+                                 'with development versions (leads to wrong '
+                                 'version ordering of the related __version__')
+                # cf. https://peps.python.org/pep-0440/#summary-of-permitted-suffixes-and-relative-ordering  # noqa
+            if serial != 0:
+                raise ValueError('"serial" must be 0 for final releases')
+
+        return super().__new__(cls, major, minor, micro,
+                               releaselevel, serial, release)
+
+    def __lt__(self, other):
+        if isinstance(other, tuple):
+            other = VersionInfo(*other)
+        return tuple.__lt__(self, other)
+
+    def __gt__(self, other):
+        if isinstance(other, tuple):
+            other = VersionInfo(*other)
+        return tuple.__gt__(self, other)
+
+    def __le__(self, other):
+        if isinstance(other, tuple):
+            other = VersionInfo(*other)
+        return tuple.__le__(self, other)
+
+    def __ge__(self, other):
+        if isinstance(other, tuple):
+            other = VersionInfo(*other)
+        return tuple.__ge__(self, other)
+
+
+__version_info__ = VersionInfo(
+    major=0,
+    minor=21,
+    micro=2,
+    releaselevel='final',  # one of 'alpha', 'beta', 'candidate', 'final'
+    serial=0,  # pre-release number (0 for final releases and snapshots)
+    release=True  # True for official releases and pre-releases
+    )
+"""Comprehensive version information tuple.
+
+https://docutils.sourceforge.io/docs/dev/policies.html#version-identification
+"""
+
+
+class ApplicationError(Exception): pass
 class DataError(ApplicationError): pass
 
 
@@ -85,6 +140,17 @@ class SettingsSpec:
     SettingsSpec subclass objects used by `docutils.frontend.OptionParser`.
     """
 
+    # TODO: replace settings_specs with a new data structure
+    # Backwards compatiblity:
+    #   Drop-in components:
+    #   Sphinx supplies settings_spec in the current format in some places
+    #   Myst parser provides a settings_spec tuple
+    #
+    #   Sphinx reads a settings_spec in order to set a default value
+    #   in writers/html.py:59
+    #   https://github.com/sphinx-doc/sphinx/blob/4.x/sphinx/writers/html.py
+    #   This should be changed (before retiring the old format)
+    #   to use `settings_default_overrides` instead.
     settings_spec = ()
     """Runtime settings specification.  Override in subclasses.
 
@@ -131,7 +197,7 @@ class SettingsSpec:
 
     settings_default_overrides = None
     """A dictionary of auxiliary defaults, to override defaults for settings
-    defined in other components.  Override in subclasses."""
+    defined in other components' `setting_specs`.  Override in subclasses."""
 
     relative_path_settings = ()
     """Settings containing filesystem paths.  Override in subclasses.
@@ -151,18 +217,21 @@ class SettingsSpec:
 
 
 class TransformSpec:
-
     """
     Runtime transform specification base class.
 
-    TransformSpec subclass objects used by `docutils.transforms.Transformer`.
+    Provides the interface to register "transforms" and helper functions
+    to resolve references with a `docutils.transforms.Transformer`.
+
+    https://docutils.sourceforge.io/docs/ref/transforms.html
     """
 
     def get_transforms(self):
         """Transforms required by this class.  Override in subclasses."""
         if self.default_transforms != ():
             import warnings
-            warnings.warn('default_transforms attribute deprecated.\n'
+            warnings.warn('TransformSpec: the "default_transforms" attribute '
+                          'will be removed in Docutils 2.0.\n'
                           'Use get_transforms() method instead.',
                           DeprecationWarning)
             return list(self.default_transforms)
@@ -172,11 +241,13 @@ class TransformSpec:
     default_transforms = ()
 
     unknown_reference_resolvers = ()
-    """List of functions to try to resolve unknown references.  Unknown
-    references have a 'refname' attribute which doesn't correspond to any
-    target in the document.  Called when the transforms in
-    `docutils.tranforms.references` are unable to find a correct target.  The
-    list should contain functions which will try to resolve unknown
+    """List of functions to try to resolve unknown references.
+
+    Unknown references have a 'refname' attribute which doesn't correspond
+    to any target in the document.  Called when the transforms in
+    `docutils.transforms.references` are unable to find a correct target.
+
+    The list should contain functions which will try to resolve unknown
     references, with the following signature::
 
         def reference_resolver(node):
@@ -193,7 +264,10 @@ class TransformSpec:
 
         reference_resolver.priority = 100
 
-    Override in subclasses."""
+    This hook is provided for 3rd party extensions.
+    Example use case: the `MoinMoin - ReStructured Text Parser`
+    in ``sandbox/mmgilbe/rst.py``.
+    """
 
 
 class Component(SettingsSpec, TransformSpec):
@@ -205,7 +279,7 @@ class Component(SettingsSpec, TransformSpec):
     subclasses."""
 
     supported = ()
-    """Names for this component.  Override in subclasses."""
+    """Name and aliases for this component.  Override in subclasses."""
 
     def supports(self, format):
         """

python/helpers/py3only/docutils/core.py

@@ -1,4 +1,4 @@
-# $Id: core.py 7466 2012-06-25 14:56:51Z milde $
+# $Id: core.py 9369 2023-05-02 23:04:27Z milde $
 # Author: David Goodger <goodger@python.org>
 # Copyright: This module has been placed in the public domain.
 
@@ -9,19 +9,22 @@ behavior.  For custom behavior (setting component options), create
 custom component objects first, and pass *them* to
 ``publish_*``/`Publisher`.  See `The Docutils Publisher`_.
 
-.. _The Docutils Publisher: http://docutils.sf.net/docs/api/publisher.html
+.. _The Docutils Publisher:
+    https://docutils.sourceforge.io/docs/api/publisher.html
 """
 
 __docformat__ = 'reStructuredText'
 
+import locale
 import pprint
+import os
 import sys
+import warnings
 
-import docutils.readers.doctree
-from docutils import __version__, __version_details__, SettingsSpec
-from docutils import frontend, io, utils, readers, writers
+from docutils import (__version__, __version_details__, SettingsSpec,
+                      io, utils, readers, writers)
 from docutils.frontend import OptionParser
-from docutils.utils.error_reporting import ErrorOutput, ErrorString
+from docutils.readers import doctree
 
 
 class Publisher:
@@ -36,8 +39,9 @@ class Publisher:
                  settings=None):
         """
         Initial setup.  If any of `reader`, `parser`, or `writer` are not
-        specified, the corresponding ``set_...`` method should be called with
-        a component name (`set_reader` sets the parser as well).
+        specified, ``set_components()`` or the corresponding ``set_...()``
+        method should be called with component names
+        (`set_reader` sets the parser as well).
         """
 
         self.document = None
@@ -76,7 +80,7 @@ class Publisher:
         """An object containing Docutils settings as instance attributes.
         Set by `self.process_command_line()` or `self.get_settings()`."""
 
-        self._stderr = ErrorOutput()
+        self._stderr = io.ErrorOutput()
 
     def set_reader(self, reader_name, parser, parser_name):
         """Set `self.reader` by name."""
@@ -102,6 +106,9 @@ class Publisher:
     def setup_option_parser(self, usage=None, description=None,
                             settings_spec=None, config_section=None,
                             **defaults):
+        warnings.warn('Publisher.setup_option_parser is deprecated, '
+                      'and will be removed in Docutils 0.21.',
+                      DeprecationWarning, stacklevel=2)
         if config_section:
             if not settings_spec:
                 settings_spec = SettingsSpec()
@@ -109,23 +116,33 @@ class Publisher:
             parts = config_section.split()
             if len(parts) > 1 and parts[-1] == 'application':
                 settings_spec.config_section_dependencies = ['applications']
-        #@@@ Add self.source & self.destination to components in future?
-        option_parser = OptionParser(
+        # @@@ Add self.source & self.destination to components in future?
+        return OptionParser(
             components=(self.parser, self.reader, self.writer, settings_spec),
             defaults=defaults, read_config_files=True,
             usage=usage, description=description)
-        return option_parser
+
+    def _setup_settings_parser(self, *args, **kwargs):
+        # Provisional: will change (docutils.frontend.OptionParser will
+        # be replaced by a parser based on arparse.ArgumentParser)
+        # and may be removed later.
+        with warnings.catch_warnings():
+            warnings.filterwarnings('ignore', category=DeprecationWarning)
+            return self.setup_option_parser(*args, **kwargs)
 
     def get_settings(self, usage=None, description=None,
                      settings_spec=None, config_section=None, **defaults):
         """
-        Set and return default settings (overrides in `defaults` dict).
+        Return settings from components and config files.
 
-        Set components first (`self.set_reader` & `self.set_writer`).
-        Explicitly setting `self.settings` disables command line option
-        processing from `self.publish()`.
+        Please set components first (`self.set_reader` & `self.set_writer`).
+        Use keyword arguments to override component defaults
+        (before updating from configuration files).
+
+        Calling this function also sets `self.settings` which makes
+        `self.publish()` skip parsing command line options.
         """
-        option_parser = self.setup_option_parser(
+        option_parser = self._setup_settings_parser(
             usage, description, settings_spec, config_section, **defaults)
         self.settings = option_parser.get_default_values()
         return self.settings
@@ -134,7 +151,7 @@ class Publisher:
                                       settings_overrides,
                                       config_section):
         if self.settings is None:
-            defaults = (settings_overrides or {}).copy()
+            defaults = settings_overrides.copy() if settings_overrides else {}
             # Propagate exceptions by default when used programmatically:
             defaults.setdefault('traceback', True)
             self.get_settings(settings_spec=settings_spec,
@@ -145,20 +162,17 @@ class Publisher:
                              settings_spec=None, config_section=None,
                              **defaults):
         """
-        Pass an empty list to `argv` to avoid reading `sys.argv` (the
-        default).
+        Parse command line arguments and set ``self.settings``.
+
+        Pass an empty sequence to `argv` to avoid reading `sys.argv`
+        (the default behaviour).
 
         Set components first (`self.set_reader` & `self.set_writer`).
         """
-        option_parser = self.setup_option_parser(
+        option_parser = self._setup_settings_parser(
             usage, description, settings_spec, config_section, **defaults)
         if argv is None:
             argv = sys.argv[1:]
-            # converting to Unicode (Python 3 does this automatically):
-            if sys.version_info < (3,0):
-                # TODO: make this failsafe and reversible?
-                argv_encoding = (frontend.locale_encoding or 'ascii')
-                argv = [a.decode(argv_encoding) for a in argv]
         self.settings = option_parser.parse_args(argv)
 
     def set_io(self, source_path=None, destination_path=None):
@@ -172,24 +186,26 @@ class Publisher:
             source_path = self.settings._source
         else:
             self.settings._source = source_path
-        # Raise IOError instead of system exit with `tracback == True`
-        # TODO: change io.FileInput's default behaviour and remove this hack
-        try:
-            self.source = self.source_class(
-                source=source, source_path=source_path,
-                encoding=self.settings.input_encoding)
-        except TypeError:
-            self.source = self.source_class(
-                source=source, source_path=source_path,
-                encoding=self.settings.input_encoding)
+        self.source = self.source_class(
+            source=source, source_path=source_path,
+            encoding=self.settings.input_encoding,
+            error_handler=self.settings.input_encoding_error_handler)
 
     def set_destination(self, destination=None, destination_path=None):
         if destination_path is None:
-            destination_path = self.settings._destination
-        else:
-            self.settings._destination = destination_path
+            if (self.settings.output and self.settings._destination
+                and self.settings.output != self.settings._destination):
+                raise SystemExit('The positional argument <destination> is '
+                                 'obsoleted by the --output option.  '
+                                 'You cannot use them together.')
+            if self.settings.output == '-':      # means stdout
+                self.settings.output = None
+            destination_path = (self.settings.output
+                                or self.settings._destination)
+        self.settings._destination = destination_path
         self.destination = self.destination_class(
-            destination=destination, destination_path=destination_path,
+            destination=destination,
+            destination_path=destination_path,
             encoding=self.settings.output_encoding,
             error_handler=self.settings.output_encoding_error_handler)
 
@@ -214,18 +230,19 @@ class Publisher:
                     argv, usage, description, settings_spec, config_section,
                     **(settings_overrides or {}))
             self.set_io()
+            self.prompt()
             self.document = self.reader.read(self.source, self.parser,
                                              self.settings)
             self.apply_transforms()
             output = self.writer.write(self.document, self.destination)
             self.writer.assemble_parts()
         except SystemExit as error:
-            exit = 1
+            exit = True
             exit_status = error.code
         except Exception as error:
             if not self.settings:       # exception too early to report nicely
                 raise
-            if self.settings.traceback: # Propagate exceptions?
+            if self.settings.traceback:  # Propagate exceptions?
                 self.debugging_dumps()
                 raise
             self.report_Exception(error)
@@ -251,8 +268,8 @@ class Publisher:
             print(pprint.pformat(self.document.__dict__), file=self._stderr)
         if self.settings.dump_transforms:
             print('\n::: Transforms applied:', file=self._stderr)
-            print((' (priority, transform class, '
-                                 'pending node details, keyword args)'), file=self._stderr)
+            print(' (priority, transform class, pending node details, '
+                  'keyword args)', file=self._stderr)
             print(pprint.pformat(
                 [(priority, '%s.%s' % (xclass.__module__, xclass.__name__),
                   pending and pending.details, kwargs)
@@ -263,6 +280,28 @@ class Publisher:
             print(self.document.pformat().encode(
                 'raw_unicode_escape'), file=self._stderr)
 
+    def prompt(self):
+        """Print info and prompt when waiting for input from a terminal."""
+        try:
+            if not (self.source.isatty() and self._stderr.isatty()):
+                return
+        except AttributeError:
+            return
+        eot_key = 'Ctrl+Z' if os.name == 'nt' else 'Ctrl+D'
+        in_format = ''
+        out_format = 'useful formats'
+        try:
+            in_format = self.parser.supported[0]
+            out_format = self.writer.supported[0]
+        except (AttributeError, IndexError):
+            pass
+        print(f'Docutils {__version__} <https://docutils.sourceforge.io>\n'
+              f'converting "{in_format}" into "{out_format}".\n'
+              f'Call with option "--help" for more info.\n'
+              f'.. Waiting for source text (finish with {eot_key} '
+              'on an empty line):',
+              file=self._stderr)
+
     def report_Exception(self, error):
         if isinstance(error, utils.SystemMessage):
             self.report_SystemMessage(error)
@@ -270,25 +309,25 @@ class Publisher:
             self.report_UnicodeError(error)
         elif isinstance(error, io.InputError):
             self._stderr.write('Unable to open source file for reading:\n'
-                               '  %s\n' % ErrorString(error))
+                               '  %s\n' % io.error_string(error))
         elif isinstance(error, io.OutputError):
             self._stderr.write(
                 'Unable to open destination file for writing:\n'
-                '  %s\n' % ErrorString(error))
+                '  %s\n' % io.error_string(error))
         else:
-            print('%s' % ErrorString(error), file=self._stderr)
-            print(("""\
+            print('%s' % io.error_string(error), file=self._stderr)
+            print(f"""\
 Exiting due to error.  Use "--traceback" to diagnose.
-Please report errors to <docutils-users@lists.sf.net>.
-Include "--traceback" output, Docutils version (%s [%s]),
-Python version (%s), your OS type & version, and the
-command line used.""" % (__version__, __version_details__,
-                         sys.version.split()[0])), file=self._stderr)
+Please report errors to <docutils-users@lists.sourceforge.net>.
+Include "--traceback" output, Docutils version ({__version__}\
+{f' [{__version_details__}]' if __version_details__ else ''}),
+Python version ({sys.version.split()[0]}), your OS type & version, \
+and the command line used.""", file=self._stderr)
 
     def report_SystemMessage(self, error):
-        print(('Exiting due to level-%s (%s) system message.'
-                             % (error.level,
-                                utils.Reporter.levels[error.level])), file=self._stderr)
+        print('Exiting due to level-%s (%s) system message.' % (
+                  error.level, utils.Reporter.levels[error.level]),
+              file=self._stderr)
 
     def report_UnicodeError(self, error):
         data = error.object[error.start:error.end]
@@ -309,23 +348,34 @@ command line used.""" % (__version__, __version_details__,
             '\n'
             'Exiting due to error.  Use "--traceback" to diagnose.\n'
             'If the advice above doesn\'t eliminate the error,\n'
-            'please report it to <docutils-users@lists.sf.net>.\n'
+            'please report it to <docutils-users@lists.sourceforge.net>.\n'
             'Include "--traceback" output, Docutils version (%s),\n'
             'Python version (%s), your OS type & version, and the\n'
             'command line used.\n'
-            % (ErrorString(error),
+            % (io.error_string(error),
                self.settings.output_encoding,
                data.encode('ascii', 'xmlcharrefreplace'),
                data.encode('ascii', 'backslashreplace'),
                self.settings.output_encoding_error_handler,
                __version__, sys.version.split()[0]))
 
-default_usage = '%prog [options] [<source> [<destination>]]'
-default_description = ('Reads from <source> (default is stdin) and writes to '
-                       '<destination> (default is stdout).  See '
-                       '<http://docutils.sf.net/docs/user/config.html> for '
-                       'the full reference.')
 
+default_usage = '%prog [options] [<source> [<destination>]]'
+default_description = (
+    '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.')
+
+
+# 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',
@@ -335,10 +385,11 @@ def publish_cmdline(reader=None, reader_name='standalone',
                     usage=default_usage, description=default_description):
     """
     Set up & run a `Publisher` for command-line-based file I/O (input and
-    output file paths taken automatically from the command line).  Return the
-    encoded string output also.
+    output file paths taken automatically from the command line).
+    Also return the output as `str` or `bytes` (for binary output document
+    formats).
 
-    Parameters: see `publish_programmatically` for the remainder.
+    Parameters: see `publish_programmatically()` for the remainder.
 
     - `argv`: Command-line argument list to use instead of ``sys.argv[1:]``.
     - `usage`: Usage string, output if there's a problem parsing the command
@@ -346,13 +397,14 @@ def publish_cmdline(reader=None, reader_name='standalone',
     - `description`: Program description, output for the "--help" option
       (along with command-line option descriptions).
     """
-    pub = Publisher(reader, parser, writer, settings=settings)
-    pub.set_components(reader_name, parser_name, writer_name)
-    output = pub.publish(
+    publisher = Publisher(reader, parser, writer, settings=settings)
+    publisher.set_components(reader_name, parser_name, writer_name)
+    output = publisher.publish(
         argv, usage, description, settings_spec, settings_overrides,
         config_section=config_section, enable_exit_status=enable_exit_status)
     return output
 
+
 def publish_file(source=None, source_path=None,
                  destination=None, destination_path=None,
                  reader=None, reader_name='standalone',
@@ -362,11 +414,12 @@ def publish_file(source=None, source_path=None,
                  config_section=None, enable_exit_status=False):
     """
     Set up & run a `Publisher` for programmatic use with file-like I/O.
-    Return the encoded string output also.
+    Also return the output as `str` or `bytes` (for binary output document
+    formats).
 
-    Parameters: see `publish_programmatically`.
+    Parameters: see `publish_programmatically()`.
     """
-    output, pub = publish_programmatically(
+    output, publisher = publish_programmatically(
         source_class=io.FileInput, source=source, source_path=source_path,
         destination_class=io.FileOutput,
         destination=destination, destination_path=destination_path,
@@ -379,6 +432,7 @@ def publish_file(source=None, source_path=None,
         enable_exit_status=enable_exit_status)
     return output
 
+
 def publish_string(source, source_path=None, destination_path=None,
                    reader=None, reader_name='standalone',
                    parser=None, parser_name='restructuredtext',
@@ -387,22 +441,23 @@ def publish_string(source, source_path=None, destination_path=None,
                    settings_overrides=None, config_section=None,
                    enable_exit_status=False):
     """
-    Set up & run a `Publisher` for programmatic use with string I/O.  Return
-    the encoded string or Unicode string output.
+    Set up & run a `Publisher` for programmatic use with string I/O.
 
-    For encoded string output, be sure to set the 'output_encoding' setting to
-    the desired encoding.  Set it to 'unicode' for unencoded Unicode string
-    output.  Here's one way::
+    Accepts a `bytes` or `str` instance as `source`.
 
-        publish_string(..., settings_overrides={'output_encoding': 'unicode'})
+    The output is encoded according to the `output_encoding`_ setting;
+    the return value is a `bytes` instance (unless `output_encoding`_ is
+    "unicode", cf. `docutils.io.StringOutput.write()`).
 
-    Similarly for Unicode string input (`source`)::
+    Parameters: see `publish_programmatically()`.
 
-        publish_string(..., settings_overrides={'input_encoding': 'unicode'})
+    This function is provisional because in Python 3 name and behaviour
+    no longer match.
 
-    Parameters: see `publish_programmatically`.
+    .. _output_encoding:
+        https://docutils.sourceforge.io/docs/user/config.html#output-encoding
     """
-    output, pub = publish_programmatically(
+    output, publisher = publish_programmatically(
         source_class=io.StringInput, source=source, source_path=source_path,
         destination_class=io.StringOutput,
         destination=None, destination_path=destination_path,
@@ -415,6 +470,7 @@ def publish_string(source, source_path=None, destination_path=None,
         enable_exit_status=enable_exit_status)
     return output
 
+
 def publish_parts(source, source_path=None, source_class=io.StringInput,
                   destination_path=None,
                   reader=None, reader_name='standalone',
@@ -425,18 +481,21 @@ def publish_parts(source, source_path=None, source_class=io.StringInput,
                   enable_exit_status=False):
     """
     Set up & run a `Publisher`, and return a dictionary of document parts.
-    Dictionary keys are the names of parts, and values are Unicode strings;
-    encoding is up to the client.  For programmatic use with string I/O.
 
-    For encoded string input, be sure to set the 'input_encoding' setting to
-    the desired encoding.  Set it to 'unicode' for unencoded Unicode string
-    input.  Here's how::
+    Dictionary keys are the names of parts.
+    Dictionary values are `str` instances; encoding is up to the client,
+    e.g.::
 
-        publish_parts(..., settings_overrides={'input_encoding': 'unicode'})
+       parts = publish_parts(...)
+       body = parts['body'].encode(parts['encoding'], parts['errors'])
 
-    Parameters: see `publish_programmatically`.
+    See the `API documentation`__ for details on the provided parts.
+
+    Parameters: see `publish_programmatically()`.
+
+    __ https://docutils.sourceforge.io/docs/api/publisher.html#publish-parts
     """
-    output, pub = publish_programmatically(
+    output, publisher = publish_programmatically(
         source=source, source_path=source_path, source_class=source_class,
         destination_class=io.StringOutput,
         destination=None, destination_path=destination_path,
@@ -447,7 +506,8 @@ def publish_parts(source, source_path=None, source_class=io.StringInput,
         settings_overrides=settings_overrides,
         config_section=config_section,
         enable_exit_status=enable_exit_status)
-    return pub.writer.parts
+    return publisher.writer.parts
+
 
 def publish_doctree(source, source_path=None,
                     source_class=io.StringInput,
@@ -457,28 +517,23 @@ def publish_doctree(source, source_path=None,
                     settings_overrides=None, config_section=None,
                     enable_exit_status=False):
     """
-    Set up & run a `Publisher` for programmatic use with string I/O.
-    Return the document tree.
+    Set up & run a `Publisher` for programmatic use. Return a document tree.
 
-    For encoded string input, be sure to set the 'input_encoding' setting to
-    the desired encoding.  Set it to 'unicode' for unencoded Unicode string
-    input.  Here's one way::
-
-        publish_doctree(..., settings_overrides={'input_encoding': 'unicode'})
-
-    Parameters: see `publish_programmatically`.
+    Parameters: see `publish_programmatically()`.
     """
-    pub = Publisher(reader=reader, parser=parser, writer=None,
-                    settings=settings,
-                    source_class=source_class,
-                    destination_class=io.NullOutput)
-    pub.set_components(reader_name, parser_name, 'null')
-    pub.process_programmatic_settings(
-        settings_spec, settings_overrides, config_section)
-    pub.set_source(source, source_path)
-    pub.set_destination(None, None)
-    output = pub.publish(enable_exit_status=enable_exit_status)
-    return pub.document
+    _output, publisher = publish_programmatically(
+        source=source, source_path=source_path,
+        source_class=source_class,
+        destination=None, destination_path=None,
+        destination_class=io.NullOutput,
+        reader=reader, reader_name=reader_name,
+        parser=parser, parser_name=parser_name,
+        writer=None, writer_name='null',
+        settings=settings, settings_spec=settings_spec,
+        settings_overrides=settings_overrides, config_section=config_section,
+        enable_exit_status=enable_exit_status)
+    return publisher.document
+
 
 def publish_from_doctree(document, destination_path=None,
                          writer=None, writer_name='pseudoxml',
@@ -486,57 +541,59 @@ def publish_from_doctree(document, destination_path=None,
                          settings_overrides=None, config_section=None,
                          enable_exit_status=False):
     """
-    Set up & run a `Publisher` to render from an existing document
-    tree data structure, for programmatic use with string I/O.  Return
-    the encoded string output.
+    Set up & run a `Publisher` to render from an existing document tree
+    data structure. For programmatic use with string output
+    (`bytes` or `str`, cf. `publish_string()`).
 
-    Note that document.settings is overridden; if you want to use the settings
-    of the original `document`, pass settings=document.settings.
+    Note that ``document.settings`` is overridden; if you want to use the
+    settings of the original `document`, pass ``settings=document.settings``.
 
-    Also, new document.transformer and document.reporter objects are
+    Also, new `document.transformer` and `document.reporter` objects are
     generated.
 
-    For encoded string output, be sure to set the 'output_encoding' setting to
-    the desired encoding.  Set it to 'unicode' for unencoded Unicode string
-    output.  Here's one way::
-
-        publish_from_doctree(
-            ..., settings_overrides={'output_encoding': 'unicode'})
-
     Parameters: `document` is a `docutils.nodes.document` object, an existing
     document tree.
 
-    Other parameters: see `publish_programmatically`.
+    Other parameters: see `publish_programmatically()`.
+
+    This function is provisional because in Python 3 name and behaviour
+    of the `io.StringOutput` class no longer match.
     """
-    reader = docutils.readers.doctree.Reader(parser_name='null')
-    pub = Publisher(reader, None, writer,
-                    source=io.DocTreeInput(document),
-                    destination_class=io.StringOutput, settings=settings)
+    reader = doctree.Reader(parser_name='null')
+    publisher = Publisher(reader, None, writer,
+                          source=io.DocTreeInput(document),
+                          destination_class=io.StringOutput,
+                          settings=settings)
     if not writer and writer_name:
-        pub.set_writer(writer_name)
-    pub.process_programmatic_settings(
+        publisher.set_writer(writer_name)
+    publisher.process_programmatic_settings(
         settings_spec, settings_overrides, config_section)
-    pub.set_destination(None, destination_path)
-    return pub.publish(enable_exit_status=enable_exit_status)
+    publisher.set_destination(None, destination_path)
+    return publisher.publish(enable_exit_status=enable_exit_status)
+
 
 def publish_cmdline_to_binary(reader=None, reader_name='standalone',
-                    parser=None, parser_name='restructuredtext',
-                    writer=None, writer_name='pseudoxml',
-                    settings=None, settings_spec=None,
-                    settings_overrides=None, config_section=None,
-                    enable_exit_status=True, argv=None,
-                    usage=default_usage, description=default_description,
-                    destination=None, destination_class=io.BinaryFileOutput
-                    ):
+                              parser=None, parser_name='restructuredtext',
+                              writer=None, writer_name='pseudoxml',
+                              settings=None,
+                              settings_spec=None,
+                              settings_overrides=None,
+                              config_section=None,
+                              enable_exit_status=True,
+                              argv=None,
+                              usage=default_usage,
+                              description=default_description,
+                              destination=None,
+                              destination_class=io.BinaryFileOutput):
     """
     Set up & run a `Publisher` for command-line-based file I/O (input and
-    output file paths taken automatically from the command line).  Return the
-    encoded string output also.
+    output file paths taken automatically from the command line).
+    Also return the output as `bytes`.
 
     This is just like publish_cmdline, except that it uses
     io.BinaryFileOutput instead of io.FileOutput.
 
-    Parameters: see `publish_programmatically` for the remainder.
+    Parameters: see `publish_programmatically()` for the remainder.
 
     - `argv`: Command-line argument list to use instead of ``sys.argv[1:]``.
     - `usage`: Usage string, output if there's a problem parsing the command
@@ -544,14 +601,15 @@ def publish_cmdline_to_binary(reader=None, reader_name='standalone',
     - `description`: Program description, output for the "--help" option
       (along with command-line option descriptions).
     """
-    pub = Publisher(reader, parser, writer, settings=settings,
-        destination_class=destination_class)
-    pub.set_components(reader_name, parser_name, writer_name)
-    output = pub.publish(
+    publisher = Publisher(reader, parser, writer, settings=settings,
+                          destination_class=destination_class)
+    publisher.set_components(reader_name, parser_name, writer_name)
+    output = publisher.publish(
         argv, usage, description, settings_spec, settings_overrides,
         config_section=config_section, enable_exit_status=enable_exit_status)
     return output
 
+
 def publish_programmatically(source_class, source, source_path,
                              destination_class, destination, destination_path,
                              reader, reader_name,
@@ -561,13 +619,15 @@ def publish_programmatically(source_class, source, source_path,
                              settings_overrides, config_section,
                              enable_exit_status):
     """
-    Set up & run a `Publisher` for custom programmatic use.  Return the
-    encoded string output and the Publisher object.
+    Set up & run a `Publisher` for custom programmatic use.
+
+    Return the output (as `str` or `bytes`, depending on `destination_class`,
+    writer, and the "output_encoding" setting) and the Publisher object.
 
     Applications should not need to call this function directly.  If it does
     seem to be necessary to call this function directly, please write to the
     Docutils-develop mailing list
-    <http://docutils.sf.net/docs/user/mailing-lists.html#docutils-develop>.
+    <https://docutils.sourceforge.io/docs/user/mailing-lists.html#docutils-develop>.
 
     Parameters:
 
@@ -581,18 +641,17 @@ def publish_programmatically(source_class, source, source_path,
         (`source_path` is opened).  If neither `source` nor
         `source_path` are supplied, `sys.stdin` is used.
 
-      - If `source_class` is `io.StringInput` **required**: The input
-        string, either an encoded 8-bit string (set the
-        'input_encoding' setting to the correct encoding) or a Unicode
-        string (set the 'input_encoding' setting to 'unicode').
+      - If `source_class` is `io.StringInput` **required**:
+        The input as either a `bytes` object (ensure the 'input_encoding'
+        setting matches its encoding) or a `str` object.
 
     * `source_path`: Type depends on `source_class`:
 
       - `io.FileInput`: Path to the input file, opened if no `source`
         supplied.
 
-      - `io.StringInput`: Optional.  Path to the file or object that produced
-        `source`.  Only used for diagnostic output.
+      - `io.StringInput`: Optional.  Path to the file or name of the
+        object that produced `source`.  Only used for diagnostic output.
 
     * `destination_class` **required**: The class for dynamically created
       destination objects.  Typically `io.FileOutput` or `io.StringOutput`.
@@ -652,13 +711,70 @@ def publish_programmatically(source_class, source, source_path,
 
     * `enable_exit_status`: Boolean; enable exit status at end of processing?
     """
-    pub = Publisher(reader, parser, writer, settings=settings,
-                    source_class=source_class,
-                    destination_class=destination_class)
-    pub.set_components(reader_name, parser_name, writer_name)
-    pub.process_programmatic_settings(
+    publisher = Publisher(reader, parser, writer, settings=settings,
+                          source_class=source_class,
+                          destination_class=destination_class)
+    publisher.set_components(reader_name, parser_name, writer_name)
+    publisher.process_programmatic_settings(
         settings_spec, settings_overrides, config_section)
-    pub.set_source(source, source_path)
-    pub.set_destination(destination, destination_path)
-    output = pub.publish(enable_exit_status=enable_exit_status)
-    return output, pub
+    publisher.set_source(source, source_path)
+    publisher.set_destination(destination, destination_path)
+    output = publisher.publish(enable_exit_status=enable_exit_status)
+    return output, publisher
+
+
+# "Entry points" with functionality of the "tools/rst2*.py" scripts
+# cf. https://packaging.python.org/en/latest/specifications/entry-points/
+
+def rst2something(writer, documenttype, doc_path=''):
+    # Helper function for the common parts of rst2...
+    #   writer:       writer name
+    #   documenttype: output document type
+    #   doc_path:     documentation path (relative to the documentation root)
+    description = (
+        f'Generate {documenttype} documents '
+        'from standalone reStructuredText sources '
+        f'<https://docutils.sourceforge.io/docs/{doc_path}>.  '
+        + default_description)
+    locale.setlocale(locale.LC_ALL, '')
+    publish_cmdline(writer_name=writer, description=description)
+
+
+def rst2html():
+    rst2something('html', 'HTML', 'user/html.html#html')
+
+
+def rst2html4():
+    rst2something('html4', 'XHTML 1.1', 'user/html.html#html4css1')
+
+
+def rst2html5():
+    rst2something('html5', 'HTML5', 'user/html.html#html5-polyglot')
+
+
+def rst2latex():
+    rst2something('latex', 'LaTeX', 'user/latex.html')
+
+
+def rst2man():
+    rst2something('manpage', 'Unix manual (troff)', 'user/manpage.html')
+
+
+def rst2odt():
+    rst2something('odt', 'OpenDocument text (ODT)', 'user/odt.html')
+
+
+def rst2pseudoxml():
+    rst2something('pseudoxml', 'pseudo-XML (test)', 'ref/doctree.html')
+
+
+def rst2s5():
+    rst2something('s5', 'S5 HTML slideshow', 'user/slide-shows.html')
+
+
+def rst2xetex():
+    rst2something('xetex', 'LaTeX (XeLaTeX/LuaLaTeX)', 'user/latex.html')
+
+
+def rst2xml():
+    rst2something('xml', 'Docutils-native XML', 'ref/doctree.html')

python/helpers/py3only/docutils/examples.py

@@ -1,4 +1,4 @@
-# $Id: examples.py 7320 2012-01-19 22:33:02Z milde $
+# $Id: examples.py 9026 2022-03-04 15:57:13Z milde $
 # Author: David Goodger <goodger@python.org>
 # Copyright: This module has been placed in the public domain.
 
@@ -49,6 +49,7 @@ def html_parts(input_string, source_path=None, destination_path=None,
         writer_name='html', settings_overrides=overrides)
     return parts
 
+
 def html_body(input_string, source_path=None, destination_path=None,
               input_encoding='unicode', output_encoding='unicode',
               doctitle=True, initial_header_level=1):
@@ -72,6 +73,7 @@ def html_body(input_string, source_path=None, destination_path=None,
         fragment = fragment.encode(output_encoding)
     return fragment
 
+
 def internals(input_string, source_path=None, destination_path=None,
               input_encoding='unicode', settings_overrides=None):
     """

python/helpers/py3only/docutils/io.py

@@ -1,4 +1,4 @@
-# $Id: io.py 7596 2013-01-25 13:42:17Z milde $
+# $Id: io.py 9427 2023-07-07 06:50:09Z milde $
 # Author: David Goodger <goodger@python.org>
 # Copyright: This module has been placed in the public domain.
 
@@ -10,17 +10,39 @@ exist for a variety of input/output mechanisms.
 __docformat__ = 'reStructuredText'
 
 import codecs
+import locale
 import os
 import re
 import sys
+import warnings
 
 from docutils import TransformSpec
-from docutils._compat import b
-from docutils.utils.error_reporting import locale_encoding, ErrorString, ErrorOutput
 
 
-class InputError(IOError): pass
-class OutputError(IOError): pass
+# Guess the locale's preferred encoding.
+# If no valid guess can be made, _locale_encoding is set to `None`:
+#
+# TODO: check whether this is set correctly with every OS and Python version
+#       or whether front-end tools need to call `locale.setlocale()`
+#       before importing this module
+try:
+    # Return locale encoding also in UTF-8 mode
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        _locale_encoding = (locale.getlocale()[1]
+                            or locale.getdefaultlocale()[1])
+        _locale_encoding = _locale_encoding.lower()
+except:  # noqa  any other problems determining the locale -> use None
+    _locale_encoding = None
+try:
+    codecs.lookup(_locale_encoding)
+except (LookupError, TypeError):
+    _locale_encoding = None
+
+
+class InputError(OSError): pass
+class OutputError(OSError): pass
+
 
 def check_encoding(stream, encoding):
     """Test, whether the encoding of `stream` matches `encoding`.
@@ -38,10 +60,22 @@ def check_encoding(stream, encoding):
         return None
 
 
-class Input(TransformSpec):
+def error_string(err):
+    """Return string representation of Exception `err`.
+    """
+    return f'{err.__class__.__name__}: {err}'
 
+
+class Input(TransformSpec):
     """
     Abstract base class for input wrappers.
+
+    Docutils input objects must provide a `read()` method that
+    returns the source, typically as `str` instance.
+
+    Inheriting `TransformSpec` allows input objects to add
+    "transforms" and "unknown_reference_resolvers" to the "Transformer".
+    (Optional for custom input objects since Docutils 0.19.)
     """
 
     component_type = 'input'
@@ -73,62 +107,72 @@ class Input(TransformSpec):
                                                   self.source_path)
 
     def read(self):
+        """Return input as `str`. Define in subclasses."""
         raise NotImplementedError
 
     def decode(self, data):
         """
-        Decode a string, `data`, heuristically.
-        Raise UnicodeError if unsuccessful.
+        Decode `data` if required.
 
-        The client application should call ``locale.setlocale`` at the
+        Return Unicode `str` instances unchanged (nothing to decode).
+
+        If `self.encoding` is None, determine encoding from data
+        or try UTF-8 and the locale's preferred encoding.
+        The client application should call ``locale.setlocale()`` at the
         beginning of processing::
 
             locale.setlocale(locale.LC_ALL, '')
+
+        Raise UnicodeError if unsuccessful.
+
+        Provisional: encoding detection will be removed in Docutils 1.0.
         """
         if self.encoding and self.encoding.lower() == 'unicode':
-            assert isinstance(data, str), (
-                'input encoding is "unicode" '
-                'but input is not a unicode object')
+            assert isinstance(data, str), ('input encoding is "unicode" '
+                                           'but `data` is no `str` instance')
         if isinstance(data, str):
-            # Accept unicode even if self.encoding != 'unicode'.
+            # nothing to decode
             return data
         if self.encoding:
             # We believe the user/application when the encoding is
             # explicitly given.
-            encodings = [self.encoding]
+            encoding_candidates = [self.encoding]
         else:
             data_encoding = self.determine_encoding_from_data(data)
             if data_encoding:
-                # If the data declares its encoding (explicitly or via a BOM),
-                # we believe it.
-                encodings = [data_encoding]
+                # `data` declares its encoding with  "magic comment" or BOM,
+                encoding_candidates = [data_encoding]
             else:
-                # Apply heuristics only if no encoding is explicitly given and
-                # no BOM found.  Start with UTF-8, because that only matches
+                # Apply heuristics if the encoding is not specified.
+                # Start with UTF-8, because that only matches
                 # data that *IS* UTF-8:
-                encodings = ['utf-8', 'latin-1']
-                if locale_encoding:
-                    encodings.insert(1, locale_encoding)
-        for enc in encodings:
+                encoding_candidates = ['utf-8']
+                # If UTF-8 fails, fall back to the locale's preferred encoding:
+                fallback = locale.getpreferredencoding(do_setlocale=False)
+                if fallback and fallback.lower() != 'utf-8':
+                    encoding_candidates.append(fallback)
+        for enc in encoding_candidates:
             try:
                 decoded = str(data, enc, self.error_handler)
                 self.successful_encoding = enc
-                # Return decoded, removing BOMs.
-                return decoded.replace('\ufeff', '')
+                return decoded
             except (UnicodeError, LookupError) as err:
-                error = err # in Python 3, the <exception instance> is
-                            # local to the except clause
+                # keep exception instance for use outside of the "for" loop.
+                error = err
         raise UnicodeError(
             'Unable to decode input data.  Tried the following encodings: '
-            '%s.\n(%s)' % (', '.join([repr(enc) for enc in encodings]),
-                         ErrorString(error)))
+            f'{", ".join(repr(enc) for enc in encoding_candidates)}.\n'
+            f'({error_string(error)})')
 
-    coding_slug = re.compile(b("coding[:=]\s*([-\w.]+)"))
+    coding_slug = re.compile(br"coding[:=]\s*([-\w.]+)")
     """Encoding declaration pattern."""
 
-    byte_order_marks = ((codecs.BOM_UTF8, 'utf-8'), # 'utf-8-sig' new in v2.5
-                        (codecs.BOM_UTF16_BE, 'utf-16-be'),
-                        (codecs.BOM_UTF16_LE, 'utf-16-le'),)
+    byte_order_marks = ((codecs.BOM_UTF32_BE, 'utf-32'),
+                        (codecs.BOM_UTF32_LE, 'utf-32'),
+                        (codecs.BOM_UTF8, 'utf-8-sig'),
+                        (codecs.BOM_UTF16_BE, 'utf-16'),
+                        (codecs.BOM_UTF16_LE, 'utf-16'),
+                        )
     """Sequence of (start_bytes, encoding) tuples for encoding detection.
     The first bytes of input data are checked against the start_bytes strings.
     A match indicates the given encoding."""
@@ -149,11 +193,24 @@ class Input(TransformSpec):
                 return match.group(1).decode('ascii')
         return None
 
+    def isatty(self):
+        """Return True, if the input source is connected to a TTY device."""
+        try:
+            return self.source.isatty()
+        except AttributeError:
+            return False
+
 
 class Output(TransformSpec):
-
     """
     Abstract base class for output wrappers.
+
+    Docutils output objects must provide a `write()` method that
+    expects and handles one argument (the output).
+
+    Inheriting `TransformSpec` allows output objects to add
+    "transforms" and "unknown_reference_resolvers" to the "Transformer".
+    (Optional for custom output objects since Docutils 0.19.)
     """
 
     component_type = 'output'
@@ -182,14 +239,22 @@ class Output(TransformSpec):
                 % (self.__class__, self.destination, self.destination_path))
 
     def write(self, data):
-        """`data` is a Unicode string, to be encoded by `self.encode`."""
+        """Write `data`. Define in subclasses."""
         raise NotImplementedError
 
     def encode(self, data):
+        """
+        Encode and return `data`.
+
+        If `data` is a `bytes` instance, it is returned unchanged.
+        Otherwise it is encoded with `self.encoding`.
+
+        Provisional: If `self.encoding` is set to the pseudo encoding name
+        "unicode", `data` must be a `str` instance and is returned unchanged.
+        """
         if self.encoding and self.encoding.lower() == 'unicode':
-            assert isinstance(data, str), (
-                'the encoding given is "unicode" but the output is not '
-                'a Unicode string')
+            assert isinstance(data, str), ('output encoding is "unicode" '
+                                           'but `data` is no `str` instance')
             return data
         if not isinstance(data, str):
             # Non-unicode (e.g. bytes) output.
@@ -198,6 +263,94 @@ class Output(TransformSpec):
             return data.encode(self.encoding, self.error_handler)
 
 
+class ErrorOutput:
+    """
+    Wrapper class for file-like error streams with
+    failsafe de- and encoding of `str`, `bytes`, `unicode` and
+    `Exception` instances.
+    """
+
+    def __init__(self, destination=None, encoding=None,
+                 encoding_errors='backslashreplace',
+                 decoding_errors='replace'):
+        """
+        :Parameters:
+            - `destination`: a file-like object,
+                        a string (path to a file),
+                        `None` (write to `sys.stderr`, default), or
+                        evaluating to `False` (write() requests are ignored).
+            - `encoding`: `destination` text encoding. Guessed if None.
+            - `encoding_errors`: how to treat encoding errors.
+        """
+        if destination is None:
+            destination = sys.stderr
+        elif not destination:
+            destination = False
+        # if `destination` is a file name, open it
+        elif isinstance(destination, str):
+            destination = open(destination, 'w')
+
+        self.destination = destination
+        """Where warning output is sent."""
+
+        self.encoding = (encoding or getattr(destination, 'encoding', None)
+                         or _locale_encoding or 'ascii')
+        """The output character encoding."""
+
+        self.encoding_errors = encoding_errors
+        """Encoding error handler."""
+
+        self.decoding_errors = decoding_errors
+        """Decoding error handler."""
+
+    def write(self, data):
+        """
+        Write `data` to self.destination. Ignore, if self.destination is False.
+
+        `data` can be a `bytes`, `str`, or `Exception` instance.
+        """
+        if not self.destination:
+            return
+        if isinstance(data, Exception):
+            data = str(data)
+        try:
+            self.destination.write(data)
+        except UnicodeEncodeError:
+            self.destination.write(data.encode(self.encoding,
+                                               self.encoding_errors))
+        except TypeError:
+            if isinstance(data, str):  # destination may expect bytes
+                self.destination.write(data.encode(self.encoding,
+                                                   self.encoding_errors))
+            elif self.destination in (sys.stderr, sys.stdout):
+                # write bytes to raw stream
+                self.destination.buffer.write(data)
+            else:
+                self.destination.write(str(data, self.encoding,
+                                           self.decoding_errors))
+
+    def close(self):
+        """
+        Close the error-output stream.
+
+        Ignored if the destination is` sys.stderr` or `sys.stdout` or has no
+        close() method.
+        """
+        if self.destination in (sys.stdout, sys.stderr):
+            return
+        try:
+            self.destination.close()
+        except AttributeError:
+            pass
+
+    def isatty(self):
+        """Return True, if the destination is connected to a TTY device."""
+        try:
+            return self.destination.isatty()
+        except AttributeError:
+            return False
+
+
 class FileInput(Input):
 
     """
@@ -205,17 +358,16 @@ class FileInput(Input):
     """
     def __init__(self, source=None, source_path=None,
                  encoding=None, error_handler='strict',
-                 autoclose=True, handle_io_errors=None, mode='r'):
+                 autoclose=True, mode='r'):
         """
         :Parameters:
             - `source`: either a file-like object (which is read directly), or
               `None` (which implies `sys.stdin` if no `source_path` given).
-            - `source_path`: a path to a file, which is opened and then read.
+            - `source_path`: a path to a file, which is opened for reading.
             - `encoding`: the expected text encoding of the input file.
             - `error_handler`: the encoding error handler to use.
             - `autoclose`: close automatically after read (except when
               `sys.stdin` is the source).
-            - `handle_io_errors`: ignored, deprecated, will be removed.
             - `mode`: how the file is to be opened (see standard function
               `open`). The default is read only ('r').
         """
@@ -225,21 +377,15 @@ class FileInput(Input):
 
         if source is None:
             if source_path:
-                # Specify encoding in Python 3
-                if sys.version_info >= (3,0):
-                    kwargs = {'encoding': self.encoding,
-                              'errors': self.error_handler}
-                else:
-                    kwargs = {}
-
                 try:
-                    self.source = open(source_path, mode, **kwargs)
-                except IOError as error:
+                    self.source = open(source_path, mode,
+                                       encoding=self.encoding,
+                                       errors=self.error_handler)
+                except OSError as error:
                     raise InputError(error.errno, error.strerror, source_path)
             else:
                 self.source = sys.stdin
-        elif (sys.version_info >= (3,0) and
-              check_encoding(self.source, self.encoding) is False):
+        elif check_encoding(self.source, self.encoding) is False:
             # TODO: re-open, warn or raise error?
             raise UnicodeError('Encoding clash: encoding given is "%s" '
                                'but source is opened with encoding "%s".' %
@@ -252,35 +398,26 @@ class FileInput(Input):
 
     def read(self):
         """
-        Read and decode a single file and return the data (Unicode string).
+        Read and decode a single file, return as `str`.
         """
-        try: # In Python < 2.5, try...except has to be nested in try...finally.
-            try:
-                if self.source is sys.stdin and sys.version_info >= (3,0):
-                    # read as binary data to circumvent auto-decoding
-                    data = self.source.buffer.read()
-                    # normalize newlines
-                    data = b('\n').join(data.splitlines()) + b('\n')
-                else:
-                    data = self.source.read()
-            except (UnicodeError, LookupError) as err: # (in Py3k read() decodes)
-                if not self.encoding and self.source_path:
-                    # re-read in binary mode and decode with heuristics
-                    b_source = open(self.source_path, 'rb')
-                    data = b_source.read()
-                    b_source.close()
-                    # normalize newlines
-                    data = b('\n').join(data.splitlines()) + b('\n')
-                else:
-                    raise
+        try:
+            if not self.encoding and hasattr(self.source, 'buffer'):
+                # read as binary data
+                data = self.source.buffer.read()
+                # decode with heuristics
+                data = self.decode(data)
+                # normalize newlines
+                data = '\n'.join(data.splitlines()+[''])
+            else:
+                data = self.source.read()
         finally:
             if self.autoclose:
                 self.close()
-        return self.decode(data)
+        return data
 
     def readlines(self):
         """
-        Return lines of a single file as list of Unicode strings.
+        Return lines of a single file as list of strings.
         """
         return self.read().splitlines(True)
 
@@ -291,9 +428,9 @@ class FileInput(Input):
 
 class FileOutput(Output):
 
-    """
-    Output for single, simple file-like objects.
-    """
+    """Output for single, simple file-like objects."""
+
+    default_destination_path = '<file>'
 
     mode = 'w'
     """The mode argument for `open()`."""
@@ -324,6 +461,10 @@ class FileOutput(Output):
                         encoding, error_handler)
         self.opened = True
         self.autoclose = autoclose
+        if handle_io_errors is not None:
+            warnings.warn('io.FileOutput: init argument "handle_io_errors" '
+                          'is ignored and will be removed in '
+                          'Docutils 2.0.', DeprecationWarning, stacklevel=2)
         if mode is not None:
             self.mode = mode
         self._stderr = ErrorOutput()
@@ -332,12 +473,12 @@ class FileOutput(Output):
                 self.opened = False
             else:
                 self.destination = sys.stdout
-        elif (# destination is file-type object -> check mode:
+        elif (  # destination is file-type object -> check mode:
               mode and hasattr(self.destination, 'mode')
               and mode != self.destination.mode):
-                print(('Warning: Destination mode "%s" '
-                               'differs from specified mode "%s"' %
-                               (self.destination.mode, mode)), file=self._stderr)
+            print('Warning: Destination mode "%s" differs from specified '
+                  'mode "%s"' % (self.destination.mode, mode),
+                  file=self._stderr)
         if not destination_path:
             try:
                 self.destination_path = self.destination.name
@@ -345,54 +486,60 @@ class FileOutput(Output):
                 pass
 
     def open(self):
-        # Specify encoding in Python 3.
-        if sys.version_info >= (3,0) and 'b' not in self.mode:
+        # Specify encoding
+        if 'b' not in self.mode:
             kwargs = {'encoding': self.encoding,
                       'errors': self.error_handler}
         else:
             kwargs = {}
         try:
             self.destination = open(self.destination_path, self.mode, **kwargs)
-        except IOError as error:
+        except OSError as error:
             raise OutputError(error.errno, error.strerror,
                               self.destination_path)
         self.opened = True
 
     def write(self, data):
-        """Encode `data`, write it to a single file, and return it.
+        """Write `data` to a single file, also return it.
 
-        With Python 3 or binary output mode, `data` is returned unchanged,
-        except when specified encoding and output encoding differ.
+        `data` can be a `str` or `bytes` instance.
+        If writing `bytes` fails, an attempt is made to write to
+        the low-level interface ``self.destination.buffer``.
+
+        If `data` is a `str` instance and `self.encoding` and
+        `self.destination.encoding` are  set to different values, `data`
+        is encoded to a `bytes` instance using `self.encoding`.
+
+        Provisional: future versions may raise an error if `self.encoding`
+        and `self.destination.encoding` are set to different values.
         """
         if not self.opened:
             self.open()
-        if ('b' not in self.mode and sys.version_info < (3,0)
-            or check_encoding(self.destination, self.encoding) is False
-           ):
-            if sys.version_info >= (3,0) and os.linesep != '\n':
-                data = data.replace('\n', os.linesep) # fix endings
+        if (isinstance(data, str)
+            and check_encoding(self.destination, self.encoding) is False):
+            if os.linesep != '\n':
+                data = data.replace('\n', os.linesep)  # fix endings
             data = self.encode(data)
 
-        try: # In Python < 2.5, try...except has to be nested in try...finally.
-            try:
-                self.destination.write(data)
-            except TypeError as e:
-                if sys.version_info >= (3,0) and isinstance(data, bytes):
-                    try:
-                        self.destination.buffer.write(data)
-                    except AttributeError:
-                        if check_encoding(self.destination, 
-                                          self.encoding) is False:
-                            raise ValueError('Encoding of %s (%s) differs \n'
-                                '  from specified encoding (%s)' %
-                                (self.destination_path or 'destination',
-                                self.destination.encoding, self.encoding))
-                        else:
-                            raise e
-            except (UnicodeError, LookupError) as err:
-                raise UnicodeError(
-                    'Unable to encode output data. output-encoding is: '
-                    '%s.\n(%s)' % (self.encoding, ErrorString(err)))
+        try:
+            self.destination.write(data)
+        except TypeError as err:
+            if isinstance(data, bytes):
+                try:
+                    self.destination.buffer.write(data)
+                except AttributeError:
+                    if check_encoding(self.destination,
+                                      self.encoding) is False:
+                        raise ValueError(
+                            f'Encoding of {self.destination_path} '
+                            f'({self.destination.encoding}) differs \n'
+                            f'  from specified encoding ({self.encoding})')
+                    else:
+                        raise err
+        except (UnicodeError, LookupError) as err:
+            raise UnicodeError(
+                'Unable to encode output data. output-encoding is: '
+                f'{self.encoding}.\n({error_string(err)})')
         finally:
             if self.autoclose:
                 self.close()
@@ -409,60 +556,69 @@ class BinaryFileOutput(FileOutput):
     A version of docutils.io.FileOutput which writes to a binary file.
     """
     # Used by core.publish_cmdline_to_binary() which in turn is used by
-    # rst2odt (OpenOffice writer)
+    # tools/rst2odt.py but not by core.rst2odt().
     mode = 'wb'
 
 
 class StringInput(Input):
-
-    """
-    Direct string input.
-    """
+    """Input from a `str` or `bytes` instance."""
 
     default_source_path = '<string>'
 
     def read(self):
-        """Decode and return the source string."""
+        """Return the source as `str` instance.
+
+        Decode, if required (see `Input.decode`).
+        """
         return self.decode(self.source)
 
 
 class StringOutput(Output):
+    """Output to a `bytes` or `str` instance.
 
-    """
-    Direct string output.
+    Provisional.
     """
 
     default_destination_path = '<string>'
 
     def write(self, data):
-        """Encode `data`, store it in `self.destination`, and return it."""
+        """Store `data` in `self.destination`, and return it.
+
+        If `self.encoding` is set to the pseudo encoding name "unicode",
+        `data` must be a `str` instance and is stored/returned unchanged
+        (cf. `Output.encode`).
+
+        Otherwise, `data` can be a `bytes` or `str` instance and is
+        stored/returned as a `bytes` instance
+        (`str` data is encoded with `self.encode()`).
+
+        Attention: 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).
+        """
         self.destination = self.encode(data)
         return self.destination
 
 
 class NullInput(Input):
 
-    """
-    Degenerate input: read nothing.
-    """
+    """Degenerate input: read nothing."""
 
     default_source_path = 'null input'
 
     def read(self):
-        """Return a null string."""
+        """Return an empty string."""
         return ''
 
 
 class NullOutput(Output):
 
-    """
-    Degenerate output: write nothing.
-    """
+    """Degenerate output: write nothing."""
 
     default_destination_path = 'null output'
 
     def write(self, data):
-        """Do nothing ([don't even] send data to the bit bucket)."""
+        """Do nothing, return None."""
         pass
 
 

python/helpers/py3only/docutils/languages/__init__.py

@@ -1,9 +1,9 @@
-# $Id: __init__.py 7648 2013-04-18 07:36:22Z milde $
+# $Id: __init__.py 9030 2022-03-05 23:28:32Z milde $
 # Author: David Goodger <goodger@python.org>
 # Copyright: This module has been placed in the public domain.
 
 # Internationalization details are documented in
-# <http://docutils.sf.net/docs/howto/i18n.html>.
+# <https://docutils.sourceforge.io/docs/howto/i18n.html>.
 
 """
 This package contains modules for language-dependent features of Docutils.
@@ -11,38 +11,73 @@ This package contains modules for language-dependent features of Docutils.
 
 __docformat__ = 'reStructuredText'
 
-import sys
+from importlib import import_module
 
 from docutils.utils import normalize_language_tag
-if sys.version_info < (2,5):
-    from docutils._compat import __import__
 
-_languages = {}
 
-def get_language(language_code, reporter=None):
-    """Return module with language localizations.
+class LanguageImporter:
+    """Import language modules.
 
-    `language_code` is a "BCP 47" language tag.
-    If there is no matching module, warn and fall back to English.
+    When called with a BCP 47 language tag, instances return a module
+    with localisations from `docutils.languages` or the PYTHONPATH.
+
+    If there is no matching module, warn (if a `reporter` is passed)
+    and fall back to English.
     """
-    # TODO: use a dummy module returning emtpy strings?, configurable?
-    for tag in normalize_language_tag(language_code):
-        tag = tag.replace('-','_') # '-' not valid in module names
-        if tag in _languages:
-            return _languages[tag]
-        try:
-            module = __import__(tag, globals(), locals(), level=1)
-        except ImportError:
+    packages = ('docutils.languages.', '')
+    warn_msg = ('Language "%s" not supported: '
+                'Docutils-generated text will be in English.')
+    fallback = 'en'
+    # TODO: use a dummy module returning empty strings?, configurable?
+
+    def __init__(self):
+        self.cache = {}
+
+    def import_from_packages(self, name, reporter=None):
+        """Try loading module `name` from `self.packages`."""
+        module = None
+        for package in self.packages:
             try:
-                module = __import__(tag, globals(), locals(), level=0)
-            except ImportError:
+                module = import_module(package+name)
+                self.check_content(module)
+            except (ImportError, AttributeError):
+                if reporter and module:
+                    reporter.info(f'{module} is no complete '
+                                  'Docutils language module.')
+                elif reporter:
+                    reporter.info(f'Module "{package+name}" not found.')
                 continue
-        _languages[tag] = module
+            break
         return module
-    if reporter is not None:
-        reporter.warning(
-            'language "%s" not supported: ' % language_code +
-            'Docutils-generated text will be in English.')
-    module = __import__('en', globals(), locals(), level=1)
-    _languages[tag] = module # warn only one time!
-    return module
+
+    def check_content(self, module):
+        """Check if we got a Docutils language module."""
+        if not (isinstance(module.labels, dict)
+                and isinstance(module.bibliographic_fields, dict)
+                and isinstance(module.author_separators, list)):
+            raise ImportError
+
+    def __call__(self, language_code, reporter=None):
+        try:
+            return self.cache[language_code]
+        except KeyError:
+            pass
+        for tag in normalize_language_tag(language_code):
+            tag = tag.replace('-', '_')  # '-' not valid in module names
+            module = self.import_from_packages(tag, reporter)
+            if module is not None:
+                break
+        else:
+            if reporter:
+                reporter.warning(self.warn_msg % language_code)
+            if self.fallback:
+                module = self.import_from_packages(self.fallback)
+        if reporter and (language_code != 'en'):
+            reporter.info('Using %s for language "%s".'
+                          % (module, language_code))
+        self.cache[language_code] = module
+        return module
+
+
+get_language = LanguageImporter()

python/helpers/py3only/docutils/languages/af.py

@@ -1,11 +1,11 @@
-# $Id: af.py 4564 2006-05-21 20:44:42Z wiemann $
+# $Id: af.py 9030 2022-03-05 23:28:32Z milde $
 # Author: Jannie Hofmeyr <jhsh@sun.ac.za>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Afrikaans-language mappings for language-dependent features of Docutils.
@@ -33,7 +33,7 @@ labels = {
       'hint': 'Wenk',
       'important': 'Belangrik',
       'note': 'Nota',
-      'tip': 'Tip', # hint and tip both have the same translation: wenk
+      'tip': 'Tip',  # hint and tip both have the same translation: wenk
       'warning': 'Waarskuwing',
       'contents': 'Inhoud'}
 """Mapping of node class name to label text."""

python/helpers/py3only/docutils/languages/ar.py

@@ -0,0 +1,60 @@
+# $Id: fa.py 4564 2016-08-10 11:48:42Z
+# Author: Shahin <me@5hah.in>
+# Copyright: This module has been placed in the public domain.
+
+# New language mappings are welcome.  Before doing a new translation, please
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
+
+"""
+Arabic-language mappings for language-dependent features of Docutils.
+"""
+
+__docformat__ = 'reStructuredText'
+
+labels = {
+      # fixed: language-dependent
+      'author': 'المؤلف',
+      'authors': 'المؤلفون',
+      'organization': 'التنظيم',
+      'address': 'العنوان',
+      'contact': 'اتصل',
+      'version': 'نسخة',
+      'revision': 'مراجعة',
+      'status': 'الحالة',
+      'date': 'تاریخ',
+      'copyright': 'الحقوق',
+      'dedication': 'إهداء',
+      'abstract': 'ملخص',
+      'attention': 'تنبيه',
+      'caution': 'احتیاط',
+      'danger': 'خطر',
+      'error': 'خطأ',
+      'hint': 'تلميح',
+      'important': 'مهم',
+      'note': 'ملاحظة',
+      'tip': 'نصيحة',
+      'warning': 'تحذير',
+      'contents': 'المحتوى'}
+"""Mapping of node class name to label text."""
+
+bibliographic_fields = {
+      # language-dependent: fixed
+      'مؤلف': 'author',
+      'مؤلفون': 'authors',
+      'التنظيم': 'organization',
+      'العنوان': 'address',
+      'اتصل': 'contact',
+      'نسخة': 'version',
+      'مراجعة': 'revision',
+      'الحالة': 'status',
+      'تاریخ': 'date',
+      'الحقوق': 'copyright',
+      'إهداء': 'dedication',
+      'ملخص': 'abstract'}
+"""Arabic (lowcased) to canonical name mapping for bibliographic fields."""
+
+author_separators = ['؛', '،']
+"""List of separator strings for the 'Authors' bibliographic field. Tried in
+order."""

python/helpers/py3only/docutils/languages/ca.py

@@ -1,11 +1,16 @@
-# $Id: ca.py 4564 2006-05-21 20:44:42Z wiemann $
-# Author: Ivan Vilata i Balaguer <ivan@selidor.net>
+# $Id: ca.py 9457 2023-10-02 16:25:50Z milde $
+# Authors: Ivan Vilata i Balaguer <ivan@selidor.net>;
+#          Antoni Bella Pérez <antonibella5@yahoo.com>
 # Copyright: This module has been placed in the public domain.
 
-# New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# New language mappings are welcome.  Before doing a new translation,
+# please read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
+
+# These translations can be used without changes for
+# Valencian variant of Catalan (use language tag "ca-valencia").
+# Checked by a native speaker of Valentian.
 
 """
 Catalan-language mappings for language-dependent features of Docutils.
@@ -17,17 +22,17 @@ labels = {
       # fixed: language-dependent
       'author': 'Autor',
       'authors': 'Autors',
-      'organization': 'Organitzaci\u00F3',
-      'address': 'Adre\u00E7a',
+      'organization': 'Organització',
+      'address': 'Adreça',
       'contact': 'Contacte',
-      'version': 'Versi\u00F3',
-      'revision': 'Revisi\u00F3',
+      'version': 'Versió',
+      'revision': 'Revisió',
       'status': 'Estat',
       'date': 'Data',
       'copyright': 'Copyright',
-      'dedication': 'Dedicat\u00F2ria',
+      'dedication': 'Dedicatòria',
       'abstract': 'Resum',
-      'attention': 'Atenci\u00F3!',
+      'attention': 'Atenció!',
       'caution': 'Compte!',
       'danger': 'PERILL!',
       'error': 'Error',
@@ -35,7 +40,7 @@ labels = {
       'important': 'Important',
       'note': 'Nota',
       'tip': 'Consell',
-      'warning': 'Av\u00EDs',
+      'warning': 'Avís',
       'contents': 'Contingut'}
 """Mapping of node class name to label text."""
 
@@ -43,15 +48,15 @@ bibliographic_fields = {
       # language-dependent: fixed
       'autor': 'author',
       'autors': 'authors',
-      'organitzaci\u00F3': 'organization',
-      'adre\u00E7a': 'address',
+      'organització': 'organization',
+      'adreça': 'address',
       'contacte': 'contact',
-      'versi\u00F3': 'version',
-      'revisi\u00F3': 'revision',
+      'versió': 'version',
+      'revisió': 'revision',
       'estat': 'status',
       'data': 'date',
       'copyright': 'copyright',
-      'dedicat\u00F2ria': 'dedication',
+      'dedicatòria': 'dedication',
       'resum': 'abstract'}
 """Catalan (lowcased) to canonical name mapping for bibliographic fields."""
 

python/helpers/py3only/docutils/languages/cs.py

@@ -1,11 +1,11 @@
-# $Id: cs.py 4564 2006-05-21 20:44:42Z wiemann $
+# $Id: cs.py 9452 2023-09-27 00:11:54Z milde $
 # Author: Marek Blaha <mb@dat.cz>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Czech-language mappings for language-dependent features of Docutils.
@@ -16,7 +16,7 @@ __docformat__ = 'reStructuredText'
 labels = {
       # fixed: language-dependent
       'author': 'Autor',
-      'authors': 'Auto\u0159i',
+      'authors': 'Autoři',
       'organization': 'Organizace',
       'address': 'Adresa',
       'contact': 'Kontakt',
@@ -25,24 +25,24 @@ labels = {
       'status': 'Stav',
       'date': 'Datum',
       'copyright': 'Copyright',
-      'dedication': 'V\u011Bnov\u00E1n\u00ED',
+      'dedication': 'Věnování',
       'abstract': 'Abstrakt',
       'attention': 'Pozor!',
-      'caution': 'Opatrn\u011B!',
-      'danger': '!NEBEZPE\u010C\u00CD!',
+      'caution': 'Opatrně!',
+      'danger': '!NEBEZPEČÍ!',
       'error': 'Chyba',
       'hint': 'Rada',
-      'important': 'D\u016Fle\u017Eit\u00E9',
-      'note': 'Pozn\u00E1mka',
+      'important': 'Důležité',
+      'note': 'Poznámka',
       'tip': 'Tip',
-      'warning': 'Varov\u00E1n\u00ED',
+      'warning': 'Varování',
       'contents': 'Obsah'}
 """Mapping of node class name to label text."""
 
 bibliographic_fields = {
       # language-dependent: fixed
       'autor': 'author',
-      'auto\u0159i': 'authors',
+      'autoři': 'authors',
       'organizace': 'organization',
       'adresa': 'address',
       'kontakt': 'contact',
@@ -51,7 +51,7 @@ bibliographic_fields = {
       'stav': 'status',
       'datum': 'date',
       'copyright': 'copyright',
-      'v\u011Bnov\u00E1n\u00ED': 'dedication',
+      'věnování': 'dedication',
       'abstrakt': 'abstract'}
 """Czech (lowcased) to canonical name mapping for bibliographic fields."""
 

python/helpers/py3only/docutils/languages/da.py

@@ -1,12 +1,11 @@
-# -*- coding: utf-8 -*-
-# $Id: da.py 7678 2013-07-03 09:57:36Z milde $
+# $Id: da.py 9030 2022-03-05 23:28:32Z milde $
 # Author: E D
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Danish-language mappings for language-dependent features of Docutils.

python/helpers/py3only/docutils/languages/de.py

@@ -1,11 +1,11 @@
-# $Id: de.py 4564 2006-05-21 20:44:42Z wiemann $
+# $Id: de.py 9030 2022-03-05 23:28:32Z milde $
 # Author: Gunnar Schwant <g.schwant@gmx.de>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 German language mappings for language-dependent features of Docutils.

python/helpers/py3only/docutils/languages/en.py

@@ -1,11 +1,11 @@
-# $Id: en.py 4564 2006-05-21 20:44:42Z wiemann $
+# $Id: en.py 9030 2022-03-05 23:28:32Z milde $
 # Author: David Goodger <goodger@python.org>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 English-language mappings for language-dependent features of Docutils.

python/helpers/py3only/docutils/languages/eo.py

@@ -1,11 +1,11 @@
-# $Id: eo.py 4564 2006-05-21 20:44:42Z wiemann $
+# $Id: eo.py 9452 2023-09-27 00:11:54Z milde $
 # Author: Marcelo Huerta San Martin <richieadler@users.sourceforge.net>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Esperanto-language mappings for language-dependent features of Docutils.
@@ -15,8 +15,8 @@ __docformat__ = 'reStructuredText'
 
 labels = {
       # fixed: language-dependent
-      'author': 'A\u016dtoro',
-      'authors': 'A\u016dtoroj',
+      'author': 'Aŭtoro',
+      'authors': 'Aŭtoroj',
       'organization': 'Organizo',
       'address': 'Adreso',
       'contact': 'Kontakto',
@@ -24,13 +24,13 @@ labels = {
       'revision': 'Revido',
       'status': 'Stato',
       'date': 'Dato',
-      # 'copyright': u'Kopirajto',
-      'copyright': 'A\u016dtorrajto',
-      'dedication': 'Dedi\u0109o',
+      # 'copyright': 'Kopirajto',
+      'copyright': 'Aŭtorrajto',
+      'dedication': 'Dediĉo',
       'abstract': 'Resumo',
       'attention': 'Atentu!',
       'caution': 'Zorgu!',
-      'danger': 'DAN\u011cERO!',
+      'danger': 'DANĜERO!',
       'error': 'Eraro',
       'hint': 'Spuro',
       'important': 'Grava',
@@ -42,8 +42,8 @@ labels = {
 
 bibliographic_fields = {
       # language-dependent: fixed
-      'a\\u016dtoro': 'author',
-      'a\\u016dtoroj': 'authors',
+      'aŭtoro': 'author',
+      'aŭtoroj': 'authors',
       'organizo': 'organization',
       'adreso': 'address',
       'kontakto': 'contact',
@@ -51,8 +51,8 @@ bibliographic_fields = {
       'revido': 'revision',
       'stato': 'status',
       'dato': 'date',
-      'a\\u016dtorrajto': 'copyright',
-      'dedi\\u0109o': 'dedication',
+      'aŭtorrajto': 'copyright',
+      'dediĉo': 'dedication',
       'resumo': 'abstract'}
 """Esperanto (lowcased) to canonical name mapping for bibliographic fields."""
 

python/helpers/py3only/docutils/languages/es.py

@@ -1,12 +1,11 @@
-# -*- coding: utf-8 -*-
-# $Id: es.py 4572 2006-05-25 20:48:37Z richieadler $
+# $Id: es.py 9452 2023-09-27 00:11:54Z milde $
 # Author: Marcelo Huerta San Martín <richieadler@users.sourceforge.net>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Spanish-language mappings for language-dependent features of Docutils.
@@ -17,19 +16,19 @@ __docformat__ = 'reStructuredText'
 labels = {
       'author': 'Autor',
       'authors': 'Autores',
-      'organization': 'Organizaci\u00f3n',
-      'address': 'Direcci\u00f3n',
+      'organization': 'Organización',
+      'address': 'Dirección',
       'contact': 'Contacto',
-      'version': 'Versi\u00f3n',
-      'revision': 'Revisi\u00f3n',
+      'version': 'Versión',
+      'revision': 'Revisión',
       'status': 'Estado',
       'date': 'Fecha',
       'copyright': 'Copyright',
       'dedication': 'Dedicatoria',
       'abstract': 'Resumen',
-      'attention': '\u00a1Atenci\u00f3n!',
-      'caution': '\u00a1Precauci\u00f3n!',
-      'danger': '\u00a1PELIGRO!',
+      'attention': '¡Atención!',
+      'caution': '¡Precaución!',
+      'danger': '¡PELIGRO!',
       'error': 'Error',
       'hint': 'Sugerencia',
       'important': 'Importante',
@@ -42,11 +41,11 @@ labels = {
 bibliographic_fields = {
       'autor': 'author',
       'autores': 'authors',
-      'organizaci\u00f3n': 'organization',
-      'direcci\u00f3n': 'address',
+      'organización': 'organization',
+      'dirección': 'address',
       'contacto': 'contact',
-      'versi\u00f3n': 'version',
-      'revisi\u00f3n': 'revision',
+      'versión': 'version',
+      'revisión': 'revision',
       'estado': 'status',
       'fecha': 'date',
       'copyright': 'copyright',

python/helpers/py3only/docutils/languages/fa.py

@@ -0,0 +1,60 @@
+# $Id: fa.py 4564 2016-08-10 11:48:42Z
+# Author: Shahin <me@5hah.in>
+# Copyright: This module has been placed in the public domain.
+
+# New language mappings are welcome.  Before doing a new translation, please
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
+
+"""
+Persian-language mappings for language-dependent features of Docutils.
+"""
+
+__docformat__ = 'reStructuredText'
+
+labels = {
+      # fixed: language-dependent
+      'author': 'نویسنده',
+      'authors': 'نویسندگان',
+      'organization': 'سازمان',
+      'address': 'آدرس',
+      'contact': 'تماس',
+      'version': 'نسخه',
+      'revision': 'بازبینی',
+      'status': 'وضعیت',
+      'date': 'تاریخ',
+      'copyright': 'کپی‌رایت',
+      'dedication': 'تخصیص',
+      'abstract': 'چکیده',
+      'attention': 'توجه!',
+      'caution': 'احتیاط!',
+      'danger': 'خطر!',
+      'error': 'خطا',
+      'hint': 'راهنما',
+      'important': 'مهم',
+      'note': 'یادداشت',
+      'tip': 'نکته',
+      'warning': 'اخطار',
+      'contents': 'محتوا'}
+"""Mapping of node class name to label text."""
+
+bibliographic_fields = {
+      # language-dependent: fixed
+      'نویسنده': 'author',
+      'نویسندگان': 'authors',
+      'سازمان': 'organization',
+      'آدرس': 'address',
+      'تماس': 'contact',
+      'نسخه': 'version',
+      'بازبینی': 'revision',
+      'وضعیت': 'status',
+      'تاریخ': 'date',
+      'کپی‌رایت': 'copyright',
+      'تخصیص': 'dedication',
+      'چکیده': 'abstract'}
+"""Persian (lowcased) to canonical name mapping for bibliographic fields."""
+
+author_separators = ['؛', '،']
+"""List of separator strings for the 'Authors' bibliographic field. Tried in
+order."""

python/helpers/py3only/docutils/languages/fi.py

@@ -1,11 +1,11 @@
-# $Id: fi.py 4564 2006-05-21 20:44:42Z wiemann $
+# $Id: fi.py 9452 2023-09-27 00:11:54Z milde $
 # Author: Asko Soukka <asko.soukka@iki.fi>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Finnish-language mappings for language-dependent features of Docutils.
@@ -15,44 +15,44 @@ __docformat__ = 'reStructuredText'
 
 labels = {
       # fixed: language-dependent
-      'author': 'Tekij\u00e4',
-      'authors': 'Tekij\u00e4t',
-      'organization': 'Yhteis\u00f6',
+      'author': 'Tekijä',
+      'authors': 'Tekijät',
+      'organization': 'Yhteisö',
       'address': 'Osoite',
       'contact': 'Yhteystiedot',
       'version': 'Versio',
       'revision': 'Vedos',
       'status': 'Tila',
-      'date': 'P\u00e4iv\u00e4ys',
-      'copyright': 'Tekij\u00e4noikeudet',
+      'date': 'Päiväys',
+      'copyright': 'Tekijänoikeudet',
       'dedication': 'Omistuskirjoitus',
-      'abstract': 'Tiivistelm\u00e4',
+      'abstract': 'Tiivistelmä',
       'attention': 'Huomio!',
       'caution': 'Varo!',
       'danger': '!VAARA!',
       'error': 'Virhe',
       'hint': 'Vihje',
-      'important': 'T\u00e4rke\u00e4\u00e4',
+      'important': 'Tärkeää',
       'note': 'Huomautus',
       'tip': 'Neuvo',
       'warning': 'Varoitus',
-      'contents': 'Sis\u00e4llys'}
+      'contents': 'Sisällys'}
 """Mapping of node class name to label text."""
 
 bibliographic_fields = {
       # language-dependent: fixed
-      'tekij\u00e4': 'author',
-      'tekij\u00e4t': 'authors',
-      'yhteis\u00f6': 'organization',
+      'tekijä': 'author',
+      'tekijät': 'authors',
+      'yhteisö': 'organization',
       'osoite': 'address',
       'yhteystiedot': 'contact',
       'versio': 'version',
       'vedos': 'revision',
       'tila': 'status',
-      'p\u00e4iv\u00e4ys': 'date',
-      'tekij\u00e4noikeudet': 'copyright',
+      'päiväys': 'date',
+      'tekijänoikeudet': 'copyright',
       'omistuskirjoitus': 'dedication',
-      'tiivistelm\u00e4': 'abstract'}
+      'tiivistelmä': 'abstract'}
 """Finnish (lowcased) to canonical name mapping for bibliographic fields."""
 
 author_separators = [';', ',']

python/helpers/py3only/docutils/languages/fr.py

@@ -1,11 +1,11 @@
-# $Id: fr.py 4564 2006-05-21 20:44:42Z wiemann $
+# $Id: fr.py 9452 2023-09-27 00:11:54Z milde $
 # Author: Stefane Fermigier <sf@fermigier.com>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 French-language mappings for language-dependent features of Docutils.
@@ -20,12 +20,12 @@ labels = {
       'address': 'Adresse',
       'contact': 'Contact',
       'version': 'Version',
-      'revision': 'R\u00e9vision',
+      'revision': 'Révision',
       'status': 'Statut',
       'date': 'Date',
       'copyright': 'Copyright',
-      'dedication': 'D\u00e9dicace',
-      'abstract': 'R\u00e9sum\u00e9',
+      'dedication': 'Dédicace',
+      'abstract': 'Résumé',
       'attention': 'Attention!',
       'caution': 'Avertissement!',
       'danger': '!DANGER!',
@@ -45,12 +45,12 @@ bibliographic_fields = {
       'adresse': 'address',
       'contact': 'contact',
       'version': 'version',
-      'r\u00e9vision': 'revision',
+      'révision': 'revision',
       'statut': 'status',
       'date': 'date',
       'copyright': 'copyright',
-      'd\u00e9dicace': 'dedication',
-      'r\u00e9sum\u00e9': 'abstract'}
+      'dédicace': 'dedication',
+      'résumé': 'abstract'}
 """French (lowcased) to canonical name mapping for bibliographic fields."""
 
 author_separators = [';', ',']

python/helpers/py3only/docutils/languages/gl.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 # Author: David Goodger
 # Contact: goodger@users.sourceforge.net
 # Revision: $Revision: 2224 $
@@ -6,9 +5,9 @@
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Galician-language mappings for language-dependent features of Docutils.
@@ -20,24 +19,24 @@ labels = {
       # fixed: language-dependent
       'author': 'Autor',
       'authors': 'Autores',
-      'organization': 'Organizaci\u00f3n',
+      'organization': 'Organización',
       'address': 'Enderezo',
       'contact': 'Contacto',
-      'version': 'Versi\u00f3n',
-      'revision': 'Revisi\u00f3n',
+      'version': 'Versión',
+      'revision': 'Revisión',
       'status': 'Estado',
       'date': 'Data',
       'copyright': 'Dereitos de copia',
       'dedication': 'Dedicatoria',
       'abstract': 'Abstract',
-      'attention': 'Atenci\u00f3n!',
+      'attention': 'Atención!',
       'caution': 'Advertencia!',
       'danger': 'PERIGO!',
       'error': 'Erro',
       'hint': 'Consello',
       'important': 'Importante',
       'note': 'Nota',
-      'tip': 'Suxesti\u00f3n',
+      'tip': 'Suxestión',
       'warning': 'Aviso',
       'contents': 'Contido'}
 """Mapping of node class name to label text."""
@@ -46,11 +45,11 @@ bibliographic_fields = {
       # language-dependent: fixed
       'autor': 'author',
       'autores': 'authors',
-      'organizaci\u00f3n': 'organization',
+      'organización': 'organization',
       'enderezo': 'address',
       'contacto': 'contact',
-      'versi\u00f3n': 'version',
-      'revisi\u00f3n': 'revision',
+      'versión': 'version',
+      'revisión': 'revision',
       'estado': 'status',
       'data': 'date',
       'dereitos de copia': 'copyright',

python/helpers/py3only/docutils/languages/he.py

@@ -1,11 +1,11 @@
 # Author: Meir Kriheli
-# Id: $Id: he.py 4837 2006-12-26 09:59:41Z sfcben $
+# Id: $Id: he.py 9452 2023-09-27 00:11:54Z milde $
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Hebrew-language mappings for language-dependent features of Docutils.
@@ -14,45 +14,47 @@ Hebrew-language mappings for language-dependent features of Docutils.
 __docformat__ = 'reStructuredText'
 
 labels = {
-      # fixed: language-dependent
-      'author': '\u05de\u05d7\u05d1\u05e8',
-      'authors': '\u05de\u05d7\u05d1\u05e8\u05d9',
-      'organization': '\u05d0\u05e8\u05d2\u05d5\u05df',
-      'address': '\u05db\u05ea\u05d5\u05d1\u05ea',
-      'contact':  '\u05d0\u05d9\u05e9 \u05e7\u05e9\u05e8',
-      'version': '\u05d2\u05e8\u05e1\u05d4',
-      'revision': '\u05de\u05d4\u05d3\u05d5\u05e8\u05d4',
-      'status': '\u05e1\u05d8\u05d8\u05d5\u05e1',
-      'date': '\u05ea\u05d0\u05e8\u05d9\u05da',
-      'copyright': '\u05d6\u05db\u05d5\u05d9\u05d5\u05ea \u05e9\u05de\u05d5\u05e8\u05d5\u05ea',
-      'dedication': '\u05d4\u05e7\u05d3\u05e9\u05d4',
-      'abstract': '\u05ea\u05e7\u05e6\u05d9\u05e8',
-      'attention': '\u05ea\u05e9\u05d5\u05de\u05ea \u05dc\u05d1',
-      'caution': '\u05d6\u05d4\u05d9\u05e8\u05d5\u05ea',
-      'danger': '\u05e1\u05db\u05e0\u05d4',
-      'error': '\u05e9\u05d2\u05d9\u05d0\u05d4' ,
-      'hint': '\u05e8\u05de\u05d6',
-      'important': '\u05d7\u05e9\u05d5\u05d1',
-      'note': '\u05d4\u05e2\u05e8\u05d4',
-      'tip': '\u05d8\u05d9\u05e4',
-      'warning': '\u05d0\u05d6\u05d4\u05e8\u05d4',
-      'contents': '\u05ea\u05d5\u05db\u05df'}
+    # fixed: language-dependent
+    'author': 'מחבר',
+    'authors': 'מחברי',
+    'organization': 'ארגון',
+    'address': 'כתובת',
+    'contact': 'איש קשר',
+    'version': 'גרסה',
+    'revision': 'מהדורה',
+    'status': 'סטטוס',
+    'date': 'תאריך',
+    'copyright': 'זכויות שמורות',
+    'dedication': 'הקדשה',
+    'abstract': 'תקציר',
+    'attention': 'תשומת לב',
+    'caution': 'זהירות',
+    'danger': 'סכנה',
+    'error': 'שגיאה',
+    'hint': 'רמז',
+    'important': 'חשוב',
+    'note': 'הערה',
+    'tip': 'טיפ',
+    'warning': 'אזהרה',
+    'contents': 'תוכן',
+    }
 """Mapping of node class name to label text."""
 
 bibliographic_fields = {
-      # language-dependent: fixed
-      '\u05de\u05d7\u05d1\u05e8': 'author',
-      '\u05de\u05d7\u05d1\u05e8\u05d9': 'authors',
-      '\u05d0\u05e8\u05d2\u05d5\u05df': 'organization',
-      '\u05db\u05ea\u05d5\u05d1\u05ea': 'address',
-      '\u05d0\u05d9\u05e9 \u05e7\u05e9\u05e8': 'contact',
-      '\u05d2\u05e8\u05e1\u05d4': 'version',
-      '\u05de\u05d4\u05d3\u05d5\u05e8\u05d4': 'revision',
-      '\u05e1\u05d8\u05d8\u05d5\u05e1': 'status',
-      '\u05ea\u05d0\u05e8\u05d9\u05da': 'date',
-      '\u05d6\u05db\u05d5\u05d9\u05d5\u05ea \u05e9\u05de\u05d5\u05e8\u05d5\u05ea': 'copyright',
-      '\u05d4\u05e7\u05d3\u05e9\u05d4': 'dedication',
-      '\u05ea\u05e7\u05e6\u05d9\u05e8': 'abstract'}
+    # language-dependent: fixed
+    'מחבר': 'author',
+    'מחברי': 'authors',
+    'ארגון': 'organization',
+    'כתובת': 'address',
+    'איש קשר': 'contact',
+    'גרסה': 'version',
+    'מהדורה': 'revision',
+    'סטטוס': 'status',
+    'תאריך': 'date',
+    'זכויות שמורות': 'copyright',
+    'הקדשה': 'dedication',
+    'תקציר': 'abstract',
+    }
 """Hebrew to canonical name mapping for bibliographic fields."""
 
 author_separators = [';', ',']

python/helpers/py3only/docutils/languages/it.py

@@ -1,11 +1,11 @@
-# $Id: it.py 4564 2006-05-21 20:44:42Z wiemann $
+# $Id: it.py 9030 2022-03-05 23:28:32Z milde $
 # Author: Nicola Larosa <docutils@tekNico.net>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Italian-language mappings for language-dependent features of Docutils.

python/helpers/py3only/docutils/languages/ja.py

@@ -1,12 +1,11 @@
-# -*- coding: utf-8 -*-
-# $Id: ja.py 4564 2006-05-21 20:44:42Z wiemann $
+# $Id: ja.py 9030 2022-03-05 23:28:32Z milde $
 # Author: Hisashi Morita <hisashim@kt.rim.or.jp>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Japanese-language mappings for language-dependent features of Docutils.

python/helpers/py3only/docutils/languages/ka.py

@@ -0,0 +1,58 @@
+# $Id: ka.py 9444 2023-08-23 12:02:41Z grubert $
+# Author: Temuri Doghonadze <temuri dot doghonadze at gmail dot com>
+# Copyright: This module has been placed in the public domain.
+
+# New language mappings are welcome.  Before doing a new translation, please
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
+
+"""
+Georgian-language mappings for language-dependent features of Docutils.
+"""
+
+__docformat__ = 'reStructuredText'
+
+labels = {
+      'abstract': 'ანოტაცია',
+      'address': 'მისამართი',
+      'attention': 'ყურადღება!',
+      'author': 'ავტორი',
+      'authors': 'ავტორები',
+      'caution': 'ფრთხილად!',
+      'contact': 'კონტაქტი',
+      'contents': 'შემცველობა',
+      'copyright': 'საავტორო უფლებები',
+      'danger': 'საშიშია!',
+      'date': 'თარიღი',
+      'dedication': 'მიძღვნა',
+      'error': 'შეცდომა',
+      'hint': 'რჩევა',
+      'important': 'მნიშვნელოვანია',
+      'note': 'შენიშვნა',
+      'organization': 'ორგანიზაცია',
+      'revision': 'რევიზია',
+      'status': 'სტატუსი',
+      'tip': 'მინიშნება',
+      'version': 'ვერსია',
+      'warning': 'გაფრთხილება'}
+"""Mapping of node class name to label text."""
+
+bibliographic_fields = {
+      'ანოტაცია': 'abstract',
+      'მისამართი': 'address',
+      'ავტორი': 'author',
+      'ავტორები': 'authors',
+      'კონტაქტი': 'contact',
+      'საავტორო უფლებები': 'copyright',
+      'თარიღი': 'date',
+      'მიძღვნა': 'dedication',
+      'ორგანიზაცია': 'organization',
+      'რევიზია': 'revision',
+      'სტატუსი': 'status',
+      'ვერსია': 'version'}
+"""Georgian (lowcased) to canonical name mapping for bibliographic fields."""
+
+author_separators = [';', ',']
+"""List of separator strings for the 'Authors' bibliographic field. Tried in
+order."""

python/helpers/py3only/docutils/languages/ko.py

@@ -0,0 +1,60 @@
+# $Id: ko.py 9030 2022-03-05 23:28:32Z milde $
+# Author: Thomas SJ Kang <thomas.kangsj@ujuc.kr>
+# Copyright: This module has been placed in the public domain.
+
+# New language mappings are welcome.  Before doing a new translation, please
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
+
+"""
+Korean-language mappings for language-dependent features of Docutils.
+"""
+
+__docformat__ = 'reStructuredText'
+
+labels = {
+      # fixed: language-dependent
+      'author': '저자',
+      'authors': '저자들',
+      'organization': '조직',
+      'address': '주소',
+      'contact': '연락처',
+      'version': '버전',
+      'revision': '리비전',
+      'status': '상태',
+      'date': '날짜',
+      'copyright': '저작권',
+      'dedication': '헌정',
+      'abstract': '요약',
+      'attention': '집중!',
+      'caution': '주의!',
+      'danger': '!위험!',
+      'error': '오류',
+      'hint': '실마리',
+      'important': '중요한',
+      'note': '비고',
+      'tip': '팁',
+      'warning': '경고',
+      'contents': '목차'}
+"""Mapping of node class name to label text."""
+
+bibliographic_fields = {
+      # language-dependent: fixed
+      '저자': 'author',
+      '저자들': 'authors',
+      '조직': 'organization',
+      '주소': 'address',
+      '연락처': 'contact',
+      '버전': 'version',
+      '리비전': 'revision',
+      '상태': 'status',
+      '날짜': 'date',
+      '저작권': 'copyright',
+      '헌정': 'dedication',
+      '요약': 'abstract'}
+"""Korean to canonical name mapping for bibliographic fields."""
+
+author_separators = [';', ',']
+"""List of separator strings for the 'Authors' bibliographic field. Tried in
+order."""

python/helpers/py3only/docutils/languages/lt.py

@@ -1,15 +1,14 @@
-# -*- coding: utf-8 -*-
-# $Id: lt.py 7668 2013-06-04 12:46:30Z milde $
+# $Id: lt.py 9030 2022-03-05 23:28:32Z milde $
 # Author: Dalius Dobravolskas <dalius.do...@gmail.com>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
-English-language mappings for language-dependent features of Docutils.
+Lithuanian language mappings for language-dependent features of Docutils.
 """
 
 __docformat__ = 'reStructuredText'
@@ -54,68 +53,7 @@ bibliographic_fields = {
       'autoriaus teisės': 'copyright',
       'dedikacija': 'dedication',
       'santrauka': 'abstract'}
-"""English (lowcased) to canonical name mapping for bibliographic fields."""
-
-author_separators = [';', ',']
-"""List of separator strings for the 'Authors' bibliographic field. Tried in
-order."""
-# -*- coding: utf-8 -*-
-# $Id: lt.py 7668 2013-06-04 12:46:30Z milde $
-# Author: David Goodger <goodger@python.org>
-# Copyright: This module has been placed in the public domain.
-
-# New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
-
-"""
-English-language mappings for language-dependent features of Docutils.
-"""
-
-__docformat__ = 'reStructuredText'
-
-labels = {
-      # fixed: language-dependent
-      'author': 'Autorius',
-      'authors': 'Autoriai',
-      'organization': 'Organizacija',
-      'address': 'Adresas',
-      'contact': 'Kontaktas',
-      'version': 'Versija',
-      'revision': 'Revizija',
-      'status': 'Būsena',
-      'date': 'Data',
-      'copyright': 'Autoriaus teisės',
-      'dedication': 'Dedikacija',
-      'abstract': 'Santrauka',
-      'attention': 'Dėmesio!',
-      'caution': 'Atsargiai!',
-      'danger': '!PAVOJINGA!',
-      'error': 'Klaida',
-      'hint': 'Užuomina',
-      'important': 'Svarbu',
-      'note': 'Pastaba',
-      'tip': 'Patarimas',
-      'warning': 'Įspėjimas',
-      'contents': 'Turinys'}
-"""Mapping of node class name to label text."""
-
-bibliographic_fields = {
-      # language-dependent: fixed
-      'autorius': 'author',
-      'autoriai': 'authors',
-      'organizacija': 'organization',
-      'adresas': 'address',
-      'kontaktas': 'contact',
-      'versija': 'version',
-      'revizija': 'revision',
-      'būsena': 'status',
-      'data': 'date',
-      'autoriaus teisės': 'copyright',
-      'dedikacija': 'dedication',
-      'santrauka': 'abstract'}
-"""English (lowcased) to canonical name mapping for bibliographic fields."""
+"""Lithuanian (lowcased) to canonical name mapping for bibliographic fields."""
 
 author_separators = [';', ',']
 """List of separator strings for the 'Authors' bibliographic field. Tried in

python/helpers/py3only/docutils/languages/lv.py

@@ -0,0 +1,59 @@
+# $Id: lv.py 9030 2022-03-05 23:28:32Z milde $
+# Copyright: This module has been placed in the public domain.
+
+# New language mappings are welcome.  Before doing a new translation, please
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
+
+"""
+Latvian-language mappings for language-dependent features of Docutils.
+"""
+
+__docformat__ = 'reStructuredText'
+
+labels = {
+      # fixed: language-dependent
+      'author': 'Autors',
+      'authors': 'Autori',
+      'organization': 'Organizācija',
+      'address': 'Adrese',
+      'contact': 'Kontakti',
+      'version': 'Versija',
+      'revision': 'Revīzija',
+      'status': 'Statuss',
+      'date': 'Datums',
+      'copyright': 'Copyright',
+      'dedication': 'Veltījums',
+      'abstract': 'Atreferējums',
+      'attention': 'Uzmanību!',
+      'caution': 'Piesardzību!',
+      'danger': '!BĪSTAMI!',
+      'error': 'Kļūda',
+      'hint': 'Ieteikums',
+      'important': 'Svarīgi',
+      'note': 'Piezīme',
+      'tip': 'Padoms',
+      'warning': 'Brīdinājums',
+      'contents': 'Saturs'}
+"""Mapping of node class name to label text."""
+
+bibliographic_fields = {
+      # language-dependent: fixed
+      'autors': 'author',
+      'autori': 'authors',
+      'organizācija': 'organization',
+      'adrese': 'address',
+      'kontakti': 'contact',
+      'versija': 'version',
+      'revīzija': 'revision',
+      'statuss': 'status',
+      'datums': 'date',
+      'copyright': 'copyright',
+      'veltījums': 'dedication',
+      'atreferējums': 'abstract'}
+"""English (lowcased) to canonical name mapping for bibliographic fields."""
+
+author_separators = [';', ',']
+"""List of separator strings for the 'Authors' bibliographic field. Tried in
+order."""

python/helpers/py3only/docutils/languages/nl.py

@@ -1,11 +1,11 @@
-# $Id: nl.py 4564 2006-05-21 20:44:42Z wiemann $
+# $Id: nl.py 9030 2022-03-05 23:28:32Z milde $
 # Author: Martijn Pieters <mjpieters@users.sourceforge.net>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Dutch-language mappings for language-dependent features of Docutils.

python/helpers/py3only/docutils/languages/pl.py

@@ -3,9 +3,9 @@
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Polish-language mappings for language-dependent features of Docutils.
@@ -28,15 +28,15 @@ labels = {
       'dedication': 'Dedykacja',
       'abstract': 'Streszczenie',
       'attention': 'Uwaga!',
-      'caution': 'Ostro\u017cnie!',
-      'danger': '!Niebezpiecze\u0144stwo!',
-      'error': 'B\u0142\u0105d',
-      'hint': 'Wskaz\u00f3wka',
-      'important': 'Wa\u017cne',
+      'caution': 'Ostrożnie!',
+      'danger': '!Niebezpieczeństwo!',
+      'error': 'Błąd',
+      'hint': 'Wskazówka',
+      'important': 'Ważne',
       'note': 'Przypis',
       'tip': 'Rada',
-      'warning': 'Ostrze\u017cenie',
-      'contents': 'Tre\u015b\u0107'}
+      'warning': 'Ostrzeżenie',
+      'contents': 'Treść'}
 """Mapping of node class name to label text."""
 
 bibliographic_fields = {
@@ -58,5 +58,3 @@ bibliographic_fields = {
 author_separators = [';', ',']
 """List of separator strings for the 'Authors' bibliographic field. Tried in
 order."""
-
- 	  	 

python/helpers/py3only/docutils/languages/pt_br.py

@@ -1,14 +1,14 @@
-# $Id: pt_br.py 5567 2008-06-03 01:11:03Z goodger $
+# $Id: pt_br.py 9452 2023-09-27 00:11:54Z milde $
 # Author: David Goodger <goodger@python.org>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
-Brazilian Portuguese-language mappings for language-dependent features of Docutils.
+Brazilian Portuguese-language mappings for language-dependent features.
 """
 
 __docformat__ = 'reStructuredText'
@@ -17,43 +17,43 @@ labels = {
       # fixed: language-dependent
       'author': 'Autor',
       'authors': 'Autores',
-      'organization': 'Organiza\u00E7\u00E3o',
-      'address': 'Endere\u00E7o',
+      'organization': 'Organização',
+      'address': 'Endereço',
       'contact': 'Contato',
-      'version': 'Vers\u00E3o',
-      'revision': 'Revis\u00E3o',
+      'version': 'Versão',
+      'revision': 'Revisão',
       'status': 'Estado',
       'date': 'Data',
       'copyright': 'Copyright',
-      'dedication': 'Dedicat\u00F3ria',
+      'dedication': 'Dedicatória',
       'abstract': 'Resumo',
-      'attention': 'Aten\u00E7\u00E3o!',
+      'attention': 'Atenção!',
       'caution': 'Cuidado!',
       'danger': 'PERIGO!',
       'error': 'Erro',
-      'hint': 'Sugest\u00E3o',
+      'hint': 'Sugestão',
       'important': 'Importante',
       'note': 'Nota',
       'tip': 'Dica',
       'warning': 'Aviso',
-      'contents': 'Sum\u00E1rio'}
+      'contents': 'Sumário'}
 """Mapping of node class name to label text."""
 
 bibliographic_fields = {
       # language-dependent: fixed
       'autor': 'author',
       'autores': 'authors',
-      'organiza\u00E7\u00E3o': 'organization',
-      'endere\u00E7o': 'address',
+      'organização': 'organization',
+      'endereço': 'address',
       'contato': 'contact',
-      'vers\u00E3o': 'version',
-      'revis\u00E3o': 'revision',
+      'versão': 'version',
+      'revisão': 'revision',
       'estado': 'status',
       'data': 'date',
       'copyright': 'copyright',
-      'dedicat\u00F3ria': 'dedication',
+      'dedicatória': 'dedication',
       'resumo': 'abstract'}
-"""Brazilian Portuguese (lowcased) to canonical name mapping for bibliographic fields."""
+"""Brazilian Portuguese (lowcased) name mapping for bibliographic fields."""
 
 author_separators = [';', ',']
 """List of separator strings for the 'Authors' bibliographic field. Tried in

python/helpers/py3only/docutils/languages/ru.py

@@ -1,12 +1,11 @@
-# -*- coding: utf-8 -*-
-# $Id: ru.py 7125 2011-09-16 18:36:18Z milde $
+# $Id: ru.py 9030 2022-03-05 23:28:32Z milde $
 # Author: Roman Suzi <rnd@onego.ru>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Russian-language mappings for language-dependent features of Docutils.
@@ -54,6 +53,6 @@ bibliographic_fields = {
       'версия': 'version'}
 """Russian (lowcased) to canonical name mapping for bibliographic fields."""
 
-author_separators =  [';', ',']
+author_separators = [';', ',']
 """List of separator strings for the 'Authors' bibliographic field. Tried in
 order."""

python/helpers/py3only/docutils/languages/sk.py

@@ -1,11 +1,11 @@
-# $Id: sk.py 4564 2006-05-21 20:44:42Z wiemann $
+# $Id: sk.py 9452 2023-09-27 00:11:54Z milde $
 # Author: Miroslav Vasko <zemiak@zoznam.sk>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Slovak-language mappings for language-dependent features of Docutils.
@@ -16,23 +16,23 @@ __docformat__ = 'reStructuredText'
 labels = {
       'author': 'Autor',
       'authors': 'Autori',
-      'organization': 'Organiz\u00E1cia',
+      'organization': 'Organizácia',
       'address': 'Adresa',
       'contact': 'Kontakt',
       'version': 'Verzia',
-      'revision': 'Rev\u00EDzia',
+      'revision': 'Revízia',
       'status': 'Stav',
-      'date': 'D\u00E1tum',
+      'date': 'Dátum',
       'copyright': 'Copyright',
       'dedication': 'Venovanie',
       'abstract': 'Abstraktne',
       'attention': 'Pozor!',
       'caution': 'Opatrne!',
-      'danger': '!NEBEZPE\u010cENSTVO!',
+      'danger': '!NEBEZPEČENSTVO!',
       'error': 'Chyba',
       'hint': 'Rada',
-      'important': 'D\u00F4le\u017Eit\u00E9',
-      'note': 'Pozn\u00E1mka',
+      'important': 'Dôležité',
+      'note': 'Poznámka',
       'tip': 'Tip',
       'warning': 'Varovanie',
       'contents': 'Obsah'}
@@ -41,13 +41,13 @@ labels = {
 bibliographic_fields = {
       'autor': 'author',
       'autori': 'authors',
-      'organiz\u00E1cia': 'organization',
+      'organizácia': 'organization',
       'adresa': 'address',
       'kontakt': 'contact',
       'verzia': 'version',
-      'rev\u00EDzia': 'revision',
+      'revízia': 'revision',
       'stav': 'status',
-      'd\u00E1tum': 'date',
+      'dátum': 'date',
       'copyright': 'copyright',
       'venovanie': 'dedication',
       'abstraktne': 'abstract'}

python/helpers/py3only/docutils/languages/sv.py

@@ -1,11 +1,11 @@
-# $Id: sv.py 4564 2006-05-21 20:44:42Z wiemann $
+# $Id: sv.py 9452 2023-09-27 00:11:54Z milde $
 # Author: Adam Chodorowski <chodorowski@users.sourceforge.net>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Swedish language mappings for language-dependent features of Docutils.
@@ -14,44 +14,44 @@ Swedish language mappings for language-dependent features of Docutils.
 __docformat__ = 'reStructuredText'
 
 labels = {
-    'author':       'F\u00f6rfattare',
-    'authors':      'F\u00f6rfattare',
+    'author': 'Författare',
+    'authors': 'Författare',
     'organization': 'Organisation',
-    'address':      'Adress',
-    'contact':      'Kontakt',
-    'version':      'Version',
-    'revision':     'Revision',
-    'status':       'Status',
-    'date':         'Datum',
-    'copyright':    'Copyright',
-    'dedication':   'Dedikation',
-    'abstract':     'Sammanfattning',
-    'attention':    'Observera!',
-    'caution':      'Varning!',
-    'danger':       'FARA!',
-    'error':        'Fel',
-    'hint':         'V\u00e4gledning',
-    'important':    'Viktigt',
-    'note':         'Notera',
-    'tip':          'Tips',
-    'warning':      'Varning',
-    'contents':     'Inneh\u00e5ll' }
+    'address': 'Adress',
+    'contact': 'Kontakt',
+    'version': 'Version',
+    'revision': 'Revision',
+    'status': 'Status',
+    'date': 'Datum',
+    'copyright': 'Copyright',
+    'dedication': 'Dedikation',
+    'abstract': 'Sammanfattning',
+    'attention': 'Observera!',
+    'caution': 'Akta!',  # 'Varning' already used for 'warning'
+    'danger': 'FARA!',
+    'error': 'Fel',
+    'hint': 'Vink',
+    'important': 'Viktigt',
+    'note': 'Notera',
+    'tip': 'Tips',
+    'warning': 'Varning',
+    'contents': 'Innehåll'}
 """Mapping of node class name to label text."""
 
 bibliographic_fields = {
     # 'Author' and 'Authors' identical in Swedish; assume the plural:
-    'f\u00f6rfattare': 'authors',
-    ' n/a':            'author',
-    'organisation':    'organization',
-    'adress':          'address',
-    'kontakt':         'contact',
-    'version':         'version',
-    'revision':        'revision',
-    'status':          'status',
-    'datum':           'date',
-    'copyright':       'copyright',
-    'dedikation':      'dedication', 
-    'sammanfattning':  'abstract' }
+    'författare': 'authors',
+    ' n/a': 'author',  # removing leads to (spurious) test failure
+    'organisation': 'organization',
+    'adress': 'address',
+    'kontakt': 'contact',
+    'version': 'version',
+    'revision': 'revision',
+    'status': 'status',
+    'datum': 'date',
+    'copyright': 'copyright',
+    'dedikation': 'dedication',
+    'sammanfattning': 'abstract'}
 """Swedish (lowcased) to canonical name mapping for bibliographic fields."""
 
 author_separators = [';', ',']

python/helpers/py3only/docutils/languages/uk.py

@@ -0,0 +1,58 @@
+# $Id: uk.py 9114 2022-07-28 17:06:10Z milde $
+# Author: Dmytro Kazanzhy <dkazanzhy@gmail.com>
+# Copyright: This module has been placed in the public domain.
+
+# New language mappings are welcome.  Before doing a new translation, please
+# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
+# translated for each language: one in docutils/languages, the other in
+# docutils/parsers/rst/languages.
+
+"""
+Ukrainian-language mappings for language-dependent features of Docutils.
+"""
+
+__docformat__ = 'reStructuredText'
+
+labels = {
+      'abstract': 'Анотація',
+      'address': 'Адреса',
+      'attention': 'Увага!',
+      'author': 'Автор',
+      'authors': 'Автори',
+      'caution': 'Обережно!',
+      'contact': 'Контакт',
+      'contents': 'Зміст',
+      'copyright': 'Права копіювання',
+      'danger': 'НЕБЕЗПЕЧНО!',
+      'date': 'Дата',
+      'dedication': 'Посвячення',
+      'error': 'Помилка',
+      'hint': 'Порада',
+      'important': 'Важливо',
+      'note': 'Примітка',
+      'organization': 'Організація',
+      'revision': 'Редакція',
+      'status': 'Статус',
+      'tip': 'Підказка',
+      'version': 'Версія',
+      'warning': 'Попередження'}
+"""Mapping of node class name to label text."""
+
+bibliographic_fields = {
+      'анотація': 'abstract',
+      'адреса': 'address',
+      'автор': 'author',
+      'автори': 'authors',
+      'контакт': 'contact',
+      'права копіювання': 'copyright',
+      'дата': 'date',
+      'посвячення': 'dedication',
+      'організація': 'organization',
+      'редакція': 'revision',
+      'статус': 'status',
+      'версія': 'version'}
+"""Ukrainian (lowcased) to canonical name mapping for bibliographic fields."""
+
+author_separators = [';', ',']
+"""List of separator strings for the 'Authors' bibliographic field. Tried in
+order."""

python/helpers/py3only/docutils/languages/zh_cn.py

@@ -1,12 +1,11 @@
-# -*- coding: utf-8 -*-
-# $Id: zh_cn.py 4564 2006-05-21 20:44:42Z wiemann $
+# $Id: zh_cn.py 9452 2023-09-27 00:11:54Z milde $
 # Author: Pan Junyong <panjy@zopechina.com>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Simplified Chinese language mappings for language-dependent features
@@ -39,7 +38,7 @@ labels = {
       'tip': '技巧',
       'warning': '警告',
       'contents': '目录',
-} 
+}
 """Mapping of node class name to label text."""
 
 bibliographic_fields = {
@@ -58,10 +57,6 @@ bibliographic_fields = {
       '摘要': 'abstract'}
 """Simplified Chinese to canonical name mapping for bibliographic fields."""
 
-author_separators = [';', ',',
-                     '\uff1b', # '；'
-                     '\uff0c', # '，'
-                     '\u3001', # '、'
-                    ]
+author_separators = [';', ',', '；', '，', '、']
 """List of separator strings for the 'Authors' bibliographic field. Tried in
 order."""

python/helpers/py3only/docutils/languages/zh_tw.py

@@ -1,44 +1,43 @@
-# -*- coding: utf-8 -*-
-# $Id: zh_tw.py 4564 2006-05-21 20:44:42Z wiemann $
+# $Id: zh_tw.py 9452 2023-09-27 00:11:54Z milde $
 # Author: Joe YS Jaw <joeysj@users.sourceforge.net>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
-Traditional Chinese language mappings for language-dependent features of Docutils.
+Traditional Chinese language mappings for language-dependent features.
 """
 
 __docformat__ = 'reStructuredText'
 
 labels = {
-      # fixed: language-dependent
-      'author': '\u4f5c\u8005', # '作者' <-- Chinese word
-      'authors': '\u4f5c\u8005\u7fa4', # '作者群',
-      'organization': '\u7d44\u7e54', # '組織',
-      'address': '\u5730\u5740', # '地址',
-      'contact': '\u9023\u7d61', # '連絡',
-      'version': '\u7248\u672c', # '版本',
-      'revision': '\u4fee\u8a02', # '修訂',
-      'status': '\u72c0\u614b', # '狀態',
-      'date': '\u65e5\u671f', # '日期',
-      'copyright': '\u7248\u6b0a', # '版權',
-      'dedication': '\u984c\u737b', # '題獻',
-      'abstract': '\u6458\u8981', # '摘要',
-      'attention': '\u6ce8\u610f\uff01', # '注意！',
-      'caution': '\u5c0f\u5fc3\uff01', # '小心！',
-      'danger': '\uff01\u5371\u96aa\uff01', # '！危險！',
-      'error': '\u932f\u8aa4', # '錯誤',
-      'hint': '\u63d0\u793a', # '提示',
-      'important': '\u91cd\u8981', # '注意！',
-      'note': '\u8a3b\u91cb', # '註釋',
-      'tip': '\u79d8\u8a23', # '秘訣',
-      'warning': '\u8b66\u544a', # '警告',
-      'contents': '\u76ee\u9304' # '目錄'
-} 
+    # fixed: language-dependent
+    'author': '作者',
+    'authors': '作者群',
+    'organization': '組織',
+    'address': '地址',
+    'contact': '連絡',
+    'version': '版本',
+    'revision': '修訂',
+    'status': '狀態',
+    'date': '日期',
+    'copyright': '版權',
+    'dedication': '題獻',
+    'abstract': '摘要',
+    'attention': '注意！',
+    'caution': '小心！',
+    'danger': '！危險！',
+    'error': '錯誤',
+    'hint': '提示',
+    'important': '重要',
+    'note': '註釋',
+    'tip': '秘訣',
+    'warning': '警告',
+    'contents': '目錄',
+    }
 """Mapping of node class name to label text."""
 
 bibliographic_fields = {
@@ -57,10 +56,6 @@ bibliographic_fields = {
       'abstract (translation required)': 'abstract'}
 """Traditional Chinese to canonical name mapping for bibliographic fields."""
 
-author_separators = [';', ',',
-                     '\uff1b', # '；'
-                     '\uff0c', # '，'
-                     '\u3001', # '、'
-                    ]
+author_separators = [';', ',', '；', '，', '、']
 """List of separator strings for the 'Authors' bibliographic field. Tried in
 order."""

python/helpers/py3only/docutils/parsers/__init__.py

@@ -1,4 +1,4 @@
-# $Id: __init__.py 7646 2013-04-17 14:17:37Z milde $
+# $Id: __init__.py 9048 2022-03-29 21:50:15Z milde $
 # Author: David Goodger <goodger@python.org>
 # Copyright: This module has been placed in the public domain.
 
@@ -8,16 +8,39 @@ This package contains Docutils parser modules.
 
 __docformat__ = 'reStructuredText'
 
-import sys
+from importlib import import_module
 
-from docutils import Component
-
-if sys.version_info < (2,5):
-    from docutils._compat import __import__
+from docutils import Component, frontend
 
 
 class Parser(Component):
-
+    settings_spec = (
+        'Generic Parser Options',
+        None,
+        (('Disable directives that insert the contents of an external file; '
+          'replaced with a "warning" system message.',
+          ['--no-file-insertion'],
+          {'action': 'store_false', 'default': 1,
+           'dest': 'file_insertion_enabled',
+           'validator': frontend.validate_boolean}),
+         ('Enable directives that insert the contents '
+          'of an external file. (default)',
+          ['--file-insertion-enabled'],
+          {'action': 'store_true'}),
+         ('Disable the "raw" directive; '
+          'replaced with a "warning" system message.',
+          ['--no-raw'],
+          {'action': 'store_false', 'default': 1, 'dest': 'raw_enabled',
+           'validator': frontend.validate_boolean}),
+         ('Enable the "raw" directive. (default)',
+          ['--raw-enabled'],
+          {'action': 'store_true'}),
+         ('Maximal number of characters in an input line. Default 10 000.',
+          ['--line-length-limit'],
+          {'metavar': '<length>', 'type': 'int', 'default': 10000,
+           'validator': frontend.validate_nonnegative_int}),
+         )
+        )
     component_type = 'parser'
     config_section = 'parsers'
 
@@ -28,6 +51,10 @@ class Parser(Component):
     def setup_parse(self, inputstring, document):
         """Initial parse setup.  Call at start of `self.parse()`."""
         self.inputstring = inputstring
+        # provide fallbacks in case the document has only generic settings
+        document.settings.setdefault('file_insertion_enabled', False)
+        document.settings.setdefault('raw_enabled', False)
+        document.settings.setdefault('line_length_limit', 10000)
         self.document = document
         document.reporter.attach_observer(document.note_parse_message)
 
@@ -37,19 +64,29 @@ class Parser(Component):
             self.document.note_parse_message)
 
 
-_parser_aliases = {
-      'restructuredtext': 'rst',
-      'rest': 'rst',
-      'restx': 'rst',
-      'rtxt': 'rst',}
+_parser_aliases = {  # short names for known parsers
+                   'null': 'docutils.parsers.null',
+                   # reStructuredText
+                   'rst': 'docutils.parsers.rst',
+                   'restructuredtext': 'docutils.parsers.rst',
+                   'rest': 'docutils.parsers.rst',
+                   'restx': 'docutils.parsers.rst',
+                   'rtxt': 'docutils.parsers.rst',
+                   # 3rd-party Markdown parsers
+                   'recommonmark': 'docutils.parsers.recommonmark_wrapper',
+                   'myst': 'myst_parser.docutils_',
+                   # 'pycmark': works out of the box
+                   # dispatcher for 3rd-party Markdown parsers
+                   'commonmark': 'docutils.parsers.commonmark_wrapper',
+                   'markdown': 'docutils.parsers.commonmark_wrapper',
+                  }
+
 
 def get_parser_class(parser_name):
     """Return the Parser class from the `parser_name` module."""
-    parser_name = parser_name.lower()
-    if parser_name in _parser_aliases:
-        parser_name = _parser_aliases[parser_name]
+    name = parser_name.lower()
     try:
-        module = __import__(parser_name, globals(), locals(), level=1)
-    except ImportError:
-        module = __import__(parser_name, globals(), locals(), level=0)
+        module = import_module(_parser_aliases.get(name, name))
+    except ImportError as err:
+        raise ImportError(f'Parser "{parser_name}" not found. {err}')
     return module.Parser

python/helpers/py3only/docutils/parsers/commonmark_wrapper.py

@@ -0,0 +1,56 @@
+#! /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: 9561 $
+# Date: $Date: 2024-03-14 17:34:48 +0100 (Do, 14. Mär 2024) $
+"""
+An interface for parsing CommonMark input.
+
+Select a locally installed parser from the following 3rd-party
+parser packages:
+
+:pycmark:       https://pypi.org/project/pycmark/
+:myst:          https://pypi.org/project/myst-docutils/
+:recommonmark:  https://pypi.org/project/recommonmark/ (deprecated)
+
+The first parser class that can be successfully imported is mapped to
+`commonmark_wrapper.Parser`.
+
+This module is provisional:
+the API is not settled and may change with any minor Docutils version.
+"""
+
+import docutils.parsers
+
+
+commonmark_parser_names = ('pycmark', 'myst', 'recommonmark')
+"""Names of compatible drop-in CommonMark parsers"""
+
+Parser = None
+parser_name = ''
+
+for name in commonmark_parser_names:
+    try:
+        Parser = docutils.parsers.get_parser_class(name)
+    except ImportError:
+        continue
+    parser_name = name
+    break
+
+if Parser is None:
+    raise ImportError(
+              'Parsing "CommonMark" requires one of the packages\n'
+              f'{commonmark_parser_names} available at https://pypi.org')
+
+if parser_name == 'myst':
+    if not Parser.settings_defaults:
+        Parser.settings_defaults = {}
+    Parser.settings_defaults['myst_commonmark_only'] = True

python/helpers/py3only/docutils/parsers/recommonmark_wrapper.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+# :Copyright: © 2020 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: 9302 $
+# Date: $Date: 2022-12-02 18:14:05 +0100 (Fr, 02. Dez 2022) $
+"""
+A parser for CommonMark Markdown text using `recommonmark`__.
+
+__ https://pypi.org/project/recommonmark/
+
+.. important:: This module is provisional
+
+   * The "recommonmark" package is unmaintained and deprecated.
+     This wrapper module will be removed in a future Docutils version.
+
+   * The API is not settled and may change with any minor Docutils version.
+"""
+
+from docutils import Component
+from docutils import nodes
+
+try:
+    # If possible, import Sphinx's 'addnodes'
+    from sphinx import addnodes
+except ImportError:
+    # stub to prevent errors if Sphinx isn't installed
+    import sys
+    import types
+
+    class pending_xref(nodes.Inline, nodes.Element): ... # NoQA
+
+    sys.modules['sphinx'] = sphinx = types.ModuleType('sphinx')
+    sphinx.addnodes = addnodes = types.SimpleNamespace()
+    addnodes.pending_xref = pending_xref
+try:
+    import recommonmark
+    from recommonmark.parser import CommonMarkParser
+except ImportError as err:
+    raise ImportError(
+        'Parsing "recommonmark" Markdown flavour requires the\n'
+        '  package https://pypi.org/project/recommonmark.'
+    ) from err
+else:
+    if recommonmark.__version__ < '0.6.0':
+        raise ImportError('The installed version of "recommonmark" is too old.'
+                          ' Update with "pip install -U recommonmark".')
+
+
+# auxiliary function for `document.findall()`
+def is_literal(node):
+    return isinstance(node, (nodes.literal, nodes.literal_block))
+
+
+class Parser(CommonMarkParser):
+    """MarkDown parser based on recommonmark.
+
+    This parser is provisional:
+    the API is not settled and may change with any minor Docutils version.
+    """
+    supported = ('recommonmark', 'commonmark', 'markdown', 'md')
+    """Formats this parser supports."""
+
+    config_section = 'recommonmark parser'
+    config_section_dependencies = ('parsers',)
+
+    def get_transforms(self):
+        return Component.get_transforms(self)  # + [AutoStructify]
+
+    def parse(self, inputstring, document):
+        """Use the upstream parser and clean up afterwards.
+        """
+        # check for exorbitantly long lines
+        for i, line in enumerate(inputstring.split('\n')):
+            if len(line) > document.settings.line_length_limit:
+                error = document.reporter.error(
+                    'Line %d exceeds the line-length-limit.'%(i+1))
+                document.append(error)
+                return
+
+        # pass to upstream parser
+        try:
+            CommonMarkParser.parse(self, inputstring, document)
+        except Exception as err:
+            if document.settings.traceback:
+                raise err
+            error = document.reporter.error('Parsing with "recommonmark" '
+                                            'returned the error:\n%s'%err)
+            document.append(error)
+
+        # Post-Processing
+        # ---------------
+
+        # merge adjoining Text nodes:
+        for node in document.findall(nodes.TextElement):
+            children = node.children
+            i = 0
+            while i+1 < len(children):
+                if (isinstance(children[i], nodes.Text)
+                    and isinstance(children[i+1], nodes.Text)):
+                    children[i] = nodes.Text(children[i]+children.pop(i+1))
+                    children[i].parent = node
+                else:
+                    i += 1
+
+        # add "code" class argument to literal elements (inline and block)
+        for node in document.findall(is_literal):
+            if 'code' not in node['classes']:
+                node['classes'].append('code')
+        # move "language" argument to classes
+        for node in document.findall(nodes.literal_block):
+            if 'language' in node.attributes:
+                node['classes'].append(node['language'])
+                del node['language']
+
+        # replace raw nodes if raw is not allowed
+        if not document.settings.raw_enabled:
+            for node in document.findall(nodes.raw):
+                warning = document.reporter.warning('Raw content disabled.')
+                node.parent.replace(node, warning)
+
+        # drop pending_xref (Sphinx cross reference extension)
+        for node in document.findall(addnodes.pending_xref):
+            reference = node.children[0]
+            if 'name' not in reference:
+                reference['name'] = nodes.fully_normalize_name(
+                                                    reference.astext())
+            node.parent.replace(node, reference)
+
+    def visit_document(self, node):
+        """Dummy function to prevent spurious warnings.
+
+        cf. https://github.com/readthedocs/recommonmark/issues/177
+        """
+        pass
+
+    # Overwrite parent method with version that
+    # doesn't pass deprecated `rawsource` argument to nodes.Text:
+    def visit_text(self, mdnode):
+        self.current_node.append(nodes.Text(mdnode.literal))

python/helpers/py3only/docutils/parsers/rst/__init__.py

@@ -1,4 +1,4 @@
-# $Id: __init__.py 7598 2013-01-30 12:39:24Z milde $
+# $Id: __init__.py 9258 2022-11-21 14:51:43Z milde $
 # Author: David Goodger <goodger@python.org>
 # Copyright: This module has been placed in the public domain.
 
@@ -69,10 +69,11 @@ appropriate).
 
 __docformat__ = 'reStructuredText'
 
+
 import docutils.parsers
 import docutils.statemachine
-from docutils import frontend, nodes, Component
-from docutils.parsers.rst import states
+from docutils.parsers.rst import roles, states
+from docutils import frontend, nodes
 from docutils.transforms import universal
 
 
@@ -80,19 +81,19 @@ class Parser(docutils.parsers.Parser):
 
     """The reStructuredText parser."""
 
-    supported = ('restructuredtext', 'rst', 'rest', 'restx', 'rtxt', 'rstx')
+    supported = ('rst', 'restructuredtext', 'rest', 'restx', 'rtxt', 'rstx')
     """Aliases this parser supports."""
 
-    settings_spec = (
+    settings_spec = docutils.parsers.Parser.settings_spec + (
         'reStructuredText Parser Options',
         None,
         (('Recognize and link to standalone PEP references (like "PEP 258").',
           ['--pep-references'],
           {'action': 'store_true', 'validator': frontend.validate_boolean}),
          ('Base URL for PEP references '
-          '(default "http://www.python.org/dev/peps/").',
+          '(default "https://peps.python.org/").',
           ['--pep-base-url'],
-          {'metavar': '<URL>', 'default': 'http://www.python.org/dev/peps/',
+          {'metavar': '<URL>', 'default': 'https://peps.python.org/',
            'validator': frontend.validate_url_trailing_slash}),
          ('Template for PEP file part of URL. (default "pep-%04d")',
           ['--pep-file-url-template'],
@@ -100,9 +101,10 @@ class Parser(docutils.parsers.Parser):
          ('Recognize and link to standalone RFC references (like "RFC 822").',
           ['--rfc-references'],
           {'action': 'store_true', 'validator': frontend.validate_boolean}),
-         ('Base URL for RFC references (default "http://www.faqs.org/rfcs/").',
+         ('Base URL for RFC references '
+          '(default "https://tools.ietf.org/html/").',
           ['--rfc-base-url'],
-          {'metavar': '<URL>', 'default': 'http://www.faqs.org/rfcs/',
+          {'metavar': '<URL>', 'default': 'https://tools.ietf.org/html/',
            'validator': frontend.validate_url_trailing_slash}),
          ('Set number of spaces for tab expansion (default 8).',
           ['--tab-width'],
@@ -114,34 +116,36 @@ class Parser(docutils.parsers.Parser):
          ('Leave spaces before footnote references.',
           ['--leave-footnote-reference-space'],
           {'action': 'store_false', 'dest': 'trim_footnote_reference_space'}),
-         ('Disable directives that insert the contents of external file '
-          '("include" & "raw"); replaced with a "warning" system message.',
-          ['--no-file-insertion'],
-          {'action': 'store_false', 'default': 1,
-           'dest': 'file_insertion_enabled',
-           'validator': frontend.validate_boolean}),
-         ('Enable directives that insert the contents of external file '
-          '("include" & "raw").  Enabled by default.',
-          ['--file-insertion-enabled'],
-          {'action': 'store_true'}),
-         ('Disable the "raw" directives; replaced with a "warning" '
-          'system message.',
-          ['--no-raw'],
-          {'action': 'store_false', 'default': 1, 'dest': 'raw_enabled',
-           'validator': frontend.validate_boolean}),
-         ('Enable the "raw" directive.  Enabled by default.',
-          ['--raw-enabled'],
-          {'action': 'store_true'}),
          ('Token name set for parsing code with Pygments: one of '
-          '"long", "short", or "none (no parsing)". Default is "long".',
+          '"long", "short", or "none" (no parsing). Default is "long".',
           ['--syntax-highlight'],
           {'choices': ['long', 'short', 'none'],
            'default': 'long', 'metavar': '<format>'}),
          ('Change straight quotation marks to typographic form: '
           'one of "yes", "no", "alt[ernative]" (default "no").',
           ['--smart-quotes'],
-          {'default': False, 'validator': frontend.validate_ternary}),
-        ))
+          {'default': False, 'metavar': '<yes/no/alt>',
+           'validator': frontend.validate_ternary}),
+         ('Characters to use as "smart quotes" for <language>. ',
+          ['--smartquotes-locales'],
+          {'metavar': '<language:quotes[,language:quotes,...]>',
+           'action': 'append',
+           'validator': frontend.validate_smartquotes_locales}),
+         ('Inline markup recognized at word boundaries only '
+          '(adjacent to punctuation or whitespace). '
+          'Force character-level inline markup recognition with '
+          '"\\ " (backslash + space). Default.',
+          ['--word-level-inline-markup'],
+          {'action': 'store_false', 'dest': '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.',
+          ['--character-level-inline-markup'],
+          {'action': 'store_true', 'default': False,
+           'dest': 'character_level_inline_markup'}),
+         )
+        )
 
     config_section = 'restructuredtext parser'
     config_section_dependencies = ('parsers',)
@@ -155,12 +159,14 @@ class Parser(docutils.parsers.Parser):
         self.inliner = inliner
 
     def get_transforms(self):
-        return Component.get_transforms(self) + [
-            universal.SmartQuotes]
+        return super().get_transforms() + [universal.SmartQuotes]
 
     def parse(self, inputstring, document):
         """Parse `inputstring` and populate `document`, a document tree."""
         self.setup_parse(inputstring, document)
+        # provide fallbacks in case the document has only generic settings
+        self.document.settings.setdefault('tab_width', 8)
+        self.document.settings.setdefault('syntax_highlight', 'long')
         self.statemachine = states.RSTStateMachine(
               state_classes=self.state_classes,
               initial_state=self.initial_state,
@@ -168,7 +174,17 @@ class Parser(docutils.parsers.Parser):
         inputlines = docutils.statemachine.string2lines(
               inputstring, tab_width=document.settings.tab_width,
               convert_whitespace=True)
-        self.statemachine.run(inputlines, document, inliner=self.inliner)
+        for i, line in enumerate(inputlines):
+            if len(line) > self.document.settings.line_length_limit:
+                error = self.document.reporter.error(
+                            'Line %d exceeds the line-length-limit.'%(i+1))
+                self.document.append(error)
+                break
+        else:
+            self.statemachine.run(inputlines, document, inliner=self.inliner)
+        # restore the "default" default role after parsing a document
+        if '' in roles._roles:
+            del roles._roles['']
         self.finish_parse()
 
 
@@ -190,7 +206,7 @@ class DirectiveError(Exception):
         self.msg = message
 
 
-class Directive(object):
+class Directive:
 
     """
     Base class for reStructuredText directives.
@@ -248,21 +264,18 @@ class Directive(object):
     - ``lineno`` is the absolute line number of the first line
       of the directive.
 
-    - ``src`` is the name (or path) of the rst source of the directive.
-
-    - ``srcline`` is the line number of the first line of the directive
-      in its source. It may differ from ``lineno``, if the main source
-      includes other sources with the ``.. include::`` directive.
-
-    - ``content_offset`` is the line offset of the first line of the content from
-      the beginning of the current input.  Used when initiating a nested parse.
+    - ``content_offset`` is the line offset of the first line
+      of the content from the beginning of the current input.
+      Used when initiating a nested parse.
 
     - ``block_text`` is a string containing the entire directive.
 
     - ``state`` is the state which called the directive function.
 
-    - ``state_machine`` is the state machine which controls the state which called
-      the directive function.
+    - ``state_machine`` is the state machine which controls the state
+      which called the directive function.
+
+    - ``reporter`` is the state machine's `reporter` instance.
 
     Directive functions return a list of nodes which will be inserted
     into the document tree at the point where the directive was
@@ -277,7 +290,7 @@ class Directive(object):
     substitution definition context, typically using code like this::
 
         if not isinstance(state, states.SubstitutionDef):
-            error = state_machine.reporter.error(
+            error = self.reporter.error(
                 'Invalid context: the "%s" directive can only be used '
                 'within a substitution definition.' % (name),
                 nodes.literal_block(block_text, block_text), line=lineno)
@@ -285,7 +298,7 @@ class Directive(object):
     """
 
     # There is a "Creating reStructuredText Directives" how-to at
-    # <http://docutils.sf.net/docs/howto/rst-directives.html>.  If you
+    # <https://docutils.sourceforge.io/docs/howto/rst-directives.html>.  If you
     # update this docstring, please update the how-to as well.
 
     required_arguments = 0
@@ -314,9 +327,10 @@ class Directive(object):
         self.block_text = block_text
         self.state = state
         self.state_machine = state_machine
+        self.reporter = state_machine.reporter
 
     def run(self):
-        raise NotImplementedError('Must override run() is subclass.')
+        raise NotImplementedError('Must override run() in subclass.')
 
     # Directive errors:
 
@@ -369,7 +383,7 @@ class Directive(object):
         if 'name' in self.options:
             name = nodes.fully_normalize_name(self.options.pop('name'))
             if 'name' in node:
-                del(node['name'])
+                del node['name']
             node['names'].append(name)
             self.state.document.note_explicit_target(node, node)
 

python/helpers/py3only/docutils/parsers/rst/directives/__init__.py

@@ -1,4 +1,4 @@
-# $Id: __init__.py 7621 2013-03-04 13:20:49Z milde $
+# $Id: __init__.py 9426 2023-07-03 12:38:54Z milde $
 # Author: David Goodger <goodger@python.org>
 # Copyright: This module has been placed in the public domain.
 
@@ -8,16 +8,14 @@ This package contains directive implementation modules.
 
 __docformat__ = 'reStructuredText'
 
-import codecs
 import re
-import sys
+import codecs
+from importlib import import_module
 
-from docutils import nodes
+from docutils import nodes, parsers
+from docutils.utils import split_escaped_whitespace, escape2null
 from docutils.parsers.rst.languages import en as _fallback_language_module
 
-if sys.version_info < (2,5):
-    from docutils._compat import __import__
-
 
 _directive_registry = {
       'attention': ('admonitions', 'Attention'),
@@ -42,7 +40,7 @@ _directive_registry = {
       'pull-quote': ('body', 'PullQuote'),
       'compound': ('body', 'Compound'),
       'container': ('body', 'Container'),
-      #'questions': ('body', 'question_list'),
+      # 'questions': ('body', 'question_list'),
       'table': ('tables', 'RSTTable'),
       'csv-table': ('tables', 'CSVTable'),
       'list-table': ('tables', 'ListTable'),
@@ -52,11 +50,11 @@ _directive_registry = {
       'sectnum': ('parts', 'Sectnum'),
       'header': ('parts', 'Header'),
       'footer': ('parts', 'Footer'),
-      #'footnotes': ('parts', 'footnotes'),
-      #'citations': ('parts', 'citations'),
+      # 'footnotes': ('parts', 'footnotes'),
+      # 'citations': ('parts', 'citations'),
       'target-notes': ('references', 'TargetNotes'),
-      'meta': ('html', 'Meta'),
-      #'imagemap': ('html', 'imagemap'),
+      'meta': ('misc', 'Meta'),
+      # 'imagemap': ('html', 'imagemap'),
       'raw': ('misc', 'Raw'),
       'include': ('misc', 'Include'),
       'replace': ('misc', 'Replace'),
@@ -66,7 +64,8 @@ _directive_registry = {
       'default-role': ('misc', 'DefaultRole'),
       'title': ('misc', 'Title'),
       'date': ('misc', 'Date'),
-      'restructuredtext-test-directive': ('misc', 'TestDirective'),}
+      'restructuredtext-test-directive': ('misc', 'TestDirective'),
+      }
 """Mapping of directive name to (module name, class name).  The
 directive name is canonical & must be lowercase.  Language-dependent
 names are defined in the ``language`` subpackage."""
@@ -74,6 +73,7 @@ names are defined in the ``language`` subpackage."""
 _directives = {}
 """Cache of imported directives."""
 
+
 def directive(directive_name, language_module, document):
     """
     Locate and return a directive function from its language-dependent name.
@@ -114,7 +114,7 @@ def directive(directive_name, language_module, document):
         # Error handling done by caller.
         return None, messages
     try:
-        module = __import__(modulename, globals(), locals(), level=1)
+        module = import_module('docutils.parsers.rst.directives.'+modulename)
     except ImportError as detail:
         messages.append(document.reporter.error(
             'Error importing directive module "%s" (directive "%s"):\n%s'
@@ -132,6 +132,7 @@ def directive(directive_name, language_module, document):
         return None, messages
     return directive, messages
 
+
 def register_directive(name, directive):
     """
     Register a nonstandard application-defined directive function.
@@ -139,6 +140,13 @@ def register_directive(name, directive):
     """
     _directives[name] = directive
 
+
+# conversion functions for `Directive.option_spec`
+# ------------------------------------------------
+#
+# see also `parsers.rst.Directive` in ../__init__.py.
+
+
 def flag(argument):
     """
     Check for a valid flag option (no argument) and return ``None``.
@@ -151,6 +159,7 @@ def flag(argument):
     else:
         return None
 
+
 def unchanged_required(argument):
     """
     Return the argument text, unchanged.
@@ -163,6 +172,7 @@ def unchanged_required(argument):
     else:
         return argument  # unchanged!
 
+
 def unchanged(argument):
     """
     Return the argument text, unchanged.
@@ -175,6 +185,7 @@ def unchanged(argument):
     else:
         return argument  # unchanged!
 
+
 def path(argument):
     """
     Return the path argument unwrapped (with newlines removed).
@@ -185,12 +196,12 @@ def path(argument):
     if argument is None:
         raise ValueError('argument required but none supplied')
     else:
-        path = ''.join([s.strip() for s in argument.splitlines()])
-        return path
+        return ''.join(s.strip() for s in argument.splitlines())
+
 
 def uri(argument):
     """
-    Return the URI argument with whitespace removed.
+    Return the URI argument with unescaped whitespace removed.
     (Directive option conversion function.)
 
     Raise ``ValueError`` if no argument is found.
@@ -198,8 +209,10 @@ def uri(argument):
     if argument is None:
         raise ValueError('argument required but none supplied')
     else:
-        uri = ''.join(argument.split())
-        return uri
+        parts = split_escaped_whitespace(escape2null(argument))
+        return ' '.join(''.join(nodes.unescape(part).split())
+                        for part in parts)
+
 
 def nonnegative_int(argument):
     """
@@ -211,9 +224,11 @@ def nonnegative_int(argument):
         raise ValueError('negative value; must be positive or zero')
     return value
 
+
 def percentage(argument):
     """
     Check for an integer percentage value with optional percent sign.
+    (Directive option conversion function.)
     """
     try:
         argument = argument.rstrip(' %')
@@ -221,13 +236,16 @@ def percentage(argument):
         pass
     return nonnegative_int(argument)
 
+
 length_units = ['em', 'ex', 'px', 'in', 'cm', 'mm', 'pt', 'pc']
 
+
 def get_measure(argument, units):
     """
     Check for a positive argument of one of the units and return a
     normalized string of the form "<value><unit>" (without space in
     between).
+    (Directive option conversion function.)
 
     To be called from directive option conversion functions.
     """
@@ -237,15 +255,18 @@ def get_measure(argument, units):
     except (AttributeError, ValueError):
         raise ValueError(
             'not a positive measure of one of the following units:\n%s'
-            % ' '.join(['"%s"' % i for i in units]))
+            % ' '.join('"%s"' % i for i in units))
     return match.group(1) + match.group(2)
 
+
 def length_or_unitless(argument):
     return get_measure(argument, length_units + [''])
 
+
 def length_or_percentage_or_unitless(argument, default=''):
     """
     Return normalized string of a length or percentage unit.
+    (Directive option conversion function.)
 
     Add <default> if there is no unit. Raise ValueError if the argument is not
     a positive measure of one of the valid CSS units (or without unit).
@@ -268,6 +289,7 @@ def length_or_percentage_or_unitless(argument, default=''):
             # raise ValueError with list of valid units:
             return get_measure(argument, length_units + ['%'])
 
+
 def class_option(argument):
     """
     Convert the argument into a list of ID-compatible strings and return it.
@@ -286,9 +308,11 @@ def class_option(argument):
         class_names.append(class_name)
     return class_names
 
+
 unicode_pattern = re.compile(
     r'(?:0x|x|\\x|U\+?|\\u)([0-9a-f]+)$|&#x([0-9a-f]+);$', re.IGNORECASE)
 
+
 def unicode_code(code):
     r"""
     Convert a Unicode character code to a Unicode character.
@@ -313,9 +337,10 @@ def unicode_code(code):
     except OverflowError as detail:
         raise ValueError('code too large (%s)' % detail)
 
+
 def single_char_or_unicode(argument):
     """
-    A single character is returned as-is.  Unicode characters codes are
+    A single character is returned as-is.  Unicode character codes are
     converted as in `unicode_code`.  (Directive option conversion function.)
     """
     char = unicode_code(argument)
@@ -324,6 +349,7 @@ def single_char_or_unicode(argument):
                          'a Unicode code' % char)
     return char
 
+
 def single_char_or_whitespace_or_unicode(argument):
     """
     As with `single_char_or_unicode`, but "tab" and "space" are also supported.
@@ -337,6 +363,7 @@ def single_char_or_whitespace_or_unicode(argument):
         char = single_char_or_unicode(argument)
     return char
 
+
 def positive_int(argument):
     """
     Converts the argument into an integer.  Raises ValueError for negative,
@@ -347,6 +374,7 @@ def positive_int(argument):
         raise ValueError('negative or zero value; must be positive')
     return value
 
+
 def positive_int_list(argument):
     """
     Converts a space- or comma-separated list of values into a Python list
@@ -361,9 +389,10 @@ def positive_int_list(argument):
         entries = argument.split()
     return [positive_int(entry) for entry in entries]
 
+
 def encoding(argument):
     """
-    Verfies the encoding argument by lookup.
+    Verifies the encoding argument by lookup.
     (Directive option conversion function.)
 
     Raises ValueError for unknown encodings.
@@ -374,6 +403,7 @@ def encoding(argument):
         raise ValueError('unknown encoding: "%s"' % argument)
     return argument
 
+
 def choice(argument, values):
     """
     Directive option utility function, supplied to enable options whose
@@ -400,6 +430,37 @@ def choice(argument, values):
         raise ValueError('"%s" unknown; choose from %s'
                          % (argument, format_values(values)))
 
+
 def format_values(values):
-    return '%s, or "%s"' % (', '.join(['"%s"' % s for s in values[:-1]]),
+    return '%s, or "%s"' % (', '.join('"%s"' % s for s in values[:-1]),
                             values[-1])
+
+
+def value_or(values, other):
+    """
+    Directive option conversion function.
+
+    The argument can be any of `values` or `argument_type`.
+    """
+    def auto_or_other(argument):
+        if argument in values:
+            return argument
+        else:
+            return other(argument)
+    return auto_or_other
+
+
+def parser_name(argument):
+    """
+    Return a docutils parser whose name matches the argument.
+    (Directive option conversion function.)
+
+    Return `None`, if the argument evaluates to `False`.
+    Raise `ValueError` if importing the parser module fails.
+    """
+    if not argument:
+        return None
+    try:
+        return parsers.get_parser_class(argument)
+    except ImportError as err:
+        raise ValueError(str(err))

python/helpers/py3only/docutils/parsers/rst/directives/admonitions.py

@@ -1,4 +1,4 @@
-# $Id: admonitions.py 7681 2013-07-12 07:52:27Z milde $
+# $Id: admonitions.py 9475 2023-11-13 22:30:00Z milde $
 # Author: David Goodger <goodger@python.org>
 # Copyright: This module has been placed in the public domain.
 
@@ -8,10 +8,11 @@ Admonition directives.
 
 __docformat__ = 'reStructuredText'
 
-from docutils import nodes
+
 from docutils.parsers.rst import Directive
 from docutils.parsers.rst import directives
 from docutils.parsers.rst.roles import set_classes
+from docutils import nodes
 
 
 class BaseAdmonition(Directive):
@@ -30,6 +31,8 @@ class BaseAdmonition(Directive):
         text = '\n'.join(self.content)
         admonition_node = self.node_class(text, **self.options)
         self.add_name(admonition_node)
+        admonition_node.source, admonition_node.line = \
+            self.state_machine.get_source_and_line(self.lineno)
         if self.node_class is nodes.admonition:
             title_text = self.arguments[0]
             textnodes, messages = self.state.inline_text(title_text,
@@ -39,9 +42,9 @@ class BaseAdmonition(Directive):
                     self.state_machine.get_source_and_line(self.lineno))
             admonition_node += title
             admonition_node += messages
-            if not 'classes' in self.options:
-                admonition_node['classes'] += ['admonition-' +
-                                               nodes.make_id(title_text)]
+            if 'classes' not in self.options:
+                admonition_node['classes'] += ['admonition-'
+                                               + nodes.make_id(title_text)]
         self.state.nested_parse(self.content, self.content_offset,
                                 admonition_node)
         return [admonition_node]

python/helpers/py3only/docutils/parsers/rst/directives/body.py

@@ -1,4 +1,4 @@
-# $Id: body.py 7267 2011-12-20 14:14:21Z milde $
+# $Id: body.py 9500 2023-12-14 22:38:49Z milde $
 # Author: David Goodger <goodger@python.org>
 # Copyright: This module has been placed in the public domain.
 
@@ -10,12 +10,14 @@ See `docutils.parsers.rst.directives` for API details.
 
 __docformat__ = 'reStructuredText'
 
+
 from docutils import nodes
 from docutils.parsers.rst import Directive
 from docutils.parsers.rst import directives
 from docutils.parsers.rst.roles import set_classes
 from docutils.utils.code_analyzer import Lexer, LexerError, NumberLines
 
+
 class BasePseudoSection(Directive):
 
     required_arguments = 1
@@ -34,16 +36,21 @@ class BasePseudoSection(Directive):
             raise self.error('The "%s" directive may not be used within '
                              'topics or body elements.' % self.name)
         self.assert_has_content()
-        title_text = self.arguments[0]
-        textnodes, messages = self.state.inline_text(title_text, self.lineno)
-        titles = [nodes.title(title_text, '', *textnodes)]
-        # Sidebar uses this code.
-        if 'subtitle' in self.options:
-            textnodes, more_messages = self.state.inline_text(
-                self.options['subtitle'], self.lineno)
-            titles.append(nodes.subtitle(self.options['subtitle'], '',
-                                         *textnodes))
-            messages.extend(more_messages)
+        if self.arguments:  # title (in sidebars optional)
+            title_text = self.arguments[0]
+            textnodes, messages = self.state.inline_text(
+                                      title_text, self.lineno)
+            titles = [nodes.title(title_text, '', *textnodes)]
+            # Sidebar uses this code.
+            if 'subtitle' in self.options:
+                textnodes, more_messages = self.state.inline_text(
+                    self.options['subtitle'], self.lineno)
+                titles.append(nodes.subtitle(self.options['subtitle'], '',
+                                             *textnodes))
+                messages.extend(more_messages)
+        else:
+            titles = []
+            messages = []
         text = '\n'.join(self.content)
         node = self.node_class(text, *(titles + messages))
         node['classes'] += self.options.get('class', [])
@@ -62,6 +69,8 @@ class Sidebar(BasePseudoSection):
 
     node_class = nodes.sidebar
 
+    required_arguments = 0
+    optional_arguments = 1
     option_spec = BasePseudoSection.option_spec.copy()
     option_spec['subtitle'] = directives.unchanged_required
 
@@ -69,6 +78,10 @@ class Sidebar(BasePseudoSection):
         if isinstance(self.state_machine.node, nodes.sidebar):
             raise self.error('The "%s" directive may not be used within a '
                              'sidebar element.' % self.name)
+        if 'subtitle' in self.options and not self.arguments:
+            raise self.error('The "subtitle" option may not be used '
+                             'without a title.')
+
         return BasePseudoSection.run(self)
 
 
@@ -124,8 +137,8 @@ class CodeBlock(Directive):
     optional_arguments = 1
     option_spec = {'class': directives.class_option,
                    'name': directives.unchanged,
-                   'number-lines': directives.unchanged # integer or None
-                  }
+                   'number-lines': directives.unchanged  # integer or None
+                   }
     has_content = True
 
     def run(self):
@@ -146,7 +159,11 @@ class CodeBlock(Directive):
             tokens = Lexer('\n'.join(self.content), language,
                            self.state.document.settings.syntax_highlight)
         except LexerError as error:
-            raise self.warning(error)
+            if self.state.document.settings.report_level > 2:
+                # don't report warnings -> insert without syntax highlight
+                tokens = Lexer('\n'.join(self.content), language, 'none')
+            else:
+                raise self.warning(error)
 
         if 'number-lines' in self.options:
             # optional argument `startline`, defaults to 1
@@ -165,12 +182,11 @@ class CodeBlock(Directive):
             node.attributes['source'] = self.options['source']
         # analyze content and add nodes for every token
         for classes, value in tokens:
-            # print (classes, value)
             if classes:
                 node += nodes.inline(value, value, classes=classes)
             else:
                 # insert as Text to decrease the verbosity of the output
-                node += nodes.Text(value, value)
+                node += nodes.Text(value)
 
         return [node]
 
@@ -178,9 +194,10 @@ class CodeBlock(Directive):
 class MathBlock(Directive):
 
     option_spec = {'class': directives.class_option,
-                   'name': directives.unchanged}
-                   ## TODO: Add Sphinx' ``mathbase.py`` option 'nowrap'?
+                   'name': directives.unchanged,
+                   # TODO: Add Sphinx' ``mathbase.py`` option 'nowrap'?
                    # 'nowrap': directives.flag,
+                   }
     has_content = True
 
     def run(self):
@@ -193,7 +210,8 @@ class MathBlock(Directive):
             if not block:
                 continue
             node = nodes.math_block(self.block_text, block, **self.options)
-            node.line = self.content_offset + 1
+            (node.source,
+             node.line) = self.state_machine.get_source_and_line(self.lineno)
             self.add_name(node)
             _nodes.append(node)
         return _nodes

python/helpers/py3only/docutils/parsers/rst/directives/html.py

@@ -1,85 +1,21 @@
-# $Id: html.py 7320 2012-01-19 22:33:02Z milde $
+# $Id: html.py 9062 2022-05-30 21:09:09Z milde $
 # Author: David Goodger <goodger@python.org>
 # Copyright: This module has been placed in the public domain.
 
 """
-Directives for typically HTML-specific constructs.
+Dummy module for backwards compatibility.
+
+This module is provisional: it will be removed in Docutils 2.0.
 """
 
 __docformat__ = 'reStructuredText'
 
-from docutils import nodes, utils
-from docutils.parsers.rst import Directive
-from docutils.parsers.rst import states
-from docutils.transforms import components
+import warnings
 
+from docutils.parsers.rst.directives.misc import MetaBody, Meta  # noqa: F401
 
-class MetaBody(states.SpecializedBody):
-
-    class meta(nodes.Special, nodes.PreBibliographic, nodes.Element):
-        """HTML-specific "meta" element."""
-        pass
-
-    def field_marker(self, match, context, next_state):
-        """Meta element."""
-        node, blank_finish = self.parsemeta(match)
-        self.parent += node
-        return [], next_state, []
-
-    def parsemeta(self, match):
-        name = self.parse_field_marker(match)
-        indented, indent, line_offset, blank_finish = \
-              self.state_machine.get_first_known_indented(match.end())
-        node = self.meta()
-        pending = nodes.pending(components.Filter,
-                                {'component': 'writer',
-                                 'format': 'html',
-                                 'nodes': [node]})
-        node['content'] = ' '.join(indented)
-        if not indented:
-            line = self.state_machine.line
-            msg = self.reporter.info(
-                  'No content for meta tag "%s".' % name,
-                  nodes.literal_block(line, line))
-            return msg, blank_finish
-        tokens = name.split()
-        try:
-            attname, val = utils.extract_name_value(tokens[0])[0]
-            node[attname.lower()] = val
-        except utils.NameValueError:
-            node['name'] = tokens[0]
-        for token in tokens[1:]:
-            try:
-                attname, val = utils.extract_name_value(token)[0]
-                node[attname.lower()] = val
-            except utils.NameValueError as detail:
-                line = self.state_machine.line
-                msg = self.reporter.error(
-                      'Error parsing meta tag attribute "%s": %s.'
-                      % (token, detail), nodes.literal_block(line, line))
-                return msg, blank_finish
-        self.document.note_pending(pending)
-        return pending, blank_finish
-
-
-class Meta(Directive):
-
-    has_content = True
-
-    SMkwargs = {'state_classes': (MetaBody,)}
-
-    def run(self):
-        self.assert_has_content()
-        node = nodes.Element()
-        new_line_offset, blank_finish = self.state.nested_list_parse(
-            self.content, self.content_offset, node,
-            initial_state='MetaBody', blank_finish=True,
-            state_machine_kwargs=self.SMkwargs)
-        if (new_line_offset - self.content_offset) != len(self.content):
-            # incomplete parse of block?
-            error = self.state_machine.reporter.error(
-                'Invalid meta directive.',
-                nodes.literal_block(self.block_text, self.block_text),
-                line=self.lineno)
-            node += error
-        return node.children
+warnings.warn('The `docutils.parsers.rst.directive.html` module'
+              ' will be removed in Docutils 2.0.'
+              ' Since Docutils 0.18, the "Meta" node is defined in'
+              ' `docutils.parsers.rst.directives.misc`.',
+              DeprecationWarning, stacklevel=2)

python/helpers/py3only/docutils/parsers/rst/directives/images.py

@@ -1,4 +1,4 @@
-# $Id: images.py 7753 2014-06-24 14:52:59Z milde $
+# $Id: images.py 9500 2023-12-14 22:38:49Z milde $
 # Author: David Goodger <goodger@python.org>
 # Copyright: This module has been placed in the public domain.
 
@@ -8,11 +8,17 @@ Directives for figures and simple images.
 
 __docformat__ = 'reStructuredText'
 
-import sys
+from urllib.request import url2pathname
 
-import urllib.error
-import urllib.parse
-import urllib.request
+try:  # check for the Python Imaging Library
+    import PIL.Image
+except ImportError:
+    try:  # sometimes PIL modules are put in PYTHONPATH's root
+        import Image
+        class PIL: pass  # noqa:E701  dummy wrapper
+        PIL.Image = Image
+    except ImportError:
+        PIL = None
 
 from docutils import nodes
 from docutils.nodes import fully_normalize_name, whitespace_normalize_name
@@ -20,28 +26,24 @@ from docutils.parsers.rst import Directive
 from docutils.parsers.rst import directives, states
 from docutils.parsers.rst.roles import set_classes
 
-try: # check for the Python Imaging Library
-    import PIL.Image
-except ImportError:
-    try:  # sometimes PIL modules are put in PYTHONPATH's root
-        import Image
-        class PIL(object): pass  # dummy wrapper
-        PIL.Image = Image
-    except ImportError:
-        PIL = None
 
 class Image(Directive):
 
     align_h_values = ('left', 'center', 'right')
     align_v_values = ('top', 'middle', 'bottom')
     align_values = align_v_values + align_h_values
+    loading_values = ('embed', 'link', 'lazy')
 
     def align(argument):
-        # This is not callable as self.align.  We cannot make it a
+        # This is not callable as `self.align()`.  We cannot make it a
         # staticmethod because we're saving an unbound method in
         # option_spec below.
         return directives.choice(argument, Image.align_values)
 
+    def loading(argument):
+        # This is not callable as `self.loading()` (see above).
+        return directives.choice(argument, Image.loading_values)
+
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
@@ -50,9 +52,10 @@ class Image(Directive):
                    'width': directives.length_or_percentage_or_unitless,
                    'scale': directives.percentage,
                    'align': align,
-                   'name': directives.unchanged,
                    'target': directives.unchanged_required,
-                   'class': directives.class_option}
+                   'loading': loading,
+                   'class': directives.class_option,
+                   'name': directives.unchanged}
 
     def run(self):
         if 'align' in self.options:
@@ -94,6 +97,8 @@ class Image(Directive):
             del self.options['target']
         set_classes(self.options)
         image_node = nodes.image(self.block_text, **self.options)
+        (image_node.source,
+         image_node.line) = self.state_machine.get_source_and_line(self.lineno)
         self.add_name(image_node)
         if reference_node:
             reference_node += image_node
@@ -127,19 +132,19 @@ class Figure(Image):
         if isinstance(image_node, nodes.system_message):
             return [image_node]
         figure_node = nodes.figure('', image_node)
+        (figure_node.source, figure_node.line
+         ) = self.state_machine.get_source_and_line(self.lineno)
         if figwidth == 'image':
             if PIL and self.state.document.settings.file_insertion_enabled:
-                imagepath = urllib.request.url2pathname(image_node['uri'])
+                imagepath = url2pathname(image_node['uri'])
                 try:
-                    img = PIL.Image.open(
-                            imagepath.encode(sys.getfilesystemencoding()))
-                except (IOError, UnicodeEncodeError):
-                    pass # TODO: warn?
+                    with PIL.Image.open(imagepath) as img:
+                        figure_node['width'] = '%dpx' % img.size[0]
+                except (OSError, UnicodeEncodeError):
+                    pass  # TODO: warn/info?
                 else:
                     self.state.document.settings.record_dependencies.add(
                         imagepath.replace('\\', '/'))
-                    figure_node['width'] = '%dpx' % img.size[0]
-                    del img
         elif figwidth is not None:
             figure_node['width'] = figwidth
         if figclasses:
@@ -158,7 +163,7 @@ class Figure(Image):
                 figure_node += caption
             elif not (isinstance(first_node, nodes.comment)
                       and len(first_node) == 0):
-                error = self.state_machine.reporter.error(
+                error = self.reporter.error(
                       'Figure caption must be a paragraph or empty comment.',
                       nodes.literal_block(self.block_text, self.block_text),
                       line=self.lineno)

python/helpers/py3only/docutils/parsers/rst/directives/misc.py

@@ -1,4 +1,4 @@
-# $Id: misc.py 7487 2012-07-22 21:20:28Z milde $
+# $Id: misc.py 9492 2023-11-29 16:58:13Z milde $
 # Authors: David Goodger <goodger@python.org>; Dethe Elza
 # Copyright: This module has been placed in the public domain.
 
@@ -6,18 +6,31 @@
 
 __docformat__ = 'reStructuredText'
 
-import os.path
+from pathlib import Path
 import re
-import sys
 import time
+from urllib.request import urlopen
+from urllib.error import URLError
 
 from docutils import io, nodes, statemachine, utils
 from docutils.parsers.rst import Directive, convert_directive_function
 from docutils.parsers.rst import directives, roles, states
 from docutils.parsers.rst.directives.body import CodeBlock, NumberLines
 from docutils.transforms import misc
-from docutils.utils.error_reporting import SafeString, ErrorString
-from docutils.utils.error_reporting import locale_encoding
+
+
+def adapt_path(path, source='', root_prefix='/'):
+    # Adapt path to files to include or embed.
+    # `root_prefix` is prepended to absolute paths (cf. root_prefix setting),
+    # `source` is the `current_source` of the including directive (which may
+    # be a file included by the main document).
+    if path.startswith('/'):
+        base = Path(root_prefix)
+        path = path[1:]
+    else:
+        base = Path(source).parent
+    # pepend "base" and convert to relative path for shorter system messages
+    return utils.relative_path(None, base/path)
 
 
 class Include(Directive):
@@ -30,6 +43,8 @@ class Include(Directive):
     a part of the given file argument may be included by specifying
     start and end line or text to match before and/or after the text
     to be used.
+
+    https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment
     """
 
     required_arguments = 1
@@ -38,50 +53,54 @@ class Include(Directive):
     option_spec = {'literal': directives.flag,
                    'code': directives.unchanged,
                    'encoding': directives.encoding,
+                   'parser': directives.parser_name,
                    'tab-width': int,
                    'start-line': int,
                    'end-line': int,
                    'start-after': directives.unchanged_required,
                    'end-before': directives.unchanged_required,
                    # ignored except for 'literal' or 'code':
-                   'number-lines': directives.unchanged, # integer or None
+                   'number-lines': directives.unchanged,  # integer or None
                    'class': directives.class_option,
                    'name': directives.unchanged}
 
-    standard_include_path = os.path.join(os.path.dirname(states.__file__),
-                                         'include')
+    standard_include_path = Path(states.__file__).parent / 'include'
 
     def run(self):
-        """Include a file as part of the content of this reST file."""
-        if not self.state.document.settings.file_insertion_enabled:
+        """Include a file as part of the content of this reST file.
+
+        Depending on the options, the file (or a clipping) is
+        converted to nodes and returned or inserted into the input stream.
+        """
+        settings = self.state.document.settings
+        if not settings.file_insertion_enabled:
             raise self.warning('"%s" directive disabled.' % self.name)
-        source = self.state_machine.input_lines.source(
-            self.lineno - self.state_machine.input_offset - 1)
-        source_dir = os.path.dirname(os.path.abspath(source))
+        tab_width = self.options.get('tab-width', settings.tab_width)
+        current_source = self.state.document.current_source
         path = directives.path(self.arguments[0])
         if path.startswith('<') and path.endswith('>'):
-            path = os.path.join(self.standard_include_path, path[1:-1])
-        path = os.path.normpath(os.path.join(source_dir, path))
-        path = utils.relative_path(None, path)
-        path = nodes.reprunicode(path)
-        encoding = self.options.get(
-            'encoding', self.state.document.settings.input_encoding)
-        e_handler=self.state.document.settings.input_encoding_error_handler
-        tab_width = self.options.get(
-            'tab-width', self.state.document.settings.tab_width)
+            path = '/' + path[1:-1]
+            root_prefix = self.standard_include_path
+        else:
+            root_prefix = settings.root_prefix
+        path = adapt_path(path, current_source, root_prefix)
+        encoding = self.options.get('encoding', settings.input_encoding)
+        error_handler = settings.input_encoding_error_handler
         try:
-            self.state.document.settings.record_dependencies.add(path)
             include_file = io.FileInput(source_path=path,
                                         encoding=encoding,
-                                        error_handler=e_handler)
-        except UnicodeEncodeError as error:
-            raise self.severe('Problems with "%s" directive path:\n'
-                              'Cannot encode input file path "%s" '
-                              '(wrong locale?).' %
-                              (self.name, SafeString(path)))
-        except IOError as error:
-            raise self.severe('Problems with "%s" directive path:\n%s.' %
-                      (self.name, ErrorString(error)))
+                                        error_handler=error_handler)
+        except UnicodeEncodeError:
+            raise self.severe(f'Problems with "{self.name}" directive path:\n'
+                              f'Cannot encode input file path "{path}" '
+                              '(wrong locale?).')
+        except OSError as error:
+            raise self.severe(f'Problems with "{self.name}" directive '
+                              f'path:\n{io.error_string(error)}.')
+        else:
+            settings.record_dependencies.add(path)
+
+        # Get to-be-included content
         startline = self.options.get('start-line', None)
         endline = self.options.get('end-line', None)
         try:
@@ -91,8 +110,8 @@ class Include(Directive):
             else:
                 rawtext = include_file.read()
         except UnicodeError as error:
-            raise self.severe('Problem with "%s" directive:\n%s' %
-                              (self.name, ErrorString(error)))
+            raise self.severe(f'Problem with "{self.name}" directive:\n'
+                              + io.error_string(error))
         # start-after/end-before: no restrictions on newlines in match-text,
         # and no restrictions on matching inside lines vs. line boundaries
         after_text = self.options.get('start-after', None)
@@ -114,14 +133,20 @@ class Include(Directive):
 
         include_lines = statemachine.string2lines(rawtext, tab_width,
                                                   convert_whitespace=True)
+        for i, line in enumerate(include_lines):
+            if len(line) > settings.line_length_limit:
+                raise self.warning('"%s": line %d exceeds the'
+                                   ' line-length-limit.' % (path, i+1))
+
         if 'literal' in self.options:
-            # Convert tabs to spaces, if `tab_width` is positive.
+            # Don't convert tabs to spaces, if `tab_width` is negative.
             if tab_width >= 0:
                 text = rawtext.expandtabs(tab_width)
             else:
                 text = rawtext
-            literal_block = nodes.literal_block(rawtext, source=path,
-                                    classes=self.options.get('class', []))
+            literal_block = nodes.literal_block(
+                                rawtext, source=path,
+                                classes=self.options.get('class', []))
             literal_block.line = 1
             self.add_name(literal_block)
             if 'number-lines' in self.options:
@@ -139,23 +164,58 @@ class Include(Directive):
                         literal_block += nodes.inline(value, value,
                                                       classes=classes)
                     else:
-                        literal_block += nodes.Text(value, value)
+                        literal_block += nodes.Text(value)
             else:
-                literal_block += nodes.Text(text, text)
+                literal_block += nodes.Text(text)
             return [literal_block]
+
         if 'code' in self.options:
             self.options['source'] = path
+            # Don't convert tabs to spaces, if `tab_width` is negative:
+            if tab_width < 0:
+                include_lines = rawtext.splitlines()
             codeblock = CodeBlock(self.name,
-                                  [self.options.pop('code')], # arguments
+                                  [self.options.pop('code')],  # arguments
                                   self.options,
-                                  include_lines, # content
+                                  include_lines,  # content
                                   self.lineno,
                                   self.content_offset,
                                   self.block_text,
                                   self.state,
                                   self.state_machine)
             return codeblock.run()
+
+        # Prevent circular inclusion:
+        clip_options = (startline, endline, before_text, after_text)
+        include_log = self.state.document.include_log
+        # log entries are tuples (<source>, <clip-options>)
+        if not include_log:  # new document, initialize with document source
+            include_log.append((utils.relative_path(None, current_source),
+                                (None, None, None, None)))
+        if (path, clip_options) in include_log:
+            master_paths = (pth for (pth, opt) in reversed(include_log))
+            inclusion_chain = '\n> '.join((path, *master_paths))
+            raise self.warning('circular inclusion in "%s" directive:\n%s'
+                               % (self.name, inclusion_chain))
+
+        if 'parser' in self.options:
+            # parse into a dummy document and return created nodes
+            document = utils.new_document(path, settings)
+            document.include_log = include_log + [(path, clip_options)]
+            parser = self.options['parser']()
+            parser.parse('\n'.join(include_lines), document)
+            # clean up doctree and complete parsing
+            document.transformer.populate_from_components((parser,))
+            document.transformer.apply_transforms()
+            return document.children
+
+        # Include as rST source:
+        #
+        # mark end (cf. parsers.rst.states.Body.comment())
+        include_lines += ['', '.. end of inclusion from "%s"' % path]
         self.state_machine.insert_input(include_lines, path)
+        # update include-log
+        include_log.append((path, clip_options))
         return []
 
 
@@ -175,19 +235,19 @@ class Raw(Directive):
     final_argument_whitespace = True
     option_spec = {'file': directives.path,
                    'url': directives.uri,
-                   'encoding': directives.encoding}
+                   'encoding': directives.encoding,
+                   'class': directives.class_option}
     has_content = True
 
     def run(self):
-        if (not self.state.document.settings.raw_enabled
-            or (not self.state.document.settings.file_insertion_enabled
-                and ('file' in self.options
-                     or 'url' in self.options))):
+        settings = self.state.document.settings
+        if (not settings.raw_enabled
+            or (not settings.file_insertion_enabled
+                and ('file' in self.options or 'url' in self.options))):
             raise self.warning('"%s" directive disabled.' % self.name)
         attributes = {'format': ' '.join(self.arguments[0].lower().split())}
-        encoding = self.options.get(
-            'encoding', self.state.document.settings.input_encoding)
-        e_handler=self.state.document.settings.input_encoding_error_handler
+        encoding = self.options.get('encoding', settings.input_encoding)
+        error_handler = settings.input_encoding_error_handler
         if self.content:
             if 'file' in self.options or 'url' in self.options:
                 raise self.error(
@@ -199,53 +259,50 @@ class Raw(Directive):
                 raise self.error(
                     'The "file" and "url" options may not be simultaneously '
                     'specified for the "%s" directive.' % self.name)
-            source_dir = os.path.dirname(
-                os.path.abspath(self.state.document.current_source))
-            path = os.path.normpath(os.path.join(source_dir,
-                                                 self.options['file']))
-            path = utils.relative_path(None, path)
+            path = adapt_path(self.options['file'],
+                              self.state.document.current_source,
+                              settings.root_prefix)
             try:
                 raw_file = io.FileInput(source_path=path,
                                         encoding=encoding,
-                                        error_handler=e_handler)
+                                        error_handler=error_handler)
+            except OSError as error:
+                raise self.severe(f'Problems with "{self.name}" directive '
+                                  f'path:\n{io.error_string(error)}.')
+            else:
                 # TODO: currently, raw input files are recorded as
                 # dependencies even if not used for the chosen output format.
-                self.state.document.settings.record_dependencies.add(path)
-            except IOError as error:
-                raise self.severe('Problems with "%s" directive path:\n%s.'
-                                  % (self.name, ErrorString(error)))
+                settings.record_dependencies.add(path)
             try:
                 text = raw_file.read()
             except UnicodeError as error:
-                raise self.severe('Problem with "%s" directive:\n%s'
-                    % (self.name, ErrorString(error)))
+                raise self.severe(f'Problem with "{self.name}" directive:\n'
+                                  + io.error_string(error))
             attributes['source'] = path
         elif 'url' in self.options:
             source = self.options['url']
-            # Do not import urllib2 at the top of the module because
-            # it may fail due to broken SSL dependencies, and it takes
-            # about 0.15 seconds to load.
-            import urllib.request, urllib.error, urllib.parse
             try:
-                raw_text = urllib.request.urlopen(source).read()
-            except (urllib.error.URLError, IOError, OSError) as error:
-                raise self.severe('Problems with "%s" directive URL "%s":\n%s.'
-                    % (self.name, self.options['url'], ErrorString(error)))
+                raw_text = urlopen(source).read()
+            except (URLError, OSError) as error:
+                raise self.severe(f'Problems with "{self.name}" directive URL '
+                                  f'"{self.options["url"]}":\n'
+                                  f'{io.error_string(error)}.')
             raw_file = io.StringInput(source=raw_text, source_path=source,
-                                      encoding=encoding, 
-                                      error_handler=e_handler)
+                                      encoding=encoding,
+                                      error_handler=error_handler)
             try:
                 text = raw_file.read()
             except UnicodeError as error:
-                raise self.severe('Problem with "%s" directive:\n%s'
-                                  % (self.name, ErrorString(error)))
+                raise self.severe(f'Problem with "{self.name}" directive:\n'
+                                  + io.error_string(error))
             attributes['source'] = source
         else:
             # This will always fail because there is no content.
             self.assert_has_content()
-        raw_node = nodes.raw('', text, **attributes)
+        raw_node = nodes.raw('', text, classes=self.options.get('class', []),
+                             **attributes)
         (raw_node.source,
-        raw_node.line) = self.state_machine.get_source_and_line(self.lineno)
+         raw_node.line) = self.state_machine.get_source_and_line(self.lineno)
         return [raw_node]
 
 
@@ -274,13 +331,14 @@ class Replace(Directive):
                 messages.append(elem)
             else:
                 return [
-                    self.state_machine.reporter.error(
-                        'Error in "%s" directive: may contain a single paragraph '
-                        'only.' % (self.name), line=self.lineno) ]
+                    self.reporter.error(
+                        f'Error in "{self.name}" directive: may contain '
+                        'a single paragraph only.', line=self.lineno)]
         if node:
             return messages + node.children
         return messages
 
+
 class Unicode(Directive):
 
     r"""
@@ -320,7 +378,7 @@ class Unicode(Directive):
                 decoded = directives.unicode_code(code)
             except ValueError as error:
                 raise self.error('Invalid character code: %s\n%s'
-                    % (code, ErrorString(error)))
+                                 % (code, io.error_string(error)))
             element += nodes.Text(decoded)
         return element.children
 
@@ -400,12 +458,12 @@ class Role(Directive):
             'supported (specified by "%r" role).' % (self.name, base_role))
         try:
             converted_role = convert_directive_function(base_role)
-            (arguments, options, content, content_offset) = (
-                self.state.parse_directive_block(
-                self.content[1:], self.content_offset, converted_role,
-                option_presets={}))
+            (arguments, options, content, content_offset
+             ) = self.state.parse_directive_block(
+                    self.content[1:], self.content_offset,
+                    converted_role, option_presets={})
         except states.MarkupError as detail:
-            error = self.state_machine.reporter.error(
+            error = self.reporter.error(
                 'Error in "%s" directive:\n%s.' % (self.name, detail),
                 nodes.literal_block(self.block_text, self.block_text),
                 line=self.lineno)
@@ -414,10 +472,11 @@ class Role(Directive):
             try:
                 options['class'] = directives.class_option(new_role_name)
             except ValueError as detail:
-                error = self.state_machine.reporter.error(
+                error = self.reporter.error(
                     'Invalid argument for "%s" directive:\n%s.'
-                    % (self.name, SafeString(detail)), nodes.literal_block(
-                    self.block_text, self.block_text), line=self.lineno)
+                    % (self.name, detail),
+                    nodes.literal_block(self.block_text, self.block_text),
+                    line=self.lineno)
                 return messages + [error]
         role = roles.CustomRole(new_role_name, base_role, options, content)
         roles.register_local_role(new_role_name, role)
@@ -447,7 +506,6 @@ class DefaultRole(Directive):
                 line=self.lineno)
             return messages + [error]
         roles._roles[''] = role
-        # @@@ should this be local to the document, not the parser?
         return messages
 
 
@@ -462,6 +520,74 @@ class Title(Directive):
         return []
 
 
+class MetaBody(states.SpecializedBody):
+
+    def field_marker(self, match, context, next_state):
+        """Meta element."""
+        node, blank_finish = self.parsemeta(match)
+        self.parent += node
+        return [], next_state, []
+
+    def parsemeta(self, match):
+        name = self.parse_field_marker(match)
+        name = nodes.unescape(utils.escape2null(name))
+        (indented, indent, line_offset, blank_finish
+         ) = self.state_machine.get_first_known_indented(match.end())
+        node = nodes.meta()
+        node['content'] = nodes.unescape(utils.escape2null(
+                                            ' '.join(indented)))
+        if not indented:
+            line = self.state_machine.line
+            msg = self.reporter.info(
+                  'No content for meta tag "%s".' % name,
+                  nodes.literal_block(line, line))
+            return msg, blank_finish
+        tokens = name.split()
+        try:
+            attname, val = utils.extract_name_value(tokens[0])[0]
+            node[attname.lower()] = val
+        except utils.NameValueError:
+            node['name'] = tokens[0]
+        for token in tokens[1:]:
+            try:
+                attname, val = utils.extract_name_value(token)[0]
+                node[attname.lower()] = val
+            except utils.NameValueError as detail:
+                line = self.state_machine.line
+                msg = self.reporter.error(
+                      'Error parsing meta tag attribute "%s": %s.'
+                      % (token, detail), nodes.literal_block(line, line))
+                return msg, blank_finish
+        return node, blank_finish
+
+
+class Meta(Directive):
+
+    has_content = True
+
+    SMkwargs = {'state_classes': (MetaBody,)}
+
+    def run(self):
+        self.assert_has_content()
+        node = nodes.Element()
+        new_line_offset, blank_finish = self.state.nested_list_parse(
+            self.content, self.content_offset, node,
+            initial_state='MetaBody', blank_finish=True,
+            state_machine_kwargs=self.SMkwargs)
+        if (new_line_offset - self.content_offset) != len(self.content):
+            # incomplete parse of block?
+            error = self.reporter.error(
+                'Invalid meta directive.',
+                nodes.literal_block(self.block_text, self.block_text),
+                line=self.lineno)
+            node += error
+        # insert at begin of document
+        index = self.state.document.first_child_not_matching_class(
+                                        (nodes.Titular, nodes.meta)) or 0
+        self.state.document[index:index] = node.children
+        return []
+
+
 class Date(Directive):
 
     has_content = True
@@ -472,21 +598,23 @@ class Date(Directive):
                 'Invalid context: the "%s" directive can only be used within '
                 'a substitution definition.' % self.name)
         format_str = '\n'.join(self.content) or '%Y-%m-%d'
-        if sys.version_info< (3, 0):
-            try:
-                format_str = format_str.encode(locale_encoding or 'utf-8')
-            except UnicodeEncodeError:
-                raise self.warning('Cannot encode date format string '
-                    'with locale encoding "%s".' % locale_encoding)
+        # @@@
+        # Use timestamp from the `SOURCE_DATE_EPOCH`_ environment variable?
+        # Pro: Docutils-generated documentation
+        #      can easily be part of `reproducible software builds`__
+        #
+        #      __ https://reproducible-builds.org/
+        #
+        # Con: Changes the specs, hard to predict behaviour,
+        #
+        # See also the discussion about \date \time \year in TeX
+        # http://tug.org/pipermail/tex-k/2016-May/002704.html
+        # source_date_epoch = os.environ.get('SOURCE_DATE_EPOCH')
+        # if (source_date_epoch):
+        #     text = time.strftime(format_str,
+        #                          time.gmtime(int(source_date_epoch)))
+        # else:
         text = time.strftime(format_str)
-        if sys.version_info< (3, 0):
-            # `text` is a byte string that may contain non-ASCII characters:
-            try:
-                text = text.decode(locale_encoding or 'utf-8')
-            except UnicodeDecodeError:
-                text = text.decode(locale_encoding or 'utf-8', 'replace')
-                raise self.warning('Error decoding "%s"'
-                    'with locale encoding "%s".' % (text, locale_encoding))
         return [nodes.Text(text)]
 
 
@@ -502,34 +630,13 @@ class TestDirective(Directive):
     def run(self):
         if self.content:
             text = '\n'.join(self.content)
-            info = self.state_machine.reporter.info(
+            info = self.reporter.info(
                 'Directive processed. Type="%s", arguments=%r, options=%r, '
                 'content:' % (self.name, self.arguments, self.options),
                 nodes.literal_block(text, text), line=self.lineno)
         else:
-            info = self.state_machine.reporter.info(
+            info = self.reporter.info(
                 'Directive processed. Type="%s", arguments=%r, options=%r, '
                 'content: None' % (self.name, self.arguments, self.options),
                 line=self.lineno)
         return [info]
-
-# Old-style, functional definition:
-#
-# def directive_test_function(name, arguments, options, content, lineno,
-#                             content_offset, block_text, state, state_machine):
-#     """This directive is useful only for testing purposes."""
-#     if content:
-#         text = '\n'.join(content)
-#         info = state_machine.reporter.info(
-#             'Directive processed. Type="%s", arguments=%r, options=%r, '
-#             'content:' % (name, arguments, options),
-#             nodes.literal_block(text, text), line=lineno)
-#     else:
-#         info = state_machine.reporter.info(
-#             'Directive processed. Type="%s", arguments=%r, options=%r, '
-#             'content: None' % (name, arguments, options), line=lineno)
-#     return [info]
-#
-# directive_test_function.arguments = (0, 1, 1)
-# directive_test_function.options = {'option': directives.unchanged_required}
-# directive_test_function.content = 1

python/helpers/py3only/docutils/parsers/rst/directives/parts.py

@@ -1,4 +1,4 @@
-# $Id: parts.py 7308 2012-01-06 12:08:43Z milde $
+# $Id: parts.py 8993 2022-01-29 13:20:04Z milde $
 # Authors: David Goodger <goodger@python.org>; Dmitry Jemerov
 # Copyright: This module has been placed in the public domain.
 
@@ -9,9 +9,9 @@ Directives for document parts.
 __docformat__ = 'reStructuredText'
 
 from docutils import nodes, languages
+from docutils.transforms import parts
 from docutils.parsers.rst import Directive
 from docutils.parsers.rst import directives
-from docutils.transforms import parts
 
 
 class Contents(Directive):
@@ -41,7 +41,7 @@ class Contents(Directive):
                    'local': directives.flag,
                    'backlinks': backlinks,
                    'class': directives.class_option}
-    
+
     def run(self):
         if not (self.state_machine.match_titles
                 or isinstance(self.state_machine.node, nodes.sidebar)):

python/helpers/py3only/docutils/parsers/rst/directives/references.py

@@ -9,9 +9,9 @@ Directives for references and targets.
 __docformat__ = 'reStructuredText'
 
 from docutils import nodes
+from docutils.transforms import references
 from docutils.parsers.rst import Directive
 from docutils.parsers.rst import directives
-from docutils.transforms import references
 
 
 class TargetNotes(Directive):

python/helpers/py3only/docutils/parsers/rst/directives/tables.py

@@ -1,4 +1,4 @@
-# $Id: tables.py 7747 2014-03-20 10:51:10Z milde $
+# $Id: tables.py 9492 2023-11-29 16:58:13Z milde $
 # Authors: David Goodger <goodger@python.org>; David Priest
 # Copyright: This module has been placed in the public domain.
 
@@ -8,15 +8,22 @@ Directives for table elements.
 
 __docformat__ = 'reStructuredText'
 
-import csv
-import os.path
-import sys
 
-from docutils import io, nodes, statemachine, utils
+import csv
+from urllib.request import urlopen
+from urllib.error import URLError
+import warnings
+
+from docutils import nodes, statemachine
+from docutils.io import FileInput, StringInput
 from docutils.parsers.rst import Directive
 from docutils.parsers.rst import directives
+from docutils.parsers.rst.directives.misc import adapt_path
 from docutils.utils import SystemMessagePropagation
-from docutils.utils.error_reporting import SafeString
+
+
+def align(argument):
+    return directives.choice(argument, ('left', 'center', 'right'))
 
 
 class Table(Directive):
@@ -28,7 +35,11 @@ class Table(Directive):
     optional_arguments = 1
     final_argument_whitespace = True
     option_spec = {'class': directives.class_option,
-                   'name': directives.unchanged}
+                   'name': directives.unchanged,
+                   'align': align,
+                   'width': directives.length_or_percentage_or_unitless,
+                   'widths': directives.value_or(('auto', 'grid'),
+                                                 directives.positive_int_list)}
     has_content = True
 
     def make_title(self):
@@ -37,68 +48,71 @@ class Table(Directive):
             text_nodes, messages = self.state.inline_text(title_text,
                                                           self.lineno)
             title = nodes.title(title_text, '', *text_nodes)
+            (title.source,
+             title.line) = self.state_machine.get_source_and_line(self.lineno)
         else:
             title = None
             messages = []
         return title, messages
 
-    def process_header_option(self):
-        source = self.state_machine.get_source(self.lineno - 1)
-        table_head = []
-        max_header_cols = 0
-        if 'header' in self.options:   # separate table header in option
-            rows, max_header_cols = self.parse_csv_data_into_rows(
-                self.options['header'].split('\n'), self.HeaderDialect(),
-                source)
-            table_head.extend(rows)
-        return table_head, max_header_cols
-
     def check_table_dimensions(self, rows, header_rows, stub_columns):
         if len(rows) < header_rows:
-            error = self.state_machine.reporter.error(
-                '%s header row(s) specified but only %s row(s) of data '
-                'supplied ("%s" directive).'
-                % (header_rows, len(rows), self.name), nodes.literal_block(
-                self.block_text, self.block_text), line=self.lineno)
+            error = self.reporter.error('%s header row(s) specified but '
+                'only %s row(s) of data supplied ("%s" directive).'
+                % (header_rows, len(rows), self.name),
+                nodes.literal_block(self.block_text, self.block_text),
+                line=self.lineno)
             raise SystemMessagePropagation(error)
         if len(rows) == header_rows > 0:
-            error = self.state_machine.reporter.error(
-                'Insufficient data supplied (%s row(s)); no data remaining '
-                'for table body, required by "%s" directive.'
-                % (len(rows), self.name), nodes.literal_block(
-                self.block_text, self.block_text), line=self.lineno)
+            error = self.reporter.error(
+                f'Insufficient data supplied ({len(rows)} row(s)); '
+                'no data remaining for table body, '
+                f'required by "{self.name}" directive.',
+                nodes.literal_block(self.block_text, self.block_text),
+                line=self.lineno)
             raise SystemMessagePropagation(error)
         for row in rows:
             if len(row) < stub_columns:
-                error = self.state_machine.reporter.error(
-                    '%s stub column(s) specified but only %s columns(s) of '
-                    'data supplied ("%s" directive).' %
-                    (stub_columns, len(row), self.name), nodes.literal_block(
-                    self.block_text, self.block_text), line=self.lineno)
+                error = self.reporter.error(
+                    f'{stub_columns} stub column(s) specified '
+                    f'but only {len(row)} columns(s) of data supplied '
+                    f'("{self.name}" directive).',
+                    nodes.literal_block(self.block_text, self.block_text),
+                    line=self.lineno)
                 raise SystemMessagePropagation(error)
             if len(row) == stub_columns > 0:
-                error = self.state_machine.reporter.error(
-                    'Insufficient data supplied (%s columns(s)); no data remaining '
-                    'for table body, required by "%s" directive.'
-                    % (len(row), self.name), nodes.literal_block(
-                    self.block_text, self.block_text), line=self.lineno)
+                error = self.reporter.error(
+                    'Insufficient data supplied (%s columns(s)); '
+                    'no data remaining for table body, required '
+                    'by "%s" directive.' % (len(row), self.name),
+                    nodes.literal_block(self.block_text, self.block_text),
+                    line=self.lineno)
                 raise SystemMessagePropagation(error)
 
-    def get_column_widths(self, max_cols):
-        if 'widths' in self.options:
-            col_widths = self.options['widths']
-            if len(col_widths) != max_cols:
-                error = self.state_machine.reporter.error(
-                    '"%s" widths do not match the number of columns in table '
-                    '(%s).' % (self.name, max_cols), nodes.literal_block(
-                    self.block_text, self.block_text), line=self.lineno)
+    def set_table_width(self, table_node):
+        if 'width' in self.options:
+            table_node['width'] = self.options.get('width')
+
+    @property
+    def widths(self):
+        return self.options.get('widths', '')
+
+    def get_column_widths(self, n_cols):
+        if isinstance(self.widths, list):
+            if len(self.widths) != n_cols:
+                # TODO: use last value for missing columns?
+                error = self.reporter.error('"%s" widths do not match the '
+                    'number of columns in table (%s).' % (self.name, n_cols),
+                    nodes.literal_block(self.block_text, self.block_text),
+                    line=self.lineno)
                 raise SystemMessagePropagation(error)
-        elif max_cols:
-            col_widths = [100 // max_cols] * max_cols
+            col_widths = self.widths
+        elif n_cols:
+            col_widths = [100 // n_cols] * n_cols
         else:
-            error = self.state_machine.reporter.error(
-                'No table data detected in CSV file.', nodes.literal_block(
-                self.block_text, self.block_text), line=self.lineno)
+            error = self.reporter.error('No table data detected in CSV file.',
+                nodes.literal_block(self.block_text, self.block_text),
+                line=self.lineno)
             raise SystemMessagePropagation(error)
         return col_widths
 
@@ -110,25 +124,47 @@ class Table(Directive):
 
 
 class RSTTable(Table):
+    """
+    Class for the `"table" directive`__ for formal tables using rST syntax.
+
+    __ https://docutils.sourceforge.io/docs/ref/rst/directives.html
+    """
 
     def run(self):
         if not self.content:
-            warning = self.state_machine.reporter.warning(
-                'Content block expected for the "%s" directive; none found.'
-                % self.name, nodes.literal_block(
-                self.block_text, self.block_text), line=self.lineno)
+            warning = self.reporter.warning('Content block expected '
+                'for the "%s" directive; none found.' % self.name,
+                nodes.literal_block(self.block_text, self.block_text),
+                line=self.lineno)
             return [warning]
         title, messages = self.make_title()
         node = nodes.Element()          # anonymous container for parsing
         self.state.nested_parse(self.content, self.content_offset, node)
         if len(node) != 1 or not isinstance(node[0], nodes.table):
-            error = self.state_machine.reporter.error(
-                'Error parsing content block for the "%s" directive: exactly '
-                'one table expected.' % self.name, nodes.literal_block(
-                self.block_text, self.block_text), line=self.lineno)
+            error = self.reporter.error('Error parsing content block for the '
+                '"%s" directive: exactly one table expected.' % self.name,
+                nodes.literal_block(self.block_text, self.block_text),
+                line=self.lineno)
             return [error]
         table_node = node[0]
         table_node['classes'] += self.options.get('class', [])
+        self.set_table_width(table_node)
+        if 'align' in self.options:
+            table_node['align'] = self.options.get('align')
+        if isinstance(self.widths, list):
+            tgroup = table_node[0]
+            try:
+                col_widths = self.get_column_widths(tgroup["cols"])
+            except SystemMessagePropagation as detail:
+                return [detail.args[0]]
+            colspecs = [child for child in tgroup.children
+                        if child.tagname == 'colspec']
+            for colspec, col_width in zip(colspecs, col_widths):
+                colspec['colwidth'] = col_width
+        if self.widths == 'auto':
+            table_node['classes'] += ['colwidths-auto']
+        elif self.widths:  # "grid" or list of integers
+            table_node['classes'] += ['colwidths-given']
         self.add_name(table_node)
         if title:
             table_node.insert(0, title)
@@ -140,12 +176,15 @@ class CSVTable(Table):
     option_spec = {'header-rows': directives.nonnegative_int,
                    'stub-columns': directives.nonnegative_int,
                    'header': directives.unchanged,
-                   'widths': directives.positive_int_list,
+                   'width': directives.length_or_percentage_or_unitless,
+                   'widths': directives.value_or(('auto', ),
+                                                 directives.positive_int_list),
                    'file': directives.path,
                    'url': directives.uri,
                    'encoding': directives.encoding,
                    'class': directives.class_option,
                    'name': directives.unchanged,
+                   'align': align,
                    # field delimiter char
                    'delim': directives.single_char_or_whitespace_or_unicode,
                    # treat whitespace after delimiter as significant
@@ -153,7 +192,7 @@ class CSVTable(Table):
                    # text field quote/unquote char:
                    'quote': directives.single_char_or_unicode,
                    # char used to escape delim & quote as-needed:
-                   'escape': directives.single_char_or_unicode,}
+                   'escape': directives.single_char_or_unicode}
 
     class DocutilsDialect(csv.Dialect):
 
@@ -169,21 +208,36 @@ class CSVTable(Table):
 
         def __init__(self, options):
             if 'delim' in options:
-                self.delimiter = CSVTable.encode_for_csv(options['delim'])
+                self.delimiter = options['delim']
             if 'keepspace' in options:
                 self.skipinitialspace = False
             if 'quote' in options:
-                self.quotechar = CSVTable.encode_for_csv(options['quote'])
+                self.quotechar = options['quote']
             if 'escape' in options:
                 self.doublequote = False
-                self.escapechar = CSVTable.encode_for_csv(options['escape'])
-            csv.Dialect.__init__(self)
-
+                self.escapechar = options['escape']
+            super().__init__()
 
     class HeaderDialect(csv.Dialect):
+        """
+        CSV dialect used for the "header" option data.
 
-        """CSV dialect to use for the "header" option data."""
-
+        Deprecated. Will be removed in Docutils 0.22.
+        """
+        # The separate HeaderDialect was introduced in revision 2294
+        # (2004-06-17) in the sandbox before the "csv-table" directive moved
+        # to the trunk in r2309. Discussion in docutils-devel around this time
+        # did not mention a rationale (part of the discussion was in private
+        # mail).
+        # This is in conflict with the documentation, which always said:
+        # "Must use the same CSV format as the main CSV data."
+        # and did not change in this aspect.
+        #
+        # Maybe it was intended to have similar escape rules for rST and CSV,
+        # however with the current implementation this means we need
+        # `\\` for rST markup and ``\\\\`` for a literal backslash
+        # in the "option" header but ``\`` and ``\\`` in the header-lines and
+        # table cells of the main CSV data.
         delimiter = ','
         quotechar = '"'
         escapechar = '\\'
@@ -193,20 +247,41 @@ class CSVTable(Table):
         lineterminator = '\n'
         quoting = csv.QUOTE_MINIMAL
 
-    def check_requirements(self):
-        pass
+        def __init__(self):
+            warnings.warn('CSVTable.HeaderDialect will be removed '
+                          'in Docutils 0.22.',
+                          PendingDeprecationWarning, stacklevel=2)
+            super().__init__()
+
+    @staticmethod
+    def check_requirements():
+        warnings.warn('CSVTable.check_requirements()'
+                      ' is not required with Python 3'
+                      ' and will be removed in Docutils 0.22.',
+                      DeprecationWarning, stacklevel=2)
+
+    def process_header_option(self):
+        source = self.state_machine.get_source(self.lineno - 1)
+        table_head = []
+        max_header_cols = 0
+        if 'header' in self.options:   # separate table header in option
+            rows, max_header_cols = self.parse_csv_data_into_rows(
+                                        self.options['header'].split('\n'),
+                                        self.DocutilsDialect(self.options),
+                                        source)
+            table_head.extend(rows)
+        return table_head, max_header_cols
 
     def run(self):
         try:
             if (not self.state.document.settings.file_insertion_enabled
                 and ('file' in self.options
                      or 'url' in self.options)):
-                warning = self.state_machine.reporter.warning(
-                    'File and URL access deactivated; ignoring "%s" '
-                    'directive.' % self.name, nodes.literal_block(
-                    self.block_text, self.block_text), line=self.lineno)
+                warning = self.reporter.warning('File and URL access '
+                    'deactivated; ignoring "%s" directive.' % self.name,
+                    nodes.literal_block(self.block_text, self.block_text),
+                    line=self.lineno)
                 return [warning]
-            self.check_requirements()
             title, messages = self.make_title()
             csv_data, source = self.get_csv_data()
             table_head, max_header_cols = self.process_header_option()
@@ -225,17 +300,18 @@ class CSVTable(Table):
             return [detail.args[0]]
         except csv.Error as detail:
             message = str(detail)
-            if sys.version_info < (3,) and '1-character string' in message:
-                message += '\nwith Python 2.x this must be an ASCII character.'
-            error = self.state_machine.reporter.error(
-                'Error with CSV data in "%s" directive:\n%s'
-                % (self.name, message), nodes.literal_block(
-                self.block_text, self.block_text), line=self.lineno)
+            error = self.reporter.error('Error with CSV data'
+                ' in "%s" directive:\n%s' % (self.name, message),
+                nodes.literal_block(self.block_text, self.block_text),
+                line=self.lineno)
             return [error]
         table = (col_widths, table_head, table_body)
         table_node = self.state.build_table(table, self.content_offset,
-                                            stub_columns)
+                                            stub_columns, widths=self.widths)
         table_node['classes'] += self.options.get('class', [])
+        if 'align' in self.options:
+            table_node['align'] = self.options.get('align')
+        self.set_table_width(table_node)
         self.add_name(table_node)
         if title:
             table_node.insert(0, title)
@@ -246,103 +322,96 @@ class CSVTable(Table):
         Get CSV data from the directive content, from an external
         file, or from a URL reference.
         """
-        encoding = self.options.get(
-            'encoding', self.state.document.settings.input_encoding)
-        error_handler = self.state.document.settings.input_encoding_error_handler
+        settings = self.state.document.settings
+        encoding = self.options.get('encoding', settings.input_encoding)
+        error_handler = settings.input_encoding_error_handler
         if self.content:
             # CSV data is from directive content.
             if 'file' in self.options or 'url' in self.options:
-                error = self.state_machine.reporter.error(
-                    '"%s" directive may not both specify an external file and'
-                    ' have content.' % self.name, nodes.literal_block(
-                    self.block_text, self.block_text), line=self.lineno)
+                error = self.reporter.error('"%s" directive may not both '
+                    'specify an external file and have content.' % self.name,
+                    nodes.literal_block(self.block_text, self.block_text),
+                    line=self.lineno)
                 raise SystemMessagePropagation(error)
             source = self.content.source(0)
             csv_data = self.content
         elif 'file' in self.options:
             # CSV data is from an external file.
             if 'url' in self.options:
-                error = self.state_machine.reporter.error(
-                      'The "file" and "url" options may not be simultaneously'
-                      ' specified for the "%s" directive.' % self.name,
-                      nodes.literal_block(self.block_text, self.block_text),
-                      line=self.lineno)
+                error = self.reporter.error('The "file" and "url" options '
+                    'may not be simultaneously specified '
+                    'for the "%s" directive.' % self.name,
+                    nodes.literal_block(self.block_text, self.block_text),
+                    line=self.lineno)
                 raise SystemMessagePropagation(error)
-            source_dir = os.path.dirname(
-                os.path.abspath(self.state.document.current_source))
-            source = os.path.normpath(os.path.join(source_dir,
-                                                   self.options['file']))
-            source = utils.relative_path(None, source)
+            source = adapt_path(self.options['file'],
+                                self.state.document.current_source,
+                                settings.root_prefix)
             try:
-                self.state.document.settings.record_dependencies.add(source)
-                csv_file = io.FileInput(source_path=source,
-                                        encoding=encoding,
-                                        error_handler=error_handler)
+                csv_file = FileInput(source_path=source,
+                                     encoding=encoding,
+                                     error_handler=error_handler)
                 csv_data = csv_file.read().splitlines()
-            except IOError as error:
-                severe = self.state_machine.reporter.severe(
+            except OSError as error:
+                severe = self.reporter.severe(
                     'Problems with "%s" directive path:\n%s.'
-                    % (self.name, SafeString(error)),
+                    % (self.name, error),
                     nodes.literal_block(self.block_text, self.block_text),
                     line=self.lineno)
                 raise SystemMessagePropagation(severe)
+            else:
+                settings.record_dependencies.add(source)
         elif 'url' in self.options:
-            # CSV data is from a URL.
-            # Do not import urllib2 at the top of the module because
-            # it may fail due to broken SSL dependencies, and it takes
-            # about 0.15 seconds to load.
-            import urllib.request, urllib.error, urllib.parse
             source = self.options['url']
             try:
-                csv_text = urllib.request.urlopen(source).read()
-            except (urllib.error.URLError, IOError, OSError, ValueError) as error:
-                severe = self.state_machine.reporter.severe(
+                with urlopen(source) as response:
+                    csv_text = response.read()
+            except (URLError, OSError, ValueError) as error:
+                severe = self.reporter.severe(
                       'Problems with "%s" directive URL "%s":\n%s.'
-                      % (self.name, self.options['url'], SafeString(error)),
+                      % (self.name, self.options['url'], error),
                       nodes.literal_block(self.block_text, self.block_text),
                       line=self.lineno)
                 raise SystemMessagePropagation(severe)
-            csv_file = io.StringInput(
-                source=csv_text, source_path=source, encoding=encoding,
-                error_handler=(self.state.document.settings.\
-                               input_encoding_error_handler))
+            csv_file = StringInput(source=csv_text, source_path=source,
+                                   encoding=encoding,
+                                   error_handler=error_handler)
             csv_data = csv_file.read().splitlines()
         else:
-            error = self.state_machine.reporter.warning(
+            error = self.reporter.warning(
                 'The "%s" directive requires content; none supplied.'
-                % self.name, nodes.literal_block(
-                self.block_text, self.block_text), line=self.lineno)
+                % self.name,
+                nodes.literal_block(self.block_text, self.block_text),
+                line=self.lineno)
             raise SystemMessagePropagation(error)
         return csv_data, source
 
-    if sys.version_info < (3,):
-        # 2.x csv module doesn't do Unicode
-        def decode_from_csv(s):
-            return s.decode('utf-8')
-        def encode_for_csv(s):
-            return s.encode('utf-8')
-    else:
-        def decode_from_csv(s):
-            return s
-        def encode_for_csv(s):
-            return s
-    decode_from_csv = staticmethod(decode_from_csv)
-    encode_for_csv = staticmethod(encode_for_csv)
+    @staticmethod
+    def decode_from_csv(s):
+        warnings.warn('CSVTable.decode_from_csv()'
+                  ' is not required with Python 3'
+                  ' and will be removed in Docutils 0.21 or later.',
+                  DeprecationWarning, stacklevel=2)
+        return s
+
+    @staticmethod
+    def encode_for_csv(s):
+        warnings.warn('CSVTable.encode_from_csv()'
+                  ' is not required with Python 3'
+                  ' and will be removed in Docutils 0.21 or later.',
+                  DeprecationWarning, stacklevel=2)
+        return s
 
     def parse_csv_data_into_rows(self, csv_data, dialect, source):
-        # csv.py doesn't do Unicode; encode temporarily as UTF-8
-        csv_reader = csv.reader([self.encode_for_csv(line + '\n')
-                                 for line in csv_data],
+        csv_reader = csv.reader((line + '\n' for line in csv_data),
                                 dialect=dialect)
         rows = []
         max_cols = 0
         for row in csv_reader:
             row_data = []
             for cell in row:
-                # decode UTF-8 back to Unicode
-                cell_text = self.decode_from_csv(cell)
                 cell_data = (0, 0, 0, statemachine.StringList(
-                    cell_text.splitlines(), source=source))
+                    cell.splitlines(), source=source))
                 row_data.append(cell_data)
             rows.append(row_data)
             max_cols = max(max_cols, len(row))
@@ -354,19 +423,22 @@ class ListTable(Table):
     """
     Implement tables whose data is encoded as a uniform two-level bullet list.
     For further ideas, see
-    http://docutils.sf.net/docs/dev/rst/alternatives.html#list-driven-tables
-    """ 
+    https://docutils.sourceforge.io/docs/dev/rst/alternatives.html#list-driven-tables
+    """
 
     option_spec = {'header-rows': directives.nonnegative_int,
                    'stub-columns': directives.nonnegative_int,
-                   'widths': directives.positive_int_list,
+                   'width': directives.length_or_percentage_or_unitless,
+                   'widths': directives.value_or(('auto', ),
+                                                 directives.positive_int_list),
                    'class': directives.class_option,
-                   'name': directives.unchanged}
+                   'name': directives.unchanged,
+                   'align': align}
 
     def run(self):
         if not self.content:
-            error = self.state_machine.reporter.error(
-                'The "%s" directive is empty; content required.' % self.name,
+            error = self.reporter.error('The "%s" directive is empty; '
+                'content required.' % self.name,
                 nodes.literal_block(self.block_text, self.block_text),
                 line=self.lineno)
             return [error]
@@ -384,7 +456,10 @@ class ListTable(Table):
             return [detail.args[0]]
         table_node = self.build_table_from_list(table_data, col_widths,
                                                 header_rows, stub_columns)
+        if 'align' in self.options:
+            table_node['align'] = self.options.get('align')
         table_node['classes'] += self.options.get('class', [])
+        self.set_table_width(table_node)
         self.add_name(table_node)
         if title:
             table_node.insert(0, title)
@@ -392,30 +467,29 @@ class ListTable(Table):
 
     def check_list_content(self, node):
         if len(node) != 1 or not isinstance(node[0], nodes.bullet_list):
-            error = self.state_machine.reporter.error(
+            error = self.reporter.error(
                 'Error parsing content block for the "%s" directive: '
                 'exactly one bullet list expected.' % self.name,
                 nodes.literal_block(self.block_text, self.block_text),
                 line=self.lineno)
             raise SystemMessagePropagation(error)
         list_node = node[0]
+        num_cols = 0
         # Check for a uniform two-level bullet list:
         for item_index in range(len(list_node)):
             item = list_node[item_index]
             if len(item) != 1 or not isinstance(item[0], nodes.bullet_list):
-                error = self.state_machine.reporter.error(
+                error = self.reporter.error(
                     'Error parsing content block for the "%s" directive: '
                     'two-level bullet list expected, but row %s does not '
                     'contain a second-level bullet list.'
-                    % (self.name, item_index + 1), nodes.literal_block(
-                    self.block_text, self.block_text), line=self.lineno)
+                    % (self.name, item_index + 1),
+                    nodes.literal_block(self.block_text, self.block_text),
+                    line=self.lineno)
                 raise SystemMessagePropagation(error)
             elif item_index:
-                # ATTN pychecker users: num_cols is guaranteed to be set in the
-                # "else" clause below for item_index==0, before this branch is
-                # triggered.
                 if len(item[0]) != num_cols:
-                    error = self.state_machine.reporter.error(
+                    error = self.reporter.error(
                         'Error parsing content block for the "%s" directive: '
                         'uniform two-level bullet list expected, but row %s '
                         'does not contain the same number of items as row 1 '
@@ -429,12 +503,19 @@ class ListTable(Table):
         col_widths = self.get_column_widths(num_cols)
         return num_cols, col_widths
 
-    def build_table_from_list(self, table_data, col_widths, header_rows, stub_columns):
+    def build_table_from_list(self, table_data,
+                              col_widths, header_rows, stub_columns):
         table = nodes.table()
+        if self.widths == 'auto':
+            table['classes'] += ['colwidths-auto']
+        elif self.widths:  # explicitly set column widths
+            table['classes'] += ['colwidths-given']
         tgroup = nodes.tgroup(cols=len(col_widths))
         table += tgroup
         for col_width in col_widths:
-            colspec = nodes.colspec(colwidth=col_width)
+            colspec = nodes.colspec()
+            if col_width is not None:
+                colspec.attributes['colwidth'] = col_width
             if stub_columns:
                 colspec.attributes['stub'] = 1
                 stub_columns -= 1

python/helpers/py3only/docutils/parsers/rst/include/README.txt

@@ -10,8 +10,8 @@ angle brackets around the file name::
     .. include:: <isonum.txt>
 
 See the documentation for the `"include" directive`__ and
-`reStructuredText Standard Substitution Definition Sets`__ for
+`reStructuredText Standard Definition Files`__ for
 details.
 
-__ http://docutils.sf.net/docs/ref/rst/directives.html#include
-__ http://docutils.sf.net/docs/ref/rst/substitutions.html
+__ https://docutils.sourceforge.io/docs/ref/rst/directives.html#include
+__ https://docutils.sourceforge.io/docs/ref/rst/definitions.html

python/helpers/py3only/docutils/parsers/rst/include/isoamsa.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |angzarr|  unicode:: U+0237C .. RIGHT ANGLE WITH DOWNWARDS ZIGZAG ARROW
 .. |cirmid|   unicode:: U+02AEF .. VERTICAL LINE WITH CIRCLE ABOVE

python/helpers/py3only/docutils/parsers/rst/include/isoamsb.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |ac|       unicode:: U+0223E .. INVERTED LAZY S
 .. |acE|      unicode:: U+0223E U+00333 .. INVERTED LAZY S with double underline

python/helpers/py3only/docutils/parsers/rst/include/isoamsc.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |dlcorn|  unicode:: U+0231E .. BOTTOM LEFT CORNER
 .. |drcorn|  unicode:: U+0231F .. BOTTOM RIGHT CORNER

python/helpers/py3only/docutils/parsers/rst/include/isoamsn.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |gnap|     unicode:: U+02A8A .. GREATER-THAN AND NOT APPROXIMATE
 .. |gnE|      unicode:: U+02269 .. GREATER-THAN BUT NOT EQUAL TO

python/helpers/py3only/docutils/parsers/rst/include/isoamso.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |ang|      unicode:: U+02220 .. ANGLE
 .. |ange|     unicode:: U+029A4 .. ANGLE WITH UNDERBAR

python/helpers/py3only/docutils/parsers/rst/include/isoamsr.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |apE|      unicode:: U+02A70 .. APPROXIMATELY EQUAL OR EQUAL TO
 .. |ape|      unicode:: U+0224A .. ALMOST EQUAL OR EQUAL TO

python/helpers/py3only/docutils/parsers/rst/include/isobox.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |boxDL| unicode:: U+02557 .. BOX DRAWINGS DOUBLE DOWN AND LEFT
 .. |boxDl| unicode:: U+02556 .. BOX DRAWINGS DOWN DOUBLE AND LEFT SINGLE

python/helpers/py3only/docutils/parsers/rst/include/isocyr1.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |Acy|    unicode:: U+00410 .. CYRILLIC CAPITAL LETTER A
 .. |acy|    unicode:: U+00430 .. CYRILLIC SMALL LETTER A

python/helpers/py3only/docutils/parsers/rst/include/isocyr2.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |DJcy|   unicode:: U+00402 .. CYRILLIC CAPITAL LETTER DJE
 .. |djcy|   unicode:: U+00452 .. CYRILLIC SMALL LETTER DJE

python/helpers/py3only/docutils/parsers/rst/include/isodia.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |acute| unicode:: U+000B4 .. ACUTE ACCENT
 .. |breve| unicode:: U+002D8 .. BREVE

python/helpers/py3only/docutils/parsers/rst/include/isogrk1.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |Agr|  unicode:: U+00391 .. GREEK CAPITAL LETTER ALPHA
 .. |agr|  unicode:: U+003B1 .. GREEK SMALL LETTER ALPHA

python/helpers/py3only/docutils/parsers/rst/include/isogrk2.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |Aacgr|  unicode:: U+00386 .. GREEK CAPITAL LETTER ALPHA WITH TONOS
 .. |aacgr|  unicode:: U+003AC .. GREEK SMALL LETTER ALPHA WITH TONOS

python/helpers/py3only/docutils/parsers/rst/include/isogrk3.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |alpha|  unicode:: U+003B1 .. GREEK SMALL LETTER ALPHA
 .. |beta|   unicode:: U+003B2 .. GREEK SMALL LETTER BETA

python/helpers/py3only/docutils/parsers/rst/include/isogrk4-wide.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |b.alpha|  unicode:: U+1D6C2 .. MATHEMATICAL BOLD SMALL ALPHA
 .. |b.beta|   unicode:: U+1D6C3 .. MATHEMATICAL BOLD SMALL BETA

python/helpers/py3only/docutils/parsers/rst/include/isogrk4.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |b.Gammad| unicode:: U+003DC .. GREEK LETTER DIGAMMA
 .. |b.gammad| unicode:: U+003DD .. GREEK SMALL LETTER DIGAMMA

python/helpers/py3only/docutils/parsers/rst/include/isolat1.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |Aacute| unicode:: U+000C1 .. LATIN CAPITAL LETTER A WITH ACUTE
 .. |aacute| unicode:: U+000E1 .. LATIN SMALL LETTER A WITH ACUTE

python/helpers/py3only/docutils/parsers/rst/include/isolat2.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |Abreve| unicode:: U+00102 .. LATIN CAPITAL LETTER A WITH BREVE
 .. |abreve| unicode:: U+00103 .. LATIN SMALL LETTER A WITH BREVE

python/helpers/py3only/docutils/parsers/rst/include/isomfrk-wide.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |Afr| unicode:: U+1D504 .. MATHEMATICAL FRAKTUR CAPITAL A
 .. |afr| unicode:: U+1D51E .. MATHEMATICAL FRAKTUR SMALL A

python/helpers/py3only/docutils/parsers/rst/include/isomfrk.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |Cfr| unicode:: U+0212D .. BLACK-LETTER CAPITAL C
 .. |Hfr| unicode:: U+0210C .. BLACK-LETTER CAPITAL H

python/helpers/py3only/docutils/parsers/rst/include/isomopf-wide.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |Aopf| unicode:: U+1D538 .. MATHEMATICAL DOUBLE-STRUCK CAPITAL A
 .. |Bopf| unicode:: U+1D539 .. MATHEMATICAL DOUBLE-STRUCK CAPITAL B

python/helpers/py3only/docutils/parsers/rst/include/isomopf.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |Copf| unicode:: U+02102 .. DOUBLE-STRUCK CAPITAL C
 .. |Hopf| unicode:: U+0210D .. DOUBLE-STRUCK CAPITAL H

python/helpers/py3only/docutils/parsers/rst/include/isomscr-wide.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |Ascr| unicode:: U+1D49C .. MATHEMATICAL SCRIPT CAPITAL A
 .. |ascr| unicode:: U+1D4B6 .. MATHEMATICAL SCRIPT SMALL A

python/helpers/py3only/docutils/parsers/rst/include/isomscr.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |Bscr| unicode:: U+0212C .. SCRIPT CAPITAL B
 .. |Escr| unicode:: U+02130 .. SCRIPT CAPITAL E

python/helpers/py3only/docutils/parsers/rst/include/isonum.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |amp|    unicode:: U+00026 .. AMPERSAND
 .. |apos|   unicode:: U+00027 .. APOSTROPHE

python/helpers/py3only/docutils/parsers/rst/include/isopub.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |blank|  unicode:: U+02423 .. OPEN BOX
 .. |blk12|  unicode:: U+02592 .. MEDIUM SHADE

python/helpers/py3only/docutils/parsers/rst/include/isotech.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |acd|      unicode:: U+0223F .. SINE WAVE
 .. |aleph|    unicode:: U+02135 .. ALEF SYMBOL

python/helpers/py3only/docutils/parsers/rst/include/mmlalias.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |angle|                           unicode:: U+02220 .. ANGLE
 .. |ApplyFunction|                   unicode:: U+02061 .. FUNCTION APPLICATION

python/helpers/py3only/docutils/parsers/rst/include/mmlextra-wide.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |af|                      unicode:: U+02061 .. FUNCTION APPLICATION
 .. |aopf|                    unicode:: U+1D552 .. MATHEMATICAL DOUBLE-STRUCK SMALL A

python/helpers/py3only/docutils/parsers/rst/include/mmlextra.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |af|                      unicode:: U+02061 .. FUNCTION APPLICATION
 .. |asympeq|                 unicode:: U+0224D .. EQUIVALENT TO

python/helpers/py3only/docutils/parsers/rst/include/xhtml1-lat1.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |Aacute| unicode:: U+000C1 .. LATIN CAPITAL LETTER A WITH ACUTE
 .. |aacute| unicode:: U+000E1 .. LATIN SMALL LETTER A WITH ACUTE

python/helpers/py3only/docutils/parsers/rst/include/xhtml1-special.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |bdquo|  unicode:: U+0201E .. DOUBLE LOW-9 QUOTATION MARK
 .. |circ|   unicode:: U+002C6 .. MODIFIER LETTER CIRCUMFLEX ACCENT

python/helpers/py3only/docutils/parsers/rst/include/xhtml1-symbol.txt

@@ -2,7 +2,7 @@
 .. Derived from the Unicode character mappings available from
    <http://www.w3.org/2003/entities/xml/>.
    Processed by unicode2rstsubs.py, part of Docutils:
-   <http://docutils.sourceforge.net>.
+   <https://docutils.sourceforge.io>.
 
 .. |alefsym|  unicode:: U+02135 .. ALEF SYMBOL
 .. |Alpha|    unicode:: U+00391 .. GREEK CAPITAL LETTER ALPHA

python/helpers/py3only/docutils/parsers/rst/languages/__init__.py

@@ -1,9 +1,9 @@
-# $Id: __init__.py 7648 2013-04-18 07:36:22Z milde $
+# $Id: __init__.py 9026 2022-03-04 15:57:13Z milde $
 # Author: David Goodger <goodger@python.org>
 # Copyright: This module has been placed in the public domain.
 
 # Internationalization details are documented in
-# <http://docutils.sf.net/docs/howto/i18n.html>.
+# <https://docutils.sourceforge.io/docs/howto/i18n.html>.
 
 """
 This package contains modules for language-dependent features of
@@ -12,26 +12,29 @@ reStructuredText.
 
 __docformat__ = 'reStructuredText'
 
-import sys
 
-from docutils.utils import normalize_language_tag
-if sys.version_info < (2,5):
-    from docutils._compat import __import__
+from docutils.languages import LanguageImporter
 
-_languages = {}
 
-def get_language(language_code):
-    for tag in normalize_language_tag(language_code):
-        tag = tag.replace('-','_') # '-' not valid in module names
-        if tag in _languages:
-            return _languages[tag]
-        try:
-            module = __import__(tag, globals(), locals(), level=1)
-        except ImportError:
-            try:
-                module = __import__(tag, globals(), locals(), level=0)
-            except ImportError:
-                continue
-        _languages[tag] = module
-        return module
-    return None
+class RstLanguageImporter(LanguageImporter):
+    """Import language modules.
+
+    When called with a BCP 47 language tag, instances return a module
+    with localisations for "directive" and "role" names for  from
+    `docutils.parsers.rst.languages` or the PYTHONPATH.
+
+    If there is no matching module, warn (if a `reporter` is passed)
+    and return None.
+    """
+    packages = ('docutils.parsers.rst.languages.', '')
+    warn_msg = 'rST localisation for language "%s" not found.'
+    fallback = None
+
+    def check_content(self, module):
+        """Check if we got an rST language module."""
+        if not (isinstance(module.directives, dict)
+                and isinstance(module.roles, dict)):
+            raise ImportError
+
+
+get_language = RstLanguageImporter()

python/helpers/py3only/docutils/parsers/rst/languages/af.py

@@ -1,11 +1,11 @@
-# $Id: af.py 7119 2011-09-02 13:00:23Z milde $
+# $Id: af.py 9417 2023-06-27 20:04:54Z milde $
 # Author: Jannie Hofmeyr <jhsh@sun.ac.za>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Afrikaans-language mappings for language-dependent features of
@@ -24,9 +24,10 @@ directives = {
       'wenk': 'hint',
       'belangrik': 'important',
       'nota': 'note',
-      'tip': 'tip', # hint and tip both have the same translation: wenk
+      'tip': 'tip',  # hint and tip both have the same translation: wenk
       'waarskuwing': 'warning',
-      'vermaning': 'admonition',
+      'advies': 'admonition',
+      'vermaning': 'admonition',  # sic! kept for backwards compatibiltity
       'kantstreep': 'sidebar',
       'onderwerp': 'topic',
       'lynblok': 'line-block',
@@ -38,20 +39,20 @@ directives = {
       'pull-quote (translation required)': 'pull-quote',
       'compound (translation required)': 'compound',
       'container (translation required)': 'container',
-      #'vrae': 'questions',
-      #'qa': 'questions',
-      #'faq': 'questions',
+      # 'vrae': 'questions',
+      # 'qa': 'questions',
+      # 'faq': 'questions',
       'table (translation required)': 'table',
       'csv-table (translation required)': 'csv-table',
       'list-table (translation required)': 'list-table',
       'meta': 'meta',
-      #'beeldkaart': 'imagemap',
+      # 'beeldkaart': 'imagemap',
       'beeld': 'image',
       'figuur': 'figure',
       'insluiting': 'include',
       'rou': 'raw',
       'vervang': 'replace',
-      'unicode': 'unicode', # should this be translated? unikode
+      'unicode': 'unicode',  # should this be translated? unikode
       'datum': 'date',
       'klas': 'class',
       'role (translation required)': 'role',
@@ -62,8 +63,8 @@ directives = {
       'section-numbering': 'sectnum',
       'header (translation required)': 'header',
       'footer (translation required)': 'footer',
-      #'voetnote': 'footnotes',
-      #'aanhalings': 'citations',
+      # 'voetnote': 'footnotes',
+      # 'aanhalings': 'citations',
       'teikennotas': 'target-notes',
       'restructuredtext-test-directive': 'restructuredtext-test-directive'}
 """Afrikaans name to registered (in directives/__init__.py) directive name
@@ -101,6 +102,7 @@ roles = {
     'uri-verwysing': 'uri-reference',
     'uri': 'uri-reference',
     'url': 'uri-reference',
-    'rou': 'raw',}
-"""Mapping of Afrikaans role names to canonical role names for interpreted text.
+    'rou': 'raw',
+    }
+"""Mapping of Afrikaans role names to canonical names for interpreted text.
 """

python/helpers/py3only/docutils/parsers/rst/languages/ar.py

@@ -0,0 +1,99 @@
+# $Id: fa.py 4564 2016-08-10 11:48:42Z
+# Author: Shahin <me@5hah.in>
+# Copyright: This module has been placed in the public domain.
+
+# New language mappings are welcome.  Before doing a new translation, please
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
+
+"""
+Arabic-language mappings for language-dependent features of
+reStructuredText.
+"""
+
+__docformat__ = 'reStructuredText'
+
+directives = {
+    # language-dependent: fixed
+    'تنبيه': 'attention',
+    'احتیاط': 'caution',
+    'كود': 'code',
+    'خطر': 'danger',
+    'خطأ': 'error',
+    'تلميح': 'hint',
+    'مهم': 'important',
+    'ملاحظة': 'note',
+    'نصيحة': 'tip',
+    'تحذير': 'warning',
+    'تذكير': 'admonition',
+    'شريط-جانبي': 'sidebar',
+    'موضوع': 'topic',
+    'قالب-سطري': 'line-block',
+    'لفظ-حرفي': 'parsed-literal',
+    'معيار': 'rubric',
+    'فكرة-الكتاب': 'epigraph',
+    'تمييز': 'highlights',
+    'نقل-قول': 'pull-quote',
+    'ترکیب': 'compound',
+    'وعاء': 'container',
+    # 'questions': 'questions',
+    'جدول': 'table',
+    'جدول-csv': 'csv-table',
+    'جدول-قوائم': 'list-table',
+    # 'qa': 'questions',
+    # 'faq': 'questions',
+    'ميتا': 'meta',
+    'رياضيات': 'math',
+    # 'imagemap': 'imagemap',
+    'صورة': 'image',
+    'رسم-توضيحي': 'figure',
+    'تضمين': 'include',
+    'خام': 'raw',
+    'تبديل': 'replace',
+    'یونیکد': 'unicode',
+    'تاریخ': 'date',
+    'كائن': 'class',
+    'قانون': 'role',
+    'قانون-افتراضي': 'default-role',
+    'عنوان': 'title',
+    'المحتوى': 'contents',
+    'رقم-الفصل': 'sectnum',
+    'رقم-القسم': 'sectnum',
+    'رأس-الصفحة': 'header',
+    'هامش': 'footer',
+    # 'footnotes': 'footnotes',
+    # 'citations': 'citations',
+    '': 'target-notes',
+}
+"""Arabic name to registered (in directives/__init__.py) directive name
+mapping."""
+
+roles = {
+    # language-dependent: fixed
+    'اختصار': 'abbreviation',
+    'اختزال': 'acronym',
+    'كود': 'code',
+    'فهرس': 'index',
+    'خفض': 'subscript',
+    'رفع': 'superscript',
+    'عنوان-مرجع': 'title-reference',
+    'مرجع-pep': 'pep-reference',
+    'rfc-مرجع': 'rfc-reference',
+    'تأكيد': 'emphasis',
+    'عريض': 'strong',
+    'لفظی': 'literal',
+    'رياضيات': 'math',
+    'مرجع-مسمى': 'named-reference',
+    'مرجع-مجهول': 'anonymous-reference',
+    'مرجع-هامشي': 'footnote-reference',
+    'مرجع-منقول': 'citation-reference',
+    'مرجع-معوض': 'substitution-reference',
+    'هدف': 'target',
+    'منبع-uri': 'uri-reference',
+    'uri': 'uri-reference',
+    'url': 'uri-reference',
+    'خام': 'raw',
+}
+"""Mapping of Arabic role names to canonical role names for interpreted text.
+"""

python/helpers/py3only/docutils/parsers/rst/languages/ca.py

@@ -1,11 +1,16 @@
-# $Id: ca.py 7119 2011-09-02 13:00:23Z milde $
-# Author: Ivan Vilata i Balaguer <ivan@selidor.net>
+# $Id: ca.py 9457 2023-10-02 16:25:50Z milde $
+# Authors: Ivan Vilata i Balaguer <ivan@selidor.net>;
+#          Antoni Bella Pérez <antonibella5@yahoo.com>
 # Copyright: This module has been placed in the public domain.
 
-# New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# New language mappings are welcome.  Before doing a new translation,
+# please read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
+
+# These translations can be used without changes for
+# Valencian variant of Catalan (use language tag "ca-valencia").
+# Checked by a native speaker of Valentian.
 
 """
 Catalan-language mappings for language-dependent features of
@@ -17,109 +22,109 @@ __docformat__ = 'reStructuredText'
 
 directives = {
       # language-dependent: fixed
-      'atenci\u00F3': 'attention',
+      'atenció': 'attention',
       'compte': 'caution',
-      'code (translation required)': 'code',
       'perill': 'danger',
       'error': 'error',
       'suggeriment': 'hint',
       'important': 'important',
       'nota': 'note',
       'consell': 'tip',
-      'av\u00EDs': 'warning',
+      'avís': 'warning',
       'advertiment': 'admonition',
       'nota-al-marge': 'sidebar',
       'nota-marge': 'sidebar',
       'tema': 'topic',
-      'bloc-de-l\u00EDnies': 'line-block',
-      'bloc-l\u00EDnies': 'line-block',
+      'bloc-de-línies': 'line-block',
+      'bloc-línies': 'line-block',
       'literal-analitzat': 'parsed-literal',
-      'r\u00FAbrica': 'rubric',
-      'ep\u00EDgraf': 'epigraph',
+      'codi': 'code',
+      'bloc-de-codi': 'code',
+      'matemàtiques': 'math',
+      'rúbrica': 'rubric',
+      'epígraf': 'epigraph',
       'sumari': 'highlights',
       'cita-destacada': 'pull-quote',
       'compost': 'compound',
-      'container (translation required)': 'container',
-      #'questions': 'questions',
+      'contenidor': 'container',
       'taula': 'table',
       'taula-csv': 'csv-table',
       'taula-llista': 'list-table',
-      #'qa': 'questions',
-      #'faq': 'questions',
-      'math (translation required)': 'math',
       'meta': 'meta',
-      #'imagemap': 'imagemap',
+      # 'imagemap': 'imagemap',
       'imatge': 'image',
       'figura': 'figure',
       'inclou': 'include',
       'incloure': 'include',
       'cru': 'raw',
-      'reempla\u00E7a': 'replace',
-      'reempla\u00E7ar': 'replace',
+      'reemplaça': 'replace',
+      'reemplaçar': 'replace',
       'unicode': 'unicode',
       'data': 'date',
       'classe': 'class',
       'rol': 'role',
-      'default-role (translation required)': 'default-role',
-      'title (translation required)': 'title',
+      'rol-predeterminat': 'default-role',
+      'títol': 'title',
       'contingut': 'contents',
       'numsec': 'sectnum',
-      'numeraci\u00F3-de-seccions': 'sectnum',
-      'numeraci\u00F3-seccions': 'sectnum',
-      'cap\u00E7alera': 'header',
-      'peu-de-p\u00E0gina': 'footer',
-      'peu-p\u00E0gina': 'footer',
-      #'footnotes': 'footnotes',
-      #'citations': 'citations',
+      'numeració-de-seccions': 'sectnum',
+      'numeració-seccions': 'sectnum',
+      'capçalera': 'header',
+      'peu-de-pàgina': 'footer',
+      'peu-pàgina': 'footer',
+      # 'footnotes': 'footnotes',
+      # 'citations': 'citations',
       'notes-amb-destinacions': 'target-notes',
       'notes-destinacions': 'target-notes',
-      'directiva-de-prova-de-restructuredtext': 'restructuredtext-test-directive'}
+      'directiva-de-prova-de-restructuredtext': 'restructuredtext-test-directive'}  # noqa:E501
 """Catalan name to registered (in directives/__init__.py) directive name
 mapping."""
 
 roles = {
     # language-dependent: fixed
     'abreviatura': 'abbreviation',
-    'abreviaci\u00F3': 'abbreviation',
+    'abreviació': 'abbreviation',
     'abrev': 'abbreviation',
     'ab': 'abbreviation',
-    'acr\u00F2nim': 'acronym',
+    'acrònim': 'acronym',
     'ac': 'acronym',
-    'code (translation required)': 'code',
-    '\u00EDndex': 'index',
-    'i': 'index',
-    'sub\u00EDndex': 'subscript',
-    'sub': 'subscript',
-    'super\u00EDndex': 'superscript',
-    'sup': 'superscript',
-    'refer\u00E8ncia-a-t\u00EDtol': 'title-reference',
-    'refer\u00E8ncia-t\u00EDtol': 'title-reference',
-    't\u00EDtol': 'title-reference',
-    't': 'title-reference',
-    'refer\u00E8ncia-a-pep': 'pep-reference',
-    'refer\u00E8ncia-pep': 'pep-reference',
-    'pep': 'pep-reference',
-    'refer\u00E8ncia-a-rfc': 'rfc-reference',
-    'refer\u00E8ncia-rfc': 'rfc-reference',
-    'rfc': 'rfc-reference',
-    '\u00E8mfasi': 'emphasis',
-    'destacat': 'strong',
+    'codi': 'code',
+    'èmfasi': 'emphasis',
     'literal': 'literal',
-    'math (translation required)': 'math',
-    'refer\u00E8ncia-amb-nom': 'named-reference',
-    'refer\u00E8ncia-nom': 'named-reference',
-    'refer\u00E8ncia-an\u00F2nima': 'anonymous-reference',
-    'refer\u00E8ncia-a-nota-al-peu': 'footnote-reference',
-    'refer\u00E8ncia-nota-al-peu': 'footnote-reference',
-    'refer\u00E8ncia-a-cita': 'citation-reference',
-    'refer\u00E8ncia-cita': 'citation-reference',
-    'refer\u00E8ncia-a-substituci\u00F3': 'substitution-reference',
-    'refer\u00E8ncia-substituci\u00F3': 'substitution-reference',
-    'destinaci\u00F3': 'target',
-    'refer\u00E8ncia-a-uri': 'uri-reference',
-    'refer\u00E8ncia-uri': 'uri-reference',
+    'matemàtiques': 'math',
+    'referència-a-pep': 'pep-reference',
+    'referència-pep': 'pep-reference',
+    'pep': 'pep-reference',
+    'referència-a-rfc': 'rfc-reference',
+    'referència-rfc': 'rfc-reference',
+    'rfc': 'rfc-reference',
+    'destacat': 'strong',
+    'subíndex': 'subscript',
+    'sub': 'subscript',
+    'superíndex': 'superscript',
+    'sup': 'superscript',
+    'referència-a-títol': 'title-reference',
+    'referència-títol': 'title-reference',
+    'títol': 'title-reference',
+    't': 'title-reference',
+    'cru': 'raw',
+    # the following roles are not implemented in Docutils
+    'índex': 'index',
+    'i': 'index',
+    'referència-anònima': 'anonymous-reference',
+    'referència-a-cita': 'citation-reference',
+    'referència-cita': 'citation-reference',
+    'referència-a-nota-al-peu': 'footnote-reference',
+    'referència-nota-al-peu': 'footnote-reference',
+    'referència-amb-nom': 'named-reference',
+    'referència-nom': 'named-reference',
+    'referència-a-substitució': 'substitution-reference',
+    'referència-substitució': 'substitution-reference',
+    'referència-a-uri': 'uri-reference',
+    'referència-uri': 'uri-reference',
     'uri': 'uri-reference',
     'url': 'uri-reference',
-    'cru': 'raw',}
+    'destinació': 'target',
+    }
 """Mapping of Catalan role names to canonical role names for interpreted text.
 """

python/helpers/py3only/docutils/parsers/rst/languages/cs.py

@@ -1,11 +1,11 @@
-# $Id: cs.py 7119 2011-09-02 13:00:23Z milde $
+# $Id: cs.py 9452 2023-09-27 00:11:54Z milde $
 # Author: Marek Blaha <mb@dat.cz>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Czech-language mappings for language-dependent features of
@@ -18,43 +18,44 @@ __docformat__ = 'reStructuredText'
 directives = {
       # language-dependent: fixed
       'pozor': 'attention',
-      'caution (translation required)': 'caution', # jak rozlisit caution a warning?
+      # jak rozlisit caution a warning?
+      'caution (translation required)': 'caution',
       'code (translation required)': 'code',
-      'nebezpe\u010D\u00ED': 'danger',
+      'nebezpečí': 'danger',
       'chyba': 'error',
       'rada': 'hint',
-      'd\u016Fle\u017Eit\u00E9': 'important',
-      'pozn\u00E1mka': 'note',
+      'důležité': 'important',
+      'poznámka': 'note',
       'tip (translation required)': 'tip',
-      'varov\u00E1n\u00ED': 'warning',
+      'varování': 'warning',
       'admonition (translation required)': 'admonition',
       'sidebar (translation required)': 'sidebar',
-      't\u00E9ma': 'topic',
+      'téma': 'topic',
       'line-block (translation required)': 'line-block',
       'parsed-literal (translation required)': 'parsed-literal',
-      'odd\u00EDl': 'rubric',
+      'oddíl': 'rubric',
       'moto': 'epigraph',
       'highlights (translation required)': 'highlights',
       'pull-quote (translation required)': 'pull-quote',
       'compound (translation required)': 'compound',
       'container (translation required)': 'container',
-      #'questions': 'questions',
-      #'qa': 'questions',
-      #'faq': 'questions',
+      # 'questions': 'questions',
+      # 'qa': 'questions',
+      # 'faq': 'questions',
       'table (translation required)': 'table',
       'csv-table (translation required)': 'csv-table',
       'list-table (translation required)': 'list-table',
       'math (translation required)': 'math',
       'meta (translation required)': 'meta',
-      #'imagemap': 'imagemap',
-      'image (translation required)': 'image',   # obrazek
-      'figure (translation required)': 'figure', # a tady?
+      # 'imagemap': 'imagemap',
+      'image (translation required)': 'image',    # obrazek
+      'figure (translation required)': 'figure',  # a tady?
       'include (translation required)': 'include',
       'raw (translation required)': 'raw',
       'replace (translation required)': 'replace',
       'unicode (translation required)': 'unicode',
       'datum': 'date',
-      't\u0159\u00EDda': 'class',
+      'třída': 'class',
       'role (translation required)': 'role',
       'default-role (translation required)': 'default-role',
       'title (translation required)': 'title',
@@ -63,8 +64,8 @@ directives = {
       'section-numbering (translation required)': 'sectnum',
       'header (translation required)': 'header',
       'footer (translation required)': 'footer',
-      #'footnotes': 'footnotes',
-      #'citations': 'citations',
+      # 'footnotes': 'footnotes',
+      # 'citations': 'citations',
       'target-notes (translation required)': 'target-notes',
       'restructuredtext-test-directive': 'restructuredtext-test-directive'}
 """Czech name to registered (in directives/__init__.py) directive name
@@ -103,6 +104,7 @@ roles = {
     'uri-reference (translation required)': 'uri-reference',
     'uri (translation required)': 'uri-reference',
     'url (translation required)': 'uri-reference',
-    'raw (translation required)': 'raw',}
+    'raw (translation required)': 'raw',
+    }
 """Mapping of Czech role names to canonical role names for interpreted text.
 """

python/helpers/py3only/docutils/parsers/rst/languages/da.py

@@ -1,12 +1,11 @@
-# -*- coding: utf-8 -*-
-# $Id: da.py 7678 2013-07-03 09:57:36Z milde $
+# $Id: da.py 9417 2023-06-27 20:04:54Z milde $
 # Author: E D
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Danish-language mappings for language-dependent features of
@@ -30,7 +29,8 @@ directives = {
       'bemærk': 'note',
       'tips': 'tip',
       'advarsel': 'warning',
-      'formaning': 'admonition',
+      'varsel': 'admonition',
+      'formaning': 'admonition',  # sic! kept for backwards compatibiltity
       'sidebjælke': 'sidebar',
       'emne': 'topic',
       'linje-blok': 'line-block',
@@ -42,15 +42,15 @@ directives = {
       'pull-quote (translation required)': 'pull-quote',
       'compound (translation required)': 'compound',
       'container (translation required)': 'container',
-      #'questions': 'questions',
+      # 'questions': 'questions',
       'tabel': 'table',
       'csv-tabel': 'csv-table',
       'liste-tabel': 'list-table',
-      #'qa': 'questions',
-      #'faq': 'questions',
+      # 'qa': 'questions',
+      # 'faq': 'questions',
       'meta': 'meta',
       'math (translation required)': 'math',
-      #'imagemap': 'imagemap',
+      # 'imagemap': 'imagemap',
       'billede': 'image',
       'figur': 'figure',
       'inkludér': 'include',
@@ -68,8 +68,8 @@ directives = {
       'sektions-nummerering': 'sectnum',
       'sidehovede': 'header',
       'sidefod': 'footer',
-      #'footnotes': 'footnotes',
-      #'citations': 'citations',
+      # 'footnotes': 'footnotes',
+      # 'citations': 'citations',
       'target-notes (translation required)': 'target-notes',
       'restructuredtext-test-direktiv': 'restructuredtext-test-directive'}
 """Danish name to registered (in directives/__init__.py) directive name
@@ -108,6 +108,7 @@ roles = {
     'uri-reference': 'uri-reference',
     'uri': 'uri-reference',
     'url': 'uri-reference',
-    'rå': 'raw',}
+    'rå': 'raw',
+    }
 """Mapping of Danish role names to canonical role names for interpreted text.
 """

python/helpers/py3only/docutils/parsers/rst/languages/de.py

@@ -1,13 +1,12 @@
-# -*- coding: utf-8 -*-
-# $Id: de.py 7223 2011-11-21 16:43:06Z milde $
+# $Id: de.py 9428 2023-07-07 06:50:26Z milde $
 # Authors: Engelbert Gruber <grubert@users.sourceforge.net>;
 #          Lea Wiemann <LeWiemann@gmail.com>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 German-language mappings for language-dependent features of
@@ -18,38 +17,41 @@ __docformat__ = 'reStructuredText'
 
 
 directives = {
+      'warnhinweis': 'admonition',  # or, more generally, 'anmerkung'?
+      'ermahnung': 'admonition',  # sic! kept for backwards compatibiltity
       'achtung': 'attention',
       'vorsicht': 'caution',
       'code': 'code',
       'gefahr': 'danger',
       'fehler': 'error',
-      'hinweis': 'hint',
+      'hinweis': 'hint',  # Wink
       'wichtig': 'important',
       'notiz': 'note',
       'tipp': 'tip',
       'warnung': 'warning',
-      'ermahnung': 'admonition',
       'kasten': 'sidebar',
-      'seitenkasten': 'sidebar',
+      'seitenkasten': 'sidebar',  # kept for backwards compatibiltity
+      'seitenleiste': 'sidebar',
       'thema': 'topic',
-      'zeilen-block': 'line-block',
+      'zeilenblock': 'line-block',
       'parsed-literal (translation required)': 'parsed-literal',
       'rubrik': 'rubric',
       'epigraph': 'epigraph',
-      'highlights (translation required)': 'highlights',
-      'pull-quote': 'pull-quote', # commonly used in German too
-      'seitenansprache': 'pull-quote', # cf. http://www.typografie.info/2/wiki.php?title=Seitenansprache
+      'highlights': 'highlights',
+      'pull-quote': 'pull-quote',  # commonly used in German too
+      'seitenansprache': 'pull-quote',
+      # cf. http://www.typografie.info/2/wiki.php?title=Seitenansprache
       'zusammengesetzt': 'compound',
       'verbund': 'compound',
       'container': 'container',
-      #'fragen': 'questions',
+      # 'fragen': 'questions',
       'tabelle': 'table',
       'csv-tabelle': 'csv-table',
-      'list-table (translation required)': 'list-table',
+      'listentabelle': 'list-table',
       'mathe': 'math',
       'formel': 'math',
       'meta': 'meta',
-      #'imagemap': 'imagemap',
+      # 'imagemap': 'imagemap',
       'bild': 'image',
       'abbildung': 'figure',
       'unverändert': 'raw',
@@ -62,16 +64,16 @@ directives = {
       'datum': 'date',
       'klasse': 'class',
       'rolle': 'role',
-      'default-role (translation required)': 'default-role',
-      'title (translation required)': 'title',
+      'standardrolle': 'default-role',
+      'titel': 'title',
       'inhalt': 'contents',
-      'kapitel-nummerierung': 'sectnum',
-      'abschnitts-nummerierung': 'sectnum',
-      'linkziel-fußfnoten': 'target-notes',
-      'header (translation required)': 'header',
-      'footer (translation required)': 'footer',
-      #u'fußfnoten': 'footnotes',
-      #'zitate': 'citations',
+      'kapitelnummerierung': 'sectnum',
+      'abschnittsnummerierung': 'sectnum',
+      'linkziel-fußnoten': 'target-notes',
+      'kopfzeilen': 'header',
+      'fußzeilen': 'footer',
+      # 'fußnoten': 'footnotes',
+      # 'zitate': 'citations',
       }
 """German name to registered (in directives/__init__.py) directive name
 mapping."""
@@ -86,18 +88,20 @@ roles = {
       'titel-referenz': 'title-reference',
       'pep-referenz': 'pep-reference',
       'rfc-referenz': 'rfc-reference',
-      'betonung': 'emphasis',
+      'betonung': 'emphasis',  # for backwards compatibility
+      'betont': 'emphasis',
       'fett': 'strong',
       'wörtlich': 'literal',
       'mathe': 'math',
       'benannte-referenz': 'named-reference',
       'unbenannte-referenz': 'anonymous-reference',
-      'fußfnoten-referenz': 'footnote-reference',
+      'fußnoten-referenz': 'footnote-reference',
       'zitat-referenz': 'citation-reference',
       'ersetzungs-referenz': 'substitution-reference',
       'ziel': 'target',
       'uri-referenz': 'uri-reference',
       'unverändert': 'raw',
-      'roh': 'raw',}
+      'roh': 'raw',
+      }
 """Mapping of German role names to canonical role names for interpreted text.
 """

python/helpers/py3only/docutils/parsers/rst/languages/en.py

@@ -1,11 +1,11 @@
-# $Id: en.py 7179 2011-10-15 22:06:45Z milde $
+# $Id: en.py 9417 2023-06-27 20:04:54Z milde $
 # Author: David Goodger <goodger@python.org>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 English-language mappings for language-dependent features of
@@ -19,9 +19,6 @@ directives = {
       # language-dependent: fixed
       'attention': 'attention',
       'caution': 'caution',
-      'code': 'code',
-      'code-block': 'code',
-      'sourcecode': 'code',
       'danger': 'danger',
       'error': 'error',
       'hint': 'hint',
@@ -29,26 +26,26 @@ directives = {
       'note': 'note',
       'tip': 'tip',
       'warning': 'warning',
-      'admonition': 'admonition',
+      'admonition': 'admonition',  # advice/advisory/remark, not reprimand
       'sidebar': 'sidebar',
       'topic': 'topic',
       'line-block': 'line-block',
       'parsed-literal': 'parsed-literal',
+      'code': 'code',
+      'code-block': 'code',
+      'sourcecode': 'code',
+      'math': 'math',
       'rubric': 'rubric',
       'epigraph': 'epigraph',
       'highlights': 'highlights',
       'pull-quote': 'pull-quote',
       'compound': 'compound',
       'container': 'container',
-      #'questions': 'questions',
       'table': 'table',
       'csv-table': 'csv-table',
       'list-table': 'list-table',
-      #'qa': 'questions',
-      #'faq': 'questions',
       'meta': 'meta',
-      'math': 'math',
-      #'imagemap': 'imagemap',
+      # 'imagemap': 'imagemap',
       'image': 'image',
       'figure': 'figure',
       'include': 'include',
@@ -65,12 +62,15 @@ directives = {
       'section-numbering': 'sectnum',
       'header': 'header',
       'footer': 'footer',
-      #'footnotes': 'footnotes',
-      #'citations': 'citations',
+      # 'footnotes': 'footnotes',
+      # 'citations': 'citations',
       'target-notes': 'target-notes',
       'restructuredtext-test-directive': 'restructuredtext-test-directive'}
-"""English name to registered (in directives/__init__.py) directive name
-mapping."""
+"""Mapping of English directive name to registered directive names
+
+Cf. https://docutils.sourceforge.io/docs/ref/rst/directives.html
+and `_directive_registry` in ``directives/__init__.py``.
+"""
 
 roles = {
     # language-dependent: fixed
@@ -79,8 +79,14 @@ roles = {
     'acronym': 'acronym',
     'ac': 'acronym',
     'code': 'code',
-    'index': 'index',
-    'i': 'index',
+    'emphasis': 'emphasis',
+    'literal': 'literal',
+    'math': 'math',
+    'pep-reference': 'pep-reference',
+    'pep': 'pep-reference',
+    'rfc-reference': 'rfc-reference',
+    'rfc': 'rfc-reference',
+    'strong': 'strong',
     'subscript': 'subscript',
     'sub': 'subscript',
     'superscript': 'superscript',
@@ -88,23 +94,21 @@ roles = {
     'title-reference': 'title-reference',
     'title': 'title-reference',
     't': 'title-reference',
-    'pep-reference': 'pep-reference',
-    'pep': 'pep-reference',
-    'rfc-reference': 'rfc-reference',
-    'rfc': 'rfc-reference',
-    'emphasis': 'emphasis',
-    'strong': 'strong',
-    'literal': 'literal',
-    'math': 'math',
-    'named-reference': 'named-reference',
+    'raw': 'raw',
+    # the following roles are not implemented in Docutils
+    'index': 'index',
+    'i': 'index',
     'anonymous-reference': 'anonymous-reference',
-    'footnote-reference': 'footnote-reference',
     'citation-reference': 'citation-reference',
+    'footnote-reference': 'footnote-reference',
+    'named-reference': 'named-reference',
     'substitution-reference': 'substitution-reference',
-    'target': 'target',
     'uri-reference': 'uri-reference',
     'uri': 'uri-reference',
     'url': 'uri-reference',
-    'raw': 'raw',}
+    'target': 'target',
+    }
 """Mapping of English role names to canonical role names for interpreted text.
+
+Cf. https://docutils.sourceforge.io/docs/ref/rst/roles.html
 """

python/helpers/py3only/docutils/parsers/rst/languages/eo.py

@@ -1,11 +1,11 @@
-# $Id: eo.py 7119 2011-09-02 13:00:23Z milde $
+# $Id: eo.py 9452 2023-09-27 00:11:54Z milde $
 # Author: Marcelo Huerta San Martin <richieadler@users.sourceforge.net>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Esperanto-language mappings for language-dependent features of
@@ -16,64 +16,65 @@ __docformat__ = 'reStructuredText'
 
 
 directives = {
-      # language-dependent: fixed
-      'atentu': 'attention',
-      'zorgu': 'caution',
-      'code (translation required)': 'code',
-      'dangxero': 'danger',
-      'dan\u011dero': 'danger',
-      'eraro': 'error',
-      'spuro': 'hint',
-      'grava': 'important',
-      'noto': 'note',
-      'helpeto': 'tip',
-      'averto': 'warning',
-      'admono': 'admonition',
-      'flankteksto': 'sidebar',
-      'temo': 'topic',
-      'linea-bloko': 'line-block',
-      'analizota-literalo': 'parsed-literal',
-      'rubriko': 'rubric',
-      'epigrafo': 'epigraph',
-      'elstarajxoj': 'highlights',
-      'elstara\u0135oj': 'highlights',
-      'ekstera-citajxo': 'pull-quote',
-      'ekstera-cita\u0135o': 'pull-quote',
-      'kombinajxo': 'compound',
-      'kombina\u0135o': 'compound',
-      'tekstingo': 'container',
-      'enhavilo': 'container',
-      #'questions': 'questions',
-      #'qa': 'questions',
-      #'faq': 'questions',
-      'tabelo': 'table',
-      'tabelo-vdk': 'csv-table', # "valoroj disigitaj per komoj"
-      'tabelo-csv': 'csv-table',
-      'tabelo-lista': 'list-table',
-      'meta': 'meta',
-      'math (translation required)': 'math',
-      #'imagemap': 'imagemap',
-      'bildo': 'image',
-      'figuro': 'figure',
-      'inkludi': 'include',
-      'senanaliza': 'raw',
-      'anstatauxi': 'replace',
-      'anstata\u016di': 'replace',
-      'unicode': 'unicode',
-      'dato': 'date',
-      'klaso': 'class',
-      'rolo': 'role',
-      'preterlasita-rolo': 'default-role',
-      'titolo': 'title',
-      'enhavo': 'contents',
-      'seknum': 'sectnum',
-      'sekcia-numerado': 'sectnum',
-      'kapsekcio': 'header',
-      'piedsekcio': 'footer',
-      #'footnotes': 'footnotes',
-      #'citations': 'citations',
-      'celaj-notoj': 'target-notes',
-      'restructuredtext-test-directive': 'restructuredtext-test-directive'}
+    # language-dependent: fixed
+    'atentu': 'attention',
+    'zorgu': 'caution',
+    'code (translation required)': 'code',
+    'dangxero': 'danger',
+    'danĝero': 'danger',
+    'eraro': 'error',
+    'spuro': 'hint',
+    'grava': 'important',
+    'noto': 'note',
+    'helpeto': 'tip',
+    'averto': 'warning',
+    'sciigo': 'admonition',
+    'admono': 'admonition',  # sic! kept for backwards compatibiltity
+    'flankteksto': 'sidebar',
+    'temo': 'topic',
+    'linea-bloko': 'line-block',
+    'analizota-literalo': 'parsed-literal',
+    'rubriko': 'rubric',
+    'epigrafo': 'epigraph',
+    'elstarajxoj': 'highlights',
+    'elstaraĵoj': 'highlights',
+    'ekstera-citajxo': 'pull-quote',
+    'ekstera-citaĵo': 'pull-quote',
+    'kombinajxo': 'compound',
+    'kombinaĵo': 'compound',
+    'tekstingo': 'container',
+    'enhavilo': 'container',
+    # 'questions': 'questions',
+    # 'qa': 'questions',
+    # 'faq': 'questions',
+    'tabelo': 'table',
+    'tabelo-vdk': 'csv-table',  # "valoroj disigitaj per komoj"
+    'tabelo-csv': 'csv-table',
+    'tabelo-lista': 'list-table',
+    'meta': 'meta',
+    'math (translation required)': 'math',
+    # 'imagemap': 'imagemap',
+    'bildo': 'image',
+    'figuro': 'figure',
+    'inkludi': 'include',
+    'senanaliza': 'raw',
+    'anstatauxi': 'replace',
+    'anstataŭi': 'replace',
+    'unicode': 'unicode',
+    'dato': 'date',
+    'klaso': 'class',
+    'rolo': 'role',
+    'preterlasita-rolo': 'default-role',
+    'titolo': 'title',
+    'enhavo': 'contents',
+    'seknum': 'sectnum',
+    'sekcia-numerado': 'sectnum',
+    'kapsekcio': 'header',
+    'piedsekcio': 'footer',
+    # 'footnotes': 'footnotes',
+    # 'citations': 'citations',
+    'celaj-notoj': 'target-notes',
+    'restructuredtext-test-directive': 'restructuredtext-test-directive'}
 """Esperanto name to registered (in directives/__init__.py) directive name
 mapping."""
 
@@ -105,14 +106,14 @@ roles = {
     'nenomita-referenco': 'anonymous-reference',
     'piednota-referenco': 'footnote-reference',
     'citajxo-referenco': 'citation-reference',
-    'cita\u0135o-referenco': 'citation-reference',
+    'citaĵo-referenco': 'citation-reference',
     'anstatauxa-referenco': 'substitution-reference',
-    'anstata\u016da-referenco': 'substitution-reference',
+    'anstataŭa-referenco': 'substitution-reference',
     'celo': 'target',
     'uri-referenco': 'uri-reference',
     'uri': 'uri-reference',
     'url': 'uri-reference',
     'senanaliza': 'raw',
 }
-"""Mapping of Esperanto role names to canonical role names for interpreted text.
+"""Mapping of Esperanto role names to canonical names for interpreted text.
 """

python/helpers/py3only/docutils/parsers/rst/languages/es.py

@@ -1,12 +1,11 @@
-# -*- coding: utf-8 -*-
-# $Id: es.py 7119 2011-09-02 13:00:23Z milde $
+# $Id: es.py 9452 2023-09-27 00:11:54Z milde $
 # Author: Marcelo Huerta San Martín <richieadler@users.sourceforge.net>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Spanish-language mappings for language-dependent features of
@@ -15,70 +14,70 @@ reStructuredText.
 
 __docformat__ = 'reStructuredText'
 
-
 directives = {
-      'atenci\u00f3n': 'attention',
-      'atencion': 'attention',
-      'precauci\u00f3n': 'caution',
-      'code (translation required)': 'code',
-      'precaucion': 'caution',
-      'peligro': 'danger',
-      'error': 'error',
-      'sugerencia': 'hint',
-      'importante': 'important',
-      'nota': 'note',
-      'consejo': 'tip',
-      'advertencia': 'warning',
-      'exhortacion': 'admonition',
-      'exhortaci\u00f3n': 'admonition',
-      'nota-al-margen': 'sidebar',
-      'tema': 'topic',
-      'bloque-de-lineas': 'line-block',
-      'bloque-de-l\u00edneas': 'line-block',
-      'literal-evaluado': 'parsed-literal',
-      'firma': 'rubric',
-      'ep\u00edgrafe': 'epigraph',
-      'epigrafe': 'epigraph',
-      'destacado': 'highlights',
-      'cita-destacada': 'pull-quote',
-      'combinacion': 'compound',
-      'combinaci\u00f3n': 'compound',
-      'contenedor': 'container',
-      #'questions': 'questions',
-      #'qa': 'questions',
-      #'faq': 'questions',
-      'tabla': 'table',
-      'tabla-vsc': 'csv-table',
-      'tabla-csv': 'csv-table',
-      'tabla-lista': 'list-table',
-      'meta': 'meta',
-      'math (translation required)': 'math',
-      #'imagemap': 'imagemap',
-      'imagen': 'image',
-      'figura': 'figure',
-      'incluir': 'include',
-      'sin-analisis': 'raw',
-      'sin-an\u00e1lisis': 'raw',
-      'reemplazar': 'replace',
-      'unicode': 'unicode',
-      'fecha': 'date',
-      'clase': 'class',
-      'rol': 'role',
-      'rol-por-omision': 'default-role',
-      'rol-por-omisi\u00f3n': 'default-role',
-      'titulo': 'title',
-      't\u00edtulo': 'title',
-      'contenido': 'contents',
-      'numseccion': 'sectnum',
-      'numsecci\u00f3n': 'sectnum',
-      'numeracion-seccion': 'sectnum',
-      'numeraci\u00f3n-secci\u00f3n': 'sectnum',
-      'notas-destino': 'target-notes',
-      'cabecera': 'header',
-      'pie': 'footer',
-      #'footnotes': 'footnotes',
-      #'citations': 'citations',
-      'restructuredtext-test-directive': 'restructuredtext-test-directive'}
+    'atención': 'attention',
+    'atencion': 'attention',
+    'precaución': 'caution',
+    'code (translation required)': 'code',
+    'precaucion': 'caution',
+    'peligro': 'danger',
+    'error': 'error',
+    'sugerencia': 'hint',
+    'importante': 'important',
+    'nota': 'note',
+    'consejo': 'tip',
+    'advertencia': 'warning',
+    'aviso': 'admonition',
+    'exhortacion': 'admonition',  # sic! kept for backwards compatibiltity
+    'exhortación': 'admonition',  # sic! kept for backwards compatibiltity
+    'nota-al-margen': 'sidebar',
+    'tema': 'topic',
+    'bloque-de-lineas': 'line-block',
+    'bloque-de-líneas': 'line-block',
+    'literal-evaluado': 'parsed-literal',
+    'firma': 'rubric',
+    'epígrafe': 'epigraph',
+    'epigrafe': 'epigraph',
+    'destacado': 'highlights',
+    'cita-destacada': 'pull-quote',
+    'combinacion': 'compound',
+    'combinación': 'compound',
+    'contenedor': 'container',
+    # 'questions': 'questions',
+    # 'qa': 'questions',
+    # 'faq': 'questions',
+    'tabla': 'table',
+    'tabla-vsc': 'csv-table',
+    'tabla-csv': 'csv-table',
+    'tabla-lista': 'list-table',
+    'meta': 'meta',
+    'math (translation required)': 'math',
+    # 'imagemap': 'imagemap',
+    'imagen': 'image',
+    'figura': 'figure',
+    'incluir': 'include',
+    'sin-analisis': 'raw',
+    'sin-análisis': 'raw',
+    'reemplazar': 'replace',
+    'unicode': 'unicode',
+    'fecha': 'date',
+    'clase': 'class',
+    'rol': 'role',
+    'rol-por-omision': 'default-role',
+    'rol-por-omisión': 'default-role',
+    'titulo': 'title',
+    'título': 'title',
+    'contenido': 'contents',
+    'numseccion': 'sectnum',
+    'numsección': 'sectnum',
+    'numeracion-seccion': 'sectnum',
+    'numeración-sección': 'sectnum',
+    'notas-destino': 'target-notes',
+    'cabecera': 'header',
+    'pie': 'footer',
+    # 'footnotes': 'footnotes',
+    # 'citations': 'citations',
+    'restructuredtext-test-directive': 'restructuredtext-test-directive'}
 """Spanish name to registered (in directives/__init__.py) directive name
 mapping."""
 
@@ -86,15 +85,14 @@ roles = {
     'abreviatura': 'abbreviation',
     'ab': 'abbreviation',
     'acronimo': 'acronym',
-    'acronimo': 'acronym',
     'ac': 'acronym',
     'code (translation required)': 'code',
     'indice': 'index',
     'i': 'index',
     'subindice': 'subscript',
-    'sub\u00edndice': 'subscript',
+    'subíndice': 'subscript',
     'superindice': 'superscript',
-    'super\u00edndice': 'superscript',
+    'superíndice': 'superscript',
     'referencia-titulo': 'title-reference',
     'titulo': 'title-reference',
     't': 'title-reference',
@@ -103,23 +101,23 @@ roles = {
     'referencia-rfc': 'rfc-reference',
     'rfc': 'rfc-reference',
     'enfasis': 'emphasis',
-    '\u00e9nfasis': 'emphasis',
+    'énfasis': 'emphasis',
     'destacado': 'strong',
-    'literal': 'literal',              # "literal" is also a word in Spanish :-)
+    'literal': 'literal',  # "literal" is also a word in Spanish :-)
     'math (translation required)': 'math',
     'referencia-con-nombre': 'named-reference',
     'referencia-anonima': 'anonymous-reference',
-    'referencia-an\u00f3nima': 'anonymous-reference',
+    'referencia-anónima': 'anonymous-reference',
     'referencia-nota-al-pie': 'footnote-reference',
     'referencia-cita': 'citation-reference',
     'referencia-sustitucion': 'substitution-reference',
-    'referencia-sustituci\u00f3n': 'substitution-reference',
+    'referencia-sustitución': 'substitution-reference',
     'destino': 'target',
     'referencia-uri': 'uri-reference',
     'uri': 'uri-reference',
     'url': 'uri-reference',
     'sin-analisis': 'raw',
-    'sin-an\u00e1lisis': 'raw',
+    'sin-análisis': 'raw',
 }
 """Mapping of Spanish role names to canonical role names for interpreted text.
 """

python/helpers/py3only/docutils/parsers/rst/languages/fa.py

@@ -0,0 +1,102 @@
+# $Id: fa.py 4564 2016-08-10 11:48:42Z
+# Author: Shahin <me@5hah.in>
+# Copyright: This module has been placed in the public domain.
+
+# New language mappings are welcome.  Before doing a new translation, please
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
+
+"""
+Persian-language mappings for language-dependent features of
+reStructuredText.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+directives = {
+    # language-dependent: fixed
+    'توجه': 'attention',
+    'احتیاط': 'caution',
+    'کد': 'code',
+    'بلوک-کد': 'code',
+    'کد-منبع': 'code',
+    'خطر': 'danger',
+    'خطا': 'error',
+    'راهنما': 'hint',
+    'مهم': 'important',
+    'یادداشت': 'note',
+    'نکته': 'tip',
+    'اخطار': 'warning',
+    'تذکر': 'admonition',
+    'نوار-کناری': 'sidebar',
+    'موضوع': 'topic',
+    'بلوک-خط': 'line-block',
+    'تلفظ-پردازش-شده': 'parsed-literal',
+    'سر-فصل': 'rubric',
+    'کتیبه': 'epigraph',
+    'نکات-برجسته': 'highlights',
+    'نقل-قول': 'pull-quote',
+    'ترکیب': 'compound',
+    'ظرف': 'container',
+    # 'questions': 'questions',
+    'جدول': 'table',
+    'جدول-csv': 'csv-table',
+    'جدول-لیست': 'list-table',
+    # 'qa': 'questions',
+    # 'faq': 'questions',
+    'متا': 'meta',
+    'ریاضی': 'math',
+    # 'imagemap': 'imagemap',
+    'تصویر': 'image',
+    'شکل': 'figure',
+    'شامل': 'include',
+    'خام': 'raw',
+    'جایگزین': 'replace',
+    'یونیکد': 'unicode',
+    'تاریخ': 'date',
+    'کلاس': 'class',
+    'قانون': 'role',
+    'قانون-پیش‌فرض': 'default-role',
+    'عنوان': 'title',
+    'محتوا': 'contents',
+    'شماره-فصل': 'sectnum',
+    'شماره‌گذاری-فصل': 'sectnum',
+    'سرآیند': 'header',
+    'پاصفحه': 'footer',
+    # 'footnotes': 'footnotes',
+    # 'citations': 'citations',
+    'یادداشت-هدف': 'target-notes',
+}
+"""Persian name to registered (in directives/__init__.py) directive name
+mapping."""
+
+roles = {
+    # language-dependent: fixed
+    'مخفف': 'abbreviation',
+    'سرنام': 'acronym',
+    'کد': 'code',
+    'شاخص': 'index',
+    'زیرنویس': 'subscript',
+    'بالانویس': 'superscript',
+    'عنوان': 'title-reference',
+    'نیرو': 'pep-reference',
+    'rfc-reference (translation required)': 'rfc-reference',
+    'تاکید': 'emphasis',
+    'قوی': 'strong',
+    'لفظی': 'literal',
+    'ریاضی': 'math',
+    'منبع-نام‌گذاری': 'named-reference',
+    'منبع-ناشناس': 'anonymous-reference',
+    'منبع-پانویس': 'footnote-reference',
+    'منبع-نقل‌فول': 'citation-reference',
+    'منبع-جایگزینی': 'substitution-reference',
+    'هدف': 'target',
+    'منبع-uri': 'uri-reference',
+    'uri': 'uri-reference',
+    'url': 'uri-reference',
+    'خام': 'raw',
+}
+"""Mapping of Persian role names to canonical role names for interpreted text.
+"""

python/helpers/py3only/docutils/parsers/rst/languages/fi.py

@@ -1,12 +1,11 @@
-# -*- coding: utf-8 -*-
-# $Id: fi.py 7119 2011-09-02 13:00:23Z milde $
+# $Id: fi.py 9452 2023-09-27 00:11:54Z milde $
 # Author: Asko Soukka <asko.soukka@iki.fi>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Finnish-language mappings for language-dependent features of
@@ -24,11 +23,11 @@ directives = {
       'vaara': 'danger',
       'virhe': 'error',
       'vihje': 'hint',
-      't\u00e4rke\u00e4\u00e4': 'important',
+      'tärkeää': 'important',
       'huomautus': 'note',
       'neuvo': 'tip',
       'varoitus': 'warning',
-      'kehotus': 'admonition',
+      'kehotus': 'admonition',  # sic! advice/advisory/remark, not reprimand
       'sivupalkki': 'sidebar',
       'aihe': 'topic',
       'rivi': 'line-block',
@@ -42,27 +41,27 @@ directives = {
       'list-table (translation required)': 'list-table',
       'compound (translation required)': 'compound',
       'container (translation required)': 'container',
-      #u'kysymykset': u'questions',
+      # 'kysymykset': 'questions',
       'meta': 'meta',
       'math (translation required)': 'math',
-      #u'kuvakartta': u'imagemap',
+      # 'kuvakartta': 'imagemap',
       'kuva': 'image',
       'kaavio': 'figure',
-      'sis\u00e4llyt\u00e4': 'include',
+      'sisällytä': 'include',
       'raaka': 'raw',
       'korvaa': 'replace',
       'unicode': 'unicode',
-      'p\u00e4iv\u00e4ys': 'date',
+      'päiväys': 'date',
       'luokka': 'class',
       'rooli': 'role',
       'default-role (translation required)': 'default-role',
       'title (translation required)': 'title',
-      'sis\u00e4llys': 'contents',
+      'sisällys': 'contents',
       'kappale': 'sectnum',
       'header (translation required)': 'header',
       'footer (translation required)': 'footer',
-      #u'alaviitteet': u'footnotes',
-      #u'viitaukset': u'citations',
+      # 'alaviitteet': 'footnotes',
+      # 'viitaukset': 'citations',
       'target-notes (translation required)': 'target-notes'}
 """Finnish name to registered (in directives/__init__.py) directive name
 mapping."""
@@ -77,7 +76,7 @@ roles = {
     'luettelo': 'index',
     'alaindeksi': 'subscript',
     'indeksi': 'subscript',
-    'yl\u00e4indeksi': 'superscript',
+    'yläindeksi': 'superscript',
     'title-reference (translation required)': 'title-reference',
     'title (translation required)': 'title-reference',
     'pep-reference (translation required)': 'pep-reference',
@@ -93,6 +92,7 @@ roles = {
     'substitution-reference (translation required)': 'substitution-reference',
     'kohde': 'target',
     'uri-reference (translation required)': 'uri-reference',
-    'raw (translation required)': 'raw',}
+    'raw (translation required)': 'raw',
+    }
 """Mapping of Finnish role names to canonical role names for interpreted text.
 """

python/helpers/py3only/docutils/parsers/rst/languages/fr.py

@@ -1,11 +1,11 @@
-# $Id: fr.py 7119 2011-09-02 13:00:23Z milde $
+# $Id: fr.py 9417 2023-06-27 20:04:54Z milde $
 # Authors: David Goodger <goodger@python.org>; William Dode
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 French-language mappings for language-dependent features of
@@ -17,8 +17,7 @@ __docformat__ = 'reStructuredText'
 
 directives = {
       'attention': 'attention',
-      'pr\u00E9caution': 'caution',
-      'code': 'code',
+      'précaution': 'caution',
       'danger': 'danger',
       'erreur': 'error',
       'conseil': 'hint',
@@ -26,28 +25,29 @@ directives = {
       'note': 'note',
       'astuce': 'tip',
       'avertissement': 'warning',
-      'admonition': 'admonition',
-      'encadr\u00E9': 'sidebar',
+      'annonce': 'admonition',
+      'admonition': 'admonition',  # sic! kept for backwards compatibiltity
+      # suggestions: annonce, avis, indication, remarque, renseignement
+      # see also https://sourceforge.net/p/docutils/bugs/453/
+      'encadré': 'sidebar',
       'sujet': 'topic',
       'bloc-textuel': 'line-block',
-      'bloc-interpr\u00E9t\u00E9': 'parsed-literal',
-      'code-interpr\u00E9t\u00E9': 'parsed-literal',
+      'bloc-interprété': 'parsed-literal',
+      'code-interprété': 'parsed-literal',
+      'code': 'code',
+      'math (translation required)': 'math',
       'intertitre': 'rubric',
       'exergue': 'epigraph',
-      '\u00E9pigraphe': 'epigraph',
+      'épigraphe': 'epigraph',
       'chapeau': 'highlights',
       'accroche': 'pull-quote',
       'compound (translation required)': 'compound',
       'container (translation required)': 'container',
-      #u'questions': 'questions',
-      #u'qr': 'questions',
-      #u'faq': 'questions',
       'tableau': 'table',
       'csv-table (translation required)': 'csv-table',
       'list-table (translation required)': 'list-table',
-      'm\u00E9ta': 'meta',
-      'math (translation required)': 'math',
-      #u'imagemap (translation required)': 'imagemap',
+      'méta': 'meta',
+      # 'imagemap (translation required)': 'imagemap',
       'image': 'image',
       'figure': 'figure',
       'inclure': 'include',
@@ -61,43 +61,48 @@ directives = {
       'default-role (translation required)': 'default-role',
       'titre (translation required)': 'title',
       'sommaire': 'contents',
-      'table-des-mati\u00E8res': 'contents',
+      'table-des-matières': 'contents',
       'sectnum': 'sectnum',
-      'section-num\u00E9rot\u00E9e': 'sectnum',
+      'section-numérotée': 'sectnum',
       'liens': 'target-notes',
       'header (translation required)': 'header',
       'footer (translation required)': 'footer',
-      #u'footnotes (translation required)': 'footnotes',
-      #u'citations (translation required)': 'citations',
+      # 'footnotes (translation required)': 'footnotes',
+      # 'citations (translation required)': 'citations',
       }
-"""French name to registered (in directives/__init__.py) directive name
-mapping."""
+"""Mapping of French directive names to registered directive names
+
+Cf. https://docutils.sourceforge.io/docs/ref/rst/directives.html
+and `_directive_registry` in ``directives/__init__.py``.
+"""
 
 roles = {
-      'abr\u00E9viation': 'abbreviation',
+      'abréviation': 'abbreviation',
       'acronyme': 'acronym',
       'sigle': 'acronym',
       'code': 'code',
-      'index': 'index',
+      'emphase': 'emphasis',
+      'littéral': 'literal',
+      'math (translation required)': 'math',
+      'pep-référence': 'pep-reference',
+      'rfc-référence': 'rfc-reference',
+      'fort': 'strong',
       'indice': 'subscript',
       'ind': 'subscript',
       'exposant': 'superscript',
       'exp': 'superscript',
-      'titre-r\u00E9f\u00E9rence': 'title-reference',
+      'titre-référence': 'title-reference',
       'titre': 'title-reference',
-      'pep-r\u00E9f\u00E9rence': 'pep-reference',
-      'rfc-r\u00E9f\u00E9rence': 'rfc-reference',
-      'emphase': 'emphasis',
-      'fort': 'strong',
-      'litt\u00E9ral': 'literal',
-    'math (translation required)': 'math',
-      'nomm\u00E9e-r\u00E9f\u00E9rence': 'named-reference',
-      'anonyme-r\u00E9f\u00E9rence': 'anonymous-reference',
-      'note-r\u00E9f\u00E9rence': 'footnote-reference',
-      'citation-r\u00E9f\u00E9rence': 'citation-reference',
-      'substitution-r\u00E9f\u00E9rence': 'substitution-reference',
+      'brut': 'raw',
+      # the following roles are not implemented in Docutils
+      'index': 'index',
+      'nommée-référence': 'named-reference',
+      'anonyme-référence': 'anonymous-reference',
+      'note-référence': 'footnote-reference',
+      'citation-référence': 'citation-reference',
+      'substitution-référence': 'substitution-reference',
       'lien': 'target',
-      'uri-r\u00E9f\u00E9rence': 'uri-reference',
-      'brut': 'raw',}
+      'uri-référence': 'uri-reference',
+      }
 """Mapping of French role names to canonical role names for interpreted text.
 """

python/helpers/py3only/docutils/parsers/rst/languages/gl.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 # Author: David Goodger
 # Contact: goodger@users.sourceforge.net
 # Revision: $Revision: 4229 $
@@ -6,9 +5,9 @@
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Galician-language mappings for language-dependent features of
@@ -20,7 +19,7 @@ __docformat__ = 'reStructuredText'
 
 directives = {
       # language-dependent: fixed
-      'atenci\u00f3n': 'attention',
+      'atención': 'attention',
       'advertencia': 'caution',
       'code (translation required)': 'code',
       'perigo': 'danger',
@@ -30,46 +29,41 @@ directives = {
       'nota': 'note',
       'consello': 'tip',
       'aviso': 'warning',
-      'admonici\u00f3n': 'admonition',
+      'admonición': 'admonition',  # sic! advice/advisory/remark, not reprimand
       'barra lateral': 'sidebar',
-      't\u00f3pico': 'topic',
-      'bloque-li\u00f1a': 'line-block',
+      'tópico': 'topic',
+      'bloque-liña': 'line-block',
       'literal-analizado': 'parsed-literal',
-      'r\u00fabrica': 'rubric',
-      'ep\u00edgrafe': 'epigraph',
+      'rúbrica': 'rubric',
+      'epígrafe': 'epigraph',
       'realzados': 'highlights',
-      'coller-citaci\u00f3n': 'pull-quote',
+      'coller-citación': 'pull-quote',
       'compor': 'compound',
       'recipiente': 'container',
-      #'questions': 'questions',
-      't\u00e1boa': 'table',
-      't\u00e1boa-csv': 'csv-table',
-      't\u00e1boa-listaxe': 'list-table',
-      #'qa': 'questions',
-      #'faq': 'questions',
+      'táboa': 'table',
+      'táboa-csv': 'csv-table',
+      'táboa-listaxe': 'list-table',
       'meta': 'meta',
       'math (translation required)': 'math',
-      #'imagemap': 'imagemap',
       'imaxe': 'image',
       'figura': 'figure',
-      'inclu\u00edr': 'include',
+      'incluír': 'include',
       'cru': 'raw',
-      'substitu\u00edr': 'replace',
+      'substituír': 'replace',
       'unicode': 'unicode',
       'data': 'date',
       'clase': 'class',
       'regra': 'role',
       'regra-predeterminada': 'default-role',
-      't\u00edtulo': 'title',
+      'título': 'title',
       'contido': 'contents',
       'seccnum': 'sectnum',
-      'secci\u00f3n-numerar': 'sectnum',
+      'sección-numerar': 'sectnum',
       'cabeceira': 'header',
-      'p\u00e9 de p\u00e1xina': 'footer',
-      #'footnotes': 'footnotes',
-      #'citations': 'citations',
+      'pé de páxina': 'footer',
       'notas-destino': 'target-notes',
-      'texto restruturado-proba-directiva': 'restructuredtext-test-directive'}
+      'texto restruturado-proba-directiva': 'restructuredtext-test-directive',
+      }
 """Galician name to registered (in directives/__init__.py) directive name
 mapping."""
 
@@ -77,35 +71,36 @@ roles = {
     # language-dependent: fixed
     'abreviatura': 'abbreviation',
     'ab': 'abbreviation',
-    'acr\u00f3nimo': 'acronym',
+    'acrónimo': 'acronym',
     'ac': 'acronym',
     'code (translation required)': 'code',
-    '\u00edndice': 'index',
+    'índice': 'index',
     'i': 'index',
-    'sub\u00edndice': 'subscript',
+    'subíndice': 'subscript',
     'sub': 'subscript',
-    'super\u00edndice': 'superscript',
+    'superíndice': 'superscript',
     'sup': 'superscript',
-    'referencia t\u00edtulo': 'title-reference',
-    't\u00edtulo': 'title-reference',
+    'referencia título': 'title-reference',
+    'título': 'title-reference',
     't': 'title-reference',
     'referencia-pep': 'pep-reference',
     'pep': 'pep-reference',
     'referencia-rfc': 'rfc-reference',
     'rfc': 'rfc-reference',
-    '\u00e9nfase': 'emphasis',
+    'énfase': 'emphasis',
     'forte': 'strong',
     'literal': 'literal',
     'math (translation required)': 'math',
     'referencia-nome': 'named-reference',
-    'referencia-an\u00f3nimo': 'anonymous-reference',
-    'referencia-nota ao p\u00e9': 'footnote-reference',
-    'referencia-citaci\u00f3n': 'citation-reference',
-    'referencia-substituci\u00f3n': 'substitution-reference',
+    'referencia-anónimo': 'anonymous-reference',
+    'referencia-nota ao pé': 'footnote-reference',
+    'referencia-citación': 'citation-reference',
+    'referencia-substitución': 'substitution-reference',
     'destino': 'target',
     'referencia-uri': 'uri-reference',
     'uri': 'uri-reference',
     'url': 'uri-reference',
-    'cru': 'raw',}
+    'cru': 'raw',
+    }
 """Mapping of Galician role names to canonical role names for interpreted text.
 """

python/helpers/py3only/docutils/parsers/rst/languages/he.py

@@ -1,11 +1,11 @@
 # Author: Meir Kriheli
-# Id: $Id: he.py 7119 2011-09-02 13:00:23Z milde $
+# Id: $Id: he.py 9452 2023-09-27 00:11:54Z milde $
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 English-language mappings for language-dependent features of
@@ -16,57 +16,58 @@ __docformat__ = 'reStructuredText'
 
 
 directives = {
-      # language-dependent: fixed
-      '\u05ea\u05e9\u05d5\u05de\u05ea \u05dc\u05d1': 'attention',
-      '\u05d6\u05d4\u05d9\u05e8\u05d5\u05ea': 'caution',
-      'code (translation required)': 'code',
-      '\u05e1\u05db\u05e0\u05d4': 'danger',
-      '\u05e9\u05d2\u05d9\u05d0\u05d4' : 'error',
-      '\u05e8\u05de\u05d6': 'hint',
-      '\u05d7\u05e9\u05d5\u05d1': 'important',
-      '\u05d4\u05e2\u05e8\u05d4': 'note',
-      '\u05d8\u05d9\u05e4': 'tip',
-      '\u05d0\u05d6\u05d4\u05e8\u05d4': 'warning',
-      'admonition': 'admonition',
-      'sidebar': 'sidebar',
-      'topic': 'topic',
-      'line-block': 'line-block',
-      'parsed-literal': 'parsed-literal',
-      'rubric': 'rubric',
-      'epigraph': 'epigraph',
-      'highlights': 'highlights',
-      'pull-quote': 'pull-quote',
-      'compound': 'compound',
-      'container': 'container',
-      #'questions': 'questions',
-      'table': 'table',
-      'csv-table': 'csv-table',
-      'list-table': 'list-table',
-      #'qa': 'questions',
-      #'faq': 'questions',
-      'meta': 'meta',
-      'math (translation required)': 'math',
-      #'imagemap': 'imagemap',
-      '\u05ea\u05de\u05d5\u05e0\u05d4': 'image',
-      'figure': 'figure',
-      'include': 'include',
-      'raw': 'raw',
-      'replace': 'replace',
-      'unicode': 'unicode',
-      'date': 'date',
-       '\u05e1\u05d2\u05e0\u05d5\u05df': 'class',
-      'role': 'role',
-      'default-role': 'default-role',
-      'title': 'title',
-      '\u05ea\u05d5\u05db\u05df': 'contents',
-      'sectnum': 'sectnum',
-      'section-numbering': 'sectnum',
-      'header': 'header',
-      'footer': 'footer',
-      #'footnotes': 'footnotes',
-      #'citations': 'citations',
-      'target-notes': 'target-notes',
-      'restructuredtext-test-directive': 'restructuredtext-test-directive'}
+    # language-dependent: fixed
+    'תשומת לב': 'attention',
+    'זהירות': 'caution',
+    'code (translation required)': 'code',
+    'סכנה': 'danger',
+    'שגיאה': 'error',
+    'רמז': 'hint',
+    'חשוב': 'important',
+    'הערה': 'note',
+    'טיפ': 'tip',
+    'אזהרה': 'warning',
+    'admonition': 'admonition',
+    'sidebar': 'sidebar',
+    'topic': 'topic',
+    'line-block': 'line-block',
+    'parsed-literal': 'parsed-literal',
+    'rubric': 'rubric',
+    'epigraph': 'epigraph',
+    'highlights': 'highlights',
+    'pull-quote': 'pull-quote',
+    'compound': 'compound',
+    'container': 'container',
+    'table': 'table',
+    'csv-table': 'csv-table',
+    'list-table': 'list-table',
+    'meta': 'meta',
+    'math (translation required)': 'math',
+    'תמונה': 'image',
+    'figure': 'figure',
+    'include': 'include',
+    'raw': 'raw',
+    'replace': 'replace',
+    'unicode': 'unicode',
+    'date': 'date',
+    'סגנון': 'class',
+    'role': 'role',
+    'default-role': 'default-role',
+    'title': 'title',
+    'תוכן': 'contents',
+    'sectnum': 'sectnum',
+    'section-numbering': 'sectnum',
+    'header': 'header',
+    'footer': 'footer',
+    'target-notes': 'target-notes',
+    'restructuredtext-test-directive': 'restructuredtext-test-directive',
+    # 'questions': 'questions',
+    # 'qa': 'questions',
+    # 'faq': 'questions',
+    # 'imagemap': 'imagemap',
+    # 'footnotes': 'footnotes',
+    # 'citations': 'citations',
+    }
 """English name to registered (in directives/__init__.py) directive name
 mapping."""
 
@@ -79,9 +80,9 @@ roles = {
     'code (translation required)': 'code',
     'index': 'index',
     'i': 'index',
-    '\u05ea\u05d7\u05ea\u05d9': 'subscript',
+    'תחתי': 'subscript',
     'sub': 'subscript',
-    '\u05e2\u05d9\u05dc\u05d9': 'superscript',
+    'עילי': 'superscript',
     'sup': 'superscript',
     'title-reference': 'title-reference',
     'title': 'title-reference',
@@ -103,6 +104,7 @@ roles = {
     'uri-reference': 'uri-reference',
     'uri': 'uri-reference',
     'url': 'uri-reference',
-    'raw': 'raw',}
+    'raw': 'raw',
+    }
 """Mapping of English role names to canonical role names for interpreted text.
 """

python/helpers/py3only/docutils/parsers/rst/languages/it.py

@@ -1,4 +1,4 @@
-# $Id: it.py 7119 2011-09-02 13:00:23Z milde $
+# $Id: it.py 9417 2023-06-27 20:04:54Z milde $
 # Authors: Nicola Larosa <docutils@tekNico.net>;
 #          Lele Gaifax <lele@seldati.it>
 # Copyright: This module has been placed in the public domain.
@@ -27,7 +27,8 @@ directives = {
       'nota': 'note',
       'consiglio': 'tip',
       'avvertenza': 'warning',
-      'ammonizione': 'admonition',
+      'avviso': 'admonition',
+      'ammonizione': 'admonition',  # sic! kept for backards compatibility
       'riquadro': 'sidebar',
       'argomento': 'topic',
       'blocco-di-righe': 'line-block',
@@ -38,15 +39,15 @@ directives = {
       'estratto-evidenziato': 'pull-quote',
       'composito': 'compound',
       'container (translation required)': 'container',
-      #'questions': 'questions',
-      #'qa': 'questions',
-      #'faq': 'questions',
+      # 'questions': 'questions',
+      # 'qa': 'questions',
+      # 'faq': 'questions',
       'tabella': 'table',
       'tabella-csv': 'csv-table',
       'tabella-elenco': 'list-table',
       'meta': 'meta',
       'math (translation required)': 'math',
-      #'imagemap': 'imagemap',
+      # 'imagemap': 'imagemap',
       'immagine': 'image',
       'figura': 'figure',
       'includi': 'include',
@@ -65,8 +66,8 @@ directives = {
       'annota-riferimenti-esterni': 'target-notes',
       'intestazione': 'header',
       'piede-pagina': 'footer',
-      #'footnotes': 'footnotes',
-      #'citations': 'citations',
+      # 'footnotes': 'footnotes',
+      # 'citations': 'citations',
       'restructuredtext-test-directive': 'restructuredtext-test-directive'}
 """Italian name to registered (in directives/__init__.py) directive name
 mapping."""
@@ -84,7 +85,7 @@ roles = {
       'enfasi': 'emphasis',
       'forte': 'strong',
       'letterale': 'literal',
-    'math (translation required)': 'math',
+      'math (translation required)': 'math',
       'riferimento-con-nome': 'named-reference',
       'riferimento-anonimo': 'anonymous-reference',
       'riferimento-nota': 'footnote-reference',
@@ -92,6 +93,7 @@ roles = {
       'riferimento-sostituzione': 'substitution-reference',
       'destinazione': 'target',
       'riferimento-uri': 'uri-reference',
-      'grezzo': 'raw',}
+      'grezzo': 'raw',
+      }
 """Mapping of Italian role names to canonical role names for interpreted text.
 """

python/helpers/py3only/docutils/parsers/rst/languages/ja.py

@@ -1,12 +1,11 @@
-# -*- coding: utf-8 -*-
-# $Id: ja.py 7119 2011-09-02 13:00:23Z milde $
+# $Id: ja.py 9030 2022-03-05 23:28:32Z milde $
 # Author: David Goodger <goodger@python.org>
 # Copyright: This module has been placed in the public domain.
 
 # New language mappings are welcome.  Before doing a new translation, please
-# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
-# translated for each language: one in docutils/languages, the other in
-# docutils/parsers/rst/languages.
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
 
 """
 Japanese-language mappings for language-dependent features of
@@ -47,12 +46,12 @@ directives = {
     '表': 'table',
     'csv表': 'csv-table',
     'リスト表': 'list-table',
-    #u'質問': 'questions',
-    #u'問答': 'questions',
-    #u'faq': 'questions',
+    # '質問': 'questions',
+    # '問答': 'questions',
+    # 'faq': 'questions',
     'math (translation required)': 'math',
     'メタ': 'meta',
-    #u'イメージマプ': 'imagemap',
+    # 'イメージマプ': 'imagemap',
     'イメージ': 'image',
     '画像': 'image',
     'フィグア': 'figure',
@@ -73,14 +72,14 @@ directives = {
     'ディフォルトロール': 'default-role',
     '既定役': 'default-role',
     'タイトル': 'title',
-    '題': 'title',                    # 題名　件名
+    '題': 'title',                       # 題名　件名
     '目次': 'contents',
     '節数': 'sectnum',
     'ヘッダ': 'header',
     'フッタ': 'footer',
-    #u'脚注': 'footnotes',             # 脚註?
-    #u'サイテーション': 'citations',　　　# 出典　引証　引用
-    'ターゲットノート': 'target-notes', # 的注　的脚注
+    # '脚注': 'footnotes',                # 脚註?
+    # 'サイテーション': 'citations',　　　# 出典　引証　引用
+    'ターゲットノート': 'target-notes',  # 的注　的脚注
     }
 """Japanese name to registered (in directives/__init__.py) directive name
 mapping."""
@@ -114,6 +113,7 @@ roles = {
     'uri参照': 'uri-reference',
     'uri': 'uri-reference',
     'url': 'uri-reference',
-    '生': 'raw',}
+    '生': 'raw',
+    }
 """Mapping of Japanese role names to canonical role names for interpreted
 text."""

python/helpers/py3only/docutils/parsers/rst/languages/ka.py

@@ -0,0 +1,90 @@
+# $Id: ka.py 9444 2023-08-23 12:02:41Z grubert $
+# Author: Temuri Doghonadze <temuri.doghonadze@gmail.com>
+# Copyright: This module has been placed in the public domain.
+
+# New language mappings are welcome.  Before doing a new translation, please
+# read <https://docutils.sourceforge.io/docs/howto/i18n.html>.
+# Two files must be translated for each language: one in docutils/languages,
+# the other in docutils/parsers/rst/languages.
+
+"""
+Georgian-language mappings for language-dependent features of
+reStructuredText.
+"""
+
+__docformat__ = 'reStructuredText'
+
+directives = {
+    'ხაზების-ბლოკი': 'line-block',
+    'მეტა': 'meta',
+    'მათემატიკა': 'math',
+    'დამუშავებული-ლიტერალი': 'parsed-literal',
+    'გამოყოფილი-ციტატა': 'pull-quote',
+    'კოდი': 'code',
+    'შერეული': 'compound',
+    'კონტეინერი': 'container',
+    'ცხრილი': 'table',
+    'csv-ცხრილი': 'csv-table',
+    'ჩამონათვალი-ცხრილი': 'list-table',
+    'დაუმუშავებელი': 'raw',
+    'ჩანაცვლება': 'replace',
+    'restructuredtext-ის-სატესტო-დირექტივა': 'restructuredtext-test-directive',
+    'სამიზნე-შენიშვნები': 'target-notes',
+    'უნიკოდი': 'unicode',
+    'თარიღი': 'date',
+    'გვერდითი-პანელი': 'sidebar',
+    'მნიშვნელოვანი': 'important',
+    'ჩასმა': 'include',
+    'ყურადღება': 'attention',
+    'გამოკვეთა': 'highlights',
+    'შენიშვნა': 'admonition',
+    'გამოსახულება': 'image',
+    'კლასი': 'class',
+    'როლი': 'role',
+    'ნაგულისხმევი-როლი': 'default-role',
+    'სათაური': 'title',
+    'განყ-ნომერი': 'sectnum',
+    'განყ-ნომერი': 'sectnum',
+    'საფრთხე': 'danger',
+    'ფრთხილად': 'caution',
+    'შეცდომა': 'error',
+    'მინიშნება': 'tip',
+    'ყურადღებით': 'warning',
+    'აღნიშვნა': 'note',
+    'ფიგურა': 'figure',
+    'რუბრიკა': 'rubric',
+    'რჩევა': 'hint',
+    'შემცველობა': 'contents',
+    'თემა': 'topic',
+    'ეპიგრაფი': 'epigraph',
+    'თავსართი': 'header',
+    'ქვედა კოლონტიტული': 'footer',
+    }
+"""Georgian name to registered (in directives/__init__.py) directive name
+mapping."""
+
+roles = {
+    'აკრონიმი': 'acronym',
+    'კოდი': 'code',
+    'ანონიმური-მიმართვა': 'anonymous-reference',
+    'სიტყვასიტყვითი': 'literal',
+    'მათემატიკა': 'math',
+    'ზედა-ინდექსი': 'superscript',
+    'მახვილი': 'emphasis',
+    'სახელიანი-მიმართვა': 'named-reference',
+    'ინდექსი': 'index',
+    'ქვედა-ინდექსი': 'subscript',
+    'სქელი-ფონტი': 'strong',
+    'აბრევიატურა': 'abbreviation',
+    'ჩანაცვლების-მიმართვა': 'substitution-reference',
+    'pep-მიმართვა': 'pep-reference',
+    'rfc-მიმართვა	': 'rfc-reference',
+    'uri-მიმართვა': 'uri-reference',
+    'title-მიმართვა': 'title-reference',
+    'ქვედა-კოლონტიტულზე-მიმართვა': 'footnote-reference',
+    'ციტატაზე-მიმართვა': 'citation-reference',
+    'სამიზნე': 'target',
+    'დაუმუშავებელი': 'raw',
+    }
+"""Mapping of Georgian role names to canonical role names for interpreted text.
+"""