Re: [boost] Documentation Redux (was Re: Boost 1.36.0 release notice)

From: Dean Michael Berris (mikhailberis_at_[hidden])
Date: 2008-08-18 15:43:36

On Mon, Aug 18, 2008 at 6:02 PM, Daniel James <daniel_james_at_[hidden]> wrote:
> 2008/8/18 Dean Michael Berris <mikhailberis_at_[hidden]>:
>>
>> Another option (that I think Dave Abrahams has been doing) is to use
>> RST [0] to make writing/reading the source documentation easier than
>> having to rely on Boostbook+XSLT (which I personally think is a
>> brittle tool-chain).
>
> We haven't a single problem with boostbook or xslt. It's actually
> quite stable. The problems have been with boost build, quickbook
> (possibly due to Spirit), doxygen and latex. Basically everything but
> boostbook. Most of the problems seem to involve poor support for
> windows. I've been testing on linux which is why they weren't
> discovered sooner.
>

Actually, not having access to a proper xslt implementation in Windows
is the big problem with boostbook+xslt. Another is the relatively
harder-to-maintain format that is XSLT -- I mean honestly, does
anybody even _like_ reading/writing XSLT?

This leads to the questions like: if we somehow wanted to change the
structure of an HTML page generated by the documentation tools or add
certain (new) page elements? We'd then have XSLT to deal with which is
just hard to test, hard to maintain, and hard to understand. I
understand though that having something like Django template support
for our documentation might be too ambitious instead of using XSLT to
generate static pages, then something like RST (or quickbook that
generates straight HTML) might be more manageable.

Then again there's the problem with Windows and XSLT which makes it brittle.

-- 
Dean Michael C. Berris
Software Engineer, Friendster, Inc.