Hi Jon,
Heh, with all those scripts and hacks that were accumulated with time
for docs makefile, placing them there with absolutely no documentation,
I ended missing scripts/check-variable-fonts.sh.
I only realized today when searching for the "|| exit" hack we added
in 2017 to fix an issue where make pdfdocs were always returning
errors (again, not documented).
This series comes after(*):
https://lore.kernel.org/linux-doc/cover.1757677427.git.mchehab+huawei@xxxxxxxxxx/T/#t
(*) I should probably have named such series as:
"Move the trick-or-treat build hacks accumulated over time into a single place and document them."
This specific script is called only when PDF build fails. Re-add
it at sphinx-build-wrapper logic. After it, problematic PDF
builds will warn again about possible issues with CJK variable
fonts:
$ make SPHINXDIRS=translations pdfdocs
Summary
=======
translations: FAILED
=============================================================================
XeTeX is confused by "variable font" files listed below:
/usr/share/fonts/google-noto-sans-cjk-vf-fonts/NotoSansCJK-VF.ttc
/usr/share/fonts/google-noto-sans-mono-cjk-vf-fonts/NotoSansMonoCJK-VF.ttc
/usr/share/fonts/google-noto-serif-cjk-vf-fonts/NotoSerifCJK-VF.ttc
For CJK pages in PDF, they need to be hidden from XeTeX by denylisting.
Or, CJK pages can be skipped by uninstalling texlive-xecjk.
For more info on denylisting, other options, and variable font, see header
comments of tools/docs/lib/latex_fonts.py.
=============================================================================
PDF build failed: not all PDF files were created.
make[2]: *** [Documentation/Makefile:58: pdfdocs] Error 1
make[1]: *** [/new_devel/docs/Makefile:1806: pdfdocs] Error 2
make: *** [Makefile:248: __sub-make] Error 2
The output message is identical, except that it now uses __file__ to get the
actual location of the verify code (which is now part of a docs lib).
All comments from the original code were preserved, but I opted to use
python docstring to store it. This way, we may even add something like
print(__doc__) in the future, if needed.
I also opted to preserve a command-line interface, which does nothing but
call the check function:
$ ./tools/docs/check-variable-fonts.py
=============================================================================
XeTeX is confused by "variable font" files listed below:
/usr/share/fonts/google-noto-sans-cjk-vf-fonts/NotoSansCJK-VF.ttc
/usr/share/fonts/google-noto-sans-mono-cjk-vf-fonts/NotoSansMonoCJK-VF.ttc
/usr/share/fonts/google-noto-serif-cjk-vf-fonts/NotoSerifCJK-VF.ttc
For CJK pages in PDF, they need to be hidden from XeTeX by denylisting.
Or, CJK pages can be skipped by uninstalling texlive-xecjk.
For more info on denylisting, other options, and variable font, see header
comments of tools/docs/lib/latex_fonts.py.
=============================================================================
I opted to place it into a class, as we can one day add more functions there,
for instance to create the proposed XML file under ~/deny-vc, as the script's
documentation proposes.
By using a class, we only need to import the class: all functions from
such class are automatically imported altogether. Plus, we don't have to
deal with namespaces for a function called "check()".
Mauro Carvalho Chehab (3):
scripts/check-variable-fonts.sh: convert to Python
scripts: check-variable-fonts.py: split into a lib and an exec file
tools/docs: sphinx-build-wrapper: warn about broken PDF fonts
MAINTAINERS | 1 -
scripts/check-variable-fonts.sh | 115 --------------------
tools/docs/check-variable-fonts.py | 23 ++++
tools/docs/lib/latex_fonts.py | 162 +++++++++++++++++++++++++++++
tools/docs/sphinx-build-wrapper | 9 +-
5 files changed, 192 insertions(+), 118 deletions(-)
delete mode 100755 scripts/check-variable-fonts.sh
create mode 100755 tools/docs/check-variable-fonts.py
create mode 100755 tools/docs/lib/latex_fonts.py
--
2.50.1
