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

From: David Abrahams (dave_at_[hidden])
Date: 2008-08-21 20:53:40

on Mon Aug 18 2008, "Dean Michael Berris" <mikhailberis-AT-gmail.com> wrote:

> 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]>:
>>
>> 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.

Whatever else happens, I think having an intermediate representation
that is DocBook is important because of all the tools that can process
it.  Don't forget that we probably want to generate PDF among other
things.

-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com