Backport: Consolidate channel documentation. close, puts etc. manpages now just reference chan (remainder)

11 files changed, 35 insertions, 1024 deletions

diff --git a/doc/close.n b/doc/close.n
index 2066583..f3a61be 100644
--- a/doc/close.n
+++ b/doc/close.n
@@ -16,97 +16,10 @@ close \- Close an open channel
 .BE
 .SH DESCRIPTION
 .PP
-Closes or half-closes the channel given by \fIchannelId\fR. \fBchan close\fR
-is another name for this command.
-.PP
-\fIChannelId\fR must be an identifier for an open channel such as a
-Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR),
-the return value from an invocation of \fBopen\fR or \fBsocket\fR, or
-the result of a channel creation command provided by a Tcl extension.
-.PP
-The single-argument form is a simple
-.QW "full-close" :
-all buffered output is flushed to the channel's output device,
-any buffered input is discarded, the underlying file or device is closed,
-and \fIchannelId\fR becomes unavailable for 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.
-.PP
-If \fIchannelId\fR is a blocking channel for a command pipeline then
-\fBclose\fR waits for the child processes to complete.
-.PP
-If the channel is shared between interpreters, then \fBclose\fR
-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
-\fBclose\fR, the cleanup actions described above occur. See the
-\fBinterp\fR command for a description of channel sharing.
-.PP
-Channels are automatically closed when an interpreter is destroyed and
-when the process exits.
-From 8.6 on (TIP#398), nonblocking channels are no longer switched to
-blocking mode when exiting; this guarantees a timely exit even when the
-peer or a communication channel is stalled. To ensure proper flushing of
-stalled nonblocking channels on exit, one must now either (a) actively
-switch them back to blocking or (b) use the environment variable
-\fBTCL_FLUSH_NONBLOCKING_ON_EXIT\fR, which when set and not equal to
-.QW \fB0\fR
-restores the previous behavior.
-.PP
-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 (either by returning a
-non-zero exit code or writing to its standard error file descriptor),
-\fBclose\fR generates an error (similar to the \fBexec\fR command.)
-.PP
-The two-argument form is a
-.QW "half-close" :
-given a bidirectional channel like a
-socket or command pipeline and a (possibly abbreviated) direction, it closes
-only the sub-stream 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 bidirectional channel is
-defined to just
-.QW "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.
-.PP
-Currently only sockets and command pipelines support half-close. A future
-extension will allow reflected and stacked channels to do so.
-.SH EXAMPLE
-.PP
-This illustrates how you can use Tcl to ensure that files get closed
-even when errors happen by combining \fBcatch\fR, \fBclose\fR and
-\fBreturn\fR:
-.PP
-.CS
-proc withOpenFile {filename channelVar script} {
-    upvar 1 $channelVar chan
-    set chan [open $filename]
-    catch {
-        uplevel 1 $script
-    } result options
-    \fBclose\fR $chan
-    return -options $options $result
-}
-.CE
+The \fBclose\fR command has been superceded by the \fBchan close\fR
+command which supports the same syntax and options.
 .SH "SEE ALSO"
-chan(n), file(n), open(n), socket(n), eof(n), Tcl_StandardChannels(3)
-.SH KEYWORDS
-blocking, channel, close, nonblocking, half-close
+chan(n)
 '\" Local Variables:
 '\" mode: nroff
 '\" fill-column: 78
diff --git a/doc/eof.n b/doc/eof.n
index 0dcf34a..7eea515 100644
--- a/doc/eof.n
+++ b/doc/eof.n
@@ -16,49 +16,10 @@ eof \- Check for end of file condition on channel
 .BE
 .SH DESCRIPTION
 .PP
-Returns 1 if an end of file condition occurred during the most
-recent input operation on \fIchannelId\fR (such as \fBgets\fR),
-0 otherwise.
-.PP
-\fIChannelId\fR must be an identifier for an open channel such as a
-Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR),
-the return value from an invocation of \fBopen\fR or \fBsocket\fR, or
-the result of a channel creation command provided by a Tcl extension.
-.SH EXAMPLES
-.PP
-Read and print out the contents of a file line-by-line:
-.PP
-.CS
-set f [open somefile.txt]
-while {1} {
-    set line [gets $f]
-    if {[\fBeof\fR $f]} {
-        close $f
-        break
-    }
-    puts "Read line: $line"
-}
-.CE
-.PP
-Read and print out the contents of a file by fixed-size records:
-.PP
-.CS
-set f [open somefile.dat]
-fconfigure $f -translation binary
-set recordSize 40
-while {1} {
-    set record [read $f $recordSize]
-    if {[\fBeof\fR $f]} {
-        close $f
-        break
-    }
-    puts "Read record: $record"
-}
-.CE
+The \fBeof\fR command has been superceded by the \fBchan eof\fR
+command which supports the same syntax and options.
 .SH "SEE ALSO"
-file(n), open(n), close(n), fblocked(n), Tcl_StandardChannels(3)
-.SH KEYWORDS
-channel, end of file
+chan(n)
 '\" Local Variables:
 '\" mode: nroff
 '\" fill-column: 78
diff --git a/doc/fblocked.n b/doc/fblocked.n
index 0a28dcf..239c465 100644
--- a/doc/fblocked.n
+++ b/doc/fblocked.n
@@ -12,59 +12,12 @@ fblocked \- Test whether the last input operation exhausted all available input
 .SH SYNOPSIS
 \fBfblocked \fIchannelId\fR
 .BE
-
 .SH DESCRIPTION
 .PP
-The \fBfblocked\fR command returns 1 if the most recent input operation
-on \fIchannelId\fR returned less information than requested because all
-available input was exhausted.
-For example, if \fBgets\fR is invoked when there are only three
-characters available for input and no end-of-line sequence, \fBgets\fR
-returns an empty string and a subsequent call to \fBfblocked\fR will
-return 1.
-.PP
-\fIChannelId\fR must be an identifier for an open channel such as a
-Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR),
-the return value from an invocation of \fBopen\fR or \fBsocket\fR, or
-the result of a channel creation command provided by a Tcl extension.
-.SH EXAMPLE
-The \fBfblocked\fR command is particularly useful when writing network
-servers, as it allows you to write your code in a line-by-line style
-without preventing the servicing of other connections.  This can be
-seen in this simple echo-service:
-.PP
-.CS
-# This is called whenever a new client connects to the server
-proc connect {chan host port} {
-    set clientName [format <%s:%d> $host $port]
-    puts "connection from $clientName"
-    fconfigure $chan -blocking 0 -buffering line
-    fileevent $chan readable [list echoLine $chan $clientName]
-}
-
-# This is called whenever either at least one byte of input
-# data is available, or the channel was closed by the client.
-proc echoLine {chan clientName} {
-    gets $chan line
-    if {[eof $chan]} {
-        puts "finishing connection from $clientName"
-        close $chan
-    } elseif {![\fBfblocked\fR $chan]} {
-        # Didn't block waiting for end-of-line
-        puts "$clientName - $line"
-        puts $chan $line
-    }
-}
-
-# Create the server socket and enter the event-loop to wait
-# for incoming connections...
-socket -server connect 12345
-vwait forever
-.CE
+The \fBfblocked\fR command has been superceded by the \fBchan blocked\fR
+command which supports the same syntax and options.
 .SH "SEE ALSO"
-gets(n), open(n), read(n), socket(n), Tcl_StandardChannels(3)
-.SH KEYWORDS
-blocking, nonblocking
+chan(n)
 '\" Local Variables:
 '\" mode: nroff
 '\" fill-column: 78
diff --git a/doc/fconfigure.n b/doc/fconfigure.n
index 3de22eb..2870d54 100644
--- a/doc/fconfigure.n
+++ b/doc/fconfigure.n
@@ -13,287 +13,16 @@ fconfigure \- Set and get options on a channel
 .SH SYNOPSIS
 .nf
 \fBfconfigure \fIchannelId\fR
-\fBfconfigure \fIchannelId\fR \fIname\fR
-\fBfconfigure \fIchannelId\fR \fIname value \fR?\fIname value ...\fR?
+\fBfconfigure \fIchannelId name\fR
+\fBfconfigure \fIchannelId name value \fR?\fIname value ...\fR?
 .fi
 .BE
 .SH DESCRIPTION
 .PP
