[Docutils-checkins] SF.net SVN: docutils:[9312] trunk/docutils

[<mi...@us...>]

Revision: 9312
          http://sourceforge.net/p/docutils/code/9312
Author:   milde
Date:     2022-12-19 20:43:08 +0000 (Mon, 19 Dec 2022)
Log Message:
-----------
Fix [bugs:#384]: allow omission of citations with "use_bibtex" setting.

If the "use_bibtex" LaTeX writer setting is active (i.e. not empty),
citations are added by LaTeX/BibTeX from a database for all citation references
in the document.
The reference resolver transform now skips `citation_reference` nodes instead of
expecting matching `citation` nodes in this case.

"use_bibtex" content is now transformed to a list by the
`frontend.validate_comma_separated_list()` validator.
As BibTeX works only with "LaTeX citations", the "use_latex_citations" setting
is set to True whenever "use_bibtex" is not empty.

Update documentation.

The test function, added in the last commit, now passes.

Modified Paths:
--------------
    trunk/docutils/HISTORY.txt
    trunk/docutils/docs/user/config.txt
    trunk/docutils/docutils/transforms/references.py
    trunk/docutils/docutils/writers/latex2e/__init__.py

Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt	2022-12-19 20:42:55 UTC (rev 9311)
+++ trunk/docutils/HISTORY.txt	2022-12-19 20:43:08 UTC (rev 9312)
@@ -45,6 +45,12 @@
   - `Transformer.populate_from_components()` now silently ignores
     components that are not instances of `docutils.TransformSpec`.
 
+* docutils/transforms/references.py
+
+  - Ignore `citation_reference` nodes if the "use_bibex" setting is
+    active. In this case, citations are provided by LaTeX/BibTeX.
+    Fixes bug #384.
+
 * docutils/utils/__init__.py
 
   - New utility function `xml_declaration()`.
@@ -79,6 +85,7 @@
 
   - Do not insert ``\usepackage[utf8]{inputenc}`` into UTF-8 encoded
     LaTeX sources. UTF-8 is the default encoding for LaTeX2e since 2018.
+  - Fix handling of the "use_bibtex" setting.
 
 * docutils/writers/latex2e/titlepage.tex
 

Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt	2022-12-19 20:42:55 UTC (rev 9311)
+++ trunk/docutils/docs/user/config.txt	2022-12-19 20:43:08 UTC (rev 9312)
@@ -100,8 +100,9 @@
 
 List values can be comma- or colon-delimited.
 
-strip_classes_, strip_elements_with_classes_, stylesheet, and
-stylesheet_path use the comma as delimiter,
+strip_classes_, strip_elements_with_classes_, smartquotes_locales_, 
+stylesheet, stylesheet_dirs, stylesheet_path, legacy_class_functions_,
+and use_bibtex_ use the comma as delimiter,
 whitespace around list values is stripped. ::
 
     strip-classes: ham,eggs,
@@ -1849,14 +1850,17 @@
 Default: writer dependent (see `[latex2e writer]`_, `[xetex writer]`_).
 Option: ``--template``.
 
-
 use_bibtex
 ~~~~~~~~~~
-Specify style and database for the experimental `BibTeX` support, for
-example::
 
-  --use-bibtex=mystyle,mydb1,mydb2
+Provisional, name, values, and behaviour may change in future versions
+or the option may be removed.
 
+A comma-separated list of style and database(s) for the experimental
+`BibTeX` support, for example::
+
+  --use-bibtex=unsrt,mydb1,mydb2
+
 Default: "" (don't use BibTeX).  Option ``--use-bibtex``.
 
 use_latex_abstract

Modified: trunk/docutils/docutils/transforms/references.py
===================================================================
--- trunk/docutils/docutils/transforms/references.py	2022-12-19 20:42:55 UTC (rev 9311)
+++ trunk/docutils/docutils/transforms/references.py	2022-12-19 20:43:08 UTC (rev 9312)
@@ -893,6 +893,11 @@
                 if resolver_function(node):
                     break
             else:
+                if (getattr(self.document.settings, 'use_bibtex', False)
+                    and isinstance(node, nodes.citation_reference)):
+                    # targets added from BibTeX database by LaTeX
+                    node.resolved = True
+                    return
                 if refname in self.document.nameids:
                     msg = self.document.reporter.error(
                         'Duplicate target name, cannot be used as a unique '
@@ -899,7 +904,7 @@
                         'reference: "%s".' % (node['refname']), base_node=node)
                 else:
                     msg = self.document.reporter.error(
-                        'Unknown target name: "%s".' % (node['refname']),
+                        f'Unknown target name: "{node["refname"]}".',
                         base_node=node)
                 msgid = self.document.set_id(msg)
                 prb = nodes.problematic(
@@ -914,6 +919,6 @@
             del node['refname']
             node['refid'] = id
             self.document.ids[id].note_referenced_by(id=id)
-            node.resolved = 1
+            node.resolved = True
 
     visit_footnote_reference = visit_citation_reference = visit_reference

Modified: trunk/docutils/docutils/writers/latex2e/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/latex2e/__init__.py	2022-12-19 20:42:55 UTC (rev 9311)
+++ trunk/docutils/docutils/writers/latex2e/__init__.py	2022-12-19 20:43:08 UTC (rev 9312)
@@ -199,10 +199,12 @@
           'number or the page number.',
           ['--reference-label'],
           {'default': ''}),
-         ('Specify style and database for bibtex, for example '
-          '"--use-bibtex=mystyle,mydb1,mydb2".',
+         ('Specify style and database(s) for bibtex, for example '
+          '"--use-bibtex=unsrt,mydb1,mydb2". Provisional!',
           ['--use-bibtex'],
-          {'default': ''}),
+          {'default': '',
+           'metavar': '<style,bibfile[,bibfile,...]>',
+           'validator': frontend.validate_comma_separated_list}),
          ('Use legacy functions with class value list for '
           '\\DUtitle and \\DUadmonition.',
           ['--legacy-class-functions'],
@@ -1162,7 +1164,7 @@
         # ~~~~~~~~
         self.settings = settings = document.settings
         # warn of deprecated settings and changing defaults:
-        if settings.use_latex_citations is None:
+        if settings.use_latex_citations is None and not settings.use_bibtex:
             settings.use_latex_citations = False
             warnings.warn('The default for the setting "use_latex_citations" '
                           'will change to "True" in Docutils 1.0.',
@@ -1202,11 +1204,9 @@
         elif settings.use_verbatim_when_possible:
             self.literal_block_env = 'verbatim'
 
-        if self.settings.use_bibtex:
-            self.bibtex = self.settings.use_bibtex.split(',', 1)
-            # TODO avoid errors on not declared citations.
-        else:
-            self.bibtex = None
+        if settings.use_bibtex:
+            self.use_latex_citations = True
+        self.bibtex = settings.use_bibtex
         # language module for Docutils-generated text
         # (labels, bibliographic_fields, and author_separators)
         self.language_module = languages.get_language(settings.language_code,
@@ -1213,7 +1213,7 @@
                                                       document.reporter)
         self.babel = babel_class(settings.language_code, document.reporter)
         self.author_separator = self.language_module.author_separators[0]
-        d_options = [self.settings.documentoptions]
+        d_options = [settings.documentoptions]
         if self.babel.language not in ('english', ''):
             d_options.append(self.babel.language)
         self.documentoptions = ','.join(filter(None, d_options))
@@ -1220,11 +1220,11 @@
         self.d_class = DocumentClass(settings.documentclass,
                                      settings.use_part_section)
         # graphic package options:
-        if self.settings.graphicx_option == '':
+        if settings.graphicx_option == '':
             self.graphicx_package = r'\usepackage{graphicx}'
         else:
             self.graphicx_package = (r'\usepackage[%s]{graphicx}' %
-                                     self.settings.graphicx_option)
+                                     settings.graphicx_option)
         # footnotes: TODO: implement LaTeX footnotes
         self.docutils_footnotes = settings.docutils_footnotes
 
@@ -1234,7 +1234,7 @@
         # Document parts
         self.head_prefix = [r'\documentclass[%s]{%s}' %
                             (self.documentoptions,
-                             self.settings.documentclass)]
+                             settings.documentclass)]
         self.requirements = SortableDict()  # made a list in depart_document()
         self.requirements['__static'] = r'\usepackage{ifthen}'
         self.latex_preamble = [settings.latex_preamble]
@@ -1329,7 +1329,7 @@
         if self.fallback_stylesheet:
             stylesheet_list = [sheet for sheet in stylesheet_list
                                if sheet != 'docutils']
-            if self.settings.legacy_class_functions:
+            if settings.legacy_class_functions:
                 # docutils.sty is incompatible with legacy functions
                 self.fallback_stylesheet = False
             else:
@@ -1806,6 +1806,8 @@
             self.out.append('\\end{figure}\n')
 
     def visit_citation_reference(self, node):
+        if self.bibtex:
+            self._bibitems.append([node.astext()])
         if self.use_latex_citations:
             if not self.inside_citation_reference_label:
                 self.out.append(r'\cite{')
@@ -2037,24 +2039,23 @@
 
         # * bibliography
         #   TODO insertion point of bibliography should be configurable.
-        if self.use_latex_citations and len(self._bibitems) > 0:
-            if not self.bibtex:
-                widest_label = ''
-                for bi in self._bibitems:
-                    if len(widest_label) < len(bi[0]):
-                        widest_label = bi[0]
-                self.out.append('\n\\begin{thebibliography}{%s}\n' %
-                                widest_label)
-                for bi in self._bibitems:
-                    # cite_key: underscores must not be escaped
-                    cite_key = bi[0].replace(r'\_', '_')
-                    self.out.append('\\bibitem[%s]{%s}{%s}\n' %
-                                    (bi[0], cite_key, bi[1]))
-                self.out.append('\\end{thebibliography}\n')
-            else:
-                self.out.append('\n\\bibliographystyle{%s}\n' %
-                                self.bibtex[0])
-                self.out.append('\\bibliography{%s}\n' % self.bibtex[1])
+        if self.bibtex and self._bibitems:
+            self.out.append('\n\\bibliographystyle{%s}\n' % self.bibtex[0])
+            self.out.append('\\bibliography{%s}\n' % ','.join(self.bibtex[1:]))
+        elif self.use_latex_citations and self._bibitems:
+            # TODO: insert citations at point of definition.
+            widest_label = ''
+            for bibitem in self._bibitems:
+                if len(widest_label) < len(bibitem[0]):
+                    widest_label = bibitem[0]
+            self.out.append('\n\\begin{thebibliography}{%s}\n' %
+                            widest_label)
+            for bibitem in self._bibitems:
+                # cite_key: underscores must not be escaped
+                cite_key = bibitem[0].replace(r'\_', '_')
+                self.out.append('\\bibitem[%s]{%s}{%s}\n' %
+                                (bibitem[0], cite_key, bibitem[1]))
+            self.out.append('\\end{thebibliography}\n')
         # * make sure to generate a toc file if needed for local contents:
         if 'minitoc' in self.requirements and not self.has_latex_toc:
             self.out.append('\n\\faketableofcontents % for local ToCs\n')

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