merged tcl 8.1 branch back into the main trunk

1 files changed, 108 insertions, 86 deletions

diff --git a/doc/fconfigure.n b/doc/fconfigure.n
index 720b206..e2479e8a 100644
--- a/doc/fconfigure.n
+++ b/doc/fconfigure.n
@@ -4,10 +4,10 @@
 '\" 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.2 1998/09/14 18:39:52 stanton Exp $
+'\" RCS: @(#) $Id: fconfigure.n,v 1.3 1999/04/16 00:46:34 stanton Exp $
 '\"
 .so man.macros
-.TH fconfigure n 7.5 Tcl "Tcl Built-In Commands"
+.TH fconfigure n 8.1 Tcl "Tcl Built-In Commands"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -51,122 +51,143 @@ 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.
+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.
 .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 ten and one million, allowing
 buffers of ten to one million bytes in size.
+.VS 8.1 br
+.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.
+.PP
+The default encoding for newly opened channels is the same platform- and
+locale-dependent system encoding used for interfacing with the operating
+system.  
+.RE
+.VE
 .TP
 \fB\-eofchar\fR \fIchar\fR
 .TP
 \fB\-eofchar\fR \fB{\fIinChar 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 both reading and writing.
-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.
+.
+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 both reading
+and writing.  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.
 .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\fP and \fBread\fP)
-the Tcl I/O system automatically translates the external end-of-line
-representation into newline characters.
-Upon output (i.e., with \fBputs\fP),
-the I/O system translates newlines to the external
-end-of-line representation.
-The default translation mode, \fBauto\fP, handles all the common
-cases automatically, but the \fB\-translation\fR option provides
-explicit control over the end of line translations.
+\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\fP
+and \fBread\fP) the Tcl I/O system automatically translates the external
+end-of-line representation into newline characters.  Upon output (i.e.,
+with \fBputs\fP), the I/O system translates newlines to the external
+end-of-line representation.  The default translation mode, \fBauto\fP,
+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:
+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\fP),
-carriage return (\fBcr\fP), or carriage return followed by a newline (\fBcrlf\fP)
-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, for the
+.
+As the input translation mode, \fBauto\fR treats any of newline
+(\fBlf\fP), carriage return (\fBcr\fP), or carriage return followed by a
+newline (\fBcrlf\fP) 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, for the
 Macintosh platform it chooses \fBcr\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.
+Windows it chooses \fBcrlf\fR.  The default setting for
+\fB\-translation\fR is \fBauto\fR for both input and output.
+.VS 8.1 br
 .TP
-\fBbinary\fR
+\fBbinary\fR 
+.
 No end-of-line translations are performed.  This is nearly identical to
 \fBlf\fP mode, except that in addition \fBbinary\fP mode also sets the
-end of file character to the empty string, which disables it.
-See the description of
-\fB\-eofchar\fP for more information.
+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.
+.VE
 .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\fP mode converts carriage returns
-to newline characters.
-As the output translation mode, \fBcr\fP mode
-translates newline characters to carriage returns.
-This mode is typically used on Macintosh platforms.
+.
+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\fP mode converts carriage returns to newline characters.  As the
+output translation mode, \fBcr\fP mode translates newline characters to
+carriage returns.  This mode is typically used on Macintosh platforms.
 .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\fP mode converts
-carriage-return-linefeed sequences
-to newline characters.
-As the output translation mode, \fBcrlf\fP mode
-translates newline characters to
-carriage-return-linefeed sequences.
-This mode is typically used on Windows platforms and for network
-connections.
+.
+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\fP mode converts carriage-return-linefeed
+sequences to newline characters.  As the output translation mode,
+\fBcrlf\fP 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.
+.
+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
 
@@ -175,4 +196,5 @@ close(n), flush(n), gets(n), puts(n), read(n), socket(n)
 
 .SH KEYWORDS
 blocking, buffering, carriage return, end of line, flushing, linemode,
-newline, nonblocking, platform, translation
+newline, nonblocking, platform, translation, encoding, filter, byte array,
+binary