docutils-develop Mailing List for Docutils: Documentation Utilities

Thank you for the report.
This will be fixed soon. (After sourceforge lets me commit from git-svn again...)


---

**[bugs:#507] renamed files**

**Status:** open
**Labels:** docs 
**Created:** Mon Jul 28, 2025 04:13 AM UTC by Chris Crawford
**Last Updated:** Mon Jul 28, 2025 04:13 AM UTC
**Owner:** nobody


some of the links are broken on 
https://docutils.sourceforge.io/rst.html
because .txt files were renamed to .rst:
https://docutils.sourceforge.io/docs/user/rst/quickstart.txt
https://docutils.sourceforge.io/docs/user/rst/cheatsheet.txt
there may be others


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

On Fri Jul 25, 2025 at 7:26 AM CEST, Guenter Milde via Docutils-develop wrote:
> The example article shows another problem: 
>
> In HTML it is simple to use footnotes as endnotes. In LaTeX, we would
> like a different layout for endnotes vs. footnotes. (The current
> implementation only works (almost) OK, if the footnotes are placed
> immediately after the block-level element with the footnote reference.)

I believe it just better to stick with the LaTeX solutions
(e. g., [1]) rather than to generate something even more crazy.
For HTML, it is IMHO quite enough the current way of having text
of notes placed wherever you do so in the source ([2]).

I see one more problem. When I put

    [xetex writer]
    latex_footnotes=True

into ./docutils.conf, it doesn’t make any difference, I have to
set `--latex-footnotes` on the command line. Any idea, where I
failed to hook into the configuration system properly?

> You may need to escape the letter or the dot, see the "Caution" admonition in 
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#enumerated-lists

Thank you for that, it helped.

Best,

Matěj

[1] https://tex.stackexchange.com/questions/56145/is-there-a-way-to-move-all-footnotes-to-the-end-of-the-document
[2] https://matej.ceplovi.cz/blog/harry-potter-poznamky-jako-odpoved.html
    (source https://git.sr.ht/~mcepl/blog-source/tree/master/item/literature/harry-potter-odpoved-brachovi.rst)
-- 
http://matej.ceplovi.cz/blog/, @mc...@en...wn
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
This is a signature anti-virus.
Please stop the spread of signature viruses!

Hi Matěj,

On 2025-07-21, Matěj Cepl wrote:

...
> I found to my unpleasant surprise
> that rst2xetex doesn’t produce correct LaTeX footnotes, but
> something weird, which certainly cannot be controlled by the
> standard LaTeX tools.

> I have found this patch, and decided to at least rebase it
> against the current master branch. I needed to fix tests, but
> otherwise the test suite now seems to pass.

> What do you think?

Thanks for the patch to a long-standing TODO item.
I'll look into it once the long overdue release 0.22 is out.

The example article shows another problem: 

In HTML it is simple to use footnotes as endnotes. In LaTeX, we would
like a different layout for endnotes vs. footnotes. (The current
implementation only works (almost) OK, if the footnotes are placed
immediately after the block-level element with the footnote reference.)

BTW: 

In your article, footnotes like ::

  .. [#] t. j. M. Aurelia a Lucia Vera.
  
are typeset "strange", because "t.", "j.", and "M." each start an
enumerated list (loweralpha) so you get 3 nested lists with just one item
"Aurelia a Lucia Vera".
You may need to escape the letter or the dot, see the "Caution" admonition in 
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#enumerated-lists

OTOH, ::

  .. [#] t, j. jelikož Loga se dohledali a dovážili násilným
     hledáním a rozvažováním.

does not become a list but I suspected that the comma is a typo.


Günter

I was trying to be as conservative as possible (and given the
length 1 of the suffix even .endswith() seemed like an overkill).
---
 docutils/docutils/writers/latex2e/__init__.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docutils/docutils/writers/latex2e/__init__.py b/docutils/docutils/writers/latex2e/__init__.py
index 4b6b0b431..3c9b082e0 100644
--- a/docutils/docutils/writers/latex2e/__init__.py
+++ b/docutils/docutils/writers/latex2e/__init__.py
@@ -2387,6 +2387,8 @@ def visit_footnote_reference(self, node) -> None:
                     self.push_output_collector([])
                     footnote.walkabout(self)
                     text = ''.join(self.out)
+                    if text[-1] == '\n':
+                        text = text[:-1]
                     self.pop_output_collector()
                     break
             else:
-- 
2.50.1

On Tue Jul 22, 2025 at 1:58 AM CEST, Matěj Cepl wrote:
> [1] https://git.sr.ht/~mcepl/justin_susil/tree/master/item/p_just_2_apol.rst

Resulting file

https://git.sr.ht/~mcepl/justin_susil/tree/master/item/p_just_2_apol.tex

looks reasonably well, only I am not certain about that EOL on
the end of each footnote text. Any suggestions how to get rid of that?

Best,

Matěj
-- 
http://matej.ceplovi.cz/blog/, @mc...@en...wn
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
My opinions may have changed, but not the fact that I am right.
    --Ashleigh Brilliant

From: John Thorvald Wodder II <gi...@va...>

Attached is a patch that implements the --latex-footnotes
option for 99% of use cases. I don't know whether you'd find it
satisfactory enough to accept, but I thought I'd at least try.

Shortcomings of this implementation:

 * Footnotes aren't hyperlinked back to their references.
   I am not aware of a way to solve this without basically
   reimplemeting docutils-footnotes.

 * Recursive footnotes are not supported and will cause
   a recursion error. Support would require tracking and
   referencing (à la https://tex.stackexchange.com/a/23158/) the
   number that LaTeX assigns to each footnote, which normally
   resets on chapters and would be broken by packages like
   footmisc and perpage.

 * If the same footnote is referenced multiple times, it will be
   treated as a new footnote each time. I believe this has the
   same solution as the above.

 * If a footnote contains two or more nested
   footnotes, the numbering will be messed up; see
   https://tex.stackexchange.com/q/38643/ for a way to address
   this.

Originally: https://sourceforge.net/p/docutils/patches/182/
---
 docutils/docutils/writers/latex2e/__init__.py |  91 +++++++++-----
 docutils/test/test_writers/test_latex2e.py    | 116 ++++++++++++++++++
 2 files changed, 179 insertions(+), 28 deletions(-)

diff --git a/docutils/docutils/writers/latex2e/__init__.py b/docutils/docutils/writers/latex2e/__init__.py
index b8264ee7d..1dcf13466 100644
--- a/docutils/docutils/writers/latex2e/__init__.py
+++ b/docutils/docutils/writers/latex2e/__init__.py
@@ -227,14 +227,17 @@ class Writer(writers.Writer):
           {'dest': 'legacy_column_widths',
            'action': 'store_false',
            'validator': frontend.validate_boolean}),
-         # TODO: implement "latex footnotes" alternative
-         ('Footnotes with numbers/symbols by Docutils. (default) '
-          '(The alternative, --latex-footnotes, is not implemented yet.)',
+         ('Footnotes with numbers/symbols by Docutils. (default)',
           ['--docutils-footnotes'],
           {'default': True,
            'action': 'store_true',
            'validator': frontend.validate_boolean}),
          ),
+         ('Footnotes with numbers by LaTeX.',
+           ['--latex-footnotes'],
+           {'dest': 'docutils_footnotes',
+            'action': 'store_false',
+            'validator': frontend.validate_boolean}),
         )
 
     relative_path_settings = ('template',)
@@ -1253,7 +1256,6 @@ def __init__(self, document, babel_class=Babel) -> None:
         else:
             self.graphicx_package = (r'\usepackage[%s]{graphicx}' %
                                      settings.graphicx_option)
-        # footnotes: TODO: implement LaTeX footnotes
         self.docutils_footnotes = settings.docutils_footnotes
 
         # Output collection stacks
@@ -1319,6 +1321,15 @@ def __init__(self, document, babel_class=Babel) -> None:
         self.out = self.body
         self.out_stack = []  # stack of output collectors
 
+        # Texts of nested footnotes to emit once we finish the topmost
+        # footnote.  footnote_queues[i] contains the text of footnotes
+        # encountered while processing the current footnote (which is nested
+        # within `i` higher footnotes).  If i == 0, they will be emitted
+        # immediately after the current footnote ends; if i > 0; they will be
+        # added to footnote_queues[i-1] after ending the current footnote,
+        # which is added to the same queue before them.
+        self.footnote_queues = []
+
         # Process settings
         # ~~~~~~~~~~~~~~~~
         # Encodings:
@@ -2324,11 +2335,11 @@ def depart_footer(self, node) -> None:
         self.pop_output_collector()
 
     def visit_footnote(self, node) -> None:
-        try:
-            backref = node['backrefs'][0]
-        except IndexError:
-            backref = node['ids'][0]  # no backref, use self-ref instead
         if self.docutils_footnotes:
+            try:
+                backref = node['backrefs'][0]
+            except IndexError:
+                backref = node['ids'][0] # no backref, use self-ref instead
             self.provide_fallback('footnotes')
             num = node[0].astext()
             if self.settings.footnote_references == 'brackets':
@@ -2341,10 +2352,12 @@ def visit_footnote(self, node) -> None:
             # prevent spurious whitespace if footnote starts with paragraph:
             if len(node) > 1 and isinstance(node[1], nodes.paragraph):
                 self.out.append('%')
-        # TODO: "real" LaTeX \footnote{}s (see visit_footnotes_reference())
+        elif not self.footnote_queues:
+            raise nodes.SkipNode
 
     def depart_footnote(self, node) -> None:
-        self.out.append('}\n')
+        if self.docutils_footnotes:
+            self.out.append('}\n')
 
     def visit_footnote_reference(self, node) -> None:
         href = ''
@@ -2352,25 +2365,47 @@ def visit_footnote_reference(self, node) -> None:
             href = node['refid']
         elif 'refname' in node:
             href = self.document.nameids[node['refname']]
-        # if not self.docutils_footnotes:
-        #     # TODO: insert footnote content at (or near) this place
-        #     #       see also docs/dev/todo.rst
-        #     try:
-        #         referenced_node = self.document.ids[node['refid']]
-        #     except (AttributeError, KeyError):
-        #         self.document.reporter.error(
-        #             'unresolved footnote-reference %s' % node)
-        #     print('footnote-ref to %s' % referenced_node)
-        format = self.settings.footnote_references
-        if format == 'brackets':
-            self.append_hypertargets(node)
-            self.out.append('\\hyperlink{%s}{[' % href)
-            self.context.append(']}')
+        if self.docutils_footnotes:
+            format = self.settings.footnote_references
+            if format == 'brackets':
+                self.append_hypertargets(node)
+                self.out.append('\\hyperlink{%s}{[' % href)
+                self.context.append(']}')
+            else:
+                if not self.fallback_stylesheet:
+                    self.fallbacks['footnotes'] = PreambleCmds.footnotes
+                self.out.append(r'\DUfootnotemark{%s}{%s}{' %
+                                (node['ids'][0], href))
+                self.context.append('}')
         else:
-            self.provide_fallback('footnotes')
-            self.out.append(r'\DUfootnotemark{%s}{%s}{' %
-                            (node['ids'][0], href))
-            self.context.append('}')
+            footnotes = (self.document.footnotes +
+                         self.document.autofootnotes +
+                         self.document.symbol_footnotes)
+            for footnote in footnotes:
+                if href in footnote['ids']:
+                    self.footnote_queues.append([])
+                    self.push_output_collector([])
+                    footnote.walkabout(self)
+                    text = ''.join(self.out)
+                    self.pop_output_collector()
+                    break
+            else:
+                self.document.reporter.error("Footnote %s referenced but not found" % href)
+                raise nodes.SkipNode
+            queued = self.footnote_queues.pop()
+            if not self.footnote_queues:
+                self.out.append("\\footnote{%")
+                self.out.append(text)
+                self.out.append("}")
+                for fn in queued:
+                    self.out.append("\\footnotetext{%")
+                    self.out.append(fn)
+                    self.out.append("}")
+            else:
+                self.out.append("\\footnotemark{}")
+                self.footnote_queues[-1].append(text)
+                self.footnote_queues[-1].extend(queued)
+            raise nodes.SkipNode
 
     def depart_footnote_reference(self, node) -> None:
         self.out.append(self.context.pop())
diff --git a/docutils/test/test_writers/test_latex2e.py b/docutils/test/test_writers/test_latex2e.py
index 84bb94e02..434786690 100755
--- a/docutils/test/test_writers/test_latex2e.py
+++ b/docutils/test/test_writers/test_latex2e.py
@@ -500,5 +500,121 @@ def test_body(self):
 ])
 
 
+totest_latex_footnotes['simple'] = [
+# input
+["""\
+Paragraphs contain text and may contain footnote references (manually
+numbered [1]_, anonymous auto-numbered [#]_, labeled auto-numbered
+[#label]_, or symbolic [*]_).
+
+.. [1] A footnote contains body elements, consistently indented by at
+   least 3 spaces.
+
+   This is the footnote's second paragraph.
+
+.. [#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 and as a hyperlink reference.
+
+.. [#] This footnote is numbered automatically and anonymously using a
+   label of "#" only.
+
+.. [*] Footnotes may also use symbols, specified with a "*" label.
+""",
+## # expected output
+head_template.substitute(dict(parts)) + r"""
+Paragraphs contain text and may contain footnote references (manually
+numbered\footnote{%
+A footnote contains body elements, consistently indented by at
+least 3 spaces.
+
+This is the footnote's second paragraph.
+}, anonymous auto-numbered\footnote{%
+This footnote is numbered automatically and anonymously using a
+label of \textquotedbl{}\#\textquotedbl{} only.
+}, labeled auto-numbered\footnote{%
+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 and as a hyperlink reference.
+}, or symbolic\footnote{%
+Footnotes may also use symbols, specified with a \textquotedbl{}*\textquotedbl{} label.
+}).
+
+\end{document}
+"""],
+]
+
+totest_latex_footnotes['nested'] = [
+# input
+["""\
+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.
+""",
+## # expected output
+head_template.substitute(dict(parts)) + r"""
+It's possible to produce nested footnotes in LaTeX.\footnote{%
+It takes some work, though.\footnotemark{}
+}\footnotetext{%
+And don't even get me started on how tricky recursive footnotes would be.
+}
+
+\end{document}
+"""],
+]
+
+totest_latex_footnotes['chained'] = [
+# input
+["""\
+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.
+""",
+## # expected output
+head_template.substitute(dict(parts)) + r"""
+It's possible to produce chained footnotes in LaTeX.\footnote{%
+They're just a special case of nested footnotes.\footnotemark{}
+}\footnotetext{%
+A nested footnote is a footnote on a footnote.\footnotemark{}
+}\footnotetext{%
+This is a footnote on a footnote on a footnote.
+}
+
+\end{document}
+"""],
+]
+
+totest_latex_footnotes['multinested'] = [
+# input
+["""\
+LaTeX isn't the best at nested footnote support. [#]_
+
+.. [#] Specifically, it gets the numbers wrong [#]_ for "multinested"
+   footnotes. [#]_
+.. [#] For example, this should be footnote 2, but both it and the next one
+   show up as footnote 3.
+.. [#] That's a footnote that contains more than one footnote of its own.
+""",
+## # expected output
+head_template.substitute(dict(parts)) + r"""
+LaTeX isn't the best at nested footnote support.\footnote{%
+Specifically, it gets the numbers wrong\footnotemark{} for \textquotedbl{}multinested\textquotedbl{}
+footnotes.\footnotemark{}
+}\footnotetext{%
+For example, this should be footnote 2, but both it and the next one
+show up as footnote 3.
+}\footnotetext{%
+That's a footnote that contains more than one footnote of its own.
+}
+
+\end{document}
+"""],
+]
+
 if __name__ == '__main__':
     unittest.main()
-- 
2.50.1

Hi,

I have used rST for reconstruction of the ancient theological
text and with the scholarly version I got plenty of footnotes
(which I would like to print on the bottom of the page with
per-page numbering) [1], and I found to my unpleasant surprise
that rst2xetex doesn’t produce correct LaTeX footnotes, but
something weird, which certainly cannot be controlled by the
standard LaTeX tools.

I have found this patch, and decided to at least rebase it
against the current master branch. I needed to fix tests, but
otherwise the test suite now seems to pass.

What do you think?

Best,

Matěj

[1] https://git.sr.ht/~mcepl/justin_susil/tree/master/item/p_just_2_apol.rst

John Thorvald Wodder II (1):
  An implementation of --latex-footnotes

Matěj Cepl (1):
  Fix tests to work with --latex-footnotes option.

 docutils/docutils/writers/latex2e/__init__.py |  93 +++--
 docutils/test/data/help/rst2latex.rst         |   3 +-
 docutils/test/test_writers/test_latex2e.py    | 322 +++++++++++++++++-
 3 files changed, 386 insertions(+), 32 deletions(-)

-- 
2.50.1

---
 docutils/docutils/writers/latex2e/__init__.py |   4 +-
 docutils/test/data/help/rst2latex.rst         |   3 +-
 docutils/test/test_writers/test_latex2e.py    | 350 ++++++++++++++----
 3 files changed, 280 insertions(+), 77 deletions(-)

diff --git a/docutils/docutils/writers/latex2e/__init__.py b/docutils/docutils/writers/latex2e/__init__.py
index 1dcf13466..4b6b0b431 100644
--- a/docutils/docutils/writers/latex2e/__init__.py
+++ b/docutils/docutils/writers/latex2e/__init__.py
@@ -232,13 +232,13 @@ class Writer(writers.Writer):
           {'default': True,
            'action': 'store_true',
            'validator': frontend.validate_boolean}),
-         ),
          ('Footnotes with numbers by LaTeX.',
            ['--latex-footnotes'],
            {'dest': 'docutils_footnotes',
             'action': 'store_false',
-            'validator': frontend.validate_boolean}),
+            'validator': frontend.validate_boolean})
         )
+    )
 
     relative_path_settings = ('template',)
     settings_defaults = {}
diff --git a/docutils/test/data/help/rst2latex.rst b/docutils/test/data/help/rst2latex.rst
index d0ede4c63..8e7e702f4 100644
--- a/docutils/test/data/help/rst2latex.rst
+++ b/docutils/test/data/help/rst2latex.rst
@@ -256,5 +256,4 @@ LaTeX-Specific Options
 --new-column-widths     Use new algorithm to determine table column widths.
                         (future default)
 --docutils-footnotes    Footnotes with numbers/symbols by Docutils. (default)
-                        (The alternative, --latex-footnotes, is not
-                        implemented yet.)
+--latex-footnotes       Footnotes with numbers by LaTeX.
diff --git a/docutils/test/test_writers/test_latex2e.py b/docutils/test/test_writers/test_latex2e.py
index 434786690..acb9dd6ed 100755
--- a/docutils/test/test_writers/test_latex2e.py
+++ b/docutils/test/test_writers/test_latex2e.py
@@ -47,7 +47,7 @@ def test_body(self):
                     self.assertEqual(expected, output)
 
 
