1. 24 Feb, 2022 18 commits
  2. 17 Feb, 2022 1 commit
    • Jonathan Corbet's avatar
      Merge branch 'pdf' into docs-next · b62ef3a1
      Jonathan Corbet authored
      Akira says:
      
      This series resolves issues listed below:
      
       1. Some of chapter and section counts in Table of Contents (TOC) in
          large PDF docs collide with chapter/section titles, e.g., Chapters 10,
          11, 12, and 13 and Section 10.10 in userspace-api.pdf.
       2. In docs of more than 99 pages, page counts in TOC are not aligned
          properly when maxdepth >= 2 is specified in toctree, e.g., Chapters 10,
          12, and 13 in userspace-api.pdf
       3. In TOC of Latin-script docs, quotation and apostrophe symbols look too
          wide, e.g., Section 2.2 in userspace-api.pdf.
       4. In TOC of translations, Korean chapter titles lose inter-phrase spaces.
       5. On systems without "Noto Sans CJK" fonts, CJK chapters in translations
          results in full of "TOFU" boxes, with a long build time and a large
          log file containing lots of missing-font warnings.
       6. In translations.pdf built by "make pdfdocs", ascii-art diagrams in CJK
          are not aligned properly.
      b62ef3a1
  3. 15 Feb, 2022 10 commits
  4. 14 Feb, 2022 1 commit
  5. 10 Feb, 2022 5 commits
    • Jonathan Corbet's avatar
      Merge branch 'pdf-conversion' into docs-next · f647de4b
      Jonathan Corbet authored
      PDF-generation improvements from Akira Yokasawa; Akira says:
      
      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.
      f647de4b
    • Akira Yokosawa's avatar
      docs: sphinx/kfigure.py: Delegate inkscape msg to kernellog.verbose · f30a7ac8
      Akira Yokosawa authored
      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):
      
        - Gtk-Message: hh:mm:ss.nnn: Failed to load module "canberra-gtk-module"
        - Unable to init server: Could not connect: Connection refused
        - Failed to get connection
        - ** (inkscape:xxx): CRITICAL **: hh:mm:ss.nnn: dbus_g_proxy_new_for_name:
          assertion 'connection != NULL' failed
        - ** (inkscape:xxx): CRITICAL **: hh:mm:ss.nnn: dbus_g_proxy_call:
          assertion 'DBUS_IS_G_PROXY (proxy)' failed
        - ** (inkscape:xxx): CRITICAL **: hh:mm:ss.nnn: dbus_g_connection_register_g_object:
          assertion 'connection != NULL' failed
        - ** (inkscape:xxx): WARNING **: hh:mm:ss.nnn:
          Fonts dir '/usr/share/inkscape/fonts' does not exist and will be ignored.
      
      To avoid unnecessary anxiety, capture the message and output it via
      kernellog.verbose or kernellog.warn depending on the exit code.
      Signed-off-by: default avatarAkira Yokosawa <akiyks@gmail.com>
      Cc: Jonathan Corbet <corbet@lwn.net>
      Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
      Cc: Randy Dunlap <rdunlap@infradead.org>
      Link: https://lore.kernel.org/r/e26a7b53-9155-8394-4a31-6006379b65a5@gmail.comSigned-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      f30a7ac8
    • Akira Yokosawa's avatar
      docs: sphinx/kfigure.py: Use inkscape(1) for SVG -> PDF conversion · 8ccd0569
      Akira Yokosawa authored
      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 SVG files
      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 nor
          librsvg are not required.
      Signed-off-by: default avatarAkira Yokosawa <akiyks@gmail.com>
      Cc: Jonathan Corbet <corbet@lwn.net>
      Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
      Link: https://lore.kernel.org/r/3eea2a8d-c52d-ee07-cf7b-83784c6f6e4b@gmail.comSigned-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      8ccd0569
    • Akira Yokosawa's avatar
      docs: sphinx/kfigure.py: Add check of 'dot -Tpdf' · ecf5fb58
      Akira Yokosawa authored
      To prevent any regression on existing build systems, limit the
      fallback of converting DOT -> raster PDF only when both of the
      following conditions are met.
      
       o dot(1) doesn't support -Tpdf
       o rsvg-convert(1) is not found
      
      While we are here, add kernellog.verbose messages related to
      rsvg-convert, 'dot -Tpdf', and 'dot -Tsvg' commands.
      Suggested-by: default avatarMauro Carvalho Chehab <mchehab@kernel.org>
      Signed-off-by: default avatarAkira Yokosawa <akiyks@gmail.com>
      Cc: Jonathan Corbet <corbet@lwn.net>
      Link: https://lore.kernel.org/r/e76f61e1-7366-ba00-b119-8ea6a2499861@gmail.comSigned-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      ecf5fb58
    • Akira Yokosawa's avatar
      docs: sphinx/kfigure.py: Use rsvg-convert(1) for DOT -> PDF conversion · c9edbe1e
      Akira Yokosawa authored
      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.
      
      By using dot(1) for DOT -> SVG, then rsvg-convert(1) for SVG -> PDF,
      more optimal PDF images can be obtained, with the bonus of improved
      portability across various distros.
      
      Add rules in kfigure.py so that the above mentioned route is 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 depending 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 generated by dot(1) are converted nicely even with such
          old versions of rsvg-convert.
      
          So this change does not affect the quality of such figures in any
          way.
      Signed-off-by: default avatarAkira Yokosawa <akiyks@gmail.com>
      Cc: Jonathan Corbet <corbet@lwn.net>
      Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
      Link: https://lore.kernel.org/r/15b56dd3-081a-2469-c3a4-dfc1ca4c6c2d@gmail.comSigned-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      c9edbe1e
  6. 01 Feb, 2022 2 commits
  7. 27 Jan, 2022 3 commits