Re: V2 documentation format

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!)

Christopher