Em Wed, 20 Jul 2016 17:06:41 -0600 Jonathan Corbet <corbet@xxxxxxx> escreveu: > On Wed, 20 Jul 2016 11:41:11 -0300 > Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> 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 -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
