On Mon, Aug 18, 2008 at 6:02 PM, Daniel James <daniel_james@fmail.co.uk> wrote:
2008/8/18 Dean Michael Berris <mikhailberis@gmail.com>:
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.