Am 20.07.2016 um 16:31 schrieb Jonathan Corbet <corbet@xxxxxxx>: > On Wed, 20 Jul 2016 16:23:28 +0200 > Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote: > >> Am 20.07.2016 um 16:11 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>: >> >>> Sphinx 1.4.5 complains about some literal blocks at >>> kernel-documentation.rst: >>> >>> Documentation/kernel-documentation.rst:373: WARNING: Could not lex literal_block as "C". Highlighting skipped. >>> Documentation/kernel-documentation.rst:378: WARNING: Could not lex literal_block as "C". Highlighting skipped. >>> Documentation/kernel-documentation.rst:576: WARNING: Could not lex literal_block as "C". Highlighting skipped. >>> >>> Fix it by telling Sphinx to consider them as "none" type. >> >> Hi Mauro, >> >> IMHO we should better fix this by unsetting the lexers default language >> in the conf.py [1] ... currently: >> >> highlight_language = 'C' # set this to 'none' >> >> As far as I know the default highlight_language is also the default >> for literal blocks starting with "::" > > 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. > > As it happens, I'd already fixed these particular warnings in docs-next: > > http://permalink.gmane.org/gmane.linux.documentation/39806 > > I took a different approach; using code-block might actually be better. In some kernel-doc comments we have constructs like this: * host point of view, the graphic address space is partitioned by multiple * vGPUs in different VMs.:: * * vGPU1 view Host view * 0 ------> +-----------+ +-----------+ * ^ |///////////| | vGPU3 | * | |///////////| +-----------+ * | |///////////| | vGPU2 | * | +-----------+ +-----------+ * mappable GM | available | ==> | vGPU1 | * | +-----------+ +-----------+ I mean, in kernel-doc comments it would be nice to have no lexer active when starting a literal block with a double colon "::". Introducing a none highlighted literal block with a directive like ".. highlight::" or ".. code-block" is a bit verbose for a C comment. And on the opposite, if one place a C construct in a literal block with a double colon "::", only the highlighting is missed, but we get now warning. At least a code-block should be a code block, not a diagram or anything other ... I don't know whats the best ... but these are my 2cent :) --Markus-- > > jon > -- > 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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
