SF.net SVN: docutils:[10012 ] trunk

Revision: 10012
          http://sourceforge.net/p/docutils/code/10012
Author:   milde
Date:     2025-02-21 23:16:17 +0000 (Fri, 21 Feb 2025)
Log Message:
-----------
Small documentation fixes.

Modified Paths:
--------------
    trunk/docutils/HISTORY.rst
    trunk/docutils/RELEASE-NOTES.rst
    trunk/docutils/docs/user/config.rst
    trunk/docutils/docutils.conf
    trunk/sandbox/enhancement-proposals/input-encoding/dep-999-input-encoding.txt
    trunk/sandbox/enhancement-proposals/settings-API/cf_parser.py

Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst	2025-02-20 10:07:20 UTC (rev 10011)
+++ trunk/docutils/HISTORY.rst	2025-02-21 23:16:17 UTC (rev 10012)
@@ -153,6 +153,11 @@
   - Do not increase indentation of follow-up lines inside inline elements.
     when formatting with `indents`_.
 
+* docutils/writers/__init__.py
+
+  - New base class `writers.DoctreeTranslator`
+    with auxiliary method `uri2path()`.
+
 * docutils/writers/_html_base.py
 
   - Make MathML the default math_output_.
@@ -180,6 +185,8 @@
   - Support SVG image inclusion with the "svg" LaTeX package (see the
     `stylesheet`__ configuration setting).
   - Add "template" to the parts returned by `Writer.assemble_parts()`.
+  - Use standard `dict` for `LaTeXTranslator.requirements`
+    and`LaTeXTranslator.fallbacks`.
   - Use <document> "title" attribute in pdfinfo.
   - Encode <meta> element content in pdfinfo.
 

Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst	2025-02-20 10:07:20 UTC (rev 10011)
+++ trunk/docutils/RELEASE-NOTES.rst	2025-02-21 23:16:17 UTC (rev 10012)
@@ -279,6 +279,12 @@
      the `Docutils Document Model`_.
      Provisional.
 
+  `writers.DoctreeTranslator`
+     Generic Docutils document tree translator base class with
+     `uri2path()` auxiliary method.
+     Provisional.
+
+
 Removed objects
   `docutils.core.Publisher.setup_option_parser()`
      internal, obsolete,

Modified: trunk/docutils/docs/user/config.rst
===================================================================
--- trunk/docutils/docs/user/config.rst	2025-02-20 10:07:20 UTC (rev 10011)
+++ trunk/docutils/docs/user/config.rst	2025-02-21 23:16:17 UTC (rev 10012)
@@ -55,7 +55,7 @@
    located in the current directory.
    The Docutils front end has to be executed from the directory
    containing this configuration file for it to take effect (note that
-   this may have nothing to do with the location of the source files).
+   this directory may differ from the location of the source files).
 
 3. ``~/.docutils``: This is a user-specific configuration file,
    located in the user's home directory.
@@ -2498,10 +2498,13 @@
 __ https://docs.python.org/3/library/codecs.html#codecs.register
 
 
+Appendix
+========
+
 Old-Format Configuration Files
-==============================
+------------------------------
 
-Formerly, Docutils configuration files contained a single "[options]"
+Formerly, Docutils `configuration files`_ contained a single "[options]"
 section only.  This was found to be inflexible, and in August 2003
 Docutils adopted the current component-based configuration file
 sections as described above.
@@ -2524,7 +2527,7 @@
 .. _auto-detect:
 
 Input Encoding Auto-Detection
-=============================
+-----------------------------
 
 Up to Docutils 0.21, the input_encoding_ default value was ``None`` and
 the actual input encoding detected from a `Unicode byte order mark` (BOM_)
@@ -2537,7 +2540,7 @@
 Docutils 1.0.  See the `inspecting_codecs`_ package for a replacement.
 
 Encoding Declaration
---------------------
+~~~~~~~~~~~~~~~~~~~~
 
 Input encoding auto-detection scans the source for an
 *encoding declaration* inspired by :PEP:`263`:

Modified: trunk/docutils/docutils.conf
===================================================================
--- trunk/docutils/docutils.conf	2025-02-20 10:07:20 UTC (rev 10011)
+++ trunk/docutils/docutils.conf	2025-02-21 23:16:17 UTC (rev 10012)
@@ -22,6 +22,8 @@
 
 [buildhtml application]
 writer: html5
-# Prevent tools/buildhtml.py from processing certain text files.
-ignore: GPL2.rst:header.rst:header0.rst:header2.rst:cheatsheet.rst
+# Prevent tools/buildhtml.py from processing certain files.
+ignore: header.rst:header0.rst:header2.rst:cheatsheet.rst
+# ignore *.txt files:
+sources: *.rst
 prune: build:dist:docutils:docutils.egg-info:licenses:test:tools

Modified: trunk/sandbox/enhancement-proposals/input-encoding/dep-999-input-encoding.txt
===================================================================
--- trunk/sandbox/enhancement-proposals/input-encoding/dep-999-input-encoding.txt	2025-02-20 10:07:20 UTC (rev 10011)
+++ trunk/sandbox/enhancement-proposals/input-encoding/dep-999-input-encoding.txt	2025-02-21 23:16:17 UTC (rev 10012)
@@ -180,11 +180,9 @@
       changeable on a per-source file basis". [:PEP:`263`]
   -1  complicates code
 
-  → "Outsourced" to the "inspecting_codecs_" package.
+  → "Outsourced" to the "`inspecting codecs`_" package.
 
-  .. _inspecting_codecs: https://codeberg.org/milde/inspecting-codecs
 
-
 Open Issues
 ===========
 
@@ -213,6 +211,11 @@
 Patches #194 Deprecate PEP 263 coding slugs support
   https://sourceforge.net/p/docutils/patches/194/
 
+_`Inspecting codecs`:
+  | Codecs that determine the encoding by looking for a BOM
+    or encoding declaration.
+  | https://codeberg.org/milde/inspecting-codecs
+
 .. _input_encoding:
     https://docutils.sourceforge.io/docs/user/config.html#input-encoding
 .. _RELEASE-NOTES:

Modified: trunk/sandbox/enhancement-proposals/settings-API/cf_parser.py
===================================================================
--- trunk/sandbox/enhancement-proposals/settings-API/cf_parser.py	2025-02-20 10:07:20 UTC (rev 10011)
+++ trunk/sandbox/enhancement-proposals/settings-API/cf_parser.py	2025-02-21 23:16:17 UTC (rev 10012)
@@ -20,7 +20,7 @@
 * Reads and parses the sequence of configuration files passed to its
   `read()` method.
 
-* Stores the extracted setting values as stings.
+* Stores the extracted setting values as strings.
 
 * Collects settings from "active sections" in its ACTIVE section.
 
@@ -35,7 +35,7 @@
 # 
 # +1 Collecting "appending_settings" becomes easier.
 # 
-# -1 Require inheriting configparser.RawConfigParser to allow storing
+# -1 Requires inheriting configparser.RawConfigParser to allow storing
 #    values other than strings. 
 #    (Alternative: collect in ``dict`` instead of ACTIVE section.)
 # 
@@ -59,9 +59,8 @@
     from all "active sections".
     """
 
-    not_utf8_error = ('Unable to read configuration file "%s": '
-                      'content not encoded as UTF-8.\n'
-                      'Skipping "%s" configuration file.')
+    not_utf8_error = ('Skipping configuration file "%s": '
+                      'Unable to read, content not encoded as UTF-8.\n')
 
     def __init__(self, *args,
                  active_sections=(),
@@ -103,7 +102,7 @@
         self._appending_setting_lists = collections.defaultdict(list)
 
     def clear(self):
-        """Clear all settings. Restore ACTIVE section.
+        """Clear all settings. Add empty ACTIVE section.
 
         The DEFAULT and the ACTIVE sections are always present.
         Exception: after an explicit `<instance>['ACTIVE'].clear()`.
@@ -120,8 +119,8 @@
             # Config files are UTF-8-encoded:
             try:
                 read_ok += super().read(filename, encoding='utf-8')
-            except UnicodeDecodeError:
-                sys.stderr.write(self.not_utf8_error % (filename, filename))
+            except UnicodeDecodeError as e:
+                sys.stderr.write(self.not_utf8_error % filename + str(e))
                 continue
             self.handle_side_effects()
             self.collect_active_settings()

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



_______________________________________________
Docutils-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-checkins