From: Reece Dunn (msclrhd_at_[hidden])
Date: 2004-06-11 15:41:27
David Abrahams wrote:
>"Reece Dunn" <msclrhd_at_[hidden]> writes:
> > David Abrahams wrote:
> >>"Reece Dunn" <msclrhd_at_[hidden]> writes:
> >> > David B. Held wrote:
> > 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.
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
> >> > 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.
It's fast, it's easy and it's free. Get MSN Messenger today!
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk