From: Johannes Berg <johannes@sipsolutions.net> To: Jonathan Corbet <corbet@lwn.net>, Linus Torvalds <torvalds@linux-foundation.org> Cc: "open list:DOCUMENTATION" <linux-doc@vger.kernel.org>, Linux Kernel Mailing List <linux-kernel@vger.kernel.org>, ksummit-discuss@lists.linuxfoundation.org, Linux Media Mailing List <linux-media@vger.kernel.org> Subject: Re: [Ksummit-discuss] Including images on Sphinx documents Date: Mon, 21 Nov 2016 11:39:41 +0100 [thread overview] Message-ID: <1479724781.8662.18.camel@sipsolutions.net> (raw) In-Reply-To: <20161119101543.12b89563@lwn.net> 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
WARNING: multiple messages have this Message-ID (diff)
From: Johannes Berg <johannes@sipsolutions.net> To: Jonathan Corbet <corbet@lwn.net>, Linus Torvalds <torvalds@linux-foundation.org> Cc: Linux Kernel Mailing List <linux-kernel@vger.kernel.org>, Linux Media Mailing List <linux-media@vger.kernel.org>, ksummit-discuss@lists.linuxfoundation.org, "open list:DOCUMENTATION" <linux-doc@vger.kernel.org> Subject: Re: [Ksummit-discuss] Including images on Sphinx documents Date: Mon, 21 Nov 2016 11:39:41 +0100 [thread overview] Message-ID: <1479724781.8662.18.camel@sipsolutions.net> (raw) In-Reply-To: <20161119101543.12b89563@lwn.net> 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
next prev parent reply other threads:[~2016-11-21 10:39 UTC|newest] Thread overview: 103+ messages / expand[flat|nested] mbox.gz Atom feed top 2016-11-07 9:55 [Ksummit-discuss] Including images on Sphinx documents Mauro Carvalho Chehab 2016-11-07 9:55 ` Mauro Carvalho Chehab 2016-11-07 10:53 ` [Ksummit-discuss] " Jani Nikula 2016-11-07 10:53 ` Jani Nikula 2016-11-07 11:46 ` [Ksummit-discuss] " Mauro Carvalho Chehab 2016-11-07 11:46 ` Mauro Carvalho Chehab 2016-11-07 17:05 ` [Ksummit-discuss] " Josh Triplett 2016-11-07 17:05 ` Josh Triplett 2016-11-08 10:50 ` Mauro Carvalho Chehab 2016-11-08 10:50 ` Mauro Carvalho Chehab 2016-11-16 16:03 ` Arnd Bergmann 2016-11-16 16:03 ` Arnd Bergmann 2016-11-16 20:26 ` Mauro Carvalho Chehab 2016-11-16 20:26 ` Mauro Carvalho Chehab 2016-11-17 11:07 ` Arnd Bergmann 2016-11-17 11:07 ` Arnd Bergmann 2016-11-17 11:28 ` Jani Nikula 2016-11-17 11:28 ` Jani Nikula 2016-11-17 12:39 ` Mauro Carvalho Chehab 2016-11-17 12:39 ` Mauro Carvalho Chehab 2016-11-17 14:52 ` Theodore Ts'o 2016-11-17 14:52 ` Theodore Ts'o 2016-11-17 15:16 ` Mauro Carvalho Chehab 2016-11-17 15:16 ` Mauro Carvalho Chehab 2016-11-17 15:28 ` Johannes Berg 2016-11-17 15:28 ` Johannes Berg 2016-11-17 16:25 ` James Bottomley 2016-11-17 16:25 ` James Bottomley 2016-11-17 15:32 ` Mauro Carvalho Chehab 2016-11-17 15:32 ` Mauro Carvalho Chehab 2016-11-17 16:02 ` Linus Torvalds 2016-11-17 16:02 ` Linus Torvalds 2016-11-17 16:04 ` Linus Torvalds 2016-11-17 16:04 ` Linus Torvalds 2016-11-18 9:15 ` Jani Nikula 2016-11-18 9:15 ` Jani Nikula 2016-11-18 10:23 ` Daniel Vetter 2016-11-18 10:23 ` Daniel Vetter 2016-11-19 17:15 ` Jonathan Corbet 2016-11-19 17:15 ` Jonathan Corbet 2016-11-19 17:38 ` Andrew Lunn 2016-11-19 17:38 ` Andrew Lunn 2016-11-19 17:50 ` Bart Van Assche 2016-11-19 17:50 ` Bart Van Assche 2016-11-19 17:50 ` Bart Van Assche 2016-11-19 17:55 ` David Woodhouse 2016-11-19 17:55 ` David Woodhouse 2016-11-19 18:45 ` Linus Torvalds 2016-11-19 18:45 ` Linus Torvalds 2016-11-19 22:59 ` David Woodhouse 2016-11-19 22:59 ` David Woodhouse 2016-11-20 14:26 ` Mauro Carvalho Chehab 2016-11-20 14:26 ` Mauro Carvalho Chehab 2016-11-19 20:54 ` Mauro Carvalho Chehab 2016-11-19 20:54 ` Mauro Carvalho Chehab 2016-11-19 21:09 ` Linus Torvalds 2016-11-19 21:09 ` Linus Torvalds 2016-11-21 10:39 ` Johannes Berg [this message] 2016-11-21 10:39 ` Johannes Berg 2016-11-21 14:06 ` Mauro Carvalho Chehab 2016-11-21 14:06 ` Mauro Carvalho Chehab 2016-11-21 15:41 ` James Bottomley 2016-11-21 15:41 ` James Bottomley 2016-11-21 15:44 ` Johannes Berg 2016-11-21 15:44 ` Johannes Berg 2016-11-21 15:47 ` Jani Nikula 2016-11-21 15:47 ` Jani Nikula 2016-11-21 19:48 ` Mauro Carvalho Chehab 2016-11-21 19:48 ` Mauro Carvalho Chehab 2016-11-13 21:00 ` Jonathan Corbet 2016-11-13 21:00 ` Jonathan Corbet 2016-11-14 14:16 ` [Ksummit-discuss] " Mauro Carvalho Chehab 2016-11-14 14:16 ` Mauro Carvalho Chehab 2016-11-09 12:27 ` [Ksummit-discuss] " Mauro Carvalho Chehab 2016-11-09 12:27 ` Mauro Carvalho Chehab 2016-11-07 17:01 ` [Ksummit-discuss] " Josh Triplett 2016-11-07 17:01 ` Josh Triplett 2016-11-09 9:22 ` Markus Heiser 2016-11-09 9:22 ` Markus Heiser 2016-11-09 11:16 ` Jani Nikula 2016-11-09 11:16 ` Jani Nikula 2016-11-09 11:27 ` Mauro Carvalho Chehab 2016-11-09 11:27 ` Mauro Carvalho Chehab 2016-11-09 11:45 ` Jani Nikula 2016-11-09 11:45 ` Jani Nikula 2016-11-09 11:27 ` Markus Heiser 2016-11-09 11:27 ` Markus Heiser 2016-11-09 11:58 ` Jani Nikula 2016-11-09 11:58 ` Jani Nikula 2016-11-09 22:11 ` Markus Heiser 2016-11-09 22:11 ` Markus Heiser 2016-11-10 10:35 ` Jani Nikula 2016-11-10 10:35 ` Jani Nikula 2016-11-11 11:22 ` Jani Nikula 2016-11-11 11:22 ` Jani Nikula 2016-11-11 11:45 ` Markus Heiser 2016-11-11 11:45 ` Markus Heiser 2016-11-11 9:34 ` Mauro Carvalho Chehab 2016-11-11 9:34 ` Mauro Carvalho Chehab 2016-11-13 19:52 ` Jonathan Corbet 2016-11-13 19:52 ` Jonathan Corbet 2016-11-14 13:30 ` [Ksummit-discuss] " Mauro Carvalho Chehab 2016-11-14 13:30 ` Mauro Carvalho Chehab
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=1479724781.8662.18.camel@sipsolutions.net \ --to=johannes@sipsolutions.net \ --cc=corbet@lwn.net \ --cc=ksummit-discuss@lists.linuxfoundation.org \ --cc=linux-doc@vger.kernel.org \ --cc=linux-kernel@vger.kernel.org \ --cc=linux-media@vger.kernel.org \ --cc=torvalds@linux-foundation.org \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.