Am 05.07.2005 um 09:25 schrieb Stephen Deasey:
Maybe we should pick one C function and one Tcl command to document
fully on the wiki, write some wiki macros to make it easy, then try
converting it into whatever?
Eh... It seems that this task is a real PITA! I think somebody
could make a fortune by inventing easy to use collaborative doc
system able to generate just a handful of formats: pdf, nroff, html.
If I understand this correctly, writing wiki pages is also a task
you have to learn (wiki markup). This is the same as with doctools.
Difference: in wiki everybody can do this from the browser, whereas
in doctools you'd have to do it off-line and in a text editor.
Apart that it is appealing to be able to write it on-line and it
seems trivial for bunch of people to do it "at the same time"
I see no other pros for Wiki. Cons are important: no simple interface
to cvs (docs are vital part of the server), lack of usable converters...
It seems like a lot of hacking for me and a great time eater.
OTOH, doctools are already supporting (almost) everything we need.
The cons are: you must edit sources off-line.
Just to be clear: I'm not trying to push doctools vs. wiki.
I'm just not convinced that wiki will save us any time and
trouble. I have a notion that doctools are less problematic
and would bring us to the goal (of having decent html/nroff
docs distributed with the server) faster.
I can imagine the following:
We divide and conquer...
Since I have more experience with doctools than wiki, I will take
a C-API and a Tcl-API call and write source of the doc in doctools.
Then I will convert this to nroff, html and wiki format by means of
the "dtp" processor from the tcllib.
You or Bernd can take the Wiki part and examine what would it mean
to write a converter that would emit something like people are
accustomed to when hitting "man fcopy" or "man lindex" or "man
Tcl_NewObj".
Then we can share experience (and source-files).
How does this sound?
