Fix PDF doc builds on major distros

Hi Jon,

Here it is the second version of the PDF series. I opted to split one of the patches in 3, to have a clearer changelog and description.

Also, archlinux LXC image download started working again, so I added an extra patch addressing texlive packae dependencies.

This series is taking me a way more time than antecipated.

This series as 3 goals:

1. Fix a pre-Sphinx 1.7 PDF variable that got renamed, but our Makefile still uses the old one that is not supported since Sphinx 1.7;

2. Fix broken or incomplete texlive dependencies on several distros;

4. "modernize" conf.py to solve font conflicts related to UTF-8 and non-UTF fonts from [T1]{fontenc} LaTeX package.

Using fontenc with xelatex is problematic, as documented at

https://www.sphinx-doc.org/en/master/latex.html

Please notice that:

- It doesn't pretend to fix all PDF issues. It focus only at the above;
- there are still distros where PDF builds fail either partially or as a hole. On my checks, those are due to problematic texlive packages shipped on such distros;
- it doesn't touch/address/alter anyhing related to kfigure.py. as such, it doesn't touch/change/improve/drop anything with regards ImageMagick and/or Inkscape.

I think we need a separate series addressing kfigure.py:
it currently breaks if either input or output has a char > 127, meaning that PDF output there may eventually break.

---
v2:
- one of the conf.py packages were split to help reviewers

    to check the actual changes;

- added an extra sphinx-pre-install patch for ArchLinux.

Mauro Carvalho Chehab (14):
docs: Makefile: Fix LaTeX paper size settings
docs: conf.py: better handle latex documents
docs: conf.py: fix doc name with SPHINXDIRS
docs: conf.py: rename some vars at latex_documents logic
docs: conf.py: use dedent and r-strings for LaTeX macros
docs: conf.py: fix some troubles for LaTeX output
docs: conf.py: extra cleanups and fixes
scripts: sphinx-pre-install: fix PDF build issues on Ubuntu
scripts: sphinx-pre-install: add missing gentoo pdf dependencies
scripts: sphinx-pre-install: fix PDF dependencies for openSuse
scripts: sphinx-pre-install: fix dependencies for OpenMandriva
scripts: sphinx-pre-install: fix pdf dependencies for Mageia 9
scripts: sphinx-pre-install: fix PDF dependencies for gentoo scripts/sphinx-pre-install: fix Archlinux PDF dependencies

 Documentation/Makefile     |   4 +-
 Documentation/conf.py      | 106 ++++++++++++++++++++++---------------
 scripts/sphinx-pre-install |  46 ++++++++++++----
 3 files changed, 101 insertions(+), 55 deletions(-)

2.50.1

According with:
https://www.sphinx-doc.org/en/master/latex.html

The variable that handles paper size changed during version 1.5, as pointed at:

	https://www.sphinx-doc.org/en/master/changes/1.5.html

---
 Documentation/Makefile | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

index 820f07e0afe6..2ed334971acd 100644
@@ -60,8 +60,8 @@ ifeq ($(HAVE_LATEXMK),1)
 endif #HAVE_LATEXMK
 
 # Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
+PAPEROPT_a4     = -D latex_elements.papersize=a4paper
+PAPEROPT_letter = -D latex_elements.papersize=letterpaper
 ALLSPHINXOPTS   = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
 ALLSPHINXOPTS   += $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
 ifneq ($(wildcard $(srctree)/.config),)

2.50.1

The original logic assumed that app.srcdir is identical to the current working dir. This is the case for a normal build, but, when SPHINXDIRS="some dir" is used, this is not the case anymore.

Adjust the logic to fill the LaTeX documents considering app.srcdir, in a way that it will work properly on all cases.

---
 Documentation/conf.py | 54 +++++++++++++++++++++----------------------
 1 file changed, 26 insertions(+), 28 deletions(-)

index f9828f3862f9..2c1be59fd54b 100644
@@ -51,11 +51,13 @@ else:
     dyn_exclude_patterns.append("devicetree/bindings/**.yaml")
     dyn_exclude_patterns.append("core-api/kho/bindings/**.yaml")
 
-# Properly handle include/exclude patterns
-# ----------------------------------------
+# Properly handle directory patterns and LaTeX docs
+# -------------------------------------------------
 
-def update_patterns(app, config):
+def config_init(app, config):
     """
+    Initialize path-dependent variabled
+
     On Sphinx, all directories are relative to what it is passed as
     SOURCEDIR parameter for sphinx-build. Due to that, all patterns
     that have directory names on it need to be dynamically set, after

@@ -86,6 +88,25 @@ def update_patterns(app, config):
 
         config.exclude_patterns.append(rel_path)
 
+    # LaTeX and PDF output require a list of documents with are dependent
+    # of the app.srcdir. Add them here
+
+    for fn in os.listdir(app.srcdir):
+        doc = os.path.join(fn, "index")
+        if not os.path.exists(os.path.join(app.srcdir, doc + ".rst")):
+            continue
+
+        has = False
+        for l in latex_documents:
+            if l[0] == doc:
+                has = True
+                break
+
+        if not has:
+            latex_documents.append((doc, fn + ".tex",
+                                    "Linux %s Documentation" % fn.capitalize(),
+                                    "The kernel development community",
+                                    "manual"))
 
 # helper
 # ------

@@ -456,32 +477,9 @@ latex_elements["preamble"] += """
         \\input{kerneldoc-preamble.sty}
 """
 
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-# Sorted in alphabetical order
+# This will be filled up by config-inited event
 latex_documents = []
 
-# Add all other index files from Documentation/ subdirectories
-for fn in os.listdir("."):
-    doc = os.path.join(fn, "index")
-    if os.path.exists(doc + ".rst"):
-        has = False
-        for l in latex_documents:
-            if l[0] == doc:
-                has = True
-                break
-        if not has:
-            latex_documents.append(
-                (
-                    doc,
-                    fn + ".tex",
-                    "Linux %s Documentation" % fn.capitalize(),
-                    "The kernel development community",
-                    "manual",
-                )
-            )
-
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
 # latex_logo = None

@@ -577,4 +575,4 @@ loadConfig(globals())
 def setup(app):
     """Patterns need to be updated at init time on older Sphinx versions"""
 
-    app.connect('config-inited', update_patterns)
+    app.connect('config-inited', config_init)

2.50.1

When SPHINXDIRS is used, the current logic produces a wrong list of files, as it will not pick the SPHINXDIRS directory, picking instead their children.

Add a rule to detect it and create the PDF doc with the right name.

---
 Documentation/conf.py | 13 +++++++++++++
 1 file changed, 13 insertions(+)

index 2c1be59fd54b..c8401ed75402 100644
@@ -91,6 +91,19 @@ def config_init(app, config):
     # LaTeX and PDF output require a list of documents with are dependent
     # of the app.srcdir. Add them here
 
+    # When SPHINXDIRS is used, we just need to get index.rst, if it exists
+    if not os.path.samefile(doctree, app.srcdir):
+        doc = "index"
+        doc_name = os.path.basename(app.srcdir)
+        if os.path.exists(os.path.join(app.srcdir, doc + ".rst")):
+            latex_documents.append((doc, doc_name + ".tex",
+                                    "Linux %s Documentation" % doc_name.capitalize(),
+                                    "The kernel development community",
+                                    "manual"))
+            return
+
+    # When building all docs, or when a main index.rst doesn't exist, seek
+    # for it on subdirectories
     for fn in os.listdir(app.srcdir):
         doc = os.path.join(fn, "index")
         if not os.path.exists(os.path.join(app.srcdir, doc + ".rst")):

2.50.1

Currently, the logic uses fn and doc vars, but they don't properly describe what such vars do.

Make them clearer:
- fname: points to the file name to search (index.rst);
- doc: contains the name of the LaTeX or PDF doc to be produced.

With that, the checks for SPHINXDIRS and for subdirs will be more coherent.

---
 Documentation/conf.py | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

index c8401ed75402..6e12c7d8e07e 100644
@@ -93,31 +93,31 @@ def config_init(app, config):
 
     # When SPHINXDIRS is used, we just need to get index.rst, if it exists
     if not os.path.samefile(doctree, app.srcdir):
-        doc = "index"
-        doc_name = os.path.basename(app.srcdir)
-        if os.path.exists(os.path.join(app.srcdir, doc + ".rst")):
-            latex_documents.append((doc, doc_name + ".tex",
-                                    "Linux %s Documentation" % doc_name.capitalize(),
+        doc = os.path.basename(app.srcdir)
+        fname = "index"
+        if os.path.exists(os.path.join(app.srcdir, fname + ".rst")):
+            latex_documents.append((fname, doc + ".tex",
+                                    "Linux %s Documentation" % doc.capitalize(),
                                     "The kernel development community",
                                     "manual"))
             return
 
     # When building all docs, or when a main index.rst doesn't exist, seek
     # for it on subdirectories
-    for fn in os.listdir(app.srcdir):
-        doc = os.path.join(fn, "index")
-        if not os.path.exists(os.path.join(app.srcdir, doc + ".rst")):
+    for doc in os.listdir(app.srcdir):
+        fname = os.path.join(doc, "index")
+        if not os.path.exists(os.path.join(app.srcdir, fname + ".rst")):
             continue
 
         has = False
         for l in latex_documents:
-            if l[0] == doc:
+            if l[0] == fname:
                 has = True
                 break
 
         if not has:
-            latex_documents.append((doc, fn + ".tex",
-                                    "Linux %s Documentation" % fn.capitalize(),
+            latex_documents.append((fname, doc + ".tex",
+                                    "Linux %s Documentation" % doc.capitalize(),
                                     "The kernel development community",
                                     "manual"))
 

2.50.1

Instead of adding extra weird indentation at the tex file, use dedent(). While here, also use r-strings, to make easier to make its content identical to the .tex output.

While here, also merge "preamble" that was added on two separate parts of the code (in the past, there were some version-specific checks).

No functional changes, just cosmetic ones.

---
 Documentation/conf.py | 26 ++++++++++++--------------
 1 file changed, 12 insertions(+), 14 deletions(-)

index 6e12c7d8e07e..628af81e6879 100644
@@ -9,6 +9,8 @@ import os
 import shutil
 import sys
 
+from  textwrap import dedent
+
 import sphinx
 
 # If extensions (or modules to document with autodoc) are in another directory,

@@ -462,11 +464,11 @@ latex_elements = {
     "inputenc": "",
     "utf8extra": "",
     # Set document margins
-    "sphinxsetup": """
+    "sphinxsetup": dedent(r"""
         hmargin=0.5in, vmargin=1in,
         parsedliteralwraps=true,
         verbatimhintsturnover=false,
-    """,
+    """),
     #
     # Some of our authors are fond of deep nesting; tell latex to
     # cope.

@@ -475,20 +477,16 @@ latex_elements = {
     # For CJK One-half spacing, need to be in front of hyperref
     "extrapackages": r"\usepackage{setspace}",
     # Additional stuff for the LaTeX preamble.
-    "preamble": """
+    "preamble": dedent(r"""
         % Use some font with UTF-8 support with XeLaTeX
-        \\usepackage{fontspec}
-        \\setsansfont{DejaVu Sans}
-        \\setromanfont{DejaVu Serif}
-        \\setmonofont{DejaVu Sans Mono}
-    """,
-}
-
-# Load kerneldoc specific LaTeX settings
-latex_elements["preamble"] += """
+        \usepackage{fontspec}
+        \setsansfont{DejaVu Sans}
+        \setromanfont{DejaVu Serif}
+        \setmonofont{DejaVu Sans Mono}
         % Load kerneldoc specific LaTeX settings
-        \\input{kerneldoc-preamble.sty}
-"""
+        \input{kerneldoc-preamble.sty}
+    """)
+}
 
 # This will be filled up by config-inited event
 latex_documents = []

2.50.1

While PDF docs work fine on RPM-based distros, it causes conflicts on Debian & friends.

There are multiple root causes here:

- the latex_elements still resambles the one from Sphinx 1.x times, where font configurations were stored under "preamble". It doesn't follow the current recommended way from Sphinx documentation:

https://www.sphinx-doc.org/en/master/latex.html

- instead of setting the main font, from where other fonts are derivated, it sets romanfont;

- "fontenc" is not set. This allows the *.tex output file to contain an UTF-8 incompatible fontset:

	\usepackage[T1]{fontenc}

Address such issues to help preventing incompatible usage of both T1 font and UTF-8 ones that comes from DejaVu font family.

On some distros, this even generate a LaTeX font warning about corrupted NFSS tables like this (I got it when running it in interactive mode):

Package: fontenc 2021/04/29 v2.0v Standard LaTeX package
LaTeX Font Info: Trying to load font information for T1+lmr on input line 11
6.
LaTeX Font Info: No file T1lmr.fd. on input line 116.

LaTeX Font Warning: Font shape `T1/lmr/m/n' undefined
(Font) using `T1/lmr/m/n' instead on input line 116.

! Corrupted NFSS tables.
wrong@fontshape ...message {Corrupted NFSS tables}
error@fontshape else let f...
l.116 ...\familydefault\seriesdefault\shapedefault

---
 Documentation/conf.py | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

index 628af81e6879..5888e2988b4f 100644
@@ -461,6 +461,7 @@ latex_elements = {
     # Latex figure (float) alignment
     # 'figure_align': 'htbp',
     # Don't mangle with UTF-8 chars
+    "fontenc": "",
     "inputenc": "",
     "utf8extra": "",
     # Set document margins

@@ -476,13 +477,14 @@ latex_elements = {
     "maxlistdepth": "10",
     # For CJK One-half spacing, need to be in front of hyperref
     "extrapackages": r"\usepackage{setspace}",
-    # Additional stuff for the LaTeX preamble.
-    "preamble": dedent(r"""
-        % Use some font with UTF-8 support with XeLaTeX
+    "fontpkg": dedent(r"""
         \usepackage{fontspec}
+        \setmainfont{DejaVu Serif}
         \setsansfont{DejaVu Sans}
-        \setromanfont{DejaVu Serif}
         \setmonofont{DejaVu Sans Mono}
+        \newfontfamily\headingfont{DejaVu Serif}
+    """),
+    "preamble": dedent(r"""
         % Load kerneldoc specific LaTeX settings
         \input{kerneldoc-preamble.sty}
     """)

2.50.1

Makes it more adehent with modern Sphinx LaTeX build setup as defined at:

https://www.sphinx-doc.org/en/master/latex.html

There, it suggests:

1) to add: 'printindex'

