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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <861t8k2mro.fsf@hiro.keithp.com>
Date:	Wed, 10 Feb 2016 15:01:15 -0800
From:	Keith Packard <keithp@...thp.com>
To:	Jonathan Corbet <corbet@....net>,
	Jani Nikula <jani.nikula@...el.com>
Cc:	linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
	Daniel Vetter <daniel.vetter@...ll.ch>
Subject: Re: [RFC] A first shot at asciidoc-based formatted docs

Jonathan Corbet <corbet@....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

Download attachment "signature.asc" of type "application/pgp-signature" (811 bytes)