Messages in this thread | | | Date | Wed, 10 Feb 2016 13:56:51 -0700 | From | Jonathan Corbet <> | Subject | Re: [RFC] A first shot at asciidoc-based formatted docs |
| |
On Wed, 10 Feb 2016 16:03:38 +0200 Jani Nikula <jani.nikula@intel.com> 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
| |