RE: [boost] Re: Documentation

From: Reece Dunn (msclrhd_at_[hidden])
Date: 2004-06-11 11:32:11

David Abrahams wrote:
>"Reece Dunn" <msclrhd_at_[hidden]> writes:
> > David B. Held wrote:
> >>If we're going to demand uniformity in licensing, should we also
> >>demand more uniformity in documentation?
> >
> > I agree on this. At the moment, we have the docs written in HTML,
> > those in BoostBook format (like Boost.Any and the BBv2 docs) and the
> > Spirit docs which have their own format.
>
>And others; we used ReST for the iterator library.

It should be fairly easy to adapt the ReST/SpiritDoc/whatever translation 
phase to generate BoostBook instead of HTML.

> > As far as I understand it, the BoostBook tool is relatively new and
> > has a learning curve, so it will take some time to migrate the docs to
> > this format.
>
>And it requires writing in XML :-( or translating to it :-|.

XML is essentially a stricter version of HTML. The main problem I see is 
porting the existing HTML-based docs to BoostBook. The others can be 
generated using a BoostBook generator (not sure how easy it will be for each 
format).

I have a Spirit-based HTML parser that does basic correction (not as good as 
HTMLTidy) that is event based (like SAX for XML) and can be used to generate 
XHTML. It should be possible to adapt this to generate a BoostBook document 
that can be used as the basis for migrated docs.

The SpiritDoc processor tool is freely available and should be easy to 
migrate to BoostBook output. Other generators can be produced for ReST, etc.

NOTE: The output of these should be seen as a basis for the actual docs as 
they won't be able to properly detect things like the licence info, author 
name or library name/category; these will need to be edited by the document 
provider. (It all depends on how this information is encoded in the base 
text. If there is a markup pattern, then it should be possible to identify 
this and extract the information.)

Let me know if I should take a look into seeing how feasible this is. Having 
a common document format will help maintain a consistent navigation/look. 
Also, it should be possible to generate frames as an alternate look by 
editing the BoostBook stylesheets and with a little wizardry it should be 
possible ot turn this on or off, depending on your preferences like it is 
currently possible to select Spirit or DocBook navigation styles.

Regards,
Reece

_________________________________________________________________
Want to block unwanted pop-ups? Download the free MSN Toolbar now!  
http://toolbar.msn.co.uk/