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" ... >> +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. -- Markus-- > > -- > ~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
