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

[Jonathan Corbet <corbet@lwn.net>]

On Tue, 26 Jan 2016 07:48:21 -0700
Jonathan Corbet <corbet@lwn.net> 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.

jon