Re: [PATCH 3/7] kernel-doc-HOWTO: add kernel-doc specification

[Randy Dunlap]

On 06/10/16 09:00, Markus Heiser wrote:
> Hi Randy,
> 
> thanks for your amendments / has been fixed [1]
> 
> [1] https://github.com/return42/linux/commit/98a9fc42cbd0c23b266ac28494dafe20d7920d05
> 
> Am 09.06.2016 um 20:05 schrieb Randy Dunlap <rdunlap@xxxxxxxxxxxxx>:
> 
>> Hi,
>>
>> Some spellos and a few questions...
> 
>>> + b/Documentation/books/kernel-doc-HOWTO/vintage-kernel-doc-mode.rst
>>> +Within the *vintage* kernel-doc mode the kernel-doc parser highlights the pattern
>>> +above, but he also dogged ignores any whitespace formatting/markup.
>>
>> what is "dogged"??
>>
> 
> ... "insistently" ...  

ah, that would be "doggedly" then.

>>> +Within reST markup (the new bas format), the wildcard in the string
>>
>> what is "bas"??
>>
> 
> sorry, another typo: "the new base format"
> 
>>
>>> +``drm_get_*_name`` has to be masked: ``drm_get_\\*_name``. Some more examples
>>> +from reST markup:
>>> +
>>> +* Emphasis "*":  like ``*emphasis*`` or ``**emphasis strong**``
>>> +* Leading "_" :  is a *anchor* in reST markup (``_foo``).
>>> +* Trailing "_:  is a reference in reST markup (``foo_``).
>>> +* interpreted text: "`"
>>> +* inline literals: "``"
>>> +* substitution references: "|"
>>> +
>>> +As long as you in the *vintage* kernel-doc mode, these special strings will be
>>> +masked in the reST output and can't be used as *plain-text markup*.
>>> +
>>> +
>>>
>>
>> My only "requirement" (if I may have one) is that we not introduce big
>> hurdles to kernel developers adding documentation.
>>
>> I'm not saying that this is a big hurdle.. I haven't looked at it enough
>> yet.
> 
> The parser has two modes, *vintage* "kernel-doc" and "reST". You can
> switch between these modes in the source code with this two comments:  
> 
>    /* parse-markup: reST */
>    /* parse-markup: kernel-doc */
> 
> Jani says that we should prefer reST as the default mode for parsing, I 
> recommended kernel-doc as default, because all old source are written
> with the *vintage* markup .. the odd side of this is, that you have to put
> a /* parse-markup: reST */ at the top of your source file to get reST
> in use ... I don't know what the best choice might bee ... I think, it
> is the best to make an option in the conf.py for this.

Thanks for that info.


-- 
~Randy