[PATCH v2 00/14] Fix PDF doc builds on major distros

[PATCH v2 00/14] Fix PDF doc builds on major distros

[Mauro Carvalho Chehab]

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

[PATCH v2 01/14] docs: Makefile: Fix LaTeX paper size settings

[Mauro Carvalho Chehab]

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

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/Makefile | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 820f07e0afe6..2ed334971acd 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -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

[PATCH v2 02/14] docs: conf.py: better handle latex documents

[Mauro Carvalho Chehab]

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.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/conf.py | 54 +++++++++++++++++++++----------------------
 1 file changed, 26 insertions(+), 28 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index f9828f3862f9..2c1be59fd54b 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -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

[PATCH v2 03/14] docs: conf.py: fix doc name with SPHINXDIRS

[Mauro Carvalho Chehab]

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.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/conf.py | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 2c1be59fd54b..c8401ed75402 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -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

[PATCH v2 04/14] docs: conf.py: rename some vars at latex_documents logic

[Mauro Carvalho Chehab]

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.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/conf.py | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index c8401ed75402..6e12c7d8e07e 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -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

[PATCH v2 05/14] docs: conf.py: use dedent and r-strings for LaTeX macros

[Mauro Carvalho Chehab]

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.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/conf.py | 26 ++++++++++++--------------
 1 file changed, 12 insertions(+), 14 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 6e12c7d8e07e..628af81e6879 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -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

[PATCH v2 06/14] docs: conf.py: fix some troubles for LaTeX output

[Mauro Carvalho Chehab]

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

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/conf.py | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 628af81e6879..5888e2988b4f 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -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

[PATCH v2 07/14] docs: conf.py: extra cleanups and fixes

[Mauro Carvalho Chehab]

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.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/conf.py | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 5888e2988b4f..1c4695727208 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -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

[PATCH v2 08/14] scripts: sphinx-pre-install: fix PDF build issues on Ubuntu

[Mauro Carvalho Chehab]

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

Reported-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/sphinx-pre-install | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index b8474848df4e..b24a6f91ec0a 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -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

[PATCH v2 09/14] scripts: sphinx-pre-install: add missing gentoo pdf dependencies

[Mauro Carvalho Chehab]

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

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/sphinx-pre-install | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index b24a6f91ec0a..f987abfec802 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -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

[PATCH v2 10/14] scripts: sphinx-pre-install: fix PDF dependencies for openSuse

[Mauro Carvalho Chehab]

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)

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/sphinx-pre-install | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index f987abfec802..86f129c76ecd 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -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

[PATCH v2 11/14] scripts: sphinx-pre-install: fix dependencies for OpenMandriva

[Mauro Carvalho Chehab]

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.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/sphinx-pre-install | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index 86f129c76ecd..224db3af17db 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -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

[PATCH v2 12/14] scripts: sphinx-pre-install: fix pdf dependencies for Mageia 9

[Mauro Carvalho Chehab]

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)

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/sphinx-pre-install | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index 224db3af17db..758a84ae6347 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -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

[PATCH v2 13/14] scripts: sphinx-pre-install: fix PDF dependencies for gentoo

[Mauro Carvalho Chehab]

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

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/sphinx-pre-install | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index 758a84ae6347..c46d7b76f93c 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -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

[PATCH v2 14/14] scripts/sphinx-pre-install: fix Archlinux PDF dependencies

[Mauro Carvalho Chehab]

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

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/sphinx-pre-install | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index c46d7b76f93c..954ed3dc0645 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -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

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

[Jonathan Corbet]

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

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

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

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

[Mauro Carvalho Chehab]

Em Thu, 21 Aug 2025 13:22:29 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > 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.  
> 
> 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, very much appreciated!
Mauro

Re: [PATCH v2 07/14] docs: conf.py: extra cleanups and fixes

[Akira Yokosawa]

Hi Mauro,

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

On Thu, 21 Aug 2025 10:16:43 +0200, Mauro Carvalho Chehab wrote:
> 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.

This looks good.

> 
> 2) to add at the main example:
>          \PassOptionsToPackage{svgnames}{xcolor}

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

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

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

Re: [PATCH v2 07/14] docs: conf.py: extra cleanups and fixes

[Mauro Carvalho Chehab]

On Fri, Aug 22, 2025 at 09:01:03PM +0900, Akira Yokosawa wrote:
> Hi Mauro,
> 
> I see this has already been merged, but let me comment after the fact.
> 
> On Thu, 21 Aug 2025 10:16:43 +0200, Mauro Carvalho Chehab wrote:
> > 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.
> 
> This looks good.
> 
> > 
> > 2) to add at the main example:
> >          \PassOptionsToPackage{svgnames}{xcolor}
> 
> OK.  So I guess Sphinx's latex builder is going to start using SVG color
> naming in the near future.
> 
> > 
> > 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.
> 
> 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?

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

Re: [PATCH v2 07/14] docs: conf.py: extra cleanups and fixes

[Jonathan Corbet]

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> On Fri, Aug 22, 2025 at 09:01:03PM +0900, Akira Yokosawa wrote:

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

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:

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

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)

Re: [PATCH v2 07/14] docs: conf.py: extra cleanups and fixes

[Mauro Carvalho Chehab]

Em Fri, 22 Aug 2025 16:34:38 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> > On Fri, Aug 22, 2025 at 09:01:03PM +0900, Akira Yokosawa wrote:  
> 
> >> > 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.  
> >> 
> >> 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?  
> >
> > 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.  
> 
> 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:
> 
> > \PassOptionsToPackage{xindy}{language=english,codepage=utf8,noautomatic}  
> 
> As I understand it, the arguments are {options}{package}, right?  so I'm
> not sure how this would work...?

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

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

Thanks,
Mauro

Re: [PATCH v2 07/14] docs: conf.py: extra cleanups and fixes

[Jonathan Corbet]

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

> Em Fri, 22 Aug 2025 16:34:38 -0600
> Jonathan Corbet <corbet@lwn.net> escreveu:
>> 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:
>> 
>> > \PassOptionsToPackage{xindy}{language=english,codepage=utf8,noautomatic}  
>> 
>> As I understand it, the arguments are {options}{package}, right?  so I'm
>> not sure how this would work...?
>
> 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.

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

> 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

OK I'll get there.

Thanks,

jon

Re: [PATCH v2 07/14] docs: conf.py: extra cleanups and fixes

[Mauro Carvalho Chehab]

Em Mon, 25 Aug 2025 06:15:49 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > Em Fri, 22 Aug 2025 16:34:38 -0600
> > Jonathan Corbet <corbet@lwn.net> escreveu:  
> >> 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:
> >>   
> >> > \PassOptionsToPackage{xindy}{language=english,codepage=utf8,noautomatic}    
> >> 
> >> As I understand it, the arguments are {options}{package}, right?  so I'm
> >> not sure how this would work...?  
> >
> > 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.  
> 
> Just to get the credit where it is due, it's Akira who first pointed
> this out.

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.

> 
> > 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  
> 
> OK I'll get there.

Thanks!

Thanks,
Mauro