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

Revision: 10152
          http://sourceforge.net/p/docutils/code/10152
Author:   milde
Date:     2025-06-02 19:20:17 +0000 (Mon, 02 Jun 2025)
Log Message:
-----------
Announce deprecation of `<target>` elements with content. Prepare "latex" writer.

The `<target>` element has 2 use cases:

a) as empty "body element" to provide a "name" attribute for the next
   body element (via the `references.PropagateTargets` transform)
   or to map a reference name to a "refid" or "refuri".

b) as "inline element" with text content to provide an anchor.

For use case b), the generic `<inline>` element is equally well suited.
Deprecation of the inline use simplifies the definition and validation
of `<target>` elements (only valid as empty block-level element).

Change `LaTeXTranslator.visit_inline()` to insert labels for the given node's IDs.
(Preparation for the future use of `<inline>` for inline anchors and generally
a good idea.)

Modified Paths:
--------------
    trunk/docutils/HISTORY.rst
    trunk/docutils/RELEASE-NOTES.rst
    trunk/docutils/docutils/writers/latex2e/__init__.py

Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst	2025-06-01 15:39:34 UTC (rev 10151)
+++ trunk/docutils/HISTORY.rst	2025-06-02 19:20:17 UTC (rev 10152)
@@ -20,6 +20,8 @@
 * docutils/writers/latex2e/__init__.py
 
   - Replace `Writer.bibtex_reference_resolver()` with a transform.
+  - `LaTeXTranslator.visit_inline()` now inserts labels for the
+    node's IDs.
 
 * docutils/transforms/references.py
 

Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst	2025-06-01 15:39:34 UTC (rev 10151)
+++ trunk/docutils/RELEASE-NOTES.rst	2025-06-02 19:20:17 UTC (rev 10152)
@@ -59,6 +59,12 @@
 * The "rst" parser will warn if a `"figure"`_ directive is missing both
   caption and legend in Docutils 1.0.
 
+* The "rst" parser will use <inline> elements for inline targets
+  in Docutils 1.0.
+
+* <target> elements with content will be deprecated in Docutils 1.0
+  and invalid in Docutils 2.0.
+
 * To match the definition in the "Exchange Table Model", the
   `"colwidth" attribute`_ will be stored as a `str` (instead of
   numerical) value in Python element instances in Docutils 1.0.

Modified: trunk/docutils/docutils/writers/latex2e/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/latex2e/__init__.py	2025-06-01 15:39:34 UTC (rev 10151)
+++ trunk/docutils/docutils/writers/latex2e/__init__.py	2025-06-02 19:20:17 UTC (rev 10152)
@@ -1765,7 +1765,6 @@
 
     def visit_caption(self, node) -> None:
         self.out.append('\n\\caption{')
-        self.out += self.ids_to_labels(node, set_anchor=False)
         self.visit_inline(node)
 
     def depart_caption(self, node) -> None:
@@ -2334,7 +2333,8 @@
                 num = '[%s]' % num
             self.out.append('%%\n\\DUfootnotetext{%s}{%s}{%s}{' %
                             (node['ids'][0], backref, self.encode(num)))
-            if node['ids'] == node['names']:
+            if node['ids'] == [nodes.make_id(n) for n in node['names']]:
+                # autonumber-label: create anchor
                 self.out += self.ids_to_labels(node)
             # prevent spurious whitespace if footnote starts with paragraph:
             if len(node) > 1 and isinstance(node[1], nodes.paragraph):
@@ -2505,7 +2505,17 @@
     def depart_image(self, node) -> None:
         self.out += self.ids_to_labels(node, newline=True)
 
-    def visit_inline(self, node) -> None:  # <span>, i.e. custom roles
+    def visit_inline(self, node) -> None:
+        # This function is also called by the visiting functions for
+        # specific inline elements, <caption>, and <paragraph>.
+
+        # Handle "ids" attribute:
+        # do we need a \phantomsection?
+        set_anchor = not (isinstance(node.parent, (nodes.caption, nodes.title))
+                          or isinstance(node, nodes.caption))
+        add_newline = isinstance(node, nodes.paragraph)
+        self.out += self.ids_to_labels(node, set_anchor, newline=add_newline)
+        # Handle "classes" attribute:
         for cls in node['classes']:
             if cls.startswith('language-'):
                 language = self.babel.language_name(cls[9:])
@@ -2705,15 +2715,19 @@
 
     def visit_math(self, node, math_env='$'):
         """math role"""
-        self.visit_inline(node)
         self.requirements['amsmath'] = r'\usepackage{amsmath}'
         math_code = node.astext().translate(unichar2tex.uni2tex_table)
         if math_env == '$':
+            self.visit_inline(node)
             if self.alltt:
                 wrapper = ['\\(', '\\)']
             else:
                 wrapper = ['$', '$']
         else:
+            for cls in node['classes']:
+                if not self.fallback_stylesheet:
+                    self.fallbacks['inline'] = PreambleCmds.inline
+                self.out.append(r'\DUrole{%s}{' % cls)
             labels = self.ids_to_labels(node, set_anchor=False, newline=True)
             wrapper = ['%%\n\\begin{%s}\n' % math_env,
                        '\n',
@@ -2814,7 +2828,6 @@
                 self.out.append('\n')
         else:
             self.out.append('\n')
-        self.out += self.ids_to_labels(node, newline=True)
         self.visit_inline(node)
 
     def depart_paragraph(self, node) -> None:
@@ -3111,13 +3124,10 @@
             ## self.out.append('%% %s\n' % node)   # for debugging
             return
         self.out.append('%\n')
-        # do we need an anchor (\phantomsection)?
-        set_anchor = not isinstance(node.parent, (nodes.caption, nodes.title))
-        # TODO: where else can/must we omit the \phantomsection?
-        self.out += self.ids_to_labels(node, set_anchor)
+        self.visit_inline(node)
 
     def depart_target(self, node) -> None:
-        pass
+        self.depart_inline(node)
 
     def visit_tbody(self, node) -> None:
         # BUG write preamble if not yet done (colspecs not [])

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