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/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)
Cons:
- 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.
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:
--------------------------------------------------------------
diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure.py
index a275ee0fec02..24d2b2addcce 100644
--- a/Documentation/sphinx/kfigure.py
+++ b/Documentation/sphinx/kfigure.py
@@ -220,10 +220,16 @@ def setupTools(app):
if rsvg_convert_cmd:
kernellog.verbose(app, "use rsvg-convert(1) from: " + rsvg_convert_cmd)
+ kernellog.verbose(app, "use 'dot -Tsvg' and rsvg-convert(1) for DOT -> PDF conversion")
dot_Tpdf = False
else:
- kernellog.verbose(app, "rsvg-convert(1) not found, "
- "falling back to raster image conversion")
+ kernellog.verbose(app,
+ "rsvg-convert(1) not found.\n"
+ " SVG rendering of convert(1) is done by ImageMagick-native renderer.")
+ if dot_Tpdf:
+ kernellog.verbose(app, "use 'dot -Tpdf' for DOT -> PDF conversion")
+ else:
+ kernellog.verbose(app, "use 'dot -Tsvg' and convert(1) for DOT -> PDF conversion")
# integrate conversion tools
@@ -368,8 +374,10 @@ def svg2pdf(app, svg_fname, pdf_fname):
"""
cmd = [convert_cmd, svg_fname, pdf_fname]
+ cmd_name = 'convert(1)'
if inkscape_cmd:
+ cmd_name = 'inkscape(1)'
if inkscape_ver_one:
cmd = [inkscape_cmd, '-o', pdf_fname, svg_fname]
else:
@@ -380,15 +388,17 @@ def svg2pdf(app, svg_fname, pdf_fname):
exit_code = 0
except subprocess.CalledProcessError as err:
warning_msg = err.output
- exit_code = 1
+ exit_code = err.returncode
pass
if exit_code != 0:
kernellog.warn(app, "Error #%d when calling: %s" % (exit_code, " ".join(cmd)))
- kernellog.warn(app, "Warning msg from inkscape: %s" % str(warning_msg, 'utf-8'))
- if warning_msg:
- kernellog.verbose(app, "Warning msg from inkscape (likely harmless):\n%s"
- % str(warning_msg, 'utf-8'))
+ if warning_msg:
+ kernellog.warn(app, "Warning msg from %s: %s"
+ % (cmd_name, str(warning_msg, 'utf-8')))
+ elif warning_msg:
+ kernellog.verbose(app, "Warning msg from %s (likely harmless):\n%s"
+ % (cmd_name, str(warning_msg, 'utf-8')))
return bool(exit_code == 0)
--------------------------------------------------------------
[1] v1: https://lkml.kernel.org/r/de8def13-efbc-1d98-acb5-5cc1f6902e4b@xxxxxxxxx
Thanks, Akira
--
Akira Yokosawa (4):
docs: sphinx/kfigure.py: Use rsvg-convert(1) for DOT -> PDF conversion
docs: sphinx/kfigure.py: Add check of 'dot -Tpdf'
docs: sphinx/kfigure.py: Use inkscape(1) for SVG -> PDF conversion
docs: sphinx/kfigure.py: Delegate inkscape msg to kernellog.verbose
Documentation/sphinx/kfigure.py | 134 ++++++++++++++++++++++++++++----
1 file changed, 121 insertions(+), 13 deletions(-)
base-commit: b36064425a18e29a3bad9c007b4dd1223f8aadc5
--
2.17.1
