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

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Revision: 9955
          http://sourceforge.net/p/docutils/code/9955
Author:   milde
Date:     2024-10-20 18:57:49 +0000 (Sun, 20 Oct 2024)
Log Message:
-----------
Small fixes and additions.

Be more specific in FAQ answer.

Don't list minor fix (bug #287) in HISTORY.

Shorten some docstrings to adhere to documentation policy
(multi-line docstrings should be summary line, blank line, details).

Better name for function factory that returns a keyword validating function.
(cf. https://stackoverflow.com/questions/3368830/how-to-name-factory-like-methods).

Fix attribute name mismatch "autonum" -> "auto".

Explain F401 noqa comment.

Fix typo in "writers/html5_polyglot/minimal.css" stylesheet.

Avoid confusing variable name ``twidth`` in latex writer.

Modified Paths:
--------------
    trunk/docutils/FAQ.rst
    trunk/docutils/HISTORY.rst
    trunk/docutils/docutils/nodes.py
    trunk/docutils/docutils/transforms/parts.py
    trunk/docutils/docutils/utils/__init__.py
    trunk/docutils/docutils/writers/html5_polyglot/minimal.css
    trunk/docutils/docutils/writers/latex2e/__init__.py
    trunk/docutils/test/functional/tests/standalone_rst_docutils_xml.py
    trunk/docutils/test/test_nodes.py

Modified: trunk/docutils/FAQ.rst
===================================================================

--- trunk/docutils/FAQ.rst	2024-10-20 17:47:14 UTC (rev 9954)
+++ trunk/docutils/FAQ.rst	2024-10-20 18:57:49 UTC (rev 9955)
@@ -1051,8 +1051,8 @@
 Why do enumerated lists only use numbers (no letters or roman numerals)?
 ------------------------------------------------------------------------
 
-The rendering of enumerators (the numbers or letters acting as list
-markers) is completely governed by the stylesheet, so either the
+In HTML, the rendering of enumerators (the numbers or letters acting as
+list markers) is completely governed by the stylesheet, so either the
 browser can't find the stylesheet (try enabling the
 `embed_stylesheet`_ setting [``--embed-stylesheet`` option]), or the
 browser can't understand it (try a not too old Firefox, Chrome, Opera,

Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst	2024-10-20 17:47:14 UTC (rev 9954)
+++ trunk/docutils/HISTORY.rst	2024-10-20 18:57:49 UTC (rev 9955)
@@ -29,8 +29,6 @@
     Python >= 3.10 is required with active type hints
     (``typing.TYPE_CHECKING == True``).
 
-  - Fix license issue (bug #487).
-
 * docs/ref/docutils.dtd
 
   - Allow multiple <term> elements in a <definition_list_item>.

Modified: trunk/docutils/docutils/nodes.py
===================================================================
--- trunk/docutils/docutils/nodes.py	2024-10-20 17:47:14 UTC (rev 9954)
+++ trunk/docutils/docutils/nodes.py	2024-10-20 18:57:49 UTC (rev 9955)
@@ -1772,8 +1772,7 @@
         """Mapping of substitution names to substitution_definition nodes."""
 
         self.substitution_names: dict[str, str] = {}
-        """Mapping of case-normalized substitution names to case-sensitive
-        names."""
+        """Mapping of case-normalized to case-sensitive substitution names."""
 
         self.refnames: dict[str, list[Element]] = {}
         """Mapping of names to lists of referencing nodes."""
@@ -1785,8 +1784,8 @@
         """Mapping of names to unique id's."""
 
         self.nametypes: dict[str, bool] = {}
-        """Mapping of names to hyperlink type (boolean: True => explicit,
-        False => implicit."""
+        """Mapping of names to hyperlink type. True: explicit, False: implicit.
+        """
 
         self.ids: dict[str, Element] = {}
         """Mapping of ids to nodes."""
@@ -3112,7 +3111,7 @@
 # __ https://docutils.sourceforge.io/docs/ref/doctree.html#attribute-reference
 # __ https://docutils.sourceforge.io/docs/ref/doctree.html#attribute-types
 
-def validate_enumerated_type(*keywords: str) -> Callable[[str], str]:
+def create_keyword_validator(*keywords: str) -> Callable[[str], str]:
     """
     Return a function that validates a `str` against given `keywords`.
 
@@ -3248,12 +3247,12 @@
     'colwidth': int,  # sic! CALS: CDATA (measure or number+'*')
     'content': str,  # <meta>
     'delimiter': str,
-    'dir': validate_enumerated_type('ltr', 'rtl', 'auto'),  # <meta>
+    'dir': create_keyword_validator('ltr', 'rtl', 'auto'),  # <meta>
     'dupnames': validate_refname_list,
-    'enumtype': validate_enumerated_type('arabic', 'loweralpha', 'lowerroman',
+    'enumtype': create_keyword_validator('arabic', 'loweralpha', 'lowerroman',
                                          'upperalpha', 'upperroman'),
     'format': str,  # CDATA (space separated format names)
-    'frame': validate_enumerated_type('top', 'bottom', 'topbot', 'all',
+    'frame': create_keyword_validator('top', 'bottom', 'topbot', 'all',
                                       'sides', 'none'),  # from CALS, ignored
     'height': validate_measure,
     'http-equiv': str,  # <meta>
@@ -3262,7 +3261,7 @@
     'level': int,
     'line': int,
     'ltrim': validate_yesorno,
-    'loading': validate_enumerated_type('embed', 'link', 'lazy'),
+    'loading': create_keyword_validator('embed', 'link', 'lazy'),
     'media': str,  # <meta>
     'morecols': int,
     'morerows': int,
@@ -3287,9 +3286,9 @@
     'title': str,
     'type': validate_NMTOKEN,
     'uri': str,
-    'valign': validate_enumerated_type('top', 'middle', 'bottom'),  # from CALS
+    'valign': create_keyword_validator('top', 'middle', 'bottom'),  # from CALS
     'width': validate_measure,
-    'xml:space': validate_enumerated_type('default', 'preserve'),
+    'xml:space': create_keyword_validator('default', 'preserve'),
     }
 """
 Mapping of `attribute names`__ to validating functions.

Modified: trunk/docutils/docutils/transforms/parts.py
===================================================================
--- trunk/docutils/docutils/transforms/parts.py	2024-10-20 17:47:14 UTC (rev 9954)
+++ trunk/docutils/docutils/transforms/parts.py	2024-10-20 18:57:49 UTC (rev 9955)
@@ -20,7 +20,7 @@
     Automatically assigns numbers to the titles of document sections.
 
     It is possible to limit the maximum section level for which the numbers
-    are added.  For those sections that are auto-numbered, the "autonum"
+    are added.  For those sections that are auto-numbered, the "auto"
     attribute is set, informing the contents table generator that a different
     form of the TOC should be used.
     """

Modified: trunk/docutils/docutils/utils/__init__.py
===================================================================
--- trunk/docutils/docutils/utils/__init__.py	2024-10-20 17:47:14 UTC (rev 9954)
+++ trunk/docutils/docutils/utils/__init__.py	2024-10-20 18:57:49 UTC (rev 9955)
@@ -23,7 +23,7 @@
 from docutils import ApplicationError, DataError
 from docutils import io, nodes
 # for backwards compatibility
-from docutils.nodes import unescape  # noqa: F401
+from docutils.nodes import unescape  # noqa: F401 (imported but unused)
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Sequence, Iterable

Modified: trunk/docutils/docutils/writers/html5_polyglot/minimal.css
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/minimal.css	2024-10-20 17:47:14 UTC (rev 9954)
+++ trunk/docutils/docutils/writers/html5_polyglot/minimal.css	2024-10-20 18:57:49 UTC (rev 9955)
@@ -1,4 +1,4 @@
-t/* Minimal style sheet for the HTML output of Docutils.                    */
+/* Minimal style sheet for the HTML output of Docutils.                    */
 /*                                                                         */
 /* :Author: Günter Milde, based on html4css1.css by David Goodger          */
 /* :Id: $Id$                                                               */

Modified: trunk/docutils/docutils/writers/latex2e/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/latex2e/__init__.py	2024-10-20 17:47:14 UTC (rev 9954)
+++ trunk/docutils/docutils/writers/latex2e/__init__.py	2024-10-20 18:57:49 UTC (rev 9955)
@@ -1067,8 +1067,8 @@
                 n_c = len(self._col_specs)
                 a.append('\\endhead\n')
                 # footer on all but last page (if it fits):
-                twidth = sum(node['colwidth']+2 for node in self._col_specs)
-                if twidth > 30 or (twidth > 12 and not self.colwidths_auto):
+                t_width = sum(node['colwidth']+2 for node in self._col_specs)
+                if t_width > 30 or (t_width > 12 and not self.colwidths_auto):
                     a.append(r'\multicolumn{%d}{%s}'
                              % (n_c, self.get_multicolumn_width(0, n_c))
                              + r'{\raggedleft\ldots continued on next page}\\'

Modified: trunk/docutils/test/functional/tests/standalone_rst_docutils_xml.py
===================================================================
--- trunk/docutils/test/functional/tests/standalone_rst_docutils_xml.py	2024-10-20 17:47:14 UTC (rev 9954)
+++ trunk/docutils/test/functional/tests/standalone_rst_docutils_xml.py	2024-10-20 18:57:49 UTC (rev 9955)
@@ -6,7 +6,6 @@
 writer = "docutils_xml"
 settings_overrides = {
     'sectsubtitle_xform': True,
-    # format output with indents and newlines
-    'indents': True,
+    'indents': True,  # format output with indents and newlines
     'validate': True,  # check conformance to Docutils Generic DTD
     }

Modified: trunk/docutils/test/test_nodes.py
===================================================================
--- trunk/docutils/test/test_nodes.py	2024-10-20 17:47:14 UTC (rev 9954)
+++ trunk/docutils/test/test_nodes.py	2024-10-20 18:57:49 UTC (rev 9955)
@@ -1140,9 +1140,9 @@
     __ https://docutils.sourceforge.io/docs/ref/doctree.html#attribute-types
     """
 
-    def test_validate_enumerated_type(self):
+    def test_create_keyword_validator(self):
         # function factory for "choice validators"
-        food = nodes.validate_enumerated_type('ham', 'spam')
+        food = nodes.create_keyword_validator('ham', 'spam')
         self.assertEqual(food('ham'), 'ham')
         with self.assertRaisesRegex(ValueError,
                                     '"bacon" is not one of "ham", "spam".'):

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.



