Re: [AOLSERVER] Sign Up for AOLserver Documentation!
In a message dated 11/3/02 10:49:42 PM, [EMAIL PROTECTED] writes: What was the new chat time on Thursdays? Last stated was 3pm Eastern, but then you asked for any takers at 2pm Eastern. I abstained, and no one else spoke up, so I'm assuming it was finally changed to 3pm Eastern. I intend to hang out in the chat room all day from now on. /s. i'll have to look back at my notes. i think it was 3est.
Re: [AOLSERVER] AOLserver command style guide (was Re: [AOLSERVER] Sign Up for AOLserver Documentation!)
On Monday 04 November 2002 12:58, you wrote: > > Is there some reason not to rename the 'nsv_*' commands to correspond to > > Tcl's 'array' command? Thus, 'nsv_set' would change to 'ns_array set', > > so that > > > > ns_array set > > > > would correspond to Tcl's > > > > array set > > > > and so on. > > Again, to remain idiomatic, I think: > > nsv_set arrayName elementName value => nsv set arrayName elementName value > nsv_get arrayName elementName => nsv get arrayName elementName > [...] > nsv_array names arrayName => nsv array names arrayName > I've reimplemented (and significantly extened) nsv_* for the Tcl threading extension 2.4 by using Tcl_Obj* for internal storage. There, I've used tsv::* tsv::set arrayName elementName value tsv::incr arrayName elementName ?increment? etc... The "tsv" stands for "thread shared variable" This is another possibility, since AOLserver has dumped the pre8 Tcl version. Zoran
[AOLSERVER] AOLserver command style guide (was Re: [AOLSERVER] Sign Up for AOLserver Documentation!)
On 2002.11.03, Scott Goodwin <[EMAIL PROTECTED]> wrote: > I Agree. We'll do the 3.5 docs first as-is. I think at some point we > should bite the bullet and rename commands like > >ns_returnadminnotice > > to be > >ns_return adminnotice > > and maintain that consistency throughout the server and modules. > Backward compatibility would be kept for some period of time. Agreed. This is Tcl's idiomatic way of doing things, which I think would be good to remain consistent within AOLserver. > Is there some reason not to rename the 'nsv_*' commands to correspond to > Tcl's 'array' command? Thus, 'nsv_set' would change to 'ns_array set', > so that > > ns_array set > > would correspond to Tcl's > > array set > > and so on. Again, to remain idiomatic, I think: nsv_set arrayName elementName value => nsv set arrayName elementName value nsv_get arrayName elementName => nsv get arrayName elementName [...] nsv_array names arrayName => nsv array names arrayName That's just my two cents, of course. -- Dossy -- Dossy Shiobara mail: [EMAIL PROTECTED] Panoptic Computer Network web: http://www.panoptic.com/ "He realized the fastest way to change is to laugh at your own folly -- then you can let go and quickly move on." (p. 70)
Re: [AOLSERVER] Sign Up for AOLserver Documentation!
Title: Message What was the new chat time on Thursdays? Last stated was 3pm Eastern, but then you asked for any takers at 2pm Eastern. I abstained, and no one else spoke up, so I'm assuming it was finally changed to 3pm Eastern. I intend to hang out in the chat room all day from now on. /s. -Original Message-From: AOLserver Discussion [mailto:[EMAIL PROTECTED]] On Behalf Of Nathan FolkmanSent: Sunday, November 03, 2002 9:05 PMTo: [EMAIL PROTECTED]Subject: Re: [AOLSERVER] Sign Up for AOLserver Documentation!In a message dated 11/3/02 7:52:51 PM, [EMAIL PROTECTED] writes: After reviewing this, I now see what you're saying. The problem is thatthe second part of some command names should really have been thesubcommand name.For example: ns_returnadminnoticeshould really have been: ns_return adminnoticeIn the same way, ns_sockopenshould really be ns_sock openWere this the case, it would be obvious to look up 'man ns_sock' and'man ns_return'. In these cases, I take back what I said -- I supposethey should be on the same man page.Thus, it appears the AOLserver Tcl Dev Guide is inconsistent --ns_sockopen, ns_socklisten and the other ns_sock* command should havebeen on the same page together, like ns_return*, but they aren't. Maybethat's because the functionality or passed args are essentially the samefor ns_return*, but different for ns_sock*./s.Ironically Jim and I were just discussing changing the nsv_* commands to be something like ns_svar . Keeping the current nsv_* commands for backward compatibility of course! ;-) I think we should concentrate on documenting the files as they exist in $TOP/aolserver/doc and can revisit single vs. multiple commands per file when we turn our attention towards the 4.0 documentation work.- n
Re: [AOLSERVER] Sign Up for AOLserver Documentation!
Title: Message I Agree. We'll do the 3.5 docs first as-is. I think at some point we should bite the bullet and rename commands like ns_returnadminnotice to be ns_return adminnotice and maintain that consistency throughout the server and modules. Backward compatibility would be kept for some period of time. Is there some reason not to rename the 'nsv_*' commands to correspond to Tcl's 'array' command? Thus, 'nsv_set' would change to 'ns_array set', so that ns_array set would correspond to Tcl's array set and so on. Those familiar with Tcl's array command would then intuitively know how to use the nsv_* / ns_array * commands. It might not be a perfect one-to-one correspondence, but it should come pretty close. /s. -Original Message-From: AOLserver Discussion [mailto:[EMAIL PROTECTED]] On Behalf Of Nathan FolkmanSent: Sunday, November 03, 2002 9:05 PMTo: [EMAIL PROTECTED]Subject: Re: [AOLSERVER] Sign Up for AOLserver Documentation!In a message dated 11/3/02 7:52:51 PM, [EMAIL PROTECTED] writes: After reviewing this, I now see what you're saying. The problem is thatthe second part of some command names should really have been thesubcommand name.For example: ns_returnadminnoticeshould really have been: ns_return adminnoticeIn the same way, ns_sockopenshould really be ns_sock openWere this the case, it would be obvious to look up 'man ns_sock' and'man ns_return'. In these cases, I take back what I said -- I supposethey should be on the same man page.Thus, it appears the AOLserver Tcl Dev Guide is inconsistent --ns_sockopen, ns_socklisten and the other ns_sock* command should havebeen on the same page together, like ns_return*, but they aren't. Maybethat's because the functionality or passed args are essentially the samefor ns_return*, but different for ns_sock*./s.Ironically Jim and I were just discussing changing the nsv_* commands to be something like ns_svar . Keeping the current nsv_* commands for backward compatibility of course! ;-) I think we should concentrate on documenting the files as they exist in $TOP/aolserver/doc and can revisit single vs. multiple commands per file when we turn our attention towards the 4.0 documentation work.- n
Re: [AOLSERVER] Sign Up for AOLserver Documentation!
In a message dated 11/3/02 7:52:51 PM, [EMAIL PROTECTED] writes: After reviewing this, I now see what you're saying. The problem is that the second part of some command names should really have been the subcommand name. For example: ns_returnadminnotice should really have been: ns_return adminnotice In the same way, ns_sockopen should really be ns_sock open Were this the case, it would be obvious to look up 'man ns_sock' and 'man ns_return'. In these cases, I take back what I said -- I suppose they should be on the same man page. Thus, it appears the AOLserver Tcl Dev Guide is inconsistent -- ns_sockopen, ns_socklisten and the other ns_sock* command should have been on the same page together, like ns_return*, but they aren't. Maybe that's because the functionality or passed args are essentially the same for ns_return*, but different for ns_sock*. /s. Ironically Jim and I were just discussing changing the nsv_* commands to be something like ns_svar . Keeping the current nsv_* commands for backward compatibility of course! ;-) I think we should concentrate on documenting the files as they exist in $TOP/aolserver/doc and can revisit single vs. multiple commands per file when we turn our attention towards the 4.0 documentation work. - n
Re: [AOLSERVER] Sign Up for AOLserver Documentation!
> I find, for example, that the traditional AOLserver documentation including all > variants of ns_return on a single page helps me to better understand the range > of responses available. After reviewing this, I now see what you're saying. The problem is that the second part of some command names should really have been the subcommand name. For example: ns_returnadminnotice should really have been: ns_return adminnotice In the same way, ns_sockopen should really be ns_sock open Were this the case, it would be obvious to look up 'man ns_sock' and 'man ns_return'. In these cases, I take back what I said -- I suppose they should be on the same man page. Thus, it appears the AOLserver Tcl Dev Guide is inconsistent -- ns_sockopen, ns_socklisten and the other ns_sock* command should have been on the same page together, like ns_return*, but they aren't. Maybe that's because the functionality or passed args are essentially the same for ns_return*, but different for ns_sock*. /s.
Re: [AOLSERVER] Sign Up for AOLserver Documentation!
On Sunday, November 3, 2002, at 02:33 PM, Scott Goodwin wrote: Documenting multiple commands on the same page ... will confuse the readers I disagree; I find, for example, that the traditional AOLserver documentation including all variants of ns_return on a single page helps me to better understand the range of responses available.
Re: [AOLSERVER] Sign Up for AOLserver Documentation!
On Sunday, November 3, 2002, at 02:09 PM, Scott Goodwin wrote: It breaks the unix standard of one command per man page I think Tcl commands are more akin to library calls than shell commands, and there is no standard for a single library call per man page. For examples, look at the documentation for strcpy and friends, or malloc and friends, which have coalesced a number of closely-related calls into a single page in every version of Unix I've used since WiCAT Unix (a System III derivative) in 1983.
Re: [AOLSERVER] Sign Up for AOLserver Documentation!
In a message dated 11/3/02 3:26:08 PM, [EMAIL PROTECTED] writes: Right. The traditional use of man pages is to type in: $ man Such as "man accept" or "man ls" ... and have the accompanying or related call names in the "SEE ALSO" section. I agree with Scott here. -- Dossy I believe both approaches are valid, take the man page for strstr as an example. - n
Re: [AOLSERVER] Sign Up for AOLserver Documentation!
On 2002.11.03, Scott Goodwin <[EMAIL PROTECTED]> wrote: > > If you mean that all the ns_sock* commands are to be documented under > one ns_sock.n man page, I have to disagree. It breaks the unix standard > of one command per man page. I wouldn't know to look in ns_sock.n for > ns_sockopen; the user should not need to know what file a command is > defined in so they can look up the command. And when I want to see how > ns_sockopen works, I don't want ns_socklisten and the others on the same > page. I'd rather have the other related commands be in the "See Also" > section. > > I believe strongly that we should have one man page per API call, and > not one man page per file name. Right. The traditional use of man pages is to type in: $ man Such as "man accept" or "man ls" ... and have the accompanying or related call names in the "SEE ALSO" section. I agree with Scott here. -- Dossy -- Dossy Shiobara mail: [EMAIL PROTECTED] Panoptic Computer Network web: http://www.panoptic.com/ "He realized the fastest way to change is to laugh at your own folly -- then you can let go and quickly move on." (p. 70)
Re: [AOLSERVER] Sign Up for AOLserver Documentation!
Title: Message Not completely true. The Tcl commands are documented on separate man pages -- the 'for' and 'foreach' Tcl commands are on their own separate pages, and the See Also leads you to the other commands. The Tcl C API is a different story -- in this case, the multiple C API functions are documented on the same page. I personally have a difficult time reading through them. I think it will be simpler and easier to write and read the Tcl API commands if we have each command documented separately on its own man page. Documenting multiple commands on the same page will make the man pages that much longer to scroll through, especially if we have good example code on them, and will confuse the readers, especially people new to AOLserver. Even if the confusion is relatively minor, if it can be avoided, I think it should be. Finally, if you look at the AOLserver 3.0 Tcl Dev Guide, each command has its own, separate page that is different for each command (ns_sockopen and ns_socklisten are not the same, repeated page). These are the reasons I believe we should stick with the unix philosophy of "one man page for one command", and continue to follow the way the 3.0 Tcl Dev Guide is done and Tcl commands are done. /s. -Original Message-From: AOLserver Discussion [mailto:[EMAIL PROTECTED]] On Behalf Of Jim DavidsonSent: Sunday, November 03, 2002 1:13 PMTo: [EMAIL PROTECTED]Subject: Re: [AOLSERVER] Sign Up for AOLserver Documentation!In a message dated 11/3/02 2:09:20 PM, [EMAIL PROTECTED] writes: If you mean that all the ns_sock* commands are to be documented under one ns_sock.n man page, I have to disagree. It breaks the unix standard of one command per man page. I wouldn't know to look in ns_sock.n for ns_sockopen; the user should not need to know what file a command is defined in so they can look up the command. And when I want to see how ns_sockopen works, I don't want ns_socklisten and the others on the same page. I'd rather have the other related commands be in the "See Also" section. I believe strongly that we should have one man page per API call, and not one man page per file name. Hi,The AOLserver doc install, like Tcl, includes a mkLinks script which links up all the pages. This means "man ns_sockopen", "man ns_sockaccept", etc. return the same page.-Jim
Re: [AOLSERVER] Sign Up for AOLserver Documentation!
In a message dated 11/3/02 2:09:20 PM, [EMAIL PROTECTED] writes: If you mean that all the ns_sock* commands are to be documented under one ns_sock.n man page, I have to disagree. It breaks the unix standard of one command per man page. I wouldn't know to look in ns_sock.n for ns_sockopen; the user should not need to know what file a command is defined in so they can look up the command. And when I want to see how ns_sockopen works, I don't want ns_socklisten and the others on the same page. I'd rather have the other related commands be in the "See Also" section. I believe strongly that we should have one man page per API call, and not one man page per file name. Hi, The AOLserver doc install, like Tcl, includes a mkLinks script which links up all the pages. This means "man ns_sockopen", "man ns_sockaccept", etc. return the same page. -Jim
Re: [AOLSERVER] Sign Up for AOLserver Documentation!
Title: Message If you mean that all the ns_sock* commands are to be documented under one ns_sock.n man page, I have to disagree. It breaks the unix standard of one command per man page. I wouldn't know to look in ns_sock.n for ns_sockopen; the user should not need to know what file a command is defined in so they can look up the command. And when I want to see how ns_sockopen works, I don't want ns_socklisten and the others on the same page. I'd rather have the other related commands be in the "See Also" section. I believe strongly that we should have one man page per API call, and not one man page per file name. /s. -Original Message-From: AOLserver Discussion [mailto:[EMAIL PROTECTED]] On Behalf Of Nathan FolkmanSent: Saturday, November 02, 2002 9:03 PMTo: [EMAIL PROTECTED]Subject: [AOLSERVER] Sign Up for AOLserver Documentation!To clarify, please sign up by file name instead of by API name. A number of the man pages contain multiple API's - example: $TOP/aolserver/doc/ns_sock.n. Also, please make sure you are working from the aolserver_v35_bp branch. We need to get the docs completed for 3.5, then we will tackle 4.0.To find out what still needs to be documented:1. Check out the 3.5 code: cvs co -raolserver_v35_bp aolserver2. Take a look in $TOP/aolserver/doc for man page files3. Check the "Tasks" area on SourceForge to see what's already been taken4. Add a new task for the man page file, or send email to [EMAIL PROTECTED] or [EMAIL PROTECTED] with the name of the file and we'll add it for youLet me know if there are any questions. Thanks!- n
[AOLSERVER] Sign Up for AOLserver Documentation!
To clarify, please sign up by file name instead of by API name. A number of the man pages contain multiple API's - example: $TOP/aolserver/doc/ns_sock.n. Also, please make sure you are working from the aolserver_v35_bp branch. We need to get the docs completed for 3.5, then we will tackle 4.0. To find out what still needs to be documented: 1. Check out the 3.5 code: cvs co -raolserver_v35_bp aolserver 2. Take a look in $TOP/aolserver/doc for man page files 3. Check the "Tasks" area on SourceForge to see what's already been taken 4. Add a new task for the man page file, or send email to [EMAIL PROTECTED] or [EMAIL PROTECTED] with the name of the file and we'll add it for you Let me know if there are any questions. Thanks! - n
