So, when you are recommending QuickBook, does this also imply BoostBook/DocBook, or are you treating them as separate tools?
Regards, &rzej;
I here's my story with boost documentation tools. I've described my views on documentation content elsewhere: https://www.youtube.com/watch?v=YxmdCxX9dMk I always liked the xml approach of separating document content from document rendering. This permits one to create the content one time and render it according to one's desire at the time. Thus one can produce HTML, PDF, (probably AsciiDoc) and who knows what else. One could also create an xmlsltproc file which would automatically generate a global table of contents for one or all boost libraries - though this has never been done. It also permitted the creating of custom "vocabularies" which would specify more meta data about the content. Doug Gregor created all this in BoostBook but it hasn't been exploited much if any. There remained a few problems though. Editing XML is/was not a user friendly operation. Eric Niebler addressed this by writing QuickBook which produced XML from a simpler text format. This was well received by Boost developers and likely saved XML from failure. I didn't like: The tool chain used B2 to transform the XML into html by invoking xsltproc. I found this to be akin to training an ant to train a flea and too hard for me to do and to keep up with. To this day I have difficulties with B2. I addressed this by editing the raw BoostBook with an XML editor: XMLMind. This is a gui editor which I fund easy to use and lets me visualize the final documentation product as I type. It's also friendly about using "templates" for things like template, class, and function reference documentation. I use a simple shell script to invoke xsltproc to generate html and pdf versions of my docs. I didn't like the usage of DOxygen. I've found this tool to be unsuited to writing documentation of code based on requirements (C++ templates) as opposed to code based on classes. My XML editor easily let me use "templates" for the things I need so no need to try to get DOxygen to do what I needed to do or tweak my C++ comments to make DOxgen do what I wanted. Finally, I ship pre-built documents with my libraries. So anyone who can look up any part of the documentation without having to go on line to do so or with having to build (via B2) A local copy. OK it takes a little extra space. But it's worth it so that users can get immediate answers to their question. It's also easy for them to send a steady stream of typos that I continually correct. Robert Ramey