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 Davidson
Sent: Sunday, November 03, 2002 1:13 PM
To: [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
