[PATCH v2] docs: sphinx-pre-install: warn about unsupported Docutils versions

[PATCH v2] docs: sphinx-pre-install: warn about unsupported Docutils versions

[Masaharu Noguchi]

Sphinx declares the range of Docutils versions it supports, but that range
does not always describe what its LaTeX builder can take: a distribution
may relax the upper bound to ship a newer Docutils, and Sphinx 9.0.x
declares support for a Docutils its LaTeX builder cannot cope with. Either
way the pair installs happily and htmldocs builds without a complaint, so
nothing looks wrong until pdfdocs is run, where four of the books fail:

  ! Dimension too large.
  \fb@put@frame ...p \ifdim \dimen@ >\ht \@tempboxa
  l.86321 \end{sphinxVerbatim}

That is arch, core-api and translations; admin-guide runs out of TeX
memory first and stops 13 pages in, and fails on the same boxes once given
more.  Each of the four includes a large literal file whole; the one in
core-api, memory-barriers.txt, is 3016 lines.  Docutils 0.22 is what puts
those blocks into sphinxVerbatim rather than sphinxalltt, and
sphinxVerbatim is framed, so they hit the size limit of
sphinx-doc/sphinx#3099 [1] -- open since 2016 and fixed only in Sphinx
9.1.0.  None of the three is at fault on its own: it takes the Docutils
version, the Sphinx version and blocks this large.

Keeping everything else fixed -- one Debian 13 container, one TeX Live, an
unmodified texmf.cnf, one kernel tree -- and varying only the two Python
packages:

  sphinx   docutils   core-api   admin-guide
  ------------------------------------------
  8.2.3    0.21.2     ok         ok
  8.2.3    0.22.4     FAILS      FAILS
  9.0.4    0.22.4     FAILS      FAILS
  9.1.0    0.22.4     ok         ok

The 9.0.4 row needs no help from a distribution: 9.0.0 through 9.0.4
declare "docutils>=0.20,<0.23" themselves, so a plain "pip install
sphinx==9.0.4" resolves Docutils to 0.22.4.  Fedora 44 reaches the same
state from the other direction, shipping Sphinx 8.2.3 -- which declares
"docutils>=0.20,<0.22" -- patched to accept "<0.23".  Upstream ships this
sort of work in a new minor rather than backporting it -- the Docutils
0.22 support went out as 9.0.0 after a backport to 8.2.x was asked for and
declined [2] -- so neither 8.2.x nor 9.0.x will grow the #3099 fix in a
point release.

Check for it, since sphinx-pre-install exists precisely to catch a
documentation build environment that will not work.  Ask the interpreter
behind sphinx-build for its Docutils version -- a venv and the system
install can differ -- and warn when Sphinx is older than 9.1.0 while
Docutils is 0.22 or newer, naming both ways out -- a newer Sphinx or an
older Docutils.  Only warn: the build is left to proceed, and htmldocs is
unaffected.  The bound Sphinx declares is no use here: it is either what
the distribution changed, or, for 9.0.x, wider than what the LaTeX builder
delivers.

[1]: https://github.com/sphinx-doc/sphinx/issues/3099
[2]: https://github.com/orgs/sphinx-doc/discussions/14055

Signed-off-by: Masaharu Noguchi <nogunix@gmail.com>
---
Verified on Debian 13 against the Sphinx/Docutils pairings listed in the
commit message: the warning fires for the ones whose pdfdocs build fails
and stays quiet for the ones that build, with the boundaries at Sphinx
9.1.0 and Docutils 0.21.2 checked explicitly.  Also checked on the
Fedora 44 host, where it fires as it should, and in a venv built from
Documentation/sphinx/requirements.txt, which resolves to Sphinx 9.1.0
and stays quiet.  make htmldocs and make pdfdocs are otherwise
untouched; the warning does not change the exit status.

This lands in the same area as Chen Miao's "docs: sphinx-pre-install:
improve dependency checks" series [1], which adds a GNU Make version
check alongside the existing Sphinx one.  It applies cleanly to mainline
today, but I am happy to rebase if that series goes in first.

[1]: https://lore.kernel.org/linux-doc/20260814214419.49925-1-chenmiao.ku@gmail.com/
---
Changes in v2:
- MIN_DOCUTILS_SPHINX is now 9.1.0 rather than 9.0.0.  The limit that
  breaks these builds is sphinx-doc/sphinx#3099, which was fixed in
  9.1.0, so v1 silently skipped the whole 9.0.x series -- which does
  fail.  Caught by Akira Yokosawa.
- Reword the warning: Sphinx 9.0.x does declare support for Docutils
  0.22, so saying it "does not support" it was wrong.  It now says what
  actually breaks, scopes the claim to this documentation's literal
  blocks rather than stating a general rule, names both ways out, and
  follows the "Warning:" wording and layout the rest of the script uses.
  The docstring now covers both routes into the pairing, not just the
  distribution one.
- Commit message: give the mechanism -- Docutils 0.22 routes large
  literal includes into sphinxVerbatim, which is framed and so subject
  to the #3099 size limit -- rather than attributing the failure to a
  single package, per Mauro Carvalho Chehab's review.
- Commit message: extend the matrix with Sphinx 9.0.0, 9.0.4 and
  Docutils 0.23, and state the fixed LaTeX configuration all rows were
  measured under, since the 9.0.x rows show the pairing arises from
  upstream metadata with no distribution involved.
- Link to v1: https://lore.kernel.org/r/20260913-docs-sphinx-pre-install-docutils-v1-1-d923c769af91@gmail.com
---
 tools/docs/sphinx-pre-install | 79 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)

diff --git a/tools/docs/sphinx-pre-install b/tools/docs/sphinx-pre-install
index 965c9b093a41..fc024556f38c 100755
--- a/tools/docs/sphinx-pre-install
+++ b/tools/docs/sphinx-pre-install
@@ -41,6 +41,17 @@ from kdoc.python_version import PythonVersion
 RECOMMENDED_VERSION = PythonVersion("3.4.3").version
 MIN_PYTHON_VERSION = PythonVersion("3.7").version
 
+# Docutils 0.22 renders large literal blocks into sphinxVerbatim rather than
+# sphinxalltt, which puts them through framed.sty.  Sphinx's size limit on
+# that path is sphinx-doc/sphinx#3099, fixed only in the 9.1.0 release:
+#     https://github.com/sphinx-doc/sphinx/issues/3099
+# Upstream ships this sort of work in a new minor rather than backporting it:
+# the Docutils 0.22 support went out as 9.0.0 after a backport to 8.2.x was
+# asked for and declined:
+#     https://github.com/orgs/sphinx-doc/discussions/14055
+MIN_DOCUTILS_SPHINX = PythonVersion("9.1.0").version
+DOCUTILS_BREAKS_AT = PythonVersion("0.22").version
+
 
 class DepManager:
     """
@@ -490,10 +501,78 @@ class MissingCheckers(AncillaryMethods):
             self.need_sphinx = 1
             return
 
+        # Check this before the version_check exit below: htmldocs invokes
+        # this script in that mode, and the warning has to reach it.
+        self.check_docutils(sphinx)
+
         # On version check mode, just assume Sphinx has all mandatory deps
         if self.version_check and self.cur_version >= RECOMMENDED_VERSION:
             sys.exit(0)
 
+    def get_docutils_version(self, cmd):
+        """
+        Get the Docutils version a sphinx-build command would use.
+
+        Docutils is a Python module rather than a program, so it has to be
+        asked of the very interpreter that runs sphinx-build: a venv and the
+        system install can hold different versions. Take it from the script's
+        shebang, falling back to the interpreter running this script.
+        """
+        python = sys.executable
+
+        try:
+            with open(cmd, "r", encoding="utf-8") as f:
+                match = re.match(r"^#!\s*(\S+)", f.readline())
+                if match:
+                    python = match.group(1)
+        except (OSError, UnicodeDecodeError):
+            pass
+
+        try:
+            result = self.run(
+                [python, "-c", "import docutils; print(docutils.__version__)"],
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+        except (OSError, subprocess.CalledProcessError):
+            return None
+
+        match = re.match(r"^\s*([0-9]+(?:\.[0-9]+)*)", result.stdout)
+        if not match:
+            return None
+
+        return PythonVersion.parse_version(match.group(1))
+
+    def check_docutils(self, sphinx):
+        """
+        Warn when Sphinx is paired with a Docutils its LaTeX builder
+        cannot take at the sizes this documentation uses.
+
+        The pair arrives either way round: a distribution may relax the
+        upper bound Sphinx declares in order to ship a newer Docutils, and
+        Sphinx 9.0.x declares support for Docutils 0.22 itself while still
+        carrying the size limit that breaks these builds. Both still build
+        HTML, so nothing looks wrong until pdfdocs is run.
+        """
+        if not self.cur_version or self.cur_version >= MIN_DOCUTILS_SPHINX:
+            return
+
+        docutils_version = self.get_docutils_version(sphinx)
+        if not docutils_version or docutils_version < DOCUTILS_BREAKS_AT:
+            return
+
+        curver = PythonVersion.ver_str(self.cur_version)
+        docver = PythonVersion.ver_str(docutils_version)
+        minver = PythonVersion.ver_str(MIN_DOCUTILS_SPHINX)
+        breakver = PythonVersion.ver_str(DOCUTILS_BREAKS_AT)
+
+        print(f"Warning: Sphinx {curver} with Docutils {docver} produces\n" \
+              "   broken LaTeX for the large literal blocks in this\n" \
+              "   documentation: pdfdocs will fail. Building them needs\n" \
+              f"   Sphinx {minver} or later, or Docutils below {breakver}.\n" \
+              "   HTML builds are unaffected.")
+
     def catcheck(self, filename):
         """
         Reads a file if it exists, returning as string.

