Re: [naviserver-devel] Release/Docs

[Zoran V. <zv...@ar...>]

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