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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20150913211758.GA6103@wunner.de>
Date:	Sun, 13 Sep 2015 23:17:58 +0200
From:	Lukas Wunner <lukas@...ner.de>
To:	Jonathan Corbet <corbet@....net>
Cc:	Danilo Cesar Lemes de Paula <danilo.cesar@...labora.co.uk>,
	Michal Marek <mmarek@...e.cz>,
	Herbert Xu <herbert@...dor.apana.org.au>,
	linux-doc@...r.kernel.org, Stephan Mueller <smueller@...onox.de>,
	Daniel Vetter <daniel.vetter@...ll.ch>,
	intel-gfx <intel-gfx@...ts.freedesktop.org>,
	Randy Dunlap <rdunlap@...radead.org>,
	linux-kernel@...r.kernel.org,
	dri-devel <dri-devel@...ts.freedesktop.org>,
	Laurent Pinchart <laurent.pinchart@...asonboard.com>
Subject: Re: [PATCH 1/6] scripts/kernel-doc: Replacing highlights hash by an
 array

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@...labora.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
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/