Re: V2 documentation format

From: Zbynek Winkler (zwin_at_[hidden])
Date: 2004-02-02 11:53:05

Christopher Currie wrote:

>>>The second question is what documentation format should be use. 
>>>Zbynek has used PHP to automatically generate header and navigation
>>>links, and I'd like to discuss if we're going to use that format,
>>>or current html, or something else.
> 
> 
> 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.

>>I too find it a bit of an overkill to use PHP just to create the headers...
>>I'm not familiar with docbook, so I'll refrain from commenting.
> 
> I tend to agree here. My personal vote is for DocBook, which I like a 
> lot, and a fair amount of work has been done with BoostBook to create a 
> unified look to Boost documentation, and to provide extensions that make 
> sense in the context of Boost. Admittedly, the generated HTML doesn't 
> look as nearly as pretty as what Zbynek has done. Fortunately, I think 
> that can be fixed simply by creating a new XML stylesheet.
> 
> If desired, I can devote a little time over the next few days to convert 
> the docs to BoostBook, using the improved structure that Zbynek has created.

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.

Zbynek

-- 
http://zw.matfyz.cz/ http://robotika.cz/
Faculty of Mathematics and Physics, Charles University, Prague, Czech Republic