docutils-develop Mailing List for Docutils: Documentation Utilities (Page 5)

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 <" rel="nofollow">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 <" rel="nofollow">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 <" rel="nofollow">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 <" rel="nofollow">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 <" rel="nofollow">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] <" rel="nofollow">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.

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

This is fixed as part of a general update to the page in [r10148].

Thank you for reporting.



---

**[bugs:#501] Typo in "Docutils Links" page**

**Status:** open-fixed
**Created:** Sat May 31, 2025 11:20 AM UTC by Edward K. Ream
**Last Updated:** Sat May 31, 2025 11:20 AM UTC
**Owner:** nobody


The [Docutils Links](https://docutils.sourceforge.io/docs/user/links.html) page contains a typo concerning Leo:

Please change:
It can be used as IDE for **literal** programming,
to
It can be used as IDE for **literate** programming,

Thanks.




---

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 a few changes, but necessary ones to remedy 3rd party problems

please try, test

next release day for 0.22 on my schedule is tuesday june 10.

all the best
 e

* docutils/parsers/rst/directives/misc.py

  - Pass default settings to custom parser for included file.

* docutils/parsers/rst/states.py

  - Remove the list`states.RSTStateMachine.memo.section_parents`
    (introduced in Docutils 0.22rc1) that broke 3rd-party applications
    setting up a "mock memo".
  - Use `types.SimpleNamespace` instead of a local definition for
    the auxilliary class `states.Struct`.

* docutils/writers/_html_base.py

  - Fix error when determining the document metadata title from the
    source path and the internal `source` attribute is None.

Sphinx uses parentheses in the [:abbr: role](https://sphinx--13576.org.readthedocs.build/en/13576/usage/restructuredtext/roles.html#role-abbr), for example:
~~~
:abbr:`LIFO (last-in, first-out)` 
~~~
+1 looks "natural" in source form
- 1 used as generic syntax, this would require escaping all opening parentheses in role content.


---

**[feature-requests:#68] Adding syntax for role parameters**

**Status:** open
**Group:** Default
**Created:** Fri Jan 31, 2020 11:28 PM UTC by adam
**Last Updated:** Tue Dec 12, 2023 06:25 PM UTC
**Owner:** nobody


Hello Docutils team,

Sometimes I would like to pass options to role functions for adding domain-specific metadata. For example,

For citation page numbers:

~~~rst
As discussed in :cite:[p.99]`knuth1968`, the implementation ...
~~~

In a cookbook:
~~~rst
If you like, add some :liquid-ingredient:[20ml, spicyness=7]`Tabasco sauce`. 
~~~


As discussed in [this Docutils mailing-list thread](https://sourceforge.net/p/docutils/mailman/message/34894112/), AsciiDoc [uses a syntax](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#images) like this:

~~~
Click image:icons/play.png[Play, title="Play"] to get the party started.
~~~

I like the idea of passing positional and named options in brackets.

Is there a possibility of Docutils supporting this feature? 


---

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

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

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

Thanks for the fast feedback. The patch is now in the repository [r10135].



---

**[bugs:#500] Html5WriterPublishPartsTestCase.test_publish skips too much when with_pygments is False**

**Status:** open-fixed
**Created:** Mon May 19, 2025 10:15 AM UTC by Michał Górny
**Last Updated:** Tue May 20, 2025 12:24 PM UTC
**Owner:** nobody


While debugging something else, I've noticed that the `Html5WriterPublishPartsTestCase.test_publish()` case contains the following bit:

```
        for name, (settings_overrides, cases) in totest.items():
            if name == 'syntax_highlight' and not with_pygments:
                self.skipTest('syntax highlight requires pygments')
```

This means that if `with_pygments` is `False`, all the remaining cases from `totest` are skipped. If I replace it with:

```
        for name, (settings_overrides, cases) in totest.items():
            if name == 'syntax_highlight' and not with_pygments:
                continue
```

I see some test regressions too.


---

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,

the plan changed

0.22rc2 is for thursday may, 22

0.22 if nothing crops up tuesday june, 10th

all the best
 e

I can confirm that the patch makes tests pass for me — and it definitely looks more reliable in the long run. Thanks!


---

**[bugs:#500] Html5WriterPublishPartsTestCase.test_publish skips too much when with_pygments is False**

**Status:** open
**Created:** Mon May 19, 2025 10:15 AM UTC by Michał Górny
**Last Updated:** Tue May 20, 2025 11:53 AM UTC
**Owner:** nobody


While debugging something else, I've noticed that the `Html5WriterPublishPartsTestCase.test_publish()` case contains the following bit:

```
        for name, (settings_overrides, cases) in totest.items():
            if name == 'syntax_highlight' and not with_pygments:
                self.skipTest('syntax highlight requires pygments')
```

This means that if `with_pygments` is `False`, all the remaining cases from `totest` are skipped. If I replace it with:

```
        for name, (settings_overrides, cases) in totest.items():
            if name == 'syntax_highlight' and not with_pygments:
                continue
```

I see some test regressions too.


---

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.