Re: [boost] Boost documentation format (was Re: Boost documentation)

From: Gennadiy Rozental (gennadiy.rozental_at_[hidden])
Date: 2007-06-25 17:07:16

"Peter Dimov" <pdimov_at_[hidden]> wrote in message 
news:01f901c7b76b$b3f46330$6407a80a_at_pdimov2...
> Gennadiy Rozental wrote:
>> "Peter Dimov" <pdimov_at_[hidden]> wrote in message
>> news:018a01c7b752$26407bf0$6407a80a_at_pdimov2...
>>> Peter Dimov wrote:
>>>
>>>> I admit that it would be possible to make the .xml files viewable in
>>>> a browser by using a stylesheet, but currently they don't seem to
>>>> be.
>>>
>>> By using
>>>
>>> http://www.badgers-in-foil.co.uk/projects/docbook-css/
>>
>>
>> Hmm. Why not regular single or multi chunk HTML output stylesheet?
>
> No idea. Given that the XML->HTML conversion is done via XSLT, I'd have
> expected the XML files to already come with an associated XSLT stylesheet,

You can do this in general sinbce there are different stylesheets you can 
apply to produce different outputs.

> but they do not. The above was what I found in the limited time I spent
> looking for a DocBook stylesheet. Apparently, the XmlMind editor also
> contains a CSS stylesheet for DocBook.

Using xml-stylesheet processing instruction allows you to assign stylesheet 
to the XML file and see it accordingly.

> The exact method is not important. What matters is that the user should be
> able to view the documentation in at least Firefox, and hopefully IE7 as
> well.

Boost release version users - yes. CVS version users - I don't think so.

> It might be reasonable to require a 'bjam' invocation for libraries
> that need building anyway, but a requirement to install a BoostBook
> toolchain seems a bit steep

It's not nesseserily required. We can do what DocBook does and provide an 
access to the current release stylesheets online.

(in this light I view QuickBook as an
> improvement as it can - IIUC - produce HTML docs from a single 'bjam'
> command given a fresh Boost tree). For header-only libraries that don't 
> even
> require bjam to be present, everything besides readily-accessible HTML 
> would
> be a regression.

In released version there should be both XML and HTML (at least). In cvs - I 
don't think so. But with stylesheet available only it can be done with the 
single xml-stylesheet processing instruction.

Gennadiy