Em Wed, 20 Jul 2016 17:33:31 +0200 Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu: > 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 ... Yeah, let's close the other issues first ;) > > > 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? What I meant to say is to use something that would convert from asciiart into a picture, just like Sphinx does with tables. Anyway, this is not a top priority ;) 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