---
base-commit: 5225b8eec4c9bb21aecff6295fab6346a3c3738e
change-id: 20260913-docs-sphinx-pre-install-docutils-7f14a21004a1

Best regards,
-- 
Masaharu Noguchi <nogunix@gmail.com>

Re: [PATCH v2] docs: sphinx-pre-install: warn about unsupported Docutils versions

[Akira Yokosawa]

Hi,

On Mon, 14 Sep 2026 19:35:40 +0900, Masaharu Noguchi wrote:
> Sphinx declares the range of Docutils versions it supports, but that range
> does not always describe what its LaTeX builder can take: a distribution
> may relax the upper bound to ship a newer Docutils, and Sphinx 9.0.x
> declares support for a Docutils its LaTeX builder cannot cope with. Either
> way the pair installs happily and htmldocs builds without a complaint, so
> nothing looks wrong until pdfdocs is run, where four of the books fail:
> 
>   ! Dimension too large.
>   \fb@put@frame ...p \ifdim \dimen@ >\ht \@tempboxa
>   l.86321 \end{sphinxVerbatim}
> 
> That is arch, core-api and translations; admin-guide runs out of TeX
> memory first and stops 13 pages in, and fails on the same boxes once given
> more.  Each of the four includes a large literal file whole; the one in
> core-api, memory-barriers.txt, is 3016 lines.  Docutils 0.22 is what puts
> those blocks into sphinxVerbatim rather than sphinxalltt, and
> sphinxVerbatim is framed, so they hit the size limit of
> sphinx-doc/sphinx#3099 [1] -- open since 2016 and fixed only in Sphinx
> 9.1.0.  None of the three is at fault on its own: it takes the Docutils
> version, the Sphinx version and blocks this large.
> 
> Keeping everything else fixed -- one Debian 13 container, one TeX Live, an
> unmodified texmf.cnf, one kernel tree -- and varying only the two Python
> packages:
> 
>   sphinx   docutils   core-api   admin-guide
>   ------------------------------------------
>   8.2.3    0.21.2     ok         ok
>   8.2.3    0.22.4     FAILS      FAILS
>   9.0.4    0.22.4     FAILS      FAILS
>   9.1.0    0.22.4     ok         ok
> 
> The 9.0.4 row needs no help from a distribution: 9.0.0 through 9.0.4
> declare "docutils>=0.20,<0.23" themselves, so a plain "pip install
> sphinx==9.0.4" resolves Docutils to 0.22.4.  Fedora 44 reaches the same
> state from the other direction, shipping Sphinx 8.2.3 -- which declares
> "docutils>=0.20,<0.22" -- patched to accept "<0.23".  Upstream ships this
> sort of work in a new minor rather than backporting it -- the Docutils
> 0.22 support went out as 9.0.0 after a backport to 8.2.x was asked for and
> declined [2] -- so neither 8.2.x nor 9.0.x will grow the #3099 fix in a
> point release.
> 
> Check for it, since sphinx-pre-install exists precisely to catch a
> documentation build environment that will not work.  Ask the interpreter
> behind sphinx-build for its Docutils version -- a venv and the system
> install can differ -- and warn when Sphinx is older than 9.1.0 while
> Docutils is 0.22 or newer, naming both ways out -- a newer Sphinx or an
> older Docutils.  Only warn: the build is left to proceed, and htmldocs is
> unaffected.  The bound Sphinx declares is no use here: it is either what
> the distribution changed, or, for 9.0.x, wider than what the LaTeX builder
> delivers.
> 

As this is expected to be resolved in Fedora 45, I didn't see much
point in adding this warning.  I now see Ubuntu 24.04 LTS has the
problematic pair of Sphinx and docutils ...  So it might be worth
to have. 

That said, with your approach, under a build env with a problematic
pair, this is what you'd see in "make htmldocs":

$ make htmldocs
Warning: Sphinx 8.2.3 with Docutils 0.22.4 produces
   broken LaTeX for the large literal blocks in this
   documentation: pdfdocs will fail. Building them needs
   Sphinx 9.1.0 or later, or Docutils below 0.22.
   HTML builds are unaffected.
[...]

I think this can annoy people who only care HTML docs.

Why not do this check after the PDF doc builds have actually failed.

That is what sphinx-build-wrapper is doing with LatexFontChecker().check()
(see line 557 of tools/docs/sphinx-build-wrapper), which is to
show the way to work around PDF build errors caused by "variable font"
flavor of Noto CJK fonts [3].  (Fedora and openSUSE have started to
deploy such fonts in 2024.)

[3]: https://bugzilla.redhat.com/show_bug.cgi?id=2271559

Regards, Akira

> [1]: https://github.com/sphinx-doc/sphinx/issues/3099
> [2]: https://github.com/orgs/sphinx-doc/discussions/14055
> 
> Signed-off-by: Masaharu Noguchi <nogunix@gmail.com>
> ---

[...]

Re: [PATCH v2] docs: sphinx-pre-install: warn about unsupported Docutils versions

[Akira Yokosawa]

Ouch, obvious typo ...

[...]
> 
> As this is expected to be resolved in Fedora 45, I didn't see much
> point in adding this warning.  I now see Ubuntu 24.04 LTS has the

                                           Ubuntu 26.04 LTS
					   
> problematic pair of Sphinx and docutils ...  So it might be worth
> to have. 

Thanks, Akira

Re: [PATCH v2] docs: sphinx-pre-install: warn about unsupported Docutils versions

[Mauro Carvalho Chehab]

On Tue, 15 Sep 2026 16:52:03 +0900
Akira Yokosawa <akiyks@gmail.com> wrote:

> Hi,
> 
> On Mon, 14 Sep 2026 19:35:40 +0900, Masaharu Noguchi wrote:
> > Sphinx declares the range of Docutils versions it supports, but that range
> > does not always describe what its LaTeX builder can take: a distribution
> > may relax the upper bound to ship a newer Docutils, and Sphinx 9.0.x
> > declares support for a Docutils its LaTeX builder cannot cope with. Either
> > way the pair installs happily and htmldocs builds without a complaint, so
> > nothing looks wrong until pdfdocs is run, where four of the books fail:
> > 
> >   ! Dimension too large.
> >   \fb@put@frame ...p \ifdim \dimen@ >\ht \@tempboxa
> >   l.86321 \end{sphinxVerbatim}
> > 
> > That is arch, core-api and translations; admin-guide runs out of TeX
> > memory first and stops 13 pages in, and fails on the same boxes once given
> > more.  Each of the four includes a large literal file whole; the one in
> > core-api, memory-barriers.txt, is 3016 lines.  Docutils 0.22 is what puts
> > those blocks into sphinxVerbatim rather than sphinxalltt, and
> > sphinxVerbatim is framed, so they hit the size limit of
> > sphinx-doc/sphinx#3099 [1] -- open since 2016 and fixed only in Sphinx
> > 9.1.0.  None of the three is at fault on its own: it takes the Docutils
> > version, the Sphinx version and blocks this large.
> > 
> > Keeping everything else fixed -- one Debian 13 container, one TeX Live, an
> > unmodified texmf.cnf, one kernel tree -- and varying only the two Python
> > packages:
> > 
> >   sphinx   docutils   core-api   admin-guide
> >   ------------------------------------------
> >   8.2.3    0.21.2     ok         ok
> >   8.2.3    0.22.4     FAILS      FAILS
> >   9.0.4    0.22.4     FAILS      FAILS
> >   9.1.0    0.22.4     ok         ok
> > 
> > The 9.0.4 row needs no help from a distribution: 9.0.0 through 9.0.4
> > declare "docutils>=0.20,<0.23" themselves, so a plain "pip install
> > sphinx==9.0.4" resolves Docutils to 0.22.4.  Fedora 44 reaches the same
> > state from the other direction, shipping Sphinx 8.2.3 -- which declares  
> > "docutils>=0.20,<0.22" -- patched to accept "<0.23".  Upstream ships this  
> > sort of work in a new minor rather than backporting it -- the Docutils
> > 0.22 support went out as 9.0.0 after a backport to 8.2.x was asked for and
> > declined [2] -- so neither 8.2.x nor 9.0.x will grow the #3099 fix in a
> > point release.
> > 
> > Check for it, since sphinx-pre-install exists precisely to catch a
> > documentation build environment that will not work.  Ask the interpreter
> > behind sphinx-build for its Docutils version -- a venv and the system
> > install can differ -- and warn when Sphinx is older than 9.1.0 while
> > Docutils is 0.22 or newer, naming both ways out -- a newer Sphinx or an
> > older Docutils.  Only warn: the build is left to proceed, and htmldocs is
> > unaffected.  The bound Sphinx declares is no use here: it is either what
> > the distribution changed, or, for 9.0.x, wider than what the LaTeX builder
> > delivers.
> >   
> 
> As this is expected to be resolved in Fedora 45, I didn't see much
> point in adding this warning.  I now see Ubuntu 24.04 LTS has the
> problematic pair of Sphinx and docutils ...  So it might be worth
> to have. 

Fedora 44 EOL is still in at least 7 months from now (e.g. when Fedora
46 will be launched), so, it could still be worth.

> That said, with your approach, under a build env with a problematic
> pair, this is what you'd see in "make htmldocs":
> 
> $ make htmldocs
> Warning: Sphinx 8.2.3 with Docutils 0.22.4 produces
>    broken LaTeX for the large literal blocks in this
>    documentation: pdfdocs will fail. Building them needs
>    Sphinx 9.1.0 or later, or Docutils below 0.22.
>    HTML builds are unaffected.
> [...]
> 
> I think this can annoy people who only care HTML docs.
> 
> Why not do this check after the PDF doc builds have actually failed.

Indeed it sounds a better approach on my eyes.

---

