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.

[Adding Keith since you said you wanted to be a part of this - let us know
when you've had enough!]

So I've spent a bit of time looking at this, and quite a bit more time
talking with various folks at LCA.  There is pretty much universal
agreement that this is interesting work and the direction we'd like to
go.  My current hope is that we can merge some version of it for 4.6 and
see where it goes from there.

So naturally I have some thoughts on the whole thing...

 - I would like to format directly to HTML if at all possible.  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 - it
   would not be necessary to split the files at that point.  We might
   still want to try to figure that out too, though.  In any case, this
   isn't a show stopper, in that we can change it anytime if a better way
   shows up.  But I'd like to have it in mind.

 - Asciidoc templates and processing should happen in a new directory
   (perhaps imaginatively called "asciidoc"); having them in a directory
   called "DocBook" seems a little weird.  More importantly, though, I'd
   like to separate them out as a fresh start, and not mess with the
   existing DocBook templates until we decide we don't need them anymore.
   If we could end up with a cleaner, simpler makefile in the process,
   that would be a bonus.

 - I'm not sold on the new inclusion mechanism.  Creating thousands of
   little files and tracking them for dependencies and such doesn't seem
   like a simplification or a path toward better performance.  I would
   like to at least consider keeping the direct-from-source inclusion.  

 - Insisting on EXPORT_SYMBOL being in the same file doesn't seem like
   it's going to work for now; that could maybe change after Al's work
   goes in, which could be fairly soon.

Please let me know your thoughts on the above.  Do you think you can find
some time over the next month for this?  I'll try to shake loose some time
too, but, well, $EXCUSES...

Many thanks for doing this work!

jon