Improved documentation on behaviour of read w.r.t. serial ports.

[Bug #219402]

1 files changed, 33 insertions, 15 deletions

diff --git a/doc/read.n b/doc/read.n
index 4194285..66dba85 100644
--- a/doc/read.n
+++ b/doc/read.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: read.n,v 1.5 2000/09/07 14:27:50 poenitz Exp $
+'\" RCS: @(#) $Id: read.n,v 1.6 2001/04/06 14:27:51 dkf Exp $
 '\" 
 .so man.macros
 .TH read n 8.1 Tcl "Tcl Built-In Commands"
@@ -22,16 +22,15 @@ read \- Read from a channel
 .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.
-.VS 8.1
-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.
+\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
 If \fIchannelId\fR is in nonblocking mode, the command may not read as
 many characters as requested: once all available input has been read,
@@ -40,10 +39,8 @@ 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.  
-.VE 8.1
-The \fB\-nonewline\fR switch is ignored if the command returns
-before reaching the end of the file.
+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
@@ -51,6 +48,27 @@ for the channel.
 See the \fBfconfigure\fR manual entry for a discussion on ways in
 which \fBfconfigure\fR will alter input.
 
+.SH "USE WITH SERIAL PORTS"
+'\" Note:  this advice actually applies to many versions of Tcl
+.VS 8.4
+For most applications a channel connected to a serial port should be
+configured to be nonblocking: \fBfconfigure \fIchannelId \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 -eofchar\fR. If there no end-of-file
+character has been configured for the channel, then \fBread\fR will
+block forever.
+.VE
+
 .SH "SEE ALSO"
 file(n), eof(n), fblocked(n), fconfigure(n)