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

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

[Akira Yokosawa]

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

[PATCH 1/3] docs: sphinx/kfigure.py: Use rsvg-convert(1) for DOT -> PDF conversion

[Akira Yokosawa]

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

[PATCH 2/3] docs: sphinx/kfigure.py: Use inkscape(1) for SVG -> PDF conversion

[Akira Yokosawa]

Using convert(1) of ImageMagick for SVG -> PDF conversion results in
PDFs containing raster (bitmap) images which sometimes look blurry.

Ideally speaking, SVG to PDF conversion should retain vector graphics
in SVG.

rsvg-convert(1) can do such conversions with regard to simple SVGs
generated by dot(1).

Unfortunately, rsvg-convert(1) does not cover some of SVG features
specific to Inkscape.
inkscape(1) of Inkscape naturally covers such SVG features.

So add a route in svg2pdf() so that inkscape(1) is used when it is
available.

Note:
    After this change, if you have Inkscape installed, ImageMagick and
    librsvg are not required.

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 | 57 +++++++++++++++++++++++++--------
 1 file changed, 43 insertions(+), 14 deletions(-)

diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure.py
index 955e3ec5de5a..8d7c59e52ceb 100644
--- a/Documentation/sphinx/kfigure.py
+++ b/Documentation/sphinx/kfigure.py
@@ -37,6 +37,7 @@ u"""
     * SVG to PDF: To generate PDF, you need at least one of this tools:
 
       - ``convert(1)``: ImageMagick (https://www.imagemagick.org)
+      - ``inkscape(1)``: Inkscape (https://inkscape.org/)
 
     List of customizations:
 
@@ -51,6 +52,7 @@ import os
 from os import path
 import subprocess
 from hashlib import sha1
+import re
 from docutils import nodes
 from docutils.statemachine import ViewList
 from docutils.parsers.rst import directives
@@ -118,6 +120,11 @@ convert_cmd = None
 # librsvg's rsvg-convert(1) support
 rsvg_convert_cmd = None
 
+# Inkscape's inkscape(1) support
+inkscape_cmd = None
+# Inkscape prior to 1.0 uses different command options
+inkscape_ver_one = False
+
 
 def setup(app):
     # check toolchain first
@@ -166,28 +173,42 @@ def setupTools(app):
     This function is called once, when the builder is initiated.
     """
     global dot_cmd, convert_cmd, rsvg_convert_cmd   # pylint: disable=W0603
+    global inkscape_cmd, inkscape_ver_one  # pylint: disable=W0603
     kernellog.verbose(app, "kfigure: check installed tools ...")
 
     dot_cmd = which('dot')
     convert_cmd = which('convert')
     rsvg_convert_cmd = which('rsvg-convert')
+    inkscape_cmd = which('inkscape')
 
     if dot_cmd:
         kernellog.verbose(app, "use dot(1) from: " + dot_cmd)
     else:
         kernellog.warn(app, "dot(1) not found, for better output quality install "
                        "graphviz from https://www.graphviz.org")
-    if convert_cmd:
-        kernellog.verbose(app, "use convert(1) from: " + convert_cmd)
-    else:
-        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)
+    if inkscape_cmd:
+        kernellog.verbose(app, "use inkscape(1) from: " + inkscape_cmd)
+        inkscape_ver = subprocess.check_output([inkscape_cmd, '--version'])
+        ver_one_ptn = b'Inkscape 1'
+        inkscape_ver_one = re.search(ver_one_ptn, inkscape_ver)
+        convert_cmd = None
+        rsvg_convert_cmd = None
+
     else:
-        kernellog.verbose(app, "rsvg-convert(1) not found, "
-                          "falling back to raster image conversion")
+        if convert_cmd:
+            kernellog.verbose(app, "use convert(1) from: " + convert_cmd)
+        else:
+            kernellog.warn(app,
+                "Neither inkscape(1) nor convert(1) found.\n"
+                "For SVG to PDF conversion, "
+                "install either Inkscape (https://inkscape.org/) (preferred) or\n"
+                "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
@@ -253,7 +274,7 @@ def convert_image(img_node, translator, src_fname=None):
     elif in_ext == '.svg':
 
         if translator.builder.format == 'latex':
-            if convert_cmd is None:
+            if not inkscape_cmd and convert_cmd is None:
                 kernellog.verbose(app,
                                   "no SVG to PDF conversion available / include SVG raw.")
                 img_node.replace_self(file2literal(src_fname))
@@ -320,16 +341,24 @@ def dot2format(app, dot_fname, out_fname):
     return bool(exit_code == 0)
 
 def svg2pdf(app, svg_fname, pdf_fname):
-    """Converts SVG to PDF with ``convert(1)`` command.
+    """Converts SVG to PDF with ``inkscape(1)`` or ``convert(1)`` command.
 
-    Uses ``convert(1)`` from ImageMagick (https://www.imagemagick.org) for
-    conversion.  Returns ``True`` on success and ``False`` if an error occurred.
+    Uses ``inkscape(1)`` from Inkscape (https://inkscape.org/) or ``convert(1)``
+    from ImageMagick (https://www.imagemagick.org) for conversion.
+    Returns ``True`` on success and ``False`` if an error occurred.
 
     * ``svg_fname`` pathname of the input SVG file with extension (``.svg``)
     * ``pdf_name``  pathname of the output PDF file with extension (``.pdf``)
 
     """
     cmd = [convert_cmd, svg_fname, pdf_fname]
+
+    if inkscape_cmd:
+        if inkscape_ver_one:
+            cmd = [inkscape_cmd, '-o', pdf_fname, svg_fname]
+        else:
+            cmd = [inkscape_cmd, '-z', '--export-pdf=%s' % pdf_fname, svg_fname]
+
     # use stdout and stderr from parent
     exit_code = subprocess.call(cmd)
     if exit_code != 0:
-- 
2.17.1

[PATCH 3/3] docs: sphinx/kfigure.py: Redirect warnings from inkscape to /dev/null

[Akira Yokosawa]

Depending on its version, distro config, and system-setup type,
inkscape(1) emits various warning messages which are harmless in
command-line uses.

List of such warning messages (incomplete, long ones wrapped):

  o Gtk-Message: hh:mm:ss.nnn: Failed to load module "canberra-gtk-module"
  o Unable to init server: Could not connect: Connection refused
  o Failed to get connection
  o ** (inkscape:xxx): CRITICAL **: hh:mm:ss.nnn: dbus_g_proxy_new_for_name:
    assertion 'connection != NULL' failed
  o ** (inkscape:xxx): CRITICAL **: hh:mm:ss.nnn: dbus_g_proxy_call:
    assertion 'DBUS_IS_G_PROXY (proxy)' failed
  o ** (inkscape:xxx): CRITICAL **: hh:mm:ss.nnn: dbus_g_connection_register_g_object:
    assertion 'connection != NULL' failed
  o ** (inkscape:xxx): WARNING **: hh:mm:ss.nnn:
    Fonts dir '/usr/share/inkscape/fonts' does not exist and will be ignored.

To avoid unnecessary anxiety, redirect warning messages from inkscape(1)
to /dev/null by default.

The redirection can be disabled by setting SPHINX_SHOW_INKSCAPE_WARN, e.g.,:

    make SPHINX_SHOW_INKSCAPE_WARN=1 pdfdocs

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 | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure.py
index 8d7c59e52ceb..d5802e3975e5 100644
--- a/Documentation/sphinx/kfigure.py
+++ b/Documentation/sphinx/kfigure.py
@@ -124,6 +124,9 @@ rsvg_convert_cmd = None
 inkscape_cmd = None
 # Inkscape prior to 1.0 uses different command options
 inkscape_ver_one = False
+# Show warning from inkscape(1), enabled by setting env var
+# SPHINX_SHOW_INKSCAPE_WARN
+inkscape_show_warn = False
 
 
 def setup(app):
@@ -173,7 +176,7 @@ def setupTools(app):
     This function is called once, when the builder is initiated.
     """
     global dot_cmd, convert_cmd, rsvg_convert_cmd   # pylint: disable=W0603
-    global inkscape_cmd, inkscape_ver_one  # pylint: disable=W0603
+    global inkscape_cmd, inkscape_ver_one, inkscape_show_warn  # pylint: disable=W0603
     kernellog.verbose(app, "kfigure: check installed tools ...")
 
     dot_cmd = which('dot')
@@ -188,12 +191,19 @@ def setupTools(app):
                        "graphviz from https://www.graphviz.org")
     if inkscape_cmd:
         kernellog.verbose(app, "use inkscape(1) from: " + inkscape_cmd)
-        inkscape_ver = subprocess.check_output([inkscape_cmd, '--version'])
+        inkscape_ver = subprocess.check_output([inkscape_cmd, '--version'],
+                                               stderr=subprocess.DEVNULL)
         ver_one_ptn = b'Inkscape 1'
         inkscape_ver_one = re.search(ver_one_ptn, inkscape_ver)
         convert_cmd = None
         rsvg_convert_cmd = None
 
+        try:
+            if os.environ['SPHINX_SHOW_INKSCAPE_WARN']:
+                inkscape_show_warn = True
+        except KeyError:
+            pass
+
     else:
         if convert_cmd:
             kernellog.verbose(app, "use convert(1) from: " + convert_cmd)
@@ -360,7 +370,11 @@ def svg2pdf(app, svg_fname, pdf_fname):
             cmd = [inkscape_cmd, '-z', '--export-pdf=%s' % pdf_fname, svg_fname]
 
     # use stdout and stderr from parent
-    exit_code = subprocess.call(cmd)
+    if inkscape_show_warn:
+        exit_code = subprocess.call(cmd)
+    else:
+        exit_code = subprocess.call(cmd, stderr=subprocess.DEVNULL)
+
     if exit_code != 0:
         kernellog.warn(app, "Error #%d when calling: %s" % (exit_code, " ".join(cmd)))
     return bool(exit_code == 0)
-- 
2.17.1

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

[Mauro Carvalho Chehab]

Em Sun, 12 Dec 2021 16:59:53 +0900
Akira Yokosawa <akiyks@gmail.com> escreveu:

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

First of all, package requirement for docs generation should be auto
discovered by:

	scripts/sphinx-pre-install

and should not break the ones detected by check_distros() and that
supports PDF generation.

> 
> Current scheme uses "dot -Tpdf" (of graphviz).
> 
> Cons:
>   - openSUSE's dot(1) does not support -Tpdf.

I'm sure I tested pdf generation in the past with openSUSE by the
time I wrote sphinx-pre-install script. Perhaps some change at either
openSUSE or at the docs makefile broke support for it.

>   - 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).

rsvg-convert is not present on Fedora (nor on RHEL and CentOS), as far
as I'm aware.

> 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.

Raster images are a very bad idea. Why don't keep use "dot -Tpdf" when
supported by the system? instead of falling back to raster images?

> * 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

What do you mean by failed? With the current way, the VBI ones
seem OK to me:

	https://linuxtv.org/downloads/v4l-dvb-apis-new/pdf/media.pdf

(This is daily updated. On today's build the raw VBI ones are in
page 1031/1032)

Do you mean that your changes caused a regression there?

> 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?

I remember that the main focus were to be able to generate PDF at the
major distros. It should be OK to use whatever tool, provided that it
won't cause regressions with such distros. Not that is should matter
much for the others, but my particular interest is that it shouldn't
cause regressions neither on Debian nor on Fedora, as those are the 
ones I use for PDF generation. Debian is used at linuxtv.org, where we
do automate builds for PDF, ePUB and HTML. Fedora is what I used locally,
in order to test and fix issues on media PDF document output.

> 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



Thanks,
Mauro

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

[Akira Yokosawa]

On Sun, 12 Dec 2021 11:38:13 +0100, Mauro Carvalho Chehab wrote:

Hi Mauro,

I didn't expect such a quick response.
Thank you so much!

> Em Sun, 12 Dec 2021 16:59:53 +0900
> Akira Yokosawa <akiyks@gmail.com> escreveu:
> 
>> This patch set improves conversions of DOT -> PDF and SVG -> PDF
>> for PDF docs.
>>
>> * DOT -> PDF conversion
> 
> First of all, package requirement for docs generation should be auto
> discovered by:
> 
> 	scripts/sphinx-pre-install

Please note that this update does not change any requirement.
I think you are worried by the possible degradation of DOT rendering
without rsvg-convert.  Please see comments below.

> 
> and should not break the ones detected by check_distros() and that
> supports PDF generation.
> 
>>
>> Current scheme uses "dot -Tpdf" (of graphviz).
>>
>> Cons:
>>   - openSUSE's dot(1) does not support -Tpdf.
> 
> I'm sure I tested pdf generation in the past with openSUSE by the
> time I wrote sphinx-pre-install script. Perhaps some change at either
> openSUSE or at the docs makefile broke support for it.

dot -T? on openSUSE Tumbleweed says (long line folded):

Format: "?" not recognized. Use one of: canon cmap cmapx cmapx_np dot dot
_json eps fig gd gd2 gif gv imap imap_np ismap jpe jpeg jpg json json0 mp
 pic plain plain-ext png pov ps ps2 svg svgz tk vml vmlz vrml wbmp xdot
 xdot1.2 xdot1.4 xdot_json

There is no "pdf" here.

> 
>>   - 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).
> 
> rsvg-convert is not present on Fedora (nor on RHEL and CentOS), as far
> as I'm aware.

It is provided in the "librsvg2-tools" package, which is suggested by
sphinx_pre_install.
So once you have it installed on Fedora/RHEL/CentOS, this change won't
cause any regression.

Don't you agree?

> 
>> 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.
> 
> Raster images are a very bad idea. Why don't keep use "dot -Tpdf" when
> supported by the system? instead of falling back to raster images?

I suppose I am able to do so.  I just thought installing rsvg-convert
wouldn't be that difficult.
I can add a patch in v2 if you insist that is necessary.

> 
>> * 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
> 
> What do you mean by failed? With the current way, the VBI ones
> seem OK to me:
> 
> 	https://linuxtv.org/downloads/v4l-dvb-apis-new/pdf/media.pdf

By "fail", I meant "fail to render properly.

selection.svg is rendered on page 810 in your PDF.
I think the mask strap is lost in the figure.
Well, selection.svg has Inkscape specific elements for the strap.
So it is not rendered in a browser, either.

If you open it in Inkscape, I think you will see the difference.
Actually speaking, I have edited selection.svg so that it can
be rendered in a browser.  My plan is to send it as an independent
patch once this patch set is accepted.

Figures 10, 11, and 12 on pages 1031 and 1032 don't look good
either.  Do you see what I mean?

> 
> (This is daily updated. On today's build the raw VBI ones are in
> page 1031/1032)
> 
> Do you mean that your changes caused a regression there?

Of course not!

> 
>> 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?
> 
> I remember that the main focus were to be able to generate PDF at the
> major distros. It should be OK to use whatever tool, provided that it
> won't cause regressions with such distros. Not that is should matter
> much for the others, but my particular interest is that it shouldn't
> cause regressions neither on Debian nor on Fedora, as those are the 
> ones I use for PDF generation. Debian is used at linuxtv.org, where we
> do automate builds for PDF, ePUB and HTML. Fedora is what I used locally,
> in order to test and fix issues on media PDF document output.

I have tested this change on Debian and Fedora systems as well as
openSUSE, Arch, and other distros.
I'd say it works flawlessly.

I'd appreciate if you could give a try on your systems.

Thanks for your feedback.
I am willing to improve the quality of the PDF docs further.

        Thanks, Akira

> 
>> 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
> 
> 
> 
> Thanks,
> Mauro
> 

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

[Mauro Carvalho Chehab]

Em Sun, 12 Dec 2021 20:57:23 +0900
Akira Yokosawa <akiyks@gmail.com> escreveu:

> On Sun, 12 Dec 2021 11:38:13 +0100, Mauro Carvalho Chehab wrote:
> 
> Hi Mauro,
> 
> I didn't expect such a quick response.
> Thank you so much!
> 
> > Em Sun, 12 Dec 2021 16:59:53 +0900
> > Akira Yokosawa <akiyks@gmail.com> escreveu:
> >   
> >> This patch set improves conversions of DOT -> PDF and SVG -> PDF
> >> for PDF docs.
> >>
> >> * DOT -> PDF conversion  
> > 
> > First of all, package requirement for docs generation should be auto
> > discovered by:
> > 
> > 	scripts/sphinx-pre-install  
> 
> Please note that this update does not change any requirement.

Ok.

> I think you are worried by the possible degradation of DOT rendering
> without rsvg-convert.  Please see comments below.
> 
> > 
> > and should not break the ones detected by check_distros() and that
> > supports PDF generation.
> >   
> >>
> >> Current scheme uses "dot -Tpdf" (of graphviz).
> >>
> >> Cons:
> >>   - openSUSE's dot(1) does not support -Tpdf.  
> > 
> > I'm sure I tested pdf generation in the past with openSUSE by the
> > time I wrote sphinx-pre-install script. Perhaps some change at either
> > openSUSE or at the docs makefile broke support for it.  
> 
> dot -T? on openSUSE Tumbleweed says (long line folded):
> 
> Format: "?" not recognized. Use one of: canon cmap cmapx cmapx_np dot dot
> _json eps fig gd gd2 gif gv imap imap_np ismap jpe jpeg jpg json json0 mp
>  pic plain plain-ext png pov ps ps2 svg svgz tk vml vmlz vrml wbmp xdot
>  xdot1.2 xdot1.4 xdot_json
> 
> There is no "pdf" here.

Tumbleweed is a rolling distribution. Something could have changed since
when I added support for it. Anyway, the script could check the output of
it to enable/disable pdf via dot (not saying it is worth or not).

> >   
> >>   - 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).  
> > 
> > rsvg-convert is not present on Fedora (nor on RHEL and CentOS), as far
> > as I'm aware.  
> 
> It is provided in the "librsvg2-tools" package, which is suggested by
> sphinx_pre_install.
> So once you have it installed on Fedora/RHEL/CentOS, this change won't
> cause any regression.
> 
> Don't you agree?

Yeah, I missed that. Thanks for reminding me about that ;-)

> >   
> >> 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.  
> > 
> > Raster images are a very bad idea. Why don't keep use "dot -Tpdf" when
> > supported by the system? instead of falling back to raster images?  
> 
> I suppose I am able to do so.  I just thought installing rsvg-convert
> wouldn't be that difficult.
> I can add a patch in v2 if you insist that is necessary.
> 
> >   
> >> * 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  
> > 
> > What do you mean by failed? With the current way, the VBI ones
> > seem OK to me:
> > 
> > 	https://linuxtv.org/downloads/v4l-dvb-apis-new/pdf/media.pdf  
> 
> By "fail", I meant "fail to render properly.
> 
> selection.svg is rendered on page 810 in your PDF.
> I think the mask strap is lost in the figure.
> Well, selection.svg has Inkscape specific elements for the strap.
> So it is not rendered in a browser, either.

Ok, so we should fix selection.svg to address such issues. The same applies
to other images and graphs. That may include properly setting the margins.

> If you open it in Inkscape, I think you will see the difference.
> Actually speaking, I have edited selection.svg so that it can
> be rendered in a browser.  My plan is to send it as an independent
> patch once this patch set is accepted.

No matter if this is merged or not, if you find an issue at the images
at the media docs, please send them to linux-media@vger.org.

> 
> Figures 10, 11, and 12 on pages 1031 and 1032 don't look good
> either.  Do you see what I mean?
> 
> > 
> > (This is daily updated. On today's build the raw VBI ones are in
> > page 1031/1032)
> > 
> > Do you mean that your changes caused a regression there?  
> 
> Of course not!
> 
> >   
> >> 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?  
> > 
> > I remember that the main focus were to be able to generate PDF at the
> > major distros. It should be OK to use whatever tool, provided that it
> > won't cause regressions with such distros. Not that is should matter
> > much for the others, but my particular interest is that it shouldn't
> > cause regressions neither on Debian nor on Fedora, as those are the 
> > ones I use for PDF generation. Debian is used at linuxtv.org, where we
> > do automate builds for PDF, ePUB and HTML. Fedora is what I used locally,
> > in order to test and fix issues on media PDF document output.  
> 
> I have tested this change on Debian and Fedora systems as well as
> openSUSE, Arch, and other distros.
> I'd say it works flawlessly.
> 
> I'd appreciate if you could give a try on your systems.

I'll try to run some tests today.

> Thanks for your feedback.
> I am willing to improve the quality of the PDF docs further.
> 
>         Thanks, Akira
> 
> >   
> >> 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

It sounds too risky to redirect stderr to /dev/null. Yeah, here, the output
of inkscape is too crowd of warnings. Hacking it with a 
SPHINX_SHOW_INKSCAPE_WARN variable also seems a bad idea.

Not sure how this could be solved.

Thanks,
Mauro

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

[Akira Yokosawa]

On Mon, 13 Dec 2021 07:33:27 +0100, Mauro Carvalho Chehab wrote:
> Em Sun, 12 Dec 2021 20:57:23 +0900
> Akira Yokosawa <akiyks@gmail.com> escreveu:
> 
>> On Sun, 12 Dec 2021 11:38:13 +0100, Mauro Carvalho Chehab wrote:
>>
>> Hi Mauro,
>>
>> I didn't expect such a quick response.
>> Thank you so much!
>>
>>> Em Sun, 12 Dec 2021 16:59:53 +0900
>>> Akira Yokosawa <akiyks@gmail.com> escreveu:
>>>   
>>>> This patch set improves conversions of DOT -> PDF and SVG -> PDF
>>>> for PDF docs.
>>>>
>>>> * DOT -> PDF conversion  
>>>
>>> First of all, package requirement for docs generation should be auto
>>> discovered by:
>>>
>>> 	scripts/sphinx-pre-install  
>>
>> Please note that this update does not change any requirement.
> 
> Ok.
> 
>> I think you are worried by the possible degradation of DOT rendering
>> without rsvg-convert.  Please see comments below.
>>
>>>
>>> and should not break the ones detected by check_distros() and that
>>> supports PDF generation.
>>>   
>>>>
>>>> Current scheme uses "dot -Tpdf" (of graphviz).
>>>>
>>>> Cons:
>>>>   - openSUSE's dot(1) does not support -Tpdf.  
>>>
>>> I'm sure I tested pdf generation in the past with openSUSE by the
>>> time I wrote sphinx-pre-install script. Perhaps some change at either
>>> openSUSE or at the docs makefile broke support for it.  
>>
>> dot -T? on openSUSE Tumbleweed says (long line folded):
>>
>> Format: "?" not recognized. Use one of: canon cmap cmapx cmapx_np dot dot
>> _json eps fig gd gd2 gif gv imap imap_np ismap jpe jpeg jpg json json0 mp
>>  pic plain plain-ext png pov ps ps2 svg svgz tk vml vmlz vrml wbmp xdot
>>  xdot1.2 xdot1.4 xdot_json
>>
>> There is no "pdf" here.
> 
> Tumbleweed is a rolling distribution. Something could have changed since
> when I added support for it. Anyway, the script could check the output of
> it to enable/disable pdf via dot (not saying it is worth or not).

I found a related message of yours in the lore archive:

   https://lore.kernel.org/all/20170715162741.0e4f1298@vento.lan/

It has no follow-up messages though.
Do you remember something further about dot(1) on Tumbleweed?


>>>   
>>>>   - 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).  
>>>
>>> rsvg-convert is not present on Fedora (nor on RHEL and CentOS), as far
>>> as I'm aware.  
>>
>> It is provided in the "librsvg2-tools" package, which is suggested by
>> sphinx_pre_install.
>> So once you have it installed on Fedora/RHEL/CentOS, this change won't
>> cause any regression.
>>
>> Don't you agree?
> 
> Yeah, I missed that. Thanks for reminding me about that ;-)

You are welcome.

> 
>>>   
>>>> 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.  
>>>
>>> Raster images are a very bad idea. Why don't keep use "dot -Tpdf" when
>>> supported by the system? instead of falling back to raster images?  
>>
>> I suppose I am able to do so.  I just thought installing rsvg-convert
>> wouldn't be that difficult.
>> I can add a patch in v2 if you insist that is necessary.

I'm working on a test of "dot -Tpdf".
I'll post it as a follow-up of [PATCH 4/3] to this patch set when
it's ready.
It will be slightly different from your suggestion.
"dot -Tpdf" will be used only when both of rsvg-convert(1) and inkscape(1)
are unavailable, and "-Tpdf" is supported.
I think this is sufficient for preventing regressions on existing
systems.

>>
>>>   
>>>> * 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  
>>>
>>> What do you mean by failed? With the current way, the VBI ones
>>> seem OK to me:
>>>
>>> 	https://linuxtv.org/downloads/v4l-dvb-apis-new/pdf/media.pdf  
>>
>> By "fail", I meant "fail to render properly.
>>
>> selection.svg is rendered on page 810 in your PDF.
>> I think the mask strap is lost in the figure.
>> Well, selection.svg has Inkscape specific elements for the strap.
>> So it is not rendered in a browser, either.
> 
> Ok, so we should fix selection.svg to address such issues. The same applies
> to other images and graphs. That may include properly setting the margins.

SVGs of the other images and graphs are rendered properly in a browser.
So I don't think those need fixes.  I'd say it's defects of
rsvg-convert, which the Gnome project might or might not be willing
to fix.  Or might have been fixed in a later versions of librsvg.
Why don't you open an issue at https://gitlab.gnome.org/GNOME/librsvg ?

> 
>> If you open it in Inkscape, I think you will see the difference.
>> Actually speaking, I have edited selection.svg so that it can
>> be rendered in a browser.  My plan is to send it as an independent
>> patch once this patch set is accepted.
> 
> No matter if this is merged or not, if you find an issue at the images
> at the media docs, please send them to linux-media@vger.org.

OK. I'll compose a proper change log for it and post it later this
week or next.
(I'm not a type of person who is good at doing several things in
parallel.)

And the most easy fix is to install Inkscape on your system for
the daily build.
Then, convert(1) picks inkscape(1) for SVG rendering and you will
see right ones (of raster images, though).

You know, ImageMagick prefers inkscape over rsvg-convert.
I think it is the right thing to do in kfigure.py as well.

> 
>>
>> Figures 10, 11, and 12 on pages 1031 and 1032 don't look good
>> either.  Do you see what I mean?
>>
>>>
>>> (This is daily updated. On today's build the raw VBI ones are in
>>> page 1031/1032)
>>>
>>> Do you mean that your changes caused a regression there?  
>>
>> Of course not!
>>
>>>   
>>>> 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?  
>>>
>>> I remember that the main focus were to be able to generate PDF at the
>>> major distros. It should be OK to use whatever tool, provided that it
>>> won't cause regressions with such distros. Not that is should matter
>>> much for the others, but my particular interest is that it shouldn't
>>> cause regressions neither on Debian nor on Fedora, as those are the 
>>> ones I use for PDF generation. Debian is used at linuxtv.org, where we
>>> do automate builds for PDF, ePUB and HTML. Fedora is what I used locally,
>>> in order to test and fix issues on media PDF document output.  
>>
>> I have tested this change on Debian and Fedora systems as well as
>> openSUSE, Arch, and other distros.
>> I'd say it works flawlessly.
>>
>> I'd appreciate if you could give a try on your systems.
> 
> I'll try to run some tests today.

Thanks!

> 
>> Thanks for your feedback.
>> I am willing to improve the quality of the PDF docs further.
>>
>>         Thanks, Akira
>>
>>>   
>>>> 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
> 
> It sounds too risky to redirect stderr to /dev/null. Yeah, here, the output
> of inkscape is too crowd of warnings. Hacking it with a 
> SPHINX_SHOW_INKSCAPE_WARN variable also seems a bad idea.

Good points!

> 
> Not sure how this could be solved.

We might be able to filter warning messages from inkscape and display
only those we don't expect.

I'm not sure maintaining such a list of harmless messages might
be too much for us or not.

Anyway, I'll give it a try.

        Thanks, Akira

> 
> Thanks,
> Mauro
> 

[PATCH 4/3] docs: sphinx/kfigure.py: Add check of 'dot -Tpdf'

[Akira Yokosawa]

To prevent any regression on existing build systems, limit the
fallback of converting DOT -> raster PDF only when all of the
following conditions are met.

 o dot(1) doesn't support -Tpdf
 o rsvg-convert(1) is not found
 o inkscape(1) is not found

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

diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure.py
index d5802e3975e5..dbe75ee8ae61 100644
--- a/Documentation/sphinx/kfigure.py
+++ b/Documentation/sphinx/kfigure.py
@@ -113,6 +113,8 @@ def pass_handle(self, node):           # pylint: disable=W0613
 
 # Graphviz's dot(1) support
 dot_cmd = None
+# dot(1) -Tpdf should be used
+dot_Tpdf = False
 
 # ImageMagick' convert(1) support
 convert_cmd = None
@@ -175,7 +177,7 @@ def setupTools(app):
 
     This function is called once, when the builder is initiated.
     """
-    global dot_cmd, convert_cmd, rsvg_convert_cmd   # pylint: disable=W0603
+    global dot_cmd, dot_Tpdf, convert_cmd, rsvg_convert_cmd   # pylint: disable=W0603
     global inkscape_cmd, inkscape_ver_one, inkscape_show_warn  # pylint: disable=W0603
     kernellog.verbose(app, "kfigure: check installed tools ...")
 
@@ -186,6 +188,16 @@ def setupTools(app):
 
     if dot_cmd:
         kernellog.verbose(app, "use dot(1) from: " + dot_cmd)
+
+        try:
+            dot_Thelp_list = subprocess.check_output([dot_cmd, '-Thelp'],
+                                    stderr=subprocess.STDOUT)
+        except subprocess.CalledProcessError as err:
+            dot_Thelp_list = err.output
+            pass
+
+        dot_Tpdf_ptn = b'pdf'
+        dot_Tpdf = re.search(dot_Tpdf_ptn, dot_Thelp_list)
     else:
         kernellog.warn(app, "dot(1) not found, for better output quality install "
                        "graphviz from https://www.graphviz.org")
@@ -197,6 +209,7 @@ def setupTools(app):
         inkscape_ver_one = re.search(ver_one_ptn, inkscape_ver)
         convert_cmd = None
         rsvg_convert_cmd = None
+        dot_Tpdf = False
 
         try:
             if os.environ['SPHINX_SHOW_INKSCAPE_WARN']:
@@ -216,6 +229,7 @@ def setupTools(app):
 
         if rsvg_convert_cmd:
             kernellog.verbose(app, "use rsvg-convert(1) from: " + rsvg_convert_cmd)
+            dot_Tpdf = False
         else:
             kernellog.verbose(app, "rsvg-convert(1) not found, "
                               "falling back to raster image conversion")
@@ -308,11 +322,12 @@ def convert_image(img_node, translator, src_fname=None):
 
             if in_ext == '.dot':
                 kernellog.verbose(app, 'convert DOT to: {out}/' + _name)
-                if translator.builder.format == 'latex':
+                if translator.builder.format == 'latex' and not dot_Tpdf:
                     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)
 
-- 
2.17.1

[PATCH 5/3] docs: sphinx/kfigure.py: Delegate inkscape msgs to kernellog

[Akira Yokosawa]

Instead of redirecting to /dev/null, capture inkscape messages and
output them via kernelloc.verbose or kerneldoc.warn depending on the
exit code.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Jonathan Corbet <corbet@lwn.net>
---
Hi Mauro,

On second thought, I took the path of delegating inkscape warnings
to kernellog.

Now you can see those warning messages by "SPHINXOPTS=-v".

Does this approach sound reasonable to you?

        Thanks, Akira
--
 Documentation/sphinx/kfigure.py | 28 +++++++++++++---------------
 1 file changed, 13 insertions(+), 15 deletions(-)

diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure.py
index dbe75ee8ae61..a275ee0fec02 100644
--- a/Documentation/sphinx/kfigure.py
+++ b/Documentation/sphinx/kfigure.py
@@ -126,9 +126,6 @@ rsvg_convert_cmd = None
 inkscape_cmd = None
 # Inkscape prior to 1.0 uses different command options
 inkscape_ver_one = False
-# Show warning from inkscape(1), enabled by setting env var
-# SPHINX_SHOW_INKSCAPE_WARN
-inkscape_show_warn = False
 
 
 def setup(app):
@@ -178,7 +175,7 @@ def setupTools(app):
     This function is called once, when the builder is initiated.
     """
     global dot_cmd, dot_Tpdf, convert_cmd, rsvg_convert_cmd   # pylint: disable=W0603
-    global inkscape_cmd, inkscape_ver_one, inkscape_show_warn  # pylint: disable=W0603
+    global inkscape_cmd, inkscape_ver_one  # pylint: disable=W0603
     kernellog.verbose(app, "kfigure: check installed tools ...")
 
     dot_cmd = which('dot')
@@ -211,12 +208,6 @@ def setupTools(app):
         rsvg_convert_cmd = None
         dot_Tpdf = False
 
-        try:
-            if os.environ['SPHINX_SHOW_INKSCAPE_WARN']:
-                inkscape_show_warn = True
-        except KeyError:
-            pass
-
     else:
         if convert_cmd:
             kernellog.verbose(app, "use convert(1) from: " + convert_cmd)
@@ -384,14 +375,21 @@ def svg2pdf(app, svg_fname, pdf_fname):
         else:
             cmd = [inkscape_cmd, '-z', '--export-pdf=%s' % pdf_fname, svg_fname]
 
-    # use stdout and stderr from parent
-    if inkscape_show_warn:
-        exit_code = subprocess.call(cmd)
-    else:
-        exit_code = subprocess.call(cmd, stderr=subprocess.DEVNULL)
+    try:
+        warning_msg = subprocess.check_output(cmd, stderr=subprocess.STDOUT)
+        exit_code = 0
+    except subprocess.CalledProcessError as err:
+        warning_msg = err.output
+        exit_code = 1
+        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'))
+
     return bool(exit_code == 0)
 
 def svg2pdf_by_rsvg(app, svg_fname, pdf_fname):
-- 
2.17.1

Re: [PATCH 5/3] docs: sphinx/kfigure.py: Delegate inkscape msgs to kernellog

[Randy Dunlap]

On 12/13/21 18:34, Akira Yokosawa wrote:
> Instead of redirecting to /dev/null, capture inkscape messages and
> output them via kernelloc.verbose or kerneldoc.warn depending on the

                  kernellog.verbose or kernellog.warn

> exit code.
> 
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
> Cc: Jonathan Corbet <corbet@lwn.net>
> ---
> Hi Mauro,
> 
> On second thought, I took the path of delegating inkscape warnings
> to kernellog.
> 
> Now you can see those warning messages by "SPHINXOPTS=-v".
> 
> Does this approach sound reasonable to you?
> 
>         Thanks, Akira
> --
>  Documentation/sphinx/kfigure.py | 28 +++++++++++++---------------
>  1 file changed, 13 insertions(+), 15 deletions(-)
> 
> diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure.py
> index dbe75ee8ae61..a275ee0fec02 100644
> --- a/Documentation/sphinx/kfigure.py
> +++ b/Documentation/sphinx/kfigure.py
> @@ -126,9 +126,6 @@ rsvg_convert_cmd = None
>  inkscape_cmd = None
>  # Inkscape prior to 1.0 uses different command options
>  inkscape_ver_one = False
> -# Show warning from inkscape(1), enabled by setting env var
> -# SPHINX_SHOW_INKSCAPE_WARN
> -inkscape_show_warn = False
>  
>  
>  def setup(app):
> @@ -178,7 +175,7 @@ def setupTools(app):
>      This function is called once, when the builder is initiated.
>      """
>      global dot_cmd, dot_Tpdf, convert_cmd, rsvg_convert_cmd   # pylint: disable=W0603
> -    global inkscape_cmd, inkscape_ver_one, inkscape_show_warn  # pylint: disable=W0603
> +    global inkscape_cmd, inkscape_ver_one  # pylint: disable=W0603
>      kernellog.verbose(app, "kfigure: check installed tools ...")
>  
>      dot_cmd = which('dot')
> @@ -211,12 +208,6 @@ def setupTools(app):
>          rsvg_convert_cmd = None
>          dot_Tpdf = False
>  
> -        try:
> -            if os.environ['SPHINX_SHOW_INKSCAPE_WARN']:
> -                inkscape_show_warn = True
> -        except KeyError:
> -            pass
> -
>      else:
>          if convert_cmd:
>              kernellog.verbose(app, "use convert(1) from: " + convert_cmd)
> @@ -384,14 +375,21 @@ def svg2pdf(app, svg_fname, pdf_fname):
>          else:
>              cmd = [inkscape_cmd, '-z', '--export-pdf=%s' % pdf_fname, svg_fname]
>  
> -    # use stdout and stderr from parent
> -    if inkscape_show_warn:
> -        exit_code = subprocess.call(cmd)
> -    else:
> -        exit_code = subprocess.call(cmd, stderr=subprocess.DEVNULL)
> +    try:
> +        warning_msg = subprocess.check_output(cmd, stderr=subprocess.STDOUT)
> +        exit_code = 0
> +    except subprocess.CalledProcessError as err:
> +        warning_msg = err.output
> +        exit_code = 1
> +        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'))
> +
>      return bool(exit_code == 0)
>  
>  def svg2pdf_by_rsvg(app, svg_fname, pdf_fname):
> 

-- 
~Randy

Re: [PATCH 5/3] docs: sphinx/kfigure.py: Delegate inkscape msgs to kernellog

[Akira Yokosawa]

On Mon, 13 Dec 2021 18:50:51 -0800, Randy Dunlap wrote:
> On 12/13/21 18:34, Akira Yokosawa wrote:
>> Instead of redirecting to /dev/null, capture inkscape messages and
>> output them via kernelloc.verbose or kerneldoc.warn depending on the
> 
>                   kernellog.verbose or kernellog.warn

Now fixed.

        Thanks, Akira
> 
>> exit code.
>>
>> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
>> Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
>> Cc: Jonathan Corbet <corbet@lwn.net>
>> ---
>> Hi Mauro,
>>
>> On second thought, I took the path of delegating inkscape warnings
>> to kernellog.
>>
>> Now you can see those warning messages by "SPHINXOPTS=-v".
>>
>> Does this approach sound reasonable to you?
>>
>>         Thanks, Akira
>> --
>>  Documentation/sphinx/kfigure.py | 28 +++++++++++++---------------
>>  1 file changed, 13 insertions(+), 15 deletions(-)
>>
>> diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure.py
>> index dbe75ee8ae61..a275ee0fec02 100644
>> --- a/Documentation/sphinx/kfigure.py
>> +++ b/Documentation/sphinx/kfigure.py
>> @@ -126,9 +126,6 @@ rsvg_convert_cmd = None
>>  inkscape_cmd = None
>>  # Inkscape prior to 1.0 uses different command options
>>  inkscape_ver_one = False
>> -# Show warning from inkscape(1), enabled by setting env var
>> -# SPHINX_SHOW_INKSCAPE_WARN
>> -inkscape_show_warn = False
>>  
>>  
>>  def setup(app):
>> @@ -178,7 +175,7 @@ def setupTools(app):
>>      This function is called once, when the builder is initiated.
>>      """
>>      global dot_cmd, dot_Tpdf, convert_cmd, rsvg_convert_cmd   # pylint: disable=W0603
>> -    global inkscape_cmd, inkscape_ver_one, inkscape_show_warn  # pylint: disable=W0603
>> +    global inkscape_cmd, inkscape_ver_one  # pylint: disable=W0603
>>      kernellog.verbose(app, "kfigure: check installed tools ...")
>>  
>>      dot_cmd = which('dot')
>> @@ -211,12 +208,6 @@ def setupTools(app):
>>          rsvg_convert_cmd = None
>>          dot_Tpdf = False
>>  
>> -        try:
>> -            if os.environ['SPHINX_SHOW_INKSCAPE_WARN']:
>> -                inkscape_show_warn = True
>> -        except KeyError:
>> -            pass
>> -
>>      else:
>>          if convert_cmd:
>>              kernellog.verbose(app, "use convert(1) from: " + convert_cmd)
>> @@ -384,14 +375,21 @@ def svg2pdf(app, svg_fname, pdf_fname):
>>          else:
>>              cmd = [inkscape_cmd, '-z', '--export-pdf=%s' % pdf_fname, svg_fname]
>>  
>> -    # use stdout and stderr from parent
>> -    if inkscape_show_warn:
>> -        exit_code = subprocess.call(cmd)
>> -    else:
>> -        exit_code = subprocess.call(cmd, stderr=subprocess.DEVNULL)
>> +    try:
>> +        warning_msg = subprocess.check_output(cmd, stderr=subprocess.STDOUT)
>> +        exit_code = 0
>> +    except subprocess.CalledProcessError as err:
>> +        warning_msg = err.output
>> +        exit_code = 1
>> +        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'))
>> +
>>      return bool(exit_code == 0)
>>  
>>  def svg2pdf_by_rsvg(app, svg_fname, pdf_fname):
>>
> 

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

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

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

So I'm unclear on the status of these patches; Mauro, are you happy with
them?  If so I'd like to get them in before the merge window.

Thanks,

jon

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

[Akira Yokosawa]

On Thu, 23 Dec 2021 12:56:56 -0700, Jonathan Corbet wrote:
> Akira Yokosawa <akiyks@gmail.com> writes:
> 
>> This patch set improves conversions of DOT -> PDF and SVG -> PDF
>> for PDF docs.
>>
>> * DOT -> PDF conversion
> 
> So I'm unclear on the status of these patches; Mauro, are you happy with
> them?  If so I'd like to get them in before the merge window.

Jon, whether Mauro is happy or not, I want to do a respin of this and
at least fix the typo in PATCH 5/3 Randy pointed out.
Maybe merge PATCH 5/3 with PATCH 3/3 as well. 

There is no reason to hurry, I suppose.

I was kind of distracted by a development in other project lately.

        Thanks, Akira
> 
> Thanks,
> 
> jon
> 

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

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

> On Thu, 23 Dec 2021 12:56:56 -0700, Jonathan Corbet wrote:
>> Akira Yokosawa <akiyks@gmail.com> writes:
>> 
>>> This patch set improves conversions of DOT -> PDF and SVG -> PDF
>>> for PDF docs.
>>>
>>> * DOT -> PDF conversion
>> 
>> So I'm unclear on the status of these patches; Mauro, are you happy with
>> them?  If so I'd like to get them in before the merge window.
>
> Jon, whether Mauro is happy or not, I want to do a respin of this and
> at least fix the typo in PATCH 5/3 Randy pointed out.
> Maybe merge PATCH 5/3 with PATCH 3/3 as well. 
>
> There is no reason to hurry, I suppose.
>
> I was kind of distracted by a development in other project lately.

No worries, I can wait :)

Thanks,

jon

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

[Mauro Carvalho Chehab]

Em Thu, 23 Dec 2021 16:48:53 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> Akira Yokosawa <akiyks@gmail.com> writes:
> 
> > On Thu, 23 Dec 2021 12:56:56 -0700, Jonathan Corbet wrote:  
> >> Akira Yokosawa <akiyks@gmail.com> writes:
> >>   
> >>> This patch set improves conversions of DOT -> PDF and SVG -> PDF
> >>> for PDF docs.
> >>>
> >>> * DOT -> PDF conversion  
> >> 
> >> So I'm unclear on the status of these patches; Mauro, are you happy with
> >> them?  If so I'd like to get them in before the merge window.  
> >
> > Jon, whether Mauro is happy or not, I want to do a respin of this and
> > at least fix the typo in PATCH 5/3 Randy pointed out.
> > Maybe merge PATCH 5/3 with PATCH 3/3 as well. 
> >
> > There is no reason to hurry, I suppose.
> >
> > I was kind of distracted by a development in other project lately.  
> 
> No worries, I can wait :)

I'll test the next review then... I guess the conversion is ok,
but I'll do a better test on a v2, after arriving from vacations.

Merry Christmas and Happy New Year!
Mauro

Status of selection.svg update (was Re: [PATCH 0/3] docs: sphinx/kfigure.py: Improve conversion to PDF)

[Akira Yokosawa]

[+Cc: linux-media, -Cc: lkml]

Hi Mauro,

In case you are wondering what is going on in the update of
selection.svg, here is a status report.

On Mon, 13 Dec 2021 16:53:07 +0900, Akira Yokosawa wrote:
> On Mon, 13 Dec 2021 07:33:27 +0100, Mauro Carvalho Chehab wrote:
[...]
>> No matter if this is merged or not, if you find an issue at the images
>> at the media docs, please send them to linux-media@vger.org.
> 
> OK. I'll compose a proper change log for it and post it later this
> week or next.
> (I'm not a type of person who is good at doing several things in
> parallel.)

I started the patch preparation, but I found the patch would be
quite large in size (~500kB).

This is because current selection.svg consists of pretty high-
resolution raster images.
I see you had done several attempts to reduce the complexity of
the SVG, but it is still large (> 200kB) and conversion to PDF by
convert(1) generates a PDF of more than 1MB!
Even inkscape(1) generates a larger PDF (>1.3MB) with embedded
raster images.

I don't believe what the figure wants to explain deserves such
a large size.
So, from my POV, adding another bitmap image to the SVG for the
sake of browser compatibility is *not* the right thing to do.

Instead, my suggestion would be to get rid of the embedded raster
images and to draw some simple vector-graphics-based figure
instead.

Am I missing something here?

        Thanks, Akira

> 
> And the most easy fix is to install Inkscape on your system for
> the daily build.
> Then, convert(1) picks inkscape(1) for SVG rendering and you will
> see right ones (of raster images, though).
> 
> You know, ImageMagick prefers inkscape over rsvg-convert.
> I think it is the right thing to do in kfigure.py as well.
> 
[...]

Re: Status of selection.svg update (was Re: [PATCH 0/3] docs: sphinx/kfigure.py: Improve conversion to PDF)

[Mauro Carvalho Chehab]

Em Wed, 29 Dec 2021 21:54:47 +0900
Akira Yokosawa <akiyks@gmail.com> escreveu:

> [+Cc: linux-media, -Cc: lkml]
> 
> Hi Mauro,
> 
> In case you are wondering what is going on in the update of
> selection.svg, here is a status report.
> 
> On Mon, 13 Dec 2021 16:53:07 +0900, Akira Yokosawa wrote:
> > On Mon, 13 Dec 2021 07:33:27 +0100, Mauro Carvalho Chehab wrote:  
> [...]
> >> No matter if this is merged or not, if you find an issue at the images
> >> at the media docs, please send them to linux-media@vger.org.  
> > 
> > OK. I'll compose a proper change log for it and post it later this
> > week or next.
> > (I'm not a type of person who is good at doing several things in
> > parallel.)  
> 
> I started the patch preparation, but I found the patch would be
> quite large in size (~500kB).
> 
> This is because current selection.svg consists of pretty high-
> resolution raster images.

No, it is not a raster image. That's why it scales so well.
Btw, the basis for this image is on this commit:

    commit 8032b526d1a3bd91ad633dd3a3b5fdbc47ad54f1
    Author: Rusty Russell <rusty@rustcorp.com.au>
    Date:   Mon Mar 16 09:05:07 2009 +1030

    linux.conf.au 2009: Tuz

> I see you had done several attempts to reduce the complexity of
> the SVG, but it is still large (> 200kB) 

One of the reasons why it is big is that the same vector image is added
there twice: the original one on the left, plus a second copy of it that
is scaled and has a clip group that hides the elements of it that aren't
visible at the image on the right.

> and conversion to PDF by
> convert(1) generates a PDF of more than 1MB!
> Even inkscape(1) generates a larger PDF (>1.3MB) with embedded
> raster images.

It doesn't matter the size of the output, provided that the image is
properly displayed on pdf and html.

> I don't believe what the figure wants to explain deserves such
> a large size.
> So, from my POV, adding another bitmap image to the SVG for the
> sake of browser compatibility is *not* the right thing to do.

I actually used a Tux-based svg image as basis because:

1. Tux (or Tuz, in this case) is well-known Linux image;
2. It is a nice image;
3. It was committed by another Kernel developer that already
   took care on having it properly licensed;
4. As this was merged to the Kernel already, it is under GPLv2.
5. It scales well on both html and pdf.

It could have used any other image, or I could have drawn a
random image, but, as I'm not good on drawing things and finding
something that won't cause a potential licensing and/or trade mark
headache could be tricky, I opted to use an already-merged Linux
image as basis.

> Instead, my suggestion would be to get rid of the embedded raster
> images and to draw some simple vector-graphics-based figure
> instead.

There were another image before selection.svg that used a simple
figure, but the cropped version didn't represent too well (IMHO).
That's why I opted to use a real figure, where you can see the
details of the image at the crop region.

I wouldn't mind replacing it with something else, but it should
be something that it won't cause licensing issues and will still
properly represent what selection does: crop, compose and scale.

> Am I missing something here?
> 
>         Thanks, Akira
> 
> > 
> > And the most easy fix is to install Inkscape on your system for
> > the daily build.
> > Then, convert(1) picks inkscape(1) for SVG rendering and you will
> > see right ones (of raster images, though).
> > 
> > You know, ImageMagick prefers inkscape over rsvg-convert.
> > I think it is the right thing to do in kfigure.py as well.
> >   
> [...]



Thanks,
Mauro

Re: Status of selection.svg update (was Re: [PATCH 0/3] docs: sphinx/kfigure.py: Improve conversion to PDF)

[Akira Yokosawa]

On Wed, 29 Dec 2021 23:14:24 +0100, Mauro Carvalho Chehab wrote:
> Em Wed, 29 Dec 2021 21:54:47 +0900
> Akira Yokosawa <akiyks@gmail.com> escreveu:
> 
>> [+Cc: linux-media, -Cc: lkml]
>>
>> Hi Mauro,
>>
>> In case you are wondering what is going on in the update of
>> selection.svg, here is a status report.
>>
>> On Mon, 13 Dec 2021 16:53:07 +0900, Akira Yokosawa wrote:
>>> On Mon, 13 Dec 2021 07:33:27 +0100, Mauro Carvalho Chehab wrote:  
>> [...]
>>>> No matter if this is merged or not, if you find an issue at the images
>>>> at the media docs, please send them to linux-media@vger.org.  
>>>
>>> OK. I'll compose a proper change log for it and post it later this
>>> week or next.
>>> (I'm not a type of person who is good at doing several things in
>>> parallel.)  
>>
>> I started the patch preparation, but I found the patch would be
>> quite large in size (~500kB).
>>
>> This is because current selection.svg consists of pretty high-
>> resolution raster images.
> 
> No, it is not a raster image. That's why it scales so well.

Ah, I was confused by the behavior of Inkscape.
Looking at the SVG source, which I am not that familiar with, it
has a ton of very long <path ...> objects.

I must have been more careful.

Sorry for the false blaming...  :-/

> Btw, the basis for this image is on this commit:
> 
>     commit 8032b526d1a3bd91ad633dd3a3b5fdbc47ad54f1
>     Author: Rusty Russell <rusty@rustcorp.com.au>
>     Date:   Mon Mar 16 09:05:07 2009 +1030
> 
>     linux.conf.au 2009: Tuz

So this logo.svg has the same issue when displayed in a browser.
I'm wondering if you could ask Rusty for some advice on this issue.

> 
>> I see you had done several attempts to reduce the complexity of
>> the SVG, but it is still large (> 200kB) 
> 
> One of the reasons why it is big is that the same vector image is added
> there twice: the original one on the left, plus a second copy of it that
> is scaled and has a clip group that hides the elements of it that aren't
> visible at the image on the right.
> 
>> and conversion to PDF by
>> convert(1) generates a PDF of more than 1MB!
>> Even inkscape(1) generates a larger PDF (>1.3MB) with embedded
>> raster images.
> 
> It doesn't matter the size of the output, provided that the image is
> properly displayed on pdf and html.

Well, I have noticed sluggish behavior of both browsers and PDF
viewers when this figure is displayed.  Not a big deal, though.

> 
>> I don't believe what the figure wants to explain deserves such
>> a large size.
>> So, from my POV, adding another bitmap image to the SVG for the
>> sake of browser compatibility is *not* the right thing to do.
> 
> I actually used a Tux-based svg image as basis because:
> 
> 1. Tux (or Tuz, in this case) is well-known Linux image;
> 2. It is a nice image;
> 3. It was committed by another Kernel developer that already
>    took care on having it properly licensed;
> 4. As this was merged to the Kernel already, it is under GPLv2.
> 5. It scales well on both html and pdf.
> 
> It could have used any other image, or I could have drawn a
> random image, but, as I'm not good on drawing things and finding
> something that won't cause a potential licensing and/or trade mark
> headache could be tricky, I opted to use an already-merged Linux
> image as basis.
> 
>> Instead, my suggestion would be to get rid of the embedded raster
>> images and to draw some simple vector-graphics-based figure
>> instead.
> 
> There were another image before selection.svg that used a simple
> figure, but the cropped version didn't represent too well (IMHO).
> That's why I opted to use a real figure, where you can see the
> details of the image at the crop region.
> 
> I wouldn't mind replacing it with something else, but it should
> be something that it won't cause licensing issues and will still
> properly represent what selection does: crop, compose and scale.

So I have no strong opinion WRT the figure.
I'm not going to post any updates for selection.svg.

        Thanks, Akira

> 
>> Am I missing something here?
>>
>>         Thanks, Akira
>>
>>>
>>> And the most easy fix is to install Inkscape on your system for
>>> the daily build.
>>> Then, convert(1) picks inkscape(1) for SVG rendering and you will
>>> see right ones (of raster images, though).
>>>
>>> You know, ImageMagick prefers inkscape over rsvg-convert.
>>> I think it is the right thing to do in kfigure.py as well.
>>>   
>> [...]
> 
> 
> 
> Thanks,
> Mauro
>