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

[Keith Packard <keithp@keithp.com>]

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

Jonathan Corbet <corbet@lwn.net> writes:

> asciidoc->HTML on its own isn't viable, I think; we do have people wanting
> other formats.  Though one might well ask when somebody last successfully
> generated PDF...maybe it's not worth the trouble.  I would like epub
> someday...

I'm hopeful that I can hack up asciidoc to generate usable HTML
directly. Once we've got HTML, we've got epub.

If we don't want to use docbook for pdf, asciidoc has a native latex
backend. That's in about the same shape as the html backend. Would that
be better than docbook?

> There's also people who actually use the man-page output.  I don't think
> that should require the xml step; getting rid of that might make it
> possible to do "make mandocs" and have it finish before the next merge
> window opens...

Adding a troff backend to asciidoc would be simple enough; I'm not sure
what other method you'd suggest here.

> We talked about that a bit in Geelong; the short-term idea was to generate
> a TOC and use CSS to place it correctly.  Daniel, if I heard you correctly,
> you thought that would be a fine solution that would remove the need for
> chunked output.  Keith seemed interested in looking into this too.

Here's an example that takes the docbook output with some simple CSS
hacks to place the TOC alongside the document in a separate scrolling
list. With a small bit of javascript, I'm pretty sure that could have
collapsible entries.

-- 
-keith

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