SF.net SVN: docutils:[10210] trunk/docutils
milde--- via Docutils-checkins <[email protected]> Tue, 19 Aug 2025 18:38:12 +0000
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 10210
http://sourceforge.net/p/docutils/code/10210
Author: milde
Date: 2025-08-19 18:38:11 +0000 (Tue, 19 Aug 2025)
Log Message:
-----------
latex writer: Fix/simplify footnote handling.
In Docutils, reference names for footnotes, citations, and
hyperlinks use the same namespace.
Change the definitions of `\DUfootnotemark` and `\DUfootnotetext`
(use `\label` and `\hyperref` instead of `\hypertarget`
and `\hyperlink`) to get corresponding behaviour in LaTeX.
This allows to remove the additional creation of a `\label` for
footnotes with "autonumber-label".
Adapt tests.
Modified Paths:
--------------
trunk/docutils/docutils/writers/latex2e/__init__.py
trunk/docutils/docutils/writers/latex2e/docutils.sty
trunk/docutils/test/functional/expected/latex_leavevmode.tex
trunk/docutils/test/functional/expected/latex_literal_block.tex
trunk/docutils/test/functional/expected/latex_literal_block_fancyvrb.tex
trunk/docutils/test/functional/expected/latex_literal_block_listings.tex
trunk/docutils/test/functional/expected/latex_literal_block_verbatim.tex
trunk/docutils/test/functional/expected/latex_literal_block_verbatimtab.tex
trunk/docutils/test/functional/expected/latex_memoir.tex
trunk/docutils/test/functional/expected/length_units_latex.tex
trunk/docutils/test/functional/expected/standalone_rst_latex.tex
trunk/docutils/test/functional/expected/standalone_rst_xetex.tex
trunk/docutils/test/test_writers/test_latex2e.py
trunk/docutils/test/test_writers/test_latex2e_parts.py
Modified: trunk/docutils/docutils/writers/latex2e/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/latex2e/__init__.py 2025-08-19 18:37:57 UTC (rev 10209)
+++ trunk/docutils/docutils/writers/latex2e/__init__.py 2025-08-19 18:38:11 UTC (rev 10210)
@@ -1359,7 +1359,7 @@
else:
# require a minimal version:
self.fallbacks['_docutils.sty'] = (
- r'\usepackage{docutils}[2024-09-24]')
+ r'\usepackage{docutils}[2025-08-06]')
self.stylesheet = [self.stylesheet_call(path)
for path in stylesheet_list]
@@ -2335,9 +2335,6 @@
num = '[%s]' % num
self.out.append('%%\n\\DUfootnotetext{%s}{%s}{%s}{' %
(node['ids'][0], backref, self.encode(num)))
- 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):
self.out.append('%')
Modified: trunk/docutils/docutils/writers/latex2e/docutils.sty
===================================================================
--- trunk/docutils/docutils/writers/latex2e/docutils.sty 2025-08-19 18:37:57 UTC (rev 10209)
+++ trunk/docutils/docutils/writers/latex2e/docutils.sty 2025-08-19 18:38:11 UTC (rev 10210)
@@ -22,7 +22,7 @@
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{docutils}
- [2024-09-24 macros for Docutils LaTeX output]
+ [2025-08-06 macros for Docutils LaTeX output]
% Helpers
% -------
@@ -124,15 +124,15 @@
% footnotes::
-% numerical or symbol footnotes with hyperlinks and backlinks
+% numbered or symbol footnotes with hyperlinks and backlinks
\providecommand*{\DUfootnotemark}[3]{%
\raisebox{1em}{\hypertarget{#1}{}}%
- \hyperlink{#2}{\textsuperscript{#3}}%
+ \hyperref[#2]{\textsuperscript{#3}}%
}
\providecommand{\DUfootnotetext}[4]{%
\begingroup%
\renewcommand{\thefootnote}{%
- \protect\raisebox{1em}{\protect\hypertarget{#1}{}}%
+ \protect\phantomsection\protect\label{#1}
\protect\hyperlink{#2}{#3}}%
\footnotetext{#4}%
\endgroup%
Modified: trunk/docutils/test/functional/expected/latex_leavevmode.tex
===================================================================
--- trunk/docutils/test/functional/expected/latex_leavevmode.tex 2025-08-19 18:37:57 UTC (rev 10209)
+++ trunk/docutils/test/functional/expected/latex_leavevmode.tex 2025-08-19 18:38:11 UTC (rev 10210)
@@ -74,15 +74,15 @@
{\enddescription\endquote}
\fi
-% numerical or symbol footnotes with hyperlinks and backlinks
+% numbered or symbol footnotes with hyperlinks and backlinks
\providecommand*{\DUfootnotemark}[3]{%
\raisebox{1em}{\hypertarget{#1}{}}%
- \hyperlink{#2}{\textsuperscript{#3}}%
+ \hyperref[#2]{\textsuperscript{#3}}%
}
\providecommand{\DUfootnotetext}[4]{%
\begingroup%
\renewcommand{\thefootnote}{%
- \protect\raisebox{1em}{\protect\hypertarget{#1}{}}%
+ \protect\phantomsection\protect\label{#1}
\protect\hyperlink{#2}{#3}}%
\footnotetext{#4}%
\endgroup%
@@ -385,7 +385,7 @@
\end{DUclass}
\item[{Footnote}] %
-\DUfootnotetext{f1}{f1}{1}{\phantomsection\label{f1}%
+\DUfootnotetext{f1}{f1}{1}{%
This footnote will move to the bottom of the page.
}
Modified: trunk/docutils/test/functional/expected/latex_literal_block.tex
===================================================================
--- trunk/docutils/test/functional/expected/latex_literal_block.tex 2025-08-19 18:37:57 UTC (rev 10209)
+++ trunk/docutils/test/functional/expected/latex_literal_block.tex 2025-08-19 18:38:11 UTC (rev 10210)
@@ -19,7 +19,7 @@
%%% User specified packages and stylesheets
%%% Fallback definitions for Docutils-specific commands
-\usepackage{docutils}[2024-09-24]
+\usepackage{docutils}[2025-08-06]
% character width in monospaced font
\newlength{\ttemwidth}
Modified: trunk/docutils/test/functional/expected/latex_literal_block_fancyvrb.tex
===================================================================
--- trunk/docutils/test/functional/expected/latex_literal_block_fancyvrb.tex 2025-08-19 18:37:57 UTC (rev 10209)
+++ trunk/docutils/test/functional/expected/latex_literal_block_fancyvrb.tex 2025-08-19 18:38:11 UTC (rev 10210)
@@ -19,7 +19,7 @@
%%% User specified packages and stylesheets
%%% Fallback definitions for Docutils-specific commands
-\usepackage{docutils}[2024-09-24]
+\usepackage{docutils}[2025-08-06]
% character width in monospaced font
\newlength{\ttemwidth}
Modified: trunk/docutils/test/functional/expected/latex_literal_block_listings.tex
===================================================================
--- trunk/docutils/test/functional/expected/latex_literal_block_listings.tex 2025-08-19 18:37:57 UTC (rev 10209)
+++ trunk/docutils/test/functional/expected/latex_literal_block_listings.tex 2025-08-19 18:38:11 UTC (rev 10210)
@@ -25,7 +25,7 @@
%%% User specified packages and stylesheets
%%% Fallback definitions for Docutils-specific commands
-\usepackage{docutils}[2024-09-24]
+\usepackage{docutils}[2025-08-06]
% character width in monospaced font
\newlength{\ttemwidth}
Modified: trunk/docutils/test/functional/expected/latex_literal_block_verbatim.tex
===================================================================
--- trunk/docutils/test/functional/expected/latex_literal_block_verbatim.tex 2025-08-19 18:37:57 UTC (rev 10209)
+++ trunk/docutils/test/functional/expected/latex_literal_block_verbatim.tex 2025-08-19 18:38:11 UTC (rev 10210)
@@ -18,7 +18,7 @@
%%% User specified packages and stylesheets
%%% Fallback definitions for Docutils-specific commands
-\usepackage{docutils}[2024-09-24]
+\usepackage{docutils}[2025-08-06]
% character width in monospaced font
\newlength{\ttemwidth}
Modified: trunk/docutils/test/functional/expected/latex_literal_block_verbatimtab.tex
===================================================================
--- trunk/docutils/test/functional/expected/latex_literal_block_verbatimtab.tex 2025-08-19 18:37:57 UTC (rev 10209)
+++ trunk/docutils/test/functional/expected/latex_literal_block_verbatimtab.tex 2025-08-19 18:38:11 UTC (rev 10210)
@@ -19,7 +19,7 @@
%%% User specified packages and stylesheets
%%% Fallback definitions for Docutils-specific commands
-\usepackage{docutils}[2024-09-24]
+\usepackage{docutils}[2025-08-06]
% character width in monospaced font
\newlength{\ttemwidth}
Modified: trunk/docutils/test/functional/expected/latex_memoir.tex
===================================================================
--- trunk/docutils/test/functional/expected/latex_memoir.tex 2025-08-19 18:37:57 UTC (rev 10209)
+++ trunk/docutils/test/functional/expected/latex_memoir.tex 2025-08-19 18:38:11 UTC (rev 10210)
@@ -88,15 +88,15 @@
{\enddescription\endquote}
\fi
-% numerical or symbol footnotes with hyperlinks and backlinks
+% numbered or symbol footnotes with hyperlinks and backlinks
\providecommand*{\DUfootnotemark}[3]{%
\raisebox{1em}{\hypertarget{#1}{}}%
- \hyperlink{#2}{\textsuperscript{#3}}%
+ \hyperref[#2]{\textsuperscript{#3}}%
}
\providecommand{\DUfootnotetext}[4]{%
\begingroup%
\renewcommand{\thefootnote}{%
- \protect\raisebox{1em}{\protect\hypertarget{#1}{}}%
+ \protect\phantomsection\protect\label{#1}
\protect\hyperlink{#2}{#3}}%
\footnotetext{#4}%
\endgroup%
@@ -709,7 +709,7 @@
This is the footnote's second paragraph.
}
%
-\DUfootnotetext{label}{footnote-reference-3}{2}{\phantomsection\label{label}%
+\DUfootnotetext{label}{footnote-reference-3}{2}{%
Footnotes may be numbered, either manually (as in\DUfootnotemark{footnote-reference-5}{footnote-1}{1}) or
automatically using a \textquotedbl{}\#\textquotedbl{}-prefixed label. This footnote has a
label so it can be referred to from multiple places, both as a
Modified: trunk/docutils/test/functional/expected/length_units_latex.tex
===================================================================
--- trunk/docutils/test/functional/expected/length_units_latex.tex 2025-08-19 18:37:57 UTC (rev 10209)
+++ trunk/docutils/test/functional/expected/length_units_latex.tex 2025-08-19 18:38:11 UTC (rev 10210)
@@ -22,7 +22,7 @@
\usepackage{nohyperref}
%%% Fallback definitions for Docutils-specific commands
-\usepackage{docutils}[2024-09-24]
+\usepackage{docutils}[2025-08-06]
\ifdefined\DUchdimen % lengh unit "ch": width of a zero char
\else
Modified: trunk/docutils/test/functional/expected/standalone_rst_latex.tex
===================================================================
--- trunk/docutils/test/functional/expected/standalone_rst_latex.tex 2025-08-19 18:37:57 UTC (rev 10209)
+++ trunk/docutils/test/functional/expected/standalone_rst_latex.tex 2025-08-19 18:38:11 UTC (rev 10210)
@@ -92,15 +92,15 @@
{\enddescription\endquote}
\fi
-% numerical or symbol footnotes with hyperlinks and backlinks
+% numbered or symbol footnotes with hyperlinks and backlinks
\providecommand*{\DUfootnotemark}[3]{%
\raisebox{1em}{\hypertarget{#1}{}}%
- \hyperlink{#2}{\textsuperscript{#3}}%
+ \hyperref[#2]{\textsuperscript{#3}}%
}
\providecommand{\DUfootnotetext}[4]{%
\begingroup%
\renewcommand{\thefootnote}{%
- \protect\raisebox{1em}{\protect\hypertarget{#1}{}}%
+ \protect\phantomsection\protect\label{#1}
\protect\hyperlink{#2}{#3}}%
\footnotetext{#4}%
\endgroup%
@@ -703,7 +703,7 @@
This is the footnote’s second paragraph.
}
%
-\DUfootnotetext{label}{footnote-reference-3}{2}{\phantomsection\label{label}%
+\DUfootnotetext{label}{footnote-reference-3}{2}{%
Footnotes may be numbered, either manually (as in\DUfootnotemark{footnote-reference-5}{footnote-1}{1}) or
automatically using a “\#”-prefixed label. This footnote has a
label so it can be referred to from multiple places, both as a
Modified: trunk/docutils/test/functional/expected/standalone_rst_xetex.tex
===================================================================
--- trunk/docutils/test/functional/expected/standalone_rst_xetex.tex 2025-08-19 18:37:57 UTC (rev 10209)
+++ trunk/docutils/test/functional/expected/standalone_rst_xetex.tex 2025-08-19 18:38:11 UTC (rev 10210)
@@ -33,7 +33,7 @@
%%% User specified packages and stylesheets
%%% Fallback definitions for Docutils-specific commands
-\usepackage{docutils}[2024-09-24]
+\usepackage{docutils}[2025-08-06]
\newcounter{enumv}
\DUprovidelength{\pdfpxdimen}{1bp}
@@ -695,7 +695,7 @@
This is the footnote’s second paragraph.
}
%
-\DUfootnotetext{label}{footnote-reference-3}{2}{\phantomsection\label{label}%
+\DUfootnotetext{label}{footnote-reference-3}{2}{%
Footnotes may be numbered, either manually (as in\DUfootnotemark{footnote-reference-5}{footnote-1}{1}) or
automatically using a “\#”-prefixed label. This footnote has a
label so it can be referred to from multiple places, both as a
Modified: trunk/docutils/test/test_writers/test_latex2e.py
===================================================================
--- trunk/docutils/test/test_writers/test_latex2e.py 2025-08-19 18:37:57 UTC (rev 10209)
+++ trunk/docutils/test/test_writers/test_latex2e.py 2025-08-19 18:38:11 UTC (rev 10210)
@@ -7,7 +7,7 @@
"""
Tests for latex2e writer.
-This module test only the "body" part of the output.
+This module tests only the "body" part of the output.
For tests of constructs that change the "head", see test-latex2e_parts.py.
"""
@@ -377,7 +377,7 @@
Just a test citation [my_cite2006]_.
.. [my_cite2006]
- The underscore is mishandled.
+ Watch the underscore!
""",
r"""
Just a test citation \cite{my_cite2006}.
@@ -384,7 +384,7 @@
\begin{thebibliography}{my\_cite2006}
\bibitem[my\_cite2006]{my_cite2006}{
-The underscore is mishandled.
+Watch the underscore!
}
\end{thebibliography}
"""],
@@ -499,6 +499,161 @@
"""],
])
+samples['docutils-footnotes'] = ({}, [
+# different markup variants
+[r"""
+Paragraphs contain text and may contain footnote references (manually
+numbered [1]_, anonymous auto-numbered [#]_, labeled auto-numbered
+[#label]_, or symbolic [*]_).
+.. [1] A footnote.
+
+.. [#label] Footnotes may be numbered, either manually or
+ automatically using a "#"-prefixed label. This footnote has a
+ label so it can be referred to from multiple places, both as a
+ footnote reference ([#label]_) and as a `hyperlink reference`__.
+
+ __ label_
+
+.. [#] This footnote is numbered automatically and anonymously using a
+ label of "#" only.
+
+.. [*] Footnotes may also use symbols, specified with a "*" label.
+""",
+ r"""
+Paragraphs contain text and may contain footnote references (manually
+numbered\DUfootnotemark{footnote-reference-1}{footnote-1}{1}, anonymous auto-numbered\DUfootnotemark{footnote-reference-2}{footnote-2}{3}, labeled auto-numbered\DUfootnotemark{footnote-reference-3}{label}{2}, or symbolic\DUfootnotemark{footnote-reference-4}{footnote-3}{*}).
+%
+\DUfootnotetext{footnote-1}{footnote-reference-1}{1}{%
+A footnote.
+}
+%
+\DUfootnotetext{label}{footnote-reference-3}{2}{%
+Footnotes may be numbered, either manually or
+automatically using a \textquotedbl{}\#\textquotedbl{}-prefixed label. This footnote has a
+label so it can be referred to from multiple places, both as a
+footnote reference (\DUfootnotemark{footnote-reference-5}{label}{2}) and as a \hyperref[label]{hyperlink reference}.
+}
+%
+\DUfootnotetext{footnote-2}{footnote-reference-2}{3}{%
+This footnote is numbered automatically and anonymously using a
+label of \textquotedbl{}\#\textquotedbl{} only.
+}
+%
+\DUfootnotetext{footnote-3}{footnote-reference-4}{*}{%
+Footnotes may also use symbols, specified with a \textquotedbl{}*\textquotedbl{} label.
+}
+"""],
+# nested footnotes
+["""\
+It's possible to produce nested footnotes in LaTeX. [#]_
+
+.. [#] It takes some work, though. [#]_
+.. [#] And don't even get me started on how tricky recursive footnotes
+ would be.
+""",
+r"""
+It's possible to produce nested footnotes in LaTeX.\DUfootnotemark{footnote-reference-1}{footnote-1}{1}
+%
+\DUfootnotetext{footnote-1}{footnote-reference-1}{1}{%
+It takes some work, though.\DUfootnotemark{footnote-reference-2}{footnote-2}{2}
+}
+%
+\DUfootnotetext{footnote-2}{footnote-reference-2}{2}{%
+And don't even get me started on how tricky recursive footnotes
+would be.
+}
+"""],
+# chained footnotes
+["""\
+It's possible to produce chained footnotes in LaTeX. [#]_
+
+.. [#] They're just a special case of nested footnotes. [#]_
+.. [#] A nested footnote is a footnote on a footnote. [#]_
+.. [#] This is a footnote on a footnote on a footnote.
+""",
+r"""
+It's possible to produce chained footnotes in LaTeX.\DUfootnotemark{footnote-reference-1}{footnote-1}{1}
+%
+\DUfootnotetext{footnote-1}{footnote-reference-1}{1}{%
+They're just a special case of nested footnotes.\DUfootnotemark{footnote-reference-2}{footnote-2}{2}
+}
+%
+\DUfootnotetext{footnote-2}{footnote-reference-2}{2}{%
+A nested footnote is a footnote on a footnote.\DUfootnotemark{footnote-reference-3}{footnote-3}{3}
+}
+%
+\DUfootnotetext{footnote-3}{footnote-reference-3}{3}{%
+This is a footnote on a footnote on a footnote.
+}
+"""],
+# multi-nested footnotes
+["""\
+A footnote [#multi]_
+
+.. [#multi] This is a footnote with nested [#]_ footnotes. [#]_ [#]_
+
+.. [#] First nested [#]_ footnote. [#]_
+
+.. [#] Second nested footnote. [#]_
+
+.. [#] Third nested footnote.
+
+.. [#] First double-nested footnote.
+
+.. [#] Second double-nested footnote.
+
+.. [#] First triple-nested footnote.
+
+.. [#] Not nested, referenced after footnote text.
+
+Ref to a new footnote [#]_
+
+A second reference to the first one [#multi]_.
+We can also write a hyperlink to multi_.
+""",
+r"""
+A footnote\DUfootnotemark{footnote-reference-1}{multi}{1}
+%
+\DUfootnotetext{multi}{footnote-reference-1}{1}{%
+This is a footnote with nested\DUfootnotemark{footnote-reference-2}{footnote-1}{2} footnotes.\DUfootnotemark{footnote-reference-3}{footnote-2}{3}\DUfootnotemark{footnote-reference-4}{footnote-3}{4}
+}
+%
+\DUfootnotetext{footnote-1}{footnote-reference-2}{2}{%
+First nested\DUfootnotemark{footnote-reference-5}{footnote-4}{5} footnote.\DUfootnotemark{footnote-reference-6}{footnote-5}{6}
+}
+%
+\DUfootnotetext{footnote-2}{footnote-reference-3}{3}{%
+Second nested footnote.\DUfootnotemark{footnote-reference-7}{footnote-6}{7}
+}
+%
+\DUfootnotetext{footnote-3}{footnote-reference-4}{4}{%
+Third nested footnote.
+}
+%
+\DUfootnotetext{footnote-4}{footnote-reference-5}{5}{%
+First double-nested footnote.
+}
+%
+\DUfootnotetext{footnote-5}{footnote-reference-6}{6}{%
+Second double-nested footnote.
+}
+%
+\DUfootnotetext{footnote-6}{footnote-reference-7}{7}{%
+First triple-nested footnote.
+}
+%
+\DUfootnotetext{footnote-7}{footnote-reference-8}{8}{%
+Not nested, referenced after footnote text.
+}
+
+Ref to a new footnote\DUfootnotemark{footnote-reference-8}{footnote-7}{8}
+
+A second reference to the first one\DUfootnotemark{footnote-reference-9}{multi}{1}.
+We can also write a hyperlink to \hyperref[multi]{multi}.
+"""],
+])
+
+
if __name__ == '__main__':
unittest.main()
Modified: trunk/docutils/test/test_writers/test_latex2e_parts.py
===================================================================
--- trunk/docutils/test/test_writers/test_latex2e_parts.py 2025-08-19 18:37:57 UTC (rev 10209)
+++ trunk/docutils/test/test_writers/test_latex2e_parts.py 2025-08-19 18:38:11 UTC (rev 10210)
@@ -191,15 +191,15 @@
}
""",
'fallbacks': r"""
-% numerical or symbol footnotes with hyperlinks and backlinks
+% numbered or symbol footnotes with hyperlinks and backlinks
\providecommand*{\DUfootnotemark}[3]{%
\raisebox{1em}{\hypertarget{#1}{}}%
- \hyperlink{#2}{\textsuperscript{#3}}%
+ \hyperref[#2]{\textsuperscript{#3}}%
}
\providecommand{\DUfootnotetext}[4]{%
\begingroup%
\renewcommand{\thefootnote}{%
- \protect\raisebox{1em}{\protect\hypertarget{#1}{}}%
+ \protect\phantomsection\protect\label{#1}
\protect\hyperlink{#2}{#3}}%
\footnotetext{#4}%
\endgroup%
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