From 886f6cac31cb2072ee79fe3009b7a89cea960ac7 Mon Sep 17 00:00:00 2001 From: Li Hua Date: Tue, 26 Mar 2024 18:45:15 +0800 Subject: scripts/sphinx-pre-install: fix Arch xelatex dependency On Arch Linux, xelatex is installed in the texlive-xetex package. Signed-off-by: Li Hua Link: https://lore.kernel.org/r/20240326104515.40346-1-lihua@email.com Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 4c781617ffe6..c559e43b2230 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -560,7 +560,7 @@ sub give_arch_linux_hints() "virtualenv" => "python-virtualenv", "dot" => "graphviz", "convert" => "imagemagick", - "xelatex" => "texlive-bin", + "xelatex" => "texlive-xetex", "latexmk" => "texlive-core", "rsvg-convert" => "extra/librsvg", ); -- cgit v1.3.1 From 1cbd16e3c125f34bef481ea048ec59bf24f1cbf4 Mon Sep 17 00:00:00 2001 From: Thorsten Blum Date: Sat, 23 Mar 2024 13:58:38 +0100 Subject: scripts: sphinx-pre-install: Add pyyaml hint to other distros Extend commit 84b4cc8189f2 ("docs: scripts: sphinx-pre-install: Fix building docs with pyyaml package") and add pyyaml as an optional package to Mageia, ArchLinux, and Gentoo. The Python module pyyaml is required to build the docs, but it is only listed in Documentation/sphinx/requirements.txt and is therefore missing when Sphinx is installed as a package and not via pip/pypi. Signed-off-by: Thorsten Blum Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240323125837.2022-2-thorsten.blum@toblux.com --- scripts/sphinx-pre-install | 3 +++ 1 file changed, 3 insertions(+) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index c559e43b2230..c1121f098542 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -514,6 +514,7 @@ sub give_mageia_hints() { my %map = ( "python-sphinx" => "python3-sphinx", + "yaml" => "python3-yaml", "virtualenv" => "python3-virtualenv", "dot" => "graphviz", "convert" => "ImageMagick", @@ -557,6 +558,7 @@ sub give_mageia_hints() sub give_arch_linux_hints() { my %map = ( + "yaml" => "python-yaml", "virtualenv" => "python-virtualenv", "dot" => "graphviz", "convert" => "imagemagick", @@ -587,6 +589,7 @@ sub give_arch_linux_hints() sub give_gentoo_hints() { my %map = ( + "yaml" => "dev-python/pyyaml", "virtualenv" => "dev-python/virtualenv", "dot" => "media-gfx/graphviz", "convert" => "media-gfx/imagemagick", -- cgit v1.3.1 From 1e596d5eff3ddbaf2c5446adcc999b2516949556 Mon Sep 17 00:00:00 2001 From: Akira Yokosawa Date: Sat, 6 Apr 2024 11:04:16 +0900 Subject: docs: Detect variable fonts and suggest denylisting them MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Link: https://lore.kernel.org/r/8734tqsrt7.fsf@meer.lwn.net/ Reported-by: Иван Иванович Link: https://lore.kernel.org/linux-doc/1708585803.600323099@f111.i.mail.ru/ Cc: Randy Dunlap Signed-off-by: Akira Yokosawa Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240406020416.25096-1-akiyks@gmail.com --- Documentation/Makefile | 7 +- Documentation/sphinx/kerneldoc-preamble.sty | 9 ++- MAINTAINERS | 1 + scripts/check-variable-fonts.sh | 117 ++++++++++++++++++++++++++++ 4 files changed, 129 insertions(+), 5 deletions(-) create mode 100755 scripts/check-variable-fonts.sh (limited to 'scripts') 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 -- cgit v1.3.1 From 5f8e4007c10d8f7a0f28be8a7894eb7712d0b111 Mon Sep 17 00:00:00 2001 From: Kees Cook Date: Thu, 11 Apr 2024 11:32:08 +0200 Subject: kernel-doc: fix struct_group_tagged() parsing kernel-doc emits a warning on struct_group_tagged() if you describe your struct group member: include/net/libeth/rx.h:69: warning: Excess struct member 'fp' description in 'libeth_fq' The code: /** * struct libeth_fq - structure representing a buffer queue * @fp: hotpath part of the structure * @pp: &page_pool for buffer management [...] */ struct libeth_fq { struct_group_tagged(libeth_fq_fp, fp, struct page_pool *pp; [...] ); When a struct_group_tagged() is encountered, we need to build a `struct TAG NAME;` from it, so that it will be treated as a valid embedded struct. Decouple the regex and do the replacement there. As far as I can see, this doesn't produce any new warnings on the current mainline tree. Reported-by: Jakub Kicinski Closes: https://lore.kernel.org/netdev/20240405212513.0d189968@kernel.org Fixes: 50d7bd38c3aa ("stddef: Introduce struct_group() helper macro") Signed-off-by: Kees Cook Co-developed-by: Alexander Lobakin Signed-off-by: Alexander Lobakin Reviewed-by: Przemek Kitszel Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240411093208.2483580-1-aleksander.lobakin@intel.com --- scripts/kernel-doc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index cb1be22afc65..438dfe76b989 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1151,7 +1151,8 @@ sub dump_struct($$) { # - first eat non-declaration parameters and rewrite for final match # - then remove macro, outer parens, and trailing semicolon $members =~ s/\bstruct_group\s*\(([^,]*,)/STRUCT_GROUP(/gos; - $members =~ s/\bstruct_group_(attr|tagged)\s*\(([^,]*,){2}/STRUCT_GROUP(/gos; + $members =~ s/\bstruct_group_attr\s*\(([^,]*,){2}/STRUCT_GROUP(/gos; + $members =~ s/\bstruct_group_tagged\s*\(([^,]*),([^,]*),/struct $1 $2; STRUCT_GROUP(/gos; $members =~ s/\b__struct_group\s*\(([^,]*,){3}/STRUCT_GROUP(/gos; $members =~ s/\bSTRUCT_GROUP(\(((?:(?>[^)(]+)|(?1))*)\))[^;]*;/$2/gos; -- cgit v1.3.1 From 5384258f4ef0c27cc9d5255ce4992f13656e215d Mon Sep 17 00:00:00 2001 From: Akira Yokosawa Date: Sat, 27 Apr 2024 17:24:11 +0900 Subject: docs: scripts/check-variable-fonts.sh: Improve commands for detection As mentioned in "Assumption:", current grep expression can't catch font files whose names are changed from upstream "Noto CJK fonts". To avoid false negatives, use command of the form: fc-list : file family variable , where ":" works as a wildcard pattern. Variable fonts can be detected by filtering the output with "variable=True" and "Noto CJK" font-family variants. Signed-off-by: Akira Yokosawa Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/c62ba2e6-c124-4e91-8011-cb1da408a3c5@gmail.com --- scripts/check-variable-fonts.sh | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) (limited to 'scripts') diff --git a/scripts/check-variable-fonts.sh b/scripts/check-variable-fonts.sh index 12765e54e4f3..ce63f0acea5f 100755 --- a/scripts/check-variable-fonts.sh +++ b/scripts/check-variable-fonts.sh @@ -20,10 +20,6 @@ # 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/ @@ -96,13 +92,15 @@ 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` +notocjkvffonts=`fc-list : file family variable | \ + grep 'variable=True' | \ + grep -E -e 'Noto (Sans|Sans Mono|Serif) CJK' | \ + sed -e 's/^/ /' -e 's/: Noto S.*$//' | sort | uniq` -if [ "x$vffonts" != "x" ] ; then +if [ "x$notocjkvffonts" != "x" ] ; then echo '=============================================================================' echo 'XeTeX is confused by "variable font" files listed below:' - echo "$vffonts" + echo "$notocjkvffonts" 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.' -- cgit v1.3.1 From d3dedad43a999810e3bc7fc7db552e2cb9a218fa Mon Sep 17 00:00:00 2001 From: Utkarsh Tripathi Date: Fri, 3 May 2024 23:56:50 +0530 Subject: kernel-doc: Added "*" in $type_constants2 to fix 'make htmldocs' warning. Fixed: WARNING: Inline literal start-string without end-string in Documentation/core-api/workqueue.rst Added "*" in $type_constants2 in kernel-doc script to include "*" in the conversion to hightlights. Previously: %WQ_* --> ``WQ_``* After Changes: %WQ_* --> ``WQ_*`` Need for the fix: ``* is not recognized as a valid end-string for inline literal. Link: https://lore.kernel.org/linux-doc/640114d2-5780-48c3-a294-c0eba230f984@gmail.com Signed-off-by: Utkarsh Tripathi Suggested-by: Akira Yokosawa Reviewed-by: Akira Yokosawa Link: https://lore.kernel.org/r/20240503182650.7761-1-utripathi2002@gmail.com Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 438dfe76b989..7962d0daa638 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -62,7 +62,7 @@ my $anon_struct_union = 0; # match expressions used to find embedded type information my $type_constant = '\b``([^\`]+)``\b'; -my $type_constant2 = '\%([-_\w]+)'; +my $type_constant2 = '\%([-_*\w]+)'; my $type_func = '(\w+)\(\)'; my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)'; my $type_param_ref = '([\!~\*]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)'; -- cgit v1.3.1