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

[Jonathan Corbet]

On Tue, 26 Jan 2016 14:08:45 +0200
Jani Nikula <jani.nikula@xxxxxxxxx> wrote:

> I'm afraid we've done some overlapping work in the mean time, but I'm
> happy we've both looked at the tool chain, and can have a more
> meaningful conversation now.

Overlapping work is just how this kernel thing works :)

> I first took roughly the same approach as you did. I was really
> impressed with the speed and the beauty of the produced HTML. The
> trouble is, neither asciidoc nor asciidoctor can produce chunked (split
> to several pages) HTML directly. This is a showstopper for the gpu
> document which turns into 1.3 MB of HTML, which looks pretty but is a
> paint to navigate. To do chunked output, you have to output DocBook and
> handle that like we do now. So while I would like to have asciidoc
> generate HTML directly for speed and beauty, I ended up going the
> asciidoc to DocBook path. The upside is all the output formats are
> supported.

So I'm not really going to have time to dig too much more into this until
after LCA, so these are really quick impressions for now.

I would *really* like to get the XML step out of the processing path if
possible.  It adds complexity, makes it harder for others to build the
docs, makes things more fragile, and slows it all down.  It seems to me
that it should be possible to do that.

The issues, it seems, are splitting the output files and format support.
The latter isn't really an issue, I don't think; there are tools to do all
kinds of format conversions.  The only one that's even slightly weird is
man, and kernel-doc already has some (unused, I think) provisions for
doing that.  We could generate man pages directly without much pain.

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