4 files changed, 81 insertions, 55 deletions
diff --git a/doc/BoolObj.3 b/doc/BoolObj.3
index 41c0a73..3b05a9e 100644
--- a/doc/BoolObj.3
+++ b/doc/BoolObj.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: BoolObj.3,v 1.5 2004/10/07 15:37:43 dkf Exp $
+'\" RCS: @(#) $Id: BoolObj.3,v 1.5.2.1 2005/04/25 21:37:18 kennykb Exp $
 '\" 
 .so man.macros
 .TH Tcl_BooleanObj 3 8.0 Tcl "Tcl Library Procedures"
@@ -65,25 +65,35 @@ and, if the object is not already a boolean object,
 frees any old internal representation.
 .PP
 \fBTcl_GetBooleanFromObj\fR attempts to return a boolean value
-from the Tcl object \fIobjPtr\fR.
-If the object is not already a boolean object,
-it will attempt to convert it to one.
-If an error occurs during conversion, it returns \fBTCL_ERROR\fR
-and leaves an error message in the interpreter's result object
-unless \fIinterp\fR is NULL.
-Otherwise, \fBTcl_GetBooleanFromObj\fR returns \fBTCL_OK\fR
-and stores the boolean value in the address given by \fIboolPtr\fR.
-If the object is not already a boolean object,
-the conversion will free any old internal representation.
-Objects having a string representation equal to any of \fB0\fR,
-\fBfalse\fR, \fBno\fR, or \fBoff\fR have a boolean value 0; if the
-string representation is any of \fB1\fR, \fBtrue\fR, \fByes\fR, or
-\fBon\fR the boolean value is 1.
-Any of these string values may be abbreviated, and upper-case spellings
-are also acceptable.
+corresponding to the value of the Tcl object \fIobjPtr\fR.
+If \fIobjPtr\fR is of the boolean type, its boolean value
+is written at the address given by \fIboolPtr\fR.  
+If \fIobjPtr\fR has a string representation recognized by
+\fBTcl_GetBoolean\fR, then \fIobjPtr\fR is converted to boolean
+type and its boolean value is written at the address given
+by \fIboolPtr\fR.  If \fIobjPtr\fR holds any value recognized as
+a number by Tcl, then if that value is zero a 0 is written at
+the address given by \fIboolPtr\fR and if that
+value is non-zero a 1 is written at the address given by \fIboolPtr\fR.
+In all cases where a value is written at the address given
+by \fIboolPtr\fR, \fBTCL_OK\fR is returned.
+If the value of \fIobjPtr\fR does not meet any of the conditions
+above, then \fBTCL_ERROR\fR is returned and error message is 
+left in the interpreter's result unless \fIinterp\fR is NULL.
+.PP
+Note that the routines \fBTcl_GetBooleanFromObj\fR and
+\fBTcl_GetBoolean\fR are not functional equivalents.
+The set of values for which \fBTcl_GetBooleanFromObj\fR
+will return \fBTCL_OK\fR is strictly larger than
+the set of values for which \fBTcl_GetBoolean\fR will do the same.
+For example, the value "5" passed to \fBTcl_GetBooleanFromObj\fR
+will lead to a \fBTCL_OK\fR return (and the boolean value 1),
+while the same value passed to \fBTcl_GetBoolean\fR will lead to
+a \fBTCL_ERROR\fR return.
 
 .SH "SEE ALSO"
-Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
+Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult,
+Tcl_GetBoolean
 
 .SH KEYWORDS
 boolean, boolean object, boolean type, internal representation, object, object type, string representation
diff --git a/doc/GetInt.3 b/doc/GetInt.3
index bd1475e..515dd91 100644
--- a/doc/GetInt.3
+++ b/doc/GetInt.3
@@ -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: GetInt.3,v 1.7 2004/10/07 15:15:38 dkf Exp $
+'\" RCS: @(#) $Id: GetInt.3,v 1.7.2.1 2005/04/25 21:37:18 kennykb Exp $
 '\" 
 .so man.macros
 .TH Tcl_GetInt 3 "" Tcl "Tcl Library Procedures"
@@ -17,62 +17,64 @@ Tcl_GetInt, Tcl_GetDouble, Tcl_GetBoolean \- convert from string to integer, dou
 \fB#include <tcl.h>\fR
 .sp
 int
-\fBTcl_GetInt\fR(\fIinterp, string, intPtr\fR)
+\fBTcl_GetInt\fR(\fIinterp, str, intPtr\fR)
 .sp
 int
-\fBTcl_GetDouble\fR(\fIinterp, string, doublePtr\fR)
+\fBTcl_GetDouble\fR(\fIinterp, str, doublePtr\fR)
 .sp
 int
-\fBTcl_GetBoolean\fR(\fIinterp, string, boolPtr\fR)
+\fBTcl_GetBoolean\fR(\fIinterp, str, boolPtr\fR)
 .SH ARGUMENTS
 .AS Tcl_Interp *doublePtr out
 .AP Tcl_Interp *interp in
 Interpreter to use for error reporting.
-.AP "const char" *string in
+.AP "const char" *str in
 Textual value to be converted.
 .AP int *intPtr out
-Points to place to store integer value converted from \fIstring\fR.
+Points to place to store integer value converted from \fIstr\fR.
 .AP double *doublePtr out
 Points to place to store double-precision floating-point
-value converted from \fIstring\fR.
+value converted from \fIstr\fR.
 .AP int *boolPtr out
-Points to place to store boolean value (0 or 1) converted from \fIstring\fR.
+Points to place to store boolean value (0 or 1) converted from \fIstr\fR.
 .BE
 
 .SH DESCRIPTION
 .PP
 These procedures convert from strings to integers or double-precision
 floating-point values or booleans (represented as 0- or 1-valued
-integers).  Each of the procedures takes a \fIstring\fR argument,
+integers).  Each of the procedures takes a \fIstr\fR argument,
 converts it to an internal form of a particular type, and stores
 the converted value at the location indicated by the procedure's
 third argument.  If all goes well, each of the procedures returns
-\fBTCL_OK\fR.  If \fIstring\fR doesn't have the proper syntax for the
+\fBTCL_OK\fR.  If \fIstr\fR doesn't have the proper syntax for the
 desired type then \fBTCL_ERROR\fR is returned, an error message is left
 in the interpreter's result, and nothing is stored at *\fIintPtr\fR
 or *\fIdoublePtr\fR or *\fIboolPtr\fR.
 .PP
-\fBTcl_GetInt\fR expects \fIstring\fR to consist of a collection
+\fBTcl_GetInt\fR expects \fIstr\fR to consist of a collection
 of integer digits, optionally signed and optionally preceded by
-white space.  If the first two characters of \fIstring\fR are ``0x''
-then \fIstring\fR is expected to be in hexadecimal form;  otherwise,
-if the first character of \fIstring\fR is ``0'' then \fIstring\fR
-is expected to be in octal form;  otherwise, \fIstring\fR is
+white space.  If the first two characters of \fIstr\fR
+after the optional white space and sign are ``0x''
+then \fIstr\fR is expected to be in hexadecimal form;  otherwise,
+if the first such character is ``0'' then \fIstr\fR
+is expected to be in octal form;  otherwise, \fIstr\fR is
 expected to be in decimal form.
 .PP
-\fBTcl_GetDouble\fR expects \fIstring\fR to consist of a floating-point
+\fBTcl_GetDouble\fR expects \fIstr\fR to consist of a floating-point
 number, which is:  white space;  a sign; a sequence of digits;  a
-decimal point;  a sequence of digits;  the letter ``e'';  and a
-signed decimal exponent.  Any of the fields may be omitted, except that
+decimal point;  a sequence of digits;  the letter ``e'';  a
+signed decimal exponent ; and more white space.
+Any of the fields may be omitted, except that
 the digits either before or after the decimal point must be present
 and if the ``e'' is present then it must be followed by the
 exponent number.
 .PP
-\fBTcl_GetBoolean\fR expects \fIstring\fR to specify a boolean
-value.  If \fIstring\fR is any of \fB0\fR, \fBfalse\fR,
+\fBTcl_GetBoolean\fR expects \fIstr\fR to specify a boolean
+value.  If \fIstr\fR is any of \fB0\fR, \fBfalse\fR,
 \fBno\fR, or \fBoff\fR, then \fBTcl_GetBoolean\fR stores a zero
 value at \fI*boolPtr\fR.
-If \fIstring\fR is any of \fB1\fR, \fBtrue\fR, \fByes\fR, or \fBon\fR,
+If \fIstr\fR is any of \fB1\fR, \fBtrue\fR, \fByes\fR, or \fBon\fR,
 then 1 is stored at \fI*boolPtr\fR.
 Any of these values may be abbreviated, and upper-case spellings
 are also acceptable.
