Am 04.07.2005 um 10:14 schrieb Bernd Eidenschink:
than one C-API call. To get an idea, install Tcl and make:
man Tcl_FSStat
and you will see that the *entire* Tcl-VFS API is documented in
one single man-page.
ok, see. would be handy.
Watch! Although handy, it is pretty inflexible.
As an exercise, imagine you'd like to use Tcl_AllocStatBuf call.
Now, you naively go and "man Tcl_AllocStatBuf". You'd like to
get call signature and parameter description, but you also want
to look at what the call is really doing. Given the current state,
this is all but user-friendly and effective.
In order to understand what I mean, please do try "man Tcl_AllocStatBuf"
and judge by yourself...
Personally, I find it very annoying and ineffective.
Wiki seems very nice for collaborative work but I do not
know if there is a wiki->doctools converter (doctools->wiki there
is).
If we start hacking wiki, how would you convert this into some
other format?
Depends on what we need for doctools, or generally for documentation.
Example:
All Headings like NAME,SYNOPSIS,DESCRIPTION,EXAMPLES,SEE
ALSO,KEYWORDS are
representated the same in the wiki, e.g. a third-level-heading:
=== SEE ALSO ===
Other "markup" like bold or underline is also easy parseable
('''bold''').
"Examples" start with one or more whitespace on a line.
So I think it should be very easy to hack a convert, as the
structure is
always the same. Like this stupid hack:
http://naviserver.sourceforge.net/wiki/index.php/News2wiki.tcl
But, as the devil is in the details, maybe you send me a doctool-
document in
the form that you can imagine as a template for NaviServer, and I
take a look
at how complex it is to write a small converter script.
OK. I will prepare a doctool for a one ns_xyz and Ns_XYZ() (both Tcl
and C api).
You must install tcllib and there you will have a dtp utility which will
translate this in wiki or html or nroff for you.
If it turns out to be simple to write a wiki->doctools converter then
I'm all
for it. Then we'd use wiki to fill-in the content, use the translator to
generate doctools pages, then cvs-import those, then generate html/nroff
offline docs during installation. Ideally, the wiki->doctools should be
somehow automated.
Hm.... and what if we'd have a wiki->nroff and wiki->html off-line
converters? Than we'd have the sources of docs in native wiki format
and check-in those in CVS. During the "make install" we'd hit the
apropriate converter and generate html/nroff on the fly? Or we can
pre-format nroff/html and check-in those... ??
This way or another, it seems that if we'd have a wiki->html and
wiki->nroff converters at hand, we could trash doctools... But I
do not know if any of those already exists. OK, the wiki->html
should already be there, otherwise wiki would not work ;-)
But, what about wiki->nroff ?
The AS project started this and I do not see any moves
there. The wiki-entered stuff is still there and nobody cares to
get it into the CVS or get it translated to other off-line reading
(man, html, pdf, etc) ?
Thats true. I think the effort stopped at the very beginning or
halfway. But
if only we had it in the Wiki! The problem is that writing
documentation
sucks, not writing the converter :-)))
But yet, having a good framework in place would actually lower the
barrier of having to start to write actually.
Ok. But we should have a complete list for C and TCL to know whats
missing or
when we are finished.
If we manage to get Wiki-based thing, than all is already in-place,
right?
I started with TCL, but the list is not perfect:
http://naviserver.sourceforge.net/wiki/index.php/Examples:Commands
The problems with the list is that you need to update yet-another-thing.
I think that tagging the CVS now with 4.99.0 is perfectly OK as it
would
identify a body in CVS which is fixed and against which we can file
bugs.
Ok, so we tag it after the macro insertion (or whatever solution)
for the
range headers?
I would suggest so.
Zoran
