Re: [PATCH] doc-rst: get rid of warnings at kernel-documentation.rst

[Mauro Carvalho Chehab <mchehab@s-opensource.com>]

Em Wed, 20 Jul 2016 17:06:41 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Wed, 20 Jul 2016 11:41:11 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > > The thing with that is that a lot of literal blocks *do* have C code, even
> > > in kernel-documentation.rst.  Setting that in conf.py would turn off all C
> > > highlighting.  I think that might actually be a desirable outcome, but it
> > > would be good to make that decision explicitly.    
> > 
> > Agreed. Assuming "C" as default seems a good idea to me.  
> 
> "Agreed," but there was an implied question there that, I think, deserves
> consideration.  Do we want to have a default highlighting language for
> literal blocks at all?  Those blocks will contain ascii art diagrams,
> device-tree fragments, error message examples, and who knows what else.
> Even if the majority of them are C code, having Sphinx treat all of them
> as C is going to lead to a steady stream of warnings and a lot of extra
> markup in the text.

On the documents I edited after the media conversion, I'm explicitly
telling the language (either "c" or "none") on every block. Yet,
any change like that would require to revisit all pages to be sure.
So, changing the default should not cause any change. Yet, I think
that, if we'll be changing the default, the best is to do it as
early as possible.

> Plus I'm not convinced that more color eye candy in code fragments is
> actually helpful.

I use colors on the text editors I use to edit the code and on my
shell prompt. So, I'm suspect, but, at least to me, I prefer it
colored.

Yet, I would very much prefer if, instead of changing the colors for
some random C code, it would be adding hyperlinks to all API calls.
This is what Doxygen does. So, we can include real code examples,
and the user can use them to cross reference with the corresponding
API symbols, like here:
	https://linuxtv.org/docs/libdvbv5/dvbv5-scan_8c-example.html

IMHO, we should mark all C codes as such, and then pursue the goal of
having an extension that would do the same.

> So I think I might actually argue in favor of Markus's suggestion and set
> the language to "none" by default.  But others may feel strongly about
> having their bikeshed in full syntax-highlighted color.  Opinions on the
> matter?
> 
> Thanks,
> 
> jon



Thanks,
Mauro