Return-Path: <linux-kernel-owner@vger.kernel.org>
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
	id S1751553AbbGIX4n (ORCPT <rfc822;w@1wt.eu>);
	Thu, 9 Jul 2015 19:56:43 -0400
Received: from tex.lwn.net ([70.33.254.29]:52468 "EHLO vena.lwn.net"
	rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP
	id S1751189AbbGIX4e (ORCPT <rfc822;linux-kernel@vger.kernel.org>);
	Thu, 9 Jul 2015 19:56:34 -0400
Date: Thu, 9 Jul 2015 17:56:32 -0600
From: Jonathan Corbet <corbet@lwn.net>
To: Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>
Cc: linux-doc@vger.kernel.org, Randy Dunlap <rdunlap@infradead.org>,
        Daniel Vetter <daniel.vetter@ffwll.ch>,
        Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
        Herbert Xu <herbert@gondor.apana.org.au>,
        Stephan Mueller <smueller@chronox.de>, Michal Marek <mmarek@suse.cz>,
        linux-kernel@vger.kernel.org,
        intel-gfx <intel-gfx@lists.freedesktop.org>,
        dri-devel <dri-devel@lists.freedesktop.org>
Subject: Re: [PATCH v2] scripts/kernel-doc: Adding cross-reference links to
 html documentation.
Message-ID: <20150709175632.49f6ee64@lwn.net>
In-Reply-To: <1435331337-22924-1-git-send-email-danilo.cesar@collabora.co.uk>
References: <558D5D91.8090301@collabora.co.uk>
	<1435331337-22924-1-git-send-email-danilo.cesar@collabora.co.uk>
Organization: LWN.net
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 8bit
Sender: linux-kernel-owner@vger.kernel.org
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org
Content-Length: 1570
Lines: 36

On Fri, 26 Jun 2015 12:08:57 -0300
Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> wrote:

> To ease the navigation in the documentation we should use <links> 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 <refentries> from the DocBook XML to generate a database. Then it looks
> for <function>,<structnames> and <paramdef> 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
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/