Re: [PATCH 00/11] Fix PDF doc builds on major distros

[Akira Yokosawa <akiyks@gmail.com>]

[-CC most folks]

Hi Mauro,

On Fri, 15 Aug 2025 13:36:16 +0200, Mauro Carvalho Chehab wrote:
> Hi Jon,
> 
> This series touch only on three files, and have a small diffstat:
> 
>    Documentation/Makefile     |    4 -
>    Documentation/conf.py      |  106 +++++++++++++++++++++----------------
>    scripts/sphinx-pre-install |   41 +++++++++++---
>    3 files changed, 96 insertions(+), 55 deletions(-)
> 
> Yet, it took a lot of my time.  Basically, it addresses lots of problems  related
> with building PDF docs:
> 
> - Makefile has a wrong set of definitions for paper size. It was
>   using pre-1.7 Sphinx nomenclature for some conf vars;
> - The LaTeX options a conf.py had lots of issues;
> - Finally, some PDF package dependencies for distros were wrong.
> 
> I wrote an entire testbench to test this and doing builds on every
> platform mentioned at sphinx-pre-install. 
> 
> After the change *most* PDF files are built on *most* platforms. 
> 
> 
> Summary
> =======
>   PASSED - AlmaLinux release 9.6 (Sage Margay) (7 tests)
>   PASSED - Amazon Linux release 2023 (Amazon Linux) (7 tests)
>   FAILED - archlinux (1 tests)
>   PASSED - CentOS Stream release 9 (7 tests)
>   PARTIAL - Debian GNU/Linux 12 (7 tests)
>   PARTIAL - Devuan GNU/Linux 5 (7 tests)
>   PASSED - Fedora release 42 (Adams) (7 tests)
>   PARTIAL - Gentoo Base System release 2.17 (7 tests)
>   PASSED - Kali GNU/Linux 2025.2 (7 tests)
>   PASSED - Mageia 9 (7 tests)
>   PARTIAL - Linux Mint 22 (7 tests)
>   PARTIAL - openEuler release 25.03 (7 tests)
>   PARTIAL - OpenMandriva Lx 4.3 (7 tests)
>   PASSED - openSUSE Leap 15.6 (7 tests)
>   PASSED - openSUSE Tumbleweed (7 tests)
>   PARTIAL - Oracle Linux Server release 9.6 (7 tests)
>   FAILED - Red Hat Enterprise Linux release 8.10 (Ootpa) (7 tests)
>   PARTIAL - Rocky Linux release 8.9 (Green Obsidian) (7 tests)
>   PARTIAL - Rocky Linux release 9.6 (Blue Onyx) (7 tests)
>   FAILED - Springdale Open Enterprise Linux release 9.2 (Parma) (7 tests)
>   PARTIAL - Ubuntu 24.04.2 LTS (7 tests)
>   PASSED - Ubuntu 25.04 (7 tests)
> 
> The failed distros are:
> 
> - archlinux. This is some problem on recent lxc containers. Unrelated
>   with pdf builds;
> - RHEL 8: paywall issue: some packages required by Sphinx require a repository
>   that it is not openly available. I might have using CentOS repos, but, as we're
>   already testing it, I opted not do do it;
> - Springdale 9.2: some broken package dependency.
> 
> Now, if you look at the full logs below, you'll see that some distros come with
> XeLaTeX or LaTeX troubles, causing bigger and/or more complex docs to
> fail. It is possible to fix those, but they depend on addressing distro-specific
> LaTeX issues like increasing maximum memory limits and maximum number
> of idented paragraphs.

No, the trouble is failed conversion of SVG --> PDF by convert(1) + rsvg-convert(1).
Failed conversions trigger huge raw SVG code to be included literally into LaTeX
sources, which results in code listings too huge to be rendered in a page; and
overwhelms xelatex.

IIUC, kfigure.py does such fallbacks of failed PDF conversions.  Mightn't it be
better to give up early in the latexdocs stage?

> It follows full results per distro.

[Ignoring lengthy list of results...]

I think all you need to test build against are the limited list of:

    - arch.pdf
    - core-api.pdf
    - doc-guide.pdf
    - gpu.pdf
    - i2c.pdf
    - RCU.pdf
    - translations.pdf
    - userspace-api.pdf

All of them have figures in SVG, and latexdocs tries to convert them
into PDF.

Probably, recommending Inkscape rather than ImageMagick would be the right
thing, at least where it is provided as a distro package.

Regards,
Akira