summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--ChangeLog5
-rw-r--r--doc/Encoding.336
-rw-r--r--doc/encoding.n20
3 files changed, 27 insertions, 34 deletions
diff --git a/ChangeLog b/ChangeLog
index 694d93a..68ca4db 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2006-02-08 Donal K. Fellows <dkf@users.sf.net>
+
+ * doc/Encoding.3, doc/encoding.n: Updates due to review at request of
+ Don Porter. Mostly minor changes.
+
2006-02-08 Don Porter <dgp@users.sourceforge.net>
TIP#258 IMPLEMENTATION
diff --git a/doc/Encoding.3 b/doc/Encoding.3
index efdc8ca..9b3473d 100644
--- a/doc/Encoding.3
+++ b/doc/Encoding.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: Encoding.3,v 1.21 2006/02/08 21:41:27 dgp Exp $
+'\" RCS: @(#) $Id: Encoding.3,v 1.22 2006/02/08 22:27:16 dkf Exp $
'\"
.so man.macros
.TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures"
@@ -54,7 +54,7 @@ int
.sp
.VS 8.5
const char *
-\fBTcl_GetEncodingNameFromEnvironment\fR(\fIbufPtr\fR)in
+\fBTcl_GetEncodingNameFromEnvironment\fR(\fIbufPtr\fR)
.VE 8.5
.sp
void
@@ -76,7 +76,6 @@ const char *
.sp
void
\fBTcl_SetDefaultEncodingDir\fR(\fIpath\fR)
-
.SH ARGUMENTS
.AS Tcl_EncodingState *dstWrotePtr in/out
.AP Tcl_Interp *interp in
@@ -206,22 +205,17 @@ anywhere (i.e., it has been freed as many times as it has been gotten)
and delete it from the database.
.PP
.VS 8.5
-\fBTcl_GetEncodingFromObj\fR treats the string representation of \fIobjPtr\fR
-as an encoding name, and finds an encoding with that name, just as
-\fBTcl_GetEncoding\fR does. When an encoding is found, its \fBTcl_Encoding\fB
-token is written to the storage pointed to by \fIencodingPtr\fR, and the value
-\fBTCL_OK\fR is returned. In addition, a copy of the \fBTcl_Encoding\fR is
-kept as the internal representation of \fIobjPtr\fR. If no such encoding is
-found, the value \fBTCL_ERROR\fR is returned, and no writing to
-\fI*encodingPtr\fR takes place.
-.PP
-The reference count of the \fBTcl_Encoding\fR token may be incremented twice,
-once for the reference written to \fI*encodingPtr\fR and once for the
-reference stored in \fIobjPtr\fR, if a reference is not already in place
-there. The caller should call \fBTcl_FreeEncoding\fR on \fI*encodingPtr\fR
-when the token will no longer be used. The usual mechanisms for freeing the
-internal representation of a \fBTcl_Obj\fR will take care of calling
-\fBTcl_FreeEncoding\fR on that reference at the appropriate time.
+\fBTcl_GetEncodingFromObj\fR treats the string representation of
+\fIobjPtr\fR as an encoding name, and finds an encoding with that
+name, just as \fBTcl_GetEncoding\fR does. When an encoding is found,
+it is cached within the \fBobjPtr\fR valuefor future reference, the
+\fBTcl_Encoding\fR token is written to the storage pointed to by
+\fIencodingPtr\fR, and the value \fBTCL_OK\fR is returned. If no such
+encoding is found, the value \fBTCL_ERROR\fR is returned, and no
+writing to \fB*\fR\fIencodingPtr\fR takes place. Just as with
+\fBTcl_GetEncoding\fR, the caller should call \fBTcl_FreeEncoding\fR
+on the resulting encoding token when that token will no longer be
+used.
.VE 8.5
.PP
\fBTcl_ExternalToUtfDString\fR converts a source buffer \fIsrc\fR from the
@@ -466,7 +460,6 @@ list. Since Tcl searches \fIsearchPath\fR for encoding data files in
list order, these routines establish the ``default'' directory in which
to find encoding data files.
.VE 8.5
-
.SH "ENCODING FILES"
Space would prohibit precompiling into Tcl every possible encoding
algorithm, so many encodings are stored on disk as dynamically-loadable
@@ -601,6 +594,3 @@ for its script library. If the encoding file exists, but is
malformed, an error message will be left in \fIinterp\fR.
.SH KEYWORDS
utf, encoding, convert
-
-
-
diff --git a/doc/encoding.n b/doc/encoding.n
index 69d6d21..a5563b6 100644
--- a/doc/encoding.n
+++ b/doc/encoding.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: encoding.n,v 1.7 2006/02/08 21:41:27 dgp Exp $
+'\" RCS: @(#) $Id: encoding.n,v 1.8 2006/02/08 22:27:16 dkf Exp $
'\"
.so man.macros
.TH encoding n "8.1" Tcl "Tcl Built-In Commands"
@@ -44,16 +44,14 @@ system encoding is used.
\fBencoding dirs\fR ?\fIdirectoryList\fR?
.VS 8.5
Tcl can load encoding data files from the file system that describe
-additional encodings for it to work with. This command
-sets the search path for \fB*.enc\fR encoding data files to
-the list of directories \fIdirectoryList\fR. If
-\fIdirectoryList\fR is omitted then the command returns the
-current list of directories that make up the search path.
-If \fIdirectoryList\fR is present, but is not a valid Tcl
-list, an error is raised. Any elements in \fIdirectoryList\fR
-that are not in fact readable directories in the filesystem are ignored
-without raising an error when searches for encoding data files
-take place.
+additional encodings for it to work with. This command sets the search
+path for \fB*.enc\fR encoding data files to the list of directories
+\fIdirectoryList\fR. If \fIdirectoryList\fR is omitted then the
+command returns the current list of directories that make up the
+search path. It is an error for \fIdirectoryList\fR to not be a valid
+list. If, when a search for an encoding data file is happening, an
+element in \fIdirectoryList\fR does not refer to a readable,
+searchable directory, that element is ignored.
.VE 8.5
.TP
\fBencoding names\fR