From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1425800AbcBRJLk (ORCPT ); Thu, 18 Feb 2016 04:11:40 -0500 Received: from mga04.intel.com ([192.55.52.120]:52680 "EHLO mga04.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1425593AbcBRJL0 (ORCPT ); Thu, 18 Feb 2016 04:11:26 -0500 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.22,464,1449561600"; d="scan'208";a="918321591" From: Jani Nikula To: Daniel Vetter , Jonathan Corbet Cc: Keith Packard , LKML , linux-doc@vger.kernel.org Subject: Re: Kernel docs: muddying the waters a bit In-Reply-To: Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo References: <20160213145317.247c63c7@lwn.net> <86fuwwcdmd.fsf@hiro.keithp.com> <20160217151401.3cb82f65@lwn.net> User-Agent: Notmuch/0.21+33~g570c0ae (http://notmuchmail.org) Emacs/24.4.1 (x86_64-pc-linux-gnu) Date: Thu, 18 Feb 2016 11:11:21 +0200 Message-ID: <874md6fkna.fsf@intel.com> MIME-Version: 1.0 Content-Type: text/plain Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Thu, 18 Feb 2016, Daniel Vetter wrote: > On Wed, Feb 17, 2016 at 11:14 PM, Jonathan Corbet wrote: >> On Sun, 14 Feb 2016 13:27:04 +0100 >> Daniel Vetter wrote: >> >>> One concern/open I have for pro/cons are the hyperlinks from kerneldoc >>> comments. Currently we have the postproc hack, iirc Jani's patches >>> generated links native when extracting the kerneldoc. What's the >>> solution with spinx? >> >> So I've been trying to figure out what this refers to. Is this the >> cross-reference links within the document? When I did my sphinx hack it >> used a technique that, shall we say, strongly resembles what Jani's >> patches did. One difference is that Sphinx has the concept of >> "functions" built into it, so I use function references for those. > > That's what I meant. As long as I can type in stuff like func(), > &struct and similar and get a link for it automatically (plus anywhere > else in the templated stuff for function headers) I'm really happy. I think that could be made to work in rst just as well as asciidoc. Which is to say, kernel-doc may generate broken refs in both, since it doesn't know if the link target exists outside of the file. Also, in theory, it's possible to generate non-unique targets in the end result if there are same named enums, structs, static functions etc. but I think that's less of a problem. Asciidoc just ignores these issues, I don't know what sphinx does. I think some of that could be alleviated by making the kernel-doc inclusion a directive through a sphinx extension. It could at the very least provide informative error messages. But that's distant future. Worth noting is that, AFAICT, in all of the proposals, including the original where kernel-doc produces docbook, this autoreferencing only works within parts processed by kernel-doc. Not in the template documents themselves. (You can still use the markup's more verbose cross referencing keywords.) BR, Jani. -- Jani Nikula, Intel Open Source Technology Center