Re: [PATCH 1/6] scripts/kernel-doc: Replacing highlights hash by an array

From: Lukas Wunner <lukas@wunner.de>
To: Jonathan Corbet <corbet@lwn.net>
Cc: Michal Marek <mmarek@suse.cz>,
	Herbert Xu <herbert@gondor.apana.org.au>,
	Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>,
	linux-doc@vger.kernel.org, Stephan Mueller <smueller@chronox.de>,
	Daniel Vetter <daniel.vetter@ffwll.ch>,
	intel-gfx <intel-gfx@lists.freedesktop.org>,
	Randy Dunlap <rdunlap@infradead.org>,
	linux-kernel@vger.kernel.org,
	dri-devel <dri-devel@lists.freedesktop.org>,
	Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Subject: Re: [PATCH 1/6] scripts/kernel-doc: Replacing highlights hash by an array
Date: Sun, 13 Sep 2015 23:17:58 +0200	[thread overview]
Message-ID: <20150913211758.GA6103@wunner.de> (raw)
In-Reply-To: <20150913143647.1c7a9b05@lwn.net>

Hi,

On Sun, Sep 13, 2015 at 02:36:47PM -0600, Jonathan Corbet wrote:
> On Mon,  7 Sep 2015 17:01:59 -0300
> Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> wrote:
> > The "highlight" code is very sensible to the order of the hash keys,
> > but the order of the keys cannot be predicted. It generates
> > faulty DocBook entries like:
> > 	- @<function>device_for_each_child</function>
> > 
> > Sorting the result is not enough some times (as it's deterministic but
> > we can't control it).
> > We should use an array for that job, so we can guarantee that the order
> > of the regex execution on dohighlight is correct.
> OK, I've spent a bunch of time with this, comparing the results before
> and after.  The output you mention is clearly wrong, but there might be
> room to differ over what the root cause is.
> 
> That output is caused by @device_for_each_child() in the comments.  This
> happens for a few other functions as well, and I think it's wrong.  @ is
> used to indicate parameters (or structure fields); I'm not sure why
> people are using it for functions that are *not* one of the above.
> Formatting the function names as a parameter doesn't seem right either.

Shouldn't kernel-doc print a warning for syntactic mistakes like this
rather than silently accomodating to it in whatever way?

As to the usage of markdown in general, there's documentation coming up
for vga_switcheroo which makes use of that so I'd love to see it merged:
https://github.com/l1k/linux/commit/d1476d748b5f1adf5bffe8e0a8bafad1e879d22f
https://github.com/l1k/linux/commit/11c55ae65788162970d8fa23cd1fd2518af55d34

The large set of dependencies pulled in on Fedora is likely to be blamed
on the RedHat packaging being notoriously coarse-grained. By comparison,
Debian is extremely fine-grained, kind of the opposite extreme, and
therefore has comparatively few prerequisites:
https://packages.debian.org/jessie/pandoc

I do agree however that alternative tools with fewer dependencies should
be supported and it would be great if the markdown patches were amended
to that end.

Best regards,

Lukas
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/dri-devel