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

From: Jonathan Corbet
Date: Tue Jan 26 2016 - 09:52:13 EST

On Tue, 26 Jan 2016 07:48:21 -0700
Jonathan Corbet <corbet@xxxxxxx> wrote:

> 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

So let's try this again without hitting that "send" button prematurely,
sigh. Claws is annoying sometimes.

You'd said:

> (We could of course split the source documents, but then I believe we'd
> have lots of trouble cross-referencing between the documents. I could be
> proven wrong. I'd *like* to be proven wrong.)

I'd like to solve the cross-reference problem anyway; the documents
shouldn't be silos unto themselves. Sphinx and ReST can do that; I *bet*
the other formats can too. Maybe I can dig into some of that in my
upcoming airplane time (LAX->MEL, 15:45, sigh).

> I should also remind us that the original goal was to enable lightweight
> markup for documentation. This seems very much achievable now.

Agreed, nice work.