Including images on Sphinx documents

Including images on Sphinx documents

[Mauro Carvalho Chehab]

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.

Comments?

Regards,
Mauro

Re: Including images on Sphinx documents

[Jani Nikula]

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

Re: Including images on Sphinx documents

[Mauro Carvalho Chehab]

Em Mon, 07 Nov 2016 12:53:55 +0200
Jani Nikula <jani.nikula@intel.com> escreveu:

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

It might be possible, if we write something at the LaTeX preamble
that would replace \includegraphics by something that would, instead,
use \includesvg, if the image is in SVG format. However, I don't know
enough about LaTeX to write such macro.

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

This may work, although it would prevent forever the usage of some
extension to auto-numerate images and to cross-reference them.

That's said, PNG also doesn't seem to work fine on Sphinx 1.4.x.

On my tests, I installed *all* texlive extensions on Fedora 24, to
be sure that the issue is not the lack of some extension[1], with:

	# dnf install $(sudo dnf search texlive |grep all|cut -d. -f 1|grep texlive-)

When running LaTeX in interactive mode, building just the media
PDF file with:

	$ cls;make cleandocs; make SPHINXOPTS="-j5" DOCBOOKS="" SPHINXDIRS=media latexdocs 
	$ PDFLATEX=xelatex LATEXOPTS="-interaction=interactive" -C Documentation/output/media/latex

I get this:

	LaTeX Warning: Hyper reference `uapi/v4l/subdev-formats:bayer-patterns' on page
	 153 undefined on input line 21373.

	<use  "bayer.png" > [153]
	! Extra alignment tab has been changed to \cr.
	<template> \endtemplate 
                        
	l.21429 \unskip}\relax \unskip}
	                               \relax \\
	? 

This patch fixes the issue:
	https://git.linuxtv.org/mchehab/experimental.git/commit/?h=dirty-pdf&id=b709de415f34d77cc121cad95bece9c7ef4d12fd

That means that Sphinx is not generating the right LaTeX output even for
(some?) PNG images.

[1] On a side note, installing texlive-texliveonfly didn't made much
difference... I still had to manually install a lot of texlive extensions
for LaTeX build to work on Fedora. It seems that texliveonfly only solved
automatically font dependencies.

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

If we're adding an extension, IMHO, it is better to do the format
conversion inside the extension. From what I understood, texlive
will still require inkscape to be installed in order for the SVG
support to work:
	https://tex.stackexchange.com/questions/122871/include-svg-images-with-the-svg-package

And it may even require "--shell-escape" to be passed at the xelatex
call if inkscape is not in the path, with seems to be a strong
indication that SVG support is not native to texlive, but, instead,
just a way to make LaTeX to call inkscape to do the image conversion.

Regards,
Mauro

Re: [Ksummit-discuss] Including images on Sphinx documents

[Josh Triplett]

On Mon, Nov 07, 2016 at 07:55:24AM -0200, Mauro Carvalho Chehab wrote:
> 2) add an Sphinx extension that would internally call ImageMagick and/or
>    inkscape to convert the bitmap;

This seems sensible; Sphinx should directly handle the source format we
want to use for images/diagrams.

> 3) if possible, add an extension to trick Sphinx for it to consider the 
>    output dir as a source dir too.

Or to provide an additional source path and point that at the output
directory.

Re: [Ksummit-discuss] Including images on Sphinx documents

[Josh Triplett]

On Mon, Nov 07, 2016 at 09:46:48AM -0200, Mauro Carvalho Chehab wrote:
> That's said, PNG also doesn't seem to work fine on Sphinx 1.4.x.
> 
> On my tests, I installed *all* texlive extensions on Fedora 24, to
> be sure that the issue is not the lack of some extension[1], with:
> 
> 	# dnf install $(sudo dnf search texlive |grep all|cut -d. -f 1|grep texlive-)
> 
> When running LaTeX in interactive mode, building just the media
> PDF file with:
> 
> 	$ cls;make cleandocs; make SPHINXOPTS="-j5" DOCBOOKS="" SPHINXDIRS=media latexdocs 
> 	$ PDFLATEX=xelatex LATEXOPTS="-interaction=interactive" -C Documentation/output/media/latex
> 
> I get this:
> 
> 	LaTeX Warning: Hyper reference `uapi/v4l/subdev-formats:bayer-patterns' on page
> 	 153 undefined on input line 21373.
> 
> 	<use  "bayer.png" > [153]
> 	! Extra alignment tab has been changed to \cr.
> 	<template> \endtemplate 
>                         
> 	l.21429 \unskip}\relax \unskip}
> 	                               \relax \\
> 	? 
> 
> This patch fixes the issue:
> 	https://git.linuxtv.org/mchehab/experimental.git/commit/?h=dirty-pdf&id=b709de415f34d77cc121cad95bece9c7ef4d12fd
> 
> That means that Sphinx is not generating the right LaTeX output even for
> (some?) PNG images.

\includegraphics normally works just fine for PNG images in PDF
documents.

[...]
> And it may even require "--shell-escape" to be passed at the xelatex
> call if inkscape is not in the path, with seems to be a strong
> indication that SVG support is not native to texlive, but, instead,
> just a way to make LaTeX to call inkscape to do the image conversion.

Please don't require --shell-escape as part of the TeX workflow.  If
LaTeX can't handle the desired image format natively, it needs
conversion in advance.

- Josh Triplett

Re: [Ksummit-discuss] Including images on Sphinx documents

[Mauro Carvalho Chehab]

Em Mon, 7 Nov 2016 09:05:05 -0800
Josh Triplett <josh@joshtriplett.org> escreveu:

> On Mon, Nov 07, 2016 at 09:46:48AM -0200, Mauro Carvalho Chehab wrote:
> > That's said, PNG also doesn't seem to work fine on Sphinx 1.4.x.
> > 
> > On my tests, I installed *all* texlive extensions on Fedora 24, to
> > be sure that the issue is not the lack of some extension[1], with:
> > 
> > 	# dnf install $(sudo dnf search texlive |grep all|cut -d. -f 1|grep texlive-)
> > 
> > When running LaTeX in interactive mode, building just the media
> > PDF file with:
> > 
> > 	$ cls;make cleandocs; make SPHINXOPTS="-j5" DOCBOOKS="" SPHINXDIRS=media latexdocs 
> > 	$ PDFLATEX=xelatex LATEXOPTS="-interaction=interactive" -C Documentation/output/media/latex
> > 
> > I get this:
> > 
> > 	LaTeX Warning: Hyper reference `uapi/v4l/subdev-formats:bayer-patterns' on page
> > 	 153 undefined on input line 21373.
> > 
> > 	<use  "bayer.png" > [153]
> > 	! Extra alignment tab has been changed to \cr.
> > 	<template> \endtemplate 
> >                         
> > 	l.21429 \unskip}\relax \unskip}
> > 	                               \relax \\
> > 	? 
> > 
> > This patch fixes the issue:
> > 	https://git.linuxtv.org/mchehab/experimental.git/commit/?h=dirty-pdf&id=b709de415f34d77cc121cad95bece9c7ef4d12fd
> > 
> > That means that Sphinx is not generating the right LaTeX output even for
> > (some?) PNG images.  
> 
> \includegraphics normally works just fine for PNG images in PDF
> documents.

I didn't try to fix the Sphinx output in LaTeX format when a PNG
image is used, but, from the above log, clearly it did something
wrong. Perhaps there's something bad defined at the sphinx.sty file,
or it simply generates the wrong LaTeX code when the image
is not on PDF format.

> [...]
> > And it may even require "--shell-escape" to be passed at the xelatex
> > call if inkscape is not in the path, with seems to be a strong
> > indication that SVG support is not native to texlive, but, instead,
> > just a way to make LaTeX to call inkscape to do the image conversion.  
> 
> Please don't require --shell-escape as part of the TeX workflow.  If
> LaTeX can't handle the desired image format natively, it needs
> conversion in advance.

Agreed. I sent a patch series to linux-doc, doing the conversion in
advance:
	https://marc.info/?l=linux-doc&m=147859902804144&w=2

Not sure why, but the archives don't have all patches yet.
Anyway, the relevant one is this:
	https://git.linuxtv.org/mchehab/experimental.git/commit/?h=pdf-fixes&id=5d41c452c787f6a6c755a3855312435bc439acb8

It basically calls ImageMagick "convert" tool for all png and
pdf files currently at the documentation (they're all at media,
ATM).
	

Thanks,
Mauro

Re: [Ksummit-discuss] Including images on Sphinx documents

[Markus Heiser]

Am 07.11.2016 um 18:01 schrieb Josh Triplett <josh@joshtriplett.org>:

> On Mon, Nov 07, 2016 at 07:55:24AM -0200, Mauro Carvalho Chehab wrote:
>> 2) add an Sphinx extension that would internally call ImageMagick and/or
>>  inkscape to convert the bitmap;
> 
> This seems sensible; Sphinx should directly handle the source format we
> want to use for images/diagrams.
> 
>> 3) if possible, add an extension to trick Sphinx for it to consider the 
>>  output dir as a source dir too.
> 
> Or to provide an additional source path and point that at the output
> directory.

The sphinx-build command excepts only one 'sourcedir' argument. All
reST files in this folder (and below) are parsed.

Most (all?) directives which include content like images or literalinclude
except only relative pathnames. Where *relative* means, relative to the
reST file where the directive is used. For security reasons relative 
pathnames outside 'sourcepath' are not excepted.

So I vote for :

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

Placing reST files together with the *autogenerated* (intermediate) 
content from

* image conversions,
* reST content build from MAINTAINERS,
* reST content build for ABI
* etc.

has the nice side effect, that we can get rid of all theses BUILDDIR
quirks in the Makefile.sphinx

Additional, we can write Makefile targets to build the above listed
intermediate content relative to the $PWD, which is what Linux's
Makefiles usual do (instead of quirking with a BUILDDIR).

E.g. with, we can also get rid of the 'kernel-include' directive 
and replace it, with Sphinx's common 'literaliclude' and we do not
need any extensions to include intermediate PDFs or whatever
intermediate content we might want to generate. 

IMO placing 'sourcedir' to O= is more sane since this marries the
Linux Makefile concept (relative to $PWD) with the sphinx concept
(in or below 'sourcedir').


-- Markus --

Re: [Ksummit-discuss] Including images on Sphinx documents

[Jani Nikula]

On Wed, 09 Nov 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
> Am 07.11.2016 um 18:01 schrieb Josh Triplett <josh@joshtriplett.org>:
>
>> On Mon, Nov 07, 2016 at 07:55:24AM -0200, Mauro Carvalho Chehab wrote:
>>> 2) add an Sphinx extension that would internally call ImageMagick and/or
>>>  inkscape to convert the bitmap;
>> 
>> This seems sensible; Sphinx should directly handle the source format we
>> want to use for images/diagrams.
>> 
>>> 3) if possible, add an extension to trick Sphinx for it to consider the 
>>>  output dir as a source dir too.
>> 
>> Or to provide an additional source path and point that at the output
>> directory.
>
> The sphinx-build command excepts only one 'sourcedir' argument. All
> reST files in this folder (and below) are parsed.
>
> Most (all?) directives which include content like images or literalinclude
> except only relative pathnames. Where *relative* means, relative to the
> reST file where the directive is used. For security reasons relative 
> pathnames outside 'sourcepath' are not excepted.
>
> So I vote for :
>
>> 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.;

We're supposed to solve problems, not create new ones.

> Placing reST files together with the *autogenerated* (intermediate) 
> content from
>
> * image conversions,
> * reST content build from MAINTAINERS,
> * reST content build for ABI
> * etc.
>
> has the nice side effect, that we can get rid of all theses BUILDDIR
> quirks in the Makefile.sphinx
>
> Additional, we can write Makefile targets to build the above listed
> intermediate content relative to the $PWD, which is what Linux's
> Makefiles usual do (instead of quirking with a BUILDDIR).
>
> E.g. with, we can also get rid of the 'kernel-include' directive 
> and replace it, with Sphinx's common 'literaliclude' and we do not
> need any extensions to include intermediate PDFs or whatever
> intermediate content we might want to generate. 

Well, kernel-include is a hack to make parse-headers.pl work, which is
also a hack that IMHO shouldn't exist...

> IMO placing 'sourcedir' to O= is more sane since this marries the
> Linux Makefile concept (relative to $PWD) with the sphinx concept
> (in or below 'sourcedir').
>
>
> -- Markus --
>
>
> --
> To unsubscribe from this list: send the line "unsubscribe linux-doc" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

-- 
Jani Nikula, Intel Open Source Technology Center

Re: [Ksummit-discuss] Including images on Sphinx documents

[Mauro Carvalho Chehab]

Em Wed, 09 Nov 2016 13:16:55 +0200
Jani Nikula <jani.nikula@linux.intel.com> escreveu:

> >> 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.;  
> 
> We're supposed to solve problems, not create new ones.

So, what's your proposal?

Thanks,
Mauro

Re: [Ksummit-discuss] Including images on Sphinx documents

[Markus Heiser]

Am 09.11.2016 um 12:16 schrieb Jani Nikula <jani.nikula@linux.intel.com>:
>> So I vote for :
>> 
>>> 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.;
> 
> We're supposed to solve problems, not create new ones.

... new ones? ...

>> IMO placing 'sourcedir' to O= is more sane since this marries the
>> Linux Makefile concept (relative to $PWD) with the sphinx concept
>> (in or below 'sourcedir').

-- Markus --

Re: [Ksummit-discuss] Including images on Sphinx documents

[Jani Nikula]

On Wed, 09 Nov 2016, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> Em Wed, 09 Nov 2016 13:16:55 +0200
> Jani Nikula <jani.nikula@linux.intel.com> escreveu:
>
>> >> 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.;  
>> 
>> We're supposed to solve problems, not create new ones.
>
> So, what's your proposal?

Second message in the thread,
http://lkml.kernel.org/r/87wpgf8ssc.fsf@intel.com

>
> Thanks,
> Mauro
> _______________________________________________
> Ksummit-discuss mailing list
> Ksummit-discuss@lists.linuxfoundation.org
> https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss

-- 
Jani Nikula, Intel Open Source Technology Center

Re: [Ksummit-discuss] Including images on Sphinx documents

[Jani Nikula]

On Wed, 09 Nov 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
> Am 09.11.2016 um 12:16 schrieb Jani Nikula <jani.nikula@linux.intel.com>:
>>> So I vote for :
>>> 
>>>> 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.;
>> 
>> We're supposed to solve problems, not create new ones.
>
> ... new ones? ...

Handle in-tree builds without copying.

Make dependency analysis with source rst and "intermediate" rst work.

Make sure your copying gets the timestamps right.

Make Sphinx dependency analysis look at the right copies depending on
in-tree vs. out-of-tree. Generally make sure it doesn't confuse Sphinx's
own dependency analysis.

The stuff I didn't think of.

Sure, it's all supposed to be basic Makefile stuff, but don't make the
mistake of thinking just one invocation of 'cp' will solve all the
problems. It all adds to the complexity we were trying to avoid when
dumping DocBook. It adds to the complexity of debugging stuff. (And hey,
there's still the one rebuilding-stuff-for-no-reason issue open.)

If you want to keep the documentation build sane, try to avoid the
Makefile preprocessing. And same old story, if you fix this for real,
even if as a Sphinx extension, *other* people than kernel developers
will be interested, and *we* don't have to do so much ourselves.


BR,
Jani.



>
>>> IMO placing 'sourcedir' to O= is more sane since this marries the
>>> Linux Makefile concept (relative to $PWD) with the sphinx concept
>>> (in or below 'sourcedir').
>
> -- Markus --

-- 
Jani Nikula, Intel Open Source Technology Center

Re: Including images on Sphinx documents

[Mauro Carvalho Chehab]

Em Mon, 07 Nov 2016 12:53:55 +0200
Jani Nikula <jani.nikula@intel.com> escreveu:

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

I guess answered this one already, but it got lost somehow...

The problem is not just with svg. Sphinx also do the wrong thing with
PNG, despite apparently generating the right LaTeX image include command.

> 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

We're currently using .. figure:: instead, as it allow optional caption
and legend, but I got the idea.

> .. raw:: latex
> 
>    <the correct latex commands required to display foo.svg>

That is a horrible hack, and will lose other attributes at
image:: (or figure::), like :align:

Also, it won't solve, as the images will need to be copied to the
build dir via Makefile, as Spinx only copies the images it recognizes.

So, in practice, the only difference is that Makefile would be calling
"cp" instead of "convert", plus we'll have to hack all ReST sources.

> 4b) Add a directive extension to make the above happen automatically.

If doable, I agree that this is the best solution. Any volunteers to write
such extension?

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

Yeah, fixing it on Sphinx upstream would be the best, but we'll still
need to maintain the workaround for a while for the unpatched versions
of Sphinx.

Thanks,
Mauro

Re: [Ksummit-discuss] Including images on Sphinx documents

[Markus Heiser]

On 09.11.2016 12:58, Jani Nikula wrote:
 > On Wed, 09 Nov 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
 >> Am 09.11.2016 um 12:16 schrieb Jani Nikula <jani.nikula@linux.intel.com>:
 >>>> So I vote for :
 >>>>
 >>>>> 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.;
 >>>
 >>> We're supposed to solve problems, not create new ones.
 >>
 >> ... new ones? ...
 >
 > Handle in-tree builds without copying.
 >
 > Make dependency analysis with source rst and "intermediate" rst work.
 >
 > Make sure your copying gets the timestamps right.
 >
 > Make Sphinx dependency analysis look at the right copies depending on
 > in-tree vs. out-of-tree. Generally make sure it doesn't confuse Sphinx's
 > own dependency analysis.
 >
 > The stuff I didn't think of.

It might be easier than you think first.

 > Sure, it's all supposed to be basic Makefile stuff, but don't make the mistake
 > of thinking just one invocation of 'cp' will solve all the problems.

I act naif using 'cp -sa', see patch below.

 > It all adds to the complexity we were trying to avoid when dumping DocBook. It
 > adds to the complexity of debugging stuff. (And hey, there's still the one
 > rebuilding-stuff-for-no-reason issue open.)

And hey ;-) I wrote you [1], this is a bug in Sphinx. Yes, I haven't had time
to send a bugfix to Sphinx, but this won't even help us (bugfixes in Sphinx will
only apply on top).

 > If you want to keep the documentation build sane, try to avoid the Makefile
 > preprocessing.

I'am just the one helping Mauro to be productive, if he needs preprocessing I
implement proposals. I know that you fear preprocessing since it tend to
fall-back, what we had with DocBook's build process.  We discussed this already,
it might better you unify this with Mauro and the other who need preprocessing.

 > And same old story, if you fix this for real, even if as a Sphinx extension,
 > *other* people than kernel developers will be interested, and *we* don't have
 > to do so much ourselves.

I don't think so, this kind of parsing header files we have and the build of
content from MAINTAINERS, ABI, etc. is very kernel specific.

Anyway, back to my point 'copy (or symlink) all rst files'. Please take a look
at my patch below. Take in mind; its just a POC.

Could this POC persuade you, if so, I send a more elaborate RFC,
what do you think about?

[1] https://www.mail-archive.com/linux-doc@vger.kernel.org/msg07302.html

-- Markus --

 > BR,
 > Jani.
 >>
 >>>> IMO placing 'sourcedir' to O= is more sane since this marries the
 >>>> Linux Makefile concept (relative to $PWD) with the sphinx concept
 >>>> (in or below 'sourcedir').
 >>
 >> -- Markus --
 >

diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
index ec0c77d..8e904c1 100644
--- a/Documentation/Makefile.sphinx
+++ b/Documentation/Makefile.sphinx
@@ -13,6 +13,10 @@ BUILDDIR      = $(obj)/output
  PDFLATEX      = xelatex
  LATEXOPTS     = -interaction=batchmode

+ifdef SPHINXDIRS
+else
+endif
+
  # User-friendly check for sphinx-build
  HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)

@@ -50,30 +54,38 @@ loop_cmd = $(echo-cmd) $(cmd_$(1))
  #    * dest folder relative to $(BUILDDIR) and
  #    * cache folder relative to $(BUILDDIR)/.doctrees
  # $4 dest subfolder e.g. "man" for man pages at media/man
-# $5 reST source folder relative to $(srctree)/$(src),
+# $5 reST source folder relative to $(obj),
  #    e.g. "media" for the linux-tv book-set at ./Documentation/media

  quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
-      cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media all;\
-	BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
+      cmd_sphinx = $(MAKE) BUILDDIR=$(BUILDDIR) $(build)=Documentation/media all;\
+	BUILDDIR=$(BUILDDIR) SPHINX_CONF=$(obj)/$5/$(SPHINX_CONF) \
  	$(SPHINXBUILD) \
  	-b $2 \
-	-c $(abspath $(srctree)/$(src)) \
-	-d $(abspath $(BUILDDIR)/.doctrees/$3) \
+	-c $(obj) \
+	-d $(obj)/.doctrees/$3 \
  	-D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \
  	$(ALLSPHINXOPTS) \
-	$(abspath $(srctree)/$(src)/$5) \
-	$(abspath $(BUILDDIR)/$3/$4);
-
-htmldocs:
+	$(obj)/$5 \
+	$(BUILDDIR)/$3/$4;
+
+ifdef O
+sync:
+	rm -rf $(objtree)/$(obj)
+	cp -sa $(srctree)/$(obj) $(objtree)
+else
+sync:
+endif
+
+htmldocs: sync
  	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))

-latexdocs:
+latexdocs: sync
  	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))

  ifeq ($(HAVE_PDFLATEX),0)

-pdfdocs:
+pdfdocs: sync
  	$(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
  	@echo "  SKIP    Sphinx $@ target."

@@ -84,10 +96,10 @@ pdfdocs: latexdocs

  endif # HAVE_PDFLATEX

-epubdocs:
+epubdocs: sync
  	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))

-xmldocs:
+xmldocs: sync
  	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))

  # no-ops for the Sphinx toolchain
@@ -98,6 +110,7 @@ installmandocs:

  cleandocs:
  	$(Q)rm -rf $(BUILDDIR)
+	$(Q)rm -rf $(obj)/.doctrees

  endif # HAVE_SPHINX

Re: [Ksummit-discuss] Including images on Sphinx documents

[Jani Nikula]

On Thu, 10 Nov 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
> Could this POC persuade you, if so, I send a more elaborate RFC,
> what do you think about?

Sorry, I do not wish to be part of this.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center

Re: [Ksummit-discuss] Including images on Sphinx documents

[Mauro Carvalho Chehab]

Em Wed, 09 Nov 2016 13:58:12 +0200
Jani Nikula <jani.nikula@linux.intel.com> escreveu:

> On Wed, 09 Nov 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
> > Am 09.11.2016 um 12:16 schrieb Jani Nikula <jani.nikula@linux.intel.com>:  
> >>> So I vote for :
> >>>   
> >>>> 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.;  
> >> 
> >> We're supposed to solve problems, not create new ones.  
> >
> > ... new ones? ...  
> 
> Handle in-tree builds without copying.
> 
> Make dependency analysis with source rst and "intermediate" rst work.
> 
> Make sure your copying gets the timestamps right.
> 
> Make Sphinx dependency analysis look at the right copies depending on
> in-tree vs. out-of-tree. Generally make sure it doesn't confuse Sphinx's
> own dependency analysis.

I agree with Jani here: copy the files will make Sphinx recompile
the entire documentation every time, with is bad. Ok, Some Makefile
logic could be added to copy only on changes, but that will increase
the Makefile complexity.

So, I prefer not using copy. As I said before, a Sphinx extension that
would make transparent for PDF document generation when a non-PDF image
is included, doing whatever conversion needed, seems to be the right fix 
here, but someone would need to step up and write such extension.

-- 

Cheers,
Mauro

Re: [Ksummit-discuss] Including images on Sphinx documents

[Jani Nikula]

On Thu, 10 Nov 2016, Jani Nikula <jani.nikula@linux.intel.com> wrote:
> On Thu, 10 Nov 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
>> Could this POC persuade you, if so, I send a more elaborate RFC,
>> what do you think about?
>
> Sorry, I do not wish to be part of this.

That was uncalled for, apologies.

Like I said, I don't think this is the right approach. Call it an
unsubstantiated gut feel coming from experience. However, I do not have
the time to properly dig into this either, and that frustrates me. I
wish I could be more helpful, but I can't right now.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center

Re: [Ksummit-discuss] Including images on Sphinx documents

[Markus Heiser]

Am 11.11.2016 um 12:22 schrieb Jani Nikula <jani.nikula@linux.intel.com>:

> On Thu, 10 Nov 2016, Jani Nikula <jani.nikula@linux.intel.com> wrote:
>> On Thu, 10 Nov 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
>>> Could this POC persuade you, if so, I send a more elaborate RFC,
>>> what do you think about?
>> 
>> Sorry, I do not wish to be part of this.
> 
> That was uncalled for, apologies.

It's OK, sometimes we are all in a hurry and want shorten things.

> Like I said, I don't think this is the right approach. Call it an
> unsubstantiated gut feel coming from experience.

Yes, building a bunch of symbolic links "smells". Unfortunately,
I currently see no other solution to solve the conflict of 
Linux's "O=/foo" and Sphinx's "sourcedir", so that was my
proposal.

> However, I do not have
> the time to properly dig into this either, and that frustrates me. I
> wish I could be more helpful, but I can't right now.

its a pity

-- Markus --

Re: Including images on Sphinx documents

[Jonathan Corbet]

On Mon, 7 Nov 2016 07:55:24 -0200
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

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

So, obviously, I've been letting this go by while dealing with other
stuff...

I really think that 2) is the one we want.  Copying all the stuff and
operating on the copies, beyond being a bit of a hack, just seems like a
recipe for weird build problems in the future.

We should figure out why PNG files don't work.  Maybe I'll give that a
try at some point soon, if I can find a moment.  Working around tools
bugs seems like the wrong approach.

Working from .svg seems optimial, but I don't like the --shell-escape
thing at all.

[Along those lines, we've picked up a lot of lines like this:

	 restricted \write18 enabled.

That, too, is shell execution stuff.  I've not been able to figure out
where it came from, but I would sure like to get rid of it...]

jon

Re: Including images on Sphinx documents

[Jonathan Corbet]

On Mon, 7 Nov 2016 09:46:48 -0200
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> When running LaTeX in interactive mode, building just the media
> PDF file with:
> 
> 	$ cls;make cleandocs; make SPHINXOPTS="-j5" DOCBOOKS="" SPHINXDIRS=media latexdocs 
> 	$ PDFLATEX=xelatex LATEXOPTS="-interaction=interactive" -C Documentation/output/media/latex
> 
> I get this:
> 
> 	LaTeX Warning: Hyper reference `uapi/v4l/subdev-formats:bayer-patterns' on page
> 	 153 undefined on input line 21373.
> 
> 	<use  "bayer.png" > [153]
> 	! Extra alignment tab has been changed to \cr.
> 	<template> \endtemplate 
>                         
> 	l.21429 \unskip}\relax \unskip}
> 	                               \relax \\
> 	? 
> 
> This patch fixes the issue:
> 	https://git.linuxtv.org/mchehab/experimental.git/commit/?h=dirty-pdf&id=b709de415f34d77cc121cad95bece9c7ef4d12fd
> 
> That means that Sphinx is not generating the right LaTeX output even for
> (some?) PNG images.

