Message-ID: <CALC8CXdNRwWnQyfA0UK657JOm6vZnH-6nOpDSjMbZkhqyiQb8g@mail.gmail.com>
Date: Thu, 2 Oct 2025 12:30:33 -0400
From: ChaosEsque Team <chaosesqueteam@...il.com>
To: Akira Yokosawa <akiyks@...il.com>
Cc: mchehab+huawei@...nel.org, corbet@....net, linux-doc@...r.kernel.org, 
	linux-kernel@...r.kernel.org
Subject: Re: [PATCH 05/11] docs: conf.py: fix some troubles for LaTeX output

AKIRA!

On Wed, Aug 20, 2025 at 4:18 AM Akira Yokosawa <akiyks@...il.com> wrote:
>
> 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 = []
> >
>

Powered by blists - more mailing lists