On a separate but related issue, has anyone tried to use rst2pdf
lately (https://github.com/rst2pdf/rst2pdf)?

It could be helpful to use an approach that won't require writing
first a LaTeX file. I remember I implemented some support for it
a long time ago. The patch back them is still on an old branch
here:

	https://git.linuxtv.org/mchehab/experimental.git/log/?h=rst2pdf-v3

If someone has the time, it could be worth trying to port it for
it to work with sphinx-build-wrapper and do some tests to check
if it is worth the efforts to fix existing bugs at the tool, if
any.

> 
> That is what sphinx-build-wrapper is doing with LatexFontChecker().check()
> (see line 557 of tools/docs/sphinx-build-wrapper), which is to
> show the way to work around PDF build errors caused by "variable font"
> flavor of Noto CJK fonts [3].  (Fedora and openSUSE have started to
> deploy such fonts in 2024.)
> 
> [3]: https://bugzilla.redhat.com/show_bug.cgi?id=2271559
> 
> Regards, Akira
> 
> > [1]: https://github.com/sphinx-doc/sphinx/issues/3099
> > [2]: https://github.com/orgs/sphinx-doc/discussions/14055
> > 
> > Signed-off-by: Masaharu Noguchi <nogunix@gmail.com>
> > ---  
> 
> [...]



Thanks,
Mauro

Re: [PATCH v2] docs: sphinx-pre-install: warn about unsupported Docutils versions

[Masaharu Noguchi]

Hi Akira,

On Tue, 15 Sep 2026 16:52:03 +0900, Akira Yokosawa wrote:
> I think this can annoy people who only care HTML docs.
>
> Why not do this check after the PDF doc builds have actually failed.
>
> That is what sphinx-build-wrapper is doing with LatexFontChecker().check()
> (see line 557 of tools/docs/sphinx-build-wrapper)

You are right, and that is a better place for it.  v3 follows it: the
check moves into tools/lib/python/kdoc/docutils_version.py, shaped like
latex_fonts.py, and sphinx-build-wrapper calls it from the same two
build_failed branches, next to LatexFontChecker.  sphinx-pre-install is
left untouched.

Measured on a broken pair: htmldocs now prints nothing new and still
exits 0, and the message appears only when pdfdocs has actually failed,
just above the error.  A working pair stays quiet in both.

Thank you for pointing at Ubuntu 26.04 LTS; that turned out to be the
strongest case for having this at all, so I checked it.  It has Sphinx
8.2.3 with Docutils 0.22.4, and its python3-sphinx depends on
"python3-docutils (>= 0.20)" with no upper bound at all, where Fedora 44
arrives at the same pair by patching the "<0.22" that Sphinx declares.
Both fail the same way here:

	              core-api            admin-guide
	---------------------------------------------------------
	Ubuntu 26.04  FAILS 26x Dim       FAILS capacity, 13 p
	Fedora 44     FAILS 26x Dim       FAILS capacity, 13 p

An LTS makes this a good deal less transient than Fedora 44 alone.

v3 follows shortly.

Thanks,
Masaharu

Re: [PATCH v2] docs: sphinx-pre-install: warn about unsupported Docutils versions

[Masaharu Noguchi]

Hi Mauro,

On Tue, 15 Sep 2026 10:16:38 +0200, Mauro Carvalho Chehab wrote:
> Fedora 44 EOL is still in at least 7 months from now (e.g. when Fedora
> 46 will be launched), so, it could still be worth.

Thank you.  And it is not only Fedora: Akira pointed at Ubuntu 26.04 LTS,
which holds up -- it ships Sphinx 8.2.3 with Docutils 0.22.4, and its
python3-sphinx depends on "python3-docutils (>= 0.20)" with no upper bound
at all.  Both fail identically here, and an LTS carries this a good deal
further than seven months.

> Indeed it sounds a better approach on my eyes.

Taken -- v3 moves the check into tools/lib/python/kdoc/docutils_version.py
and calls it from sphinx-build-wrapper next to LatexFontChecker, only
once a PDF build has failed.  sphinx-pre-install is left untouched, which
also drops the overlap with Chen Miao's series.

> On a separate but related issue, has anyone tried to use rst2pdf
> lately (https://github.com/rst2pdf/rst2pdf)?

I have not tried it myself, but not having to go through LaTeX at all is
an appealing idea.  I would like to look at porting your branch once this
one has settled.

Thanks,
Masaharu

Re: rst2pdf (was [PATCH v2] docs: sphinx-pre-install: warn about unsupported Docutils versions)

[Jonathan Corbet]

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> On a separate but related issue, has anyone tried to use rst2pdf
> lately (https://github.com/rst2pdf/rst2pdf)?

I have a branch sitting around that, on occasion, I dust off to see how
it works; every time, rst2pdf crashes and burns.  I've long wanted to
find some time to figure out what's going on and try to fix it but
... well, we know that story by now ...

It would be *wonderful* if we could us it and short the LaTeX toolchain
out entirely.

jon

Re: rst2pdf (was [PATCH v2] docs: sphinx-pre-install: warn about unsupported Docutils versions)

[Mauro Carvalho Chehab]

On Tue, 15 Sep 2026 08:35:11 -0600
Jonathan Corbet <corbet@lwn.net> wrote:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > On a separate but related issue, has anyone tried to use rst2pdf
> > lately (https://github.com/rst2pdf/rst2pdf)?  
> 
> I have a branch sitting around that, on occasion, I dust off to see how
> it works; every time, rst2pdf crashes and burns.  I've long wanted to
> find some time to figure out what's going on and try to fix it but
> ... well, we know that story by now ...
> 
> It would be *wonderful* if we could us it and short the LaTeX toolchain
> out entirely.

If someone has spare tokens, perhaps detecting the issues could be
delegated to some LLM agent that would try to address them, generating
enough feedback to have something to submit back to rst2pdf maintainers.

As this is basically a transformation problem (from rst vocabulary to pdf
vocabulary), I suspect it won't take much LLM time to discover the main 
issues. Perhaps even small model like ornith-1.5-9B could be enough to
deal with it.


Thanks,
Mauro