Return-Path: <linux-kernel-owner@vger.kernel.org>
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
	id S1750876AbbHQELH (ORCPT <rfc822;w@1wt.eu>);
	Mon, 17 Aug 2015 00:11:07 -0400
Received: from tex.lwn.net ([70.33.254.29]:36512 "EHLO vena.lwn.net"
	rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP
	id S1750710AbbHQELF (ORCPT <rfc822;linux-kernel@vger.kernel.org>);
	Mon, 17 Aug 2015 00:11:05 -0400
Date: Sun, 16 Aug 2015 22:10:58 -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 1/4] scripts/kernel-doc: Adding cross-reference links
 to html documentation.
Message-ID: <20150816221058.0496becc@xps.lwn.net>
In-Reply-To: <1438112718-12168-2-git-send-email-danilo.cesar@collabora.co.uk>
References: <1438112718-12168-1-git-send-email-danilo.cesar@collabora.co.uk>
	<1438112718-12168-2-git-send-email-danilo.cesar@collabora.co.uk>
Organization: LWN.net
X-Mailer: Claws Mail 3.11.1 (GTK+ 2.24.28; x86_64-redhat-linux-gnu)
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: 1560
Lines: 34

On Tue, 28 Jul 2015 16:45:15 -0300
Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> wrote:

> Functions, Structs and Parameters definitions on kernel documentation
> are pure cosmetic, it only highlights the element.
> 
> 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 had some airplane time today and was able to mess with this some.  I
can't make it break anymore, and it clearly improves the resulting
documentation, so I've applied it to the docs tree for 4.3.

I want to look at the rest of the stuff a bit more and play with it, but
it's hard to imagine why we wouldn't want that as well.  I'm a bit more
leery just because it adds another dependency to the build, even if it's
an optional dependency.  My thinking at the moment is to apply it shortly
after the merge window so it can have a long soak in linux-next before a
4.4 merge; hope that sounds good.

Thanks for doing this work,

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/