The main objection to the quickbook - boostbook - doxygen way of generating documentation, as I understand it, is that it is very hard to generate a different look-and-feel to the documentation from the standard one created by the stylesheets. OTOH others think having the same look-and-feel of all Boost docs is an advantage. So I do not think there is any way around this basic disagreement.
If you want a different look and feel, then yes things could be a lot better. However, within boost the consistency is a good thing IMO. BTW the look and feel is in 2 parts: * Different stylesheet, fluorescent dancing C++ keywords etc.... this is actually trivial to do. * Different Docbook customisation layer (and yes there are some formatting options that can only be addressed in XSL, not in XSL params). This is the hard one - or at least its the hard one if we're using Jamfiles. From the command line it's trivial if you don't mind writing a... ahem... makefile ;) BTW is there any reason to continue using the Boostbook customisation layer? Is anyone actually using it? I'm fairly sure quickbook doesn't, and it would sure simplify the build process to leave out one level of XSL transformation. Sadly we would need an XSL expert to sort that mess out I suspect :(
I do understand that other issues have been mentioned, such as lack of support for diagrams ( graphviz ? ) or formulas ( MathML ? ) directly in quickbook.
Since graphviz can generate SVG's, it would I assume be trivial for quickbook to shell out to "dot" to render inline graphviz text. Or you can just invoke it yourself (though I accept this may be less convenient). Equations are probably a more pressing need, and IMO it's a problem that no one has properly solved (unless you live entirely within the LatTex universe perhaps). MathML is useless as a format to write in, comes in 2 flavours (presentation and content with different tools supporting each - for example last I checked OpenOffice generates content, but most presentation tools expect presentation format). MathJax almost completely solves these issues, and looks quite lovely... but... because it relies on external Javascript files, it gets blocked by browsers unless everything is on the server (ie not on the local disk). Boost.Math renders it's equations as SVG's which works well, but it's a pain to author them separately from the actual text. I'm sure we would have more/better equations if they were inline in the quickbook. We could embed LaTex, but the conversion to SVG appears to be long and flaky involving quite a few tools (though it appears MathJax can do this in one step, but there are some comments that it generate "odd" SVG XML). Might be worth looking into though. Perhaps more pressing is the ability to generate a navigation panel - all the information we need is present in the Docbook - and frankly I simply cannot believe that the Docbook XSL stylesheets don't support this already (Ah they do - sort of - via a "webpage" project, but it's not vanilla docbook). Doing it ourselves probably means pre-processing the generating HTML or something similarly yucky :(
But we have the source for quickbook and can modify it accordingly, so I do not think that quickbook is itself the problem. I do agree that writing directly in boostbook ( or docbook ) is a real pain, which I have always found I could forgo, but quickbook has always been supremely easy to use for me.
+1, me too! John. --- This email has been checked for viruses by AVG. http://www.avg.com