docs: Detect variable fonts and suggest denylisting them

Fedora and openSUSE has started deploying "variable font" [1] format
Noto CJK fonts [2, 3]. "CJK" here stands for "Chinese, Japanese,
and Korean".

Unfortunately, XeTeX/XeLaTeX doesn't understand those fonts for
historical reasons and builds of translations.pdf end up in errors
if such fonts are present on the build host.

To help developers work around the issue, add a script to check the
presence of "variable font" Noto CJK fonts and to emit suggestions.
The script is invoked in the error path of "make pdfdocs" so that the
suggestions are made only when a PDF build actually fails.

The first suggestion is to denylist those "variable font" files by
activating a per-user and command-local fontconfig setting.

For further info and backgrounds, please refer to the header comment
of scripts/check-variable-font.sh newly added in this commit.

Link: [1] https://en.wikipedia.org/wiki/Variable_font
Link: [2] https://fedoraproject.org/wiki/Changes/Noto_CJK_Variable_Fonts
Link: [3] https://build.opensuse.org/request/show/1157217
Reported-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/8734tqsrt7.fsf@meer.lwn.net/
Reported-by: Иван Иванович <relect@bk.ru>
Link: https://lore.kernel.org/linux-doc/1708585803.600323099@f111.i.mail.ru/
Cc: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20240406020416.25096-1-akiyks@gmail.com

authored by

Akira Yokosawa and committed by

Jonathan Corbet 2 years ago 1e596d5e 9e192b39

+129 -5

4 changed files

expand all

Documentation

Makefile

sphinx

kerneldoc-preamble.sty

MAINTAINERS

scripts

check-variable-fonts.sh

+6 -1

Documentation/Makefile

··· 28 28 PDFLATEX = xelatex 29 29 LATEXOPTS = -interaction=batchmode -no-shell-escape 30 30 31 + # For denylisting "variable font" files 32 + # Can be overridden by setting as an env variable 33 + FONTS_CONF_DENY_VF ?= $(HOME)/deny-vf 34 + 31 35 ifeq ($(findstring 1, $(KBUILD_VERBOSE)),) 32 36 SPHINXOPTS += "-q" 33 37 endif ··· 155 151 156 152 else # HAVE_PDFLATEX 157 153 154 + pdfdocs: DENY_VF = XDG_CONFIG_HOME=$(FONTS_CONF_DENY_VF) 158 155 pdfdocs: latexdocs 159 156 @$(srctree)/scripts/sphinx-pre-install --version-check 160 157 $(foreach var,$(SPHINXDIRS), \ 161 - $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit; \ 158 + $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" $(DENY_VF) -C $(BUILDDIR)/$(var)/latex || sh $(srctree)/scripts/check-variable-fonts.sh || exit; \ 162 159 mkdir -p $(BUILDDIR)/$(var)/pdf; \ 163 160 mv $(subst .tex,.pdf,$(wildcard $(BUILDDIR)/$(var)/latex/*.tex)) $(BUILDDIR)/$(var)/pdf/; \ 164 161 )

+5 -4

Documentation/sphinx/kerneldoc-preamble.sty

··· 215 215 due to the lack of suitable font families and/or the texlive-xecjk 216 216 package. 217 217 218 - If you want them, please install ``Noto Sans CJK'' font families 219 - along with the texlive-xecjk package by following instructions from 218 + If you want them, please install non-variable ``Noto Sans CJK'' 219 + font families along with the texlive-xecjk package by following 220 + instructions from 220 221 \sphinxcode{./scripts/sphinx-pre-install}. 221 - Having optional ``Noto Serif CJK'' font families will improve 222 - the looks of those translations. 222 + Having optional non-variable ``Noto Serif CJK'' font families will 223 + improve the looks of those translations. 223 224 \end{sphinxadmonition}} 224 225 \newcommand{\kerneldocEndSC}{} 225 226 \newcommand{\kerneldocBeginTC}[1]{}

MAINTAINERS

··· 6406 6406 P: Documentation/doc-guide/maintainer-profile.rst 6407 6407 T: git git://git.lwn.net/linux.git docs-next 6408 6408 F: Documentation/ 6409 + F: scripts/check-variable-font.sh 6409 6410 F: scripts/documentation-file-ref-check 6410 6411 F: scripts/kernel-doc 6411 6412 F: scripts/sphinx-pre-install

+117

scripts/check-variable-fonts.sh

··· 1 + #!/bin/sh 2 + # SPDX-License-Identifier: GPL-2.0-only 3 + # Copyright (C) Akira Yokosawa, 2024 4 + # 5 + # For "make pdfdocs", reports of build errors of translations.pdf started 6 + # arriving early 2024 [1, 2]. It turned out that Fedora and openSUSE 7 + # tumbleweed have started deploying variable-font [3] format of "Noto CJK" 8 + # fonts [4, 5]. For PDF, a LaTeX package named xeCJK is used for CJK 9 + # (Chinese, Japanese, Korean) pages. xeCJK requires XeLaTeX/XeTeX, which 10 + # does not (and likely never will) understand variable fonts for historical 11 + # reasons. 12 + # 13 + # The build error happens even when both of variable- and non-variable-format 14 + # fonts are found on the build system. To make matters worse, Fedora enlists 15 + # variable "Noto CJK" fonts in the requirements of langpacks-ja, -ko, -zh_CN, 16 + # -zh_TW, etc. Hence developers who have interest in CJK pages are more 17 + # likely to encounter the build errors. 18 + # 19 + # This script is invoked from the error path of "make pdfdocs" and emits 20 + # suggestions if variable-font files of "Noto CJK" fonts are in the list of 21 + # fonts accessible from XeTeX. 22 + # 23 + # Assumption: 24 + # File names are not modified from those of upstream Noto CJK fonts: 25 + # https://github.com/notofonts/noto-cjk/ 26 + # 27 + # References: 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 33 + # 34 + #=========================================================================== 35 + # Workarounds for building translations.pdf 36 + #=========================================================================== 37 + # 38 + # * Denylist "variable font" Noto CJK fonts. 39 + # - Create $HOME/deny-vf/fontconfig/fonts.conf from template below, with 40 + # tweaks if necessary. Remove leading "# ". 41 + # - Path of fontconfig/fonts.conf can be overridden by setting an env 42 + # variable FONTS_CONF_DENY_VF. 43 + # 44 + # * Template: 45 + # ----------------------------------------------------------------- 46 + # <?xml version="1.0"?> 47 + # <!DOCTYPE fontconfig SYSTEM "urn:fontconfig:fonts.dtd"> 48 + # <fontconfig> 49 + #  52 + # <selectfont> 53 + # <rejectfont> 54 + #  57 + # <glob>/usr/share/fonts/google-noto-*-cjk-vf-fonts</glob> 58 + #  61 + # <glob>/usr/share/fonts/truetype/Noto*CJK*-VF.otf</glob> 62 + # </rejectfont> 63 + # </selectfont> 64 + # </fontconfig> 65 + # ----------------------------------------------------------------- 66 + # 67 + # The denylisting is activated for "make pdfdocs". 68 + # 69 + # * For skipping CJK pages in PDF 70 + # - Uninstall texlive-xecjk. 71 + # Denylisting is not needed in this case. 72 + # 73 + # * For printing CJK pages in PDF 74 + # - Need non-variable "Noto CJK" fonts. 75 + # * Fedora 76 + # - google-noto-sans-cjk-fonts 77 + # - google-noto-serif-cjk-fonts 78 + # * openSUSE tumbleweed 79 + # - Non-variable "Noto CJK" fonts are not available as distro packages 80 + # as of April, 2024. Fetch a set of font files from upstream Noto 81 + # CJK Font released at: 82 + # https://github.com/notofonts/noto-cjk/tree/main/Sans#super-otc 83 + # and at: 84 + # https://github.com/notofonts/noto-cjk/tree/main/Serif#super-otc 85 + # , then uncompress and deploy them. 86 + # - Remember to update fontconfig cache by running fc-cache. 87 + # 88 + # !!! Caution !!! 89 + # Uninstalling "variable font" packages can be dangerous. 90 + # They might be depended upon by other packages important for your work. 91 + # Denylisting should be less invasive, as it is effective only while 92 + # XeLaTeX runs in "make pdfdocs". 93 + 94 + # Default per-user fontconfig path (overridden by env variable) 95 + : ${FONTS_CONF_DENY_VF:=$HOME/deny-vf} 96 + 97 + export XDG_CONFIG_HOME=${FONTS_CONF_DENY_VF} 98 + 99 + vffonts=`fc-list -b | grep -iE 'file: .*noto.*cjk.*-vf' | \ 100 + sed -e 's/\tfile:/ file:/' -e 's/(s)$//' | sort | uniq` 101 + 102 + if [ "x$vffonts" != "x" ] ; then 103 + echo '=============================================================================' 104 + echo 'XeTeX is confused by "variable font" files listed below:' 105 + echo "$vffonts" 106 + echo 107 + echo 'For CJK pages in PDF, they need to be hidden from XeTeX by denylisting.' 108 + echo 'Or, CJK pages can be skipped by uninstalling texlive-xecjk.' 109 + echo 110 + echo 'For more info on denylisting, other options, and variable font, see header' 111 + echo 'comments of scripts/check-variable-fonts.sh.' 112 + echo '=============================================================================' 113 + fi 114 + 115 + # As this script is invoked from Makefile's error path, always error exit 116 + # regardless of whether any variable font is discovered or not. 117 + exit 1

Configure Feed

Configure Feed