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

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

On Sat, Sep 12, 2015 at 03:24:49PM -0600, Jonathan Corbet wrote:
> On Mon,  7 Sep 2015 17:01:58 -0300
> Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> wrote:
> 
> > The following series contains:
> >  * kernel-doc: markdown support and improvements.
> 
> OK, I've spent a while looking this stuff over.  I like the general idea,
> but I do have a couple of concerns.
> 
> 1 Installing pandoc on a Fedora system wants to drag in 70(!) packages
>   for 100MB of total stuff.  Installing it on Arch is ... well ... enough
>   to make you want to switch to Fedora.  If we add a dependency on a tool
>   this massive, people are going to complain, loudly.
> 
>   Have you looked at using something like cmark instead?  I don't know
>   the tool well, but it seems like it can do the job simply enough.  It's
>   focused, written in C, and doesn't drag in a diskful of Haskell
>   stuff.  There's lot of other converters out there too, I'm not tied to
>   this one (though I think CommonMark deserves support), but I do think
>   this question needs to be considered.

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).

> 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 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.

Thanks, Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/dri-devel