Matthias Schabel wrote:
Fortunately, there is no mandate on the specific format of documentation for Boost libraries. However, I agree that it is desirable to have some level of consistency of documentation format.
This is a much bigger problem than at first it appears. I think some projects (like PHP and Java) get a big 'boost' from users because all the documentation looks the same, has the same conventions and look and feel. Josh Bloch (on of the major forces in Java standard library development) credits JavaDoc as one of the critical elements in adoption of Java libraries. I personally don't like the uneven look of current Boost docs. The more recent docs (like math tookit, bimap, all the Niebler libs) are really nice -- they look pleasing and have consistent structure. I'd like to see all the library docs look this way...
I know that Steven spent a significant amount of time getting quickbook to work for the Boost.Units documentation, so I would agree that flakiness is a problem. Given that writing documentation is generally the least favorite activity in any given software project, adding even small hurdles is clearly undesirable...
The current toolchain is hard to setup, no doubt. Overall, though, I think it's worth it. Lot's of developers have managed it, so it's not that hard in the end. Not saying we shouldn't look at ways of making it better, we should. We really need volunteers to help ;-) The current system can clearly produce both nice html and pdf. Even though John and Paul struggled, they were able to get both PDF for the math toolkit which is chock full of references, graphs, etc. I've had a date-time PDF docs for several releases. This is a very useful feature that the straight html docs can't serve. The date-time docs are all in BoostBook xml -- I really wish they were in QuickBook b/c it would be so much nicer to maintain them... Jeff