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

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

The issue is fixed in Docutils 0.22 released 2025-07-29.
Thank you for reporting.




---

**[feature-requests:#94] Should docutils whine about nesting simple body elements?**

**Status:** closed-fixed
**Group:** Default
**Created:** Thu Feb 09, 2023 09:55 AM UTC by Julien Palard
**Last Updated:** Thu Jun 06, 2024 08:16 PM UTC
**Owner:** nobody


Context:

[This](https://github.com/python/cpython/blob/45fa12aec8f508c224a1521cfe3ae597f1026264/Doc/tools/extensions/pyspecific.py#L149) call to `nested_parse` adds a `Paragraph` node to a `Paragraph` node,  this look forbidden by [the doc](https://docutils.sourceforge.io/docs/ref/doctree.html#body-elements), and it also look to misbehave sphinx-side, when translating the document, where we completly loose the nested paragraph once translated.

It renders properly though when **not** translated.

The linked `nested_parse` returns:

```xml
<paragraph classes="availability">
    <pending_xref refdoc="index" refdomain="std" refexplicit="True" reftarget="availability" reftype="ref" refwarn="True">
        <inline classes="xref std std-ref">
            Availability
    : 
    Unix, not Emscripten, not WASI.
    <paragraph>
        Hello world I'm the content of the "availability" directive.
```

If it's really something that should not be done, maybe some kind of warning at build time could help debugging those issues?



---

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-fixed --> closed-fixed
- **Comment**:

The issue is fixed in Docutils 0.22 released 2025-07-29.
Thank you for reporting.




---

**[feature-requests:#102] Image height/width attributes**

**Status:** closed-fixed
**Group:** Default
**Created:** Wed Dec 20, 2023 02:35 PM UTC by toastal
**Last Updated:** Wed Sep 11, 2024 07:30 AM UTC
**Owner:** nobody


When setting `:width:` or `:height:` on an image, the output is a `<image style="width: $W; height: $H">`. This isn’t the expected out put as there are & have been `width` & `height` attributes for the `<img>` tag for a long time. One might assume this is the same affect, but there are some important problems & why I think this is a bug for incorrect implementation.

1. Tools like Lighthouse, et al. show users to have width/height as a optimization so the browser can calculate & the image size properly without having to do a layout shift which is great
2. A good CSP (Content Security Policy) should never include `unsafe-inline` as this can be an attack surface but the output of `:width:` & `:height:` do just this.

The way to solve this to keep out unneeded inline style practice for good CSP but still have the width/height is to just use `<img width="$W" height="$H">` (at least when units are not specified).

What I may not be accounting for: units. `12px` is not the same as `12rem` or `12ex` or `12vw`. However, what I had input in my image was just plain ol’ integers got back something I didn’t expect: a) something using `px` (I‘m exclusively using relative unit like `em`, `rem`, etc.) and b) not using the attributes since the number I gave had no units.


---

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-fixed --> closed-fixed
- **Comment**:

The issue is fixed in Docutils 0.22 released 2025-07-29.
Thank you for reporting.




---

**[feature-requests:#105] manpage: would like more informative document comments**

**Status:** closed-fixed
**Group:** Default
**Labels:** manpage writer 
**Created:** Wed Mar 27, 2024 01:07 AM UTC by G. Branden Robinson
**Last Updated:** Thu May 16, 2024 02:39 PM UTC
**Owner:** engelbert gruber


*man* documents generated by *rst2man*  have some indication that they were automatically generated but I would prefer to see more information along these lines.

Here's the status quo.
~~~
.\" Man page generated from reStructuredText.
.\" body of man page follows
.\" Generated by docutils manpage writer.
.
~~~

In my opinion, the comments should be coalesced at the top of the document and include tool versioning information.

More like this:

~~~
.\" Man page generated from reStructuredText by rst2man
.\" from docutils 0.21rc1.
~~~


---

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.

@aa-turner:  Can we close this bug? Is there still something to do after 0.22 is out?


---

**[bugs:#493] Test failure on Windows with embedded images**

**Status:** open-fixed
**Created:** Wed Aug 07, 2024 02:25 AM UTC by Adam  Turner
**Last Updated:** Mon Apr 14, 2025 01:10 PM UTC
**Owner:** nobody


xref [r9785], [r9853], [r9855]

Dear @milde,

Thank you for the fix to my recent patch. It seems neither my patch nor the fix addressed the root cause of the test failures, as tests have resumed failing on Windows.

I believe the following demonstrates the problem:

```pycon
>>> import sys; print(sys.platform)
win32
>>> import urllib.parse, urllib.request
>>> urllib.request.url2pathname('test/data/circle-broken.svg')
'test\\data\\circle-broken.svg'
>>> urllib.parse.unquote('test/data/circle-broken.svg')
'test/data/circle-broken.svg'
```

Currently, we use `imagepath = urllib.request.url2pathname(uri_parts.path)`, which converts path separators to their platform-native format. On UNIX, `url2pathname` simply calls `unquote`, but on Windows it handles UNC paths (``\\host\path\``) and escaped drive letters (``///C|/users/``).

I don't know what led to using `url2pathname()`, as it is quite specialised (the docstring notes "not recommended for general use"). Is it possible to use the simpler `unquote()` here?  

For local file paths (e.g. without a ``file:///`` scheme), should we even be using URI parsing? Perhaps we should use proper path handling if there is no URI scheme (i.e. the user has provided a file-path).

A


---

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-fixed --> closed-fixed
- **Comment**:

The issue is fixed in Docutils 0.22 released 2025-07-29.
Thank you for reporting.




---

**[bugs:#346] reST parser warns twice for short underline**

**Status:** closed-fixed
**Created:** Sun Jul 29, 2018 11:37 AM UTC by Takeshi KOMIYA
**Last Updated:** Thu Apr 17, 2025 09:50 PM UTC
**Owner:** nobody


reST parser warns twice if the underline for second heading is short.
I think it is a bit verbose.

Input:
~~~
$ cat helper.rst
Issue #5214
===========

django_assert_num_queries
========
~~~
Output (warnings):
~~~
$ rst2html.py helpers.rst > /dev/null
helpers.rst:5: (WARNING/2) Title underline too short.

django_assert_num_queries
========
helpers.rst:5: (WARNING/2) Title underline too short.

django_assert_num_queries
========
~~~

It seems the parser does not warn if the short underline appears at first.

Note: originately this was reported to sphinx:  https://github.com/sphinx-doc/sphinx/issues/5214


---

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-fixed --> closed-fixed
- **Comment**:

The issue is fixed in Docutils 0.22 released 2025-07-29.
Thanks again for reporting.




---

**[bugs:#481] manpage: please stop converting text to full capitals**

**Status:** closed-fixed
**Labels:** manpage writer 
**Created:** Wed Mar 27, 2024 01:12 AM UTC by G. Branden Robinson
**Last Updated:** Sun May 19, 2024 04:18 PM UTC
**Owner:** engelbert gruber


*mandoc* maintainer Ingo Schwarze and I (*groff* lead developer) reached a consensus a few years ago that man pages should stop shouting.  This is a historical artifact of practices at Bell Labs in the 1970s.

It also can, reportedly, create accessibility problems, since a screen reader may pronounce words in FULL CAPS letter by letter instead of reading them as words.  (The KDE screen reader I tried with a PDF didn't do this.)

In _groff_ 1.23.0, this behavior is configurable, and the user can turn the full-caps conversion on at rendering time.  With _man-db_, these options can be passed in via the ``MANROFFOPT`` environment variable.

~~~
     -rCS=1   Set section headings (the argument(s) to .SH) in full
              capitals.  This transformation is off by default because
              it discards case distinction information.

     -rCT=1   Set the man page identifier (the first argument to .TH) in
              full capitals in headers and footers.  This transformation
              is off by default because it discards case distinction
              information.
~~~


---

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-fixed --> closed-fixed
- **Comment**:

The bug is fixed in Docutils 0.22 released 2025-07-29.
Thank you for reporting.




---

**[bugs:#486] 0.21.1: sdist is missing tox.ini**

**Status:** closed-fixed
**Created:** Mon Apr 22, 2024 08:01 AM UTC by Marcel Telka
**Last Updated:** Fri May 03, 2024 11:47 AM UTC
**Owner:** nobody


The sdist package for version 0.21.1 is missing tox.ini.  Please add the missing tox.ini to sdist to make downstream testing easier.  Thank you.


---

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-fixed --> closed-fixed
- **Comment**:

The bug is fixed in Docutils 0.22 released 2025-07-29.



---

**[bugs:#488] prepare URIs **

**Status:** closed-fixed
**Labels:** manpage writer 
**Created:** Sun May 12, 2024 03:55 PM UTC by engelbert gruber
**Last Updated:** Fri Apr 25, 2025 04:37 PM UTC
**Owner:** engelbert gruber


groff_man_style on hyperlinks

    The arguments to .MR, .MT, and .UR should be prepared for typesetting
    
1. Use special character escape sequences to encode Unicode  basic  Latin  characters  where  necessary, particularly the hyphen-minus.
2. URIs can be lengthy; ... the  application  of  non-printing break point escape sequences \: after each slash (or series thereof), and before each  dot  (or  series  thereof)  is recommended 
3. Consider  adding  break points  before  or after at signs in email addresses, and question marks, ampersands, and number signs in HTTP(S) URIs.


---

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-fixed --> closed-fixed
- **Comment**:

The bug is fixed in Docutils 0.22 released 2025-07-29.




---

**[bugs:#489] Issues with the Docutils Doctree**

**Status:** closed-fixed
**Created:** Tue Jun 11, 2024 12:13 PM UTC by Günter Milde
**Last Updated:** Fri Apr 25, 2025 01:15 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Doctree-amendment-System-messages-can-appear-in-plac.patch](https://sourceforge.net/p/docutils/bugs/489/attachment/0001-Doctree-amendment-System-messages-can-appear-in-plac.patch) (5.5 kB; text/x-patch)


There are a number of discrepancies between the [Docutils Generic DTD][docutils.dtd]
and the implementation in Docutils code.

footnote
--------

[docutils.dtd][docutils.dtd]: `(label?, (%body.elements;)+)`
→ Label **optional**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> Each footnote consists of an explicit markup start (".. "), a left
> square bracket, **the footnote label**, a right square bracket, and
> whitespace, followed by indented body elements.

The `footnote` class in [docutils.nodes](https://docutils.sourceforge.io/docutils/nodes.py) is a subclass of `Labeled`, 
whose docstring says: "**Contains a label** as its first element."

The rST parser **requires** a label but allows **empty footnotes**
(cf. `test/test_writers/test_latex2e.py`).

citation
--------

[docutils.dtd][docutils.dtd]: `(label, (%body.elements;)+)`
→ Label **required**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> Citations are **identical to footnotes** except that they use only
> non-numeric labels …

The rST parser allows **empty citations** (cf. test_rst/test_citations.py).

figure
------

[docutils.dtd][docutils.dtd]: `(image, ((caption, legend?) | legend))`
→ caption or legend **required**; (not changed since 2002-04-20).

[reStructuredText Directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure)

> A "figure" consists of image data (including image options), an **optional
> caption** (a single paragraph), and an **optional legend** (arbitrary body
> elements). For page-based output media, figures might float to a different
> position if this helps the page layout.

The rST parser allows **figures without caption or legend**.

Docutils HTML and LaTeX writers use a different layout for figures vs.
images. They can handle figures without caption/legend.

Suggestion
----------

* Make *footnote label compulsory`*.
* Let rST report a *warning for empty footnote and citation*.
  Remove tests with empty footnote and citation.
* Allow *figures without caption/legend* in the Docutils Generic DTD.

(Change in Docutils 1.0, announce in 0.22.)

Questions
---------
Are there a use cases for 
* footnotes without label,
* footnotes without content,
* citations without content?

[docutils.dtd]: https://docutils.sourceforge.io/docs/ref/docutils.dtd
[rST spec]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html



---

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-fixed --> closed-fixed
- **Comment**:

The bug is fixed in Docutils 0.22 released 2025-07-29.
Thanks agaoin for reporting.




---

**[bugs:#490] EncodingWarnings in io module**

**Status:** closed-fixed
**Created:** Fri Jun 28, 2024 03:34 PM UTC by Jason R. Coombs
**Last Updated:** Wed Aug 07, 2024 03:57 PM UTC
**Owner:** nobody


When running the [distutils](https://github.com/pypa/distutils) tests with `PYTHONWARNDEFAULTENCODING=1`, two warnings are emitted:

```
distutils/tests/test_check.py::TestCheck::test_check_restructuredtext
  /Users/jaraco/code/pypa/distutils/.tox/py/lib/python3.12/site-packages/docutils/io.py:381: EncodingWarning: 'encoding' argument not specified
    self.source = open(source_path, mode,

distutils/tests/test_check.py::TestCheck::test_check_restructuredtext
  /Users/jaraco/code/pypa/distutils/.tox/py/lib/python3.12/site-packages/docutils/io.py:151: EncodingWarning: UTF-8 Mode affects locale.getpreferredencoding(). Consider locale.getencoding() instead.
    fallback = locale.getpreferredencoding(do_setlocale=False)
```

Docutils should honor [PEP 597](https://peps.python.org/pep-0597/) and address these warnings (and possibly others). In my experience, adding `encoding='utf-8'` to any io operation is the best approach - it's straight-up compatible with the default on non-Windows systems and usually honoring the Unix convention is suitable if not preferable on Windows. Not only that, but that behavior will become the default in Python 3.15 or so.


---

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-fixed --> closed-fixed
- **Comment**:

The bug is fixed in Docutils 0.22 released 2025-07-29.
Thanks again for reporting.




---

**[bugs:#491] Don't hardcode interpreter in utils/smartquotes.py**

**Status:** closed-fixed
**Created:** Tue Jul 02, 2024 01:39 PM UTC by Ross Burton
**Last Updated:** Sat Jul 27, 2024 09:05 AM UTC
**Owner:** nobody


The interpreter is hardcoded in smartquotes.py:

https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/docutils/utils/smartquotes.py

Instead of using "/usr/bin/python3" directly, it's recommended to use "/usr/bin/env python3".


---

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-fixed --> closed-fixed
- **Comment**:

The bug is fixed in Docutils 0.22 released 2025-07-29.
Thank you for reporting.



---

**[bugs:#494] rst2odt: TypeError with --stylesheet=styles.xml**

**Status:** closed-fixed
**Labels:** ODT Writer 
**Created:** Fri Oct 04, 2024 10:52 AM UTC by Paul Kishimoto
**Last Updated:** Fri Nov 29, 2024 08:29 AM UTC
**Owner:** nobody


The documentation (page “ODT Writer for Docutils”, section [“4 Styles and Classes”](https://docutils.sourceforge.io/docs/user/odt.html#styles-and-classes)) states:
> Note that with the `--stylesheet` command line option, you can use either `styles.odt` or `styles.xml`, as described below. Use of `styles.odt` is recommended over `styles.xml`.

With Python 3.12.3 and docutils 0.21.2, it appears that styles.xml is not usable, either from the command line or programmatically.

To reproduce from the command line:
1. A file `empty.rst`.
2. A file `styles.xml`, extracted from any valid ODT archive.
3. Run `$ docutils --writer=odt --stylesheet=styles.xml --traceback empty.rst >bug.odt`

The output is:
```
Traceback (most recent call last):
  File "/home/khaeru/.venv/3.12/bin/docutils", line 8, in <module>
    sys.exit(main())
             ^^^^^^
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/__main__.py", line 78, in main
    publish_cmdline(reader_name=args.reader,
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/core.py", line 402, in publish_cmdline
    output = publisher.publish(
             ^^^^^^^^^^^^^^^^^^
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/core.py", line 237, in publish
    output = self.writer.write(self.document, self.destination)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/writers/__init__.py", line 80, in write
    self.translate()
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/writers/odf_odt/__init__.py", line 510, in translate
    self.visitor.retrieve_styles(self.EXTENSION)
  File "/home/khaeru/.venv/3.12/lib/python3.12/site-packages/docutils/writers/odf_odt/__init__.py", line 941, in retrieve_styles
    self.dom_stylesheetcontent = etree.fromstring(
                                 ^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/xml/etree/ElementTree.py", line 1335, in XML
    parser.feed(text)
TypeError: a bytes-like object is required, not 'NoneType'
```

The same error occurs when calling:
```python
from docutils.core import publish_string

publish_string(
    source="",
    writer_name="odt",
    settings_overrides={"stylesheet": "styles.xml"},
)
```

This seems to be a consequence of `ODFTranslator.retrieve_styles()` ([here](https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/docutils/writers/odf_odt/__init__.py#l925)), wherein:

1. `s2 = None` is set.
2. If the provided path has extension `extension` (e.g. ".odt"), it is overwritten with content read from `content.xml` in the archive; **but** if the provided path has extension ".xml", it remains `None`.
3. This value is assigned to `self.str_stylesheetcontent` and then parsed with `etree.tostring()`.

Also, the parsed `self.dom_stylesheetcontent` does not appear to be used anywhere else in the module. It's not clear why it is needed.


---

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-fixed --> closed-fixed
- **Comment**:

The fix is now in Docutils 0.22 released 2025-07-29.
Thank you for reporting.




---

**[bugs:#495] locale.Error: unsupported locale setting**

**Status:** closed-fixed
**Created:** Tue Oct 08, 2024 11:34 AM UTC by Artur Stępniak
**Last Updated:** Sat Jun 07, 2025 08:01 PM UTC
**Owner:** nobody


I'm getting "locale.Error: unsupported locale setting" when running e.g. rst2man docs/man/openvpn3-log.1.rst  | groff -Tutf8 -man

Full output:
~~~
Traceback (most recent call last):
  File "/usr/bin/rst2man", line 8, in <module>
    sys.exit(rst2man())
             ^^^^^^^^^
  File "/usr/lib/python3.12/site-packages/docutils/core.py", line 760, in rst2man
    rst2something('manpage', 'Unix manual (troff)', 'user/manpage.html')
  File "/usr/lib/python3.12/site-packages/docutils/core.py", line 739, in rst2something
    locale.setlocale(locale.LC_ALL, '')
  File "/usr/lib/python3.12/locale.py", line 615, in setlocale
    return _setlocale(category, locale)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
locale.Error: unsupported locale setting
~~~

my locale setting:
~~~
locale
locale: Cannot set LC_CTYPE to default locale: No such file or directory
locale: Cannot set LC_MESSAGES to default locale: No such file or directory
locale: Cannot set LC_ALL to default locale: No such file or directory
LANG=szl_PL.UTF-8
LC_CTYPE="szl_PL.UTF-8"
LC_NUMERIC=pl_PL.UTF-8
LC_TIME=pl_PL.UTF-8
LC_COLLATE="szl_PL.UTF-8"
LC_MONETARY=pl_PL.UTF-8
LC_MESSAGES="szl_PL.UTF-8"
LC_PAPER=pl_PL.UTF-8
LC_NAME=pl_PL.UTF-8
LC_ADDRESS=pl_PL.UTF-8
LC_TELEPHONE=pl_PL.UTF-8
LC_MEASUREMENT=pl_PL.UTF-8
LC_IDENTIFICATION=pl_PL.UTF-8
LC_ALL=
~~~


---

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-fixed --> closed-fixed
- **Comment**:

The bug is fixed in Docutils 0.22 released 2025-07-29.
Thank you for reporting.




---

**[bugs:#497] manpage writer renders links incorrectly**

**Status:** closed-fixed
**Labels:** manpage writer 
**Created:** Tue Feb 11, 2025 11:03 PM UTC by Ulya Trofimovich
**Last Updated:** Wed Apr 30, 2025 07:08 PM UTC
**Owner:** engelbert gruber


Hi! Here's an example bug.rst file (trimmed from a real-world manpage AUTHORS section and changed to hide real names):
~~~
$ cat bug.rst
Aaaaa (aa...@bb...),
`Bbb <" rel="nofollow">https://github.com/cc>`_ (dd...@gm...),
`mm <" rel="nofollow">https://github.com/m>`_
`nn <" rel="nofollow">https://github.com/nn>`_
and `OooOoooo <" rel="nofollow">https://github.com/OooOoooo>`_.
~~~
With rst2man (Docutils 0.21.2, Python 3.12.8, on linux) it is rendered as follows (I cut first and last output lines in the output as they obscure the view and are irrelevant):
~~~
$ rst2man bug.rst > bug.1 && man ./bug.1
NAME
        - Aaaaa ( <aa...@bb...> ), Bbb <" rel="nofollow">https://github.com/cc>
        ( <dd...@gm...> ), mm <" rel="nofollow">https://github.com/m>

        <nn> and  <OooOoooo> .
~~~
What I think is wrong:

1. In <nn> and <OooOoooo> URI had been removed completely (note that they are different from other addresses in that the substitution text is the same as the last URI path component)
2. spaces surrounding email in parentheses look weird
3. newlines seem to be inserted at random

I would like it to be rendered like this:
~~~
NAME
        - Aaaaa (aa...@bb...), Bbb <" rel="nofollow">https://github.com/cc> (dd...@gm...), mm <" rel="nofollow">https://github.com/m> nn <" rel="nofollow">https://github.com/nn> and OooOoooo <." rel="nofollow">https://github.com/OooOoooo>.
~~~
    
I suspect this is the change in https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-21-2024-04-09, as I saw other changes listed in this release in the same diff with the breaking changes described above.


---

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-fixed --> closed-fixed
- **Comment**:

The bug is fixed in Docutils 0.22 released 2025-07-29.
Thank you for reporting.




---

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

**Status:** closed-fixed
**Created:** Mon May 19, 2025 10:15 AM UTC by Michał Górny
**Last Updated:** Tue May 20, 2025 03:09 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.

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



---

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

**Status:** closed-fixed
**Created:** Sat May 31, 2025 11:20 AM UTC by Edward K. Ream
**Last Updated:** Tue Jun 03, 2025 08:53 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.

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

The bug is fixed in Docutils 0.22 released 2025-07-29.
Thank you for reporting.




---

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

**Status:** closed-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-fixed --> closed-fixed
- **Comment**:

Fixed. Thank you for reporting.



---

**[bugs:#506] Incorrect description of phrase references in the specification page**

**Status:** closed-fixed
**Created:** Fri Jul 11, 2025 09:55 AM UTC by Yuki Kobayashi
**Last Updated:** Fri Jul 11, 2025 12:52 PM UTC
**Owner:** engelbert gruber


[The reST specification page](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-references) says that phrase references end with ``\`_`` (or ``\`__``). But it looks like the ending string needs to be `` `_`` (or `` `__``).


---

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,

after one month of rc5

the final 0.22 is in the open
sorry for the long wait

the Release consists of ... maybe see online
https://docutils.sourceforge.io/0.22/RELEASE-NOTES.html

all the best and onto next
 e

Release 0.22rc5 (2025-06-24)
============================

Targets generated from hyperlink references with embedded URI or alias
are no longer "explicit" but "implicit" (i.e. with the same priority as
auto-generated section targets, see `implicit hyperlink targets`__).

__ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
   #implicit-hyperlink-targets

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

Release 0.22rc4 (2025-06-17)
============================

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.


Release 0.22rc3 (2025-06-10)
============================

New objects
  `transforms.references.CitationReferences`
     Mark citation_references as resolved if the backend
     uses a BibTeX database.

Output changes

  manpage:
     Do not drop text of internal targets.


Release 0.22rc2 (2025-05-22)
============================

Fix backwards-compatibility problem:
  reStructuredText section parsing no longer requires
  `parsers.rst.states.RSTStateMachine.memo.section_parents`
  (a cache introduced in Docutils 0.22rc1).

Deprecate `parsers.rst.states.Struct` (obsoleted by
`types.SimpleNamespace`).


Release 0.22rc1 (2025-05-06)
============================

reStructuredText:
  - Support `CSS3 units`_. This adds "ch", "rem", "vw", "vh", "vmin",
    "vmax", and "Q" to the `supported length units`__. Note that some
    output formats don't support all units.
  - New option "figname" for the `"figure"`_ directive.

  .. _CSS3 units: https://www.w3.org/TR/css-values-3/#lengths
  __ docs/ref/rst/restructuredtext.html#length-units

Document Tree / Docutils DTD
  - Allow multiple <term> elements in a `\<definition_list_item>`__
    (third-party writers may need adaption).
  - The first element in a <figure> may also be a <reference>
    (with nested "clickable" <image>).

  __ docs/ref/doctree.html#definition-list-item

Configuration changes
  - Make MathML the default math_output_ for the "html5" writer.
  - Change the default input_encoding_ from ``None`` (auto-detect) to
"utf-8".
  - Drop short options ``-i`` and ``-o``.
    Use the long equivalents ``--input-encoding`` and ``--output-encoding``.
    (See `command line interface`_ for the rationale.)
  - Rename configuration setting "output" to "output_path_".
  - New setting "validate_".
  - The manpage writer now recognizes the sections [writers] and
    [manpage writer] with the new setting `text_references`_.

Output changes
  LaTeX:
     Don't wrap references with custom reference_label_ in a ``\hyperref``
     command. The "hyperref" package generates hyperlinks for labels by
     default, so there is no change in the PDF
     (except for the starred forms like ``reference_label = \ref*``).

     Stop requiring "ifthen.sty". Add "ifthen" to the stylesheet__ setting
     or replace use of ``\ifthenelse{\isundefined...`` with the eTeX
     primitive ``\ifdefined``.

     __ docs/user/config.html#stylesheet-2

  HTML5:
     Unitless image_ size measures__ are written as <img> "width" and
     "hight" values instead of "style" rules.  The current behaviour
     is kept for values with units, so users may specify, e.g. ``:width:
     50px`` instead of ``:width: 50`` to override CSS stylesheet rules.

     __ docs/ref/doctree.html#measure

  manpage:
     Don't UPPERCASE section headings.

     Handle hyperlink references (see the text_references_ setting).

  null:
     The "null" writer output changed from None to the empty string.

     `publish_string()` now returns a `bytes` or `str` instance
     for all writers (as documented).

New objects
  `parsers.docutils_xml`
     parser for `Docutils XML`_ (e.g., the output of the "xml" writer).
     Provisional.

     Try ``docutils --parser=xml test/data/multiple-term-definitions.xml``
     or use the :parser: option of the `"include"`_ directive to include
     an XML file in a rST document.

  `nodes.Element.validate()`
     Raise `nodes.ValidationError` if the element does not comply with
     the `Docutils Document Model`_.
     Provisional.

  `writers.DoctreeTranslator`
     Generic Docutils document tree translator base class with
     `uri2path()` auxiliary method.
     Provisional.

Removed objects
  `core.Publisher.setup_option_parser()`
     internal, obsolete,
  `frontend.ConfigParser.get_section()`
     obsoleted by the configparser's "Mapping Protocol Access",
  `frontend.OptionParser.set_defaults_from_dict()`
     obsolete,
  `nodes.Element.set_class()`
     obsolete, append to Element['classes'] directly,
  `parsers.rst.directives.tables.CSVTable.decode_from_csv()`
     not required with Python 3,
  `parsers.rst.directives.tables.CSVTable.encode_from_csv()`
     not required with Python 3,
  `transforms.writer_aux.Compound`
     not used since Dec 2010,
  `utils.error_reporting`
     obsolete in Python 3,
  `utils.Reporter.set_conditions()`
     obsolete, set attributes via configuration settings or directly.

Removed localisations
  Mistranslations of the "admonition" directive name:
     Use "advies" (af), "varsel" (da), "warnhinweis" (de), "aviso" (es),
     "sciigo" (eo), "annonce" (fr), "avviso" (it), "advies" (nl),
     "zauważenie" (pl) (introduced in Docutils 0.21)
     or the English name "admonition".

New files
  ``docutils/parsers/rst/include/html-roles.txt``
     `Standard definition file`_ for additional roles matching HTML tags.

Removed files
  ``tools/rst2odt_prepstyles.py``
     Obsoleted by `writers.odf_odt.prepstyles`.
  ``docutils/utils/roman.py``
     Obsoleted by ``docutils/utils/_roman_numerals.py``

Bugfixes and improvements (see
https://docutils.sourceforge.io/0.22/HISTORY.html).

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...
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...
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