Doc improvements.

3 files changed, 61 insertions, 21 deletions

diff --git a/ChangeLog b/ChangeLog
index 65ad93c..4fb2c3d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2009-04-15  Donal K. Fellows  <dkf@users.sf.net>
+
+	* doc/chan.n, doc/close.n: Tidy up documentation of TIP #332.
+
 2009-04-14  Kevin B. Kenny  <kennykb@acm.org>
 
 	* library/tzdata/Asia/Karachi: Updated rules for Pakistan Summer
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?...
diff --git a/doc/close.n b/doc/close.n
index c4b1612..60a8b97 100644
--- a/doc/close.n
+++ b/doc/close.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: close.n,v 1.15 2008/12/18 01:14:16 ferrieux Exp $
+'\" RCS: @(#) $Id: close.n,v 1.16 2009/04/15 12:31:24 dkf Exp $
 '\" 
 .so man.macros
 .TH close n 7.5 Tcl "Tcl Built-In Commands"
@@ -16,7 +16,6 @@ close \- Close an open channel
 .SH SYNOPSIS
 \fBclose \fIchannelId\fR ?r(ead)|w(rite)?
 .BE
-
 .SH DESCRIPTION
 .PP
 Closes or half-closes the channel given by \fIchannelId\fR.
@@ -58,14 +57,25 @@ an error occurs while flushing output.  If a command in a command
 pipeline created with \fBopen\fR returns an error, \fBclose\fR
 generates an error (similar to the \fBexec\fR command.)
 .PP
-The two-argument form is a "half-close": given a bidirectional channel like a socket or command pipeline and a (possibly abbreviated) direction, it closes only the substream going in that direction. This means a shutdown() on a socket, and a close() of one end of a pipe for a command pipeline. Then, the Tcl-level channel data structure is either kept or freed depending on whether the other direction is still open.
+.VS 8.6
+The two-argument form is a "half-close": given a bidirectional channel like a
+socket or command pipeline and a (possibly abbreviated) direction, it closes
+only the substream going in that direction. This means a shutdown() on a
+socket, and a close() of one end of a pipe for a command pipeline. Then, the
+Tcl-level channel data structure is either kept or freed depending on whether
+the other direction is still open.
 .PP
-A single-argument close on an already half-closed bi-channel is defined to just "finish the job. A half-close on an already closed half, or on a wrong-sided unidirectional channel, raises an error.
+A single-argument close on an already half-closed bi-channel is defined to
+just "finish the job. A half-close on an already closed half, or on a
+wrong-sided unidirectional channel, raises an error.
 .PP
-In the case of a command pipeline, the child-reaping duty falls upon the shoulders of the last close or half-close, which is thus allowed to report an abnormal exit error.
+In the case of a command pipeline, the child-reaping duty falls upon the
+shoulders of the last close or half-close, which is thus allowed to report an
+abnormal exit error.
 .PP
-Currently only sockets and command pipelines support half-close. A future extension will allow reflected and stacked channels to do so.
-
+Currently only sockets and command pipelines support half-close. A future
+extension will allow reflected and stacked channels to do so.
+.VE 8.6
 .SH EXAMPLE
 .PP
 This illustrates how you can use Tcl to ensure that files get closed
@@ -87,3 +97,7 @@ proc withOpenFile {filename channelVar script} {
 file(n), open(n), socket(n), eof(n), Tcl_StandardChannels(3)
 .SH KEYWORDS
 blocking, channel, close, nonblocking, half-close
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End: