| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-ID: <b4c81d64-b605-4b0a-9d99-fec55a1e0514@gmail.com>
Date: Wed, 6 Aug 2025 12:13:15 +0900
From: Akira Yokosawa <akiyks@...il.com>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc: Jonathan Corbet <corbet@....net>,
Linux Doc Mailing List <linux-doc@...r.kernel.org>,
linux-kernel@...r.kernel.org, Sai Vishnu M <saivishnu725@...il.com>,
Akira Yokosawa <akiyks@...il.com>
Subject: Re: [PATCH 00/15] Translate sphinx-pre-install to Python
Hi,
On Thu, 31 Jul 2025 13:51:07 +0200, Mauro Carvalho Chehab wrote:
> Em Tue, 8 Jul 2025 23:56:01 +0900
> Akira Yokosawa <akiyks@...il.com> escreveu:
>
>> I've been ignoring sphinx-pre-install all these years, but the impressive
>> test results presented in this cover-letter made me test it.
>
> I'm now working to fix PDF generation, assuming that all packages from
> sphinx-pre-install are installed.
>
> I'm placing the patches on my scratch tree at:
> https://github.com/mchehab/linux/tree/my-docs-next
>
> It contains several branches merged there in sequence:
> - elder_python_v1: makes kernel-doc run with elder kernels (2 patches);
> - netlink_v10: patches adding an yaml parser for netlink (14 patches);
> - sphinx-pre-install-v4: current version of this series (39 patches);
> - pdfdocs: specific fixes for PDF doc generation (11 patches);
> - sphinx-build-wrapper: a new script with a large cleanup at docs Makefile
> (7 patches)
Sorry, but I've not looked into those branches.
[...]
> So, at least for me, it seems that the changes will be fixing
> lots of existing issues.
>
> Btw, one of the problem with PDFs is that the existing logic
> doesn't really report success/failures for each PDF target.
> That's why I ended writing a wrapper (sphinx-build-wrapper) with
> checks the results. As a side effect, docs Makefile is now in
> sane state.
I might be interested in seeing the docs Makefile updates.
>
> Thanks,
> Mauro
>
> ---
[...]
> Summary
> =======
> PASSED - AlmaLinux release 9.6 (Sage Margay) (7 tests)
> PASSED - Amazon Linux release 2023 (Amazon Linux) (7 tests)
> PASSED - Arch Linux (7 tests)
> PASSED - CentOS Stream release 9 (7 tests)
> PARTIAL - Debian GNU/Linux 12 (7 tests)
> PARTIAL - Devuan GNU/Linux 5 (7 tests)
> PASSED - Fedora release 42 (Adams) (7 tests)
> PARTIAL - Gentoo Base System release 2.17 (7 tests)
> PASSED - Kali GNU/Linux 2025.2 (7 tests)
> PASSED - Mageia 9 (7 tests)
> PARTIAL - Linux Mint 22 (7 tests)
> PARTIAL - openEuler release 25.03 (7 tests)
> PARTIAL - OpenMandriva Lx 4.0 (7 tests)
> PASSED - openSUSE Leap 15.6 (7 tests)
> PASSED - openSUSE Tumbleweed (7 tests)
> PASSED - Oracle Linux Server release 9.6 (7 tests)
> FAILED - Red Hat Enterprise Linux release 8.10 (Ootpa) (7 tests)
> FAILED - rockylinux8 (1 tests)
> PASSED - Rocky Linux release 9.6 (Blue Onyx) (7 tests)
> FAILED - Springdale Open Enterprise Linux release 9.2 (Parma) (7 tests)
> PASSED - Ubuntu 24.04.2 LTS (7 tests)
> PASSED - Ubuntu 25.04 (7 tests)
Here is a summary I have made based on my own tests against limited list of
distros. I'm still ignoring sphinx_pre_install.
-----------------------------------------------------------------------
* TL;DR
Setting up a tool for SVG --> PDF conversion and CJK fonts properly for
"make latexdocs" and "make pdfdocs" is sometimes tricky.
Summary table as of 2025/08/02 WRT distro packages installed as they are:
[legends]
pdf & img: pdfdocs with ImageMagick + rsvg-convert; w/o CJK fonts
pdf & ink: pdfdocs with Inkscape; w/o CJK fonts
pdf & cjk: pdfdocs with either ImageMagick or Inkscape; with CJK fonts
========================================================================
pdf
-----------------
distro python3 sphinx html img ink cjk notes
=================== ======= ======= ===== ===== ===== ===== =========
debian:bullseye 3.9.2 3.4.3 PASS FAIL PASS PASS [*0]
debian:bookworm 3.11.2 5.3.0 PASS FAIL PASS PASS [*0]
debian:trixie 3.13.5 8.1.3 PASS FAIL PASS PASS [*6]
ubuntu:jammy 3.10.6 4.3.2 PASS FAIL PASS PASS [*0]
ubuntu:noble 3.12.3 7.2.6 PASS FAIL PASS PASS [*6]
ubuntu:plucky 3.13.3 8.1.3 PASS FAIL PASS PASS [*6]
almalinux:9 3.9.21 3.4.3 PASS PASS PASS PASS
almalinux:10 3.12.9 7.2.6 PASS PASS --- FAIL [*1]
fedora:42 3.13.5 8.1.3 PASS PASS PASS PASS [*2]
opensuse/leap:15.6 3.11.9 7.2.6 PASS PASS FAIL FAIL [*3]
mageia:9 3.10.11 6.1.3 PASS PASS PASS PASS [*4]
opensuse/tumbleweed 3.13.5 8.2.3 PASS PASS PASS FAIL [*5]
archlinux 3.13.5 8.2.3 PASS PASS PASS PASS
=================== ======= ======= ===== ===== ===== ===== ==========
"FAIL" means several situations, most of which can be worked around by
manual intervention after installing distro packages:
(1) error/warning in "make latexdocs"
(1-a) due to some issues in distro package that is not up-to-date
(1-b) convert(1) of ImageMagick doesn't generate PDFs with the warning:
WARNING: Warning msg from convert(1): convert: attempt to perform an
operation not allowed by the security policy `PDF' ...
(1-c) Incompatibility of newly added SVG figures with avalable
SVG --> PDF converters:
(1-c1) covert(1) + rsvg-convert(1)
(1-c2) inkscape(1)
(2) error in "make pdfdocs"
(2-a) (1-b) or (1-c) can cause "LaTeX Warning: Float too large for page
by <huge>pt" and ends up in the fatal error of xelatex:
"! TeX capacity exceeded, sorry [main memory size=5000000]"
(2-b) (1-b) or (1-c) can cause xelatex to error-exit without leaving
any hint in the .log file.
(3) CJK pages can't be rendered
(3-a) due to missing *static* Noto CJK fonts in distro packages
Notes
=====
[*0] ImageMagick is not allowed to generate PDFs in Debian and its
derivative releases prior to ubuntu:noble.
[*1] An issue in cairo prevents a DOT diagram in a CJK page to be converted
into PDF ("dot -Tpdf" crash; known issue with cairo-1.18.2-2.el10).
Inkscape is not in EPEL 10. Use of flatpak is recommended for GUI apps,
but flatpak apps don't see font setups of hosts by default.
Serif shape Static Noto CJK fonts are not provided as distro packages.
[*2] Due to a xelatex & fontspec limitation, if you have variable Noto CJK
fonts installed, they need to be deny-listed for building PDF docs
with CJK fonts.
[*3] Sphinx 7.2.6 is provided as python311-Sphinx.
Inkscape 1.0.1 crashes against figures drawn with Inkscape 1.4.x.
Noto CJK fonts are not provided as distro packages.
[*4] When Inkscape is available, their parallel runs under Gnome desktop
can cause emergency saves of SVG files. This issue can be worked
around by, e.g., building under a text-only session or a non-Gnome
desktop.
[*5] Static Noto CJK fonts are not provided as distro packages.
Even if they are manually installed from Google fonts manually,
deny-listing distro-provided variable ones is required for CJK pages.
[*6] convert(1) + rsvg_convert(1) doesn't work well with some SVG files
under recent debian and its derivatives. Incomplete list of examples:
- Documentation/gpu/pipe_and_queue_abstraction.svg:
convert: unrecognized color `context-stroke' @ warning/color.c/GetColorCompliance/1057.
convert: non-conforming drawing primitive definition `fill' @ error/draw.c/RenderMVGContent/4456.
- Documentation/userspace-api/media/v4l/selection.svg:
convert: unrecognized color `dt' @ warning/color.c/GetColorCompliance/1064.
convert: non-conforming drawing primitive definition `fill' @ error/draw.c/RenderMVGContent/4548.
convert: unrecognized color `w' @ warning/color.c/GetColorCompliance/1064.
convert: unrecognized color `dt' @ warning/color.c/GetColorCompliance/1064.
convert: unrecognized color `w' @ warning/color.c/GetColorCompliance/1064.
[about almalinux:8]
There is a package python3.11, but there is no accompanying package
for virtualenv in official EL 8 repos. It might be possible to install
python3.11 as well as accompanying pip and pyyaml, and install modern
Sphinx by non-venv pip. This might be feasible, e.g., in containerized
setups.
On top of almalinux:8, as far as I could test, xelatex & fontspec
can't discover fonts by its names such as "DejaVu Sans".
-----------------------------------------------------------------------
Thanks, Akira
Powered by blists - more mailing lists