“printindex” call, the last thing in the file. Override if you want to generate the index differently, append some content after the index, or change the font. As LaTeX uses two-column mode for the index it is often advisable to set this key to r'\footnotesize\raggedright\printindex'.

This indeed solved a corner case on a distro where the index was not properly generated.

2) to add at the main example:

         \PassOptionsToPackage{svgnames}{xcolor}

3) I got a corner case on one of the distros was using xindy to produce indexes. This ended causing the build logic to incorretly try to use T1 fontenc, which is not UTF-8 compatible.

This patch adds:

        \PassOptionsToPackage{xindy}{language=english,codepage=utf8,noautomatic}

to cover such case. It should be noticed that, as the config doesn't have \usepackage{xindy}, this will be used only if latexmk ends using xindy.

---
 Documentation/conf.py | 7 +++++++
 1 file changed, 7 insertions(+)

index 5888e2988b4f..1c4695727208 100644
@@ -456,8 +456,15 @@ htmlhelp_basename = "TheLinuxKerneldoc"
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     "papersize": "a4paper",
+    "passoptionstopackages": dedent(r"""
+        \PassOptionsToPackage{svgnames}{xcolor}
+        % Avoid encoding troubles when creating indexes
+        \PassOptionsToPackage{xindy}{language=english,codepage=utf8,noautomatic}
+    """),
     # The font size ('10pt', '11pt' or '12pt').
     "pointsize": "11pt",
+    # Needed to generate a .ind file
+    "printindex": r"\footnotesize\raggedright\printindex",
     # Latex figure (float) alignment
     # 'figure_align': 'htbp',
     # Don't mangle with UTF-8 chars

2.50.1

Hi Mauro,

I see this has already been merged, but let me comment after the fact.

This looks good.

OK. So I guess Sphinx's latex builder is going to start using SVG color naming in the near future.

But I can't see how this macro (executed by XeTeX engine) would have any effect on xindy (command) invoked from latexmk.

Can you elaborate on your theory of how it works?
And which distro runs xindy?

Thanks,
Akira

I can't remember on what distro I saw the issue, but I got it during my builds, where, instead of running makeindex, it tried to run xindy, with failed because of utf-8 fonts.

My theory is that, on one of the ditros, there is a /etc/latexmk or similar containing instructions to use xindy instead of makeindex.

In any case, this rule is harmless on setups that use makeindex:
it only affect setups where there is a latexmk or .latexmk file setting xindy as the default index builder: if this is used, xindy will use utf-8 fonts instead of Type 1.

Thanks,
Mauro

Can we try to get a handle on that and, if it's truly needed, document why? I will confess that I'm confused by it:

As I understand it, the arguments are {options}{package}, right? so I'm not sure how this would work...?

Thanks,

jon (who will be traveling and slow to respond for a bit)

Em Fri, 22 Aug 2025 16:34:38 -0600
Jonathan Corbet <[email protected]> escreveu:

Heh, you're right: the argument is reversed. Also, I repeated the tests here, and were unable to reproduce the issue I had with xindy.

So, let's just drop it. If we needed, we can re-add, reverting the parameter order there. Patch is at:

	https://lore.kernel.org/linux-doc/83068bc31839e7095f1f408e49658362d467797e.1756123459.git.mchehab+huawei@kernel.org/T/#u

Thanks,
Mauro

Just to get the credit where it is due, it's Akira who first pointed this out.

OK I'll get there.

Thanks,

jon

Em Mon, 25 Aug 2025 06:15:49 -0600
Jonathan Corbet <[email protected]> escreveu:

Yes, I know: by you, I mean you both ;-)

Feel free to add a reported-by at the actual patch... I ended forgetting about that.

Thanks!

Thanks,
Mauro

PDF output with current Debian-based distros require other packages for it to work. The main one is pzdr.tfm. Without that, \sphinxhyphen{} won't work, affecting multiple docs.

For CJK, tex-gyre is required.

Add the missing packages to the list.

After the change, all PDF files build on latest Ubuntu:

Ubuntu 25.04:
-------------
PASSED: OS detection: Ubuntu 25.04
SKIPPED (Sphinx Sphinx 8.1.3): System packages
SKIPPED (Sphinx already installed either as venv or as native package): Sphinx on venv SKIPPED (Sphinx already installed either as venv or as native package): Sphinx package
PASSED: Clean documentation: Build time: 0:00, return code: 0
PASSED: Build HTML documentation: Build time: 3:28, return code: 0
PASSED: Build PDF documentation: Build time: 11:08, return code: 0

PDF docs:
---------
PASSED: dev-tools: pdf/dev-tools.pdf
PASSED: tools: pdf/tools.pdf
PASSED: filesystems: pdf/filesystems.pdf
PASSED: w1: pdf/w1.pdf
PASSED: maintainer: pdf/maintainer.pdf
PASSED: process: pdf/process.pdf
PASSED: isdn: pdf/isdn.pdf
PASSED: fault-injection: pdf/fault-injection.pdf
PASSED: iio: pdf/iio.pdf
PASSED: scheduler: pdf/scheduler.pdf
PASSED: staging: pdf/staging.pdf
PASSED: fpga: pdf/fpga.pdf
PASSED: power: pdf/power.pdf
PASSED: leds: pdf/leds.pdf
PASSED: edac: pdf/edac.pdf
PASSED: PCI: pdf/PCI.pdf
PASSED: firmware-guide: pdf/firmware-guide.pdf
PASSED: cpu-freq: pdf/cpu-freq.pdf
PASSED: mhi: pdf/mhi.pdf
PASSED: wmi: pdf/wmi.pdf
PASSED: timers: pdf/timers.pdf
PASSED: accel: pdf/accel.pdf
PASSED: hid: pdf/hid.pdf
PASSED: userspace-api: pdf/userspace-api.pdf
PASSED: spi: pdf/spi.pdf
PASSED: networking: pdf/networking.pdf
PASSED: virt: pdf/virt.pdf
PASSED: nvme: pdf/nvme.pdf
PASSED: translations: pdf/translations.pdf
PASSED: input: pdf/input.pdf
PASSED: tee: pdf/tee.pdf
PASSED: doc-guide: pdf/doc-guide.pdf
PASSED: cdrom: pdf/cdrom.pdf
PASSED: gpu: pdf/gpu.pdf
PASSED: i2c: pdf/i2c.pdf
PASSED: RCU: pdf/RCU.pdf
PASSED: watchdog: pdf/watchdog.pdf
PASSED: usb: pdf/usb.pdf
PASSED: rust: pdf/rust.pdf
PASSED: crypto: pdf/crypto.pdf
PASSED: kbuild: pdf/kbuild.pdf
PASSED: livepatch: pdf/livepatch.pdf
PASSED: mm: pdf/mm.pdf
PASSED: locking: pdf/locking.pdf
PASSED: infiniband: pdf/infiniband.pdf
PASSED: driver-api: pdf/driver-api.pdf
PASSED: bpf: pdf/bpf.pdf
PASSED: devicetree: pdf/devicetree.pdf
PASSED: block: pdf/block.pdf
PASSED: target: pdf/target.pdf
PASSED: arch: pdf/arch.pdf
PASSED: pcmcia: pdf/pcmcia.pdf
PASSED: scsi: pdf/scsi.pdf
PASSED: netlabel: pdf/netlabel.pdf
PASSED: sound: pdf/sound.pdf
PASSED: security: pdf/security.pdf
PASSED: accounting: pdf/accounting.pdf
PASSED: admin-guide: pdf/admin-guide.pdf
PASSED: core-api: pdf/core-api.pdf
PASSED: fb: pdf/fb.pdf
PASSED: peci: pdf/peci.pdf
PASSED: trace: pdf/trace.pdf
PASSED: misc-devices: pdf/misc-devices.pdf
PASSED: kernel-hacking: pdf/kernel-hacking.pdf
PASSED: hwmon: pdf/hwmon.pdf

