RE: [boost] Re: Documentation
David Abrahams wrote:
"Reece Dunn" <msclrhd@hotmail.com> 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/
"Reece Dunn" <msclrhd@hotmail.com> writes:
David Abrahams wrote:
"Reece Dunn" <msclrhd@hotmail.com> 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.
Yeah, especially since docutils (ReST) already contains a DocBook generating backend. It can also be done with XSLT from the ReST XML generator. But ReST doesn't contain ways to represent many of the C++-specific logical elements of BoostBook, IIUC.
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.
I thought the main thing was that it is extensible.
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).
There's no advantage to translating into BoostBook, AFAICT, unless we're going to stick in its special logical elements. We can always just use a common .css if you just want a similar look. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
participants (2)
-
David Abrahams -
Reece Dunn