linux-kernel - Re: [PATCH 05/11] docs: conf.py: fix some troubles for LaTeX output

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <bf58f8ef-5fe8-435c-a2d5-efe0f2fd2ebd@gmail.com>
Date: Wed, 20 Aug 2025 17:16:11 +0900
From: Akira Yokosawa <akiyks@...il.com>
To: mchehab+huawei@...nel.org
Cc: corbet@....net, linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
 Akira Yokosawa <akiyks@...il.com>
Subject: Re: [PATCH 05/11] docs: conf.py: fix some troubles for LaTeX output

Hi Mauro,

Looks like my word choice annoyed you.  Apologies again.

I've just realized your response while composing this, but I'm sending
it anyway.  Please see below.

On Fri, 15 Aug 2025 13:36:21 +0200, Mauro Carvalho Chehab wrote:
> While PDF docs work fine on RPM-based distros, it causes conflicts
> on Debian & friends:
> 
> Documentation/output/process/latex/process.log:
> 
> 	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@...tshape ...message {Corrupted NFSS tables}
>                                                   error@...tshape else let f...
> 	l.116 ...\familydefault\seriesdefault\shapedefault
> 
> Change some logic inside latex_elements to avoid such issues,
> following the example from Sphinx documentation:
> 
> 	https://www.sphinx-doc.org/en/master/latex.html
> 

I spotted a wrong looking LaTeX macro use.  See below:

> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
> ---
>  Documentation/conf.py | 39 +++++++++++++++++++++++----------------
>  1 file changed, 23 insertions(+), 16 deletions(-)
> 
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 6e12c7d8e07e..712e0a016727 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,
> @@ -454,19 +456,38 @@ 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}
> +    """),

This use of \PassOptionsToPackage{}{} looks very wrong, because its 1st
argument is the option string you would like to pass to a latex package
given in the 2nd argument.

See: https://latexref.xyz/_005cPassOptionsToClass-_0026-_005cPassOptionsToPackage.html

Furthermore, as there is no such latex package named "xindy",
this will have any effect even if you reverse the argument order.

I imagine you had some illusion and believed it would fix some issue
you had observed.

Also, I don't see the need of \PassOptionsToPackage{svgnames}{xcolor}.
Please clarify who needs that color namespace option in the changelog.

>      # The font size ('10pt', '11pt' or '12pt').
>      "pointsize": "11pt",
> +    # Needed to generate a .ind file
> +    'printindex': r'\footnotesize\raggedright\printindex',

I would mention this as an improvement in the changelog.

And the following changes look good to me.

Thanks, Akira

>      # Latex figure (float) alignment
>      # 'figure_align': 'htbp',
>      # Don't mangle with UTF-8 chars
> +    "fontenc": "",
>      "inputenc": "",
>      "utf8extra": "",
> +    'fontpkg': dedent(r'''
> +        \usepackage{fontspec}
> +        \setmainfont{DejaVu Serif}
> +        \setsansfont{DejaVu Sans}
> +        \setmonofont{DejaVu Sans Mono}
> +        \newfontfamily\headingfont{DejaVu Serif}
> +    '''),
>      # Set document margins
> -    "sphinxsetup": """
> +    "sphinxsetup": dedent(r"""
>          hmargin=0.5in, vmargin=1in,
>          parsedliteralwraps=true,
>          verbatimhintsturnover=false,
> -    """,
> +    """),
> +    "preamble": dedent(r"""
> +        % Load kerneldoc specific LaTeX settings
> +        \input{kerneldoc-preamble.sty}
> +    """),
>      #
>      # Some of our authors are fond of deep nesting; tell latex to
>      # cope.
> @@ -474,22 +495,8 @@ 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": """
> -        % 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"] += """
> -        % Load kerneldoc specific LaTeX settings
> -        \\input{kerneldoc-preamble.sty}
> -"""
> -
>  # This will be filled up by config-inited event
>  latex_documents = []
>