On 05.09.2006, at 09:34, Bernd Eidenschink wrote:
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.
AHHHHHH! XML again!? I wen't there and I came back!
The first doc in threading extension was TMML (based on XML).
It was a HORROR to maintain and I switched to tcllib instead.
Had a look at POD (perl doc format pendant)? Well this is basically
tcllib format. Easy to write and maintain. Sometimes when a page
becomes pretty large, you can get lost, but in XML I get lost
about 10 lines below. Same as HTML. You need a damn good tool to
use it productively, especially when making large changes.
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.
NO. MORE burden!
Please lets forget XML before we write yet another line on that.
To my opinion, the tcl doctools format is the simplest most natural
to understand and write format I've come accross when writing short(er)
man pages. And this is the bulk of that we need....
Cheers
Zoran
