Re: [boost] Copy editing documentation - SOC project

From: Joel de Guzman (joel_at_[hidden])
Date: 2007-03-12 19:14:14

John Maddock wrote:
> 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 :-(

Oh. And we have a lot of those.

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

Rene already started a Windows installer script.

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

Too ambitious, IMO.

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

Not hard. I know what to do. It's just a matter of doing it.

>> 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 :-)

..Also, make it usable for non-boost documentation. It's a generally
useful tool. Address the qualms of Dave A :) Have the toolset hook
(optionally) to python (to take advantage of Dave's work on LiTre).
Use regex for the syntax highlighter (so we can plug in highilghers
for other languages). I can come up with a list of things needed to
be done.

Regards,
-- 
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net