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

[Jonathan Corbet]

On Wed, 10 Feb 2016 16:03:38 +0200
Jani Nikula <jani.nikula@xxxxxxxxx> wrote:

> I'd like to clarify the end goal a bit more before deciding what to do
> next. In particular, is the aim to have asciidoc->HTML only or dual
> asciidoc->HTML and asciidoc->XML->whatever? Or independent
> asciidoc->HTML first, with the existing DocBook on the side until
> everything's converted? Something else?

asciidoc->HTML on its own isn't viable, I think; we do have people wanting
other formats.  Though one might well ask when somebody last successfully
generated PDF...maybe it's not worth the trouble.  I would like epub
someday...

There's also people who actually use the man-page output.  I don't think
that should require the xml step; getting rid of that might make it
possible to do "make mandocs" and have it finish before the next merge
window opens...

> Direct asciidoc->HTML has the problem I mentioned that there is no
> chunked output. If the source is big (as-is or via asciidoc includes)
> the output is big. The current gpu.tmpl turned way too big. We could
> alleviate that by splitting the source documents into smaller pieces (in
> gpu.tmpl case it's desirable no matter what), and tying them together
> via cross-references and TOC rather than asciidoc includes.

We talked about that a bit in Geelong; the short-term idea was to generate
a TOC and use CSS to place it correctly.  Daniel, if I heard you correctly,
you thought that would be a fine solution that would remove the need for
chunked output.  Keith seemed interested in looking into this too.

I would still like to look into splitting up the output.  One would *think*
we ought to be able to do that without the whole docbook infrastructure,
but, then, I'm known to be a naive optimist...

> The problem with this, in turn, is that I don't really know how
> automatic cross-referencing between kernel-doc comments would turn out
> then (e.g. i915 kernel-doc references a symbol in drm core kernel-doc
> after gpu.tmpl split) as asciidoc would process the files
> independently. A kernel-doc comment writer shouldn't have to know which
> document the referenced symbol is in... We could do post-processing I
> guess, but I'd really like to get rid of the homebrew aspects here.
> 
> Is it acceptable to have dead links when referencing symbols outside of
> the document in question, for the time being, until someone figures out
> a nice way to do this?

Short-term *maybe*, but I think we'd want to figure that one out quickly. 

> Also in my dream world you could have asciidoc files anywhere in the
> Documentation tree, with a Makefile per directory identifying which ones
> should be processed as asciidoc. I might even name them all .txt, and
> you wouldn't have to rename existing "almost markup" plain text files to
> have them processed, just fix the markup and update the Makefile. (FWIW
> asciidoc suggests .txt extension, though asciidoctor suggests .adoc or
> .asciidoc.) I think this would better promote a gradual transition to
> lightweight markup, with easier to review patches. Also you mentioned
> there's no structure under Documentation. Allowing asciidoc files
> anywhere would, I think, help gradual restructuring.

I agree with all of this, but I still think that, for the short term while
we're figuring out how all this works, it's better to concentrate it in one
place where people can actually find it...

> I'd turn this around. IMO the problem isn't insisting EXPORT_SYMBOL is
> in the same file as the definition of the symbol. The problem is
> insisting that the kernel-doc comment is in the same file as the
> EXPORT_SYMBOL and the definition. Particularly include/media has plenty
> of kernel-doc in headers with the declarations.
> 
> If we can't insist on that, we could teach kernel-doc to scan a list of
> other files for the EXPORT_SYMBOLs, instead of having that logic
> externally in docproc. This should be trivial, especially if you know
> perl. (Unfortunately this might get a little tricky with the include
> syntax.)
> 
> This was mostly driven by the desire to get rid of the docproc
> preprocessing step.

...and that's a worthy goal.  In an ideal world, it's all found together.
I think we should probably proceed with the idea that the EXPORT_SYMBOL
issue can be dealt with.

> >> 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...  
> 
> If we can come up with a plan where I can be reasonably sure the
> polished effort isn't going down the drain... ;)

Seems we should be able to do that.  We want this stuff, even I'm not so
dumb as to send it down the drain when things are so close...:)

jon