From mboxrd@z Thu Jan 1 00:00:00 1970 From: Danilo Cesar Lemes de Paula Subject: Re: [PATCH v2] scripts/kernel-doc: Adding cross-reference links to html documentation. Date: Mon, 13 Jul 2015 17:19:42 -0300 Message-ID: <55A41D5E.2070700@collabora.co.uk> References: <558D5D91.8090301@collabora.co.uk> <1435331337-22924-1-git-send-email-danilo.cesar@collabora.co.uk> <20150709175632.49f6ee64@lwn.net> Mime-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: base64 Return-path: In-Reply-To: <20150709175632.49f6ee64@lwn.net> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: intel-gfx-bounces@lists.freedesktop.org Sender: "Intel-gfx" To: Jonathan Corbet Cc: 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 List-Id: dri-devel@lists.freedesktop.org T24gMDcvMDkvMjAxNSAwODo1NiBQTSwgSm9uYXRoYW4gQ29yYmV0IHdyb3RlOgo+IE9uIEZyaSwg MjYgSnVuIDIwMTUgMTI6MDg6NTcgLTAzMDAKPiBEYW5pbG8gQ2VzYXIgTGVtZXMgZGUgUGF1bGEg PGRhbmlsby5jZXNhckBjb2xsYWJvcmEuY28udWs+IHdyb3RlOgo+IAo+PiBUbyBlYXNlIHRoZSBu YXZpZ2F0aW9uIGluIHRoZSBkb2N1bWVudGF0aW9uIHdlIHNob3VsZCB1c2UgPGxpbmtzPiBpbnNp ZGUKPj4gdGhvc2UgdGFncyBzbyByZWFkZXJzIGNhbiBlYXNpbHkganVtcCBiZXR3ZWVuIG1ldGhv ZHMgZGlyZWN0bHkuCj4+Cj4+IFRoaXMgd2FzIGRpc2N1c3NlZCBpbiAyMDE0WzFdIGFuZCBpcyBp bXBsZW1lbnRlZCBieSBnZXR0aW5nIGEgbGlzdAo+PiBvZiA8cmVmZW50cmllcz4gZnJvbSB0aGUg RG9jQm9vayBYTUwgdG8gZ2VuZXJhdGUgYSBkYXRhYmFzZS4gVGhlbiBpdCBsb29rcwo+PiBmb3Ig PGZ1bmN0aW9uPiw8c3RydWN0bmFtZXM+IGFuZCA8cGFyYW1kZWY+IHRhZ3MgdGhhdCBtYXRjaGVz IHRoZSBvbmVzIGluCj4+IHRoZSBkYXRhYmFzZS4gQXMgaXQgb25seSBsaW5rcyBleGlzdGVudCBy ZWZlcmVuY2VzLCBubyBicm9rZW4gbGlua3MgYXJlCj4+IGFkZGVkLgo+IAo+IFNvIEkgcHV0IGEg bG90IG1vcmUgdGltZSBpbnRvIHRoaXMgdG9kYXkgdGhhbiBJIHJlYWxseSBoYWQgYXZhaWxhYmxl LiAgSQoKVGhhbmtzLCBJIHJlYWxseSBhcHByZWNpYXRlIHRoYXQuCgo+IHRoaW5rIGl0J3MgY29v bCBzdHVmZiwgYW5kIHdlIGRlZmluaXRlbHkgd2FudCBpdC4gIEJ1dCBjYW4gSSBhc2sgZm9yIG9u ZQo+IG1vcmUgcGFzcz8gIEluIHBhcnRpY3VsYXI6Cj4gCj4gIC0gSXQgbWFrZXMgdGhlIGRvY3Mg YnVpbGQgYSBsb3QgbW9yZSBub2lzeSwgdGhhdCB3b3VsZCBiZSBuaWNlIHRvIGZpeC4KCkZhaXIg ZW5vdWdoLiBJdCB3YXMgc2hvd2luZyBhbGwgdGhlIGNvbW1hbmRzLiBJIGRpZCBjaGFuZ2UgdGhh dCB0byBhCmZhbmN5ICJYTUxSRUYgIERvY3VtZW50YXRpb24vRG9jQm9vay9Gb29CYXIueG1sIiBt ZXNzYWdlLgoKPiAKPiAgLSBBIGJpdCBtb3JlIGRvY3VtZW50YXRpb24gaW4gdGhlIHNjcmlwdCB3 b3VsZCBiZSBuaWNlLiAgSXQgYWxzbyBpcyBoYXBweQo+ICAgIHRvIHJ1biB3aXRoIHNpbGx5IGFy Z3VtZW50czsgYSBkZXRhaWwgc2luY2Ugbm9ib2R5IHdpbGwgcnVuIGl0Cj4gICAgZGlyZWN0bHks IGJ1dCBzdGlsbC4uLgoKSSBkaWQgaW1wcm92ZSB0aGUgZG9jdW1lbnRhdGlvbiBhbmQgYWxzbyBm aXhlZCB0aGUgc2lsbHkgYXJndW1lbnQgdGhpbmcuCgo+IAo+ICAtIE1vc3QgaW1wb3J0YW50bHks IGl0IGJyZWFrcyAibWFrZSBodG1sZG9jcyI7IGluIHBhcnRpY3VsYXIsIHZhc3QKPiAgICBhbW91 bnRzIG9mIGVycm9yIHNwZXcgcmVzdWx0cyB3aGVuIGl0IGdldHMgYXJvdW5kIHRvIG1lZGlhX2Fw aS5odG1sLiAgSQo+ICAgIHNwZW50IGEgd2hpbGUgdHJ5aW5nIHRvIGZpZ3VyZSBvdXQgd2hhdCB3 YXMgZ29pbmcgb24gYnV0IGRpZG4ndCBjb21lIHVwCj4gICAgd2l0aCBhbnl0aGluZyBjb25jbHVz aXZlOyBteSBzdXNwaWNpb24gaXMgdGhhdCBpdCBoYXMgdG8gZG8gd2l0aCB0aGUKPiAgICBzZXBh cmF0ZSBtYWtlZmlsZSBpbiBEb2N1bWVudGF0aW9uL0RvY0Jvb2svbWVkaWEvLgoKSSdtIG5vdCBz dXJlIGFib3V0IHRoaXMuCm1lZGlhLWFwaSBpcyBzcGl0dGluZyBsb3RzIG9mIHdhcm5pbmdzIHdp dGggb3Igd2l0aG91dCB0aGUgZG9jdW1lbnRhdGlvbgpwYXRjaC4KSSBjb21wYXJlZCB0aGUgbnVt YmVyIG9mIGZpbGVzIGFuZCB0aGV5J3JlIHRoZSBzYW1lIChleGNlcHRpbmcgdGhvc2UKYXV4aWxp YXJ5IGRiIGZpbGVzKS4gRm9yIG1lLCBib3RoIGJ1aWxkcyBhY3R1YWxseSBzcGl0cyAyODI1IGxp bmVzIG9uClNUREVSUi4uLgoKSSBhbHNvIGRpZCBhIHNtb2tlIGNoZWNrIGluIHRoZSBtZWRpYS1h cGkgaHRtbCBkb2N1bWVudGF0aW9uIGFuZCBpdApsb29rcyBmaW5lLgoKV291bGQgeW91IG1pbmQg dG8gY2hlY2sgYWdhaW4gaWYgaXQgaGFwcGVucyB3aXRoIHRoZSB2MyBvZiBteSBwYXRjaCBJJ20K c2VuZGluZyBuZXh0PwoKRGFuaWxvCj4gCj4gVGhhbmtzLAo+IAo+IGpvbgo+IApfX19fX19fX19f X19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fXwpJbnRlbC1nZnggbWFpbGluZyBs aXN0CkludGVsLWdmeEBsaXN0cy5mcmVlZGVza3RvcC5vcmcKaHR0cDovL2xpc3RzLmZyZWVkZXNr dG9wLm9yZy9tYWlsbWFuL2xpc3RpbmZvL2ludGVsLWdmeAo= From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753115AbbGMUTy (ORCPT ); Mon, 13 Jul 2015 16:19:54 -0400 Received: from bhuna.collabora.co.uk ([93.93.135.160]:60662 "EHLO bhuna.collabora.co.uk" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752072AbbGMUTw (ORCPT ); Mon, 13 Jul 2015 16:19:52 -0400 Message-ID: <55A41D5E.2070700@collabora.co.uk> Date: Mon, 13 Jul 2015 17:19:42 -0300 From: Danilo Cesar Lemes de Paula User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:31.0) Gecko/20100101 Icedove/31.7.0 MIME-Version: 1.0 To: Jonathan Corbet CC: linux-doc@vger.kernel.org, Randy Dunlap , Daniel Vetter , Laurent Pinchart , Herbert Xu , Stephan Mueller , Michal Marek , linux-kernel@vger.kernel.org, intel-gfx , dri-devel Subject: Re: [PATCH v2] scripts/kernel-doc: Adding cross-reference links to html documentation. References: <558D5D91.8090301@collabora.co.uk> <1435331337-22924-1-git-send-email-danilo.cesar@collabora.co.uk> <20150709175632.49f6ee64@lwn.net> In-Reply-To: <20150709175632.49f6ee64@lwn.net> Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 8bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On 07/09/2015 08:56 PM, Jonathan Corbet wrote: > On Fri, 26 Jun 2015 12:08:57 -0300 > Danilo Cesar Lemes de Paula wrote: > >> To ease the navigation in the documentation we should use inside >> those tags so readers can easily jump between methods directly. >> >> This was discussed in 2014[1] and is implemented by getting a list >> of from the DocBook XML to generate a database. Then it looks >> for , and tags that matches the ones in >> the database. As it only links existent references, no broken links are >> added. > > So I put a lot more time into this today than I really had available. I Thanks, I really appreciate that. > think it's cool stuff, and we definitely want it. But can I ask for one > more pass? In particular: > > - It makes the docs build a lot more noisy, that would be nice to fix. Fair enough. It was showing all the commands. I did change that to a fancy "XMLREF Documentation/DocBook/FooBar.xml" message. > > - A bit more documentation in the script would be nice. It also is happy > to run with silly arguments; a detail since nobody will run it > directly, but still... I did improve the documentation and also fixed the silly argument thing. > > - Most importantly, it breaks "make htmldocs"; in particular, vast > amounts of error spew results when it gets around to media_api.html. I > spent a while trying to figure out what was going on but didn't come up > with anything conclusive; my suspicion is that it has to do with the > separate makefile in Documentation/DocBook/media/. I'm not sure about this. media-api is spitting lots of warnings with or without the documentation patch. I compared the number of files and they're the same (excepting those auxiliary db files). For me, both builds actually spits 2825 lines on STDERR... I also did a smoke check in the media-api html documentation and it looks fine. Would you mind to check again if it happens with the v3 of my patch I'm sending next? Danilo > > Thanks, > > jon >