diff --git a/doc/fconfigure.n b/doc/fconfigure.n
index 807ce90..56cbf8a 100644
--- a/doc/fconfigure.n
+++ b/doc/fconfigure.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: fconfigure.n,v 1.11 2004/10/27 12:53:22 dkf Exp $
+'\" RCS: @(#) $Id: fconfigure.n,v 1.11.2.1 2005/04/25 21:37:18 kennykb Exp $
 '\"
 .so man.macros
 .TH fconfigure n 8.3 Tcl "Tcl Built-In Commands"
@@ -91,11 +91,14 @@ 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.
+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.  
+system, as returned by \fBencoding system\fR.
 .RE
 .TP
 \fB\-eofchar\fR \fIchar\fR
diff --git a/doc/fcopy.n b/doc/fcopy.n
index a90cc7b..11f0689 100644
--- a/doc/fcopy.n
+++ b/doc/fcopy.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: fcopy.n,v 1.4 2004/09/06 09:44:56 dkf Exp $
+'\" RCS: @(#) $Id: fcopy.n,v 1.4.2.1 2005/04/25 21:37:19 kennykb Exp $
 '\" 
 .so man.macros
 .TH fcopy n 8.0 Tcl "Tcl Built-In Commands"
@@ -72,12 +72,15 @@ Only the number of bytes written to \fIoutchan\fR is reported,
 either as the return value of a synchronous \fBfcopy\fP or
 as the argument to the callback for an asynchronous \fBfcopy\fP.
 .PP
-\fBFcopy\fR obeys the encodings configured for the channels. This
+\fBFcopy\fR obeys the encodings and character translations configured
+for the channels. This
 means that the incoming characters are converted internally first
 UTF-8 and then into the encoding of the channel \fBfcopy\fR writes
 to. See the manual entry for \fBfconfigure\fR for details on the
-\fB\-encoding\fR option. No conversion is done if both channels are
-set to encoding "binary". If only the output channel is set to
+\fB\-encoding\fR and \fB\-translation\fR options. No conversion is
+done if both channels are
+set to encoding "binary" and have matching translations. If only the
+output channel is set to
 encoding "binary" the system will write the internal UTF-8
 representation of the incoming characters. If only the input channel
 is set to encoding "binary" the system will assume that the incoming
@@ -85,9 +88,19 @@ bytes are valid UTF-8 characters and convert them according to the
 output encoding. The behaviour of the system for bytes which are not
 valid UTF-8 characters is undefined in this case.
 
-.SH EXAMPLE
+.SH EXAMPLES
 .PP
-This first example shows how the callback gets
+The first example transfers the contents of one channel exactly to
+another. Note that when copying one file to another, it is better to
+use \fBfile copy\fR which also copies file metadata (e.g. the file
+access permissions) where possible.
+.DS
+fconfigure $in -translation binary
+fconfigure $out -translation binary
+\fBfcopy\fR $in $out
+.DE
+.PP
+This second example shows how the callback gets
 passed the number of bytes transferred.
 It also uses vwait to put the application into the event loop.
 Of course, this simplified example could be done without the command 
@@ -104,12 +117,11 @@ proc Cleanup {in out bytes {error {}}} {
 }
 set in [open $file1]
 set out [socket $server $port]
-fcopy $in $out -command [list Cleanup $in $out]
+\fBfcopy\fR $in $out -command [list Cleanup $in $out]
 vwait total
-
 .DE
 .PP
-The second example copies in chunks and tests for end of file
+The third example copies in chunks and tests for end of file
 in the command callback
 .DS
 proc CopyMore {in out chunk bytes {error {}}} {
@@ -120,7 +132,7 @@ proc CopyMore {in out chunk bytes {error {}}} {
 	close $in
 	close $out
     } else {
-	fcopy $in $out -command [list CopyMore $in $out $chunk] \\
+	\fBfcopy\fR $in $out -command [list CopyMore $in $out $chunk] \\
 	    -size $chunk
     }
 }
@@ -128,13 +140,12 @@ set in [open $file1]
 set out [socket $server $port]
 set chunk 1024
 set total 0
-fcopy $in $out -command [list CopyMore $in $out $chunk] -size $chunk
+\fBfcopy\fR $in $out -command [list CopyMore $in $out $chunk] -size $chunk
 vwait done
-
 .DE
 
 .SH "SEE ALSO"
-eof(n), fblocked(n), fconfigure(n)
+eof(n), fblocked(n), fconfigure(n), file(n)
 
 .SH KEYWORDS
 blocking, channel, end of line, end of file, nonblocking, read, translation