From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1756263AbcBJAJl (ORCPT ); Tue, 9 Feb 2016 19:09:41 -0500 Received: from tex.lwn.net ([70.33.254.29]:60612 "EHLO vena.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1755225AbcBJAJk (ORCPT ); Tue, 9 Feb 2016 19:09:40 -0500 Date: Tue, 9 Feb 2016 17:09:38 -0700 From: Jonathan Corbet To: Jani Nikula Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Daniel Vetter , Keith Packard Subject: Re: [RFC] A first shot at asciidoc-based formatted docs Message-ID: <20160209170938.3a4b9fb1@lwn.net> In-Reply-To: References: <1453764522-29030-1-git-send-email-corbet@lwn.net> 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: X-Mailing-List: linux-kernel@vger.kernel.org On Tue, 26 Jan 2016 14:08:45 +0200 Jani Nikula wrote: > I'm afraid we've done some overlapping work in the mean time, but I'm > happy we've both looked at the tool chain, and can have a more > meaningful conversation now. [Adding Keith since you said you wanted to be a part of this - let us know when you've had enough!] So I've spent a bit of time looking at this, and quite a bit more time talking with various folks at LCA. There is pretty much universal agreement that this is interesting work and the direction we'd like to go. My current hope is that we can merge some version of it for 4.6 and see where it goes from there. So naturally I have some thoughts on the whole thing... - I would like to format directly to HTML if at all possible. It seems it should be possible to get a table of contents into the files, and the feedback I got was that a TOC would be enough for navigation - it would not be necessary to split the files at that point. We might still want to try to figure that out too, though. In any case, this isn't a show stopper, in that we can change it anytime if a better way shows up. But I'd like to have it in mind. - Asciidoc templates and processing should happen in a new directory (perhaps imaginatively called "asciidoc"); having them in a directory called "DocBook" seems a little weird. More importantly, though, I'd like to separate them out as a fresh start, and not mess with the existing DocBook templates until we decide we don't need them anymore. If we could end up with a cleaner, simpler makefile in the process, that would be a bonus. - I'm not sold on the new inclusion mechanism. Creating thousands of little files and tracking them for dependencies and such doesn't seem like a simplification or a path toward better performance. I would like to at least consider keeping the direct-from-source inclusion. - Insisting on EXPORT_SYMBOL being in the same file doesn't seem like it's going to work for now; that could maybe change after Al's work goes in, which could be fairly soon. Please let me know your thoughts on the above. Do you think you can find some time over the next month for this? I'll try to shake loose some time too, but, well, $EXCUSES... Many thanks for doing this work! jon