From: Jani Nikula <jani.nikula@intel.com>
To: Mauro Carvalho Chehab <mchehab@s-opensource.com>,
Jonathan Corbet <corbet@lwn.net>,
linux-kernel@vger.kernel.org, linux-media@vger.kernel.org
Cc: ksummit-discuss@lists.linuxfoundation.org, linux-doc@vger.kernel.org
Subject: Re: [Ksummit-discuss] Including images on Sphinx documents
Date: Mon, 07 Nov 2016 12:53:55 +0200 [thread overview]
Message-ID: <87wpgf8ssc.fsf@intel.com> (raw)
In-Reply-To: <20161107075524.49d83697@vento.lan>
On Mon, 07 Nov 2016, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> Hi Jon,
>
> I'm trying to sort out the next steps to do after KS, with regards to
> images included on RST files.
>
> The issue is that Sphinx image support highly depends on the output
> format. Also, despite TexLive support for svg and png images[1], Sphinx
> doesn't produce the right LaTeX commands to use svg[2]. On my tests
> with PNG on my notebook, it also didn't seem to do the right thing for
> PNG either. So, it seems that the only safe way to support images is
> to convert all of them to PDF for latex/pdf build.
>
> [1] On Fedora, via texlive-dvipng and texlive-svg
> [2] https://github.com/sphinx-doc/sphinx/issues/1907
>
> As far as I understand from KS, two decisions was taken:
>
> - We're not adding a sphinx extension to run generic commands;
> - The PDF images should be build in runtime from their source files
> (either svg or bitmap), and not ship anymore the corresponding
> PDF files generated from its source.
>
> As you know, we use several images at the media documentation:
> https://www.kernel.org/doc/html/latest/_images/
>
> Those images are tightly coupled with the explanation texts. So,
> maintaining them away from the documentation is not an option.
>
> I was originally thinking that adding a graphviz extension would solve the
> issue, but, in fact, most of the images aren't diagrams. Instead, there are
> several ones with images showing the result of passing certain parameters to
> the ioctls, explaining things like scale and cropping and how bytes are
> packed on some image formats.
>
> Linus proposed to call some image conversion tool like ImageMagick or
> inkscape to convert them to PDF when building the pdfdocs or latexdocs
> target at Makefile, but there's an issue with that: Sphinx doesn't read
> files from Documentation/output, and writing them directly at the
> source dir would be against what it is expected when the "O=" argument
> is passed to make.
>
> So, we have a few alternatives:
>
> 1) copy (or symlink) all rst files to Documentation/output (or to the
> build dir specified via O= directive) and generate the *.pdf there,
> and produce those converted images via Makefile.;
>
> 2) add an Sphinx extension that would internally call ImageMagick and/or
> inkscape to convert the bitmap;
>
> 3) if possible, add an extension to trick Sphinx for it to consider the
> output dir as a source dir too.
Looking at the available extensions, and the images to be displayed,
seems to me making svg work, somehow, is the right approach. (As opposed
to trying to represent the images in graphviz or whatnot.)
IIUC texlive supports displaying svg directly, but the problem is that
Sphinx produces bad latex for that. Can we make it work by manually
writing the latex? If yes, we wouldn't need to use an external tool to
convert the svg to something else, but rather fix the latex. Thus:
4a) See if this works:
.. only:: html
.. image:: foo.svg
.. raw:: latex
<the correct latex commands required to display foo.svg>
4b) Add a directive extension to make the above happen automatically.
Of course, the correct fix is to have this fixed in upstream Sphinx, but
as a workaround an extension doing the above seems plausible, and not
too much effort - provided that we can make the raw latex work.
BR,
Jani.
--
Jani Nikula, Intel Open Source Technology Center
next prev parent reply other threads:[~2016-11-07 10:54 UTC|newest]
Thread overview: 51+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-11-07 9:55 [Ksummit-discuss] Including images on Sphinx documents Mauro Carvalho Chehab
2016-11-07 10:53 ` Jani Nikula [this message]
2016-11-07 11:46 ` Mauro Carvalho Chehab
2016-11-07 17:05 ` Josh Triplett
2016-11-08 10:50 ` Mauro Carvalho Chehab
2016-11-16 16:03 ` Arnd Bergmann
2016-11-16 20:26 ` Mauro Carvalho Chehab
2016-11-17 11:07 ` Arnd Bergmann
2016-11-17 11:28 ` Jani Nikula
2016-11-17 12:39 ` Mauro Carvalho Chehab
2016-11-17 14:52 ` Theodore Ts'o
2016-11-17 15:16 ` Mauro Carvalho Chehab
2016-11-17 15:28 ` Johannes Berg
2016-11-17 16:25 ` James Bottomley
2016-11-17 15:32 ` Mauro Carvalho Chehab
2016-11-17 16:02 ` Linus Torvalds
2016-11-17 16:04 ` Linus Torvalds
2016-11-18 9:15 ` Jani Nikula
2016-11-18 10:23 ` Daniel Vetter
2016-11-19 17:15 ` Jonathan Corbet
2016-11-19 17:38 ` Andrew Lunn
2016-11-19 17:50 ` Bart Van Assche
2016-11-19 17:55 ` David Woodhouse
2016-11-19 18:45 ` Linus Torvalds
2016-11-19 22:59 ` David Woodhouse
2016-11-20 14:26 ` Mauro Carvalho Chehab
2016-11-19 20:54 ` Mauro Carvalho Chehab
2016-11-19 21:09 ` Linus Torvalds
2016-11-21 10:39 ` Johannes Berg
2016-11-21 14:06 ` Mauro Carvalho Chehab
2016-11-21 15:41 ` James Bottomley
2016-11-21 15:44 ` Johannes Berg
2016-11-21 15:47 ` Jani Nikula
2016-11-21 19:48 ` Mauro Carvalho Chehab
2016-11-13 21:00 ` Jonathan Corbet
2016-11-14 14:16 ` Mauro Carvalho Chehab
2016-11-09 12:27 ` Mauro Carvalho Chehab
2016-11-07 17:01 ` Josh Triplett
2016-11-09 9:22 ` Markus Heiser
2016-11-09 11:16 ` Jani Nikula
2016-11-09 11:27 ` Mauro Carvalho Chehab
2016-11-09 11:45 ` Jani Nikula
2016-11-09 11:27 ` Markus Heiser
2016-11-09 11:58 ` Jani Nikula
2016-11-09 22:11 ` Markus Heiser
2016-11-10 10:35 ` Jani Nikula
2016-11-11 11:22 ` Jani Nikula
2016-11-11 11:45 ` Markus Heiser
2016-11-11 9:34 ` Mauro Carvalho Chehab
2016-11-13 19:52 ` Jonathan Corbet
2016-11-14 13:30 ` Mauro Carvalho Chehab
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87wpgf8ssc.fsf@intel.com \
--to=jani.nikula@intel.com \
--cc=corbet@lwn.net \
--cc=ksummit-discuss@lists.linuxfoundation.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-media@vger.kernel.org \
--cc=mchehab@s-opensource.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).