---
 scripts/sphinx-pre-install | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

index b8474848df4e..b24a6f91ec0a 100755
@@ -764,9 +764,6 @@ class SphinxDependencyChecker(MissingCheckers):
 
         if self.pdf:
             pdf_pkgs = {
-                "texlive-lang-chinese": [
-                    "/usr/share/texlive/texmf-dist/tex/latex/ctex/ctexhook.sty",
-                ],
                 "fonts-dejavu": [
                     "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
                 ],

@@ -775,6 +772,15 @@ class SphinxDependencyChecker(MissingCheckers):
                     "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
                     "/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc",
                 ],
+                "tex-gyre": [
+                    "/usr/share/texmf/tex/latex/tex-gyre/tgtermes.sty"
+                ],
+                "texlive-fonts-recommended": [
+                    "/usr/share/texlive/texmf-dist/fonts/tfm/adobe/zapfding/pzdr.tfm",
+                ],
+                "texlive-lang-chinese": [
+                    "/usr/share/texlive/texmf-dist/tex/latex/ctex/ctexhook.sty",
+                ],
             }
 
             for package, files in pdf_pkgs.items():

2.50.1

There are two packages that are required to build PDF at gentoo:

dev-texlive/texlive-latexextra
media-fonts/lm

Place latex_dependencies on a list to make it easier to maintain and add the missing ones.

With that, most PDF documents now build on Gentoo:

Gentoo Base System release 2.17:
--------------------------------
PASSED: OS detection: Gentoo Base System release 2.17
SKIPPED (Sphinx Sphinx 8.2.3): System packages
SKIPPED (Sphinx already installed either as venv or as native package): Sphinx on venv SKIPPED (Sphinx already installed either as venv or as native package): Sphinx package
PASSED: Clean documentation: Build time: 0:00, return code: 0
PASSED: Build HTML documentation: Build time: 5:28, return code: 0
PARTIAL: Build PDF documentation: Test failed (Build time: 9:19, return code: 2)

PDF docs:
---------
PASSED: dev-tools: pdf/dev-tools.pdf
PASSED: tools: pdf/tools.pdf
PASSED: filesystems: pdf/filesystems.pdf
PASSED: w1: pdf/w1.pdf
PASSED: maintainer: pdf/maintainer.pdf
PASSED: process: pdf/process.pdf
PASSED: isdn: pdf/isdn.pdf
PASSED: fault-injection: pdf/fault-injection.pdf
PASSED: iio: pdf/iio.pdf
PASSED: scheduler: pdf/scheduler.pdf
PASSED: staging: pdf/staging.pdf
PASSED: fpga: pdf/fpga.pdf
PASSED: power: pdf/power.pdf
PASSED: leds: pdf/leds.pdf
PASSED: edac: pdf/edac.pdf
PASSED: PCI: pdf/PCI.pdf
PASSED: firmware-guide: pdf/firmware-guide.pdf
PASSED: cpu-freq: pdf/cpu-freq.pdf
PASSED: mhi: pdf/mhi.pdf
PASSED: wmi: pdf/wmi.pdf
PASSED: timers: pdf/timers.pdf
PASSED: accel: pdf/accel.pdf
PASSED: hid: pdf/hid.pdf
FAILED: userspace-api: Build failed (FAILED)
PASSED: spi: pdf/spi.pdf
PASSED: networking: pdf/networking.pdf
PASSED: virt: pdf/virt.pdf
PASSED: nvme: pdf/nvme.pdf
FAILED: translations: Build failed (FAILED)
PASSED: input: pdf/input.pdf
PASSED: tee: pdf/tee.pdf
PASSED: doc-guide: pdf/doc-guide.pdf
PASSED: cdrom: pdf/cdrom.pdf
FAILED: gpu: Build failed (FAILED)
FAILED: i2c: Build failed (FAILED)
FAILED: RCU: Build failed (FAILED)
PASSED: watchdog: pdf/watchdog.pdf
PASSED: usb: pdf/usb.pdf
PASSED: rust: pdf/rust.pdf
PASSED: crypto: pdf/crypto.pdf
PASSED: kbuild: pdf/kbuild.pdf
PASSED: livepatch: pdf/livepatch.pdf
PASSED: mm: pdf/mm.pdf
PASSED: locking: pdf/locking.pdf
PASSED: infiniband: pdf/infiniband.pdf
PASSED: driver-api: pdf/driver-api.pdf
PASSED: bpf: pdf/bpf.pdf
PASSED: devicetree: pdf/devicetree.pdf
PASSED: block: pdf/block.pdf
PASSED: target: pdf/target.pdf
FAILED: arch: Build failed (FAILED)
PASSED: pcmcia: pdf/pcmcia.pdf
PASSED: scsi: pdf/scsi.pdf
PASSED: netlabel: pdf/netlabel.pdf
PASSED: sound: pdf/sound.pdf
PASSED: security: pdf/security.pdf
PASSED: accounting: pdf/accounting.pdf
PASSED: admin-guide: pdf/admin-guide.pdf
FAILED: core-api: Build failed (FAILED)
PASSED: fb: pdf/fb.pdf
PASSED: peci: pdf/peci.pdf
PASSED: trace: pdf/trace.pdf
PASSED: misc-devices: pdf/misc-devices.pdf
PASSED: kernel-hacking: pdf/kernel-hacking.pdf
PASSED: hwmon: pdf/hwmon.pdf

---
 scripts/sphinx-pre-install | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

index b24a6f91ec0a..f987abfec802 100755
@@ -1058,12 +1058,19 @@ class SphinxDependencyChecker(MissingCheckers):
         """
         Provide package installation hints for Gentoo.
         """
+        texlive_deps = [
+            "dev-texlive/texlive-latexextra",
+            "dev-texlive/texlive-xetex",
+            "media-fonts/dejavu",
+            "media-fonts/lm",
+        ]
+
         progs = {
             "convert":       "media-gfx/imagemagick",
             "dot":           "media-gfx/graphviz",
             "rsvg-convert":  "gnome-base/librsvg",
             "virtualenv":    "dev-python/virtualenv",
-            "xelatex":       "dev-texlive/texlive-xetex media-fonts/dejavu",
+            "xelatex":       " ".join(texlive_deps),
             "yaml":          "dev-python/pyyaml",
             "python-sphinx": "dev-python/sphinx",
         }

2.50.1

The dependencies are outdated: both versions need texlive-dejavu fonts. Also, for PDF generation, python311-Sphinx-latex is required.

With that, all PDF files are now tuilt on both:

openSUSE Leap 15.6:
-------------------
PASSED: OS detection: openSUSE Leap 15.6
SKIPPED (Sphinx Sphinx 7.2.6): System packages
SKIPPED (Sphinx already installed either as venv or as native package): Sphinx on venv SKIPPED (Sphinx already installed either as venv or as native package): Sphinx package
PASSED: Clean documentation: Build time: 0:00, return code: 0
PASSED: Build HTML documentation: Build time: 5:29, return code: 0
PASSED: Build PDF documentation: Build time: 13:45, return code: 0

openSUSE Tumbleweed:
--------------------
PASSED: OS detection: openSUSE Tumbleweed
SKIPPED (Sphinx Sphinx 8.2.3): System packages
SKIPPED (Sphinx already installed either as venv or as native package): Sphinx on venv SKIPPED (Sphinx already installed either as venv or as native package): Sphinx package
PASSED: Clean documentation: Build time: 0:00, return code: 0
PASSED: Build HTML documentation: Build time: 4:33, return code: 0
PASSED: Build PDF documentation: Build time: 13:18, return code: 0

Summary
=======
PASSED - openSUSE Leap 15.6 (7 tests)
PASSED - openSUSE Tumbleweed (7 tests)

---
 scripts/sphinx-pre-install | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

index f987abfec802..86f129c76ecd 100755
@@ -901,7 +901,7 @@ class SphinxDependencyChecker(MissingCheckers):
             "dot":           "graphviz",
             "python-sphinx": "python3-sphinx",
             "virtualenv":    "python3-virtualenv",
-            "xelatex":       "texlive-xetex-bin",
+            "xelatex":       "texlive-xetex-bin texlive-dejavu",
             "yaml":          "python3-pyyaml",
         }
 

@@ -937,7 +937,7 @@ class SphinxDependencyChecker(MissingCheckers):
                     self.recommend_python = True
 
                 progs.update({
-                    "python-sphinx": "python311-Sphinx",
+                    "python-sphinx": "python311-Sphinx python311-Sphinx-latex",
                     "virtualenv":    "python311-virtualenv",
                     "yaml":          "python311-PyYAML",
                 })

@@ -945,7 +945,7 @@ class SphinxDependencyChecker(MissingCheckers):
             # Tumbleweed defaults to Python 3.11
 
             progs.update({
-                "python-sphinx": "python313-Sphinx",
+                "python-sphinx": "python313-Sphinx python313-Sphinx-latex",
                 "virtualenv":    "python313-virtualenv",
                 "yaml":          "python313-PyYAML",
             })

2.50.1

The dependeny list for OpenMandriva is wrong. Update it.

Yet, on my tests with OpenMandriva LX 4.3, the texlive packages are
broken: xelatex can't build anything there, as it lacks xelatex.sfm.

Yet, this could be a problem at the way I created the container. Just in case, add a note about that.

---
 scripts/sphinx-pre-install | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

index 86f129c76ecd..224db3af17db 100755
@@ -984,13 +984,19 @@ class SphinxDependencyChecker(MissingCheckers):
         if re.search(r"OpenMandriva", self.system_release):
             packager_cmd = "dnf install"
             noto_sans = "noto-sans-cjk-fonts"
-            tex_pkgs = ["texlive-collection-fontsextra"]
+            tex_pkgs = [
+                "texlive-collection-basic",
+                "texlive-collection-langcjk",
+                "texlive-collection-fontsextra",
+                "texlive-collection-fontsrecommended"
+            ]
 
             # Tested on OpenMandriva Lx 4.3
             progs["convert"] = "imagemagick"
             progs["yaml"] = "python-pyyaml"
             progs["python-virtualenv"] = "python-virtualenv"
             progs["python-sphinx"] = "python-sphinx"
+            progs["xelatex"] = "texlive"
 
             self.check_program("python-virtualenv", DepManager.PYTHON_MANDATORY)
 

@@ -1004,7 +1010,9 @@ class SphinxDependencyChecker(MissingCheckers):
 
             if not self.distro_msg:
                 self.distro_msg = \
-                    "Note: for venv, ensurepip could be broken, preventing its install method."
+                    "Notes:\n"\
+                    "1. for venv, ensurepip could be broken, preventing its install method.\n" \
+                    "2. at least on OpenMandriva LX 4.3, texlive packages seem broken"
 
         else:
             packager_cmd = "urpmi"

2.50.1

On Mageia 9, two packages are missing. Add them.

With that, all PDF packages now build:

Mageia 9:
---------
PASSED: OS detection: Mageia 9
PASSED: System packages: Packages installed
PASSED: Sphinx on venv: Sphinx Sphinx 8.1.3
PASSED: Sphinx package: Sphinx Sphinx 6.1.3
PASSED: Clean documentation: Build time: 0:00, return code: 0
PASSED: Build HTML documentation: Build time: 5:17, return code: 0
PASSED: Build PDF documentation: Build time: 14:28, return code: 0

PDF docs:
---------
PASSED: dev-tools: pdf/dev-tools.pdf
PASSED: tools: pdf/tools.pdf
PASSED: filesystems: pdf/filesystems.pdf
PASSED: w1: pdf/w1.pdf
PASSED: maintainer: pdf/maintainer.pdf
PASSED: process: pdf/process.pdf
PASSED: isdn: pdf/isdn.pdf
PASSED: fault-injection: pdf/fault-injection.pdf
PASSED: iio: pdf/iio.pdf
PASSED: scheduler: pdf/scheduler.pdf
PASSED: staging: pdf/staging.pdf
PASSED: fpga: pdf/fpga.pdf
PASSED: power: pdf/power.pdf
PASSED: leds: pdf/leds.pdf
PASSED: edac: pdf/edac.pdf
PASSED: PCI: pdf/PCI.pdf
PASSED: firmware-guide: pdf/firmware-guide.pdf
PASSED: cpu-freq: pdf/cpu-freq.pdf
PASSED: mhi: pdf/mhi.pdf
PASSED: wmi: pdf/wmi.pdf
PASSED: timers: pdf/timers.pdf
PASSED: accel: pdf/accel.pdf
PASSED: hid: pdf/hid.pdf
PASSED: userspace-api: pdf/userspace-api.pdf
PASSED: spi: pdf/spi.pdf
PASSED: networking: pdf/networking.pdf
PASSED: virt: pdf/virt.pdf
PASSED: nvme: pdf/nvme.pdf
PASSED: translations: pdf/translations.pdf
PASSED: input: pdf/input.pdf
PASSED: tee: pdf/tee.pdf
PASSED: doc-guide: pdf/doc-guide.pdf
PASSED: cdrom: pdf/cdrom.pdf
PASSED: gpu: pdf/gpu.pdf
PASSED: i2c: pdf/i2c.pdf
PASSED: RCU: pdf/RCU.pdf
PASSED: watchdog: pdf/watchdog.pdf
PASSED: usb: pdf/usb.pdf
PASSED: rust: pdf/rust.pdf
PASSED: crypto: pdf/crypto.pdf
PASSED: kbuild: pdf/kbuild.pdf
PASSED: livepatch: pdf/livepatch.pdf
PASSED: mm: pdf/mm.pdf
PASSED: locking: pdf/locking.pdf
PASSED: infiniband: pdf/infiniband.pdf
PASSED: driver-api: pdf/driver-api.pdf
PASSED: bpf: pdf/bpf.pdf
PASSED: devicetree: pdf/devicetree.pdf
PASSED: block: pdf/block.pdf
PASSED: target: pdf/target.pdf
PASSED: arch: pdf/arch.pdf
PASSED: pcmcia: pdf/pcmcia.pdf
PASSED: scsi: pdf/scsi.pdf
PASSED: netlabel: pdf/netlabel.pdf
PASSED: sound: pdf/sound.pdf
PASSED: security: pdf/security.pdf
PASSED: accounting: pdf/accounting.pdf
PASSED: admin-guide: pdf/admin-guide.pdf
PASSED: core-api: pdf/core-api.pdf
PASSED: fb: pdf/fb.pdf
PASSED: peci: pdf/peci.pdf
PASSED: trace: pdf/trace.pdf
PASSED: misc-devices: pdf/misc-devices.pdf
PASSED: kernel-hacking: pdf/kernel-hacking.pdf
PASSED: hwmon: pdf/hwmon.pdf

Summary
=======
PASSED - Mageia 9 (7 tests)

---
 scripts/sphinx-pre-install | 2 ++
 1 file changed, 2 insertions(+)

index 224db3af17db..758a84ae6347 100755
@@ -979,6 +979,8 @@ class SphinxDependencyChecker(MissingCheckers):
 
         tex_pkgs = [
             "texlive-fontsextra",
+            "texlive-fonts-asian",
+            "fonts-ttf-dejavu",
         ]
 
         if re.search(r"OpenMandriva", self.system_release):

2.50.1

Package fonts are wrong. Fix it. With that, most PDF files now builds.

PDF docs:
---------
PASSED: dev-tools: pdf/dev-tools.pdf
PASSED: tools: pdf/tools.pdf
PASSED: filesystems: pdf/filesystems.pdf
PASSED: w1: pdf/w1.pdf
PASSED: maintainer: pdf/maintainer.pdf
PASSED: process: pdf/process.pdf
PASSED: isdn: pdf/isdn.pdf
PASSED: fault-injection: pdf/fault-injection.pdf
PASSED: iio: pdf/iio.pdf
PASSED: scheduler: pdf/scheduler.pdf
PASSED: staging: pdf/staging.pdf
PASSED: fpga: pdf/fpga.pdf
PASSED: power: pdf/power.pdf
PASSED: leds: pdf/leds.pdf
PASSED: edac: pdf/edac.pdf
PASSED: PCI: pdf/PCI.pdf
PASSED: firmware-guide: pdf/firmware-guide.pdf
PASSED: cpu-freq: pdf/cpu-freq.pdf
PASSED: mhi: pdf/mhi.pdf
PASSED: wmi: pdf/wmi.pdf
PASSED: timers: pdf/timers.pdf
PASSED: accel: pdf/accel.pdf
PASSED: hid: pdf/hid.pdf
FAILED: userspace-api: Build failed (FAILED)
PASSED: spi: pdf/spi.pdf
PASSED: networking: pdf/networking.pdf
PASSED: virt: pdf/virt.pdf
PASSED: nvme: pdf/nvme.pdf
FAILED: translations: Build failed (FAILED)
PASSED: input: pdf/input.pdf
PASSED: tee: pdf/tee.pdf
PASSED: doc-guide: pdf/doc-guide.pdf
PASSED: cdrom: pdf/cdrom.pdf
FAILED: gpu: Build failed (FAILED)
FAILED: i2c: Build failed (FAILED)
FAILED: RCU: Build failed (FAILED)
PASSED: watchdog: pdf/watchdog.pdf
PASSED: usb: pdf/usb.pdf
PASSED: rust: pdf/rust.pdf
PASSED: crypto: pdf/crypto.pdf
PASSED: kbuild: pdf/kbuild.pdf
PASSED: livepatch: pdf/livepatch.pdf
PASSED: mm: pdf/mm.pdf
PASSED: locking: pdf/locking.pdf
PASSED: infiniband: pdf/infiniband.pdf
PASSED: driver-api: pdf/driver-api.pdf
PASSED: bpf: pdf/bpf.pdf
PASSED: devicetree: pdf/devicetree.pdf
PASSED: block: pdf/block.pdf
PASSED: target: pdf/target.pdf
FAILED: arch: Build failed (FAILED)
PASSED: pcmcia: pdf/pcmcia.pdf
PASSED: scsi: pdf/scsi.pdf
PASSED: netlabel: pdf/netlabel.pdf
PASSED: sound: pdf/sound.pdf
PASSED: security: pdf/security.pdf
PASSED: accounting: pdf/accounting.pdf
PASSED: admin-guide: pdf/admin-guide.pdf
FAILED: core-api: Build failed (FAILED)
PASSED: fb: pdf/fb.pdf
PASSED: peci: pdf/peci.pdf
PASSED: trace: pdf/trace.pdf
PASSED: misc-devices: pdf/misc-devices.pdf
PASSED: kernel-hacking: pdf/kernel-hacking.pdf
PASSED: hwmon: pdf/hwmon.pdf

---
 scripts/sphinx-pre-install | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index 758a84ae6347..c46d7b76f93c 100755
@@ -1069,10 +1069,10 @@ class SphinxDependencyChecker(MissingCheckers):
         Provide package installation hints for Gentoo.
         """
         texlive_deps = [
+            "dev-texlive/texlive-fontsrecommended",
             "dev-texlive/texlive-latexextra",
             "dev-texlive/texlive-xetex",
             "media-fonts/dejavu",
-            "media-fonts/lm",
         ]
 
         progs = {

2.50.1

There are some missing packages causing PDF build to fail on Archlinux and add latexmk (from texlive-binextra package).

Yet, at least today, PDF builds are failing on a very late stage, when trying to run xdvipdfmx:

	$ xdvipdfmx -E -o "peci.pdf"  "peci.xdv"
	xdvipdfmx:fatal: Unrecognized paper format: # Simply write the paper name. See man 1 paper and "paper --no-size --all" for possible values

Despite its message, even using a very simple document like:

        \def\sphinxdocclass{report}
	\documentclass[a4paper,11pt,english]{sphinxmanual}
	\begin{document}
	Test
	\end{document}

or even:

	\def\sphinxdocclass{report}
	\documentclass{sphinxmanual}
	\begin{document}
	Test
	\end{document}

Is causing xdvipdfmx to complain about geometry. As Archlinux is a rolling release distro, maybe I got it on a bad day. So, let's fix it in the hope that soon enough someone would fix the issues there.

Such broken scenario happens with those packages installed:

texlive-basic 2025.2-1
texlive-bin 2025.2-1
texlive-binextra 2025.2-1
texlive-fontsrecommended 2025.2-1
texlive-langchinese 2025.2-1
texlive-langcjk 2025.2-1
texlive-latex 2025.2-1
texlive-latexextra 2025.2-1
texlive-latexrecommended 2025.2-1
texlive-pictures 2025.2-1
texlive-xetex 2025.2-1
python-docutils 1:0.21.2-3
python-sphinx 8.2.3-1
python-sphinx-alabaster-theme 1.0.0-4
python-sphinxcontrib-applehelp 2.0.0-3
python-sphinxcontrib-devhelp 2.0.0-4
python-sphinxcontrib-htmlhelp 2.1.0-3
python-sphinxcontrib-jsmath 1.0.1-19
python-sphinxcontrib-qthelp 2.0.0-3
python-sphinxcontrib-serializinghtml 2.0.0-3

---
 scripts/sphinx-pre-install | 5 +++++
 1 file changed, 5 insertions(+)

index c46d7b76f93c..954ed3dc0645 100755
@@ -1048,7 +1048,12 @@ class SphinxDependencyChecker(MissingCheckers):
         }
 
         archlinux_tex_pkgs = [
+            "texlive-basic",
+            "texlive-binextra",
             "texlive-core",
+            "texlive-fontsrecommended",
+            "texlive-langchinese",
+            "texlive-langcjk",
             "texlive-latexextra",
             "ttf-dejavu",
         ]

2.50.1

OK, in the hopes of pushing through some of this stuff, I have gone ahead and applied this set; if things need tweaking, we can tweak in the coming weeks.

Thanks,

jon

Em Thu, 21 Aug 2025 13:22:29 -0600
Jonathan Corbet <[email protected]> escreveu:

Thanks, very much appreciated!
Mauro