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

[Jonathan Corbet]

On Wed, 10 Feb 2016 09:07:22 +0100
Daniel Vetter <daniel.vetter@xxxxxxxx> wrote:

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

That can be fine, I'd just like to have the end goal in mind.  For the near
future we should go with what actually works, definitely.

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

That's a good question.  I can certainly see the value of mixing the
templates with the rest, but that's a longer-term thing.  I'd sure like to
clean up the main Documentation/ directory before we start scattering
asciidoc stuff around there.  For the moment, I think my preference is
still to focus this work in one place where it's easily found and played
with.  Straightening out this directory is going to involve a fair amount
of moving stuff around, adding a few template files to that debt isn't
going to change the situation much.

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

Well, we are talking about an order of magnitude more files...  Still, I
said "not sold on" rather than "violently opposed to".  It does seem that
there are some good reasons for doing things this way, including, as Jani
said, getting rid of docproc and not mixing in a weird alien include
syntax.  I'm still not 100% sold, but I'll not hold up a working patch on
this point.

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

asm stuff and things built into libraries.  But it does seem that this is
well on the way toward being fixed.

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

Not yet.  It's worth doing...it would be nice, someday, if docs makefiles
could just have lines like:

      adoc-y += drm.txt ...

but I think we should work out how the pieces fit together before we get
too worried about the details of the build system.  What we have now isn't
particularly well integrated, we're not likely to make it all that much
worse...

Thanks,

jon