docutils-develop — For developer discussions of the implementation.

[Docutils-develop] [docutils:bugs] #522 `languages.get_language()` unsafe fallback import lets PyPI package shadow language module (e.g. `id`)

[Günter M. <mi...@us...>]

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

The issue should be fixed in [r10398].
Thank you for the report.



---

**[bugs:#522] \`languages.get\_language\(\)\` unsafe fallback import lets PyPI package shadow language module \(e.g. \`id\`\)**

**Status:** open-fixed
**Created:** Mon Aug 31, 2026 03:59 PM UTC by Bart van der Braak
**Last Updated:** Mon Aug 31, 2026 04:00 PM UTC
**Owner:** nobody


I'm DevOps Engineer at Blender and we noticed an issue popping up while building our the Indonesian language version of our documentation after updating one of our dependencies:

```
pipenv run sphinx-build -b html -j 12 -D language=id ./manual /home/blender/git/blender-manual-v450/build/html/id
Courtesy Notice:
Pipenv found itself running within a virtual environment,  so it will 
automatically use that environment, instead of  creating its own for any 
project. You can set
PIPENV_IGNORE_VIRTUALENVS=1 to force pipenv to ignore that environment and 
create  its own instead.
You can set PIPENV_VERBOSITY=-1 to suppress this warning.
Running Sphinx v7.4.7
loading translations [id]... done
making output directory... done
loading intersphinx inventory 'blender_api' from https://docs.blender.org/api/4.5/objects.inv...
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 2072 source files that are out of date
updating environment: [new config] 2072 added, 0 changed, 0 removed
Sphinx parallel build error:
AttributeError: module 'id' has no attribute 'bibliographic_fields'
```
Source: https://builder.staging.blender.org/admin/#/builders/16/builds/4

It looks like `docutils.languages.get_language()` falls back to a bare `import <language_code>` when no `docutils.languages.<code>` module exists. If a PyPI package happens to share the name of a language code (e.g. `id`, the PEP 740 attestations package used by `twine`), that package gets imported instead, breaking language support with no clear error.

### Reproduce

I crafted the following A/B scenario:

#### A: clean venv, no `id` package

```bash
[bart@ws-bart:/tmp]$ python3 -m venv /tmp/env_clean
[bart@ws-bart:/tmp]$ /tmp/env_clean/bin/pip install -q docutils

[notice] A new release of pip is available: 26.1.2 -> 26.2.1
[notice] To update, run: /tmp/env_clean/bin/python3 -m pip install --upgrade pip
[bart@ws-bart:/tmp]$ /tmp/env_clean/bin/python -c "
from docutils.languages import get_language
mod = get_language('id')
print(mod)
print(hasattr(mod, 'bibliographic_fields'))
"
<module 'docutils.languages.en' from '/tmp/env_clean/lib/python3.14/site-packages/docutils/languages/en.py'>
True
```

#### B: venv with `id` pypi package installed

```bash
[bart@ws-bart:/tmp]$ # --- B: venv with `id` pypi package installed ---
[bart@ws-bart:/tmp]$ python3 -m venv /tmp/env_poisoned
[bart@ws-bart:/tmp]$ /tmp/env_poisoned/bin/pip install -q docutils id

[notice] A new release of pip is available: 26.1.2 -> 26.2.1
[notice] To update, run: /tmp/env_poisoned/bin/python3 -m pip install --upgrade pip
[bart@ws-bart:/tmp]$ /tmp/env_poisoned/bin/python -c "
from docutils.languages import get_language
mod = get_language('id')
print(mod)
print(hasattr(mod, 'bibliographic_fields'))
"
<module 'id' from '/tmp/env_poisoned/lib/python3.14/site-packages/id/__init__.py'>
False
```

### Versions used

```
docutils 0.21.2, Python 3.12
```


---

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.

[Docutils-develop] [docutils:bugs] #520 SmartQuotes misclassifies an opening single quote before a converted ellipsis

[Günter M. <mi...@us...>]

Thanks for the report.

IMO, the issue is "SmartQuotes misclassifies an opening quote before non-ASCII punctuation when there are bracktes around". 

Test sample:
~~~rst
The misclassification happens also in other cases:
  ('...') ("...") ('--') ("--") ('---') ("---") ASCII patterns

  ('…') ("…") ('–') ("–") ('—') ("—") ("—") Unicode punctuation

* No difference between single and double quotes
* No difference between smartquote patterns or direct Unicode input.

Word characters:
('a') ('b') ('c') ('D') ASCII
('ä') ('Ö') ('ß') ('λ') non-ASCII

ASCII punctuation and non-word characters:
('!') ('?') (';') (':') ('.') (',') ('/') ('#') ('+') ('-') ('*') ('=')
('^') ('"') ('%') ('$') but ('&')

non-ASCII punctuation:
('¡') ('¿') ('‧') ('‰') ('⁋') ('∀')

* ASCII punctuation (except the ampersand) is OK,
  non-ASCII punctuation is problematic.

OTOH, without brackets, everything is fine:
  '.' '&' '...' '--' '¡' '¿' '‧' '‰' '⁋'.

There are other misclassifications, e.g., the quote after an EM-DASH at the
end of a paragraph:

ASCII pattern ('---') ('---')

Unicode ('—') ('—')
~~~

> I'm not sure if this is an issue worth fixing, [...]

Nor am I, "smartquotes" is intended as a simple helper and will always have its limitations (cf. [caveats](https://docutils.sourceforge.io/docs/user/smartquotes.html#caveats)). 


---

**[bugs:#520] SmartQuotes misclassifies an opening single quote before a converted ellipsis**

**Status:** open
**Created:** Thu Aug 20, 2026 10:33 PM UTC by Jared Dillard
**Last Updated:** Thu Aug 20, 2026 10:33 PM UTC
**Owner:** nobody


When smart quotes and ellipsis conversion are enabled, a straight single quote before `...` is converted to a closing quotation mark instead of an opening quotation mark.

Input:

```text
Add secondary prompts ('...') to the sidebar.
```

Actual output:

```text
Add secondary prompts (’…’) to the sidebar.
```

Expected output:

```text
Add secondary prompts (‘…’) to the sidebar.
```

In the actual output, both quotes are U+2019 RIGHT SINGLE QUOTATION MARK. The opening quote should be U+2018 LEFT SINGLE QUOTATION MARK.

## Minimal reproduction

```python
from docutils.core import publish_parts

source = "Add secondary prompts ('...') to the sidebar.\n"
parts = publish_parts(
    source,
    writer_name="html5",
    settings_overrides={
        "smart_quotes": True,
        "language_code": "en",
    },
)
print(parts["fragment"].strip())
```

Output:

```html
<p>Add secondary prompts (’…’) to the sidebar.</p>
```

## Environment

- Python: 3.12.7
- Docutils: 0.22.3

## Additional context

This was originally reported in [Sphinx issue #9713](https://github.com/sphinx-doc/sphinx/issues/9713). Docutils 0.17 fixed the separate quote-classification cases involving opening or separator characters such as `[`, `-`, and `+`. Those cases work with Docutils 0.22.3, but the ellipsis case above remains reproducible. I'm not sure if this is an issue worth fixing, but wanted to pass it along.

The behavior seems to be related to conversion order: `...` becomes U+2026 HORIZONTAL ELLIPSIS before the neighboring quote is classified.


---

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.

[Docutils-develop] [docutils:bugs] #521 Document fetch triggered by XML writer raw XML validation

[Günter M. <mi...@us...>]

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

Fixed in [r10395].



---

**[bugs:#521] Document fetch triggered by XML writer raw XML validation**

**Status:** open-fixed
**Created:** Fri Aug 21, 2026 12:21 PM UTC by Florian Weimer
**Last Updated:** Fri Aug 21, 2026 12:21 PM UTC
**Owner:** nobody
**Attachments:**

- [RHEL-214776.html](https://sourceforge.net/p/docutils/bugs/521/attachment/RHEL-214776.html) (7.8 kB; text/html)


Red Hat Product Security has asked me to forward the attached vulnerability report. I do not think it is a significant issue (perhaps no vulnerability at all), so I'm not filing a private bug for it.

This is a small reproducer:

```
from docutils.core import publish_string
RST_INPUT = """\
.. raw:: xml

   <!DOCTYPE r [<!ENTITY xxe SYSTEM "http://127.0.0.1:9/">]>
   <r>&xxe;</r>
"""
print(publish_string(RST_INPUT, writer_name='xml'))
```

It fails with a `urllib.error.URLError` exception, indicating that the conversion triggered unexpected network activity.

I've been told to mention: Found by AISLE in partnership with Red Hat


---

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.

[Docutils-develop] [docutils:bugs] #519 XSS via unescaped HTML in PEP email masking transform

[Günter M. <mi...@us...>]

- **status**: open --> open-fixed
- **private**: Yes --> No
- **Comment**:

The issue is fixed in [r10394].
Thank you again for reporting.



---

**[bugs:#519] XSS via unescaped HTML in PEP email masking transform**

**Status:** open-fixed
**Created:** Mon Jul 27, 2026 10:09 AM UTC by Florian Weimer
**Last Updated:** Sat Aug 15, 2026 07:10 PM UTC
**Owner:** nobody
**Attachments:**

- [RHEL-214726.txt](https://sourceforge.net/p/docutils/bugs/519/attachment/RHEL-214726.txt) (5.9 kB; text/plain)


I have been instructed to forward the attached security report to you privately. As far as I can tell, it is accurate, and the vulnerability is still present in the current sources. My understanding is that docutils offers a processing mode that is robust in the presence of malicious inputs, which is why a trust boundary is crossed.

Please let me know how you want to handle this.

An automatically generated proper reproducer looks like this:

```
#!/usr/bin/env python3
"""Reproducer for XSS in PEP email masking transform (mask_email)."""

import sys
sys.path.insert(0, 'docutils')

from docutils.core import publish_parts

src = """\
PEP: 9999
Title: Test
Author: `"><img src=x onerror=alert(1)> <ev...@ex...>`_
Status: Draft
Type: Standards Track
Created: 01-Jan-2026

Abstract
========

Test.
"""

parts = publish_parts(source=src, reader_name='pep', writer_name='html')
body = parts['html_body']

if '<img src=x onerror=alert(1)>' in body:
    print('VULNERABLE: unescaped HTML found in output')
    print()
    for line in body.splitlines():
        if 'onerror' in line:
            print(' ', line.strip())
    sys.exit(1)
else:
    print('OK: no unescaped HTML in output')
    sys.exit(0)
```

The reconstructed patch is:

```
Index: docutils/docutils/transforms/peps.py
===================================================================
--- docutils/docutils/transforms/peps.py        (revision 10391)
+++ docutils/docutils/transforms/peps.py	(working copy)
@@ -303,8 +303,8 @@
         if ref['refuri'][8:] in non_masked_addresses:
             replacement = ref[0]
         else:
-            replacement_text = ref.astext().replace('@', ' at ')
-            replacement = nodes.raw('', replacement_text, format='html')
+            replacement_text = ref.astext().replace('@', ' at ')
+            replacement = nodes.Text(replacement_text)
         if pepno is None:
             return replacement
         else:
```


---

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.

Re: [Docutils-develop] Private Sourceforge bugs are posted to docutils-develop

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

Dear Florian,

On 2026-07-27, Florian Weimer via Docutils-develop wrote:
> I've noticed that private bugs are announced on this list, making the
> private checkbox in the Sourceforge bug tracker ineffictive.

Thank you for pointing this out. 
Sorry for the delay, I was on summer holidays in the great outdoors.

I changed the settings to "Send notifications for: All public ticket
changes", so this should no longer be an issue. 

Instead, there is a real chance that the issue is overlooked as I usually
just check the lists.

> Is there are more reliable way to report security
> issues privately?

You can email the developers directly, preferably the one(s) listed in 
copyright notice of the affected module file (however, some developers
are no longer active). 


That said, I was able to read your private bug report and will respond there.

Günter

[Docutils-develop] Private Sourceforge bugs are posted to docutils-develop

[Florian W. <fw...@re...>]

I've noticed that private bugs are announced on this list, making the
private checkbox in the Sourceforge bug tracker ineffictive.

I think I successfully canceled the previous attempt to post a private
bug of mine here.  Is there are more reliable way to report security
issues privately?

(The issues I've been asked to report probably do not need to handled
privately in my personal opinion, but I've been specifically instructed
not to report them publicly, and would have to obtain permission from
our security team before posting them to this list, for example.)

Thanks,
Florian

Re: [Docutils-develop] AI policy?

[engelbert g. <eng...@gm...>]

Yes +2 for this

personally i tried ai and indeed not fit my work ... way

as long as we are not on any git
pull requests mean commits, patches, contributions
i somehow think restricting to git-language a little bit limited

cheers

On Wed, 10 Jun 2026 at 19:03, Karl O. Pinc <ko...@ka...> wrote:
>
> On 2026-06-10 11:02, Guenter Milde via Docutils-develop wrote:
>
> > our sister (or daughter) project Sphinx just added an AI policy page
> > https://www.sphinx-doc.org/en/master/internals/ai-policy.html
> >
> > I propose to include a similar text into our Project Policies
> > https://docutils.sourceforge.io/docs/dev/policies.html
> >
> > What do you think?
>
> Makes perfect sense to me.  But that means pretty much
> nothing because I have no real standing regards
> docutils.
>
>
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.

[Docutils-develop] [docutils:feature-requests] #36 prevent accidential file overwrites by wildcard expansion

[Günter M. <mi...@us...>]

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

The second positional argument for the destination is dropped in [r10348] . Now, more than one positional argument will result in an error.
Use the `--output` and `-o` options or output redirection (`>`) to specify an output file.



---

**[feature-requests:#36] prevent accidential file overwrites by wildcard expansion**

**Status:** open-fixed
**Group:** Default
**Created:** Fri Mar 15, 2013 10:43 PM UTC by Jakub Wilk
**Last Updated:** Tue Apr 29, 2025 07:47 PM UTC
**Owner:** nobody


A Debian user complained that if you use a wildcard as input file name, and the wildcard unexpectedly expands to two names, then rst2html will overwrite your files:
http://bugs.debian.org/654690

Would if be possible to add an option for not overwriting output files, that you could add to your configuration file, and later override from command line if needed?



---

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.

Re: [Docutils-develop] roadmap (was: release 0.23)

[engelbert g. <eng...@gm...>]

i am fine with 1.0

cheers

On Wed, 10 Jun 2026 at 11:27, Guenter Milde via Docutils-develop
<doc...@li...> wrote:
>
> Dear Docutils develpers,
>
> it is now 2 weeks since
> On 2026-05-27, engelbert gruber wrote:
>
> > release 0.23 is out
>
>
> There has been no doc report yet, so either there are no new bugs :)
> or no one cares. :(
>
> I suggest to let the next release be Docutils 1.0.
> This allows us to officially switch to `Semantic Versioning`__
> and to implement the changes__ anounced for 1.0.
>
> __ https://semver.org/
> __ https://docutils.sourceforge.io/RELEASE-NOTES.html#future-changes
>
> Thanks,
> Günter
>
>
>
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.

Re: [Docutils-develop] AI policy?

[Karl O. P. <ko...@ka...>]

On 2026-06-10 11:02, Guenter Milde via Docutils-develop wrote:

> our sister (or daughter) project Sphinx just added an AI policy page
> https://www.sphinx-doc.org/en/master/internals/ai-policy.html
> 
> I propose to include a similar text into our Project Policies
> https://docutils.sourceforge.io/docs/dev/policies.html
> 
> What do you think?

Makes perfect sense to me.  But that means pretty much
nothing because I have no real standing regards
docutils.

[Docutils-develop] AI policy?

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

Dear Docutils developers,

our sister (or daughter) project Sphinx just added an AI policy page
https://www.sphinx-doc.org/en/master/internals/ai-policy.html

I propose to include a similar text into our Project Policies
https://docutils.sourceforge.io/docs/dev/policies.html

What do you think?

Günter

[Docutils-develop] roadmap (was: release 0.23)

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

Dear Docutils develpers,

it is now 2 weeks since
On 2026-05-27, engelbert gruber wrote:

> release 0.23 is out


There has been no doc report yet, so either there are no new bugs :)
or no one cares. :(

I suggest to let the next release be Docutils 1.0.
This allows us to officially switch to `Semantic Versioning`__
and to implement the changes__ anounced for 1.0.

__ https://semver.org/
__ https://docutils.sourceforge.io/RELEASE-NOTES.html#future-changes

Thanks,
Günter

[Docutils-develop] [docutils:patches] #81 latex2e: Allow footnotes to be more easily customizable

[Günter M. <mi...@us...>]

- **status**: open --> pending-remind



---

**[patches:#81] latex2e: Allow footnotes to be more easily customizable**

**Status:** pending-remind
**Group:** None
**Created:** Wed Jul 13, 2011 10:35 AM UTC by Kirill Smelkov
**Last Updated:** Wed May 13, 2026 10:24 PM UTC
**Owner:** nobody


For example Russian GOST 19.106 requires that footnotes contain
footnote-number + "\)" which in plain LaTeX could be done as

\renewcommand\{\thefootnote\}\{\arabic\{footnote\}\)\}
^
note "\)"

but Docutils uses its own \DUfootnotemark and \DUfootnotetext macros
with hyperlinks setup which redefine \thefootnote in-there and the
above-shown tweak does not work.

So in order to make even small tweaks for foot notes, users have to
either "fork" \DUfootnotemark and \DUfootnotetext in their stylesheet,
or better, what I'm proposing here, just redefine here-introduced
\DUthefootnote, e.g. like this:

\providecommand\*\{\DUthefootnote\}\[1\]\{\#1\)\}

Thanks,
Kirill


---

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.

[Docutils-develop] [docutils:patches] #182 An implementation of --latex-footnotes

[Günter M. <mi...@us...>]

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

"LaTeX footnotes" are supported in [Docutils 0.23](https://pypi.org/project/docutils/0.23/).
I applied the patch and did some heavy testing and refactoring later.
Note that this is still provisional and needs more "road testing". 

Docutils does not handle all cases where standard LaTeX does not support footnotes in special places (like headings, inside tables, ...) as there are different solutions out in optional LaTeX packages and we don't want to force one special approach or dependency on authors.



---

**[patches:#182] An implementation of --latex-footnotes**

**Status:** closed-accepted
**Group:** None
**Created:** Fri Jun 18, 2021 11:39 PM UTC by John Thorvald Wodder II
**Last Updated:** Fri May 01, 2026 06:12 PM UTC
**Owner:** nobody
**Attachments:**

- [latex-footnotes.patch](https://sourceforge.net/p/docutils/patches/182/attachment/latex-footnotes.patch) (9.4 kB; application/octet-stream)


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.


---

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.

[Docutils-develop] [docutils:patches] #215 Fix Unknown target name warning in roles.rst

[Günter M. <mi...@us...>]

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

Fixed in [Docutils 0.23](https://pypi.org/project/docutils/0.23/).
Thanks for report and patch suggestion.



---

**[patches:#215] Fix Unknown target name warning in roles.rst**

**Status:** closed-fixed
**Group:** None
**Created:** Fri Sep 19, 2025 07:13 PM UTC by Dmitry Shachnev
**Last Updated:** Wed Oct 08, 2025 06:07 AM UTC
**Owner:** nobody
**Attachments:**

- [0001-Fix-Unknown-target-name-warning-in-roles.rst.patch](https://sourceforge.net/p/docutils/patches/215/attachment/0001-Fix-Unknown-target-name-warning-in-roles.rst.patch) (918 Bytes; text/x-patch)


This fixes a minor problem that I noticed when building a Debian package for 0.22.1.


---

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.

[Docutils-develop] [docutils:patches] #216 Fix type annotation for get_default_settings

[Günter M. <mi...@us...>]

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

Fixed in [Docutils 0.23](https://pypi.org/project/docutils/0.23/).
Thank you again for report and patch.



---

**[patches:#216] Fix type annotation for get\_default\_settings**

**Status:** closed-accepted
**Group:** None
**Created:** Thu Jan 22, 2026 09:04 AM UTC by Dmitry Shachnev
**Last Updated:** Sun Jan 25, 2026 02:16 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Fix-type-annotation-for-get\_default\_settings.patch](https://sourceforge.net/p/docutils/patches/216/attachment/0001-Fix-type-annotation-for-get_default_settings.patch) (966 Bytes; text/x-patch)


It accepts classes themselves, not instances of those classes.

This fixes error from mypy that I have for code that calls `get_default_settings(Writer)`.
```
error: Argument 1 to "get_default_settings" has incompatible type "type[Writer]"; expected "SettingsSpec"  [arg-type]
```


---

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.

[Docutils-develop] [docutils:bugs] #517 content_offset in directives inside grid/simple tables are off

[Günter M. <mi...@us...>]

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

Fixed in [Docutils 0.23](https://pypi.org/project/docutils/0.23/).
Thank you for report and testing.



---

**[bugs:#517] content\_offset in directives inside grid/simple tables are off**

**Status:** closed-fixed
**Created:** Sat Dec 27, 2025 05:07 PM UTC by Felix Fontein
**Last Updated:** Wed Jan 07, 2026 08:23 PM UTC
**Owner:** nobody


When parsing a directive in a grid table or simple table, the directive's `content_offset` is off by one. (When nesting such a table in another such a table, it's off by one for every nesting level.)

For example, for the following code block directives, `content_offset` is always off from the real content line where the code block's content is in:

```rst
content_offset is off by 1:

+----------------------+
| .. code-block:: yaml |
|                      |
|    - foo             |
+----------------------+

content_offset is off by 2:

+------------------------+
|+----------------------+|
|| .. code-block:: yaml ||
||                      ||
||    - foo             ||
|+----------------------+|
+------------------------+

content_offset is off by 3:

+--------------------------+
|+------------------------+|
||+----------------------+||
||| .. code-block:: yaml |||
|||                      |||
|||    - foo             |||
||+----------------------+||
|+------------------------+|
+--------------------------+

content_offset is off by 1:

=====  =====
col 1  col 2
=====  =====
1      .. code-block:: yaml

          - foo
=====  =====

content_offset is off by 2:

=====  =====
col 1  col 2
=====  =====
1      =====  =====
       col 1  col 2
       =====  =====
       1      .. code-block:: yaml

                 - foo
       =====  =====
=====  =====
```

(I've noticed this when registering an own code block directive to find the actual location - row and column - of the code block's contents, to be able to give more precise error messages when linting.)


---

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.

[Docutils-develop] release 0.23

[engelbert g. <eng...@gm...>]

hei to all,

release 0.23 is out

nothing changed since 0.23rc1
still

General:
  - Define `public API and backwards compatibility policy`_.

rST parser:
  - Problems with the "include" directive are reported as ERROR, not SEVERE.
  - The "include" directive options :start-after: and :end-before: may now
    also be used without value (standing for an empty line).
  - The highlight language of a custom role based on the `"code" role`_
    defaults to the role's name (if supported by Pygments_).
    Specifying ``:language: none`` turns off syntax highlight.

HTML5 writer:
  - If a section has several IDs, use the last one (from the first
    `explicit target`__) as self-link_.

    __ docs/ref/rst/restructuredtext.html#explicit-hyperlink-targets

LaTeX writer:
  - Do not write ``\label`` commands for section titles and other
    implicit targets if there is no matching reference in the document.
  - Support `semantic inline markup roles`_.

Configuration changes
  - New setting `legacy_ids`_.
  - The new setting `latex_footnotes`_ replaces "docutils_footnotes"
    (ignored since Docutils 0.13.1).  The command line option
    ``--docutils-footnotes`` is kept and sets latex_footnotes_ to False.

New objects
  `nodes.document.names`:
    Internal attribute mapping `reference names`_ to the
    referenced elements (or ``None`` if the name is a duplicate).
  `nodes.document.note_names()`:
    Register an element's names, check for duplicates.
  `nodes.document.set_duplicate_name()`
    Called by `nodes.document.note_names()` to handle duplicate names.
    Provisional.
  `transforms.SectionIDs`:
    Ensure all sections have an identifier_.

Removed objects
  `parsers.rst.directives.tables.CSVTable.check_requirements()`
     not required with Python 3.
  `nodes.document.set_duplicate_name_id()`
     internal method, replaced by `nodes.document.set_duplicate_name()`.

[Docutils-develop] Release 0.23 Wednesday 27 may

[engelbert g. <eng...@gm...>]

Hei

if no stop is happening

Cheers

[Docutils-develop] [docutils:patches] #81 latex2e: Allow footnotes to be more easily customizable

[Günter M. <mi...@us...>]

- **Group**:  --> None
- **Comment**:

There is support for "--latex-footnotes" in Docutils 0.23 (rc1 is just out) so maybe we can close this ticket as outdated.



---

**[patches:#81] latex2e: Allow footnotes to be more easily customizable**

**Status:** open
**Group:** None
**Created:** Wed Jul 13, 2011 10:35 AM UTC by Kirill Smelkov
**Last Updated:** Wed Jul 13, 2011 10:35 AM UTC
**Owner:** nobody


For example Russian GOST 19.106 requires that footnotes contain
footnote-number + "\)" which in plain LaTeX could be done as

\renewcommand\{\thefootnote\}\{\arabic\{footnote\}\)\}
^
note "\)"

but Docutils uses its own \DUfootnotemark and \DUfootnotetext macros
with hyperlinks setup which redefine \thefootnote in-there and the
above-shown tweak does not work.

So in order to make even small tweaks for foot notes, users have to
either "fork" \DUfootnotemark and \DUfootnotetext in their stylesheet,
or better, what I'm proposing here, just redefine here-introduced
\DUthefootnote, e.g. like this:

\providecommand\*\{\DUthefootnote\}\[1\]\{\#1\)\}

Thanks,
Kirill


---

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.

[Docutils-develop] [docutils:bugs] #482 manpage: section numbers wrongly in boldface in "See also" section

[engelbert g. <gr...@us...>]

one problem is the manpage writer does not know it is man page reference, it is only marked as emphasize

second

~~~
*groff_man_style*\(7)
  is a reference to the *groff* *man* macro language, with much advice
  for document authors.
~~~

is
~~~
        <definition_list_item>
            <term>
                <emphasis>
                    groff_man_style
                (7)
            <definition>
~~~

and defintionlistitems are typeset BOLD 
admittedly a decision i simply made without asking

problem one would require the manpage writer to lex/parse


---

**[bugs:#482] manpage: section numbers wrongly in boldface in "See also" section**

**Status:** open
**Labels:** manpage writer 
**Created:** Wed Mar 27, 2024 01:22 AM UTC by G. Branden Robinson
**Last Updated:** Wed Mar 27, 2024 11:16 AM UTC
**Owner:** engelbert gruber


The parenthesized section number of a man page document should be rendered upright at normal weight, not in boldface.

This appears to be an unintentional defect in the manpage writer.  Here's a snippet of _rst2man_ output.

~~~
.SH SEE ALSO
.INDENT 0.0
.TP
.B \fIgroff_man_style\fP(7)
is a reference to the \fIgroff\fP \fIman\fP macro language, with much advice
for document authors.
.TP
.B \fImandoc\fP(1)
is a non\-\fIroff\fP\-based system for formatting man pages.
.UNINDENT
~~~

It's pretty confusing to humans to mix font selection escape sequences with _man_ font macros.  (I also think that macros should be used in preference to formatter requests or escape sequences wherever possible, but I acknowledge that this is a much bigger challenge for document format conversion programs than for human writers.)

Here's what I propose when formatting a man page cross reference, in case you're doing any pattern matching to detect them.

~~~
.TP
.B \fIgroff_man_style\fP\R(7)\fP
~~~

If you're _not_ doing pattern matching to detect man page cross references, the problem may be harder.

Here's my rST input for the foregoing.

~~~
See also
========

*groff_man_style*\(7)
  is a reference to the *groff* *man* macro language, with much advice
  for document authors.

*mandoc*\(1)
  is a non-*roff*-based system for formatting man pages.
~~~

It appears to me that the decision to set the paragraph tag (definition list headword) in bold was _rst2man_'s; it was not derived from any formatting in the rST source document.  I humbly suggest reconsidering that choice, and let rST document authors select whatever degree of typographic emphasis for the paragraph tag/definition list headword they desire.  In fact it appears to be that they can already do so, so the ``B`` call may just be getting in the way.


---

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.

[Docutils-develop] docutils 0.23rc1 released

[engelbert g. <eng...@gm...>]

Hello dear everyone,

thanks to Günter a lot was done

please tryout the rc1 and report any problems

Changes in 0.23rc1

General:
  - Define `public API and backwards compatibility policy`_.

rST parser:
  - Problems with the "include" directive are reported as ERROR, not SEVERE.
  - The "include" directive options :start-after: and :end-before: may now
    also be used without value (standing for an empty line).
  - The highlight language of a custom role based on the `"code" role`_
    defaults to the role's name (if supported by Pygments_).
    Specifying ``:language: none`` turns off syntax highlight.

HTML5 writer:
  - If a section has several IDs, use the last one (from the first
    `explicit target`__) as self-link_.

    __ docs/ref/rst/restructuredtext.html#explicit-hyperlink-targets

LaTeX writer:
  - Do not write ``\label`` commands for section titles and other
    implicit targets if there is no matching reference in the document.
  - Support `semantic inline markup roles`_.

Configuration changes
  - New setting `legacy_ids`_.
  - The new setting `latex_footnotes`_ replaces "docutils_footnotes"
    (ignored since Docutils 0.13.1).  The command line option
    ``--docutils-footnotes`` is kept and sets latex_footnotes_ to False.

New objects
  `nodes.document.names`:
    Internal attribute mapping `reference names`_ to the
    referenced elements (or ``None`` if the name is a duplicate).
  `nodes.document.note_names()`:
    Register an element's names, check for duplicates.
  `nodes.document.set_duplicate_name()`
    Called by `nodes.document.note_names()` to handle duplicate names.
    Provisional.
  `transforms.SectionIDs`:
    Ensure all sections have an identifier_.

Removed objects
  `parsers.rst.directives.tables.CSVTable.check_requirements()`
     not required with Python 3.
  `nodes.document.set_duplicate_name_id()`
     internal method, replaced by `nodes.document.set_duplicate_name()`.

[Docutils-develop] [docutils:patches] #182 An implementation of --latex-footnotes

[Günter M. <mi...@us...>]

- **status**: open --> open-accepted
- **Comment**:

The patch is commited in [r10314]. The commits up to [r10322] take care of 99% of the remaining 1% problematic cases and document the changes and limitations.



---

**[patches:#182] An implementation of --latex-footnotes**

**Status:** open-accepted
**Group:** None
**Created:** Fri Jun 18, 2021 11:39 PM UTC by John Thorvald Wodder II
**Last Updated:** Sat Jun 26, 2021 10:28 PM UTC
**Owner:** nobody
**Attachments:**

- [latex-footnotes.patch](https://sourceforge.net/p/docutils/patches/182/attachment/latex-footnotes.patch) (9.4 kB; application/octet-stream)


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.


---

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.

[Docutils-develop] [docutils:bugs] #518 id_prefix removes footnote prefix from

[Günter M. <mi...@us...>]

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

Fine.
The updates are now also at https://docutils.sourceforge.io/docs/, so I'll close this issue.
Thanks again for reporting.



---

**[bugs:#518] id\_prefix removes footnote prefix from **

**Status:** closed-fixed
**Created:** Sun Mar 22, 2026 12:40 AM UTC by miketheman
**Last Updated:** Fri Apr 10, 2026 01:22 PM UTC
**Owner:** nobody


I was recently working on adding an `id_prefix` string to enable the behavior as described in https://docutils.sourceforge.io/docs/user/config.html#id-prefix

It works pretty consistently, however when I came across a footnote, it removed the `footnote-` prefix from the rendered ID, but not the associated `href` value, leaving the rendered links a little more confusing than before.

Here's a reproduction example:

```python
import sys
from difflib import unified_diff

from docutils.core import publish_parts


INPUT_RST_WITH_FOOTNOTES = """
Footnote reference, like [5]_.

Some Text

.. [5] A numerical footnote.
"""


def render_body(rst: str, settings: dict) -> str:
    return publish_parts(rst, writer="html5", settings_overrides=settings)["body"]


settings = {"output_encoding": "unicode"}
basic = render_body(INPUT_RST_WITH_FOOTNOTES, settings)

settings["id_prefix"] = "user-content-"
prefixed = render_body(INPUT_RST_WITH_FOOTNOTES, settings)

sys.stdout.writelines(
    unified_diff(
        basic.splitlines(keepends=True),
        prefixed.splitlines(keepends=True),
        fromfile="basic.html",
        tofile="prefixed.html",
    )
)
```

Output with Docutils 0.22.4:

    :::udiff
    --- basic.html
    +++ prefixed.html
    @@ -1,8 +1,8 @@
    -<p>Footnote reference, like <a class="brackets" href="#footnote-1" id="footnote-reference-1" role="doc-noteref"><span class="fn-bracket">[</span>5<span class="fn-bracket">]</span></a>.</p>
    +<p>Footnote reference, like <a class="brackets" href="#user-content-5" id="user-content-footnote-reference-1" role="doc-noteref"><span class="fn-bracket">[</span>5<span class="fn-bracket">]</span></a>.</p>
     <p>Some Text</p>
    <aside class="footnote-list brackets">
    -<aside class="footnote brackets" id="footnote-1" role="doc-footnote">
    -<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-1">5</a><span class="fn-bracket">]</span></span>
    +<aside class="footnote brackets" id="user-content-5" role="doc-footnote">
    +<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#user-content-footnote-reference-1">5</a><span class="fn-bracket">]</span></span>
    <p>A numerical footnote.</p>
    </aside>
    </aside>

The things that are different:

- the footnote reference changes from `1` to `5` - which is more accurate than before - yay!
- the footnote id/href value loses it's `footnote-` prefix in the reference part, the backlinks have the prefix + `footnote-`

Both link and backlink work, it's more about the inconsistent naming of the `id` and associated `href` values, and ther output behavior not matching the expectation from the documentation.

Hope this makes sense!


---

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.

[Docutils-develop] [docutils:bugs] Re: #518 id_prefix removes footnote prefix from

[Günter M. <mi...@us...>]

> Is there something to change in SF classification to make this a documentation issue vs bug?

Classing the report as bug report is IMO correct, defining the problem as a documentation issue should help to address it.

Would the changes in [r10310] and [10311] have prevented the "wrong feeling"?
(It will take some time to get them into the published documentation at  https://docutils.sourceforge.io/docs/.)



---

**[bugs:#518] id\_prefix removes footnote prefix from **

**Status:** open
**Created:** Sun Mar 22, 2026 12:40 AM UTC by miketheman
**Last Updated:** Sat Mar 28, 2026 08:10 PM UTC
**Owner:** nobody


I was recently working on adding an `id_prefix` string to enable the behavior as described in https://docutils.sourceforge.io/docs/user/config.html#id-prefix

It works pretty consistently, however when I came across a footnote, it removed the `footnote-` prefix from the rendered ID, but not the associated `href` value, leaving the rendered links a little more confusing than before.

Here's a reproduction example:

```python
import sys
from difflib import unified_diff

from docutils.core import publish_parts


INPUT_RST_WITH_FOOTNOTES = """
Footnote reference, like [5]_.

Some Text

.. [5] A numerical footnote.
"""


def render_body(rst: str, settings: dict) -> str:
    return publish_parts(rst, writer="html5", settings_overrides=settings)["body"]


settings = {"output_encoding": "unicode"}
basic = render_body(INPUT_RST_WITH_FOOTNOTES, settings)

settings["id_prefix"] = "user-content-"
prefixed = render_body(INPUT_RST_WITH_FOOTNOTES, settings)

sys.stdout.writelines(
    unified_diff(
        basic.splitlines(keepends=True),
        prefixed.splitlines(keepends=True),
        fromfile="basic.html",
        tofile="prefixed.html",
    )
)
```

Output with Docutils 0.22.4:

    :::udiff
    --- basic.html
    +++ prefixed.html
    @@ -1,8 +1,8 @@
    -<p>Footnote reference, like <a class="brackets" href="#footnote-1" id="footnote-reference-1" role="doc-noteref"><span class="fn-bracket">[</span>5<span class="fn-bracket">]</span></a>.</p>
    +<p>Footnote reference, like <a class="brackets" href="#user-content-5" id="user-content-footnote-reference-1" role="doc-noteref"><span class="fn-bracket">[</span>5<span class="fn-bracket">]</span></a>.</p>
     <p>Some Text</p>
    <aside class="footnote-list brackets">
    -<aside class="footnote brackets" id="footnote-1" role="doc-footnote">
    -<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-1">5</a><span class="fn-bracket">]</span></span>
    +<aside class="footnote brackets" id="user-content-5" role="doc-footnote">
    +<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#user-content-footnote-reference-1">5</a><span class="fn-bracket">]</span></span>
    <p>A numerical footnote.</p>
    </aside>
    </aside>

The things that are different:

- the footnote reference changes from `1` to `5` - which is more accurate than before - yay!
- the footnote id/href value loses it's `footnote-` prefix in the reference part, the backlinks have the prefix + `footnote-`

Both link and backlink work, it's more about the inconsistent naming of the `id` and associated `href` values, and ther output behavior not matching the expectation from the documentation.

Hope this makes sense!


---

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.