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
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
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
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)
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
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
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
© 2016 - 2025 Red Hat, Inc.