Re: [naviserver-devel] Range requests
Am 03.07.2005 um 12:27 schrieb Stephen Deasey: I'm wondering if the best way forward is to back out the range code, make a quick release, then add it back for the next one along with the TclVFS stuff, file upload improvements, and hopefully my mythical caching changes, all of which are pretty invasive and potentially destabilizing. What does everyone think? Apropos a quick tagged release, yes! As I see, Vlad is somehow dependent on the range's implementation and I would not like to make his life complicated by taking out the pieces. Perhaps a temporary #ifdef USE_BYTE_RANGES which would be per-default undefined? This way he can just simply fix the Makefile. I'm also using this with URLDECODE_RELAXED to be compatible with (broken) urldecoder on AS... Zoran
Re: [Re: [naviserver-devel] Range requests]
Am 03.07.2005 um 23:04 schrieb [EMAIL PROTECTED]: It needs improvements i agree. i am on vaca! tion this week so you all decide without waiting for me. I'd suggest #ifdef USE_BYTE_RANGES undefined by default. You can temporarily tweak the Makefile to define it. OTOH, what Stephen is suggesting makes sense. Stripout the range code, make a release, add it back again. This way you'd be on the CVS-head as you were before. Only the tagged release would have no ranges. Zoran
[naviserver-devel] Release/Docs
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? 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). 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 :-) (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) 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? What do you think? Bernd.
Re: [naviserver-devel] Release/Docs
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
Re: [naviserver-devel] Release/Docs
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 ? Hm, the existing nroff docs could be transformed like here: http://naviserver.sourceforge.net/wiki/index.php/Template:Documentation_template I used the script that is found under the link hack at the end. (It's a hack. It's a hack.) The way back from wiki-nroff could be, depending on the nroff quality, more easy, if we use an easy and fresh Wiki document (and make use of standard HTML-Comments for better parsing). But it always would be unorthodox. :-)
Re: [naviserver-devel] Release/Docs
Am 04.07.2005 um 16:45 schrieb Bernd Eidenschink: 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 ? Hm, the existing nroff docs could be transformed like here: http://naviserver.sourceforge.net/wiki/index.php/ Template:Documentation_template I used the script that is found under the link hack at the end. (It's a hack. It's a hack.) The way back from wiki-nroff could be, depending on the nroff quality, more easy, if we use an easy and fresh Wiki document (and make use of standard HTML-Comments for better parsing). But it always would be unorthodox. :-) I see this really pragmatic: *I* would not like to invent the wheel. If there is some good quality wiki-nroff, wiki-html, wiki-(whatever) this would be the way to go: write all in Wiki and get it converted to other stuff. This is very appealing. If not, but somebody (you?) could write working converters for at least html and nroff conversion, I'd be happy to use them and would also opt to write source docs in wiki. Ideal would be a tclsh app I could hit like wiki2html source.wiki (would produce source.html in the current dir) wiki2nroff source.wiki (would produce source.nroff in the current dir) If not, I'd use doctools for already given reasons. It can't be that bad considering that all of tcllib modules are documented with doctools (with some notable deficiencies in documenting C-code as I already mentioned). Zoran
Re: [naviserver-devel] Release/Docs
Don't know if this is useful: http://hula-project.org/Wiki_Conversion Our idea is that there be a script on the wiki server that autogenerates PDFs of the admin guide, the user guide, and any other large-scale documentation, suitable for printing and binding and admiring and cherishing forever and ever. -- Nat Friedman
