Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1523637 > unrolled thread

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

Back to article view | Back to linux.kernel

This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by below is the oldest one visible, not the original post.

Contents

  Re: [Ksummit-discuss] Including images on Sphinx documents Arnd Bergmann <arnd@arndb.de> - 2016-11-16 17:10 +0100
    Re: [Ksummit-discuss] Including images on Sphinx documents Mauro Carvalho Chehab <mchehab@infradead.org> - 2016-11-16 21:30 +0100
      Re: [Ksummit-discuss] Including images on Sphinx documents Arnd Bergmann <arnd@arndb.de> - 2016-11-17 12:10 +0100
        Re: [Ksummit-discuss] Including images on Sphinx documents Jani Nikula <jani.nikula@intel.com> - 2016-11-17 12:30 +0100
          Re: [Ksummit-discuss] Including images on Sphinx documents Mauro Carvalho Chehab <mchehab@infradead.org> - 2016-11-17 18:10 +0100
        Re: [Ksummit-discuss] Including images on Sphinx documents Mauro Carvalho Chehab <mchehab@infradead.org> - 2016-11-17 18:10 +0100
        Re: [Ksummit-discuss] Including images on Sphinx documents Linus Torvalds <torvalds@linux-foundation.org> - 2016-11-17 18:10 +0100
        Re: [Ksummit-discuss] Including images on Sphinx documents James Bottomley <James.Bottomley@HansenPartnership.com> - 2016-11-17 18:10 +0100
        Re: [Ksummit-discuss] Including images on Sphinx documents Mauro Carvalho Chehab <mchehab@infradead.org> - 2016-11-17 18:20 +0100
          Re: [Ksummit-discuss] Including images on Sphinx documents Johannes Berg <johannes@sipsolutions.net> - 2016-11-17 18:30 +0100
        Re: [Ksummit-discuss] Including images on Sphinx documents Theodore Ts'o <tytso@mit.edu> - 2016-11-17 18:30 +0100
        Re: [Ksummit-discuss] Including images on Sphinx documents Linus Torvalds <torvalds@linux-foundation.org> - 2016-11-17 19:10 +0100
          Re: [Ksummit-discuss] Including images on Sphinx documents Jani Nikula <jani.nikula@intel.com> - 2016-11-18 10:20 +0100
            Re: [Ksummit-discuss] Including images on Sphinx documents Daniel Vetter <daniel@ffwll.ch> - 2016-11-18 11:30 +0100
          Re: [Ksummit-discuss] Including images on Sphinx documents Jonathan Corbet <corbet@lwn.net> - 2016-11-19 18:20 +0100
            Re: [Ksummit-discuss] Including images on Sphinx documents Andrew Lunn <andrew@lunn.ch> - 2016-11-19 18:40 +0100
            Re: [Ksummit-discuss] Including images on Sphinx documents Bart Van Assche <Bart.VanAssche@sandisk.com> - 2016-11-19 19:00 +0100
            Re: [Ksummit-discuss] Including images on Sphinx documents David Woodhouse <dwmw2@infradead.org> - 2016-11-19 19:00 +0100
              Re: [Ksummit-discuss] Including images on Sphinx documents Linus Torvalds <torvalds@linux-foundation.org> - 2016-11-19 19:50 +0100
                Re: [Ksummit-discuss] Including images on Sphinx documents "David Woodhouse" <dwmw2@infradead.org> - 2016-11-20 00:30 +0100
                  Re: [Ksummit-discuss] Including images on Sphinx documents Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-11-20 15:30 +0100
            Re: [Ksummit-discuss] Including images on Sphinx documents Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-11-19 22:00 +0100
              Re: [Ksummit-discuss] Including images on Sphinx documents Linus Torvalds <torvalds@linux-foundation.org> - 2016-11-19 22:10 +0100
            Re: [Ksummit-discuss] Including images on Sphinx documents Johannes Berg <johannes@sipsolutions.net> - 2016-11-21 11:40 +0100
              Re: [Ksummit-discuss] Including images on Sphinx documents Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-11-21 15:10 +0100
                Re: [Ksummit-discuss] Including images on Sphinx documents Jani Nikula <jani.nikula@linux.intel.com> - 2016-11-21 16:50 +0100
                Re: [Ksummit-discuss] Including images on Sphinx documents Johannes Berg <johannes@sipsolutions.net> - 2016-11-21 16:50 +0100
                  Re: [Ksummit-discuss] Including images on Sphinx documents Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-11-21 20:50 +0100
                Re: [Ksummit-discuss] Including images on Sphinx documents James Bottomley <James.Bottomley@HansenPartnership.com> - 2016-11-21 16:50 +0100

Page 2 of 2 — ← Prev page 1 [2]

#1526242

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

[toc] | [prev] | [next] | [standalone]

#1526141

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

[toc] | [prev] | [next] | [standalone]

#1526142

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

[toc] | [prev] | [next] | [standalone]

#1526549

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

[toc] | [prev] | [next] | [standalone]

#1526695

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

[toc] | [prev] | [next] | [standalone]

#1526813

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

[toc] | [prev] | [next] | [standalone]

#1526824

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

[toc] | [prev] | [next] | [standalone]

#1527005

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

[toc] | [prev] | [next] | [standalone]

#1526826

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

[toc] | [prev] | [standalone]

Page 2 of 2 — ← Prev page 1 [2]

Back to top | Article view | linux.kernel

csiph-web