So I'm seriously confused.

I can get that particular message - TeX is complaining about too many
columns in the table.  But applying your patch (with a suitable bayer.pdf
provided) does not fix the problem.  Indeed, I can remove the figure with
the image entirely and still not fix the problem.  Are you sure that the
patch linked here actually fixed it for you?

jon

Re: Including images on Sphinx documents

[Mauro Carvalho Chehab]

Em Sun, 13 Nov 2016 12:52:50 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Mon, 7 Nov 2016 07:55:24 -0200
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > 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.  
> 
> So, obviously, I've been letting this go by while dealing with other
> stuff...
> 
> I really think that 2) is the one we want.  Copying all the stuff and
> operating on the copies, beyond being a bit of a hack, just seems like a
> recipe for weird build problems in the future.

Yes, (2) sounds to be the best option.

> We should figure out why PNG files don't work.  Maybe I'll give that a
> try at some point soon, if I can find a moment.  Working around tools
> bugs seems like the wrong approach.

I appreciate any efforts on that.

> Working from .svg seems optimial, but I don't like the --shell-escape
> thing at all.
> 
> [Along those lines, we've picked up a lot of lines like this:
> 
> 	 restricted \write18 enabled.
> 
> That, too, is shell execution stuff.  I've not been able to figure out
> where it came from, but I would sure like to get rid of it...]

Didn't know that! I'm new to LaTeX. Frankly, the log output sounds
very scary to me, as there are lots of warnings there, and debugging
each of them takes time. I don't see any \write18 inside the generated
.tex files or inside the sphinx.sty file. Perhaps it comes from some
Tex extension, like adjustbox?

> 
> jon



Thanks,
Mauro

Re: Including images on Sphinx documents

[Mauro Carvalho Chehab]

Em Sun, 13 Nov 2016 14:00:27 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Mon, 7 Nov 2016 09:46:48 -0200
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > When running LaTeX in interactive mode, building just the media
> > PDF file with:
> > 
> > 	$ cls;make cleandocs; make SPHINXOPTS="-j5" DOCBOOKS="" SPHINXDIRS=media latexdocs 
> > 	$ PDFLATEX=xelatex LATEXOPTS="-interaction=interactive" -C Documentation/output/media/latex
> > 
> > I get this:
> > 
> > 	LaTeX Warning: Hyper reference `uapi/v4l/subdev-formats:bayer-patterns' on page
> > 	 153 undefined on input line 21373.
> > 
> > 	<use  "bayer.png" > [153]
> > 	! Extra alignment tab has been changed to \cr.
> > 	<template> \endtemplate 
> >                         
> > 	l.21429 \unskip}\relax \unskip}
> > 	                               \relax \\
> > 	? 
> > 
> > This patch fixes the issue:
> > 	https://git.linuxtv.org/mchehab/experimental.git/commit/?h=dirty-pdf&id=b709de415f34d77cc121cad95bece9c7ef4d12fd
> > 
> > That means that Sphinx is not generating the right LaTeX output even for
> > (some?) PNG images.  
> 
> So I'm seriously confused.
> 
> I can get that particular message - TeX is complaining about too many
> columns in the table.  But applying your patch (with a suitable bayer.pdf
> provided) does not fix the problem.  Indeed, I can remove the figure with
> the image entirely and still not fix the problem.  Are you sure that the
> patch linked here actually fixed it for you?

There are two patches on the series fixing the column issues for the Bayer
formats table on the /6 patch series.

I guess I got confused with that, because of this warning:

 	LaTeX Warning: Hyper reference `uapi/v4l/subdev-formats:bayer-patterns' on page
 	 153 undefined on input line 21373.

Anyway, you're right: PNG is indeed working fine[1], and the
cross-reference is OK. The issue is just with SVG.

I'll fold it with patch 6/6 and submit a new series.

Sorry for the mess.

[1] I tested now on sphinx 1.4.8 - I was using an older version
before (1.4.5, I guess).

Thanks,
Mauro

[PATCH] docs-rst: Let Sphinx do PNG image conversion

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
index 0f08bd8b87ba..297b85c37ab9 100644
--- a/Documentation/media/Makefile
+++ b/Documentation/media/Makefile
@@ -12,17 +12,6 @@ TARGETS := $(addprefix $(BUILDDIR)/, $(FILES))
 
 IMAGES = \
 	typical_media_device.svg \
-	uapi/v4l/fieldseq_tb.png \
-	uapi/v4l/selection.png \
-	uapi/v4l/vbi_hsync.png \
-	uapi/v4l/fieldseq_bt.png \
-	uapi/v4l/crop.png \
-	uapi/v4l/nv12mt.png \
-	uapi/v4l/vbi_525.png \
-	uapi/v4l/nv12mt_example.png \
-	uapi/v4l/vbi_625.png \
-	uapi/v4l/pipeline.png \
-	uapi/v4l/bayer.png \
 	uapi/dvb/dvbstb.svg \
 	uapi/v4l/constraints.svg \
 	uapi/v4l/subdev-image-processing-full.svg \
@@ -37,8 +26,6 @@ cmd = $(echo-cmd) $(cmd_$(1))
 quiet_cmd_genpdf = GENPDF  $2
       cmd_genpdf = convert $2 $3
 
-%.pdf: %.png
-	@$(call cmd,genpdf,$<,$@)
 %.pdf: %.svg
 	@$(call cmd,genpdf,$<,$@)
 
diff --git a/Documentation/media/uapi/v4l/crop.rst b/Documentation/media/uapi/v4l/crop.rst
index 31c5ba5ebd04..578c6f3d20f3 100644
--- a/Documentation/media/uapi/v4l/crop.rst
+++ b/Documentation/media/uapi/v4l/crop.rst
@@ -53,8 +53,8 @@ Cropping Structures
 
 .. _crop-scale:
 
-.. figure::  crop.*
-    :alt:    crop.pdf / crop.png
+.. figure::  crop.png
+    :alt:    crop.png
     :align:  center
 
     Image Cropping, Insertion and Scaling
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi.rst b/Documentation/media/uapi/v4l/dev-raw-vbi.rst
index fb4d9c4098a0..f81d906137ee 100644
--- a/Documentation/media/uapi/v4l/dev-raw-vbi.rst
+++ b/Documentation/media/uapi/v4l/dev-raw-vbi.rst
@@ -221,8 +221,8 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does
 
 .. _vbi-hsync:
 
-.. figure::  vbi_hsync.*
-    :alt:    vbi_hsync.pdf / vbi_hsync.png
+.. figure::  vbi_hsync.png
+    :alt:    vbi_hsync.png
     :align:  center
 
     **Figure 4.1. Line synchronization**
@@ -230,8 +230,8 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does
 
 .. _vbi-525:
 
-.. figure::  vbi_525.*
-    :alt:    vbi_525.pdf / vbi_525.png
+.. figure::  vbi_525.png
+    :alt:    vbi_525.png
     :align:  center
 
     **Figure 4.2. ITU-R 525 line numbering (M/NTSC and M/PAL)**
@@ -240,8 +240,8 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does
 
 .. _vbi-625:
 
-.. figure::  vbi_625.*
-    :alt:    vbi_625.pdf / vbi_625.png
+.. figure::  vbi_625.png
+    :alt:    vbi_625.png
     :align:  center
 
     **Figure 4.3. ITU-R 625 line numbering**
diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst
index b515424b3949..c18e9c5427ee 100644
--- a/Documentation/media/uapi/v4l/dev-subdev.rst
+++ b/Documentation/media/uapi/v4l/dev-subdev.rst
@@ -99,8 +99,8 @@ the video sensor and the host image processing hardware.
 
 .. _pipeline-scaling:
 
-.. figure::  pipeline.*
-    :alt:    pipeline.pdf / pipeline.png
+.. figure::  pipeline.png
+    :alt:    pipeline.png
     :align:  center
 
     Image Format Negotiation on Pipelines
diff --git a/Documentation/media/uapi/v4l/field-order.rst b/Documentation/media/uapi/v4l/field-order.rst
index 26c9a6541493..a7e1b4dae343 100644
--- a/Documentation/media/uapi/v4l/field-order.rst
+++ b/Documentation/media/uapi/v4l/field-order.rst
@@ -141,8 +141,8 @@ enum v4l2_field
 Field Order, Top Field First Transmitted
 ========================================
 
-.. figure::  fieldseq_tb.*
-    :alt:    fieldseq_tb.pdf / fieldseq_tb.png
+.. figure::  fieldseq_tb.png
+    :alt:    fieldseq_tb.png
     :align:  center
 
 
@@ -151,7 +151,7 @@ Field Order, Top Field First Transmitted
 Field Order, Bottom Field First Transmitted
 ===========================================
 
-.. figure::  fieldseq_bt.*
-    :alt:    fieldseq_bt.pdf / fieldseq_bt.png
+.. figure::  fieldseq_bt.png
+    :alt:    fieldseq_bt.png
     :align:  center
 
diff --git a/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst b/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst
index d088c469f880..c8a77bc79f2f 100644
--- a/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst
@@ -33,8 +33,8 @@ Layout of macroblocks in memory is presented in the following figure.
 
 .. _nv12mt:
 
-.. figure::  nv12mt.*
-    :alt:    nv12mt.pdf / nv12mt.png
+.. figure::  nv12mt.png
+    :alt:    nv12mt.png
     :align:  center
 
     V4L2_PIX_FMT_NV12MT macroblock Z shape memory layout
@@ -50,8 +50,8 @@ interleaved. Height of the buffer is aligned to 32.
 
 .. _nv12mt_ex:
 
-.. figure::  nv12mt_example.*
-    :alt:    nv12mt_example.pdf / nv12mt_example.png
+.. figure::  nv12mt_example.png
+    :alt:    nv12mt_example.png
     :align:  center
 
     Example V4L2_PIX_FMT_NV12MT memory layout of macroblocks
diff --git a/Documentation/media/uapi/v4l/selection-api-003.rst b/Documentation/media/uapi/v4l/selection-api-003.rst
index c76e2332116b..207349c17ead 100644
--- a/Documentation/media/uapi/v4l/selection-api-003.rst
+++ b/Documentation/media/uapi/v4l/selection-api-003.rst
@@ -7,8 +7,8 @@ Selection targets
 
 .. _sel-targets-capture:
 
-.. figure::  selection.*
-    :alt:    selection.pdf / selection.png
+.. figure::  selection.png
+    :alt:    selection.png
     :align:  center
 
     Cropping and composing targets
diff --git a/Documentation/media/uapi/v4l/subdev-formats.rst b/Documentation/media/uapi/v4l/subdev-formats.rst
index 5053e284265d..2f9c135dfadd 100644
--- a/Documentation/media/uapi/v4l/subdev-formats.rst
+++ b/Documentation/media/uapi/v4l/subdev-formats.rst
@@ -1514,8 +1514,8 @@ be named ``MEDIA_BUS_FMT_SRGGB10_2X8_PADHI_LE``.
 
 .. _bayer-patterns:
 
-.. figure::  bayer.*
-    :alt:    bayer.pdf / bayer.png
+.. figure::  bayer.png
+    :alt:    bayer.png
     :align:  center
 
     **Figure 4.8 Bayer Patterns**

Re: [Ksummit-discuss] Including images on Sphinx documents

[Arnd Bergmann]

On Tuesday, November 8, 2016 8:50:36 AM CET Mauro Carvalho Chehab wrote:
> > [...]
> > > And it may even require "--shell-escape" to be passed at the xelatex
> > > call if inkscape is not in the path, with seems to be a strong
> > > indication that SVG support is not native to texlive, but, instead,
> > > just a way to make LaTeX to call inkscape to do the image conversion.  
> > 
> > Please don't require --shell-escape as part of the TeX workflow.  If
> > LaTeX can't handle the desired image format natively, it needs
> > conversion in advance.
> 
> Agreed. I sent a patch series to linux-doc, doing the conversion in
> advance:
>         https://marc.info/?l=linux-doc&m=147859902804144&w=2
> 
> Not sure why, but the archives don't have all patches yet.
> Anyway, the relevant one is this:
>         https://git.linuxtv.org/mchehab/experimental.git/commit/?h=pdf-fixes&id=5d41c452c787f6a6c755a3855312435bc439acb8
> 
> It basically calls ImageMagick "convert" tool for all png and
> pdf files currently at the documentation (they're all at media,
> ATM).

It looks like we still need to find a way to address the .gif files
though, as they have the same problem as the .pdf files.

During the kernel summit, I looked around for any binary files in
the kernel source tree, and except for the penguin logo, they are
all in Documentation/media/uapi/v4l/, but they are not all pdf
files, but also .png and .pdf.

	Arnd

Re: [Ksummit-discuss] Including images on Sphinx documents

[Mauro Carvalho Chehab]

Hi Arnd,

Em Wed, 16 Nov 2016 17:03:47 +0100
Arnd Bergmann <arnd@arndb.de> escreveu:

> On Tuesday, November 8, 2016 8:50:36 AM CET Mauro Carvalho Chehab wrote:
> > It basically calls ImageMagick "convert" tool for all png and
> > pdf files currently at the documentation (they're all at media,
> > ATM).  
> 
> It looks like we still need to find a way to address the .gif files
> though, as they have the same problem as the .pdf files.

Actually, my last patch series removed all *.pdf images and converted
all .gif files under Documentation/media to PNG[1]. I also replaced some
images by .svg, but the remaining ones are more complex. I'm even not
sure if it makes sense to convert a few of them to vectorial graphics,
like on this case:
	https://mchehab.fedorapeople.org/kernel_docs/media/_images/selection.png

>
> During the kernel summit, I looked around for any binary files in
> the kernel source tree, and except for the penguin logo, they are
> all in Documentation/media/uapi/v4l/, but they are not all pdf
> files, but also .png and .pdf.

>From what I understood from Linus, his problem is to carry on a
non-editable file at the Kernel tree. With that sense, a PNG file
is OK, as it is editable.

I had, in the past, problems with binary contents on either Mercurial
or git (before migrating to git, we used Mercurial for a while).
So, before Kernel 4.8, those .pdf, .png (and .gif) images were uuencoded,
in order to avoid troubles handling patches with them.

Nowadays, I don't see any issue handling binary images via e-mail or via git.

Btw, with that regards, SVG images are a lot worse to handle, as a single
line can easily have more than 998 characters, with makes some email
servers to reject patches with them. So, at the version 3 of my patch 
series, I had to use inkscape to ungroup some images, and to rewrite their
files, as otherwise, two patches were silently rejected by the VGER 
server.

[1] The reason to convert to PNG is that it means one less format to be
concerned with. Also, it doesn't make much sense to use two different
formats for bitmap images at the documentation.

Thanks,
Mauro

Re: [Ksummit-discuss] Including images on Sphinx documents

[Arnd Bergmann]

On Wednesday, November 16, 2016 6:26:33 PM CET Mauro Carvalho Chehab wrote:
> Em Wed, 16 Nov 2016 17:03:47 +0100
> Arnd Bergmann <arnd@arndb.de> escreveu:
> 
> > On Tuesday, November 8, 2016 8:50:36 AM CET Mauro Carvalho Chehab wrote:
> > > It basically calls ImageMagick "convert" tool for all png and
> > > pdf files currently at the documentation (they're all at media,
> > > ATM).  
> > 
> > It looks like we still need to find a way to address the .gif files
> > though, as they have the same problem as the .pdf files.
> 
> Actually, my last patch series removed all *.pdf images and converted
> all .gif files under Documentation/media to PNG[1]. I also replaced some
> images by .svg, but the remaining ones are more complex. I'm even not
> sure if it makes sense to convert a few of them to vectorial graphics,
> like on this case:
> 	https://mchehab.fedorapeople.org/kernel_docs/media/_images/selection.png
> 
> >
> > During the kernel summit, I looked around for any binary files in
> > the kernel source tree, and except for the penguin logo, they are
> > all in Documentation/media/uapi/v4l/, but they are not all pdf
> > files, but also .png and .pdf.
> 
> From what I understood from Linus, his problem is to carry on a
> non-editable file at the Kernel tree. With that sense, a PNG file
> is OK, as it is editable.

[adding Linus for clarification]

I understood the concern as being about binary files that you cannot
modify with classic 'patch', which is a separate issue.

> I had, in the past, problems with binary contents on either Mercurial
> or git (before migrating to git, we used Mercurial for a while).
> So, before Kernel 4.8, those .pdf, .png (and .gif) images were uuencoded,
> in order to avoid troubles handling patches with them.
> 
> Nowadays, I don't see any issue handling binary images via e-mail or via git.



> Btw, with that regards, SVG images are a lot worse to handle, as a single
> line can easily have more than 998 characters, with makes some email
> servers to reject patches with them. So, at the version 3 of my patch 
> series, I had to use inkscape to ungroup some images, and to rewrite their
> files, as otherwise, two patches were silently rejected by the VGER 
> server.

Ok, good to know.

> [1] The reason to convert to PNG is that it means one less format to be
> concerned with. Also, it doesn't make much sense to use two different
> formats for bitmap images at the documentation.

I just tried converting all the .gif and .png files to .pnm. This would
make the files patchable but also add around 25MB to the uncompressed
kernel source tree (118kb compressed, compared to 113kb for the .gif and
.png files). This is certainly worse than the uuencoded files you
had before

	Arnd

Re: [Ksummit-discuss] Including images on Sphinx documents

[Jani Nikula]

On Thu, 17 Nov 2016, Arnd Bergmann <arnd@arndb.de> wrote:
> On Wednesday, November 16, 2016 6:26:33 PM CET Mauro Carvalho Chehab wrote:
>> Em Wed, 16 Nov 2016 17:03:47 +0100
>> Arnd Bergmann <arnd@arndb.de> escreveu:
>> 
>> > On Tuesday, November 8, 2016 8:50:36 AM CET Mauro Carvalho Chehab wrote:
>> > > It basically calls ImageMagick "convert" tool for all png and
>> > > pdf files currently at the documentation (they're all at media,
>> > > ATM).  
>> > 
>> > It looks like we still need to find a way to address the .gif files
>> > though, as they have the same problem as the .pdf files.
>> 
>> Actually, my last patch series removed all *.pdf images and converted
>> all .gif files under Documentation/media to PNG[1]. I also replaced some
>> images by .svg, but the remaining ones are more complex. I'm even not
>> sure if it makes sense to convert a few of them to vectorial graphics,
>> like on this case:
>> 	https://mchehab.fedorapeople.org/kernel_docs/media/_images/selection.png
>> 
>> >
>> > During the kernel summit, I looked around for any binary files in
>> > the kernel source tree, and except for the penguin logo, they are
>> > all in Documentation/media/uapi/v4l/, but they are not all pdf
>> > files, but also .png and .pdf.
>> 
>> From what I understood from Linus, his problem is to carry on a
>> non-editable file at the Kernel tree. With that sense, a PNG file
>> is OK, as it is editable.
>
> [adding Linus for clarification]
>
> I understood the concern as being about binary files that you cannot
> modify with classic 'patch', which is a separate issue.

Also reported at [1]. So kernel.org has patches that you can't apply
with either classic patch or git apply. They could at least be in git
binary format so you could apply them with *something*. Of course, not
having binaries at all would be clean.

BR,
Jani.


[1] http://lkml.kernel.org/r/02a78907-933d-3f61-572e-28154b16b9e5@redhat.com

>
>> I had, in the past, problems with binary contents on either Mercurial
>> or git (before migrating to git, we used Mercurial for a while).
>> So, before Kernel 4.8, those .pdf, .png (and .gif) images were uuencoded,
>> in order to avoid troubles handling patches with them.
>> 
>> Nowadays, I don't see any issue handling binary images via e-mail or via git.
>
>
>
>> Btw, with that regards, SVG images are a lot worse to handle, as a single
>> line can easily have more than 998 characters, with makes some email
>> servers to reject patches with them. So, at the version 3 of my patch 
>> series, I had to use inkscape to ungroup some images, and to rewrite their
>> files, as otherwise, two patches were silently rejected by the VGER 
>> server.
>
> Ok, good to know.
>
>> [1] The reason to convert to PNG is that it means one less format to be
>> concerned with. Also, it doesn't make much sense to use two different
>> formats for bitmap images at the documentation.
>
> I just tried converting all the .gif and .png files to .pnm. This would
> make the files patchable but also add around 25MB to the uncompressed
> kernel source tree (118kb compressed, compared to 113kb for the .gif and
> .png files). This is certainly worse than the uuencoded files you
> had before
>
> 	Arnd
> _______________________________________________
> Ksummit-discuss mailing list
> Ksummit-discuss@lists.linuxfoundation.org
> https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss

-- 
Jani Nikula, Intel Open Source Technology Center

Re: [Ksummit-discuss] Including images on Sphinx documents

[Mauro Carvalho Chehab]

Em Thu, 17 Nov 2016 13:28:29 +0200
Jani Nikula <jani.nikula@intel.com> escreveu:

> On Thu, 17 Nov 2016, Arnd Bergmann <arnd@arndb.de> wrote:
> > On Wednesday, November 16, 2016 6:26:33 PM CET Mauro Carvalho Chehab wrote:  
> >> Em Wed, 16 Nov 2016 17:03:47 +0100
> >> Arnd Bergmann <arnd@arndb.de> escreveu:
> >>   
> >> > On Tuesday, November 8, 2016 8:50:36 AM CET Mauro Carvalho Chehab wrote:  

> >> > During the kernel summit, I looked around for any binary files in
> >> > the kernel source tree, and except for the penguin logo, they are
> >> > all in Documentation/media/uapi/v4l/, but they are not all pdf
> >> > files, but also .png and .pdf.  
> >> 
> >> From what I understood from Linus, his problem is to carry on a
> >> non-editable file at the Kernel tree. With that sense, a PNG file
> >> is OK, as it is editable.  

Btw, Sphinx is indeed supporting PNG without external conversions, for
both html and pdf. For reference, those are the formats it supports
for images:

	http://www.sphinx-doc.org/en/1.4.8/builders.html

There are just two formats supported for the output types we use:
PNG and JPEG. Any other format requires external conversion.

> >
> > [adding Linus for clarification]
> >
> > I understood the concern as being about binary files that you cannot
> > modify with classic 'patch', which is a separate issue.  

I don't think this is a big issue, as nowadays everyone uses git.

> 
> Also reported at [1]. So kernel.org has patches that you can't apply
> with either classic patch or git apply. They could at least be in git
> binary format so you could apply them with *something*. Of course, not
> having binaries at all would be clean.
> 
> [1] http://lkml.kernel.org/r/02a78907-933d-3f61-572e-28154b16b9e5@redhat.com

This could be solved the other way around: someone could send a patch
to "patch" adding support for binary patches in the git format.

The thing is: images usually don't change that much. For example, the
tux logo only had 3 patches in git:
	3d4f16348b77 Revert "linux.conf.au 2009: Tuz"
	8032b526d1a3 linux.conf.au 2009: Tuz
	1da177e4c3f4 (tag: v2.6.12-rc2) Linux-2.6.12-rc2

Some other examples:

$ git log --oneline ./Documentation/blockdev/drbd/DRBD-data-packets.svg
b411b3637fa7 The DRBD driver

$ git log --oneline ./Documentation/RCU/Design/Data-Structures/HugeTreeClassicRCU.svg
5c1458478c49 documentation: Add documentation for RCU's major data structures

The media images changed a little bit more, but due to the recent
documentation efforts. Usually, it takes years for someone to touch
them. If you look on it at Kernel v4.7, for example, even the media
images didn't have any changes, except due to dir renames or when
the files got encoded with base64:

