Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[10007] trunk/docutils
|
From: <mi...@us...> - 2025-01-31 10:15:45
|
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.
|
