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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