$ git log --oneline -- v4.7 ./Documentation/DocBook/media/v4l/subdev-image-processing-full.svg
59ef29cc86af [media] v4l: Add subdev selections documentation: svg and dia files
$ git checkout v4.7
$ git log --oneline --follow ./Documentation/DocBook/media/v4l/fieldseq_bt.pdf
4266129964b8 [media] DocBook: Move all media docbook stuff into its own directory
8e080c2e6cad V4L/DVB (12761): DocBook: add media API specs
$ git log --oneline --follow ./Documentation/DocBook/media/v4l/*.gif
bd7319dc325a [media] DocBook: Use base64 for gif/png files
4266129964b8 [media] DocBook: Move all media docbook stuff into its own directory
$ git log --oneline --follow ./Documentation/DocBook/media/bayer.png.b64
bd7319dc325a [media] DocBook: Use base64 for gif/png files

> >> I had, in the past, problems with binary contents on either Mercurial
> >> or git (before migrating to git, we used Mercurial for a while).
> >> So, before Kernel 4.8, those .pdf, .png (and .gif) images were uuencoded,
> >> in order to avoid troubles handling patches with them.
> >> 
> >> Nowadays, I don't see any issue handling binary images via e-mail or via git.  
> >
> >
> >  
> >> Btw, with that regards, SVG images are a lot worse to handle, as a single
> >> line can easily have more than 998 characters, with makes some email
> >> servers to reject patches with them. So, at the version 3 of my patch 
> >> series, I had to use inkscape to ungroup some images, and to rewrite their
> >> files, as otherwise, two patches were silently rejected by the VGER 
> >> server.  
> >
> > Ok, good to know.
> >  
> >> [1] The reason to convert to PNG is that it means one less format to be
> >> concerned with. Also, it doesn't make much sense to use two different
> >> formats for bitmap images at the documentation.  
> >
> > I just tried converting all the .gif and .png files to .pnm. This would
> > make the files patchable but also add around 25MB to the uncompressed
> > kernel source tree (118kb compressed, compared to 113kb for the .gif and
> > .png files). This is certainly worse than the uuencoded files you
> > had before

There's also another drawback: PNM doesn't allow transparent background.
Some images have transparent backgrounds. So, such conversion would lose
it. Also, PNM is not supported on Sphinx, so it would require external
conversion, just like svg.

IMHO, if we're willing to make easier to use patch, the best is to use
uuencode (or base64). In that case, It could make sense to use it for svg 
too, in order to solve the warn of patches that contain lines longer than
998 characters (with is a violation to IETF rfc 2821).

The drawback of uuencode/base64 is that it makes harder to edit the files.
So, IMHO, I would keep them in binary format.

Thanks,
Mauro

Re: [Ksummit-discuss] Including images on Sphinx documents

[Theodore Ts'o]

On Thu, Nov 17, 2016 at 12:07:15PM +0100, Arnd Bergmann wrote:
> [adding Linus for clarification]
> 
> I understood the concern as being about binary files that you cannot
> modify with classic 'patch', which is a separate issue.

I think the other complaint is that the image files aren't "source" in
the proper term, since they are *not* the preferred form for
modification --- that's the svg files.  Beyond the license compliance
issues (which are satisified because the .svg files are included in
the git tree), there is the SCM cleaniless argument of not including
generated files in the distribution, since this increases the
opportunites for the "real" source file and the generated source file
to get out of sync.  (As just one example, if the patch can't
represent the change to binary file.)

I do check in generated files on occasion --- usually because I don't
trust autoconf to be a stable in terms of generating a correct
configure file from a configure.in across different versions of
autoconf and different macro libraries that might be installed on the
system.  So this isn't a hard and fast rule by any means (although
Linus may be more strict than I on that issue).

I don't understand why it's so terrible to have generate the image
file from the .svg file in a Makefile rule, and then copy it somewhere
else if Sphinx is too dumb to fetch it from the normal location?

     	       	      	      	       - Ted

Re: [Ksummit-discuss] Including images on Sphinx documents

[Mauro Carvalho Chehab]

Hi Ted,

Em Thu, 17 Nov 2016 09:52:44 -0500
Theodore Ts'o <tytso@mit.edu> escreveu:

> On Thu, Nov 17, 2016 at 12:07:15PM +0100, Arnd Bergmann wrote:
> > [adding Linus for clarification]
> > 
> > I understood the concern as being about binary files that you cannot
> > modify with classic 'patch', which is a separate issue.  
> 
> I think the other complaint is that the image files aren't "source" in
> the proper term, since they are *not* the preferred form for
> modification --- that's the svg files.  Beyond the license compliance
> issues (which are satisified because the .svg files are included in
> the git tree), there is the SCM cleaniless argument of not including
> generated files in the distribution, since this increases the
> opportunites for the "real" source file and the generated source file
> to get out of sync.  (As just one example, if the patch can't
> represent the change to binary file.)
> 
> I do check in generated files on occasion --- usually because I don't
> trust autoconf to be a stable in terms of generating a correct
> configure file from a configure.in across different versions of
> autoconf and different macro libraries that might be installed on the
> system.  So this isn't a hard and fast rule by any means (although
> Linus may be more strict than I on that issue).
> 
> I don't understand why it's so terrible to have generate the image
> file from the .svg file in a Makefile rule, and then copy it somewhere
> else if Sphinx is too dumb to fetch it from the normal location?

The images whose source are in .svg are now generated via Makefile
for the PDF output (after my patches, already applied to the docs-next
tree).

So, the problem that remains is for those images whose source
is a bitmap. If we want to stick with the Sphinx supported formats,
we have only two options for bitmaps: jpg or png. We could eventually
use uuencode or base64 to make sure that the patches won't use
git binary diff extension, or, as Arnd proposed, use a portable
bitmap format, in ascii, converting via Makefile, but losing
the alpha channel with makes the background transparent.

Thanks,
Mauro

Re: [Ksummit-discuss] Including images on Sphinx documents

[Johannes Berg]

> So, the problem that remains is for those images whose source
> is a bitmap. If we want to stick with the Sphinx supported formats,
> we have only two options for bitmaps: jpg or png. We could eventually
> use uuencode or base64 to make sure that the patches won't use
> git binary diff extension, or, as Arnd proposed, use a portable
> bitmap format, in ascii, converting via Makefile, but losing
> the alpha channel with makes the background transparent.
> 

Or just "rewrite" them in svg? None of the gif files I can see actually
look like they'd have been drawn in gif format anyway. The original
source may be lost, but it doesn't seem all that hard to recreate them
in svg.

johannes

Re: [Ksummit-discuss] Including images on Sphinx documents

[Mauro Carvalho Chehab]

Em Thu, 17 Nov 2016 12:07:15 +0100
Arnd Bergmann <arnd@arndb.de> escreveu:

> On Wednesday, November 16, 2016 6:26:33 PM CET Mauro Carvalho Chehab wrote:
> > Em Wed, 16 Nov 2016 17:03:47 +0100
> > Arnd Bergmann <arnd@arndb.de> escreveu:
> >   
> > > On Tuesday, November 8, 2016 8:50:36 AM CET Mauro Carvalho Chehab wrote:  

> > From what I understood from Linus, his problem is to carry on a
> > non-editable file at the Kernel tree. With that sense, a PNG file
> > is OK, as it is editable.  

Btw, Sphinx is indeed supporting PNG without external conversions, for
both html and pdf. For reference, those are the formats it supports
for images:

	http://www.sphinx-doc.org/en/1.4.8/builders.html

There are just two formats supported for the output types we use:
PNG and JPEG.


> [adding Linus for clarification]
> 
> I understood the concern as being about binary files that you cannot
> modify with classic 'patch', which is a separate issue.

I don't think this is a big issue, as nowadays everyone uses git.

Also, this could be solved the other way around: someone could send a
patch to "patch" adding support for binary patches in the git format.

Also, images usually don't change that much. For example, the
tux logo only had 3 patches in git:
	3d4f16348b77 Revert "linux.conf.au 2009: Tuz"
	8032b526d1a3 linux.conf.au 2009: Tuz
	1da177e4c3f4 (tag: v2.6.12-rc2) Linux-2.6.12-rc2

Some other examples:

$ git log --oneline ./Documentation/blockdev/drbd/DRBD-data-packets.svg
b411b3637fa7 The DRBD driver

$ git log --oneline ./Documentation/RCU/Design/Data-Structures/HugeTreeClassicRCU.svg
5c1458478c49 documentation: Add documentation for RCU's major data structures

The media images changed a little bit more, but due to the recent
documentation efforts. Usually, it takes years for someone to touch
them. If you look on it at Kernel v4.7, for example, even the media
images didn't have any changes, except due to dir renames:

$ git log --oneline ./Documentation/DocBook/media/v4l/subdev-image-processing-full.svg
59ef29cc86af [media] v4l: Add subdev selections documentation: svg and dia files

$ git log --oneline --follow ./Documentation/DocBook/media/v4l/fieldseq_bt.pdf
4266129964b8 [media] DocBook: Move all media docbook stuff into its own directory
8e080c2e6cad V4L/DVB (12761): DocBook: add media API specs

$ git log --oneline --follow ./Documentation/DocBook/media/v4l/*.gif
bd7319dc325a [media] DocBook: Use base64 for gif/png files
4266129964b8 [media] DocBook: Move all media docbook stuff into its own directory

$ git log --oneline --follow Documentation/DocBook/media/bayer.png.b64
bd7319dc325a [media] DocBook: Use base64 for gif/png files

> > I had, in the past, problems with binary contents on either Mercurial
> > or git (before migrating to git, we used Mercurial for a while).
> > So, before Kernel 4.8, those .pdf, .png (and .gif) images were uuencoded,
> > in order to avoid troubles handling patches with them.
> > 
> > Nowadays, I don't see any issue handling binary images via e-mail or via git.  
> 
> > Btw, with that regards, SVG images are a lot worse to handle, as a single
> > line can easily have more than 998 characters, with makes some email
> > servers to reject patches with them. So, at the version 3 of my patch 
> > series, I had to use inkscape to ungroup some images, and to rewrite their
> > files, as otherwise, two patches were silently rejected by the VGER 
> > server.  
> 
> Ok, good to know.
> 
> > [1] The reason to convert to PNG is that it means one less format to be
> > concerned with. Also, it doesn't make much sense to use two different
> > formats for bitmap images at the documentation.  
> 
> I just tried converting all the .gif and .png files to .pnm. This would
> make the files patchable but also add around 25MB to the uncompressed
> kernel source tree (118kb compressed, compared to 113kb for the .gif and
> .png files). This is certainly worse than the uuencoded files you
> had before

There's also another drawback: PNM doesn't allow transparent background.
Some images have transparent backgrounds. So, such conversion would lose
it. Also, PNM is not supported on Sphinx, so it would require external
conversion, just like svg.

IMHO, if we're willing to make easier to use patch, the best is to use
uuencode (or base64). In that case, It could make sense to use it for svg 
too, in order to solve the warn of patches that contain lines longer than
998 characters (with is a violation to IETF rfc 2821).

The drawback of uuencode/base64 is that it makes harder to edit the files.
So, IMHO, I would keep them in binary format.

Thanks,
Mauro

Re: [Ksummit-discuss] Including images on Sphinx documents

[Linus Torvalds]

On Thu, Nov 17, 2016 at 3:07 AM, Arnd Bergmann <arnd@arndb.de> wrote:
>
> [adding Linus for clarification]
>
> I understood the concern as being about binary files that you cannot
> modify with classic 'patch', which is a separate issue.

No. That is how I *noticed* the issue. Those stupid pdf binary files
have been around forever, I just didn't notice until the Fedora people
started complaining about the patches.

My real problem is not "binary" or even "editable", but SOURCE CODE.

It's like including a "vmlinux" image in the git tree: sure, you can
technically "edit" it with a hex editor, but that doesn't change the
basic issue: it's not the original source code.

I don't want to see generated binary crap.

That goes for png, that goes for gif, that goes for pdf - and in fact
that goes for svg *too*, if the actual source of the svg was something
else, and it was generated from some other data.

We have makefiles, but more importantly, few enough people actually
*generate* the documentation, that I think if it's an option to just
fix sphinx, we should do that instead. If it means that you have to
have some development version of sphinx, so be it. Most people read
the documentation either directly in the unprocessed text-files
("source code") or on the web (by searching for pre-formatted docs)
that I really don't think we need to worry too much about the
toolchain.

But what we *should* worry about is having the kernel source tree
contain source.

                 Linus

Re: [Ksummit-discuss] Including images on Sphinx documents

[Linus Torvalds]

On Thu, Nov 17, 2016 at 8:02 AM, Linus Torvalds
<torvalds@linux-foundation.org> wrote:
>
> No. That is how I *noticed* the issue. Those stupid pdf binary files
> have been around forever, I just didn't notice until the Fedora people
> started complaining about the patches.

Side note: my release patches these days enable both "--binary" and
"-M", so they require "git apply" now. So we handle the binaries fine
in patches now, but as mentioned, that was just what made me notice,
it wasn't a fix for the deeper ("source") problem.

                   Linus

Re: [Ksummit-discuss] Including images on Sphinx documents

[James Bottomley]

On Thu, 2016-11-17 at 13:16 -0200, Mauro Carvalho Chehab wrote:
> Hi Ted,
> 
> Em Thu, 17 Nov 2016 09:52:44 -0500
> Theodore Ts'o <tytso@mit.edu> escreveu:
> 
> > On Thu, Nov 17, 2016 at 12:07:15PM +0100, Arnd Bergmann wrote:
> > > [adding Linus for clarification]
> > > 
> > > I understood the concern as being about binary files that you
> > > cannot
> > > modify with classic 'patch', which is a separate issue.  
> > 
> > I think the other complaint is that the image files aren't "source"
> > in
> > the proper term, since they are *not* the preferred form for
> > modification --- that's the svg files.  Beyond the license
> > compliance
> > issues (which are satisified because the .svg files are included in
> > the git tree), there is the SCM cleaniless argument of not
> > including
> > generated files in the distribution, since this increases the
> > opportunites for the "real" source file and the generated source
> > file
> > to get out of sync.  (As just one example, if the patch can't
> > represent the change to binary file.)
> > 
> > I do check in generated files on occasion --- usually because I
> > don't
> > trust autoconf to be a stable in terms of generating a correct
> > configure file from a configure.in across different versions of
> > autoconf and different macro libraries that might be installed on
> > the
> > system.  So this isn't a hard and fast rule by any means (although
> > Linus may be more strict than I on that issue).
> > 
> > I don't understand why it's so terrible to have generate the image
> > file from the .svg file in a Makefile rule, and then copy it
> > somewhere
> > else if Sphinx is too dumb to fetch it from the normal location?
> 
> The images whose source are in .svg are now generated via Makefile
> for the PDF output (after my patches, already applied to the docs
> -next
> tree).
> 
> So, the problem that remains is for those images whose source
> is a bitmap. If we want to stick with the Sphinx supported formats,
> we have only two options for bitmaps: jpg or png. We could eventually
> use uuencode or base64 to make sure that the patches won't use
> git binary diff extension, or, as Arnd proposed, use a portable
> bitmap format, in ascii, converting via Makefile, but losing
> the alpha channel with makes the background transparent.

If it can use svg, why not use that?  SVG files can be a simple xml
wrapper around a wide variety of graphic image formats which are
embedded in the svg using the data-uri format, you know ...

Anything that handles SVGs should be able to handle all the embeddable
image formats, which should give you a way around image restrictions
whatever it is would otherwise have.

James

Re: [Ksummit-discuss] Including images on Sphinx documents

[Jani Nikula]

On Thu, 17 Nov 2016, Linus Torvalds <torvalds@linux-foundation.org> wrote:
> We have makefiles, but more importantly, few enough people actually
> *generate* the documentation, that I think if it's an option to just
> fix sphinx, we should do that instead. If it means that you have to
> have some development version of sphinx, so be it. Most people read
> the documentation either directly in the unprocessed text-files
> ("source code") or on the web (by searching for pre-formatted docs)
> that I really don't think we need to worry too much about the
> toolchain.

My secret plan was to make building documentation easy, and then trick
more people into actually doing that on a regular basis, to ensure we
keep the build working and the output sensible in a variety of
environments. Sure we have a bunch of people doing this, and we have
0day doing this, but I'd hate it if it became laborous and fiddly to set
up the toolchain to generate documentation.

So I'm not necessarily disagreeing with anything you say, but I think
there's value in having a low bar for entry (from the toolchain POV) for
people interested in working with documentation, whether they're
seasoned kernel developers or newcomers purely interested in
documentation.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center

Re: [Ksummit-discuss] Including images on Sphinx documents

[Daniel Vetter]

On Fri, Nov 18, 2016 at 11:15:09AM +0200, Jani Nikula wrote:
> On Thu, 17 Nov 2016, Linus Torvalds <torvalds@linux-foundation.org> wrote:
> > We have makefiles, but more importantly, few enough people actually
> > *generate* the documentation, that I think if it's an option to just
> > fix sphinx, we should do that instead. If it means that you have to
> > have some development version of sphinx, so be it. Most people read
> > the documentation either directly in the unprocessed text-files
> > ("source code") or on the web (by searching for pre-formatted docs)
> > that I really don't think we need to worry too much about the
> > toolchain.
> 
> My secret plan was to make building documentation easy, and then trick
> more people into actually doing that on a regular basis, to ensure we
> keep the build working and the output sensible in a variety of
> environments. Sure we have a bunch of people doing this, and we have
> 0day doing this, but I'd hate it if it became laborous and fiddly to set
> up the toolchain to generate documentation.
> 
> So I'm not necessarily disagreeing with anything you say, but I think
> there's value in having a low bar for entry (from the toolchain POV) for
> people interested in working with documentation, whether they're
> seasoned kernel developers or newcomers purely interested in
> documentation.

Yeah, I want a low bar for doc building too. The initial hack fest we had
to add cross-linking and other dearly needed stuff increased the build
time so much that everyone stopped creating docs. It's of course not as
extreme, but stating that "no one runs the doc toolchain" is imo akin to
"no one runs gcc, developers just read the source and users install rpms".
It's totally true, until you try to change stuff, then you have to be able
to build that pile fast and with an easily-obtained toolchain.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

Re: [Ksummit-discuss] Including images on Sphinx documents

[Jonathan Corbet]

On Thu, 17 Nov 2016 08:02:50 -0800
Linus Torvalds <torvalds@linux-foundation.org> wrote:

> We have makefiles, but more importantly, few enough people actually
> *generate* the documentation, that I think if it's an option to just
> fix sphinx, we should do that instead. If it means that you have to
> have some development version of sphinx, so be it. Most people read
> the documentation either directly in the unprocessed text-files
> ("source code") or on the web (by searching for pre-formatted docs)
> that I really don't think we need to worry too much about the
> toolchain.
> 
> But what we *should* worry about is having the kernel source tree
> contain source.

I would be happy to take a shot at fixing sphinx; we clearly need to
engage more with sphinx upstream in general.  But I guess I still haven't
figured out what "fixing sphinx" means in this case.

I don't know what the ultimate source of these images is (Mauro, perhaps
you could shed some light there?).  Perhaps its SVG for some of the
diagrams, but for the raster images, probably not; it's probably some
weird-ass diagram-editor format.  We could put those in the tree, but
they are likely to be harder to convert to a useful format and will raise
all of the same obnoxious binary patch issues.

Rather than beating our heads against the wall trying to convert between
various image formats, maybe we need to take a step back.  We're trying
to build better documentation, and there is certainly a place for
diagrams and such in that documentation.  Johannes was asking about it
for the 802.11 docs, and I know Paul has run into these issues with the
RCU docs as well.  Might there be a tool or an extension out there that
would allow us to express these diagrams in a text-friendly, editable
form?

With some effort, I bet we could get rid of a number of the images, and
perhaps end up with something that makes sense when read in the .rst
source files as an extra benefit.  But I'm not convinced that we can,
say, sensibly express the differences between different video interlacing
schemes that way.

jon

Re: [Ksummit-discuss] Including images on Sphinx documents

[Andrew Lunn]

> Rather than beating our heads against the wall trying to convert between
> various image formats, maybe we need to take a step back.  We're trying
> to build better documentation, and there is certainly a place for
> diagrams and such in that documentation.  Johannes was asking about it
> for the 802.11 docs, and I know Paul has run into these issues with the
> RCU docs as well.  Might there be a tool or an extension out there that
> would allow us to express these diagrams in a text-friendly, editable
> form?

Hi Jonathan

A lot depends on what the diagram is supposed to show. I've used
graphviz dot in documents which get processes with Sphinx. That works
well for state machine, linked lists, etc. It uses a mainline Sphinx
extension.

It does however increase the size of your documents toolchain, you
need graphviz. But i doubt there is a distribution which does not have
it.

If you are worried about getting all these needed tools installed, i
think tools/perf might be a useful guide. When you compile it, it
gives helpful hints:

No libdw DWARF unwind found, Please install elfutils-devel/libdw-dev >= 0.158
No sys/sdt.h found, no SDT events are defined, please install systemtap-sdt-devel or systemtap-sdt-dev

     Andrew

Re: [Ksummit-discuss] Including images on Sphinx documents

[Bart Van Assche]

On 11/19/16 09:15, Jonathan Corbet wrote:
> Might there be a tool or an extension out there that would allow us
 > to express these diagrams in a text-friendly, editable form?

How about using the graphviz languages for generating diagrams that can 
be described easily in one of the graphviz languages? The graphviz 
programming languages are well suited for version control. And the 
graphviz software includes a tool for converting diagrams described in a 
graphviz language into many formats, including png, svg and pdf. 
Examples of diagrams generated with graphviz are available at 
http://www.graphviz.org/Gallery.php.

Bart.

Re: [Ksummit-discuss] Including images on Sphinx documents

[David Woodhouse]

[-- Attachment #1: Type: text/plain, Size: 314 bytes --]

On Sat, 2016-11-19 at 10:15 -0700, Jonathan Corbet wrote:
> Might there be a tool or an extension out there that
> would allow us to express these diagrams in a text-friendly, editable
> form?

I know it's unfashionable these days, but TeX always used to be bloody
good at that kind of thing.

-- 
dwmw2

[-- Attachment #2: smime.p7s --]
[-- Type: application/x-pkcs7-signature, Size: 5760 bytes --]

Re: [Ksummit-discuss] Including images on Sphinx documents

[Linus Torvalds]

On Sat, Nov 19, 2016 at 9:55 AM, David Woodhouse <dwmw2@infradead.org> wrote:
>
> I know it's unfashionable these days, but TeX always used to be bloody
> good at that kind of thing.

You must have used a different TeX than I did.

TeX is a horrible example. The moment you needed to insert anything
that TeX didn't know about, you were screwed.

I think my go-to for TeX was LaTeX, the "epsfig" thing, and then xfig
and eps files (using fig2dev). Christ, I get flashbacks just thinking
about it.

I thought one of the points of Sphinx was to not have to play those games.

I think that graphviz and svg are the reasonable modern formats. Let's
try to avoid bitmaps in today's world, except perhaps as intermediate
generated things for what we can't avoid.

                    Linus

Re: [Ksummit-discuss] Including images on Sphinx documents

[Mauro Carvalho Chehab]

Em Sat, 19 Nov 2016 10:15:43 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Thu, 17 Nov 2016 08:02:50 -0800
> Linus Torvalds <torvalds@linux-foundation.org> wrote:
> 
> > We have makefiles, but more importantly, few enough people actually
> > *generate* the documentation, that I think if it's an option to just
> > fix sphinx, we should do that instead. If it means that you have to
> > have some development version of sphinx, so be it. Most people read
> > the documentation either directly in the unprocessed text-files
> > ("source code") or on the web (by searching for pre-formatted docs)
> > that I really don't think we need to worry too much about the
> > toolchain.
> > 
> > But what we *should* worry about is having the kernel source tree
> > contain source.  
> 
> I would be happy to take a shot at fixing sphinx; we clearly need to
> engage more with sphinx upstream in general.  But I guess I still haven't
> figured out what "fixing sphinx" means in this case.
> 
> I don't know what the ultimate source of these images is (Mauro, perhaps
> you could shed some light there?).  Perhaps its SVG for some of the
> diagrams, but for the raster images, probably not; it's probably some
> weird-ass diagram-editor format.  We could put those in the tree, but
> they are likely to be harder to convert to a useful format and will raise
> all of the same obnoxious binary patch issues.

I did some research on Friday trying to identify where those images
came. It turns that, for the oldest images (before I took the media
maintainership), PDF were actually their "source", as far as I could track,
in the sense that the *.gif images were produced from the PDF.

The images seem to be generated using some LaTeX tool. Their original
format were probably EPS. I was able to convert those to SVG from their
pdf "source":

	https://git.linuxtv.org/mchehab/experimental.git/commit/?h=svg-images&id=9baca9431d333af086c1ccd499668b5b76d35a64

I didn't check yet where the newer images came from, but I guess
that at least some of them were generated using some bitmap editor
like gimp.

> Rather than beating our heads against the wall trying to convert between
> various image formats, maybe we need to take a step back.  We're trying
> to build better documentation, and there is certainly a place for
> diagrams and such in that documentation.  Johannes was asking about it
> for the 802.11 docs, and I know Paul has run into these issues with the
> RCU docs as well.  Might there be a tool or an extension out there that
> would allow us to express these diagrams in a text-friendly, editable
> form?

I guess that a Sphinx extension for graphviz is something that we'll
need sooner or later. One of our images were clearly generated using
graphviz:
	Documentation/media/uapi/v4l/pipeline.png

> With some effort, I bet we could get rid of a number of the images, and
> perhaps end up with something that makes sense when read in the .rst
> source files as an extra benefit.  But I'm not convinced that we can,
> say, sensibly express the differences between different video interlacing
> schemes that way.

Explaining visual concepts without images is really hard. Several
images that we use are there to explain things like interlacing,
point (x, y) positions of R, G and B pixels (or YUV), and even
wavelengths to show where the VBI frames are taken. There's not
much we can to do get rid of those images.

We can try to convert those to vector graphics, or encapsulate the bitmaps
inside a SVG file, but still we'll need images on documents.

Thanks,
Mauro

Re: [Ksummit-discuss] Including images on Sphinx documents

[Linus Torvalds]

On Sat, Nov 19, 2016 at 12:54 PM, Mauro Carvalho Chehab
<mchehab@s-opensource.com> wrote:
>
> I did some research on Friday trying to identify where those images
> came. It turns that, for the oldest images (before I took the media
> maintainership), PDF were actually their "source", as far as I could track,
> in the sense that the *.gif images were produced from the PDF.
>
> The images seem to be generated using some LaTeX tool. Their original
> format were probably EPS.

The original format was almost certainly xfig.

Converting fig files to eps and pdf to then encapsulate them into
LaTeX was a very common way to do documentation with simple figures.
Iirc, xfig natively supported "export as eps".

                Linus

Re: [Ksummit-discuss] Including images on Sphinx documents

[David Woodhouse]

> On Sat, Nov 19, 2016 at 9:55 AM, David Woodhouse <dwmw2@infradead.org>
> wrote:
>>
>> I know it's unfashionable these days, but TeX always used to be bloody
>> good at that kind of thing.
>
> You must have used a different TeX than I did.
>
> TeX is a horrible example. The moment you needed to insert anything
> that TeX didn't know about, you were screwed.
>
> I think my go-to for TeX was LaTeX, the "epsfig" thing, and then xfig
> and eps files (using fig2dev). Christ, I get flashbacks just thinking
> about it.

You're right. You included Epson,  which was generated from fig.

Now I'm having flashbacks too, and I actually remember.

> I thought one of the points of Sphinx was to not have to play those games.
>
> I think that graphviz and svg are the reasonable modern formats. Let's
> try to avoid bitmaps in today's world, except perhaps as intermediate
> generated things for what we can't avoid.

Sure, SVG makes sense. It's a text-based format (albeit XML) and it *can*
be edited with a text editor and reasonably kept in version control, at
least if the common tools store it in a diff-friendly way (with some line
breaks occasionally, and maybe no indenting). Do they?


-- 
dwmw2

Re: [Ksummit-discuss] Including images on Sphinx documents

[Mauro Carvalho Chehab]

Em Sat, 19 Nov 2016 22:59:01 -0000
"David Woodhouse" <dwmw2@infradead.org> escreveu:

> > I think that graphviz and svg are the reasonable modern formats. Let's
> > try to avoid bitmaps in today's world, except perhaps as intermediate
> > generated things for what we can't avoid.  

Ok, I got rid of all bitmap images:
	https://git.linuxtv.org/mchehab/experimental.git/log/?h=svg-images

Now, all images are in SVG (one is actually a .dot file - while we don't
have an extension to handle it, I opted to keep both .dot and .svg on
my development tree - I'll likely add a Makefile rule for it too).

I converted the ones from pdf/xfig to SVG, and I rewrote the other ones
on SVG. The most complex one was cropping a bitmap image. Instead, I took
the "Tuz" image - e. g. the one from commit 8032b526d1a3 
("linux.conf.au 2009: Tuz") and use it for image crop. The file size is
a way bigger than the previous one (the PNG had 11K; the SVG now has 563K),
but the end result looked nice, IMHO.

> Sure, SVG makes sense. It's a text-based format (albeit XML) and it *can*
> be edited with a text editor and reasonably kept in version control, at
> least if the common tools store it in a diff-friendly way (with some line
> breaks occasionally, and maybe no indenting). Do they?

Inkscape does a good job on breaking lines for a diff-friendly output.

Yet, some lines violate the maximum limit for e-mails defined by
IETF RFC 2821. The problem is that sending such patches to the mailing
lists could make them be ignored.

Not sure what would be the best way to solve such issues.


Thanks,
Mauro

Re: [Ksummit-discuss] Including images on Sphinx documents

[Johannes Berg]

On Sat, 2016-11-19 at 10:15 -0700, Jonathan Corbet wrote:
> 
> I don't know what the ultimate source of these images is (Mauro,
> perhaps you could shed some light there?).

I'd argue that it probably no longer matters. Whether it's xfig, svg,
graphviz originally etc. - the source is probably long lost. Recreating
these images in any other format is probably not very difficult for
most or almost all of them.

> Rather than beating our heads against the wall trying to convert
> between various image formats, maybe we need to take a step
> back.  We're trying to build better documentation, and there is
> certainly a place for diagrams and such in that
> documentation.  Johannes was asking about it for the 802.11 docs, and
> I know Paul has run into these issues with the RCU docs as
> well.  Might there be a tool or an extension out there that would
> allow us to express these diagrams in a text-friendly, editable
> form?
> 
> With some effort, I bet we could get rid of a number of the images,
> and perhaps end up with something that makes sense when read in the
> .rst source files as an extra benefit. 

I tend to agree, and I think that having this readable in the text
would be good.

You had pointed me to this plugin before
https://pythonhosted.org/sphinxcontrib-aafig/

but I don't think it can actually represent any of the pictures.

Some surely could be represented directly by having the graphviz source
inside the rst file:
http://www.sphinx-doc.org/en/1.4.8/ext/graphviz.html

(that's even an included plugin, no need to install anything extra)

graphviz is actually quite powerful, so I suspect things like
dvbstb.png can be represented there, perhaps not pixel-identically, but
at least semantically equivalently.


However, I don't think we'll actually find a catch-all solution, so we
need to continue this discussion here for a fallback anyway - as you
stated (I snipped that quote, sorry), a picture describing the video
formats will likely not be representable in text.


As far as my use-case for sequence diagrams is concerned, I'd really
like to see this integrated with the toolchain since the source format
for them is in fact a text format.

johannes

Re: [Ksummit-discuss] Including images on Sphinx documents

[Mauro Carvalho Chehab]

Em Mon, 21 Nov 2016 11:39:41 +0100
Johannes Berg <johannes@sipsolutions.net> escreveu:

> On Sat, 2016-11-19 at 10:15 -0700, Jonathan Corbet wrote:
> > 
> > I don't know what the ultimate source of these images is (Mauro,
> > perhaps you could shed some light there?).  
> 
> I'd argue that it probably no longer matters. Whether it's xfig, svg,
> graphviz originally etc. - the source is probably long lost. Recreating
> these images in any other format is probably not very difficult for
> most or almost all of them.

I did it already. I converted one image to Graphviz and the rest
to SVG.

> 
> > Rather than beating our heads against the wall trying to convert
> > between various image formats, maybe we need to take a step
> > back.  We're trying to build better documentation, and there is
> > certainly a place for diagrams and such in that
> > documentation.  Johannes was asking about it for the 802.11 docs, and
> > I know Paul has run into these issues with the RCU docs as
> > well.  Might there be a tool or an extension out there that would
> > allow us to express these diagrams in a text-friendly, editable
> > form?
> > 
> > With some effort, I bet we could get rid of a number of the images,
> > and perhaps end up with something that makes sense when read in the
> > .rst source files as an extra benefit.   
> 
> I tend to agree, and I think that having this readable in the text
> would be good.
> 
> You had pointed me to this plugin before
> https://pythonhosted.org/sphinxcontrib-aafig/
> 
> but I don't think it can actually represent any of the pictures.

No, but there are some ascii art images inside some txt/rst files
and inside some kernel-doc comments. We could either use the above
extension for them or to convert into some image. The ascii art
images I saw seem to be diagrams, so Graphviz would allow replacing
most of them, if not all.

> Some surely could be represented directly by having the graphviz source
> inside the rst file:
> http://www.sphinx-doc.org/en/1.4.8/ext/graphviz.html
> 
> (that's even an included plugin, no need to install anything extra)

Yes, but it seems that the existing plugin mis some things that
the .. figure:: tag does, like allowing to specify the alternate and
placing a caption to the figure (or tables) [1].

Also, as SVG is currently broken on Sphinx for PDF output, we'll
need to pre-process the image before calling Sphinx anyway. So,
IMHO, the best for now would be to use the same approach for both
cases.

On my patchsets, they're doing both SVG and Graphviz handling via
Makefile, before calling Sphinx.

When we have the needed features either at Sphinx upstream or as a
plugin, we could then switch to such solution.

[1] Another missing feature with regards to that is that Sphinx
doesn't seem to be able to produce a list of figures and tables.
Eventually, the image extension (or upstream improvements) that
would implement proper support for SVG and Graphviz could also
implement support for such indexes.

> graphviz is actually quite powerful, so I suspect things like
> dvbstb.png can be represented there, perhaps not pixel-identically, but
> at least semantically equivalently.

Yes, but we'll still need SVG for more complex things. I actually
converted (actually, I rewrote) dvbstb.png as SVG.

> However, I don't think we'll actually find a catch-all solution, so we
> need to continue this discussion here for a fallback anyway - as you
> stated (I snipped that quote, sorry), a picture describing the video
> formats will likely not be representable in text.
> 
> As far as my use-case for sequence diagrams is concerned, I'd really
> like to see this integrated with the toolchain since the source format
> for them is in fact a text format.

Yes, for sure having support for Graphviz will be very useful.

Thanks,
Mauro

Re: [Ksummit-discuss] Including images on Sphinx documents

[James Bottomley]

On Mon, 2016-11-21 at 12:06 -0200, Mauro Carvalho Chehab wrote:
> Em Mon, 21 Nov 2016 11:39:41 +0100
> Johannes Berg <johannes@sipsolutions.net> escreveu:
> > On Sat, 2016-11-19 at 10:15 -0700, Jonathan Corbet wrote:
> > 
> > > Rather than beating our heads against the wall trying to convert
> > > between various image formats, maybe we need to take a step
> > > back.  We're trying to build better documentation, and there is
> > > certainly a place for diagrams and such in that
> > > documentation.  Johannes was asking about it for the 802.11 docs, 
> > > and I know Paul has run into these issues with the RCU docs as
> > > well.  Might there be a tool or an extension out there that would
> > > allow us to express these diagrams in a text-friendly, editable
> > > form?
> > > 
> > > With some effort, I bet we could get rid of a number of the 
> > > images, and perhaps end up with something that makes sense when 
> > > read in the .rst source files as an extra benefit.   
> > 
> > I tend to agree, and I think that having this readable in the text
> > would be good.
> > 
> > You had pointed me to this plugin before
> > https://pythonhosted.org/sphinxcontrib-aafig/
> > 
> > but I don't think it can actually represent any of the pictures.
> 
> No, but there are some ascii art images inside some txt/rst files
> and inside some kernel-doc comments. We could either use the above
> extension for them or to convert into some image. The ascii art
> images I saw seem to be diagrams, so Graphviz would allow replacing
> most of them, if not all.

Please don't replace ASCII art that effectively conveys conceptual
diagrams.  If you do, we'll wind up in situations where someone hasn't
built the docs and doesn't possess the tools to see a diagram that was
previously shown by every text editor (or can't be bothered to dig out
the now separate file).  In the name of creating "prettier" diagrams
(and final doc), we'll have damaged capacity to understand stuff by
just reading the source if this diagram is in kernel doc comments.  I
think this is a good application of "if it ain't broke, don't fix it".

James

Re: [Ksummit-discuss] Including images on Sphinx documents

[Johannes Berg]

> > > You had pointed me to this plugin before
> > > https://pythonhosted.org/sphinxcontrib-aafig/
> > > 
> > > but I don't think it can actually represent any of the pictures.
> > 
> > No, but there are some ascii art images inside some txt/rst files
> > and inside some kernel-doc comments. We could either use the above
> > extension for them or to convert into some image. The ascii art
> > images I saw seem to be diagrams, so Graphviz would allow replacing
> > most of them, if not all.
> 
> Please don't replace ASCII art that effectively conveys conceptual
> diagrams.  If you do, we'll wind up in situations where someone
> hasn't built the docs and doesn't possess the tools to see a diagram
> that was previously shown by every text editor (or can't be bothered
> to dig out the now separate file).  In the name of creating
> "prettier" diagrams (and final doc), we'll have damaged capacity to
> understand stuff by just reading the source if this diagram is in
> kernel doc comments.  I think this is a good application of "if it
> ain't broke, don't fix it".

Right, I agree completely!

That's the selling point of aafig though, it translates to pretty
diagrams, but looks fine when viewed in a normal text editor (with
fixed-width font)

I had a hack elsewhere that would embed the fixed-width text if the
plugin isn't present, which seemed like a decent compromise, but nobody
is willing to let plugins be used in general to start with, it seems :)

johannes

Re: [Ksummit-discuss] Including images on Sphinx documents

[Jani Nikula]

On Mon, 21 Nov 2016, Johannes Berg <johannes@sipsolutions.net> wrote:
> I had a hack elsewhere that would embed the fixed-width text if the
> plugin isn't present, which seemed like a decent compromise, but nobody
> is willing to let plugins be used in general to start with, it seems :)

FWIW I'm all for doing this stuff in Sphinx, with Sphinx extensions. And
to me it sounds like what you describe is interesting outside of kernel
too.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center

Re: [Ksummit-discuss] Including images on Sphinx documents

[Mauro Carvalho Chehab]

Em Mon, 21 Nov 2016 16:44:28 +0100
Johannes Berg <johannes@sipsolutions.net> escreveu:

> > > > You had pointed me to this plugin before
> > > > https://pythonhosted.org/sphinxcontrib-aafig/
> > > > 
> > > > but I don't think it can actually represent any of the pictures.  
> > > 
> > > No, but there are some ascii art images inside some txt/rst files
> > > and inside some kernel-doc comments. We could either use the above
> > > extension for them or to convert into some image. The ascii art
> > > images I saw seem to be diagrams, so Graphviz would allow replacing
> > > most of them, if not all.  
> > 
> > Please don't replace ASCII art that effectively conveys conceptual
> > diagrams.  If you do, we'll wind up in situations where someone
> > hasn't built the docs and doesn't possess the tools to see a diagram
> > that was previously shown by every text editor (or can't be bothered
> > to dig out the now separate file).  In the name of creating
> > "prettier" diagrams (and final doc), we'll have damaged capacity to
> > understand stuff by just reading the source if this diagram is in
> > kernel doc comments.  I think this is a good application of "if it
> > ain't broke, don't fix it".  

I agree with it as a general rule. Yet, there are cases where the diagram 
is so complex that rewriting it with Graphviz would make sense, like
the one on this document:

	Documentation/media/v4l-drivers/pxa_camera.rst

Regards,
Mauro



> 
> Right, I agree completely!
> 
> That's the selling point of aafig though, it translates to pretty
> diagrams, but looks fine when viewed in a normal text editor (with
> fixed-width font)
> 
> I had a hack elsewhere that would embed the fixed-width text if the
> plugin isn't present, which seemed like a decent compromise, but nobody
> is willing to let plugins be used in general to start with, it seems :)
> 
> johannes


Thanks,
Mauro