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

[Jonathan Corbet <corbet@lwn.net>]

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.

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

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