On 06/04/2014 08:51 AM, Daniel James wrote:
Forgive the stupid question, but why does quickbook generate boostbook
xml, which then generates html, instead of quickbook generating html directly?
Not a stupid question.. Just a historical one. The precursor to quickbook did generate HTML directly. It was "ported" to generate docbook to have it integrate into the then newish Boost documentation toolchain based on docbook in order to simplify doc writing with a simpler wiki like syntax. Yes, boostbook markup is hard-coded into a lot of places.
I had a crude html generator in the abandoned spirit 2 branch, I think it's the only feature I didn't backport. It could do a passable job of simple markup, but for complicated documents it wasn't much use. Especially for documents which use doxygen, as that is used to generate boostbook. I felt it was more useful to concentrate on improving the language.
I was the one who took Joel de Guzman's QuickDoc tool, which generated HTML, re-purposed it to generate BoostBook XML, and rechristened it QuickBook. It has been terrifically useful, and other have run with it. As others have pointed out, the Docbook toolchain is powerful. Escaping to BoostBook/Docbook XML is a great way to Get Things Done when QuickBook doesn't offer a pithy syntax. And as Daniel points out, Doxygen generates XML which can be integrated with the XML spit out by QuickBook, allowing you to easily link from your user docs to your reference and (with some difficulty), the reverse. It's ugly and round-about, and it cries out for a better solution, but it's the best we've got, and it gets the job done. Eric