From mboxrd@z Thu Jan 1 00:00:00 1970 From: Lukas Wunner Subject: Re: [PATCH 1/6] scripts/kernel-doc: Replacing highlights hash by an array Date: Sun, 13 Sep 2015 23:17:58 +0200 Message-ID: <20150913211758.GA6103@wunner.de> References: <1441656124-8997-1-git-send-email-danilo.cesar@collabora.co.uk> <1441656124-8997-2-git-send-email-danilo.cesar@collabora.co.uk> <20150913143647.1c7a9b05@lwn.net> Mime-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: base64 Return-path: Content-Disposition: inline In-Reply-To: <20150913143647.1c7a9b05@lwn.net> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" To: Jonathan Corbet Cc: Michal Marek , Herbert Xu , Danilo Cesar Lemes de Paula , linux-doc@vger.kernel.org, Stephan Mueller , Daniel Vetter , intel-gfx , Randy Dunlap , linux-kernel@vger.kernel.org, dri-devel , Laurent Pinchart List-Id: dri-devel@lists.freedesktop.org SGksCgpPbiBTdW4sIFNlcCAxMywgMjAxNSBhdCAwMjozNjo0N1BNIC0wNjAwLCBKb25hdGhhbiBD b3JiZXQgd3JvdGU6Cj4gT24gTW9uLCAgNyBTZXAgMjAxNSAxNzowMTo1OSAtMDMwMAo+IERhbmls byBDZXNhciBMZW1lcyBkZSBQYXVsYSA8ZGFuaWxvLmNlc2FyQGNvbGxhYm9yYS5jby51az4gd3Jv dGU6Cj4gPiBUaGUgImhpZ2hsaWdodCIgY29kZSBpcyB2ZXJ5IHNlbnNpYmxlIHRvIHRoZSBvcmRl ciBvZiB0aGUgaGFzaCBrZXlzLAo+ID4gYnV0IHRoZSBvcmRlciBvZiB0aGUga2V5cyBjYW5ub3Qg YmUgcHJlZGljdGVkLiBJdCBnZW5lcmF0ZXMKPiA+IGZhdWx0eSBEb2NCb29rIGVudHJpZXMgbGlr ZToKPiA+IAktIEA8ZnVuY3Rpb24+ZGV2aWNlX2Zvcl9lYWNoX2NoaWxkPC9mdW5jdGlvbj4KPiA+ IAo+ID4gU29ydGluZyB0aGUgcmVzdWx0IGlzIG5vdCBlbm91Z2ggc29tZSB0aW1lcyAoYXMgaXQn cyBkZXRlcm1pbmlzdGljIGJ1dAo+ID4gd2UgY2FuJ3QgY29udHJvbCBpdCkuCj4gPiBXZSBzaG91 bGQgdXNlIGFuIGFycmF5IGZvciB0aGF0IGpvYiwgc28gd2UgY2FuIGd1YXJhbnRlZSB0aGF0IHRo ZSBvcmRlcgo+ID4gb2YgdGhlIHJlZ2V4IGV4ZWN1dGlvbiBvbiBkb2hpZ2hsaWdodCBpcyBjb3Jy ZWN0Lgo+IE9LLCBJJ3ZlIHNwZW50IGEgYnVuY2ggb2YgdGltZSB3aXRoIHRoaXMsIGNvbXBhcmlu ZyB0aGUgcmVzdWx0cyBiZWZvcmUKPiBhbmQgYWZ0ZXIuICBUaGUgb3V0cHV0IHlvdSBtZW50aW9u IGlzIGNsZWFybHkgd3JvbmcsIGJ1dCB0aGVyZSBtaWdodCBiZQo+IHJvb20gdG8gZGlmZmVyIG92 ZXIgd2hhdCB0aGUgcm9vdCBjYXVzZSBpcy4KPiAKPiBUaGF0IG91dHB1dCBpcyBjYXVzZWQgYnkg QGRldmljZV9mb3JfZWFjaF9jaGlsZCgpIGluIHRoZSBjb21tZW50cy4gIFRoaXMKPiBoYXBwZW5z IGZvciBhIGZldyBvdGhlciBmdW5jdGlvbnMgYXMgd2VsbCwgYW5kIEkgdGhpbmsgaXQncyB3cm9u Zy4gIEAgaXMKPiB1c2VkIHRvIGluZGljYXRlIHBhcmFtZXRlcnMgKG9yIHN0cnVjdHVyZSBmaWVs ZHMpOyBJJ20gbm90IHN1cmUgd2h5Cj4gcGVvcGxlIGFyZSB1c2luZyBpdCBmb3IgZnVuY3Rpb25z IHRoYXQgYXJlICpub3QqIG9uZSBvZiB0aGUgYWJvdmUuCj4gRm9ybWF0dGluZyB0aGUgZnVuY3Rp b24gbmFtZXMgYXMgYSBwYXJhbWV0ZXIgZG9lc24ndCBzZWVtIHJpZ2h0IGVpdGhlci4KClNob3Vs ZG4ndCBrZXJuZWwtZG9jIHByaW50IGEgd2FybmluZyBmb3Igc3ludGFjdGljIG1pc3Rha2VzIGxp a2UgdGhpcwpyYXRoZXIgdGhhbiBzaWxlbnRseSBhY2NvbW9kYXRpbmcgdG8gaXQgaW4gd2hhdGV2 ZXIgd2F5PwoKQXMgdG8gdGhlIHVzYWdlIG9mIG1hcmtkb3duIGluIGdlbmVyYWwsIHRoZXJlJ3Mg ZG9jdW1lbnRhdGlvbiBjb21pbmcgdXAKZm9yIHZnYV9zd2l0Y2hlcm9vIHdoaWNoIG1ha2VzIHVz ZSBvZiB0aGF0IHNvIEknZCBsb3ZlIHRvIHNlZSBpdCBtZXJnZWQ6Cmh0dHBzOi8vZ2l0aHViLmNv bS9sMWsvbGludXgvY29tbWl0L2QxNDc2ZDc0OGI1ZjFhZGY1YmZmZThlMGE4YmFmYWQxZTg3OWQy MmYKaHR0cHM6Ly9naXRodWIuY29tL2wxay9saW51eC9jb21taXQvMTFjNTVhZTY1Nzg4MTYyOTcw ZDhmYTIzY2QxZmQyNTE4YWY1NWQzNAoKVGhlIGxhcmdlIHNldCBvZiBkZXBlbmRlbmNpZXMgcHVs bGVkIGluIG9uIEZlZG9yYSBpcyBsaWtlbHkgdG8gYmUgYmxhbWVkCm9uIHRoZSBSZWRIYXQgcGFj a2FnaW5nIGJlaW5nIG5vdG9yaW91c2x5IGNvYXJzZS1ncmFpbmVkLiBCeSBjb21wYXJpc29uLApE ZWJpYW4gaXMgZXh0cmVtZWx5IGZpbmUtZ3JhaW5lZCwga2luZCBvZiB0aGUgb3Bwb3NpdGUgZXh0 cmVtZSwgYW5kCnRoZXJlZm9yZSBoYXMgY29tcGFyYXRpdmVseSBmZXcgcHJlcmVxdWlzaXRlczoK aHR0cHM6Ly9wYWNrYWdlcy5kZWJpYW4ub3JnL2plc3NpZS9wYW5kb2MKCkkgZG8gYWdyZWUgaG93 ZXZlciB0aGF0IGFsdGVybmF0aXZlIHRvb2xzIHdpdGggZmV3ZXIgZGVwZW5kZW5jaWVzIHNob3Vs ZApiZSBzdXBwb3J0ZWQgYW5kIGl0IHdvdWxkIGJlIGdyZWF0IGlmIHRoZSBtYXJrZG93biBwYXRj aGVzIHdlcmUgYW1lbmRlZAp0byB0aGF0IGVuZC4KCkJlc3QgcmVnYXJkcywKCkx1a2FzCl9fX19f X19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fCmRyaS1kZXZlbCBtYWls aW5nIGxpc3QKZHJpLWRldmVsQGxpc3RzLmZyZWVkZXNrdG9wLm9yZwpodHRwOi8vbGlzdHMuZnJl ZWRlc2t0b3Aub3JnL21haWxtYW4vbGlzdGluZm8vZHJpLWRldmVsCg== From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1755351AbbIMV0V (ORCPT ); Sun, 13 Sep 2015 17:26:21 -0400 Received: from mailout1.hostsharing.net ([83.223.95.204]:39270 "EHLO mailout1.hostsharing.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752274AbbIMV0S (ORCPT ); Sun, 13 Sep 2015 17:26:18 -0400 X-Greylist: delayed 494 seconds by postgrey-1.27 at vger.kernel.org; Sun, 13 Sep 2015 17:26:18 EDT Date: Sun, 13 Sep 2015 23:17:58 +0200 From: Lukas Wunner To: Jonathan Corbet Cc: Danilo Cesar Lemes de Paula , Michal Marek , Herbert Xu , linux-doc@vger.kernel.org, Stephan Mueller , Daniel Vetter , intel-gfx , Randy Dunlap , linux-kernel@vger.kernel.org, dri-devel , Laurent Pinchart Subject: Re: [PATCH 1/6] scripts/kernel-doc: Replacing highlights hash by an array Message-ID: <20150913211758.GA6103@wunner.de> References: <1441656124-8997-1-git-send-email-danilo.cesar@collabora.co.uk> <1441656124-8997-2-git-send-email-danilo.cesar@collabora.co.uk> <20150913143647.1c7a9b05@lwn.net> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20150913143647.1c7a9b05@lwn.net> User-Agent: Mutt/1.5.23 (2014-03-12) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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 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: > > - @device_for_each_child > > > > 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