SF.net SVN: docutils:[10007 ] trunk/docutils

Revision: 10007
          http://sourceforge.net/p/docutils/code/10007
Author:   milde
Date:     2025-01-31 10:15:44 +0000 (Fri, 31 Jan 2025)
Log Message:
-----------
LaTeX writer: Fixes for section numbering by LaTeX.

Document the internal settings "sectnum_depth", "sectnum_start",
"sectnum_prefix" and "sectnum_suffix".
Silently ignore configuration file values for these settings
(documented behaviour of internal settings) instead of raising
a ValueError.

Simplify logic and gather it in `Transformer.visit_section()`:
Do not set LaTeX-specific default values for the internal settings.
Do not (ab)use an empty requirement value to mark section number configuration
as done.

Add test cases.

Modified Paths:
--------------
    trunk/docutils/docs/user/config.rst
    trunk/docutils/docutils/writers/latex2e/__init__.py
    trunk/docutils/test/test_writers/test_latex2e_parts.py

Modified: trunk/docutils/docs/user/config.rst
===================================================================
--- trunk/docutils/docs/user/config.rst	2025-01-16 09:50:06 UTC (rev 10006)
+++ trunk/docutils/docs/user/config.rst	2025-01-31 10:15:44 UTC (rev 10007)
@@ -614,13 +614,17 @@
 sectnum_xform
 -------------
 
-Enable automatic section numbering by Docutils
-(`docutils.transforms.parts.SectNum`) associated
-with the `"sectnum" directive`_.
+Enable automatic section numbering by Docutils (`SectNum` transform_
+associated with the `"sectnum" directive`_).
 
-If disabled, section numbers might be added to the output by the
-renderer (e.g. by CSS style rules or by LaTeX).
+If disabled, the `SectNum` transform adds the `internal settings`_
+sectnum_depth_, sectnum_start_, sectnum_prefix_, and sectnum_suffix_
+to store the respective `"sectnum" directive options`__.
+Section numbers may be added to the output by the renderer
+(e.g. by CSS style rules or LaTeX).
 
+__ ../ref/rst/directives.html#sectnum-options
+
 :Default: True.
 :Options: ``--section-numbering``, ``--no-section-numbering``.
 
@@ -2399,13 +2403,13 @@
 
 These settings are for internal use only; setting them in
 configuration files has no effect, and there are no corresponding
-command-line options.
+command-line options (except for `_destination`_).
 
 _config_files
 ~~~~~~~~~~~~~
 List of paths of applied configuration files.
 
-*Default*: None.  No command-line options.
+*Default*: None.
 
 _directories
 ~~~~~~~~~~~~
@@ -2414,15 +2418,14 @@
 List of paths to source directories, set from `positional arguments
 <tools.html#buildhtml-py>`__.
 
+*Default*: None (current working directory).
 
-*Default*: None (current working directory).  No command-line options.
-
 _disable_config
 ~~~~~~~~~~~~~~~
 Prevent standard configuration files from being read.
 For command-line use, set the DOCUTILSCONFIG_ variable.
 
-:Default: None (config files enabled).  No command-line options.
+:Default: None (config files enabled).
 
 _destination
 ~~~~~~~~~~~~
@@ -2433,13 +2436,40 @@
 
 *Default*: None (stdout).  *Option*: ``--output``.
 
-
 _source
 ~~~~~~~
 Path to input source, set from `positional arguments`_.
 
-*Default*: None (stdin).  No command-line options.
+*Default*: None (stdin).
 
+sectnum_depth
+~~~~~~~~~~~~~
+Stores the value of the `"sectnum" directive`_'s "depth" option
+if sectnum_xform_ is False.
+
+No default. [#SectNum]_
+
+sectnum_prefix
+~~~~~~~~~~~~~~
+Stores the value of the `"sectnum" directive`_'s "prefix" option
+if sectnum_xform_ is False.
+
+No default. [#SectNum]_
+
+sectnum_start
+~~~~~~~~~~~~~
+Stores the value of the `"sectnum" directive`_'s "start" option
+if sectnum_xform_ is False.
+
+No default. [#SectNum]_
+
+sectnum_suffix
+~~~~~~~~~~~~~~
+Stores the value of the `"sectnum" directive`_'s "suffix" option
+if sectnum_xform_ is False.
+
+No default. [#SectNum]_
+
 --------------------------------------------------------------------------
 
 .. [#override] The overridden setting will automatically be set to
@@ -2462,6 +2492,9 @@
    buildhtml_ application are resolved relative to the directory of
    the respective configuration file.
 
+.. [#SectNum] Added by the `SectNum` transform_, if and only if there
+   is a `"sectnum" directive`_ in the source document.
+
 __ https://docs.python.org/3/library/codecs.html#codecs.register
 
 

Modified: trunk/docutils/docutils/writers/latex2e/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/latex2e/__init__.py	2025-01-16 09:50:06 UTC (rev 10006)
+++ trunk/docutils/docutils/writers/latex2e/__init__.py	2025-01-31 10:15:44 UTC (rev 10007)
@@ -238,8 +238,7 @@
         )
 
     relative_path_settings = ('template',)
-    settings_defaults = {'sectnum_depth': 0,
-                         'sectnum_start': 1}  # updated by SectNum transform
+    settings_defaults = {}
     config_section = 'latex2e writer'
     config_section_dependencies = ('writers', 'latex writers')
 
@@ -2021,8 +2020,7 @@
             self.out.append('\n\\faketableofcontents % for local ToCs\n')
         # * conditional requirements (before style sheet)
         self.requirements = [self.requirements[key]
-                             for key in sorted(self.requirements.keys())
-                             if self.requirements[key]]
+                             for key in sorted(self.requirements.keys())]
         # * coditional fallback definitions (after style sheet)
         self.fallbacks = [self.fallbacks[key]
                           for key in sorted(self.fallbacks.keys())]
@@ -2884,27 +2882,29 @@
         # counter for this section's level (initialized by parent section)
         self._section_number[self.section_level - 1] += 1
 
-        # Add LaTeX section numbering configuration code to requirements.
+        # Section numbering configuration
         if 'sectnum' in self.requirements:
             return  # already done
-        # settings.sectnum_depth values:
+        # sectnum_depth values:
         #    0    no section numbering or section numbering by Docutils
         #   >0    value of "sectnum"'s :depth: option (1 = top level section)
         #   None  "sectnum" directive without depth arg -> keep default
         if self.settings.sectnum_xform:  # section numbering by Docutils
-            sectnum_depth = 0
-        else:  # section numbering by LaTeX:
-            sectnum_depth = self.settings.sectnum_depth
-            if self.settings.sectnum_start != 1:
-                self.requirements['sectnum_start'] = (
-                    r'\setcounter{%s}{%d}' % (self.d_class.sections[0],
-                                              self.settings.sectnum_start-1))
+            sectnum_depth = 0  # suppress LaTeX section numbers
+        else:
+            sectnum_depth = getattr(self.settings, 'sectnum_depth', 0)
+            if isinstance(sectnum_depth, str):
+                sectnum_depth = 0  # ignore values from config files
+            sectnum_start = getattr(self.settings, 'sectnum_start', 1)
+            if isinstance(sectnum_start, str):
+                sectnum_start = 1  # ignore values from config files
+            if sectnum_start != 1:
+                self.requirements['sectnum_start'] = r'\setcounter{%s}{%d}' % (
+                    self.d_class.sections[0], sectnum_start-1)
             # TODO: currently ignored (configure in a stylesheet):
             # settings.sectnum_prefix
             # settings.sectnum_suffix
-        if sectnum_depth is None:
-            self.requirements['sectnum'] = ''
-        else:
+        if sectnum_depth is not None:
             self.requirements['sectnum'] = r'\setcounter{secnumdepth}{%d}' % (
                 self.d_class.latex_section_depth(sectnum_depth))
 

Modified: trunk/docutils/test/test_writers/test_latex2e_parts.py
===================================================================
--- trunk/docutils/test/test_writers/test_latex2e_parts.py	2025-01-16 09:50:06 UTC (rev 10006)
+++ trunk/docutils/test/test_writers/test_latex2e_parts.py	2025-01-31 10:15:44 UTC (rev 10007)
@@ -959,25 +959,72 @@
 ])
 
 
-samples['sectnum_xform False'] = ({'sectnum_xform': False}, [
-# no section numbers
+# section numbering by LaTeX
+samples['sectnum_xform False'] = ({'sectnum_xform': False,
+                                   # ignore str values of internal settings:
+                                   'sectnum_start': '42',
+                                   'sectnum_depth': '3'
+                                   }, [
 ["""\
-some text
+no sectnum directive -> suppress section numbers
 
-first section
--------------
+section
+-------
 """,
  {'body': r"""
-some text
+no sectnum directive -> suppress section numbers
 
 
-\section{first section%
-  \label{first-section}%
+\section{section%
+  \label{section}%
 }
 """,
   'requirements': '\\usepackage[T1]{fontenc}\n'
                   '\\setcounter{secnumdepth}{0}\n',
   }],
+['no sectnum directive and no section -> no requirements',
+ {'body': '\nno sectnum directive and no section -> no requirements\n'
+  }],
+
+["""\
+default section numbers -> no requirements
+
+.. sectnum::
+
+section
+-------
+""",
+ {'body': r"""
+default section numbers -> no requirements
+
+
+\section{section%
+  \label{section}%
+}
+""",
+  }],
+["""\
+section numbers with custom start and depth
+
+.. sectnum::
+   :start: 7
+   :depth: 2
+
+section
+-------
+""",
+ {'body': r"""
+section numbers with custom start and depth
+
+
+\section{section%
+  \label{section}%
+}
+""",
+  'requirements': '\\usepackage[T1]{fontenc}\n'
+                  '\\setcounter{secnumdepth}{2}\n'
+                  '\\setcounter{section}{6}\n',
+  }],
 ])
 
 samples['stylesheet_path'] = ({'stylesheet_path': f'{spam},{ham}'}, [

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