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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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



[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux