Re: [boost] Copy editing documentation - SOC project

From: John Maddock (john_at_[hidden])
Date: 2007-03-12 13:08:44

Paul A Bristow wrote:
>> How about beefing up our documentation tools? Make it easier to
>> install configure and use, make it seamlessly generate nice PDF
>> without the hassles of FOP (e.g.
>> http://dblatex.sourceforge.net/examples.html), etc?
>
> Neat !

Before we get too carried away, there are still plenty of issues with 
DocBook to latex conversion: tables with code in them get particularly badly 
mangled as I recall.  Ultimately every time you change formats you loose 
something :-(

> But Quickbook seems to me to meet the needs of Boost-type stuff very
> nicely. (and once setup - the tricky bit - is virtually the same as
> Docbook etc).
>
> Or does it need some work on it still?

We could really use someone to figure out all the installation stuff, 
document it, and write some Unix and windows installer scripts.

> Except that the conversion to pdf didn't work using FOP (but as I
> recall, for problems with graphics being inefficient for graphics
> using bitmaps not vectors, and we didn't manage the equations in
> MathML rather than intrinsic problems?)

Basically FOP sucks.  I'm sorry, but it's my opinion and I'm sticking to it! 
The interesting thing is the commercial alternative (RenderX) works very 
well, so clearly it can be done.

Sadly writing a complete docbook->pdf converter in three months sounds a bit 
ambitious - pity 'cos I bet a lot of projects besides Boost could use it.

> And it doesn't produce an automatic INDEX, as well as a Table of
> Contents.

Modifying quickbook to take a concordance file and produce propper docbook 
indexes shouldn't be too hard?  Then we just need to rely on the docbook 
toolchains doing something meaningful with the data...

> So how can we produce a GSoC project out of this?

So... installation scripts, documentation, and index generation.  Is that 
enough to be a project?  Oh wait we could at IDE integration as well, and 
let's not forget that Matias got started on some of this last year: 
http://cablemodem.fibertel.com.ar/mcape/oss/projects/mc_projects/boost_projects/blade.html, 
looks like not much has been started but the logos and code name are nice 
anyway :-)

John.