From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S966404AbcAZOwL (ORCPT ); Tue, 26 Jan 2016 09:52:11 -0500 Received: from tex.lwn.net ([70.33.254.29]:37459 "EHLO vena.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S965271AbcAZOwG (ORCPT ); Tue, 26 Jan 2016 09:52:06 -0500 Date: Tue, 26 Jan 2016 07:52:04 -0700 From: Jonathan Corbet To: Jani Nikula Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Daniel Vetter Subject: Re: [RFC] A first shot at asciidoc-based formatted docs Message-ID: <20160126075204.6f6bd0e2@lwn.net> In-Reply-To: <20160126074821.5303b782@lwn.net> References: <1453764522-29030-1-git-send-email-corbet@lwn.net> <20160126074821.5303b782@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 07:48:21 -0700 Jonathan Corbet wrote: > For HTML-page splitting, we can see if the tools can help us, consider > splitting the template files, or do the splitting in a postprocessing > step. Docproc (or whatever replaces it) could also maybe do that work. > It doesn't seem to me something that should force the inclusion of an > entire XML-based processing step. > > > > But then, I'm here spouting ideas without any proof to back them up again, > so who knows...:) > > Thanks for doing this work. As you said, it has been demonstrated So let's try this again without hitting that "send" button prematurely, sigh. Claws is annoying sometimes. You'd said: > (We could of course split the source documents, but then I believe we'd > have lots of trouble cross-referencing between the documents. I could be > proven wrong. I'd *like* to be proven wrong.) I'd like to solve the cross-reference problem anyway; the documents shouldn't be silos unto themselves. Sphinx and ReST can do that; I *bet* the other formats can too. Maybe I can dig into some of that in my upcoming airplane time (LAX->MEL, 15:45, sigh). > I should also remind us that the original goal was to enable lightweight > markup for documentation. This seems very much achievable now. Agreed, nice work. jon