Re: [naviserver-devel] Documentation & website question

[Bernd E. <eid...@we...>]

> Maybe instead of solving documentation issue technically using
> conversion tools we can just include html pages with all we have docs
> into distributon, like Apache does, once installed we will copy manuals
> under pages so every new install will have access to docs even without
> writing any script. Those docs can have working examples, simple ones or
> complex does not matter but they will perform testing and educational
> tasks at the same time.
> I went through AOlserver site, wiki and our wiki and pieces of docs, it
> is spread and having this simply as html docs in one place may be easier.

How do Apache folks do it? Is the base of documentation HTML? 
I would suggest some simple XML at least, so we are able to use the same tool 
(e.g. tdom) and mechanism (e.g. XSLT) for both man pages and the 
documentation Vlad suggested to put under docroot. Even the NEWS file could 
be compiled from the XML base, to not double work. 

Btw: Right now we use (ok, don't use) doctools and dtplite from tcllib. Would 
some readable XML feel more natural or would it lower the mental burden to 
start documenting? Using XML/XSLT would still allow to also create doctools 
format and then creating usual xyz-roff format.

Most of the content on the Wiki is static. I would not vote against replacing 
it with static HTML content (about, license, news; links to SF) that mainly 
includes the transformed parts of the documentation base. Nothing is lost, 
the current activity is mainly removing hidden div-layers with SPAM links :-|

Bernd.