Re: [PATCH v2 0/4] docs: sphinx/kfigure.py: Improve conversion to PDF

[Mauro Carvalho Chehab]

Em Fri, 7 Jan 2022 22:45:47 +0900
Akira Yokosawa <akiyks@xxxxxxxxx> escreveu:

> On Wed, 29 Dec 2021 20:42:00 +0900, Akira Yokosawa wrote:
> > This patch set improves conversions of DOT -> PDF and SVG -> PDF
> > for PDF docs.  
> 
> Gentle ping.
> 
> Mauro, any comments?

Sorry, have been busy those days with not much time to test it,
and I'm not expecting any time to test it on the next couple of
weeks.

The main concern from my last review is that inkscape is too noisy 
(well, frankly, textlive is also too noisy). If this was solved
on a nice way, and provided that the output files on both html and
pdf are working fine with those conversions, I don't have any 
objections to this series.

Regards,
Mauro

> 
> > 
> > * DOT -> PDF conversion
> > 
> > Current scheme uses "dot -Tpdf" (of graphviz).
> > 
> > Cons:
> >   - openSUSE's dot(1) does not support -Tpdf.
> >   - Other distro's dot(1) generates PDFs with unnecessarily wide
> >     margins for inclusion into LaTeX docs.
> > 
> > Patch 1/4 changes the route to the following two steps:
> > 
> >   1. DOT -> SVG by "dot -Tsvg"
> >   2. SVG -> PDF by "rsvg-convert -f pdf" with fallback to convert(1)
> > 
> > Pros:
> >   - Improved portability across distros
> >   - Less space around graphs in final PDF documents
> > 
> > Con:
> >   - On systems without rsvg-convert, generated PDF will be of raster
> >     image.
> > 
> > Patch 2/4 avoids raster-image PDF by using "dot -Tpdf" on systems where
> > the option is available.
> > 
> > * SVG -> PDF conversion
> > 
> > Current scheme uses convert(1) (of ImageMagick)  
> 
> I was not aware of security concerns regarding ImageMagick until
> Christoph brought them up in another thread [1].
> 
> [1]: https://lore.kernel.org/linux-doc/20220104131952.GA21933@xxxxxx/
> 
> Now I can add another Con as bellow.
> 
> > 
> > Cons:  
>     - ImageMagick is not allowed to read/write PDF by default under
>       Debian/Ubuntu and Gentoo systems.  The policy is a band-aide
>       fix to its security issues.
> >   - Generated PDFs are of raster image.  Some of them look blurry.
> >   - Raster images tend to be large in size.
> >   - convert(1) delegates SVG decoding to rsvg-convert(1).
> >     It doesn't cover full range of Inkscape-specific SVG features
> >     and fails to convert some of SVG figures properly.  
> 
>         Thanks, Akira
> 
> > 
> > Improper conversions are observed with SVGs listed below (incomplete,
> > conversion quality depends on the version of rsvg-convert):
> >   - Documentation/userspace-api/media/v4l/selection.svg
> >   - Documentation/userspace-api/media/v4l/vbi_525.svg
> >   - Documentation/userspace-api/media/v4l/vbi_625.svg
> >   - Documentation/userspace-api/media/v4l/vbi_hsync.svg
> >   - Documentation/admin-guide/blockdev/drbd/DRBD-8.3-data-packets.svg
> >   - Documentation/admin-guide/blockdev/drbd/DRBD-data-packages.svg
> > 
> > If you have Inkscape installed as well, convert(1) delegates SVG
> > decoding to inkscape(1) rather than to rsvg-convert(1) and SVGs listed
> > above can be rendered properly.
> > 
> > So if Inkscape is required for converting those SVGs properly, why not
> > use it directly in the first place?
> > 
> > Patches 3/4 and 4/4 add code to utilize inkscape(1) for SVG -> PDF
> > conversion when it is available.  They don't modify any existing
> > requirements for kernel-doc.
> > 
> > Patch 3/4 adds the alternative route of SVG -> PDF conversion by
> > inkscape(1).
> > Patch 4/4 delegates warning messages from inkscape(1) to kernellog.verbose
> > as they are likely harmless in command-line uses.
> > 
> > Pros:
> >   - Generated PDFs are of vector graphics.
> >   - Vector graphics tends to be smaller in size and looks nicer when
> >     zoomed in.
> >   - SVGs drawn by Inkscape are fully supported.
> > 
> > On systems without Inkscape, no regression is expected by these two
> > patches.
> > 
> > Changes since v1 (as of Patch 5/3) [1]:
> > 
> > - Reorder and merge patches to reduce/eliminate regression windows of
> >   raster-image PDF and stderr redirection.
> >     v1        v2
> >     1/3       1/4
> >     4/3       2/4
> >     2/3       3/4
> >     3/3+5/3   4/4
> > 
> > - Massage kernellog.verbose/warn messages. They now show command(s)
> >   used in DOT -> PDF conversion.
> > 
> > - Pass actual exit code of inkscape(1) to kernellog.warn.
> > 
> > FWIW, diff of v1 vs. v2 follows:
> > 
> > --------------------------------------------------------------  
> [...]
> 



Thanks,
Mauro