docs: shim inkscape -> rsvg-convert in docs build (fixes #4040)#4043
Conversation
dblatex hardcodes 'inkscape -D --export-filename=OUT IN' for SVG conversion, which spams the build log with Pango/GtkRecentManager warnings on headless runs (issue LinuxCNC#4040). Drop a small shim named 'inkscape' in scripts/ (already on the docs build PATH per docs/src/Submakefile:7) that translates the dblatex call into rsvg-convert. Falls back to the real inkscape if args do not match the expected pattern, if rsvg-convert is missing, or if LINUXCNC_DOCS_NO_RSVG=1 is set. Add librsvg2-bin to DOC_DEPENDS; inkscape stays as fallback. Measured: Master_Documentation PDF build 51.5s -> 46.8s (9%), zero pixel diff across all 1055 pages. Per-SVG conversion ~6x faster in isolation.
|
On CI:
This is an example of where it happens: |
CI runners on debian bookworm/trixie/sid use an older dblatex variant
that invokes inkscape with the 0.x syntax:
inkscape -z -D --export-png=OUT IN
inkscape -z -D --export-pdf=OUT IN
inkscape -z -D --export-eps=OUT IN
The shim only matched the 1.x --export-filename= form, so on those
runners every call fell through to the real Inkscape and the
GtkRecentManager warnings persisted.
Accept -z and --without-gui as no-ops, parse --export-{png,pdf,eps}=
with explicit format, and keep extension inference for the 1.x form.
|
Good catch. CI runners use older dblatex that invokes Inkscape 0.x syntax: My shim only matched the 1.x Pushed 0e99880: accept Re-running CI should now hit rsvg-convert on all three debian flavors. |
|
package-indep (debian:sid) and (debian:trixie): |
git index had mode 100644 from initial commit (core.fileMode=false locally masked the +x bit). On CI the file was checked out as non-executable and inkscape calls fell through to /usr/bin/inkscape on every system, leaving the warnings in place. Set the executable bit in the index.
|
Root cause for the persistent warnings: shim was committed with mode 100644 ( Pushed c1b2cc7: Also reviewing the arm bookworm failure now. |
|
ARM bookworm fail is unrelated: Waiting on the new CI run with the executable-bit fix. |
|
No more inkscape warnings, all green 💪 |
|
And three times 4000+ fewer junk lines. |
|
It's a pity we can't patch dblatex instead, inserting a shim/emulator is cunning, but possibly confusing in the future. |
|
On Fedora with package dblatex-0.3.12-28.fc43.noarch it already uses rsvg-convert and no longer takes to inkscape. On Trixie it is dblatex 0.3.12py3-5 (file /usr/lib/python3/dist-packages/dbtexmf/core/imagedata.py) and it uses inkscape. So it probably got patched in the RPM build. |
|
Patching dblatex would just prop up an unmaintained stack (asciidoc-py is dead upstream, dblatex is niche, the XSL to LaTeX pipeline is dead weight). asciidoctor + asciidoctor-pdf looks like the obvious target: actively maintained, near drop-in for the source, prawn-svg renders SVG natively (no Inkscape, no LaTeX, no XSL). Has this already been discussed, or is a different docs-toolchain direction already on the cards? |
|
We actually need to drop the ...TeX build step completely. There have been several discussions already that the docs need "fixing", but it is a huge undertaking (and complicated by the translations). Fixing the docs is not going to be easy nor pretty in the short run and may trip on a few toes in the process too. |
Some time ago I tried that but it turned out that all the internal adoc references need to have a relative path like this: - * the <<cha:hal-introduction,Hardware Abstraction Layer>> (HAL), which provides a method of linking all
+ * the <<hal/intro.adoc#cha:hal-introduction,Hardware Abstraction Layer>> (HAL), which provides a method of linking allSo it got stuck somewhere writing a script to convert the references, see here: |
4 participants
Summary
dblatexhardcodesinkscape -D --export-filename=OUT INfor SVG conversion, which floods the build log withPango/GtkRecentManagerwarnings on headless runs (#4040).Drops a small bash shim named
inkscapeinscripts/(already on the docs build PATH via docs/src/Submakefile:7) that translates the dblatex call intorsvg-convert. No changes to dblatex, a2x, or any Makefile recipe.The shim is fail-safe and falls back to the real
inkscapewhen:rsvg-convertis missing,LINUXCNC_DOCS_NO_RSVG=1is set.librsvg2-binadded toDOC_DEPENDS.inkscapestays in the list as the fallback dependency.Measured
Test plan
make pdfdocscompletes withoutFailed to wrap object/PangoFT2FontMap/GtkRecentManagerwarnings.LINUXCNC_DOCS_NO_RSVG=1 make pdfdocsstill works (fallback path).scripts/inkscape --versionreturns the real Inkscape version (unknown-args passthrough).