Daniel Wallin wrote:
Quickbook is also a nice documentation language to use, but the reliance on Boostbook+XSLT makes it harder to pull-off. I don't know though if Quickbook can be made to generate HTML directly instead of XML. Joel?
We could "easily" build a python-based BoostBook/DocBook -> xxx converter. What I'd actually do, though, is transform BoostBook/DocBook into docutils' internal format, then feed that into docutils and use its already-written backend writers to generate whatever xxx we chose ;-).
If we were to explore that path, http://sphinx.pocoo.org might be of interest. It's a documentation framework built on docutils, that could give us a uniform look and feel, plus cross referencing. Seems geared toward Python, but I'm sure it could be extended with whatever docnodes we could need.
Guys, before we get too carried away, please be aware that some of us are already generating very nice html and PDF docs from Docbook thankyou very much, and already have a significant investment in quickbook templates that output raw Docbook. Unless you're planning on supporting the entire Docbook DTD, complete with at least the same amount of flexibility and configuration as the Docbook XSLT toolchain has, then I don't see an advantage, just a whole ton of work trying to convert to yet another format :-( What we really should do (and I suspect could be done quite easily) is: 1) Split the build so that building the docs for library X *only* builds the docs for lib X, and so that building from /libs/X/doc has *exactly* the same effect as building from /doc/. In other words build multiple "books" rather than trying (and mostly failing) to build one big "book". 2) Have the doc build automatically invoke the inspect program over the generated docs - to catch for broken links etc, hopefully this should eliminate most of the "partial build" problems. 3) Add the doc build for each library to the tests. 4) The only drawback I see, is the difficulty of one library linking/referencing to another, I guess it would be possible to generate a Docbook file containing just the link URL's to all the libraries sections that could be included and referenced? Don't know if it's worth the hassle though? Unfortunately most of the above represent Boost.Build changes :-( John.