Am 04.07.2005 um 08:45 schrieb Bernd Eidenschink:
Hi!
I want to ask you for your opinion on a few things:
a) Documentation
AFAIK the status was to ask Andreas Kupries for (small?)
modification of the
doctools to be able to make smart C-Function documentation.
Zoran: Can you tell if your suggestions will be (or are) accepted?
This seems to lag behind (my fault) . Basically, the doctools is
allright, the
only "limitation" is that you can't make one man-page describing more
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. Now, doctools can't make this. You'd need to
supply a man-page per-api-call.
But...
Having worked with that in last couple of days. I find it
*extremely* annoying. OOH, having conceptually related calls
all fit on one page is appealing. OTOH, if you frequently need
(man) access to a single call, then it is absolutely impractical
and annoying to flip pages and pages of docs just to locate the
call in question.
I would really suggest we make a simple (and doctools supported)
page-per-api-call approach. The doctools can already do that and
it will be easier to read and (perhaps) maintain.
The drawback is: number of files (will be quite large).
I think I can live with that.
To me it would make sense to make the documentation effort now top
priority,
regardless of the format. Later we can copy and paste it from
whatever source
to our preferred target, but we should aim for the source now. Even
the fresh
NaviServer commands are not documented and only available for the
skilled C
developer (and see current discussion on AOLserver mailinglist).
Right.
In the first step documentation must not be perfect and long, as
long as it
respects some formal template documentation style and presents
things the way
they work. Strategy?
Two possible ways:
(A)
1. Construct list of all current commands (C and TCL), mark the
deprecated
ones.
2. Categorize commands.
3. We distribute documentation work among each other (small bunch
of commands
for everyone; and we know who documents what command); and everyone
on the
mailing list is a volunteer per se and likes to contribute :-)
This is not an option. This has to be done for the B. (below) as well!
(B)
- Update the '/doc' dir in CVS using current templates OR
- Update the '/doc' dir in CVS using doctools OR
- use Wiki for easy peer review and parse the Wiki structure later to
transform the docs to whatever format (would be very simple step)
Current templates are in plan nroff and thus complex to
write. I would really use doctools for this purpose. doctools
have a very short learning curve (very similar to POD and very
Tcl-lish) so I believe everybody will be up and running after
glancing on a doctools page for a few minutes.
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? 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) ?
Bottom line: I think the best way would be to make a template
for a C-API and Tcl-API call, then check-in this template for
every C/Tcl API calls in CVS, then take one at a time and fill
in the content. The CVS is a collaborative env, right?
Who does which page? This is a simple matter of communication.
I do not think that we need to divide this somehow. We are just
a few people and it suffices to document as we go. I do not think
that we will have much problems with that. A short email on the
list telling: hey, I'j now do the ns_XZY or Ns_XZY() would do.
b) Intermediate-Release, Beta-Release
This was also the intention for 4.99.0.
There should be a release, downloadable!, so we have a visible
result of the
current status and efforts. It should be clearly marked or named as
intermediate or beta release, open for testing and reviewing.
Along with a statement or Roadmap that says: This release will
become a
default stable release - the next target is VFS, caching, etc.
Do we want Version 5.0.0 to be the one with VFS, caching etc. or
the first
stable release?
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.
I would do the 5.0 after we've done all those nice new things like VFS
support (advancing well, btw), fancier upload caps, integration of
ns_cache,
full support for byte-ranges, finalized docs etc. I would target this
towards the end of the year.
Zoran
