From: Christopher Currie (Christopher_at_[hidden])
Date: 2004-02-02 13:31:14
Zbynek Winkler wrote:
>>The only drawback is that it makes it harder to distribute the docs as
>>pure html; users wouldn't be able to download the docs unless we put
>>them through a php pre-processor first.
> I've thought of that and made a script that saves the generated html for
> offline distribution.
That's fine; I'm just concerned that it ties us to hosting providers
that have php, which isn't a problem now, but might be harder when some
other scripting language becomes de rigeur.
> I think it is just an issue of a learing curve. I know php so it is ease for
> me to use so I used it. I've tried DocBook before and it appeared clumsy to me
> (to difficult to do simple things). Dave mentioned RestructuredText - if I
> were to choose a whole new format for the documentation (=a lot of rewrite)
> then I would go for something like that because it is easy to edit. This php
> thing was motivated by doing as little work as possible to get the desired effect.
Trust me, I've got nothing against PHP, I use it myself when it's
appropriate, which for me usually means when I have to generate dynamic
content. I also have nothing against reST, I think its goal of having
its raw source be readable is admirable.
But I disagree that moving to DocBook would require a lot of rewrite;
most of the conversion would involve a search-and-replace from HTML tags
to DocBook tags, and then some cleanup work. It's getting the toolchain
working that's somewhat complicated, and that can be solved with some
better documentation. :-)
Mostly, I favor DocBook because it's already being used by Boost, and I
personally feel that its markup is more expressive and flexible. I know
it has its faults, but I think its similarity to HTML will make the
conversion less painful, and editing more intuitive (which might
encourage more people to help out!)
Boost-Build list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk