From: Jeff Garland (jeff_at_[hidden])
Date: 2007-05-04 20:43:56
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...
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk