Refer to the "pycmark" CommonMark parser and other documentation fixes.

git-svn-id: https://svn.code.sf.net/p/docutils/code/trunk@8942 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

3 files changed, 38 insertions, 18 deletions

diff --git a/docutils/docs/user/config.txt b/docutils/docs/user/config.txt
index bd0a943e4..6a8a203bd 100644
--- a/docutils/docs/user/config.txt
+++ b/docutils/docs/user/config.txt
@@ -348,6 +348,8 @@ The threshold at or above which system messages are converted to
 exceptions, halting execution immediately.  If `traceback`_ is set, the
 exception will propagate; otherwise, Docutils will exit.
 
+See also report_level_.
+
 Default: severe (4).  Options: ``--halt, --strict``.
 
 id_prefix
@@ -485,6 +487,8 @@ Report system messages at or higher than <level>:
 4  severe
 5  none
 
+See also halt_level_.
+
 Default: warning (2).
 Options: ``--report, -r, --verbose, -v, --quiet, -q``.
 
@@ -818,17 +822,6 @@ Options: ``--trim-footnote-reference-space, --leave-footnote-reference-space``.
    and it is left if the reference style is "brackets".
 
 
-.. _recommonmark:
-
-[recommonmark parser]
----------------------
-
-Experimental, based on recommonmark__.
-Currently no configuration settings.
-
-__ https://pypi.org/project/recommonmark/
-
-
 .. _myst:
 
 [myst parser]
@@ -845,6 +838,29 @@ See `MyST with Docutils`_ and its `Sphinx configuration options`_
    https://myst-parser.readthedocs.io/en/latest/sphinx/reference.html#sphinx-config-options
 
 
+.. _pycmark:
+
+[pycmark parser]
+----------------
+
+Provided by the 3rd party package `pycmark`__.
+Currently no configuration settings.
+
+__ https://pypi.org/project/pycmark/
+
+
+
+.. _recommonmark:
+
+[recommonmark parser]
+---------------------
+
+Provisional, depends on (deprecated) 3rd-party package recommonmark__.
+Currently no configuration settings.
+
+__ https://pypi.org/project/recommonmark/
+
+
 [readers]
 =========
 
@@ -2166,8 +2182,10 @@ Option: ``--reader``
 parser
 ~~~~~~
 Parser component name.
-One of "rst", "markdown", "recommonmark_", "myst_",
-or the import name of a drop-in parser module.
+Either "rst" (default) or the import name of a drop-in parser module.
+
+Parsers for CommonMark_ known to work with Docutils include "pycmark_",
+"myst_", and "recommonmark_".
 
 Default: "rst".
 Option: ``--parser``
@@ -2184,6 +2202,8 @@ or the import name of a drop-in writer module.
 Default: "html5".
 Option: ``--writer``
 
+.. _CommonMark: https://spec.commonmark.org/0.30/
+
 
 Other Settings
 ==============
diff --git a/docutils/docutils/transforms/frontmatter.py b/docutils/docutils/transforms/frontmatter.py
index 8b523b406..d8be367bd 100644
--- a/docutils/docutils/transforms/frontmatter.py
+++ b/docutils/docutils/transforms/frontmatter.py
@@ -503,9 +503,10 @@ class DocInfo(Transform):
             raise
 
     def authors_from_one_paragraph(self, field):
-        """Return list of Text nodes for authornames.
-
-        The set of separators is locale dependent (default: ";"- or ",").
+        """Return list of Text nodes with author names in `field`.
+        
+        Author names must be separated by one of the "autor separators"
+        defined for the document language (default: ";" or ",").
         """
         # @@ keep original formatting? (e.g. ``:authors: A. Test, *et-al*``)
         text = ''.join(str(node)
diff --git a/docutils/test/test_writers/test_docutils_xml.py b/docutils/test/test_writers/test_docutils_xml.py
index d4b9179f7..b9bbe43ed 100755
--- a/docutils/test/test_writers/test_docutils_xml.py
+++ b/docutils/test/test_writers/test_docutils_xml.py
@@ -194,8 +194,7 @@ class DocutilsXMLTestCase(DocutilsTestSupport.StandardTestCase):
              u'<string>:10: '
              u'(WARNING/2) Invalid raw XML in column 30, line offset 1:\n',
              u'<test>inline raw XML&lt;/test>\n'])
-        # abort with SystemMessage if halt_level is "info":
-        settings['halt_level'] = 2
+        settings['halt_level'] = 2 # convert info messages to exceptions
         settings['warning_stream'] = ''
         self.assertRaises(docutils.utils.SystemMessage,
                           publish_xml, settings, invalid_raw_xml_source)