From mboxrd@z Thu Jan 1 00:00:00 1970 From: Jonathan Corbet Subject: Re: [PATCH v2] scripts/kernel-doc: Adding cross-reference links to html documentation. Date: Thu, 9 Jul 2015 17:56:32 -0600 Message-ID: <20150709175632.49f6ee64@lwn.net> References: <558D5D91.8090301@collabora.co.uk> <1435331337-22924-1-git-send-email-danilo.cesar@collabora.co.uk> Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 8bit Return-path: In-Reply-To: <1435331337-22924-1-git-send-email-danilo.cesar@collabora.co.uk> Sender: linux-doc-owner@vger.kernel.org To: Danilo Cesar Lemes de Paula 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 List-Id: dri-devel@lists.freedesktop.org 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 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. - 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... - 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/. Thanks, jon