From: Markus Heiser <markus.heiser@darmarit.de>
To: Randy Dunlap <rdunlap@infradead.org>
Cc: corbet@lwn.net, jani.nikula@intel.com, daniel.vetter@ffwll.ch,
grant.likely@secretlab.ca, mchehab@osg.samsung.com,
keithp@keithp.com, linux-kernel@vger.kernel.org,
linux-doc@vger.kernel.org, hverkuil@xs4all.nl
Subject: Re: [PATCH 3/7] kernel-doc-HOWTO: add kernel-doc specification
Date: Fri, 10 Jun 2016 18:00:17 +0200 [thread overview]
Message-ID: <31D63290-0177-466E-9C30-C4E7268CF99A@darmarit.de> (raw)
In-Reply-To: <5759AFD8.5090509@infradead.org>
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@infradead.org>:
> 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
next prev parent reply other threads:[~2016-06-10 16:00 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-06-06 16:32 [PATCH 0/7] add reST/sphinx-doc to linux documentation Markus Heiser
2016-06-06 16:32 ` [PATCH 1/7] python: add scripts/site-packages Markus Heiser
2016-06-06 16:32 ` [PATCH 2/7] sphinx-doc: add basic sphinx-build infrastructure Markus Heiser
2016-06-06 16:32 ` [PATCH 3/7] kernel-doc-HOWTO: add kernel-doc specification Markus Heiser
2016-06-09 18:05 ` Randy Dunlap
2016-06-09 18:42 ` Jani Nikula
2016-06-10 16:00 ` Markus Heiser [this message]
2016-06-10 16:04 ` Randy Dunlap
2016-06-06 16:32 ` [PATCH 4/7] linuxdoc: add python package linuxdoc Markus Heiser
2016-06-06 16:32 ` [PATCH 5/7] kernel-doc parser: inital python implementation Markus Heiser
2016-06-06 16:32 ` [PATCH 6/7] kernel-doc directive: initial implementation Markus Heiser
2016-06-06 16:32 ` [PATCH 7/7] flat-table " Markus Heiser
2016-06-07 7:54 ` [PATCH 0/7] add reST/sphinx-doc to linux documentation Daniel Vetter
2016-06-07 8:59 ` Jani Nikula
2016-06-07 9:36 ` Markus Heiser
2016-06-07 11:09 ` Jani Nikula
2016-06-07 15:13 ` Markus Heiser
2016-06-07 9:14 ` Markus Heiser
2016-06-08 19:49 ` Jonathan Corbet
2016-06-10 15:25 ` Markus Heiser
2016-06-10 17:19 ` Jani Nikula
2016-06-15 13:01 ` Markus Heiser
2016-06-07 13:47 ` Markus Heiser
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=31D63290-0177-466E-9C30-C4E7268CF99A@darmarit.de \
--to=markus.heiser@darmarit.de \
--cc=corbet@lwn.net \
--cc=daniel.vetter@ffwll.ch \
--cc=grant.likely@secretlab.ca \
--cc=hverkuil@xs4all.nl \
--cc=jani.nikula@intel.com \
--cc=keithp@keithp.com \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=mchehab@osg.samsung.com \
--cc=rdunlap@infradead.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).