On Tue, 26 Jan 2016 14:08:45 +0200 Jani Nikula <jani.nikula@xxxxxxxxx> 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. Overlapping work is just how this kernel thing works :) > I first took roughly the same approach as you did. I was really > impressed with the speed and the beauty of the produced HTML. The > trouble is, neither asciidoc nor asciidoctor can produce chunked (split > to several pages) HTML directly. This is a showstopper for the gpu > document which turns into 1.3 MB of HTML, which looks pretty but is a > paint to navigate. To do chunked output, you have to output DocBook and > handle that like we do now. So while I would like to have asciidoc > generate HTML directly for speed and beauty, I ended up going the > asciidoc to DocBook path. The upside is all the output formats are > supported. So I'm not really going to have time to dig too much more into this until after LCA, so these are really quick impressions for now. I would *really* like to get the XML step out of the processing path if possible. It adds complexity, makes it harder for others to build the docs, makes things more fragile, and slows it all down. It seems to me that it should be possible to do that. The issues, it seems, are splitting the output files and format support. The latter isn't really an issue, I don't think; there are tools to do all kinds of format conversions. The only one that's even slightly weird is man, and kernel-doc already has some (unused, I think) provisions for doing that. We could generate man pages directly without much pain. For HTML-page splitting, we can see if the tools can help us, consider splitting the template files, or do the splitting in a postprocessing step. Docproc (or whatever replaces it) could also maybe do that work. It doesn't seem to me something that should force the inclusion of an entire XML-based processing step. But then, I'm here spouting ideas without any proof to back them up again, so who knows...:) Thanks for doing this work. As you said, it has been demonstrated -- 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
