Re: [PATCH 0/6] scripts/kernel-doc: Kernel-doc improvements

From: Jonathan Corbet <corbet@lwn.net>
To: Daniel Vetter <daniel@ffwll.ch>
Cc: Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>,
	Daniel Vetter <daniel.vetter@ffwll.ch>,
	Andrew Morton <akpm@linux-foundation.org>,
	Johannes Berg <johannes.berg@intel.com>,
	linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org,
	intel-gfx <intel-gfx@lists.freedesktop.org>,
	dri-devel <dri-devel@lists.freedesktop.org>
Subject: Re: [PATCH 0/6] scripts/kernel-doc: Kernel-doc improvements
Date: Sun, 13 Sep 2015 13:13:56 -0600	[thread overview]
Message-ID: <20150913131356.780426e9@lwn.net> (raw)
In-Reply-To: <20150913103607.GA3383@phenom.ffwll.local>

On Sun, 13 Sep 2015 12:36:07 +0200
Daniel Vetter <daniel@ffwll.ch> wrote:

> Personally I don't care which kind of text markup we pick and wich
> converter, as long as the project looks reasonable far away from
> immeninent death (way too many one-person projects on github in this
> area).
> 
> But if we have this discussion I'd like to decouple it from the other
> kerneldoc improvemnts in this series (patches 1, 5 and 6). If we cant
> agree on the text markup then drm docs will simply look a bit funny for
> everyone else. But if the inline struct stuff won't happen 0-day will
> scream around (and there's already patches which use the new layout).

Those patches are:

1)  scripts/kernel-doc: Replacing highlights hash by an array
5)  scripts/kernel-doc: Improve Markdown results
6)  scripts/kernel-doc: Processing -nofunc for functions only

#1 is fine, I'll merge that today.  #6 is already merged.  #5 is a markdown
patch, though, and doesn't make sense without the others?  Are you thinking
about #3 (drm/doc: Convert to markdown)?  That one would almost work (it
depends on #2 currently) and it nicely shows *why* I'd like to get away from
XML... 

> > 2 We're constructing an increasingly complicated document-processing
> >   mechanism with a lot of independently moving parts.  What if we
> >   converted the whole document to markdown and dispensed with the XML
> >   part altogether?  Making the source files simpler and dispensing with
> >   the xmlto requirement would be a big win, IMO.
> 
> Who's going to convert the almost 30kloc of xml template (which often have
> large amounts of texts) and the over 60k kerneldoc comments that we have
> already?

I thought you'd do that :)

Seriously, though, a change would be a big job.  There's a reason I've said
several times that it would make no sense to delay the work at hand in the
hopes of somebody doing this whole job instead.  But we can certainly
ponder what might be better.

Getting rid of the XML stuff may well simplify the whole process and make
the documentation much more accessible for those who would change it; that
could be a goal worth going for.  Oh, and anything requiring changes to the
kerneldoc comments is going nowhere, that was never something I'd
contemplated.  Those comments are fine.

But any such change needs a lot of thought and a reasonable proof of
concept.  Meanwhile we have work that can make the docs better now, and I
want to merge it.  But we should choose the tools we use carefully, and I
anticipate a lot of opposition to one that has to drag in 70 Haskell
packages with it.

> > I will not make #2 be a precondition to getting some form of this work
> > merged, but I would like to have a good answer for #1.  Adding such a
> > heavyweight dependency (even as an optional one) needs to have a pretty
> > good story behind it.
> 
> Should we discuss #1 at ks? Imo as long as no one pipes up to do the
> massive conversion away from the current toolchain (and subsystem
> maintainers won't just kill that effort because it causes too much churn)
> moving forward with the kerneldoc toolchain we have makes sense. Hence I'd
> like to see those patches landed before we resolve #1 if possible.

I've tossed the topic out there; the kernel summit agenda hasn't been made
yet, though.  In any case, I'd be happy to resolve this particular issue
before then if it were possible.

jon