-The \fBfconfigure\fR command sets and retrieves options for channels.
-.PP
-\fIChannelId\fR identifies the channel for which to set or query an
-option and must refer to an open channel such as a Tcl standard
-channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR), the return
-value from an invocation of \fBopen\fR or \fBsocket\fR, or the result
-of a channel creation command provided by a Tcl extension.
-.PP
-If no \fIname\fR or \fIvalue\fR arguments are supplied, the command
-returns a list containing alternating option names and values for the channel.
-If \fIname\fR is supplied but no \fIvalue\fR then the command returns
-the current value of the given option.
-If one or more pairs of \fIname\fR and \fIvalue\fR are supplied, the
-command sets each of the named options to the corresponding \fIvalue\fR;
-in this case the return value is an empty string.
-.PP
-The options described below are supported for all channels. In addition,
-each channel type may add options that only it supports. See the manual
-entry for the command that creates each type of channels for the options
-that that specific type of channel supports. For example, see the manual
-entry for the \fBsocket\fR command for additional options for sockets, and
-the \fBopen\fR command for additional options for serial devices.
-.TP
-\fB\-blocking\fR \fIboolean\fR
-The \fB\-blocking\fR option determines whether I/O operations on the
-channel can cause the process to block indefinitely.
-The value of the option must be a proper boolean value.
-Channels are normally in blocking mode;  if a channel is placed into
-nonblocking mode it will affect the operation of the \fBgets\fR,
-\fBread\fR, \fBputs\fR, \fBflush\fR, and \fBclose\fR commands by
-allowing them to operate asynchronously;
-see the documentation for those commands for details.
-For nonblocking mode to work correctly, the application must be
-using the Tcl event loop (e.g. by calling \fBTcl_DoOneEvent\fR or
-invoking the \fBvwait\fR command).
-.TP
-\fB\-buffering\fR \fInewValue\fR
-.
-If \fInewValue\fR is \fBfull\fR then the I/O system will buffer output
-until its internal buffer is full or until the \fBflush\fR command is
-invoked. If \fInewValue\fR is \fBline\fR, then the I/O system will
-automatically flush output for the channel whenever a newline character
-is output. If \fInewValue\fR is \fBnone\fR, the I/O system will flush
-automatically after every output operation.  The default is for
-\fB\-buffering\fR to be set to \fBfull\fR except for channels that
-connect to terminal-like devices; for these channels the initial setting
-is \fBline\fR.  Additionally, \fBstdin\fR and \fBstdout\fR are
-initially set to \fBline\fR, and \fBstderr\fR is set to \fBnone\fR.
-.TP
-\fB\-buffersize\fR \fInewSize\fR
-.
-\fINewvalue\fR must be an integer; its value is used to set the size of
-buffers, in bytes, subsequently allocated for this channel to store input
-or output. \fINewvalue\fR must be between one and one million, allowing
-buffers of one to one million bytes in size.
-.TP
-\fB\-encoding\fR \fIname\fR
-.
-This option is used to specify the encoding of the channel, so that the data
-can be converted to and from Unicode for use in Tcl.  For instance, in
-order for Tcl to read characters from a Japanese file in \fBshiftjis\fR
-and properly process and display the contents, the encoding would be set
-to \fBshiftjis\fR.  Thereafter, when reading from the channel, the bytes in
-the Japanese file would be converted to Unicode as they are read.
-Writing is also supported \- as Tcl strings are written to the channel they
-will automatically be converted to the specified encoding on output.
-.RS
-.PP
-If a file contains pure binary data (for instance, a JPEG image), the
-encoding for the channel should be configured to be \fBbinary\fR.  Tcl
-will then assign no interpretation to the data in the file and simply read or
-write raw bytes.  The Tcl \fBbinary\fR command can be used to manipulate this
-byte-oriented data.  It is usually better to set the
-\fB\-translation\fR option to \fBbinary\fR when you want to transfer
-binary data, as this turns off the other automatic interpretations of
-the bytes in the stream as well.
-.PP
-The default encoding for newly opened channels is the same platform- and
-locale-dependent system encoding used for interfacing with the operating
-system, as returned by \fBencoding system\fR.
-.RE
-.TP
-\fB\-eofchar\fR \fIchar\fR
-.TP
-\fB\-eofchar\fR \fB{\fIchar outChar\fB}\fR
-.
-This option supports DOS file systems that use Control-z (\ex1A) as an
-end of file marker.  If \fIchar\fR is not an empty string, then this
-character signals end-of-file when it is encountered during input.  For
-output, the end-of-file character is output when the channel is closed.
-If \fIchar\fR is the empty string, then there is no special end of file
-character marker.  For read-write channels, a two-element list specifies
-the end of file marker for input and output, respectively.  As a
-convenience, when setting the end-of-file character for a read-write
-channel you can specify a single value that will apply to reading
-only.  When querying the end-of-file character of a read-write
-channel, a two-element list will always be returned.  The default value
-for \fB\-eofchar\fR is the empty string in all cases except for files
-under Windows.  In that case the \fB\-eofchar\fR is Control-z (\ex1A) for
-reading and the empty string for writing.
-The acceptable range for \fB\-eofchar\fR values is \ex01 - \ex7F;
-attempting to set \fB\-eofchar\fR to a value outside of this range will
-generate an error.
-.VS "TCL8.7 TIP656"
-.TP
-\fB\-profile\fR \fIprofile\fR
-.
-Specifies the encoding profile to be used on the channel. The encoding
-transforms in use for the channel's input and output will then be subject to the
-rules of that profile. Any failures will result in a channel error. See
-\fBPROFILES\fR in the \fBencoding(n)\fR documentation for details about encoding
-profiles.
-.VE "TCL8.7 TIP656"
-.TP
-\fB\-translation\fR \fImode\fR
-.TP
-\fB\-translation\fR \fB{\fIinMode outMode\fB}\fR
-.
-In Tcl scripts the end of a line is always represented using a single
-newline character (\en).  However, in actual files and devices the end of
-a line may be represented differently on different platforms, or even for
-different devices on the same platform.  For example, under UNIX newlines
-are used in files, whereas carriage-return-linefeed sequences are
-normally used in network connections.  On input (i.e., with \fBgets\fR
-and \fBread\fR) the Tcl I/O system automatically translates the external
-end-of-line representation into newline characters.  Upon output (i.e.,
-with \fBputs\fR), the I/O system translates newlines to the external
-end-of-line representation.  The default translation mode, \fBauto\fR,
-handles all the common cases automatically, but the \fB\-translation\fR
-option provides explicit control over the end of line translations.
-.RS
-.PP
-The value associated with \fB\-translation\fR is a single item for
-read-only and write-only channels.  The value is a two-element list for
-read-write channels; the read translation mode is the first element of
-the list, and the write translation mode is the second element.  As a
-convenience, when setting the translation mode for a read-write channel
-you can specify a single value that will apply to both reading and
-writing.  When querying the translation mode of a read-write channel, a
-two-element list will always be returned.  The following values are
-currently supported:
-.TP
-\fBauto\fR
-.
-As the input translation mode, \fBauto\fR treats any of newline
-(\fBlf\fR), carriage return (\fBcr\fR), or carriage return followed by a
-newline (\fBcrlf\fR) as the end of line representation.  The end of line
-representation can even change from line-to-line, and all cases are
-translated to a newline.  As the output translation mode, \fBauto\fR
-chooses a platform specific representation; for sockets on all platforms
-Tcl chooses \fBcrlf\fR, for all Unix flavors, it chooses \fBlf\fR, and
-for the various flavors of Windows it chooses \fBcrlf\fR.  The default
-setting for \fB\-translation\fR is \fBauto\fR for both input and output.
-.TP
-\fBbinary\fR
-.
-No end-of-line translations are performed.  This is nearly identical to
-\fBlf\fR mode, except that in addition \fBbinary\fR mode also sets the
-end-of-file character to the empty string (which disables it) and sets the
-encoding to \fBbinary\fR (which disables encoding filtering).  See the
-description of \fB\-eofchar\fR and \fB\-encoding\fR for more information.
-.RS
-.PP
-Internally, i.e. when it comes to the actual behaviour of the
-translator this value \fBis\fR identical to \fBlf\fR and is therefore
-reported as such when queried. Even if \fBbinary\fR was used to set
-the translation.
-.RE
-.TP
-\fBcr\fR
-.
-The end of a line in the underlying file or device is represented by a
-single carriage return character.  As the input translation mode,
-\fBcr\fR mode converts carriage returns to newline characters.  As the
-output translation mode, \fBcr\fR mode translates newline characters to
-carriage returns.
-.TP
-\fBcrlf\fR
-.
-The end of a line in the underlying file or device is represented by a
-carriage return character followed by a linefeed character.  As the input
-translation mode, \fBcrlf\fR mode converts carriage-return-linefeed
-sequences to newline characters.  As the output translation mode,
-\fBcrlf\fR mode translates newline characters to carriage-return-linefeed
-sequences.  This mode is typically used on Windows platforms and for
-network connections.
-.TP
-\fBlf\fR
-.
-The end of a line in the underlying file or device is represented by a
-single newline (linefeed) character.  In this mode no translations occur
-during either input or output.  This mode is typically used on UNIX
-platforms.
-.RE
-.PP
-.SH "STANDARD CHANNELS"
-.PP
-The Tcl standard channels (\fBstdin\fR, \fBstdout\fR, and \fBstderr\fR)
-can be configured through this command like every other channel opened
-by the Tcl library. Beyond the standard options described above they
-will also support any special option according to their current type.
-If, for example, a Tcl application is started by the \fBinet\fR
-super-server common on Unix system its Tcl standard channels will be
-sockets and thus support the socket options.
-.SH EXAMPLES
-.PP
-Instruct Tcl to always send output to \fBstdout\fR immediately,
-whether or not it is to a terminal:
-.PP
-.CS
-\fBfconfigure\fR stdout -buffering none
-.CE
-.PP
-Open a socket and read lines from it without ever blocking the
-processing of other events:
-.PP
-.CS
-set s [socket some.where.com 12345]
-\fBfconfigure\fR $s -blocking 0
-fileevent $s readable "readMe $s"
-proc readMe chan {
-    if {[gets $chan line] < 0} {
-        if {[eof $chan]} {
-            close $chan
-            return
-        }
-        # Could not read a complete line this time; Tcl's
-        # internal buffering will hold the partial line for us
-        # until some more data is available over the socket.
-    } else {
-        puts stdout $line
-    }
-}
-.CE
-.PP
-Read a PPM-format image from a file:
-.PP
-.CS
-# Open the file and put it into Unix ASCII mode
-set f [open teapot.ppm]
-\fBfconfigure\fR $f \-encoding ascii \-translation lf
-
-# Get the header
-if {[gets $f] ne "P6"} {
-    error "not a raw\-bits PPM"
-}
-
-# Read lines until we have got non-comment lines
-# that supply us with three decimal values.
-set words {}
-while {[llength $words] < 3} {
-    gets $f line
-    if {[string match "#*" $line]} continue
-    lappend words {*}[join [scan $line %d%d%d]]
-}
-
-# Those words supply the size of the image and its
-# overall depth per channel. Assign to variables.
-lassign $words xSize ySize depth
-
-# Now switch to binary mode to pull in the data,
-# one byte per channel (red,green,blue) per pixel.
-\fBfconfigure\fR $f \-translation binary
-set numDataBytes [expr {3 * $xSize * $ySize}]
-set data [read $f $numDataBytes]
-
-close $f
-.CE
+The \fBfconfigure\fR command has been superceded by the \fBchan configure\fR
+command which supports the same syntax and options.
 .SH "SEE ALSO"
-close(n), encoding(n), flush(n), gets(n), open(n), puts(n), read(n), socket(n),
-Tcl_StandardChannels(3)
-.SH KEYWORDS
-blocking, buffering, carriage return, end of line, flushing, linemode,
-newline, nonblocking, platform, profile, translation, encoding, filter, byte array,
-binary
+chan(n)
 '\" Local Variables:
 '\" mode: nroff
 '\" End:
diff --git a/doc/fileevent.n b/doc/fileevent.n
index bbba997..4ba534a 100644
--- a/doc/fileevent.n
+++ b/doc/fileevent.n
@@ -17,143 +17,12 @@ fileevent \- Execute a script when a channel becomes readable or writable
 .sp
 \fBfileevent \fIchannelId \fBwritable \fR?\fIscript\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
-This command is used to create \fIfile event handlers\fR.  A file event
-handler is a binding between a channel and a script, such that the script
-is evaluated whenever the channel becomes readable or writable.  File event
-handlers are most commonly used to allow data to be received from another
-process on an event-driven basis, so that the receiver can continue to
-interact with the user while waiting for the data to arrive.  If an
-application invokes \fBgets\fR or \fBread\fR on a blocking channel when
-there is no input data available, the process will block; until the input
-data arrives, it will not be able to service other events, so it will
-appear to the user to
-.QW "freeze up" .
-With \fBfileevent\fR, the process can
-tell when data is present and only invoke \fBgets\fR or \fBread\fR when
-they will not block.
-.PP
-The \fIchannelId\fR argument to \fBfileevent\fR refers to an open
-channel such as a Tcl standard channel (\fBstdin\fR, \fBstdout\fR,
-or \fBstderr\fR), the return value from an invocation of \fBopen\fR
-or \fBsocket\fR, or the result of a channel creation command provided
-by a Tcl extension.
-.PP
-If the \fIscript\fR argument is specified, then \fBfileevent\fR
-creates a new event handler:  \fIscript\fR will be evaluated
-whenever the channel becomes readable or writable (depending on the
-second argument to \fBfileevent\fR).
-In this case \fBfileevent\fR returns an empty string.
-The \fBreadable\fR and \fBwritable\fR event handlers for a file
-are independent, and may be created and deleted separately.
-However, there may be at most one \fBreadable\fR and one \fBwritable\fR
-handler for a file at a given time in a given interpreter.
-If \fBfileevent\fR is called when the specified handler already
-exists in the invoking interpreter, the new script replaces the old one.
-.PP
-If the \fIscript\fR argument is not specified, \fBfileevent\fR
-returns the current script for \fIchannelId\fR, or an empty string
-if there is none.
-If the \fIscript\fR argument is specified as an empty string
-then the event handler is deleted, so that no script will be invoked.
-A file event handler is also deleted automatically whenever
-its channel is closed or its interpreter is deleted.
-.PP
-A channel is considered to be readable if there is unread data
-available on the underlying device.
-A channel is also considered to be readable if there is unread
-data in an input buffer, except in the special case where the
-most recent attempt to read from the channel was a \fBgets\fR
-call that could not find a complete line in the input buffer.
-This feature allows a file to be read a line at a time in nonblocking mode
-using events.
-A channel is also considered to be readable if an end of file or
-error condition is present on the underlying file or device.
-It is important for \fIscript\fR to check for these conditions
-and handle them appropriately;  for example, if there is no special
-check for end of file, an infinite loop may occur where \fIscript\fR
-reads no data, returns, and is immediately invoked again.
-.PP
-A channel is considered to be writable if at least one byte of data
-can be written to the underlying file or device without blocking,
-or if an error condition is present on the underlying file or device.
-.PP
-Event-driven I/O works best for channels that have been placed into
-nonblocking mode with the \fBfconfigure\fR command.  In blocking mode,
-a \fBputs\fR command may block if you give it more data than the
-underlying file or device can accept, and a \fBgets\fR or \fBread\fR
-command will block if you attempt to read more data than is ready; a
-readable underlying file or device may not even guarantee that a
-blocking [read 1] will succeed (counter-examples being multi-byte
-encodings, compression or encryption transforms ). In all such cases,
-no events will be processed while the commands block.
-.PP
-In nonblocking mode \fBputs\fR, \fBread\fR, and \fBgets\fR never block.
-See the documentation for the individual commands for information
-on how they handle blocking and nonblocking channels.
-.PP
-Testing for the end of file condition should be done after any attempts
-read the channel data. The eof flag is set once an attempt to read the
-end of data has occurred and testing before this read will require an
-additional event to be fired.
-.PP
-The script for a file event is executed at global level (outside the
-context of any Tcl procedure) in the interpreter in which the
-\fBfileevent\fR command was invoked.
-If an error occurs while executing the script then the
-command registered with \fBinterp bgerror\fR is used to report the error.
-In addition, the file event handler is deleted if it ever returns
-an error;  this is done in order to prevent infinite loops due to
-buggy handlers.
-.SH EXAMPLE
-.PP
-In this setup \fBGetData\fR will be called with the channel as an
-argument whenever $chan becomes readable. The \fBread\fR call will
-read whatever binary data is currently available without blocking.
-Here the channel has the fileevent removed when an end of file
-occurs to avoid being continually called (see above). Alternatively
-the channel may be closed on this condition.
-.PP
-.CS
-proc GetData {chan} {
-    set data [read $chan]
-    puts "[string length $data] $data"
-    if {[eof $chan]} {
-        fileevent $chan readable {}
-    }
-}
-
-fconfigure $chan -blocking 0 -encoding binary
-\fBfileevent\fR $chan readable [list GetData $chan]
-.CE
-.PP
-The next example demonstrates use of \fBgets\fR to read line-oriented
-data.
-.PP
-.CS
-proc GetData {chan} {
-    if {[gets $chan line] >= 0} {
-        puts $line
-    }
-    if {[eof $chan]} {
-        close $chan
-    }
-}
-
-fconfigure $chan -blocking 0 -buffering line -translation crlf
-\fBfileevent\fR $chan readable [list GetData $chan]
-.CE
-.SH CREDITS
-.PP
-\fBfileevent\fR is based on the \fBaddinput\fR command created
-by Mark Diekhans.
+The \fBfileevent\fR command has been superceded by the \fBchan event\fR
+command which supports the same syntax and options.
 .SH "SEE ALSO"
-fconfigure(n), gets(n), interp(n), puts(n), read(n), Tcl_StandardChannels(3)
-.SH KEYWORDS
-asynchronous I/O, blocking, channel, event handler, nonblocking, readable,
-script, writable.
+chan(n)
 '\" Local Variables:
 '\" mode: nroff
 '\" fill-column: 78
diff --git a/doc/flush.n b/doc/flush.n
index 1d84383..259f4cb 100644
--- a/doc/flush.n
+++ b/doc/flush.n
@@ -16,33 +16,10 @@ flush \- Flush buffered output for a channel
 .BE
 .SH DESCRIPTION
 .PP
-Flushes any output that has been buffered for \fIchannelId\fR.
-.PP
-\fIChannelId\fR must be an identifier for an open channel such as a
-Tcl standard channel (\fBstdout\fR or \fBstderr\fR), the return
-value from an invocation of \fBopen\fR or \fBsocket\fR, or the result
-of a channel creation command provided by a Tcl extension.  The
-channel must have been opened for writing.
-.PP
-If the channel is in blocking mode the command does not return until all the
-buffered output has been flushed to the channel. If the channel is in
-nonblocking mode, the command may return before all buffered output has been
-flushed; the remainder will be flushed in the background as fast as the
-underlying file or device is able to absorb it.
-.SH EXAMPLE
-.PP
-Prompt for the user to type some information in on the console:
-.PP
-.CS
-puts -nonewline "Please type your name: "
-\fBflush\fR stdout
-gets stdin name
-puts "Hello there, $name!"
-.CE
+The \fBflush\fR command has been superceded by the \fBchan flush\fR
+command which supports the same syntax and options.
 .SH "SEE ALSO"
-file(n), open(n), socket(n), Tcl_StandardChannels(3)
-.SH KEYWORDS
-blocking, buffer, channel, flush, nonblocking, output
+chan(n)
 '\" Local Variables:
 '\" mode: nroff
 '\" fill-column: 78
diff --git a/doc/gets.n b/doc/gets.n
index 29355a4..8ee0db1 100644
--- a/doc/gets.n
+++ b/doc/gets.n
@@ -14,94 +14,12 @@ gets \- Read a line from a channel
 .SH SYNOPSIS
 \fBgets \fIchannelId\fR ?\fIvarName\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
-This command reads the next line from \fIchannelId\fR, returns everything
-in the line up to (but not including) the end-of-line character(s), and
-discards the end-of-line character(s).
-.PP
-\fIChannelId\fR must be an identifier for an open channel such as the
-Tcl standard input channel (\fBstdin\fR), the return value from an
-invocation of \fBopen\fR or \fBsocket\fR, or the result of a channel
-creation command provided by a Tcl extension. The channel must have
-been opened for input.
-.PP
-If \fIvarName\fR is omitted the line is returned as the result of the
-command.
-If \fIvarName\fR is specified then the line is placed in the variable by
-that name and the return value is a count of the number of characters
-returned.
-.PP
-If end of file occurs while scanning for an end of
-line, the command returns whatever input is available up to the end of file.
-If \fIchannelId\fR is in non-blocking mode and there is not a full
-line of input available, the command returns an empty string and
-does not consume any input.
-If \fIvarName\fR is specified and an empty string is returned in
-\fIvarName\fR because of end-of-file or because of insufficient
-data in non-blocking mode, then the return count is -1.
-Note that if \fIvarName\fR is not specified then the end-of-file
-and no-full-line-available cases can
-produce the same results as if there were an input line consisting
-only of the end-of-line character(s).
-The \fBeof\fR and \fBfblocked\fR commands can be used to distinguish
-these three cases.
-.SH "ENCODING ERRORS"
-.PP
-Encoding errors may exist, if the encoding profile \fBstrict\fR is used.
-Encoding errors are special, as an eventual introspection or  recovery is
-possible by changing to an encoding which accepts the data.
-An encoding error is reported by the POSIX error code \fBEILSEQ\fR.
-The file pointer is unchanged in the error case.
-.PP
-Here is an example with an encoding error in UTF-8 encoding, which is then
-introspected by a switch to the binary encoding. The test file contains a not
-continued multi-byte sequence at position 1 (\fBA \\xC3 B\fR):
-.PP
-File creation for example
-.CS
-% set f [open test_A_195_B.txt wb]; puts -nonewline $f A\\xC3B; close $f
-.CE
-Encoding error example
-.CS
-% set f [open test_A_195_B.txt r]
-file384b6a8
-% fconfigure $f -encoding utf-8 -profile strict
-% catch {gets $f} e d
-1
-% set d
--code 1 -level 0
--errorstack {INNER {invokeStk1 gets file384b6a8}}
--errorcode {POSIX EILSEQ {invalid or incomplete multibyte or wide character}}
--errorinfo {...} -errorline 1
-% tell $f
-0
-% fconfigure $f -encoding binary -profile strict
-% gets $f
-AÃB
-.CE
-Compared to \fBread\fR, any already decoded data is not consumed.
-The file position is still at 0 and the recovery \fBgets\fR returns also the
-already well decoded leading data.
-.SH "EXAMPLE"
-This example reads a file one line at a time and prints it out with
-the current line number attached to the start of each line.
-.PP
-.CS
-set chan [open "some.file.txt"]
-set lineNumber 0
-while {[\fBgets\fR $chan line] >= 0} {
-    puts "[incr lineNumber]: $line"
-}
-close $chan
-.CE
-
+The \fBgets\fR command has been superceded by the \fBchan gets\fR
+command which supports the same syntax and options.
 .SH "SEE ALSO"
-file(n), eof(n), fblocked(n), Tcl_StandardChannels(3)
-
-.SH KEYWORDS
-blocking, channel, end of file, end of line, line, non-blocking, read
+chan(n)
 '\" Local Variables:
 '\" mode: nroff
 '\" fill-column: 78
diff --git a/doc/puts.n b/doc/puts.n
index 0943f87..e818273 100644
--- a/doc/puts.n
+++ b/doc/puts.n
@@ -16,92 +16,10 @@ puts \- Write to a channel
 .BE
 .SH DESCRIPTION
 .PP
-Writes the characters given by \fIstring\fR to the channel given
-by \fIchannelId\fR.
-.PP
-\fIChannelId\fR must be an identifier for an open channel such as a
-Tcl standard channel (\fBstdout\fR or \fBstderr\fR), the return
-value from an invocation of \fBopen\fR or \fBsocket\fR, or the result
-of a channel creation command provided by a Tcl extension. The channel
-must have been opened for output.
-.PP
-If no \fIchannelId\fR is specified then it defaults to
-\fBstdout\fR. \fBPuts\fR normally outputs a newline character after
-\fIstring\fR, but this feature may be suppressed by specifying the
-\fB\-nonewline\fR switch.
-.PP
-Newline characters in the output are translated by \fBputs\fR to
-platform-specific end-of-line sequences according to the current
-value of the \fB\-translation\fR option for the channel (for example,
-on PCs newlines are normally replaced with carriage-return-linefeed
-sequences.
-See the \fBfconfigure\fR manual entry for a discussion on ways in
-which \fBfconfigure\fR will alter output.
-.PP
-Tcl buffers output internally, so characters written with \fBputs\fR
-may not appear immediately on the output file or device;  Tcl will
-normally delay output until the buffer is full or the channel is
-closed.
-You can force output to appear immediately with the \fBflush\fR
-command.
-.PP
-When the output buffer fills up, the \fBputs\fR command will normally
-block until all the buffered data has been accepted for output by the
-operating system.
-If \fIchannelId\fR is in nonblocking mode then the \fBputs\fR command
-will not block even if the operating system cannot accept the data.
-Instead, Tcl continues to buffer the data and writes it in the
-background as fast as the underlying file or device can accept it.
-The application must use the Tcl event loop for nonblocking output
-to work;  otherwise Tcl never finds out that the file or device is
-ready for more output data.
-It is possible for an arbitrarily large amount of data to be
-buffered for a channel in nonblocking mode, which could consume a
-large amount of memory.
-To avoid wasting memory, nonblocking I/O should normally
-be used in an event-driven fashion with the \fBfileevent\fR command
-(do not invoke \fBputs\fR unless you have recently been notified
-via a file event that the channel is ready for more output data).
-.SH "ENCODING ERRORS"
-.PP
-Encoding errors may exist, if the encoding profile \fBstrict\fR is used.
-\fBputs\fR writes out data until an encoding error occurs and fails with
-POSIX error code \fBEILSEQ\fR.
-
-.SH EXAMPLES
-.PP
-Write a short message to the console (or wherever \fBstdout\fR is
-directed):
-.PP
-.CS
-\fBputs\fR "Hello, World!"
-.CE
-.PP
-Print a message in several parts:
-.PP
-.CS
-\fBputs\fR -nonewline "Hello, "
-\fBputs\fR "World!"
-.CE
-.PP
-Print a message to the standard error channel:
-.PP
-.CS
-\fBputs\fR stderr "Hello, World!"
-.CE
-.PP
-Append a log message to a file:
-.PP
-.CS
-set chan [open my.log a]
-set timestamp [clock format [clock seconds]]
-\fBputs\fR $chan "$timestamp - Hello, World!"
-close $chan
-.CE
+The \fBputs\fR command has been superceded by the \fBchan puts\fR
+command which supports the same syntax and options.
 .SH "SEE ALSO"
-file(n), fileevent(n), Tcl_StandardChannels(3)
-.SH KEYWORDS
-channel, newline, output, write
+chan(n)
 '\" Local Variables:
 '\" mode: nroff
 '\" fill-column: 78
diff --git a/doc/read.n b/doc/read.n
index 7c0c155..d298138 100644
--- a/doc/read.n
+++ b/doc/read.n
@@ -18,145 +18,10 @@ read \- Read from a channel
 .BE
 .SH DESCRIPTION
 .PP
-In the first form, the \fBread\fR command reads all of the data from
-\fIchannelId\fR up to the end of the file.  If the \fB\-nonewline\fR
-switch is specified then the last character of the file is discarded
-if it is a newline.  In the second form, the extra argument specifies
-how many characters to read.  Exactly that many characters will be
-read and returned, unless there are fewer than \fInumChars\fR left in
-the file; in this case all the remaining characters are returned.  If
-the channel is configured to use a multi-byte encoding, then the
-number of characters read may not be the same as the number of bytes
-read.
-.PP
-\fIChannelId\fR must be an identifier for an open channel such as the
-Tcl standard input channel (\fBstdin\fR), the return value from an
-invocation of \fBopen\fR or \fBsocket\fR, or the result of a channel
-creation command provided by a Tcl extension. The channel must have
-been opened for input.
-.PP
-If \fIchannelId\fR is in nonblocking mode, the command may not read as
-many characters as requested: once all available input has been read,
-the command will return the data that is available rather than
-blocking for more input.  If the channel is configured to use a
-multi-byte encoding, then there may actually be some bytes remaining
-in the internal buffers that do not form a complete character.  These
-bytes will not be returned until a complete character is available or
-end-of-file is reached.  The \fB\-nonewline\fR switch is ignored if
-the command returns before reaching the end of the file.
-.PP
-\fBRead\fR translates end-of-line sequences in the input into
-newline characters according to the \fB\-translation\fR option
-for the channel.
-See the \fBfconfigure\fR manual entry for a discussion on ways in
-which \fBfconfigure\fR will alter input.
-.SH "ENCODING ERRORS"
-.PP
-Encoding errors may exist, if the encoding profile \fBstrict\fR is used.
-Encoding errors are special, as an eventual introspection or  recovery is
-possible by changing to an encoding (or encoding profile), which accepts
-the data.
-An encoding error is reported by the POSIX error code \fBEILSEQ\fR.
-.PP
-In blocking mode, the error is directly thrown, even, if there is a
-leading decodable data portion.
-The file pointer is advanced just before the encoding error.
-An eventual well decoded data chunk before the encoding error is returned
-in the error option dictionary key \fB-data\fR.
-The value of the key contains the empty string, if the error arises at the
-first data position.
-.PP
-In non blocking mode, first, any data without encoding error is returned
-(without error state).
-In the next call, no data is returned and the \fBEILSEQ\fR error state is set.
-The key \fB-data\fR is not present.
-.PP
-Here is an example with an encoding error in UTF-8 encoding, which is then
-introspected by a switch to the binary encoding. The test file contains a not
-continued multi-byte sequence at position 1 (\fBA \\xC3 B\fR):
-.PP
-File creation for examples
-.
-.CS
-% set f [open test_A_195_B.txt wb]; puts -nonewline $f A\\xC3B; close $f
-.CE
-Blocking example
-.
-.CS
-% set f [open test_A_195_B.txt r]
-file35a65a0
-% fconfigure $f -encoding utf-8 -profile strict -blocking 1
-% catch {read $f} e d
-1
-% set d
--data A -code 1 -level 0
--errorstack {INNER {invokeStk1 read file35a65a0}}
--errorcode {POSIX EILSEQ {invalid or incomplete multibyte or wide character}}
--errorinfo {...} -errorline 1
-% tell $f
-1
-% fconfigure $f -encoding binary -profile strict
-% read $f
-ÃB
-% close $f
-.CE
-The already decoded data "A" is returned in the error options dictionary key
-\fB-data\fR.
-The file position is advanced on the encoding error position 1.
-The data at the error position is thus recovered by the next \fBread\fR command.
-.PP
-Non blocking example
-.
-.CS
-% set f [open test_A_195_B.txt r]
-file35a65a0
-% fconfigure $f -encoding utf-8 -profile strict -blocking 0
-% read $f
-A
-% tell $f
-1
-% catch {read $f} e d
-1
-% set d
--code 1 -level 0
--errorstack {INNER {invokeStk1 read file384b228}}
--errorcode {POSIX EILSEQ {invalid or incomplete multibyte or wide character}}
--errorinfo {...} -errorline 1
-.CE
-.SH "USE WITH SERIAL PORTS"
-'\" Note:  this advice actually applies to many versions of Tcl
-.PP
-For most applications a channel connected to a serial port should be
-configured to be nonblocking: \fBfconfigure\fI channelId \fB\-blocking
-\fI0\fR.  Then \fBread\fR behaves much like described above.  Care
-must be taken when using \fBread\fR on blocking serial ports:
-.TP
-\fBread \fIchannelId numChars\fR
-.
-In this form \fBread\fR blocks until \fInumChars\fR have been received
-from the serial port.
-.TP
-\fBread \fIchannelId\fR
-.
-In this form \fBread\fR blocks until the reception of the end-of-file
-character, see \fBfconfigure\fR \fB\-eofchar\fR. If there no end-of-file
-character has been configured for the channel, then \fBread\fR will
-block forever.
-.SH "EXAMPLE"
-.PP
-This example code reads a file all at once, and splits it into a list,
-with each line in the file corresponding to an element in the list:
-.PP
-.CS
-set fl [open /proc/meminfo]
-set data [\fBread\fR $fl]
-close $fl
-set lines [split $data \en]
-.CE
+The \fBread\fR command has been superceded by the \fBchan read\fR
+command which supports the same syntax and options.
 .SH "SEE ALSO"
-file(n), eof(n), fblocked(n), fconfigure(n), Tcl_StandardChannels(3)
-.SH KEYWORDS
-blocking, channel, end of line, end of file, nonblocking, read, translation, encoding
+chan(n)
 '\"Local Variables:
 '\"mode: nroff
 '\"End:
diff --git a/doc/seek.n b/doc/seek.n
index 3b206d1..8f0e707 100644
--- a/doc/seek.n
+++ b/doc/seek.n
@@ -16,76 +16,10 @@ seek \- Change the access position for an open channel
 .BE
 .SH DESCRIPTION
 .PP
-Changes the current access position for \fIchannelId\fR.
-.PP
-\fIChannelId\fR must be an identifier for an open channel such as a
-Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR),
-the return value from an invocation of \fBopen\fR or \fBsocket\fR, or
-the result of a channel creation command provided by a Tcl extension.
-.PP
-The \fIoffset\fR and \fIorigin\fR
-arguments specify the position at which the next read or write will occur
-for \fIchannelId\fR. \fIOffset\fR must be an integer (which may be
-negative) and \fIorigin\fR must be one of the following:
-.TP 10
-\fBstart\fR
-.
-The new access position will be \fIoffset\fR bytes from the start
-of the underlying file or device.
-.TP 10
-\fBcurrent\fR
-.
-The new access position will be \fIoffset\fR bytes from the current
-access position; a negative \fIoffset\fR moves the access position
-backwards in the underlying file or device.
-.TP 10
-\fBend\fR
-.
-The new access position will be \fIoffset\fR bytes from the end of
-the file or device.  A negative \fIoffset\fR places the access position
-before the end of file, and a positive \fIoffset\fR places the access
-position after the end of file.
-.PP
-The \fIorigin\fR argument defaults to \fBstart\fR.
-.PP
-The command flushes all buffered output for the channel before the command
-returns, even if the channel is in non-blocking mode.
-It also discards any buffered and unread input.
-This command returns an empty string.
-An error occurs if this command is applied to channels whose underlying
-file or device does not support seeking.
-.PP
-Note that \fIoffset\fR values are byte offsets, not character
-offsets.  Both \fBseek\fR and \fBtell\fR operate in terms of bytes,
-not characters, unlike \fBread\fR.
-.SH EXAMPLES
-.PP
-Read a file twice:
-.PP
-.CS
-set f [open file.txt]
-set data1 [read $f]
-\fBseek\fR $f 0
-set data2 [read $f]
-close $f
-# $data1 eq $data2 if the file wasn't updated
-.CE
-.PP
-Read the last 10 bytes from a file:
-.PP
-.CS
-set f [open file.data]
-# This is guaranteed to work with binary data but
-# may fail with other encodings...
-fconfigure $f -translation binary
-\fBseek\fR $f -10 end
-set data [read $f 10]
-close $f
-.CE
+The \fBseek\fR command has been superceded by the \fBchan seek\fR
+command which supports the same syntax and options.
 .SH "SEE ALSO"
-file(n), open(n), close(n), gets(n), tell(n), Tcl_StandardChannels(3)
-.SH KEYWORDS
-access position, file, seek
+chan(n)
 '\" Local Variables:
 '\" mode: nroff
 '\" fill-column: 78
diff --git a/doc/tell.n b/doc/tell.n
index 54fbae1..4948a19 100644
--- a/doc/tell.n
+++ b/doc/tell.n
@@ -16,36 +16,10 @@ tell \- Return current access position for an open channel
 .BE
 .SH DESCRIPTION
 .PP
-Returns an integer giving the current access position in
-\fIchannelId\fR.  This value returned is a byte offset that can be passed to
-\fBseek\fR in order to set the channel to a particular position.  Note
-that this value is in terms of bytes, not characters like \fBread\fR.
-The value returned is -1 for channels that do not support
-seeking.
-.PP
-\fIChannelId\fR must be an identifier for an open channel such as a
-Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR),
-the return value from an invocation of \fBopen\fR or \fBsocket\fR, or
-the result of a channel creation command provided by a Tcl extension.
-.SH EXAMPLE
-.PP
-Read a line from a file channel only if it starts with \fBfoobar\fR:
-.PP
-.CS
-# Save the offset in case we need to undo the read...
-set offset [\fBtell\fR $chan]
-if {[read $chan 6] eq "foobar"} {
-    gets $chan line
-} else {
-    set line {}
-    # Undo the read...
-    seek $chan $offset
-}
-.CE
+The \fBtell\fR command has been superceded by the \fBchan tell\fR
+command which supports the same syntax and options.
 .SH "SEE ALSO"
-file(n), open(n), close(n), gets(n), seek(n), Tcl_StandardChannels(3)
-.SH KEYWORDS
-access position, channel, seeking
+chan(n)
 '\" Local Variables:
 '\" mode: nroff
 '\" fill-column: 78