Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: kdoc: latex_fonts: Improve docstrings and comments
In preparation to document kernel-doc module, improve its
documentation.
Among the changes, it had to place the xml template inside
a code block, as otherwise doc build would break.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <6e0eb2e245eae9b4f39cf231dee32df00b9e8b7b.1768838938.git.mchehab+huawei@kernel.org>
authored by
Mauro Carvalho Chehab
and committed by
Jonathan Corbet
4d7f6319
4b8fae7a
+56
-39
+56
-39
tools/lib/python/kdoc/latex_fonts.py
+56
-39
tools/lib/python/kdoc/latex_fonts.py
···
5
5
# Ported to Python by (c) Mauro Carvalho Chehab, 2025
6
6
7
7
"""
8
-
Detect problematic Noto CJK variable fonts.
8
+
Detect problematic Noto CJK variable fonts
9
+
==========================================
9
10
10
-
For "make pdfdocs", reports of build errors of translations.pdf started
11
-
arriving early 2024 [1, 2]. It turned out that Fedora and openSUSE
12
-
tumbleweed have started deploying variable-font [3] format of "Noto CJK"
13
-
fonts [4, 5]. For PDF, a LaTeX package named xeCJK is used for CJK
11
+
For ``make pdfdocs``, reports of build errors of translations.pdf started
12
+
arriving early 2024 [1]_ [2]_. It turned out that Fedora and openSUSE
13
+
tumbleweed have started deploying variable-font [3]_ format of "Noto CJK"
14
+
fonts [4]_ [5]_. For PDF, a LaTeX package named xeCJK is used for CJK
14
15
(Chinese, Japanese, Korean) pages. xeCJK requires XeLaTeX/XeTeX, which
15
16
does not (and likely never will) understand variable fonts for historical
16
17
reasons.
···
26
25
suggestions if variable-font files of "Noto CJK" fonts are in the list of
27
26
fonts accessible from XeTeX.
28
27
29
-
References:
30
-
[1]: https://lore.kernel.org/r/8734tqsrt7.fsf@meer.lwn.net/
31
-
[2]: https://lore.kernel.org/r/1708585803.600323099@f111.i.mail.ru/
32
-
[3]: https://en.wikipedia.org/wiki/Variable_font
33
-
[4]: https://fedoraproject.org/wiki/Changes/Noto_CJK_Variable_Fonts
34
-
[5]: https://build.opensuse.org/request/show/1157217
28
+
.. [1] https://lore.kernel.org/r/8734tqsrt7.fsf@meer.lwn.net/
29
+
.. [2] https://lore.kernel.org/r/1708585803.600323099@f111.i.mail.ru/
30
+
.. [3] https://en.wikipedia.org/wiki/Variable_font
31
+
.. [4] https://fedoraproject.org/wiki/Changes/Noto_CJK_Variable_Fonts
32
+
.. [5] https://build.opensuse.org/request/show/1157217
35
33
36
-
#===========================================================================
37
34
Workarounds for building translations.pdf
38
-
#===========================================================================
35
+
-----------------------------------------
39
36
40
37
* Denylist "variable font" Noto CJK fonts.
38
+
41
39
- Create $HOME/deny-vf/fontconfig/fonts.conf from template below, with
42
40
tweaks if necessary. Remove leading "".
41
+
43
42
- Path of fontconfig/fonts.conf can be overridden by setting an env
44
43
variable FONTS_CONF_DENY_VF.
45
44
46
-
* Template:
47
-
-----------------------------------------------------------------
48
-
<?xml version="1.0"?>
49
-
<!DOCTYPE fontconfig SYSTEM "urn:fontconfig:fonts.dtd">
50
-
<fontconfig>
51
-
<!--
52
-
Ignore variable-font glob (not to break xetex)
53
-
-->
54
-
<selectfont>
55
-
<rejectfont>
56
-
<!--
57
-
for Fedora
58
-
-->
59
-
<glob>/usr/share/fonts/google-noto-*-cjk-vf-fonts</glob>
60
-
<!--
61
-
for openSUSE tumbleweed
62
-
-->
63
-
<glob>/usr/share/fonts/truetype/Noto*CJK*-VF.otf</glob>
64
-
</rejectfont>
65
-
</selectfont>
66
-
</fontconfig>
67
-
-----------------------------------------------------------------
45
+
* Template::
46
+
47
+
<?xml version="1.0"?>
48
+
<!DOCTYPE fontconfig SYSTEM "urn:fontconfig:fonts.dtd">
49
+
<fontconfig>
50
+
<!--
51
+
Ignore variable-font glob (not to break xetex)
52
+
-->
53
+
<selectfont>
54
+
<rejectfont>
55
+
<!--
56
+
for Fedora
57
+
-->
58
+
<glob>/usr/share/fonts/google-noto-*-cjk-vf-fonts</glob>
59
+
<!--
60
+
for openSUSE tumbleweed
61
+
-->
62
+
<glob>/usr/share/fonts/truetype/Noto*CJK*-VF.otf</glob>
63
+
</rejectfont>
64
+
</selectfont>
65
+
</fontconfig>
68
66
69
67
The denylisting is activated for "make pdfdocs".
70
68
71
69
* For skipping CJK pages in PDF
70
+
72
71
- Uninstall texlive-xecjk.
73
72
Denylisting is not needed in this case.
74
73
75
74
* For printing CJK pages in PDF
75
+
76
76
- Need non-variable "Noto CJK" fonts.
77
+
77
78
* Fedora
79
+
78
80
- google-noto-sans-cjk-fonts
79
81
- google-noto-serif-cjk-fonts
82
+
80
83
* openSUSE tumbleweed
84
+
81
85
- Non-variable "Noto CJK" fonts are not available as distro packages
82
86
as of April, 2024. Fetch a set of font files from upstream Noto
83
87
CJK Font released at:
88
+
84
89
https://github.com/notofonts/noto-cjk/tree/main/Sans#super-otc
90
+
85
91
and at:
92
+
86
93
https://github.com/notofonts/noto-cjk/tree/main/Serif#super-otc
87
-
, then uncompress and deploy them.
94
+
95
+
then uncompress and deploy them.
88
96
- Remember to update fontconfig cache by running fc-cache.
89
97
90
-
!!! Caution !!!
98
+
.. caution::
91
99
Uninstalling "variable font" packages can be dangerous.
92
100
They might be depended upon by other packages important for your work.
93
101
Denylisting should be less invasive, as it is effective only while
···
125
115
self.re_cjk = re.compile(r"([^:]+):\s*Noto\s+(Sans|Sans Mono|Serif) CJK")
126
116
127
117
def description(self):
118
+
"""
119
+
Returns module description.
120
+
"""
128
121
return __doc__
129
122
130
123
def get_noto_cjk_vf_fonts(self):
131
-
"""Get Noto CJK fonts"""
124
+
"""
125
+
Get Noto CJK fonts.
126
+
"""
132
127
133
128
cjk_fonts = set()
134
129
cmd = ["fc-list", ":", "file", "family", "variable"]
···
158
143
return sorted(cjk_fonts)
159
144
160
145
def check(self):
161
-
"""Check for problems with CJK fonts"""
146
+
"""
147
+
Check for problems with CJK fonts.
148
+
"""
162
149
163
150
fonts = textwrap.indent("\n".join(self.get_noto_cjk_vf_fonts()), " ")
164
151
if not fonts: