From mboxrd@z Thu Jan 1 00:00:00 1970 From: Daniel Vetter Subject: Re: [PATCH 0/6] scripts/kernel-doc: Kernel-doc improvements Date: Sun, 13 Sep 2015 12:36:07 +0200 Message-ID: <20150913103607.GA3383@phenom.ffwll.local> References: <1441656124-8997-1-git-send-email-danilo.cesar@collabora.co.uk> <20150912152449.1cdc1710@lwn.net> Mime-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: base64 Return-path: Received: from mail-wi0-f179.google.com (mail-wi0-f179.google.com [209.85.212.179]) by gabe.freedesktop.org (Postfix) with ESMTPS id 675D46E178 for ; Sun, 13 Sep 2015 03:37:02 -0700 (PDT) Received: by wiclk2 with SMTP id lk2so101066485wic.1 for ; Sun, 13 Sep 2015 03:37:00 -0700 (PDT) Content-Disposition: inline In-Reply-To: <20150912152449.1cdc1710@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: Danilo Cesar Lemes de Paula , Johannes Berg , linux-doc@vger.kernel.org, Daniel Vetter , intel-gfx , linux-kernel@vger.kernel.org, dri-devel , Andrew Morton List-Id: dri-devel@lists.freedesktop.org T24gU2F0LCBTZXAgMTIsIDIwMTUgYXQgMDM6MjQ6NDlQTSAtMDYwMCwgSm9uYXRoYW4gQ29yYmV0 IHdyb3RlOgo+IE9uIE1vbiwgIDcgU2VwIDIwMTUgMTc6MDE6NTggLTAzMDAKPiBEYW5pbG8gQ2Vz YXIgTGVtZXMgZGUgUGF1bGEgPGRhbmlsby5jZXNhckBjb2xsYWJvcmEuY28udWs+IHdyb3RlOgo+ IAo+ID4gVGhlIGZvbGxvd2luZyBzZXJpZXMgY29udGFpbnM6Cj4gPiAgKiBrZXJuZWwtZG9jOiBt YXJrZG93biBzdXBwb3J0IGFuZCBpbXByb3ZlbWVudHMuCj4gCj4gT0ssIEkndmUgc3BlbnQgYSB3 aGlsZSBsb29raW5nIHRoaXMgc3R1ZmYgb3Zlci4gIEkgbGlrZSB0aGUgZ2VuZXJhbCBpZGVhLAo+ IGJ1dCBJIGRvIGhhdmUgYSBjb3VwbGUgb2YgY29uY2VybnMuCj4gCj4gMSBJbnN0YWxsaW5nIHBh bmRvYyBvbiBhIEZlZG9yYSBzeXN0ZW0gd2FudHMgdG8gZHJhZyBpbiA3MCghKSBwYWNrYWdlcwo+ ICAgZm9yIDEwME1CIG9mIHRvdGFsIHN0dWZmLiAgSW5zdGFsbGluZyBpdCBvbiBBcmNoIGlzIC4u LiB3ZWxsIC4uLiBlbm91Z2gKPiAgIHRvIG1ha2UgeW91IHdhbnQgdG8gc3dpdGNoIHRvIEZlZG9y YS4gIElmIHdlIGFkZCBhIGRlcGVuZGVuY3kgb24gYSB0b29sCj4gICB0aGlzIG1hc3NpdmUsIHBl b3BsZSBhcmUgZ29pbmcgdG8gY29tcGxhaW4sIGxvdWRseS4KPiAKPiAgIEhhdmUgeW91IGxvb2tl ZCBhdCB1c2luZyBzb21ldGhpbmcgbGlrZSBjbWFyayBpbnN0ZWFkPyAgSSBkb24ndCBrbm93Cj4g ICB0aGUgdG9vbCB3ZWxsLCBidXQgaXQgc2VlbXMgbGlrZSBpdCBjYW4gZG8gdGhlIGpvYiBzaW1w bHkgZW5vdWdoLiAgSXQncwo+ICAgZm9jdXNlZCwgd3JpdHRlbiBpbiBDLCBhbmQgZG9lc24ndCBk cmFnIGluIGEgZGlza2Z1bCBvZiBIYXNrZWxsCj4gICBzdHVmZi4gIFRoZXJlJ3MgbG90IG9mIG90 aGVyIGNvbnZlcnRlcnMgb3V0IHRoZXJlIHRvbywgSSdtIG5vdCB0aWVkIHRvCj4gICB0aGlzIG9u ZSAodGhvdWdoIEkgdGhpbmsgQ29tbW9uTWFyayBkZXNlcnZlcyBzdXBwb3J0KSwgYnV0IEkgZG8g dGhpbmsKPiAgIHRoaXMgcXVlc3Rpb24gbmVlZHMgdG8gYmUgY29uc2lkZXJlZC4KClBlcnNvbmFs bHkgSSBkb24ndCBjYXJlIHdoaWNoIGtpbmQgb2YgdGV4dCBtYXJrdXAgd2UgcGljayBhbmQgd2lj aApjb252ZXJ0ZXIsIGFzIGxvbmcgYXMgdGhlIHByb2plY3QgbG9va3MgcmVhc29uYWJsZSBmYXIg YXdheSBmcm9tCmltbWVuaW5lbnQgZGVhdGggKHdheSB0b28gbWFueSBvbmUtcGVyc29uIHByb2pl Y3RzIG9uIGdpdGh1YiBpbiB0aGlzCmFyZWEpLgoKQnV0IGlmIHdlIGhhdmUgdGhpcyBkaXNjdXNz aW9uIEknZCBsaWtlIHRvIGRlY291cGxlIGl0IGZyb20gdGhlIG90aGVyCmtlcm5lbGRvYyBpbXBy b3ZlbW50cyBpbiB0aGlzIHNlcmllcyAocGF0Y2hlcyAxLCA1IGFuZCA2KS4gSWYgd2UgY2FudAph Z3JlZSBvbiB0aGUgdGV4dCBtYXJrdXAgdGhlbiBkcm0gZG9jcyB3aWxsIHNpbXBseSBsb29rIGEg Yml0IGZ1bm55IGZvcgpldmVyeW9uZSBlbHNlLiBCdXQgaWYgdGhlIGlubGluZSBzdHJ1Y3Qgc3R1 ZmYgd29uJ3QgaGFwcGVuIDAtZGF5IHdpbGwKc2NyZWFtIGFyb3VuZCAoYW5kIHRoZXJlJ3MgYWxy ZWFkeSBwYXRjaGVzIHdoaWNoIHVzZSB0aGUgbmV3IGxheW91dCkuCgo+IDIgV2UncmUgY29uc3Ry dWN0aW5nIGFuIGluY3JlYXNpbmdseSBjb21wbGljYXRlZCBkb2N1bWVudC1wcm9jZXNzaW5nCj4g ICBtZWNoYW5pc20gd2l0aCBhIGxvdCBvZiBpbmRlcGVuZGVudGx5IG1vdmluZyBwYXJ0cy4gIFdo YXQgaWYgd2UKPiAgIGNvbnZlcnRlZCB0aGUgd2hvbGUgZG9jdW1lbnQgdG8gbWFya2Rvd24gYW5k IGRpc3BlbnNlZCB3aXRoIHRoZSBYTUwKPiAgIHBhcnQgYWx0b2dldGhlcj8gIE1ha2luZyB0aGUg c291cmNlIGZpbGVzIHNpbXBsZXIgYW5kIGRpc3BlbnNpbmcgd2l0aAo+ICAgdGhlIHhtbHRvIHJl cXVpcmVtZW50IHdvdWxkIGJlIGEgYmlnIHdpbiwgSU1PLgoKV2hvJ3MgZ29pbmcgdG8gY29udmVy dCB0aGUgYWxtb3N0IDMwa2xvYyBvZiB4bWwgdGVtcGxhdGUgKHdoaWNoIG9mdGVuIGhhdmUKbGFy Z2UgYW1vdW50cyBvZiB0ZXh0cykgYW5kIHRoZSBvdmVyIDYwayBrZXJuZWxkb2MgY29tbWVudHMg dGhhdCB3ZSBoYXZlCmFscmVhZHk/Cgo+IEkgd2lsbCBub3QgbWFrZSAjMiBiZSBhIHByZWNvbmRp dGlvbiB0byBnZXR0aW5nIHNvbWUgZm9ybSBvZiB0aGlzIHdvcmsKPiBtZXJnZWQsIGJ1dCBJIHdv dWxkIGxpa2UgdG8gaGF2ZSBhIGdvb2QgYW5zd2VyIGZvciAjMS4gIEFkZGluZyBzdWNoIGEKPiBo ZWF2eXdlaWdodCBkZXBlbmRlbmN5IChldmVuIGFzIGFuIG9wdGlvbmFsIG9uZSkgbmVlZHMgdG8g aGF2ZSBhIHByZXR0eQo+IGdvb2Qgc3RvcnkgYmVoaW5kIGl0LgoKU2hvdWxkIHdlIGRpc2N1c3Mg IzEgYXQga3M/IEltbyBhcyBsb25nIGFzIG5vIG9uZSBwaXBlcyB1cCB0byBkbyB0aGUKbWFzc2l2 ZSBjb252ZXJzaW9uIGF3YXkgZnJvbSB0aGUgY3VycmVudCB0b29sY2hhaW4gKGFuZCBzdWJzeXN0 ZW0KbWFpbnRhaW5lcnMgd29uJ3QganVzdCBraWxsIHRoYXQgZWZmb3J0IGJlY2F1c2UgaXQgY2F1 c2VzIHRvbyBtdWNoIGNodXJuKQptb3ZpbmcgZm9yd2FyZCB3aXRoIHRoZSBrZXJuZWxkb2MgdG9v bGNoYWluIHdlIGhhdmUgbWFrZXMgc2Vuc2UuIEhlbmNlIEknZApsaWtlIHRvIHNlZSB0aG9zZSBw YXRjaGVzIGxhbmRlZCBiZWZvcmUgd2UgcmVzb2x2ZSAjMSBpZiBwb3NzaWJsZS4KClRoYW5rcywg RGFuaWVsCi0tIApEYW5pZWwgVmV0dGVyClNvZnR3YXJlIEVuZ2luZWVyLCBJbnRlbCBDb3Jwb3Jh dGlvbgpodHRwOi8vYmxvZy5mZndsbC5jaApfX19fX19fX19fX19fX19fX19fX19fX19fX19fX19f X19fX19fX19fX19fX19fXwpkcmktZGV2ZWwgbWFpbGluZyBsaXN0CmRyaS1kZXZlbEBsaXN0cy5m cmVlZGVza3RvcC5vcmcKaHR0cDovL2xpc3RzLmZyZWVkZXNrdG9wLm9yZy9tYWlsbWFuL2xpc3Rp bmZvL2RyaS1kZXZlbAo= From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752248AbbIMKhG (ORCPT ); Sun, 13 Sep 2015 06:37:06 -0400 Received: from mail-wi0-f179.google.com ([209.85.212.179]:34483 "EHLO mail-wi0-f179.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751655AbbIMKhC (ORCPT ); Sun, 13 Sep 2015 06:37:02 -0400 Date: Sun, 13 Sep 2015 12:36:07 +0200 From: Daniel Vetter To: Jonathan Corbet Cc: Danilo Cesar Lemes de Paula , Daniel Vetter , Andrew Morton , Johannes Berg , linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org, intel-gfx , dri-devel Subject: Re: [PATCH 0/6] scripts/kernel-doc: Kernel-doc improvements Message-ID: <20150913103607.GA3383@phenom.ffwll.local> Mail-Followup-To: Jonathan Corbet , Danilo Cesar Lemes de Paula , Andrew Morton , Johannes Berg , linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org, intel-gfx , dri-devel References: <1441656124-8997-1-git-send-email-danilo.cesar@collabora.co.uk> <20150912152449.1cdc1710@lwn.net> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20150912152449.1cdc1710@lwn.net> X-Operating-System: Linux phenom 4.1.0-2-amd64 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 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 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