I hope you'll take a fresh view of documentation in the spirit that it's intended. You know where to find things. A potential user of your system can only go to the most likely spot, such as the doc directory in the distribution and aolserver.com. I am reporting to you what I find or don't find as I go along.
--- Andrew Piskorski <[EMAIL PROTECTED]> wrote: > On Thu, Jun 30, 2005 at 05:31:38PM -0700, Fred Cox > wrote: > > > However, the documentation appears to be > non-existent > > or wildly out of date, which raises the bar > > considerably. > > Somewhat out of date, incomplete, and disorganized, > yes. Wildly so, > or non-existant, no. My guess is you're looking in > the wrong place. Here's where I tried to start: aolserver-4.0.10/doc/Ns_RegisterRequest.3 aolserver-4.0.10/doc/Ns_ConnGetQuery.3 Since these, and all the ones I looked at at random have this same description: .SH DESCRIPTION .PP These functions ... I assumed that all of the included documentation is non-existent. Doing a ls -l shows that some of the API is documented, but seemingly all of the C API is not. http://www.aolserver.com/docs/devel/c/c-examples.html includes this bit of ancient lore: * For example, if this module is known as `hello' and loaded * into the `server1' server with entries similar to the following * in the nsd.ini file: * * [ns\servers] * server1=My First Server * * [ns\server1\modules] * hello=hello.dll ; or hello.so on Unix platforms I don't know how long ago AOLserver was using Microsoft style .ini files, but it version 4 doesn't seem to. I couldn't find documentation on how one is supposed to do this. I had to guess that the user's modules are similar to the ones that are built. Fortunately, that did work. The Wiki seems very skimpy. The impression I got from following links from aolserver.com and web searching is that there was a documentation effort that weakly started and fizzled out in 2002. If you're serious about building up your community, you would be well served by updating the documentation and fleshing it out. When a potential user finds that much of the documentation is missing, and other parts of it are out of date, then he has to take everything with a big grain of salt when he does find something, unless it's clear that this document is recently written. I would put a big README in the doc directory explaining that it's incomplete. I would go over your examples and bring them up to date. People using old versions of AOLserver aren't going to be looking at them, and newbies are just going to be confused and probably give up. > Try these: > > http://panoptic.com/wiki/aolserver/227 > http://www.aolserver.com/docs/ > http://aolserver.am.net/cvs/tcl > > > I would prefer to use C, since I don't currently > know > > Tcl, and I am developing for a fairly low end > machine. > > IMNSHO that is an incredibly bad reason to use C, > especially with > AOLserver, and especially if you plan to write code > using AOLserver on > an ongoing basis. > Is this because you have a bad impression of C, or because it AOLserver doesn't work well with C? > One of Tcl's advantages is that it is very easy for > a good programmer > to pick up quickly. A few days for basic > competence, a harder to pin > down amount of time for true mastery. It's harder > to pin down, as it > depends more on what sort of problems you've tackled > - e.g., how much > you've played with eval - than simply on how long > you've used Tcl. > > > If I'm going to use an interpreted language, I may > > end up using Apache 2.0 with MPM=worker and > mod_perl, > > Someone started work on a Perl binding for AOLserver > on SourceForge, > but AFAIK it was alpha and no one has touched it for > years now. The > Standard ML and Python bindings were much further > along, and Scheme > and Ruby probably were as well. But AFAIK no one is > currently using > any of those. The PHP (definitely) and Java (I > think) bindings work > and do get some use. Oh, and Vlad Seryakov might > actually be using > OCaml with AOLserver, not sure. > > http://www.panoptic.com/wiki/aolserver/165 > > > I have figured out how to use Ns_RegisterRequest, > and > > Ns_ConnGetQuery, but it appears that clean access > to > > uploaded files is limited to Tcl. In C, the > Ns_Set > > You could always simply call the Tcl APIs from C. Is there any documentation on how to do that? > Not the most > efficient way of doing things, but then it shouldn't > be any SLOWER > than just using the Tcl APIs from Tcl in the first > place, so it should > be fine. > Thanks for any info, Fred > -- > Andrew Piskorski <[EMAIL PROTECTED]> > http://www.piskorski.com/ > > > -- > AOLserver - http://www.aolserver.com/ > > To Remove yourself from this list, simply send an > email to <[EMAIL PROTECTED]> with the > body of "SIGNOFF AOLSERVER" in the email message. > You can leave the Subject: field of your email > blank. > ____________________________________________________ Yahoo! Sports Rekindle the Rivalries. Sign up for Fantasy Football http://football.fantasysports.yahoo.com -- AOLserver - http://www.aolserver.com/ To Remove yourself from this list, simply send an email to <[EMAIL PROTECTED]> with the body of "SIGNOFF AOLSERVER" in the email message. You can leave the Subject: field of your email blank.
