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 -- 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
