diff --git a/Documentation/Makefile b/Documentation/Makefile index b68f8c816897..a961692baa12 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -28,6 +28,10 @@ BUILDDIR = $(obj)/output PDFLATEX = xelatex LATEXOPTS = -interaction=batchmode -no-shell-escape +# For denylisting "variable font" files +# Can be overridden by setting as an env variable +FONTS_CONF_DENY_VF ?= $(HOME)/deny-vf + ifeq ($(findstring 1, $(KBUILD_VERBOSE)),) SPHINXOPTS += "-q" endif @@ -151,10 +155,11 @@ pdfdocs: else # HAVE_PDFLATEX +pdfdocs: DENY_VF = XDG_CONFIG_HOME=$(FONTS_CONF_DENY_VF) pdfdocs: latexdocs @$(srctree)/scripts/sphinx-pre-install --version-check $(foreach var,$(SPHINXDIRS), \ - $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit; \ + $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" $(DENY_VF) -C $(BUILDDIR)/$(var)/latex || sh $(srctree)/scripts/check-variable-fonts.sh || exit; \ mkdir -p $(BUILDDIR)/$(var)/pdf; \ mv $(subst .tex,.pdf,$(wildcard $(BUILDDIR)/$(var)/latex/*.tex)) $(BUILDDIR)/$(var)/pdf/; \ ) diff --git a/Documentation/sphinx/kerneldoc-preamble.sty b/Documentation/sphinx/kerneldoc-preamble.sty index 3092df051c95..d479cfa73658 100644 --- a/Documentation/sphinx/kerneldoc-preamble.sty +++ b/Documentation/sphinx/kerneldoc-preamble.sty @@ -215,11 +215,12 @@ due to the lack of suitable font families and/or the texlive-xecjk package. - If you want them, please install ``Noto Sans CJK'' font families - along with the texlive-xecjk package by following instructions from + If you want them, please install non-variable ``Noto Sans CJK'' + font families along with the texlive-xecjk package by following + instructions from \sphinxcode{./scripts/sphinx-pre-install}. - Having optional ``Noto Serif CJK'' font families will improve - the looks of those translations. + Having optional non-variable ``Noto Serif CJK'' font families will + improve the looks of those translations. \end{sphinxadmonition}} \newcommand{\kerneldocEndSC}{} \newcommand{\kerneldocBeginTC}[1]{} diff --git a/MAINTAINERS b/MAINTAINERS index aa3b947fb080..3a4768c2f712 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -6406,6 +6406,7 @@ S: Maintained P: Documentation/doc-guide/maintainer-profile.rst T: git git://git.lwn.net/linux.git docs-next F: Documentation/ +F: scripts/check-variable-font.sh F: scripts/documentation-file-ref-check F: scripts/kernel-doc F: scripts/sphinx-pre-install diff --git a/scripts/check-variable-fonts.sh b/scripts/check-variable-fonts.sh new file mode 100755 index 000000000000..12765e54e4f3 --- /dev/null +++ b/scripts/check-variable-fonts.sh @@ -0,0 +1,117 @@ +#!/bin/sh +# SPDX-License-Identifier: GPL-2.0-only +# Copyright (C) Akira Yokosawa, 2024 +# +# For "make pdfdocs", reports of build errors of translations.pdf started +# arriving early 2024 [1, 2]. It turned out that Fedora and openSUSE +# tumbleweed have started deploying variable-font [3] format of "Noto CJK" +# fonts [4, 5]. For PDF, a LaTeX package named xeCJK is used for CJK +# (Chinese, Japanese, Korean) pages. xeCJK requires XeLaTeX/XeTeX, which +# does not (and likely never will) understand variable fonts for historical +# reasons. +# +# The build error happens even when both of variable- and non-variable-format +# fonts are found on the build system. To make matters worse, Fedora enlists +# variable "Noto CJK" fonts in the requirements of langpacks-ja, -ko, -zh_CN, +# -zh_TW, etc. Hence developers who have interest in CJK pages are more +# likely to encounter the build errors. +# +# This script is invoked from the error path of "make pdfdocs" and emits +# suggestions if variable-font files of "Noto CJK" fonts are in the list of +# fonts accessible from XeTeX. +# +# Assumption: +# File names are not modified from those of upstream Noto CJK fonts: +# https://github.com/notofonts/noto-cjk/ +# +# References: +# [1]: https://lore.kernel.org/r/8734tqsrt7.fsf@meer.lwn.net/ +# [2]: https://lore.kernel.org/r/1708585803.600323099@f111.i.mail.ru/ +# [3]: https://en.wikipedia.org/wiki/Variable_font +# [4]: https://fedoraproject.org/wiki/Changes/Noto_CJK_Variable_Fonts +# [5]: https://build.opensuse.org/request/show/1157217 +# +#=========================================================================== +# Workarounds for building translations.pdf +#=========================================================================== +# +# * Denylist "variable font" Noto CJK fonts. +# - Create $HOME/deny-vf/fontconfig/fonts.conf from template below, with +# tweaks if necessary. Remove leading "# ". +# - Path of fontconfig/fonts.conf can be overridden by setting an env +# variable FONTS_CONF_DENY_VF. +# +# * Template: +# ----------------------------------------------------------------- +# +# +# +# +# +# +# +# /usr/share/fonts/google-noto-*-cjk-vf-fonts +# +# /usr/share/fonts/truetype/Noto*CJK*-VF.otf +# +# +# +# ----------------------------------------------------------------- +# +# The denylisting is activated for "make pdfdocs". +# +# * For skipping CJK pages in PDF +# - Uninstall texlive-xecjk. +# Denylisting is not needed in this case. +# +# * For printing CJK pages in PDF +# - Need non-variable "Noto CJK" fonts. +# * Fedora +# - google-noto-sans-cjk-fonts +# - google-noto-serif-cjk-fonts +# * openSUSE tumbleweed +# - Non-variable "Noto CJK" fonts are not available as distro packages +# as of April, 2024. Fetch a set of font files from upstream Noto +# CJK Font released at: +# https://github.com/notofonts/noto-cjk/tree/main/Sans#super-otc +# and at: +# https://github.com/notofonts/noto-cjk/tree/main/Serif#super-otc +# , then uncompress and deploy them. +# - Remember to update fontconfig cache by running fc-cache. +# +# !!! Caution !!! +# Uninstalling "variable font" packages can be dangerous. +# They might be depended upon by other packages important for your work. +# Denylisting should be less invasive, as it is effective only while +# XeLaTeX runs in "make pdfdocs". + +# Default per-user fontconfig path (overridden by env variable) +: ${FONTS_CONF_DENY_VF:=$HOME/deny-vf} + +export XDG_CONFIG_HOME=${FONTS_CONF_DENY_VF} + +vffonts=`fc-list -b | grep -iE 'file: .*noto.*cjk.*-vf' | \ + sed -e 's/\tfile:/ file:/' -e 's/(s)$//' | sort | uniq` + +if [ "x$vffonts" != "x" ] ; then + echo '=============================================================================' + echo 'XeTeX is confused by "variable font" files listed below:' + echo "$vffonts" + echo + echo 'For CJK pages in PDF, they need to be hidden from XeTeX by denylisting.' + echo 'Or, CJK pages can be skipped by uninstalling texlive-xecjk.' + echo + echo 'For more info on denylisting, other options, and variable font, see header' + echo 'comments of scripts/check-variable-fonts.sh.' + echo '=============================================================================' +fi + +# As this script is invoked from Makefile's error path, always error exit +# regardless of whether any variable font is discovered or not. +exit 1