RE: [boost] Re: Documentation

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 
>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