From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S933366AbcFJQEd (ORCPT ); Fri, 10 Jun 2016 12:04:33 -0400 Received: from merlin.infradead.org ([205.233.59.134]:60700 "EHLO merlin.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S932938AbcFJQEc (ORCPT ); Fri, 10 Jun 2016 12:04:32 -0400 Subject: Re: [PATCH 3/7] kernel-doc-HOWTO: add kernel-doc specification To: Markus Heiser References: <1465230745-31358-1-git-send-email-markus.heiser@darmarIT.de> <1465230745-31358-4-git-send-email-markus.heiser@darmarIT.de> <5759AFD8.5090509@infradead.org> <31D63290-0177-466E-9C30-C4E7268CF99A@darmarit.de> 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 From: Randy Dunlap Message-ID: <575AE505.9040800@infradead.org> Date: Fri, 10 Jun 2016 09:04:21 -0700 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.5.0 MIME-Version: 1.0 In-Reply-To: <31D63290-0177-466E-9C30-C4E7268CF99A@darmarit.de> Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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 : > >> 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