Date:	Wed, 4 May 2016 17:55:05 +0200
From:	Markus Heiser <markus.heiser@...marit.de>
To:	Daniel Vetter <daniel@...ll.ch>,
	Jani Nikula <jani.nikula@...el.com>,
	Jonathan Corbet <corbet@....net>
Cc:	Daniel Vetter <daniel.vetter@...ll.ch>,
	Grant Likely <grant.likely@...retlab.ca>,
	Mauro Carvalho Chehab <mchehab@....samsung.com>,
	Dan Allen <dan@...ndevise.io>,
	Russel Winder <russel@...der.org.uk>,
	Keith Packard <keithp@...thp.com>,
	LKML <linux-kernel@...r.kernel.org>, linux-doc@...r.kernel.org,
	Hans Verkuil <hverkuil@...all.nl>,
	"linux-media@...r.kernel.org linux-media" 
	<linux-media@...r.kernel.org>,
	Graham Whaley <graham.whaley@...ux.intel.com>
Subject: Re: Kernel docs: muddying the waters a bit

Am 04.05.2016 um 15:43 schrieb Daniel Vetter <daniel@...ll.ch>:

> On Wed, May 04, 2016 at 02:40:29PM +0200, Markus Heiser wrote:
>>> On Wed, 04 May 2016, Markus Heiser <markus.heiser@...marit.de> wrote:
>>> I'd be *very* hesitant about adding the kind of things you do in
>>> reformat_block_rst to kernel-doc. IMO the extraction from kernel-doc
>>> comments must be as simple as possible with basically pass-through of
>>> the comment blocks to sphinx.
>> 
>> Right, but you forgot, that the current markup in the source code comments
>> is based on the  kernel-doc-nano-HOWTO and I guess no one will migrate all
>> these source code comments to reST markup ;-)
>> 
>> So there is a need to differentiate between *vintage* kernel-doc markup 
>> and reST markup.
>> 
>> My suggestion is to add a tag to the comments, here a short example
>> what this might look like.
>> 
>> <vintage-comment-SNIP> --------------
>> /**
>> * drm_minor_release - Release DRM minor
>> * @minor: Pointer to DRM minor object
>> *
>> * Release a minor that was previously acquired via drm_minor_acquire().
>> */
>> <vintage-comment-SNAP> --------------
>> 
>> in short: the vintage style does not need any change and 
>> comments with reST markup has a tag ":reST:" in the first 
>> line(s) ...
>> 
>> <reST-comment-SNIP> --------------
>> /**
>> * :reST:
>> *
>> * .. c:function:: void drm_minor_release(struct drm_minor *minor)
>> *
>> *    Release DRM minor
>> *
>> *    :param struct drm_minor \*minor: Pointer to DRM minor object
>> *
>> */
>> <reST-comment-SNAP> --------------
>> 
>> Comments with the ":reST:" tag could be exported and pass-through
>> to sphinx.
>> 
>>> Specifically, do not attempt to detect and
>>> parse elements like lists in kernel-doc.
>> 
>> If your markup in the comments is plain reST, no need to parse, but there
>> are markups in the (vintage) comments which made use of individual 
>> text-markups, e.g. the markup of lists or ASCII-art. 
>> 
>> This individual text-markups has not been converted/rendered in the docbook
>> output, but I wanted to convert this individuals to reST, to render them in
>> Sphinx.
> 
> I think we need to unconfuse what's current standardize kerneldoc markup.
> There's three bits:
> - The header with the one-liner and parameters, i.e.

OK, forget my <reST-comment-SNAP> example, I don't really want to promote
this way ... I agree, it is better to stay with standardize kernel-doc markup
and provide a "pass through" for the section-content (even if it is mixing 
markups).

Am 04.05.2016 um 15:41 schrieb Jani Nikula <jani.nikula@...el.com>:

> Kernel-doc the tool should continue to parse kernel-doc comments at the
> high level like they currently are, according to the kernel-doc
> howto. 

The requirement was unclear for me, thanks to Daniel and 
Jani for clarifying this.


Am 04.05.2016 um 15:43 schrieb Daniel Vetter <daniel@...ll.ch>:

> This is already used widely in kerneldoc included by gpu.tmpl, and
> currently it's asciidoc. Those lists and asciiarts though are _not_
> standard kerneldoc at all. But imo any doc toolchain improvement should
> integrate along those lines.
> 
> For reference, this is what it's supposed to look like with the asciidoc
> support enabled:
> 
> https://dri.freedesktop.org/docs/drm/API-struct-drm-display-mode.html
> 
> Fyi those hacked-up patches to make this happen are available in
> 
> https://cgit.freedesktop.org/drm-intel/log/?h=topic/kerneldoc
> 

Correct my, if I'am wrong. I'am a bit unfamiliar with DOCPROC in
particular with your "MARKDOWNREADY := gpu.xml" process.

As I understood, you convert markdown to docbook within the kernel-doc 
script using pandoc's executable? ... I don't face this topic. With my 
modification of kernel-doc I produced pure reST markup from standardize
kernel-doc markup, no intermediate steps or tools required.

Am 04.05.2016 um 15:41 schrieb Jani Nikula <jani.nikula@...el.com>:

> Overall I think we should promote fixing those in the kernel-doc
> comments. Trying to guesswork in kernel-doc tool will leave the source
> littered with bad examples that get proliferated all around. Instead of
> gradually fixing things, we'll end up gradually messing things up even
> more.

I agree with you, lets drop the reformat_block_rst from my kernel-doc script:

* https://github.com/return42/sphkerneldoc/blob/master/scripts/kernel-doc#L1736

and we should have a plain "pass through".

Am 04.05.2016 um 17:09 schrieb Jonathan Corbet <corbet@....net>:

> I think all of this makes sense.  It would be really nice to have the
> directives in the native sphinx language like that.  I *don't* think we
> need to aim for that at the outset; the docproc approach works until we can
> properly get rid of it.  What would be *really* nice would be to get
> support for the kernel-doc directive into the sphinx upstream.

No need for kernel-doc directive in sphinx upstream, later it will be 
an extension which could be installed by a simple command like 
"pip install kernel-doc-extensions" or similar.

I develop these required extension (and more) within my proof of concept
on github ... this takes time ... if I finished all my tests and all is
well, I will build the *kernel-doc-extensions* package and deploy it
on https://pypi.python.org/pypi from where everyone could install this 
with "pip".

At this time I see only one change/merge to the linux upstream, this is my
modification of the kernel-doc script to get a proper reST output.

But my recommendation is not to merge anything in a hurry.

--Markus--

Powered by blists - more mailing lists