docutils-develop — For developer discussions of the implementation.

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

[Docutils-develop] [docutils:feature-requests] #89 Public API, versioning, and deprecation

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

I'd like to finalise/close this issue and apply the proposed API definition and backwards policy Commit	[r10309]  updated the proposal [EP 10](https://docutils.sourceforge.io/docs/eps/ep-010.html). Unless someone objects, I'd apply the attached patch in 4 weeks to ship with Docutils 0.23. After this, Docutils will switch "semantic versioning".


Attachments:

- [0001-Define-public-API-and-backwards-compatible-policy.patch](https://sourceforge.net/p/docutils/feature-requests/_discuss/thread/c3485acc56/a268/attachment/0001-Define-public-API-and-backwards-compatible-policy.patch) (10.2 kB; text/x-patch)


---

**[feature-requests:#89] Public API, versioning, and deprecation**

**Status:** open
**Group:** Default
**Created:** Sun Jan 16, 2022 01:39 AM UTC by Adam  Turner
**Last Updated:** Wed May 14, 2025 02:35 PM UTC
**Owner:** nobody


As requested by @milde in https://sourceforge.net/p/docutils/bugs/441/#7043/cdb8/8742/6e7f I'm opening this issue to allow for discussion on Docutils' public API, versioning policy, and deprecation.

[Enhancement proposal 10](https://docutils.sourceforge.io/docs/eps/ep-010.html) summarizes the discussion. It will be updated with new insights and decisions until a consensus is found.

This also relates to FR 87 on type annotations. 

From Günter, 

> The idea is to reconcile the reality (Docutils is used as if it were mature) and the version number (<1) once the API sufficiently defined a deprecation policy is agreed.

The only text I can find on library versioning is at https://docutils.sourceforge.io/docs/dev/policies.html#version-identification, excerpt below:

> **Major releases** (x.0, e.g. 1.0) will be rare, and will
represent major changes in API, functionality, or commitment.  The
major number will be bumped to 1 when the project is
feature-complete, and may be incremented later if there is a major
change in the design or API.  When Docutils reaches version 1.0,
the major APIs will be considered frozen.
For details, see the `backwards compatibility policy`_.

> Releases that change the minor number (x.y, e.g. 0.5) will be
**feature releases**; new features from the `Docutils core`_ will
be included.

> Releases that change the micro number (x.y.z, e.g. 0.4.1) will be
**bug-fix releases**.  No new features will be introduced in these
releases; only bug fixes will be included.

The proposed backwards compatability policy reads:

> Docutils' backwards compatibility policy follows the rules for Python in
PEP 387. ... The scope of the public API is laid out at the start of the backwards
  compatibility rules

I propose two modifications to the policies, which will make future changes to Docutils easier to review and reason about, for project members as well as outside contributors. 

Firstly, I propose adopting a formal versioning "system" such as Sematic Versioning ([SemVer](https://semver.org/)) or Calendar Versioning ([CalVer](https://calver.org/)). 

Semantic versioning is nearly identical to the current versioning policy, and has the benefit of being a known quantity, reducing misunderstandings. A potential phrasing would be:

**"Docutils follows SemVer. All changes must also follow the backwards compatability policy."**

What this does change is that the API is never considered complete, as in the original phrasing. Docutils [isn't slated for inclusion](https://www.python.org/dev/peps/pep-0258/#rejection-notice) in the standard library any more, and there will always be potential improvements and changes -- new parsers, new node types, changes in the HTML specification, et cetera. 

The 1.0 release then does not need to be a "big deal", and future breaking changes can go to 2.0, 3.0, etc -- setuptools is now on `60.5.0`!

Semantic versioning does have some drawbacks (https://snarky.ca/why-i-dont-like-semver/), so projects like pip have adopted calendar based versioning -- the major version is the year (22), and the minor version is either the current month or an increasing number.  This relies on strong documentation and changelogs, so that when users upgrade it is obvious what changed (the idea being that every change breaks someone, so there is no contract that version numbers within a certain range mean no breakage). Luckily, Docutils has a good culture around changelogs and histories etc, so this would be easy to adopt.

______


I also suggest enumerating all modules, classes, and functions that form the public API. The current backwards compatability policy references PEP 387, which is specifically for the Python project itself. Checking through the documentation on every change to identify if a name is public or private is error prone (we are all human, and can miss things with no malintent) and time consuming.

At the very least I would suggest, `docutils.nodes`, the reader/writer/parser aliases, `docutils.core`,  and the front end tools. (I'm happy to write out the full list if you give me modules/etc that should be part of the public API). It would also be useful to identify what parts of Docutils large downstream consumers use, and either create higher level abstractions or mark those as public API. (I would suggest Sphinx and MyST-parser). 

It is also the [established practice](https://www.python.org/dev/peps/pep-0008/#descriptive-naming-styles) to mark names as private by prefixing them with an underscore. I suggest adopting this, as it gives strong guidance to downstream library authors what Docutils considers private and public. Making a private name public is far easier than going through a deprecation cycle for the reverse.

I'd suggest adding the ability to have exceptions to the policy, with removal after one minor version. My full suggested text is:

**"Removal or significant alteration of any members of the public API will only take place after the behaviour has been marked as deprecated for two minor releases. Certain changes may have a shorter deprecation period of one minor release. This requires at least two project members to be in favour of doing so, and no members against.**

**Changes that may affect end-users (e.g. by requiring changes to the configuration file or potentially breaking custom style sheets) should be announced with a FutureWarning."**

This post is intentionally opinionated so as to provide something to talk over / edit -- I'm not massively attached to any one thing!

A

----
for reference, amongst others, I took inspiration from:
https://setuptools.pypa.io/en/latest/development/releases.html
https://pip.pypa.io/en/latest/development/release-process/
https://numpy.org/neps/nep-0023-backwards-compatibility.html



---

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.

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

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

Thank you for the report.
I'd classify the problem as a documentation issue rather than a bug.

The problem is the difference between an *reference name* and an *identifier* .
Identifiers are derived from reference names via the [identifier normalization](https://docutils.sourceforge.io/docs/ref/rst/directives.html#identifier-normalization). Due to identifier restriction in HTML4, a reference name consisting of only digits "vanishes completely" unless prefixed. (cf. https://sourceforge.net/p/docutils/feature-requests/66/).

This is why the reference-name "5" is replaced by the auto-generated ID "footnote-1" (with 1 just be a running number to disambiguate all "footnote" IDs). A similar problem happens to, e.g. section headings consiting of just a date.
However, prefixing the ID with "user-content" allows the "1" to be appended.

You may play with the attached test script.


Attachments:

- [ids.py](https://sourceforge.net/p/docutils/bugs/_discuss/thread/8a618f0801/b4e5/attachment/ids.py) (832 Bytes; text/x-python)


---

**[bugs:#518] id_prefix removes footnote prefix from **

**Status:** open
**Created:** Sun Mar 22, 2026 12:40 AM UTC by miketheman
**Last Updated:** Sun Mar 22, 2026 12:40 AM 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:patches] #216 Fix type annotation for get_default_settings

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

Applied in [r10294]. 
Thank you for the patch.


---

**[patches:#216] Fix type annotation for get_default_settings**

**Status:** open-accepted
**Group:** None
**Created:** Thu Jan 22, 2026 09:04 AM UTC by Dmitry Shachnev
**Last Updated:** Sun Jan 25, 2026 02:15 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:patches] #216 Fix type annotation for get_default_settings

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

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

Applied in [r10294]. 
Thank you for the patch.



---

**[patches:#216] Fix type annotation for get_default_settings**

**Status:** open-accepted
**Group:** None
**Created:** Thu Jan 22, 2026 09:04 AM UTC by Dmitry Shachnev
**Last Updated:** Thu Jan 22, 2026 09:04 AM 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:patches] #216 Fix type annotation for get_default_settings

[Dmitry S. <man...@us...>]

---

**[patches:#216] Fix type annotation for get_default_settings**

**Status:** open
**Group:** None
**Created:** Thu Jan 22, 2026 09:04 AM UTC by Dmitry Shachnev
**Last Updated:** Thu Jan 22, 2026 09:04 AM 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.

Re: [Docutils-develop] Patch for .htaccess file

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

Karl has a point, that it is apache specfifc

but
for pages served by apache ... this is a betterment

all the best

On Mon, 12 Jan 2026 at 01:07, Karl O. Pinc <ko...@ka...> wrote:
>
> On Sun, 11 Jan 2026 20:53:55 -0000 (UTC)
> Guenter Milde via Docutils-develop
> <doc...@li...> wrote:
>
> > Bug report #516 by Ulrich Müller notices that the "View document
> > source" links are served with the "personal" MIME type
> > "text/prs.fallenstein.rst"
> >
> > The following patch is intended to override this with the "unoffical
> > official" unregistered MIME type "text/x-rst":
> >
> > --- .htaccess (Revision 10160)
> > +++ .htaccess (Arbeitskopie)
> > @@ -1,5 +1,12 @@
> > +# Enable directory index listings
> > +# ===============================
> >  Options Indexes
> >
> > +# MIME types
> > +# ==========
> > +# use "text/x-rst" instead of the personal/vanity entry
> > "text.prs.fallenstein.rst" +AddType text/x-rst .rst
> > +
> >  # Redirects
> >  # =========
> >
> > Would this be a good idea?
>
> I'm going to comment, even though abundently ignorant.
>
> Anything involving .htaccess is voodoo, and apache-specific
> action-at-a-distance voodoo at that.  When doing web-related
> sysadmin work I try to stay far away from .htaccess files.
>
> Please ignore this comment if you do not find it useful.
>
> Regards,
>
> Karl <ko...@ka...>
> Free Software:  "You don't pay back, you pay forward."
>                  -- Robert A. Heinlein
>
>
> _______________________________________________
> 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] Patch for .htaccess file

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

On Sun, 11 Jan 2026 20:53:55 -0000 (UTC)
Guenter Milde via Docutils-develop
<doc...@li...> wrote:

> Bug report #516 by Ulrich Müller notices that the "View document
> source" links are served with the "personal" MIME type
> "text/prs.fallenstein.rst"
> 
> The following patch is intended to override this with the "unoffical
> official" unregistered MIME type "text/x-rst":
> 
> --- .htaccess	(Revision 10160)
> +++ .htaccess	(Arbeitskopie)
> @@ -1,5 +1,12 @@
> +# Enable directory index listings
> +# ===============================
>  Options Indexes
>  
> +# MIME types
> +# ==========
> +# use "text/x-rst" instead of the personal/vanity entry
> "text.prs.fallenstein.rst" +AddType text/x-rst .rst
> +
>  # Redirects
>  # =========
>  
> Would this be a good idea?

I'm going to comment, even though abundently ignorant.

Anything involving .htaccess is voodoo, and apache-specific
action-at-a-distance voodoo at that.  When doing web-related
sysadmin work I try to stay far away from .htaccess files.

Please ignore this comment if you do not find it useful.

Regards,

Karl <ko...@ka...>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein

[Docutils-develop] Patch for .htaccess file

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

Dear Docutils developers,

Bug report #516 by Ulrich Müller notices that the "View document source"
links are served with the "personal" MIME type "text/prs.fallenstein.rst"

The following patch is intended to override this with the "unoffical
official" unregistered MIME type "text/x-rst":

--- .htaccess	(Revision 10160)
+++ .htaccess	(Arbeitskopie)
@@ -1,5 +1,12 @@
+# Enable directory index listings
+# ===============================
 Options Indexes
 
+# MIME types
+# ==========
+# use "text/x-rst" instead of the personal/vanity entry "text.prs.fallenstein.rst"
+AddType text/x-rst .rst
+
 # Redirects
 # =========
 
Would this be a good idea?

Günter

 

[Docutils-develop] [docutils:bugs] #516 FAQ says MIME type for rst is text/x-rst but its source page is served as text/prs.fallenstein.rst

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

Commit [r10290] updates the FAQ answer to document the 3rd party entry "text/prs.fallenstein.rst"


---

**[bugs:#516] FAQ says MIME type for rst is text/x-rst but its source page is served as text/prs.fallenstein.rst**

**Status:** open
**Created:** Mon Dec 15, 2025 07:26 AM UTC by Ulrich Müller
**Last Updated:** Fri Jan 09, 2026 05:40 PM UTC
**Owner:** nobody


The Docutils FAQ says in section 2.24 https://docutils.sourceforge.io/FAQ.html#what-s-the-official-mime-type-for-restructuredtext-data:

> [...] the "official unofficial" standard MIME type is "text/x-rst".

However, when following the "View document source" at the bottom of the page, I get a different MIME type:
~~~
$ curl -I https://docutils.sourceforge.io/FAQ.rst
HTTP/2 200 
date: Mon, 15 Dec 2025 07:20:49 GMT
content-type: text/prs.fallenstein.rst
[...]
~~~
Clearly, this is not what the FAQ says.



---

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] #516 FAQ says MIME type for rst is text/x-rst but its source page is served as text/prs.fallenstein.rst

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

The author/change controller  writes in the registration:
      
>   If anybody more intimately involved with ReStructuredText 
      wants to take it over, it will be surrendered gladly.

We may consider taking over as "change controller" and
   
* keep the name as ``text/prs.fallenstein.rst``
     (never touch a running system),
* change the name to ``text/prs.docutils.rst`` 
     (simple registration in the Personal Registration Tree), or
* try to register as ``text/rst``
     (official registry, requires publication of an RFC)


---

**[bugs:#516] FAQ says MIME type for rst is text/x-rst but its source page is served as text/prs.fallenstein.rst**

**Status:** open
**Created:** Mon Dec 15, 2025 07:26 AM UTC by Ulrich Müller
**Last Updated:** Mon Dec 15, 2025 10:23 AM UTC
**Owner:** nobody


The Docutils FAQ says in section 2.24 https://docutils.sourceforge.io/FAQ.html#what-s-the-official-mime-type-for-restructuredtext-data:

> [...] the "official unofficial" standard MIME type is "text/x-rst".

However, when following the "View document source" at the bottom of the page, I get a different MIME type:
~~~
$ curl -I https://docutils.sourceforge.io/FAQ.rst
HTTP/2 200 
date: Mon, 15 Dec 2025 07:20:49 GMT
content-type: text/prs.fallenstein.rst
[...]
~~~
Clearly, this is not what the FAQ says.



---

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] #517 content_offset in directives inside grid/simple tables are off

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

Line numbers are still wrong in the nested parsing of cell content in "CSV tables".
Generally, the line numbers are only intended for ease of debugging and should not be relied upon too heavily.


---

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

**Status:** open-fixed
**Created:** Sat Dec 27, 2025 05:07 PM UTC by Felix Fontein
**Last Updated:** Wed Jan 07, 2026 01:13 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] [docutils:bugs] #517 content_offset in directives inside grid/simple tables are off

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

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

The fix is out.
Sorry for the confusion: I intended to publish 2 commits with one `git svn dcommit`
but only the first came through.



---

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

**Status:** open-fixed
**Created:** Sat Dec 27, 2025 05:07 PM UTC by Felix Fontein
**Last Updated:** Tue Jan 06, 2026 08:59 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] [docutils:bugs] #517 content_offset in directives inside grid/simple tables are off

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

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



---

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

**Status:** open
**Created:** Sat Dec 27, 2025 05:07 PM UTC by Felix Fontein
**Last Updated:** Tue Jan 06, 2026 05:35 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] [docutils:bugs] #517 content_offset in directives inside grid/simple tables are off

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

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



---

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

**Status:** open-fixed
**Created:** Sat Dec 27, 2025 05:07 PM UTC by Felix Fontein
**Last Updated:** Tue Jan 06, 2026 05:35 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] [docutils:bugs] #517 content_offset in directives inside grid/simple tables are off

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

Thanks for the test script.  The attached variant was used to explore the problem and find the
spot that needs to be changed.
Commit [r10279] fixes the problem (and also wrong line numbers in some system messages for markup errors inside table cells.


Attachments:

- [directive-in-table.py](https://sourceforge.net/p/docutils/bugs/_discuss/thread/450678dd49/a008/attachment/directive-in-table.py) (3.0 kB; text/x-python)


---

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

**Status:** open
**Created:** Sat Dec 27, 2025 05:07 PM UTC by Felix Fontein
**Last Updated:** Thu Jan 01, 2026 08:42 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] [docutils:bugs] #517 content_offset in directives inside grid/simple tables are off

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

Thank you for the report.
Could you attach your test-directive, so that I can experiment and try a fix?


---

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

**Status:** open
**Created:** Sat Dec 27, 2025 05:07 PM UTC by Felix Fontein
**Last Updated:** Sat Dec 27, 2025 05:07 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] [docutils:bugs] #514 publish_file no longer works with "BytesIO-like" objects.

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

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

Fixed in Docutils 0.22.4.
Thank you for analysis and report.



---

**[bugs:#514] publish_file no longer works with "BytesIO-like" objects.**

**Status:** closed-fixed
**Created:** Sat Nov 15, 2025 05:26 PM UTC by Kristian Lehto
**Last Updated:** Mon Dec 01, 2025 11:14 PM UTC
**Owner:** nobody


Hello,

We are using code bellow to convert rst files to html.

Code works fine if we use old docutils version 0.20.1.

python -m pip install docutils==0.20.1

But current 0.22.3 version crashes.

import io
from docutils.core import publish_file

text = open('test.rst', 'rb').read()
source = io.BytesIO(text)
destination = open('test.html', 'w')
publish_file(source=source, destination=destination, writer_name='html')
destination.close()
source.close()

Traceback (most recent call last):
  File "C:\projects\test\test.py", line 7, in <module>
    publish_file(source=source, destination=destination, writer_name='html')
    ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Python314\Lib\site-packages\docutils\core.py", line 465, in publish_file
    output, _publisher = publish_programmatically(
                         ~~~~~~~~~~~~~~~~~~~~~~~~^
        source_class=io.FileInput, source=source, source_path=source_path,
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    ...<7 lines>...
        config_section=config_section,
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        enable_exit_status=enable_exit_status)
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Python314\Lib\site-packages\docutils\core.py", line 794, in publish_programmatically
    output = publisher.publish(enable_exit_status=enable_exit_status)
  File "C:\Python314\Lib\site-packages\docutils\core.py", line 269, in publish
    self.document = self.reader.read(self.source, self.parser,
                    ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
                                     self.settings)
                                     ^^^^^^^^^^^^^^
  File "C:\Python314\Lib\site-packages\docutils\readers\__init__.py", line 95, in read
    self.parse()
    ~~~~~~~~~~^^
  File "C:\Python314\Lib\site-packages\docutils\readers\__init__.py", line 101, in parse
    self.parser.parse(self.input, document)
    ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Python314\Lib\site-packages\docutils\parsers\rst\__init__.py", line 175, in parse
    inputlines = docutils.statemachine.string2lines(
          inputstring, tab_width=document.settings.tab_width,
          convert_whitespace=True)
  File "C:\Python314\Lib\site-packages\docutils\statemachine.py", line 1515, in string2lines
    astring = whitespace.sub(' ', astring)
TypeError: cannot use a string pattern on a bytes-like object


---

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

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

Hei everybody,

another quick release, docutils 0.22.4 containing

reStructuredText Specification:
  - Clarify indentation rules: minimal indentation is *one* space.
  - Clarify comment syntax: Comments begin with two dots and *whitespace*.

HTML writers:
  - New value "auto" for the initial_header_level_ setting.
  - Bugfixes in the provisional style-sheet "responsive.css".

see https://docutils.sourceforge.io/HISTORY.html for details

thanks to Günter for his work

all the best
 e

[Docutils-develop] release plan: 0.22.4 thu dec 18

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

hei

if no stopper shows up
i will release 0.22.4 tomorrow dec 18 around 7pm CET

all the best
 e