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

[Daniel Vetter <daniel.vetter@ffwll.ch>]

On Wed, Feb 10, 2016 at 1:09 AM, Jonathan Corbet <corbet@lwn.net> wrote:
> On Tue, 26 Jan 2016 14:08:45 +0200
> Jani Nikula <jani.nikula@intel.com> 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.

I think for 4.6 it'd be best to go with the hybrid asciidoc->docbook
toolchain, since that's less disruptive. And with that we can also
fully concentrating on the frontend, and how it'll look and behave.

Once that's solid we can look into the icing on the cake for later
kernels I think.

>  - 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.

For the long term dream plan of including other .txt files from the
existing pile of unstructured docs, do we really want a separate
asciidoc directory? Or just .asciidoc as a special extension?

>  - 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.

The motivation behind the new inclusion mechanism isn't the speed-up
due to parallelization, but being able to use native asciidoc
includes. With those you can pass options to e.g. shift the hierarchy.
With that you can do subheadings in DOC: sections and then seamlessly
include them. Or similar stuff.

The speed-up due to parallelization is just a small bonus.

Also generating thousands of files is totally not unheard of in the kernel:

$ find include/config | wc -l
2623

None of those are in git.

>  - 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.

Hm, assuming Al gets his stuff into 4.6 could we just assume this? It
holds true for gpu docs already I think, and most other subsystems.
The trouble iirc is all around asm and similar stuff, and we can't
kerneldoc asm afaik.

> 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...

One more thing we discussed: Did you ping kbuild folks already? Or
want to get some agreement on the overall build process first?

Cheers, Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch