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

Revision: 10147
          http://sourceforge.net/p/docutils/code/10147
Author:   milde
Date:     2025-05-27 06:15:14 +0000 (Tue, 27 May 2025)
Log Message:
-----------
LaTeX writer: Use a transform to resolve BibTeX references.

The 'use_bibtex' setting indicates that citation entries are fetched
from a BibTeX database by the backend (LaTeX).
Use a transfrom instead of the deprecated "unknown_reference_resolvers"
hook chain to mark citation_references as resolved.

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

Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst	2025-05-27 06:14:22 UTC (rev 10146)
+++ trunk/docutils/HISTORY.rst	2025-05-27 06:15:14 UTC (rev 10147)
@@ -17,8 +17,16 @@
 Release 0.22rc3 (unpublished)
 =============================
 
-* nothing yet.
+* docutils/writers/latex2e/__init__.py
 
+  - Replace `Writer.bibtex_reference_resolver()` with a transform.
+
+* docutils/transforms/references.py
+
+  - New transform `CitationReferences`. Marks citation_references
+    as resolved if BibTeX is used by the backend (LaTeX).
+
+
 Release 0.22rc2 (2025-05-22)
 ============================
 

Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst	2025-05-27 06:14:22 UTC (rev 10146)
+++ trunk/docutils/RELEASE-NOTES.rst	2025-05-27 06:15:14 UTC (rev 10147)
@@ -164,7 +164,8 @@
 * Remove the input_encoding_ auto-detection code in Docutils 1.0.
 
 * Remove the "TransformSpec.unknown_reference_resolvers" hook chain
-  in Docutils 1.0.  Use a transform.
+  in Docutils 1.0.  Use a transform, see
+  `transforms.references.CitationReferences` for an example.
 
 * Remove `parsers.rst.roles.set_classes()` and
   `parsers.rst.roles.normalized_role_options()`
@@ -230,7 +231,10 @@
 Release 0.22rc3 (unpublished)
 =============================
 
-* nothing yet.
+New objects
+  `transforms.references.`CitationReferences`
+     Mark citation_references as resolved if the backend (LaTeX)
+     uses a BibTeX database.
 
 Release 0.22rc2 (2025-05-22)
 ============================

Modified: trunk/docutils/docs/api/transforms.rst
===================================================================
--- trunk/docutils/docs/api/transforms.rst	2025-05-27 06:14:22 UTC (rev 10146)
+++ trunk/docutils/docs/api/transforms.rst	2025-05-27 06:15:14 UTC (rev 10147)
@@ -97,6 +97,8 @@
 
 peps_.PEPZero                       peps.Headers (t/p)            760
 
+references_.CitationReferences      latex2e (w)                   770
+
 components.Filter                   *not used*                    780
 
 universal_.Decorations              Reader (r)                    820
@@ -205,6 +207,7 @@
 
 writers.latex2e.Writer
   writer_aux.Admonitions
+  references.CitationReferences
 
 writers._html_base.Writer:
   writer_aux.Admonitions

Modified: trunk/docutils/docutils/transforms/references.py
===================================================================
--- trunk/docutils/docutils/transforms/references.py	2025-05-27 06:14:22 UTC (rev 10146)
+++ trunk/docutils/docutils/transforms/references.py	2025-05-27 06:15:14 UTC (rev 10147)
@@ -842,6 +842,31 @@
         return footnote
 
 
+class CitationReferences(Transform):
+    """Resolve <citation_references>.
+
+    The 'use_bibtex'__ configuration setting indicates that citation entries
+    are fetched from a BibTeX database by the backend (LaTeX).
+
+    __ https://docutils.sourceforge.io/docs/user/config.html#use-bibtex
+    """
+    # TODO: Bibliography database support for other output formats.
+
+    default_priority = 770
+    # Apply between `InternalTargets` (660) and `DanglingReferences` (850)
+
+    def apply(self) -> None:
+        if not getattr(self.document.settings, 'use_bibtex', []):
+            return
+        for node in self.document.findall(nodes.citation_reference):
+            # Skip nodes that are resolved or have a matching target:
+            if node.resolved or self.document.nameids.get(node.get('refname')):
+                continue
+            if node.astext():  # ensure text content (becomes the BibTeX key)
+                node.delattr('refname')
+                node.resolved = True
+
+
 class DanglingReferences(Transform):
 
     """

Modified: trunk/docutils/docutils/writers/latex2e/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/latex2e/__init__.py	2025-05-27 06:14:22 UTC (rev 10146)
+++ trunk/docutils/docutils/writers/latex2e/__init__.py	2025-05-27 06:15:14 UTC (rev 10147)
@@ -20,7 +20,7 @@
 from pathlib import Path
 
 from docutils import frontend, nodes, languages, writers, utils
-from docutils.transforms import writer_aux
+from docutils.transforms import references, writer_aux
 from docutils.utils._roman_numerals import RomanNumeral
 from docutils.utils.math import pick_math_environment, unichar2tex
 
@@ -254,29 +254,13 @@
     def __init__(self) -> None:
         writers.Writer.__init__(self)
         self.translator_class = LaTeXTranslator
-        self.unknown_reference_resolvers = [self.bibtex_reference_resolver]
-        self.bibtex_reference_resolver.priority = 400
 
-    @staticmethod
-    def bibtex_reference_resolver(node: nodes.Element) -> bool:
-        """Mark citation references as resolved if BibTeX is used.
-
-        Cf. `TransformSpec.unknown_reference_resolvers`.
-        """
-        if (isinstance(node, nodes.citation_reference)
-            and node.document.settings.use_bibtex):
-            del node['refname']
-            node.resolved = True
-            return True
-        else:
-            return False
-
     def get_transforms(self):
         # Override parent method to add latex-specific transforms
         return super().get_transforms() + [
                    # Convert specific admonitions to generic one
                    writer_aux.Admonitions,
-                   # TODO: footnote collection transform
+                   references.CitationReferences,
                    ]
 
     def translate(self) -> None:

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