lint and better documentation of the character vs. byte oriented commands

5 files changed, 51 insertions, 25 deletions

diff --git a/doc/read.n b/doc/read.n
index 21d9549..74f725e 100644
--- a/doc/read.n
+++ b/doc/read.n
@@ -5,10 +5,10 @@
 '\" 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.3 1999/04/16 00:46:35 stanton Exp $
+'\" RCS: @(#) $Id: read.n,v 1.4 1999/05/05 01:19:42 stanton Exp $
 '\" 
 .so man.macros
-.TH read n 7.5 Tcl "Tcl Built-In Commands"
+.TH read n 8.1 Tcl "Tcl Built-In Commands"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,7 +16,7 @@ read \- Read from a channel
 .SH SYNOPSIS
 \fBread \fR?\fB\-nonewline\fR? \fIchannelId\fR
 .sp
-\fBread \fIchannelId numBytes\fR
+\fBread \fIchannelId numChars\fR
 .BE
 
 .SH DESCRIPTION
@@ -25,15 +25,23 @@ 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 bytes to
-read.  Exactly that many bytes will be read and returned, unless
-there are fewer than \fInumBytes\fR left in the file;  in this case
-all the remaining bytes are returned.
+.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.
 .PP
-If \fIchannelId\fR is in nonblocking mode, the command may not read
-as many bytes 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 \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.  
+.VE 8.1
 The \fB\-nonewline\fR switch is ignored if the command returns
 before reaching the end of the file.
 .PP
@@ -47,4 +55,4 @@ which \fBfconfigure\fR will alter input.
 eof(n), fblocked(n), fconfigure(n)
 
 .SH KEYWORDS
-blocking, channel, end of line, end of file, nonblocking, read, translation
+blocking, channel, end of line, end of file, nonblocking, read, translation, encoding
diff --git a/doc/seek.n b/doc/seek.n
index 3620e83..c6d69d2 100644
--- a/doc/seek.n
+++ b/doc/seek.n
@@ -5,10 +5,10 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: seek.n,v 1.2 1998/09/14 18:39:55 stanton Exp $
+'\" RCS: @(#) $Id: seek.n,v 1.3 1999/05/05 01:19:43 stanton Exp $
 '\" 
 .so man.macros
-.TH seek n 7.5 Tcl "Tcl Built-In Commands"
+.TH seek n 8.1 Tcl "Tcl Built-In Commands"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -50,6 +50,12 @@ 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
+.VS 8.1
+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.
+.VE 8.1
 
 .SH KEYWORDS
 access position, file, seek
diff --git a/doc/string.n b/doc/string.n
index 81df8b0..f93e551 100644
--- a/doc/string.n
+++ b/doc/string.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: string.n,v 1.5 1999/05/04 02:57:54 stanton Exp $
+'\" RCS: @(#) $Id: string.n,v 1.6 1999/05/05 01:19:43 stanton Exp $
 '\" 
 .so man.macros
 .TH string n 8.1 Tcl "Tcl Built-In Commands"
@@ -24,8 +24,13 @@ The legal \fIoption\fRs (which may be abbreviated) are:
 .VS 8.1
 .TP
 \fBstring bytelength \fIstring\fR
-Returns a decimal string giving the number of bytes in the
-\fIstring\fR when represented as UTF-8.
+Returns a decimal string giving the number of bytes used to represent
+\fIstring\fR in memory.  Because UTF-8 uses one to three bytes to
+represent Unicode characters, the byte length will not be the same as
+the character length in general.  The cases where a script cares about
+the byte length are rare.  In almost all cases, you should use the
+\fBstring length\fB operation.  Refer to the \fBTcl_NumUtfChars\fR
+manual entry for more details on the UTF-8 representation.
 .TP
 \fBstring compare \fIstring1 string2\fR ?\fIlength\fR?
 .VE 8.1
@@ -79,11 +84,12 @@ A Tcl expression that returns a number.
 .IP \fBend[+-]\fIexpression\fR 10
 The last char of the string plus or minus the number specified
 in the expression (e.g. \fBend-1\fR).
-.RE
+.PP
 .VE 8.1
 If \fIcharIndex\fR is less than 0 or greater than
 or equal to the length of the string then an empty string is
 returned.
+.RE
 .TP
 \fBstring last \fIstring1 string2\fR
 Search \fIstring2\fR for a sequence of characters that exactly match
@@ -92,7 +98,9 @@ first character in the last such match within \fIstring2\fR.  If there
 is no match, then return \-1.
 .TP
 \fBstring length \fIstring\fR
-Returns a decimal string giving the number of characters in \fIstring\fR.
+Returns a decimal string giving the number of characters in
+\fIstring\fR.  Note that this is not necessarily the same as the
+number of bytes used to store the string.
 .VS 8.1
 .TP
 \fBstring map ?\fIoptions\fR? \fIcharMap string\fR
diff --git a/doc/tell.n b/doc/tell.n
index fbbef62..15079c3 100644
--- a/doc/tell.n
+++ b/doc/tell.n
@@ -5,10 +5,10 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: tell.n,v 1.2 1998/09/14 18:39:55 stanton Exp $
+'\" RCS: @(#) $Id: tell.n,v 1.3 1999/05/05 01:19:43 stanton Exp $
 '\" 
 .so man.macros
-.TH tell n 7.5 Tcl "Tcl Built-In Commands"
+.TH tell n 8.1 Tcl "Tcl Built-In Commands"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -19,8 +19,12 @@ tell \- Return current access position for an open channel
 
 .SH DESCRIPTION
 .PP
-Returns a decimal string giving the current access position in
-\fIchannelId\fR.
+.VS 8.1
+Returns an integer string 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.
+.VE 8.1
 The value returned is -1 for channels that do not support
 seeking.
 
diff --git a/generic/tclIOCmd.c b/generic/tclIOCmd.c
index f88840b..bbb4e4e 100644
--- a/generic/tclIOCmd.c
+++ b/generic/tclIOCmd.c
@@ -8,7 +8,7 @@
  * See the file "license.terms" for information on usage and redistribution
  * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  *
- * RCS: @(#) $Id: tclIOCmd.c,v 1.5 1999/04/16 00:46:47 stanton Exp $
+ * RCS: @(#) $Id: tclIOCmd.c,v 1.6 1999/05/05 01:19:43 stanton Exp $
  */
 
 #include "tclInt.h"
@@ -298,7 +298,7 @@ Tcl_ReadObjCmd(dummy, interp, objc, objv)
 
     if ((objc != 2) && (objc != 3)) {
 	argerror:
-	Tcl_WrongNumArgs(interp, 1, objv, "channelId ?numBytes?");
+	Tcl_WrongNumArgs(interp, 1, objv, "channelId ?numChars?");
 	Tcl_AppendResult(interp, " or \"", Tcl_GetString(objv[0]),
 		" ?-nonewline? channelId\"", (char *) NULL);
 	return TCL_ERROR;