* Merged changes from 8.1.0 branch

1 files changed, 53 insertions, 11 deletions

diff --git a/doc/Encoding.3 b/doc/Encoding.3
index e9329dd..8d1262b 100644
--- a/doc/Encoding.3
+++ b/doc/Encoding.3
@@ -4,17 +4,18 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Encoding.3,v 1.2 1999/04/16 00:46:31 stanton Exp $
+'\" RCS: @(#) $Id: Encoding.3,v 1.3 1999/04/30 22:45:00 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetDefaultEncodingDir, Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings.
-
-
-
-
+Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_ExternalToUtfDString,
+Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal,
+Tcl_WinTCharToUtf, Tcl_WinUtfToTChar,
+Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNames,
+Tcl_CreateEncoding, Tcl_GetDefaultEncodingDir,
+Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings.
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -40,6 +41,12 @@ int
 	dstCharsPtr\fR)
 .sp
 char *
+\fBTcl_WinTCharToUtf\fR(\fItsrc, srcLen, dstPtr\fR)
+.sp
+TCHAR *
+\fBTcl_WinUtfToTChar\fR(\fIsrc, srcLen, dstPtr\fR)
+.sp
+char *
 \fBTcl_GetEncodingName\fR(\fIencoding\fR)
 .sp
 int
@@ -50,7 +57,6 @@ void
 .sp
 Tcl_Encoding
 \fBTcl_CreateEncoding\fR(\fItypePtr\fR)
-
 .sp
 char *
 \fBTcl_GetDefaultEncodingDir\fR(\fIvoid\fR)
@@ -72,10 +78,12 @@ NULL, the current system encoding is used.
 .AP "CONST char" *src in
 For the \fBTcl_ExternalToUtf\fR functions, an array of bytes in the
 specified encoding that are to be converted to UTF-8.  For the
-\fBTcl_UtfToExternal\fR functions, an array of UTF-8 characters to be
-converted to the specified encoding.  
+\fBTcl_UtfToExternal\fR and \fBTcl_WinUtfToTChar\fR functions, an array of
+UTF-8 characters to be converted to the specified encoding.  
+.AP "CONST TCHAR" *tsrc in
+An array of Windows TCHAR characters to convert to UTF-8.
 .AP int srcLen in 
-Length of \fIsrc\fR in bytes.  If the length is negative, the 
+Length of \fIsrc\fR or \fItsrc\fR in bytes.  If the length is negative, the 
 encoding-specific length of the string is used.
 .AP Tcl_DString *dstPtr out
 Pointer to an uninitialized or free \fBTcl_DString\fR in which the converted
@@ -223,7 +231,41 @@ is filled with the corresponding number of bytes that were stored in
 \fIdst\fR.  The return values are the same as the return values for
 \fBTcl_ExternalToUtf\fR.
 .PP
-\fBTcl_GetEncodingName\fR is roughly the inverse of \fBTk_GetEncoding\fR.
+\fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR are
+Windows-only convenience
+functions for converting between UTF-8 and Windows strings.  On Windows 95
+(as with the Macintosh and Unix operating systems),
+all strings exchanged between Tcl and the operating system are "char"
+based.  On Windows NT, some strings exchanged between Tcl and the
+operating system are "char" oriented while others are in Unicode.  By
+convention, in Windows a TCHAR is a character in the ANSI code page
+on Windows 95 and a Unicode character on Windows NT.
+.PP
+If you planned to use the same "char" based interfaces on both Windows
+95 and Windows NT, you could use \fBTcl_UtfToExternal\fR and
+\fBTcl_ExternalToUtf\fR (or their \fBTcl_DString\fR equivalents) with an
+encoding of NULL (the current system encoding).  On the other hand,
+if you planned to use the Unicode interface when running on Windows NT
+and the "char" interfaces when running on Windows 95, you would have
+to perform the following type of test over and over in your program
+(as represented in psuedo-code):
+.CS
+if (running NT) {
+    encoding <- Tcl_GetEncoding("unicode");
+    nativeBuffer <- Tcl_UtfToExternal(encoding, utfBuffer);
+    Tcl_FreeEncoding(encoding);
+} else {
+    nativeBuffer <- Tcl_UtfToExternal(NULL, utfBuffer);
+.CE
+\fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR automatically
+handle this test and use the proper encoding based on the current
+operating system.  \fBTcl_WinUtfToTChar\fR returns a pointer to
+a TCHAR string, and \fBTcl_WinTCharToUtf\fR expects a TCHAR string
+pointer as the \fIsrc\fR string.  Otherwise, these functions
+behave identically to \fBTcl_UtfToExternalDString\fR and
+\fBTcl_ExternalToUtfDString\fR.
+.PP
+\fBTcl_GetEncodingName\fR is roughly the inverse of \fBTcl_GetEncoding\fR.
 Given an \fIencoding\fR, the return value is the \fIname\fR argument that
 was used to create the encoding.  The string returned by 
 \fBTcl_GetEncodingName\fR is only guaranteed to persist until the