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
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.
Want to block unwanted pop-ups? Download the free MSN Toolbar now!
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk