Re: [Boost-docs] Getting the ball rolling...

From: David Abrahams (dave_at_[hidden])
Date: 2002-11-18 11:05:46

Douglas Gregor <gregod_at_[hidden]> writes:

> (h) PS/PDF backend output (Difficulty: 2)
> How can we generate high-qualify PS/PDF documentation? One route is to use the 
> DocBook->FO XSLT stylesheets, and then use a tool like Apache's FOP to create 
> PDF. Another route is to use one of the TeX-generating DocBook
> processors (like OpenJade) to build PS/PDF documentation. I've tried
> the former (the result is good, but not perfect), but have had no
> success with the latter. The task here is to try other methods and
> report back on the suitability of those methods.

I believe we could get some mileage out of the tools at
http://www.reportlab.com/opensource.html.

I'm not sure if I can volunteer for this yet or not.

> (i) Jam integration (Difficulty: 3)
> Find a way to integrate building documentation into the build process, using 
> Jam. For instance, it would be great to be able to type "bjam doc-pdf" and 
> get back a PDF file containing Boost documentation. This is an ongoing task 
> that may start simple (C++XML->DocBook via an XSLT processor, then 
> DocBook->HTML via an XSLT processor) and will grow in complexity 
> (Doxygen->C++XML->DocBook->FO->PDF...) as we learn more.

I'll do this one eventually, or farm it out to somebody on the
Jamboost list if there's interest ;-)

> (j) Convert existing documentation (Difficulty: 1)
> Try converting some existing Boost documentation to the DocBook/C++XML format, 
> and report your responses. It's probably best to start with a small library 
> or, even better, a library that isn't changing often or whose author is not 
> likely to convert the documentation himself. Some potential candidates: any, 
> array, compose. Please get the author's permission first, and report back 
> with any problems you encounter.
>
> (k) Documentation, documentation, documentation (Difficulty: 2)
> Documentation for developers that want to use this system is a must. What more 
> can I say?

Everybody had better take responsibility for documenting the parts
that they implement, and each part should have at least two volunteers
to review and edit what is produced. Otherwise, this will never get
done and the whole project will fail.

-- 
David Abrahams
dave_at_[hidden] * http://www.boost-consulting.com
Boost support, enhancements, training, and commercial distribution