mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2026-09-22 09:34:56 +02:00
Jonathan Corbet
f647de4b02
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.
Linux kernel
============
There are several guides for kernel developers and users. These guides can
be rendered in a number of formats, like HTML and PDF. Please read
Documentation/admin-guide/README.rst first.
In order to build the documentation, use ``make htmldocs`` or
``make pdfdocs``. The formatted documentation can also be read online at:
https://www.kernel.org/doc/html/latest/
There are various text files in the Documentation/ subdirectory,
several of them using the Restructured Text markup notation.
Please read the Documentation/process/changes.rst file, as it contains the
requirements for building and running the kernel, and information about
the problems which may result by upgrading your kernel.