summaryrefslogtreecommitdiffstats
path: root/doc/Encoding.3
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2008-06-29 22:28:20 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2008-06-29 22:28:20 (GMT)
commit131a59f68c8b1673c1fcd9b035bb7791eea72bc9 (patch)
treecdb9d2219449fc94b2623bab245f0b0cdcf45c52 /doc/Encoding.3
parent7b7bac281c6cba5b97c0962a4032cc39dcc6308f (diff)
downloadtcl-131a59f68c8b1673c1fcd9b035bb7791eea72bc9.zip
tcl-131a59f68c8b1673c1fcd9b035bb7791eea72bc9.tar.gz
tcl-131a59f68c8b1673c1fcd9b035bb7791eea72bc9.tar.bz2
Prepare Tcl's docs for life as 8.6 (remove out of date change bars, fix
typedefs, add a few missing bits)
Diffstat (limited to 'doc/Encoding.3')
-rw-r--r--doc/Encoding.340
1 files changed, 10 insertions, 30 deletions
diff --git a/doc/Encoding.3 b/doc/Encoding.3
index 51ef92f..a824b2f 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.29 2007/12/13 15:22:31 dgp Exp $
+'\" RCS: @(#) $Id: Encoding.3,v 1.30 2008/06/29 22:28:24 dkf Exp $
'\"
.so man.macros
.TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures"
@@ -21,10 +21,8 @@ Tcl_Encoding
void
\fBTcl_FreeEncoding\fR(\fIencoding\fR)
.sp
-.VS 8.5
int
\fBTcl_GetEncodingFromObj\fR(\fIinterp, objPtr, encodingPtr\fR)
-.VE 8.5
.sp
char *
\fBTcl_ExternalToUtfDString\fR(\fIencoding, src, srcLen, dstPtr\fR)
@@ -52,10 +50,8 @@ const char *
int
\fBTcl_SetSystemEncoding\fR(\fIinterp, name\fR)
.sp
-.VS 8.5
const char *
\fBTcl_GetEncodingNameFromEnvironment\fR(\fIbufPtr\fR)
-.VE 8.5
.sp
void
\fBTcl_GetEncodingNames\fR(\fIinterp\fR)
@@ -63,13 +59,11 @@ void
Tcl_Encoding
\fBTcl_CreateEncoding\fR(\fItypePtr\fR)
.sp
-.VS 8.5
Tcl_Obj *
\fBTcl_GetEncodingSearchPath\fR()
.sp
int
\fBTcl_SetEncodingSearchPath\fR(\fIsearchPath\fR)
-.VE 8.5
.sp
const char *
\fBTcl_GetDefaultEncodingDir\fR(\fIvoid\fR)
@@ -87,13 +81,9 @@ Name of encoding to load.
The encoding to query, free, or use for converting text. If \fIencoding\fR is
NULL, the current system encoding is used.
.AP Tcl_Obj *objPtr in
-.VS 8.5
Name of encoding to get token for.
-.VE 8.5
.AP Tcl_Encoding *encodingPtr out
-.VS 8.5
Points to storage where encoding token is to be written.
-.VE 8.5
.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
@@ -147,15 +137,11 @@ buffer as a result of the conversion. May be NULL.
Filled with the number of characters that correspond to the number of bytes
stored in the output buffer. May be NULL.
.AP Tcl_DString *bufPtr out
-.VS 8.5
Storage for the prescribed system encoding name.
-.VE 8.5
.AP "const Tcl_EncodingType" *typePtr in
Structure that defines a new type of encoding.
.AP Tcl_Obj *searchPath in
-.VS 8.5
List of filesystem directories in which to search for encoding data files.
-.VE 8.5
.AP "const char" *path in
A path to the location of the encoding file.
.BE
@@ -204,7 +190,6 @@ anywhere (i.e., it has been freed as many times as it has been gotten)
\fBTcl_FreeEncoding\fR will release all storage the encoding was using
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,
@@ -216,7 +201,6 @@ 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
specified \fIencoding\fR into UTF-8. The converted bytes are stored in
@@ -331,14 +315,12 @@ procedure increments the reference count of the new system encoding,
decrements the reference count of the old system encoding, and returns
\fBTCL_OK\fR.
.PP
-.VS 8.5
\fBTcl_GetEncodingNameFromEnvironment\fR provides a means for the Tcl
library to report the encoding name it believes to be the correct one
to use as the system encoding, based on system calls and examination of
the environment suitable for the platform. It accepts \fIbufPtr\fR,
a pointer to an uninitialized or freed \fBTcl_DString\fR and writes
the encoding name to it. The \fBTcl_DStringValue\fR is returned.
-.VE 8.5
.PP
\fBTcl_GetEncodingNames\fR sets the \fIinterp\fR result to a list
consisting of the names of all the encodings that are currently defined
@@ -366,13 +348,13 @@ convert between this encoding and UTF-8. It is defined as follows:
.PP
.CS
typedef struct Tcl_EncodingType {
- const char *\fIencodingName\fR;
- Tcl_EncodingConvertProc *\fItoUtfProc\fR;
- Tcl_EncodingConvertProc *\fIfromUtfProc\fR;
- Tcl_EncodingFreeProc *\fIfreeProc\fR;
- ClientData \fIclientData\fR;
- int \fInullSize\fR;
-} Tcl_EncodingType;
+ const char *\fIencodingName\fR;
+ Tcl_EncodingConvertProc *\fItoUtfProc\fR;
+ Tcl_EncodingConvertProc *\fIfromUtfProc\fR;
+ Tcl_EncodingFreeProc *\fIfreeProc\fR;
+ ClientData \fIclientData\fR;
+ int \fInullSize\fR;
+} \fBTcl_EncodingType\fR;
.CE
.PP
The \fIencodingName\fR provides a string name for the encoding, by
@@ -400,7 +382,7 @@ The callback procedures \fItoUtfProc\fR and \fIfromUtfProc\fR should match the
type \fBTcl_EncodingConvertProc\fR:
.PP
.CS
-typedef int Tcl_EncodingConvertProc(
+typedef int \fBTcl_EncodingConvertProc\fR(
ClientData \fIclientData\fR,
const char *\fIsrc\fR,
int \fIsrcLen\fR,
@@ -431,7 +413,7 @@ procedure will be a non-NULL location.
The callback procedure \fIfreeProc\fR, if non-NULL, should match the type
\fBTcl_EncodingFreeProc\fR:
.CS
-typedef void Tcl_EncodingFreeProc(
+typedef void \fBTcl_EncodingFreeProc\fR(
ClientData \fIclientData\fR);
.CE
.PP
@@ -439,7 +421,6 @@ This \fIfreeProc\fR function is called when the encoding is deleted. The
\fIclientData\fR parameter is the same as the \fIclientData\fR field
specified to \fBTcl_CreateEncoding\fR when the encoding was created.
.PP
-.VS 8.5
\fBTcl_GetEncodingSearchPath\fR and \fBTcl_SetEncodingSearchPath\fR
are called to access and set the list of filesystem directories searched
for encoding data files.
@@ -467,7 +448,6 @@ list. Since Tcl searches \fIsearchPath\fR for encoding data files in
list order, these routines establish the
.QW 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