Subject: Re: [PATCH v2 0/4] docs: sphinx/kfigure.py: Improve conversion to PDF
To:     Jonathan Corbet <corbet@lwn.net>,
        Mauro Carvalho Chehab <mchehab@kernel.org>
Cc:     Randy Dunlap <rdunlap@infradead.org>, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org, Akira Yokosawa <akiyks@gmail.com>
References: <e01fe9f9-f600-c2fc-c6b3-ef6395655ffe@gmail.com>
From:   Akira Yokosawa <akiyks@gmail.com>
Message-ID: <e545803a-8f09-f0e7-4ca0-16b673ef1796@gmail.com>
Date:   Fri, 7 Jan 2022 22:45:47 +0900
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101
 Thunderbird/78.14.0
MIME-Version: 1.0
In-Reply-To: <e01fe9f9-f600-c2fc-c6b3-ef6395655ffe@gmail.com>
Content-Type: text/plain; charset=utf-8
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Precedence: bulk

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?

> 
> * 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@lst.de/

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:
> 
> --------------------------------------------------------------
[...]