Re: [boost] boost development process / scope

From: John Maddock (john_at_[hidden])
Date: 2007-05-05 04:43:35

Jeff Garland wrote:
> 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...

Agreed 100%.

Unfortunately converting old html docs is a lot of work :-(

>> 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...

I think the toolchain is getting there: we just need better documentation 
for setting it up.  Actually quickbook is trivial to get going, it's the 
Docbook XSL and particularly the FO to PDF translations that are hard: in 
other words it's the third party stuff that get's you!

I have some improved Docbook->FO stylesheets I've been hacking away at: I 
think we can do much better with PDF generation (syntax highlighted code for 
starters), which just leaves the toolchain setup issues.  Using XEP rather 
than Apache FOP for PDF generation makes a huge difference too.

If someone would like to roadtest some improved setup instructions, I'll try 
and put something together... I'm just not sure when!

John.