Re: [RFC] A first shot at asciidoc-based formatted docs

[Keith Packard <keithp@keithp.com>]

[-- Attachment #1: Type: text/plain, Size: 2589 bytes --]

Jonathan Corbet <corbet@lwn.net> 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]
        <div class="sect1{style? {style}}{role? {role}}">
        <h2{id? id="{id}"}>{numbered?{sectnum} }{title}</h2>
        <div class="sectionbody">
        |
        </div>
        </div>

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]
        <div class="sect1{style? {style}}{role? {role}}">
        <h2{id? id="{id}"}>{numbered?{sectnum} }{title}</h2>
        |>"table-of-contents"<dl class="toc">
                <dt>
                        <span class="section">
                                <a href="{id}">{numbered?{sectnum} {title}</a>
                        </span>
                </dt>
        </dl>
        <div class="sectionbody">
        |
        </div>
        </div>

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.

-- 
-keith

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 810 bytes --]