lkml.org 
[lkml]   [2021]   [Dec]   [12]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    Subject[PATCH 1/3] docs: sphinx/kfigure.py: Use rsvg-convert(1) for DOT -> PDF conversion
    From
    Date
    On openSUSE, dot(1) command does not support direct PDF output.
    On other distros, generated PDF images have unnecessarily wide margins,
    especially for small graphs.

    DOT -> PDF conversion can by improved by the following steps:

    1. DOT -> SVG by "dot -Tsvg"
    2. SVG -> PDF by "rsvg-convert -f pdf"

    Resulting PDFs will be free of extra margins.

    Add rules in kfigure.py so that the above mentioned steps are taken
    when rsvg-convert(1) is available.

    Note that rsvg-convert(1) is recommended by sphinx_pre_install.
    So it is most likely that existing systems for building pdfdocs have
    rsvg-convert(1) installed.

    Note:
    SVG features supported by rsvg-convert(1) vary depends on its
    version and distro config.
    For example, the one found on Ubuntu Bionic (version 2.40.20) does
    poor job in rendering some of SVG files drawn by Inkscape.

    SVG files of graphs generated by dot(1) are converted nicely even
    with such old versions of rsvg-convert.
    So this change won't affect the quality of such graphs in any way.

    Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
    Cc: Jonathan Corbet <corbet@lwn.net>
    Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
    ---
    Documentation/sphinx/kfigure.py | 46 +++++++++++++++++++++++++++++++--
    1 file changed, 44 insertions(+), 2 deletions(-)

    diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure.py
    index 3c78828330be..955e3ec5de5a 100644
    --- a/Documentation/sphinx/kfigure.py
    +++ b/Documentation/sphinx/kfigure.py
    @@ -31,6 +31,8 @@ u"""

    * ``dot(1)``: Graphviz (https://www.graphviz.org). If Graphviz is not
    available, the DOT language is inserted as literal-block.
    + For conversion to PDF, ``rsvg-convert(1)`` of librsvg
    + (https://gitlab.gnome.org/GNOME/librsvg) is used when available.

    * SVG to PDF: To generate PDF, you need at least one of this tools:

    @@ -113,6 +115,9 @@ dot_cmd = None
    # ImageMagick' convert(1) support
    convert_cmd = None

    +# librsvg's rsvg-convert(1) support
    +rsvg_convert_cmd = None
    +

    def setup(app):
    # check toolchain first
    @@ -160,11 +165,12 @@ def setupTools(app):

    This function is called once, when the builder is initiated.
    """
    - global dot_cmd, convert_cmd # pylint: disable=W0603
    + global dot_cmd, convert_cmd, rsvg_convert_cmd # pylint: disable=W0603
    kernellog.verbose(app, "kfigure: check installed tools ...")

    dot_cmd = which('dot')
    convert_cmd = which('convert')
    + rsvg_convert_cmd = which('rsvg-convert')

    if dot_cmd:
    kernellog.verbose(app, "use dot(1) from: " + dot_cmd)
    @@ -177,6 +183,11 @@ def setupTools(app):
    kernellog.warn(app,
    "convert(1) not found, for SVG to PDF conversion install "
    "ImageMagick (https://www.imagemagick.org)")
    + if rsvg_convert_cmd:
    + kernellog.verbose(app, "use rsvg-convert(1) from: " + rsvg_convert_cmd)
    + else:
    + kernellog.verbose(app, "rsvg-convert(1) not found, "
    + "falling back to raster image conversion")


    # integrate conversion tools
    @@ -266,7 +277,13 @@ def convert_image(img_node, translator, src_fname=None):

    if in_ext == '.dot':
    kernellog.verbose(app, 'convert DOT to: {out}/' + _name)
    - ok = dot2format(app, src_fname, dst_fname)
    + if translator.builder.format == 'latex':
    + svg_fname = path.join(translator.builder.outdir, fname + '.svg')
    + ok1 = dot2format(app, src_fname, svg_fname)
    + ok2 = svg2pdf_by_rsvg(app, svg_fname, dst_fname)
    + ok = ok1 and ok2
    + else:
    + ok = dot2format(app, src_fname, dst_fname)

    elif in_ext == '.svg':
    kernellog.verbose(app, 'convert SVG to: {out}/' + _name)
    @@ -319,6 +336,31 @@ def svg2pdf(app, svg_fname, pdf_fname):
    kernellog.warn(app, "Error #%d when calling: %s" % (exit_code, " ".join(cmd)))
    return bool(exit_code == 0)

    +def svg2pdf_by_rsvg(app, svg_fname, pdf_fname):
    + """Convert SVG to PDF with ``rsvg-convert(1)`` command.
    +
    + * ``svg_fname`` pathname of input SVG file, including extension ``.svg``
    + * ``pdf_fname`` pathname of output PDF file, including extension ``.pdf``
    +
    + Input SVG file should be the one generated by ``dot2format()``.
    + SVG -> PDF conversion is done by ``rsvg-convert(1)``.
    +
    + If ``rsvg-convert(1)`` is unavailable, fall back to ``svg2pdf()``.
    +
    + """
    +
    + if rsvg_convert_cmd is None:
    + ok = svg2pdf(app, svg_fname, pdf_fname)
    + else:
    + cmd = [rsvg_convert_cmd, '--format=pdf', '-o', pdf_fname, svg_fname]
    + # use stdout and stderr from parent
    + exit_code = subprocess.call(cmd)
    + if exit_code != 0:
    + kernellog.warn(app, "Error #%d when calling: %s" % (exit_code, " ".join(cmd)))
    + ok = bool(exit_code == 0)
    +
    + return ok
    +

    # image handling
    # ---------------------
    --
    2.17.1

    \
     
     \ /
      Last update: 2021-12-12 09:01    [W:6.947 / U:0.036 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site