From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752374AbcBJXG0 (ORCPT ); Wed, 10 Feb 2016 18:06:26 -0500 Received: from home.keithp.com ([63.227.221.253]:48859 "EHLO elaine.keithp.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1750828AbcBJXGZ (ORCPT ); Wed, 10 Feb 2016 18:06:25 -0500 X-Greylist: delayed 304 seconds by postgrey-1.27 at vger.kernel.org; Wed, 10 Feb 2016 18:06:24 EST From: Keith Packard To: Jonathan Corbet , 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 In-Reply-To: <20160209170938.3a4b9fb1@lwn.net> References: <1453764522-29030-1-git-send-email-corbet@lwn.net> <20160209170938.3a4b9fb1@lwn.net> User-Agent: Notmuch/0.21 (http://notmuchmail.org) Emacs/24.5.1 (x86_64-pc-linux-gnu) Date: Wed, 10 Feb 2016 15:01:15 -0800 Message-ID: <861t8k2mro.fsf@hiro.keithp.com> MIME-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha256; protocol="application/pgp-signature" Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org --=-=-= Content-Type: text/plain Content-Transfer-Encoding: quoted-printable Jonathan Corbet writes: > [Adding Keith since you said you wanted to be a part of this - let us know > when you've had enough!] Thanks. > - I would like to format directly to HTML if at all possible. Agreed. asciidoc's docbook path seems to only increase the amount of software involved. > 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 I spent a few hours on the flight home reading asciidoc source code, and it is a stream processor with a stack. The output is generated with some simple templates, one for each backend. Here's the xhtml1.1 template for section level sections: (sect1 in the .conf file): [sect1]
{numbered?{sectnum} }{title}
|
The contents of the section get inserted at the |; it's nesting, so [sect2] bits would get expanded while being processed. Each asciidoc backend has dramatically different functionality. It's pretty clear to me that the 'docbook' backend has the best support for larger documents as that provides 'book-scale' processing bits. I've recently written a book in asciidoc using the docbook backend, and the html and pdf results are quite comparable. Using the html backend from asciidoc yields a significantly different result. I think it should be pretty easy to hack asciidoc to add diversions to hold TOC contents while generating the rest of the doc and then replay the diversion into the final document. Something like: [sect1]
{numbered?{sectnum} }{title} |>"table-of-contents"
{numbered?{sectnum} {title= }
|
At the end of the document, we'd have some way of wrapping the diversion in suitable additional bits to complete the TOC, which would then be formatted by CSS. This same technique could be used to create lists of figures and tables. The goal would be to create an html document which could be used without javascript, and that would work without css as well. =2D-=20 =2Dkeith --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 iQIVAwUBVrvBO9siGmkAAAARAQjHTw/8DLE7JHKWh560wfdjTHs1EJ5lRzsM4ZAJ RpM+0cVo9v+yCRv/6Jd54LWE5dtNU1X/Nr9N0RznEl1LuZxRMYzgtI1NxPQpMGxL QjM7fBnhYy4BJOofXa65Ms76wvrRlc2V+KcEYGtNvhJg0IQASK/ITZm0ptnUk5KK KFxgvWwLySUl2D0RJOMhVRxESua6xJOTx4mSza1Bw7gE8InC9/KAXnuti3y1luXp 8NmXwGhz9/iIl89ToFGLg0WeGO404iVvHXh66p1nnNbR4wsrVQRQQBfqCv8mdovs qjQtqK5GxHFtTxcTagYbKmDG7oUCnQO2m0UDpedceEiNZ68ogYtefq5yujU84QcX ELk38w7986VuYVJskdfDlRsTA12t9UhcjbrTLRYmDVBah+EL6j1OVwSaM9jxiKkx DWubYh6xk+QbDp6al7b7bmiDt8jj2zNiulbT21adQ0XD4nwe7dHj7KeiUdRxb9UL rrUd60bWHK8a9sIp7gL6daq6Z/5rxGKY0+5NhE71MA4o0S0fy0EzrKtAebiUCxZ/ M3Rnv2cbwZlIgIS9KjkdwucKM84xYd1FDbL1UWKPvw38Ab8Ul0Oxkfg8mfzrEjYe nXzJx0L/gg3CSy1OhxGK7qPteWNEhchZ2QihLYstei/xIcDQ83Kt2w02tOPCFjGx ePfFiDzLCTA= =E3QQ -----END PGP SIGNATURE----- --=-=-=--