David Abrahams wrote:
"Reece Dunn" <msclrhd@hotmail.com> writes:
"Reece Dunn" <msclrhd@hotmail.com> writes:
David B. Held wrote: It should be fairly easy to adapt the ReST/SpiritDoc/whatever
David Abrahams wrote: 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.
These could always be added in by the author after the BoostBook files have been generated, if you are planning to migrate from ReST/SpiritDocs to BoostBook. This was the idea, to give the user a tool/toolset to help migrate to the BoostBook format.
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.
It is. You can have any element and attribute structure you want; this is how it is extensible. What I was referring to is that XML emposes stricter formatting rules than HTML, requiring attributes to be quoted and all tags to have corresponding closing tags (the open/close tag being a special case). This might be new to people familiar only with HTML and so may make mistakes, resulting in an invalid XML file. Automating this conversion process will help ensure a valid XML file to work from.
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.
I thought one of the ideas behind BoostBook was to have a documentation format that will eventually become Boost-wide. If this is the case, then having tools like what I'm suggesting will help speed up the migration process. If not, then what you are suggesting is also fine. Regards, Reece _________________________________________________________________ It's fast, it's easy and it's free. Get MSN Messenger today! http://www.msn.co.uk/messenger