Updated http and ReplaceChannel man pages

2 files changed, 50 insertions, 18 deletions

diff --git a/doc/ChnlReplace.3 b/doc/ChnlReplace.3
index a1129c3..3c56cb3 100644
--- a/doc/ChnlReplace.3
+++ b/doc/ChnlReplace.3
@@ -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: ChnlReplace.3,v 1.2 1999/06/25 23:46:59 welch Exp $
+'\" RCS: @(#) $Id: ChnlReplace.3,v 1.3 1999/06/30 17:46:51 welch Exp $
 .so man.macros
 .TH Tcl_ReplaceChannel 3 8.2 Tcl "Tcl Library Procedures"
 .BS
@@ -47,25 +47,46 @@ a new channel on top of an existing one.
 Any number of channels can be stacked together.
 .PP
 \fBTcl_ReplaceChannel\fR
-interposes a new channel type on an existing \fIchannel\fP.
-After the call to \fBTcl_ReplaceChannel\fR,
-any operation on \fIchannel\fP uses the I/O channel functions
+replaces an existing \fIchannel\fP with a new channel by
+the same name that was registered for \fIchannel\fP
+with \fBTcl_RegisterChannel\fP.
+Because the channel name is the same, all Tcl-level I/O
+operations will automatically use the new channel instead
+of the old one.
+The new channel uses the I/O channel functions
 defined in \fItypePtr\fP, and the channel functions are passed
-the new \fIclientData\fP instead of the existing client data
-for \fIchannel\fP.
-A new channel structure is created under the same name that
-exists for \fIchannel\fP, and the existing Tcl_Channel data structure
-is linked using the channelPtr->supercedes structure member.
+the new \fIclientData\fP.
+A pointer to the new channel structure is returned.
+If an error occurs when creating the new channel,
+NULL is returned instead. 
+.PP
+The \fImask\fP parameter specifies the operations that
+are allowed on the new channel.
+These can be a subset of the operations allowed on the original channel.
+For example, a read-write channel may become
+read-only after the \fBTcl_ReplaceChannel\fR call.
+.PP
+The old Tcl_Channel data structure
+is linked to the new channel
+using the \fBsupercedes\fP structure member of the
+Tcl_Channel that is returned by
+\fBTcl_ReplaceChannel\fR.
 The new channel functions
-should use Tcl_Read and Tcl_Write to get at the underlying channel.
-Closing the new channel closes the channels stacked below it.
+should use the standard channel APIs like
+\fBTcl_Read\fP, \fBTcl_ReadChars\fP and \fBTcl_Write\fP
+to get at the underlying channel instead of
+accessing the other channel data structure directly.
 .PP
-The set of operations allowed on the new channel can be restricted
-by the new channel type. For example, a read-write channel may become
-read-only after the \fBTcl_ReplaceChannel\fR
-call.
+Closing the new channel closes the channels stacked below it.
+The close of stacked channels is executed in a way that
+allows buffered data to be properly flushed.
 .PP
-\fBTcl_UndoReplaceChannel\fP restores the channel to its original state.
+\fBTcl_UndoReplaceChannel\fP reverses the process.
+The old channel is associated with the channel name,
+and the new channel created by 
+\fBTcl_ReplaceChannel\fR is destroyed.
+If there is no old channel, then \fBTcl_UndoReplaceChannel\fP 
+is equivalent to \fBTcl_Close\fP .
 
 .SH "SEE ALSO"
 Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n).
diff --git a/doc/http.n b/doc/http.n
index 7fd61ce..b4f1b1e 100644
--- a/doc/http.n
+++ b/doc/http.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: http.n,v 1.3 1999/04/16 00:46:35 stanton Exp $
+'\" RCS: @(#) $Id: http.n,v 1.4 1999/06/30 17:46:51 welch Exp $
 '\" 
 .so man.macros
 .TH "Http" n 8.0 Tcl "Tcl Built-In Commands"
@@ -32,6 +32,8 @@ Http \- Client-side implementation of the HTTP/1.0 protocol.
 \fB::http::code \fItoken\fR
 .sp
 \fB::http::data \fItoken\fR
+.sp
+\fB::http::cleanup \fItoken\fR
 .BE
 
 .SH DESCRIPTION
@@ -243,6 +245,13 @@ state array.
 \fB::http::size\fP \fItoken\fP
 This is a convenience procedure that returns the \fBcurrentsize\fP
 element of the state array.
+.TP
+\fB::http::cleanup\fP \fItoken\fP
+This procedure cleans up the state associated with the connection
+identified by \fItoken\fP.  After this call, the procedures
+like \fB::http::data\fP cannot be used to get information
+about the operation.
+
 .SH "STATE ARRAY"
 The \fB::http::geturl\fR procedure returns a \fItoken\fR that can be used to
 get to the state of the HTTP transaction in the form of a Tcl array.
@@ -251,7 +260,9 @@ Use this construct to create an easy-to-use array variable:
 upvar #0 $token state
 .CE
 Once the data associated with the url is no longer needed, the state
-array should be unset to free up storage.  The following elements of
+array should be unset to free up storage.
+The \fBhttp::cleanup\fP procedure is provided for that purpose.
+The following elements of
 the array are supported:
 .RS
 .TP