[Bug 2957688]: clarified [socket -server] docs

2 files changed, 43 insertions, 33 deletions

diff --git a/ChangeLog b/ChangeLog
index 5ff895c..32ed37c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,41 +1,45 @@
+2010-02-24  Donal K. Fellows  <dkf@users.sf.net>
+
+	* doc/socket.n: [Bug 2957688]: Clarified that [socket -server] works
+	with a command prefix. Extended example to show this in action.
+
 2010-02-22  Andreas Kupries  <andreask@activestate.com>
 
-	* generic/tclZlib.c (ZlibTransformInput): [Bug 2762041]: Added a
-	hack to work around the general problem, early EOF recognition
-	based on the base-channel, instead of the data we have ready for
-	reading in the transform. Long-term we need a proper general fix
-	(likely tracking EOF on each level of the channel stack), with
-	attendant complexity. Further: Z_BUF_ERROR can be ignored, and
-	must be when feeding the zlib code with single characters.
+	* generic/tclZlib.c (ZlibTransformInput): [Bug 2762041]: Added a hack
+	to work around the general problem, early EOF recognition based on the
+	base-channel, instead of the data we have ready for reading in the
+	transform. Long-term we need a proper general fix (likely tracking EOF
+	on each level of the channel stack), with attendant complexity.
+	Furthermore, Z_BUF_ERROR can be ignored, and must be when feeding the
+	zlib code with single characters.
 
 2010-02-22  Jan Nijtmans  <nijtmans@users.sf.net>
 
-	* unix/tclUnixPort.h    Remove unnecessary EXTERN's, which already
-	                        are in the global stub table.
-	* unix/configure.in     Use @EXEEXT@ in stead of @EXT_SUFFIX@
-	* unix/tcl.m4
-	* unix/Makefile.in      Use -DBUILD_tcl for CYGWIN
-	* unix/configure        (regenerated)
-	* unix/dltest/pkg*.c    Use EXTERN to control CYGWIN exported symbols
-	* generic/tclCmdMZ.c    Remove some unnecessary type casts.
-	* generic/tclCompCmds.c
-	* generic/tclTest.c
-	* generic/tclUtil.c
+	* unix/tclUnixPort.h:   Remove unnecessary EXTERN's, which already are
+	                        in the global stub table.
+	* unix/configure.in:    Use @EXEEXT@ in stead of @EXT_SUFFIX@
+	* unix/tcl.m4:
+	* unix/Makefile.in:     Use -DBUILD_tcl for CYGWIN
+	* unix/configure:       (regenerated)
+	* unix/dltest/pkg*.c:   Use EXTERN to control CYGWIN exported symbols
+	* generic/tclCmdMZ.c:   Remove some unnecessary type casts.
+	* generic/tclCompCmds.c:
+	* generic/tclTest.c:
+	* generic/tclUtil.c:
 
 2010-02-21  Mo DeJong  <mdejong@users.sourceforge.net>
 
-	* tests/regexp.test: Add test cases back ported from
-        Jacl regexp work.
+	* tests/regexp.test: Add test cases back ported from Jacl regexp work.
 
 2010-02-21  Jan Nijtmans  <nijtmans@users.sf.net>
 
-	* generic/tclDate.c     Some more const tables.
-	* generic/tclGetDate.y
-	* generic/regc_lex.c
-	* generic/regerror.c
-	* generic/tclStubLib.c
+	* generic/tclDate.c:    Some more const tables.
+	* generic/tclGetDate.y:
+	* generic/regc_lex.c:
+	* generic/regerror.c:
+	* generic/tclStubLib.c:
 	* generic/tclBasic.c:   Fix [Bug 2954959] expr abs(0.0) is -0.0
-	* tests/expr.test
+	* tests/expr.test:
 
 2010-02-20  Donal K. Fellows  <dkf@users.sf.net>
 
diff --git a/doc/socket.n b/doc/socket.n
index 6fe5517..7596abb 100644
--- a/doc/socket.n
+++ b/doc/socket.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: socket.n,v 1.19 2010/01/20 13:42:17 dkf Exp $
+'\" RCS: @(#) $Id: socket.n,v 1.20 2010/02/24 10:11:46 dkf Exp $
 .so man.macros
 .TH socket n 8.0 Tcl "Tcl Built-In Commands"
 .BS
@@ -100,6 +100,7 @@ using \fBfconfigure\fR to read the \fB\-sockname\fR option).
 Tcl will automatically accept connections to the given port.
 For each connection Tcl will create a new channel that may be used to
 communicate with the client.  Tcl then invokes \fIcommand\fR
+(properly a command prefix list, see the \fBEXAMPLES\fR below)
 with three additional arguments: the name of the new channel, the
 address, in network address notation, of the client's host, and
 the client's port number.
@@ -164,24 +165,29 @@ list is identical to the address, its first element.
 Here is a very simple time server:
 .PP
 .CS
-proc Server {channel clientaddr clientport} {
+proc Server {startTime channel clientaddr clientport} {
     puts "Connection from $clientaddr registered"
-    puts $channel [clock format [clock seconds]]
+    set now [clock seconds]
+    puts $channel [clock format $now]
+    puts $channel "[expr {$now - $startTime}] since start"
     close $channel
 }
 
-\fBsocket\fR -server Server 9900
+\fBsocket -server\fR [list Server [clock seconds]] 9900
 vwait forever
 .CE
 .PP
-And here is the corresponding client to talk to the server:
+And here is the corresponding client to talk to the server and extract
+some information:
 .PP
 .CS
 set server localhost
 set sockChan [\fBsocket\fR $server 9900]
-gets $sockChan line
+gets $sockChan line1
+gets $sockChan line2
 close $sockChan
-puts "The time on $server is $line"
+puts "The time on $server is $line1"
+puts "That is [lindex $line2 0]s since the server started"
 .CE
 .SH "SEE ALSO"
 fconfigure(n), flush(n), open(n), read(n)