Am 20.07.2016 um 17:06 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>: > Em Wed, 20 Jul 2016 16:49:59 +0200 > Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu: > >> 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 :) > > I actually think that the best would be if we could have a way to > "draw" graphs inside the documentation. please .. not yet ;-) ... we have so many problem sites to close first ... graphiz & Co. bring additional dependencies to fulfill in context with sphinx 1.2 ... > We have a few cases of > diagrams like the above at the media documentation too. > > As Sphinx seems to like ASCIIart, IMHO, the more Sphinx-style > way would be to have a: > > .. code-block:: asciiart > > markup to handle it. why a special markup for a literal block? -- M -- > Another possibility would be to have a graphviz extension. > >> >> --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 >> > > > > 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 -- 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
