Re: [naviserver-devel] Release/Docs

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

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