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