Doc improvements.

1 files changed, 36 insertions, 14 deletions

diff --git a/doc/chan.n b/doc/chan.n
index 2924465..d353fab 100644
--- a/doc/chan.n
+++ b/doc/chan.n
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: chan.n,v 1.23 2009/01/30 11:34:36 dkf Exp $
+'\" RCS: @(#) $Id: chan.n,v 1.24 2009/04/15 12:31:24 dkf Exp $
 .so man.macros
 .TH chan n 8.5 Tcl "Tcl Built-In Commands"
 .BS
@@ -33,22 +33,35 @@ otherwise. Note that this only ever returns 1 when the channel has
 been configured to be non-blocking; all Tcl channels have blocking
 turned on by default.
 .TP
-\fBchan close \fIchannelId\fR
+\fBchan close \fIchannelId\fR ?\fIdirection\fR?
 .
 Close and destroy the channel called \fIchannelId\fR. Note that this
 deletes all existing file-events registered on the channel.
+.VS 8.6
+If the \fIdirection\fR argument (which must be \fBread\fR or \fBwrite\fR or
+any unique abbreviation of them) is present, the channel will only be
+half-closed, so that it can go from being read-write to write-only or
+read-only respectively. If a read-only channel is closed for reading, it is
+the same as if the channel is fully closed, and respectively similar for
+write-only channels. Without the \fIdirection\fR argument, the channel is
+closed for both reading and writing (but only if those directions are
+currently open). It is an error to close a read-only channel for writing, or a
+write-only channel for reading.
+.VE 8.6
 .RS
 .PP
 As part of closing the channel, all buffered output is flushed to the
-channel's output device, any buffered input is discarded, the
-underlying operating system resource is closed and \fIchannelId\fR
-becomes unavailable for future use.
-.PP
-If the channel is blocking, the command does not return until all
-output is flushed.  If the channel is nonblocking and there is
-unflushed output, the channel remains open and the command returns
-immediately; output will be flushed in the background and the channel
-will be closed when all the flushing is complete.
+channel's output device (only if the channel is ceasing to be writable), any
+buffered input is discarded (only if the channel is ceasing to be readable),
+the underlying operating system resource is closed and \fIchannelId\fR becomes
+unavailable for future use (both only if the channel is being completely
+closed).
+.PP
+If the channel is blocking and the channel is ceasing to be writable, the
+command does not return until all output is flushed.  If the channel is
+nonblocking and there is unflushed output, the channel remains open and the
+command returns immediately; output will be flushed in the background and the
+channel will be closed when all the flushing is complete.
 .PP
 If \fIchannelId\fR is a blocking channel for a command pipeline then
 \fBchan close\fR waits for the child processes to complete.
@@ -58,10 +71,12 @@ makes \fIchannelId\fR unavailable in the invoking interpreter but has
 no other effect until all of the sharing interpreters have closed the
 channel. When the last interpreter in which the channel is registered
 invokes \fBchan close\fR (or \fBclose\fR), the cleanup actions
-described above occur. See the \fBinterp\fR command for a description
-of channel sharing.
+described above occur. With half-closing, the half-close of the channel only
+applies to the current interpreter's view of the channel until all channels
+have closed it in that direction (or completely).
+See the \fBinterp\fR command for a description of channel sharing.
 .PP
-Channels are automatically closed when an interpreter is destroyed and
+Channels are automatically fully closed when an interpreter is destroyed and
 when the process exits.  Channels are switched to blocking mode, to
 ensure that all output is correctly flushed before the process exits.
 .PP
@@ -69,6 +84,13 @@ The command returns an empty string, and may generate an error if
 an error occurs while flushing output.  If a command in a command
 pipeline created with \fBopen\fR returns an error, \fBchan close\fR
 generates an error (similar to the \fBexec\fR command.)
+.PP
+.VS 8.6
+Note that half-closes of sockets and command pipelines can have important side
+effects because they result in a shutdown() or close() of the underlying
+system resource, which can change how other processes or systems respond to
+the Tcl program.
+.VE 8.6
 .RE
 .TP
 \fBchan configure \fIchannelId\fR ?\fIoptionName\fR? ?\fIvalue\fR? ?\fIoptionName value\fR?...