-samples = {}
+samples = {}  # type: ignore
 
 
 samples['default'] = ({}, [
@@ -500,98 +500,256 @@ def test_body(self):
 ])
 
 
-totest_latex_footnotes['simple'] = [
-# input
-["""\
-Paragraphs contain text and may contain footnote references (manually
-numbered [1]_, anonymous auto-numbered [#]_, labeled auto-numbered
-[#label]_, or symbolic [*]_).
+class FootnoteTestCase(unittest.TestCase):
 
-.. [1] A footnote contains body elements, consistently indented by at
-   least 3 spaces.
+    maxDiff = None
+    settings = {
+        '_disable_config': True,
+        'strict_visitor': True,
+        'output_encoding': 'unicode',
+        'stylesheet': '',
+        'language_code': 'en',
+        'use_latex_toc': False,
+        'use_latex_citations': False,
+        'legacy_column_widths': True,
+    }
 
-   This is the footnote's second paragraph.
+    def test_footnotes(self):
+        for name, (settings_overrides, cases) in footnote_samples.items():
+            for casenum, (rst_input, expected) in enumerate(cases):
+                with self.subTest(id=f'footnote_samples[{name!r}][{casenum}]'):
+                    output = publish_parts(
+                        source=rst_input,
+                        writer=latex2e.Writer(),
+                        settings_overrides=self.settings | settings_overrides
+                    )['whole']
+                    self.assertEqual(expected, output)
 
-.. [#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 and as a hyperlink reference.
 
-.. [#] This footnote is numbered automatically and anonymously using a
-   label of "#" only.
+footnote_samples = {
+    'simple': ({}, [
+        [r"""
+        Paragraphs contain text and may contain footnote references (manually
+        numbered [1]_, anonymous auto-numbered [#]_, labeled auto-numbered
+        [#label]_, or symbolic [*]_).
+        
+        .. [1] A footnote contains body elements, consistently indented by at
+           least 3 spaces.
+        
+           This is the footnote's second paragraph.
+        
+        .. [#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 and as a hyperlink reference.
+        
+        .. [#] This footnote is numbered automatically and anonymously using a
+           label of "#" only.
+        
+        .. [*] Footnotes may also use symbols, specified with a "*" label.
+        """,
+ r"""\documentclass[a4paper]{article}
+% generated by Docutils <https://docutils.sourceforge.io/>
+\usepackage{cmap} % fix search and cut-and-paste in Acrobat
+\usepackage[T1]{fontenc}
+
+%%% Custom LaTeX preamble
+% PDF Standard Fonts
+\usepackage{mathptmx} % Times
+\usepackage[scaled=.90]{helvet}
+\usepackage{courier}
+
+%%% User specified packages and stylesheets
+
+%%% Fallback definitions for Docutils-specific commands
+
+% numerical or symbol footnotes with hyperlinks and backlinks
+\providecommand*{\DUfootnotemark}[3]{%
+  \raisebox{1em}{\hypertarget{#1}{}}%
+  \hyperlink{#2}{\textsuperscript{#3}}%
+}
+\providecommand{\DUfootnotetext}[4]{%
+  \begingroup%
+  \renewcommand{\thefootnote}{%
+    \protect\raisebox{1em}{\protect\hypertarget{#1}{}}%
+    \protect\hyperlink{#2}{#3}}%
+  \footnotetext{#4}%
+  \endgroup%
+}
 
-.. [*] Footnotes may also use symbols, specified with a "*" label.
-""",
-## # expected output
-head_template.substitute(dict(parts)) + r"""
+% hyperlinks:
+\ifdefined\hypersetup
+\else
+  \usepackage[hyperfootnotes=false,
+              colorlinks=true,linkcolor=blue,urlcolor=blue]{hyperref}
+  \usepackage{bookmark}
+  \urlstyle{same} % normal text font (alternatives: tt, rm, sf)
+\fi
+
+%%% Body
+\begin{document}
+
+\begin{quote}
 Paragraphs contain text and may contain footnote references (manually
-numbered\footnote{%
+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 contains body elements, consistently indented by at
 least 3 spaces.
 
 This is the footnote's second paragraph.
-}, anonymous auto-numbered\footnote{%
-This footnote is numbered automatically and anonymously using a
-label of \textquotedbl{}\#\textquotedbl{} only.
-}, labeled auto-numbered\footnote{%
+}
+%
+\DUfootnotetext{label}{footnote-reference-3}{2}{\phantomsection\label{label}%
 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 and as a hyperlink reference.
-}, or symbolic\footnote{%
+}
+%
+\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.
-}).
+}
+\end{quote}
 
 \end{document}
-"""],
-]
+"""]]),
+    'nested': ({}, [
+        [r"""
+        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"""\documentclass[a4paper]{article}
+% generated by Docutils <https://docutils.sourceforge.io/>
+\usepackage{cmap} % fix search and cut-and-paste in Acrobat
+\usepackage[T1]{fontenc}
+
+%%% Custom LaTeX preamble
+% PDF Standard Fonts
+\usepackage{mathptmx} % Times
+\usepackage[scaled=.90]{helvet}
+\usepackage{courier}
+
+%%% User specified packages and stylesheets
+
+%%% Fallback definitions for Docutils-specific commands
+
+% numerical or symbol footnotes with hyperlinks and backlinks
+\providecommand*{\DUfootnotemark}[3]{%
+  \raisebox{1em}{\hypertarget{#1}{}}%
+  \hyperlink{#2}{\textsuperscript{#3}}%
+}
+\providecommand{\DUfootnotetext}[4]{%
+  \begingroup%
+  \renewcommand{\thefootnote}{%
+    \protect\raisebox{1em}{\protect\hypertarget{#1}{}}%
+    \protect\hyperlink{#2}{#3}}%
+  \footnotetext{#4}%
+  \endgroup%
+}
 
-totest_latex_footnotes['nested'] = [
-# input
-["""\
-It's possible to produce nested footnotes in LaTeX. [#]_
+% hyperlinks:
+\ifdefined\hypersetup
+\else
+  \usepackage[hyperfootnotes=false,
+              colorlinks=true,linkcolor=blue,urlcolor=blue]{hyperref}
+  \usepackage{bookmark}
+  \urlstyle{same} % normal text font (alternatives: tt, rm, sf)
+\fi
 
-.. [#] It takes some work, though. [#]_
-.. [#] And don't even get me started on how tricky recursive footnotes would be.
-""",
-## # expected output
-head_template.substitute(dict(parts)) + r"""
-It's possible to produce nested footnotes in LaTeX.\footnote{%
-It takes some work, though.\footnotemark{}
-}\footnotetext{%
+%%% Body
+\begin{document}
+
+\begin{quote}
+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.
 }
+\end{quote}
 
 \end{document}
-"""],
-]
+"""]]),
+    'chained': ({}, [
+        [r"""
+        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"""\documentclass[a4paper]{article}
+% generated by Docutils <https://docutils.sourceforge.io/>
+\usepackage{cmap} % fix search and cut-and-paste in Acrobat
+\usepackage[T1]{fontenc}
+
+%%% Custom LaTeX preamble
+% PDF Standard Fonts
+\usepackage{mathptmx} % Times
+\usepackage[scaled=.90]{helvet}
+\usepackage{courier}
+
+%%% User specified packages and stylesheets
+
+%%% Fallback definitions for Docutils-specific commands
+
+% numerical or symbol footnotes with hyperlinks and backlinks
+\providecommand*{\DUfootnotemark}[3]{%
+  \raisebox{1em}{\hypertarget{#1}{}}%
+  \hyperlink{#2}{\textsuperscript{#3}}%
+}
+\providecommand{\DUfootnotetext}[4]{%
+  \begingroup%
+  \renewcommand{\thefootnote}{%
+    \protect\raisebox{1em}{\protect\hypertarget{#1}{}}%
+    \protect\hyperlink{#2}{#3}}%
+  \footnotetext{#4}%
+  \endgroup%
+}
 
-totest_latex_footnotes['chained'] = [
-# input
-["""\
-It's possible to produce chained footnotes in LaTeX. [#]_
+% hyperlinks:
+\ifdefined\hypersetup
+\else
+  \usepackage[hyperfootnotes=false,
+              colorlinks=true,linkcolor=blue,urlcolor=blue]{hyperref}
+  \usepackage{bookmark}
+  \urlstyle{same} % normal text font (alternatives: tt, rm, sf)
+\fi
 
-.. [#] 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.
-""",
-## # expected output
-head_template.substitute(dict(parts)) + r"""
-It's possible to produce chained footnotes in LaTeX.\footnote{%
-They're just a special case of nested footnotes.\footnotemark{}
-}\footnotetext{%
-A nested footnote is a footnote on a footnote.\footnotemark{}
-}\footnotetext{%
+%%% Body
+\begin{document}
+
+\begin{quote}
+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.
 }
+\end{quote}
 
 \end{document}
-"""],
-]
-
-totest_latex_footnotes['multinested'] = [
-# input
-["""\
+"""]]),
+    'multinested': ({}, [
+        [r"""
 LaTeX isn't the best at nested footnote support. [#]_
 
 .. [#] Specifically, it gets the numbers wrong [#]_ for "multinested"
@@ -600,21 +758,67 @@ def test_body(self):
    show up as footnote 3.
 .. [#] That's a footnote that contains more than one footnote of its own.
 """,
-## # expected output
-head_template.substitute(dict(parts)) + r"""
-LaTeX isn't the best at nested footnote support.\footnote{%
-Specifically, it gets the numbers wrong\footnotemark{} for \textquotedbl{}multinested\textquotedbl{}
-footnotes.\footnotemark{}
-}\footnotetext{%
+r"""\documentclass[a4paper]{article}
+% generated by Docutils <https://docutils.sourceforge.io/>
+\usepackage{cmap} % fix search and cut-and-paste in Acrobat
+\usepackage[T1]{fontenc}
+
+%%% Custom LaTeX preamble
+% PDF Standard Fonts
+\usepackage{mathptmx} % Times
+\usepackage[scaled=.90]{helvet}
+\usepackage{courier}
+
+%%% User specified packages and stylesheets
+
+%%% Fallback definitions for Docutils-specific commands
+
+% numerical or symbol footnotes with hyperlinks and backlinks
+\providecommand*{\DUfootnotemark}[3]{%
+  \raisebox{1em}{\hypertarget{#1}{}}%
+  \hyperlink{#2}{\textsuperscript{#3}}%
+}
+\providecommand{\DUfootnotetext}[4]{%
+  \begingroup%
+  \renewcommand{\thefootnote}{%
+    \protect\raisebox{1em}{\protect\hypertarget{#1}{}}%
+    \protect\hyperlink{#2}{#3}}%
+  \footnotetext{#4}%
+  \endgroup%
+}
+
+% hyperlinks:
+\ifdefined\hypersetup
+\else
+  \usepackage[hyperfootnotes=false,
+              colorlinks=true,linkcolor=blue,urlcolor=blue]{hyperref}
+  \usepackage{bookmark}
+  \urlstyle{same} % normal text font (alternatives: tt, rm, sf)
+\fi
+
+%%% Body
+\begin{document}
+
+LaTeX isn't the best at nested footnote support.\DUfootnotemark{footnote-reference-1}{footnote-1}{1}
+%
+\DUfootnotetext{footnote-1}{footnote-reference-1}{1}{%
+Specifically, it gets the numbers wrong\DUfootnotemark{footnote-reference-2}{footnote-2}{2} for \textquotedbl{}multinested\textquotedbl{}
+footnotes.\DUfootnotemark{footnote-reference-3}{footnote-3}{3}
+}
+%
+\DUfootnotetext{footnote-2}{footnote-reference-2}{2}{%
 For example, this should be footnote 2, but both it and the next one
 show up as footnote 3.
-}\footnotetext{%
+}
+%
+\DUfootnotetext{footnote-3}{footnote-reference-3}{3}{%
 That's a footnote that contains more than one footnote of its own.
 }
 
 \end{document}
-"""],
-]
+"""]]),
+}
+
 
 if __name__ == '__main__':
     unittest.main()
-- 
2.50.1

A fix is in [patches:#214] by OP Jynn Nelson . Thanks.


---

**[bugs:#504] errors for malformed tables do not indicate what the error is**

**Status:** open
**Created:** Thu Jun 05, 2025 09:04 PM UTC by Jynn Nelson
**Last Updated:** Wed Jun 11, 2025 02:37 PM UTC
**Owner:** nobody
**Attachments:**

- [table.rst](https://sourceforge.net/p/docutils/bugs/504/attachment/table.rst) (1.1 kB; application/octet-stream)


The error messages for malformed tables are quite long and do not indicate where the error occurred. I expect docutils to point at a single line of code, and say why it was malformed. Instead it points at the whole table and just says "malformed table".

~~~
$ grep PRETTY /etc/os-release
PRETTY_NAME="Pop!_OS 22.04 LTS"
$ python -V
Python 3.10.12
$ docutils -V
docutils (Docutils 0.21.2, Python 3.10.12, on linux)
$ docutils --traceback table.rst >/dev/null
table.rst:5: (ERROR/3) Malformed table.

+-------------------------+-------------------+
| Standard Code           | Message(s)       |
+=========================+===================+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M2, Invalid combination | None              |
+-------------------------+-------------------+
~~~

Note that docutils *does*  have the information to report this bug, because I can see it in a debugger. It simply doesn't include that info in the error.

~~~
$ python -m pdb $(which docutils) --traceback table.rst
> /home/jyn/.local/bin/docutils(3)<module>()
-> import re
(Pdb) break docutils/parsers/rst/states.py:1787
Breakpoint 1 at /home/jyn/.local/lib/python3.10/site-packages/docutils/parsers/rst/states.py:1787
(Pdb) c
> /home/jyn/.local/lib/python3.10/site-packages/docutils/parsers/rst/states.py(1787)malformed_table()
-> message = 'Malformed table.'
(Pdb) up
> /home/jyn/.local/lib/python3.10/site-packages/docutils/parsers/rst/states.py(1737)isolate_grid_table()
-> messages.extend(self.malformed_table(block))
(Pdb) list
1732 	            else:
1733 	                messages.extend(self.malformed_table(block))
1734 	                return [], messages, blank_finish
1735 	        for i in range(len(block)):     # check right edge
1736 	            if len(block[i]) != width or block[i][-1] not in '+|':
1737 ->	                messages.extend(self.malformed_table(block))
1738 	                return [], messages, blank_finish
1739 	        return block, messages, blank_finish
1740 	
1741 	    def isolate_simple_table(self):
1742 	        start = self.state_machine.line_offset
(Pdb) p block[i]
'| Standard Code           | Message(s)       |'
(Pdb) p width
47
(Pdb) p len(block[i])
46
~~~


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

Thank you for the patch. I will have a look at this once 0.22 is out. (We don't want delay the release any further by new changes to the release candidate unless it is  urgent.)


---

**[patches:#214] Give better messages on malformed tables**

**Status:** open
**Group:** None
**Created:** Sun Jun 08, 2025 05:58 PM UTC by Jynn Nelson
**Last Updated:** Sun Jun 08, 2025 05:58 PM UTC
**Owner:** nobody
**Attachments:**

- [tables.diff](https://sourceforge.net/p/docutils/patches/214/attachment/tables.diff) (5.2 kB; application/octet-stream)


This does several things:
- Specifies `Misaligned right border` for that error, instead of just "malformed table".
- Shows the line where each error happened, not the line where the table starts.
  - This had a complication that line numbers appear to be wrong when `include` directives are present (they include the lines in the source document, instead of being relative to the included document). Just disabled the new smarter logic in that case.
- Changes `malformed_table` to require both detail and an offset, so poor errors like this can't happen in the future.

Fixes https://sourceforge.net/p/docutils/bugs/504/.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

This seems to be by-effect of the legacy algorithm for parsing section titles (cf. [bugs:#213]).
This is fixed by [patches:#346].


---

**[bugs:#505] Curious repeated paragraph**

**Status:** open-fixed
**Created:** Thu Jun 26, 2025 06:38 PM UTC by Harmen
**Last Updated:** Sun Jul 20, 2025 09:47 PM UTC
**Owner:** nobody


When the following is parsed, the line that says "this is repeated" appears **twice** as a paragraph.

```
=========
section 1
=========

---
abc
---

this is repeated

=========
section 2
=========
```

It is fixed by:

1. Adding an additional newline after the sentence
2. Using 4 hyphens `----` instead of 3 `---` above and below `abc`
3. Removing the upper `---`

Pandoc renders this as expected (at least by me).


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

- **status**: open --> open-fixed
- **Comment**:

This seems to be by-effect of the legacy algorithm for parsing section titles (cf. [bugs:#213]).
This is fixed by [patches:#346] and should be fine in the next release.



---

**[bugs:#505] Curious repeated paragraph**

**Status:** open-fixed
**Created:** Thu Jun 26, 2025 06:38 PM UTC by Harmen
**Last Updated:** Tue Jul 01, 2025 05:57 PM UTC
**Owner:** nobody


When the following is parsed, the line that says "this is repeated" appears **twice** as a paragraph.

```
=========
section 1
=========

---
abc
---

this is repeated

=========
section 2
=========
```

It is fixed by:

1. Adding an additional newline after the sentence
2. Using 4 hyphens `----` instead of 3 `---` above and below `abc`
3. Removing the upper `---`

Pandoc renders this as expected (at least by me).


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

could you test with the prerelease

make a env, install latest release candidate

~~~
mkdir testdir
cd testdir
python3 -m venv .
. bin/activate
pip install --pre docutils
~~~

run the test
`rst2html dbl-par.rst`

i do not get duplication




---

**[bugs:#505] Curious repeated paragraph**

**Status:** open
**Created:** Thu Jun 26, 2025 06:38 PM UTC by Harmen
**Last Updated:** Sat Jun 28, 2025 09:51 AM UTC
**Owner:** nobody


When the following is parsed, the line that says "this is repeated" appears **twice** as a paragraph.

```
=========
section 1
=========

---
abc
---

this is repeated

=========
section 2
=========
```

It is fixed by:

1. Adding an additional newline after the sentence
2. Using 4 hyphens `----` instead of 3 `---` above and below `abc`
3. Removing the upper `---`

Pandoc renders this as expected (at least by me).


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

you are completely right, i just happened to never have used upperlines

but now i know how put chapter titles

please bear with me, if this is not fixed in 0.22

cheers and many thanks

On Sat, 28 Jun 2025 at 11:51, Harmen <ha...@us...> wrote:

> @grubert <https://sourceforge.net/u/grubert/profile/> actually that is
> not documented:
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
>
> I think the example should be fine according to that specification.
>
> In any case, it's a bug to have the paragraph repeated.
> ------------------------------
>
> *[bugs:#505] <https://sourceforge.net/p/docutils/bugs/505/> Curious
> repeated paragraph*
>
> *Status:* open
> *Created:* Thu Jun 26, 2025 06:38 PM UTC by Harmen
> *Last Updated:* Sat Jun 28, 2025 09:29 AM UTC
> *Owner:* nobody
>
> When the following is parsed, the line that says "this is repeated"
> appears *twice* as a paragraph.
>
> =========
> section 1
> =========
>
> ---
> abc
> ---
>
> this is repeated
>
> =========
> section 2
> =========
>
> It is fixed by:
>
>    1. Adding an additional newline after the sentence
>    2. Using 4 hyphens ---- instead of 3 --- above and below abc
>    3. Removing the upper ---
>
> Pandoc renders this as expected (at least by me).
> ------------------------------
>
> Sent from sourceforge.net because you indicated interest in
> https://sourceforge.net/p/docutils/bugs/505/
>
> To unsubscribe from further messages, please visit
> https://sourceforge.net/auth/subscriptions/
>



---

**[bugs:#505] Curious repeated paragraph**

**Status:** open
**Created:** Thu Jun 26, 2025 06:38 PM UTC by Harmen
**Last Updated:** Sat Jun 28, 2025 09:51 AM UTC
**Owner:** nobody


When the following is parsed, the line that says "this is repeated" appears **twice** as a paragraph.

```
=========
section 1
=========

---
abc
---

this is repeated

=========
section 2
=========
```

It is fixed by:

1. Adding an additional newline after the sentence
2. Using 4 hyphens `----` instead of 3 `---` above and below `abc`
3. Removing the upper `---`

Pandoc renders this as expected (at least by me).


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

sections do not have overlines (upper) only the document title


---

**[bugs:#505] Curious repeated paragraph**

**Status:** open
**Created:** Thu Jun 26, 2025 06:38 PM UTC by Harmen
**Last Updated:** Thu Jun 26, 2025 06:38 PM UTC
**Owner:** nobody


When the following is parsed, the line that says "this is repeated" appears **twice** as a paragraph.

```
=========
section 1
=========

---
abc
---

this is repeated

=========
section 2
=========
```

It is fixed by:

1. Adding an additional newline after the sentence
2. Using 4 hyphens `----` instead of 3 `---` above and below `abc`
3. Removing the upper `---`

Pandoc renders this as expected (at least by me).


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

Hei everyone,

only one change:

 Don't report an error for duplicate targets with identical refname

all the best
 e

Hei everyone,

today june 17th rc4 is out.

the final 0.22 is scheduled for end of july, start of august.

cheers
 e

Hei everyone,

next pre-release,

This release often works in clarifying things, thanks to all the testers
and many thanks to Günter for the work.

Changes that should be run through pre-release

* Drop the "name" option of the "target-notes" directive. (Report an
  error instead of silently ignoring the value.)

* New alias "rst-class" for the "class" directive to improve the
  compatibility with Sphinx.

* "Downgrade" targets generated from hyperlink references with embedded
  URI or alias from explicit to implicit (i.e. similar to the targets for
  sections, see implicit hyperlink targets for details).

thanks for your patience and help
 e

- **status**: open-fixed --> open



---

**[bugs:#502] Duplicate target not always recognized.**

**Status:** open
**Created:** Tue Jun 03, 2025 09:33 AM UTC by Günter Milde
**Last Updated:** Mon Jun 16, 2025 01:02 PM UTC
**Owner:** nobody


Hyperlinks with embedded alias generate both, a `<reference>` and a `<target>`. 
This allows simple references to the target:
~~~
See `here <example.html>`_.

As we have shown here_, ...
~~~
However, it may lead to duplicates:
~~~
_`Here` is an explicit inline target.

See `here <example.html>`_.

As we have shown here_, ...
~~~
The second target gives a WARNING `Duplicate explicit target name: "here".`
Using the reference name results in an ERROR `Duplicate target name, cannot be used as a unique reference: "here".`

However (in versions up to 0.22.rc2), the duplicate target is ignored in case of **embedded internal** targets:
~~~
_`Here` is an explicit inline target.

See `here <elsewhere_>`_.

As we have shown here_, ...

The target is _`elsewhere`.
~~~
There is no WARNING or ERROR and both references link to "elsewhere".

This is fixed in [r10151].


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

It seems, that up to now many users did not know that ````link text <target>`_```
creates a <target> with the reference name "link text".

The Sphinx rST primer did start with
~~~rst
Use ```Link text <https://domain.invalid/>`_`` for inline web links. 
~~~
without mentioning that this *named hyperlink reference with embedded URI* also generates a target.

The missing WARNING for *named hyperlink references with embedded alias* did contribute to the confusion. As a result, even the [Docutils Directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html) documentation shows warnings after the fix in [r10151].

In order to avoid breaking lots of existing documents,  *named hyperlink references with embedded URI or alias* should not be interpreted as an explicit intention to create a target. 
Rather, like section titles, the  reference name should be treated as [**implicit** hyperlink targets]( https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#implicit-hyperlink-targets).




---

**[bugs:#502] Duplicate target not always recognized.**

**Status:** open-fixed
**Created:** Tue Jun 03, 2025 09:33 AM UTC by Günter Milde
**Last Updated:** Tue Jun 03, 2025 03:33 PM UTC
**Owner:** nobody


Hyperlinks with embedded alias generate both, a `<reference>` and a `<target>`. 
This allows simple references to the target:
~~~
See `here <example.html>`_.

As we have shown here_, ...
~~~
However, it may lead to duplicates:
~~~
_`Here` is an explicit inline target.

See `here <example.html>`_.

As we have shown here_, ...
~~~
The second target gives a WARNING `Duplicate explicit target name: "here".`
Using the reference name results in an ERROR `Duplicate target name, cannot be used as a unique reference: "here".`

However (in versions up to 0.22.rc2), the duplicate target is ignored in case of **embedded internal** targets:
~~~
_`Here` is an explicit inline target.

See `here <elsewhere_>`_.

As we have shown here_, ...

The target is _`elsewhere`.
~~~
There is no WARNING or ERROR and both references link to "elsewhere".

This is fixed in [r10151].


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

Thank you for the report.

Note, that Docutils does report the line in the table for "simple" tables:
~~~
========================   =================
 Standard Code             Message(s)       
========================   =================
 M1, indicator undefined  Illegal reference
 M2, Invalid combination   None             
========================   =================
~~~
Compiling with `docutils` reports
~~~
/tmp/foo.rst:4: (ERROR/3) Malformed table.
Text in column margin in table line 4.
...
~~~


---

**[bugs:#504] errors for malformed tables do not indicate what the error is**

**Status:** open
**Created:** Thu Jun 05, 2025 09:04 PM UTC by Jynn Nelson
**Last Updated:** Thu Jun 05, 2025 09:04 PM UTC
**Owner:** nobody
**Attachments:**

- [table.rst](https://sourceforge.net/p/docutils/bugs/504/attachment/table.rst) (1.1 kB; application/octet-stream)


The error messages for malformed tables are quite long and do not indicate where the error occurred. I expect docutils to point at a single line of code, and say why it was malformed. Instead it points at the whole table and just says "malformed table".

~~~
$ grep PRETTY /etc/os-release
PRETTY_NAME="Pop!_OS 22.04 LTS"
$ python -V
Python 3.10.12
$ docutils -V
docutils (Docutils 0.21.2, Python 3.10.12, on linux)
$ docutils --traceback table.rst >/dev/null
table.rst:5: (ERROR/3) Malformed table.

+-------------------------+-------------------+
| Standard Code           | Message(s)       |
+=========================+===================+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M2, Invalid combination | None              |
+-------------------------+-------------------+
~~~

Note that docutils *does*  have the information to report this bug, because I can see it in a debugger. It simply doesn't include that info in the error.

~~~
$ python -m pdb $(which docutils) --traceback table.rst
> /home/jyn/.local/bin/docutils(3)<module>()
-> import re
(Pdb) break docutils/parsers/rst/states.py:1787
Breakpoint 1 at /home/jyn/.local/lib/python3.10/site-packages/docutils/parsers/rst/states.py:1787
(Pdb) c
> /home/jyn/.local/lib/python3.10/site-packages/docutils/parsers/rst/states.py(1787)malformed_table()
-> message = 'Malformed table.'
(Pdb) up
> /home/jyn/.local/lib/python3.10/site-packages/docutils/parsers/rst/states.py(1737)isolate_grid_table()
-> messages.extend(self.malformed_table(block))
(Pdb) list
1732 	            else:
1733 	                messages.extend(self.malformed_table(block))
1734 	                return [], messages, blank_finish
1735 	        for i in range(len(block)):     # check right edge
1736 	            if len(block[i]) != width or block[i][-1] not in '+|':
1737 ->	                messages.extend(self.malformed_table(block))
1738 	                return [], messages, blank_finish
1739 	        return block, messages, blank_finish
1740 	
1741 	    def isolate_simple_table(self):
1742 	        start = self.state_machine.line_offset
(Pdb) p block[i]
'| Standard Code           | Message(s)       |'
(Pdb) p width
47
(Pdb) p len(block[i])
46
~~~


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

Hei

minimal changes and fixes

manpage writer no longer drops the text of internal targets

0.22 in one week ... if ... :-)

cheers and thanks to günter
 e

---

**[bugs:#503] LaTeX writer fails to generate "labels" for some elements with "ids".**

**Status:** open
**Created:** Wed Jun 04, 2025 04:34 PM UTC by Günter Milde
**Last Updated:** Wed Jun 04, 2025 04:34 PM UTC
**Owner:** nobody


Most doctree elements (nodes) accept the "ids" attribute that can be used as end-point for internal cross references.
In LaTeX, "ids" are represented as "labels". This is only implemented for a small subset of elements.
For example the internal hyperlink in 
~~~
.. note::
   :name: my-note
   
   This is an admonition with ID
   
Link to my-note_. 
~~~
does not work because there is no `\label{my-note}`  in the LaTeX output.

See also [Sphinx issue #13609](https://github.com/sphinx-doc/sphinx/issues/13609#issuecomment-2937289148).


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

- Description has changed:

Diff:

~~~~

--- old
+++ new
@@ -26,6 +26,6 @@
 
 The target is _`elsewhere`.
 ~~~
-There no WARNING or ERROR and both references link to "elsewhere".
+There is no WARNING or ERROR and both references link to "elsewhere".
 
 This is fixed in [r10151].

~~~~




---

**[bugs:#502] Duplicate target not always recognized.**

**Status:** open-fixed
**Created:** Tue Jun 03, 2025 09:33 AM UTC by Günter Milde
**Last Updated:** Tue Jun 03, 2025 09:33 AM UTC
**Owner:** nobody


Hyperlinks with embedded alias generate both, a `<reference>` and a `<target>`. 
This allows simple references to the target:
~~~
See `here <example.html>`_.

As we have shown here_, ...
~~~
However, it may lead to duplicates:
~~~
_`Here` is an explicit inline target.

See `here <example.html>`_.

As we have shown here_, ...
~~~
The second target gives a WARNING `Duplicate explicit target name: "here".`
Using the reference name results in an ERROR `Duplicate target name, cannot be used as a unique reference: "here".`

However (in versions up to 0.22.rc2), the duplicate target is ignored in case of **embedded internal** targets:
~~~
_`Here` is an explicit inline target.

See `here <elsewhere_>`_.

As we have shown here_, ...

The target is _`elsewhere`.
~~~
There is no WARNING or ERROR and both references link to "elsewhere".

This is fixed in [r10151].


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

---

**[bugs:#502] Duplicate target not always recognized.**

**Status:** open-fixed
**Created:** Tue Jun 03, 2025 09:33 AM UTC by Günter Milde
**Last Updated:** Tue Jun 03, 2025 09:33 AM UTC
**Owner:** nobody


Hyperlinks with embedded alias generate both, a `<reference>` and a `<target>`. 
This allows simple references to the target:
~~~
See `here <example.html>`_.

As we have shown here_, ...
~~~
However, it may lead to duplicates:
~~~
_`Here` is an explicit inline target.

See `here <example.html>`_.

As we have shown here_, ...
~~~
The second target gives a WARNING `Duplicate explicit target name: "here".`
Using the reference name results in an ERROR `Duplicate target name, cannot be used as a unique reference: "here".`

However (in versions up to 0.22.rc2), the duplicate target is ignored in case of **embedded internal** targets:
~~~
_`Here` is an explicit inline target.

See `here <elsewhere_>`_.

As we have shown here_, ...

The target is _`elsewhere`.
~~~
There no WARNING or ERROR and both references link to "elsewhere".

This is fixed in [r10151].


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.