[PATCH 0/3] docs: sphinx/kfigure.py: Improve conversion to PDF

[Akira Yokosawa <akiyks@gmail.com>]

This patch set improves conversions of DOT -> PDF and SVG -> PDF
for PDF docs.

* 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/3 changes the route to 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 for graphs in final PDF documents

Con:
  - On systems without rsvg-convert, generated PDF will be of raster
    image.


* SVG -> PDF conversion

Current scheme uses convert(1) (of ImageMagick)

Cons:
  - Generated PDFs are of raster image.  Some of them look blurry.
  - Raster image tends 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.

Failed conversions are observed with:
  - Documentation/userspace-api/media/v4l/selection.svg
  - Documentation/userspace-api/media/v4l/vbi_525.svg
  - Documentation/userspace-api/media/v4l/vbi_625.svg

If you have Inkscape installed as well, convert(1) delegates SVG
decoding to inkscape(1) and the above SVGs are rendered correctly.

So if Inkscape is required for converting those SVGs, why not use it
directly in the first place?

Patch 2/3 adds a route of SVG -> PDF conversion by inkscape(1).
Patch 3/3 hides warning messages from inkscape(1) which are harmless
in command-line uses.

Pros:
  - Generated PDFs are of vector graphics.
  - Vector graphics tends to be smaller in size and keeps looking nice
    while zoomed in.
  - SVGs drawn by Inkscape are fully supported.

On systems without Inkscape, there won't be any change in behavior.

        Thanks, Akira
--
Akira Yokosawa (3):
  docs: sphinx/kfigure.py: Use rsvg-convert(1) for DOT -> PDF conversion
  docs: sphinx/kfigure.py: Use inkscape(1) for SVG -> PDF conversion
  docs: sphinx/kfigure.py: Redirect warnings from inkscape to /dev/null

 Documentation/sphinx/kfigure.py | 109 ++++++++++++++++++++++++++++----
 1 file changed, 97 insertions(+), 12 deletions(-)


base-commit: a32fa6b2e8b4e0b8c03f5218afa0649e188239c5
-- 
2.17.1