summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--doc/AddErrInfo.33
-rw-r--r--doc/AppInit.34
-rw-r--r--doc/AssocData.34
-rw-r--r--doc/Async.34
-rw-r--r--doc/CallDel.314
-rw-r--r--doc/CrtCommand.36
-rw-r--r--doc/CrtFileHdlr.37
-rw-r--r--doc/CrtObjCmd.310
-rw-r--r--doc/CrtTimerHdlr.36
-rw-r--r--doc/CrtTrace.38
-rw-r--r--doc/DoWhenIdle.36
-rw-r--r--doc/Encoding.34
-rw-r--r--doc/Exit.34
-rw-r--r--doc/FileSystem.34
-rw-r--r--doc/GetStdChan.34
-rw-r--r--doc/GetTime.32
-rw-r--r--doc/Hash.310
-rw-r--r--doc/Notifier.316
-rw-r--r--doc/Object.312
-rw-r--r--doc/Preserve.34
-rw-r--r--doc/SetResult.34
-rw-r--r--doc/SplitList.35
-rw-r--r--doc/SplitPath.35
-rw-r--r--doc/StaticPkg.34
-rw-r--r--doc/StringObj.314
-rw-r--r--doc/Tcl.n10
-rw-r--r--doc/TraceCmd.34
-rw-r--r--doc/TraceVar.34
-rw-r--r--doc/WrongNumArgs.312
-rw-r--r--doc/after.n17
-rw-r--r--doc/append.n9
-rw-r--r--doc/chan.n4
-rw-r--r--doc/clock.n2
-rw-r--r--doc/dict.n34
-rw-r--r--doc/encoding.n4
-rw-r--r--doc/error.n5
-rw-r--r--doc/eval.n6
-rw-r--r--doc/exec.n16
-rw-r--r--doc/expr.n29
-rw-r--r--doc/file.n20
-rw-r--r--doc/fileevent.n9
-rw-r--r--doc/glob.n11
42 files changed, 293 insertions, 67 deletions
diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3
index 161de0c..ae535d7 100644
--- a/doc/AddErrInfo.3
+++ b/doc/AddErrInfo.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: AddErrInfo.3,v 1.21 2008/06/29 22:28:21 dkf Exp $
+'\" RCS: @(#) $Id: AddErrInfo.3,v 1.22 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_AddErrorInfo 3 8.5 Tcl "Tcl Library Procedures"
@@ -140,6 +140,7 @@ if ((objc % 2) == 0) { /* explicit result argument */
}
return Tcl_SetReturnOptions(interp, Tcl_NewListObj(objc-1, objv+1));
.CE
+.PP
(It is not really implemented that way. Internal access
privileges allow for a more efficient alternative that meshes
better with the bytecode compiler.)
diff --git a/doc/AppInit.3 b/doc/AppInit.3
index 99e1555..15d5635 100644
--- a/doc/AppInit.3
+++ b/doc/AppInit.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: AppInit.3,v 1.9 2007/12/13 15:22:30 dgp Exp $
+'\" RCS: @(#) $Id: AppInit.3,v 1.10 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_AppInit 3 7.0 Tcl "Tcl Library Procedures"
@@ -57,9 +57,11 @@ for the interpreter's result; otherwise the result is ignored.
.PP
In addition to \fBTcl_AppInit\fR, your application should also contain
a procedure \fBmain\fR that calls \fBTcl_Main\fR as follows:
+.PP
.CS
Tcl_Main(argc, argv, Tcl_AppInit);
.CE
+.PP
The third argument to \fBTcl_Main\fR gives the address of the
application-specific initialization procedure to invoke.
This means that you do not have to use the name \fBTcl_AppInit\fR
diff --git a/doc/AssocData.3 b/doc/AssocData.3
index 2b85137..6366cdf 100644
--- a/doc/AssocData.3
+++ b/doc/AssocData.3
@@ -5,7 +5,7 @@
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\"
-'\" RCS: @(#) $Id: AssocData.3,v 1.8 2008/06/29 22:28:23 dkf Exp $
+'\" RCS: @(#) $Id: AssocData.3,v 1.9 2008/10/15 10:43:37 dkf Exp $
.so man.macros
.TH Tcl_SetAssocData 3 7.5 Tcl "Tcl Library Procedures"
.BS
@@ -63,11 +63,13 @@ If the \fIdeleteProc\fR argument is non-NULL it specifies the address of a
procedure to invoke if the interpreter is deleted before the association
is deleted. \fIDeleteProc\fR should have arguments and result that match
the type \fBTcl_InterpDeleteProc\fR:
+.PP
.CS
typedef void \fBTcl_InterpDeleteProc\fR(
ClientData \fIclientData\fR,
Tcl_Interp *\fIinterp\fR);
.CE
+.PP
When \fIdeleteProc\fR is invoked the \fIclientData\fR and \fIinterp\fR
arguments will be the same as the corresponding arguments passed to
\fBTcl_SetAssocData\fR.
diff --git a/doc/Async.3 b/doc/Async.3
index 346a26c..dba4400 100644
--- a/doc/Async.3
+++ b/doc/Async.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: Async.3,v 1.13 2008/06/29 22:28:23 dkf Exp $
+'\" RCS: @(#) $Id: Async.3,v 1.14 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_AsyncCreate 3 7.0 Tcl "Tcl Library Procedures"
@@ -83,12 +83,14 @@ the world is in a safe state, and \fIproc\fR can then carry out
the actions associated with the asynchronous event.
\fIProc\fR should have arguments and result that match the
type \fBTcl_AsyncProc\fR:
+.PP
.CS
typedef int \fBTcl_AsyncProc\fR(
ClientData \fIclientData\fR,
Tcl_Interp *\fIinterp\fR,
int \fIcode\fR);
.CE
+.PP
The \fIclientData\fR will be the same as the \fIclientData\fR
argument passed to \fBTcl_AsyncCreate\fR when the handler was
created.
diff --git a/doc/CallDel.3 b/doc/CallDel.3
index 9c225e0..0dbed27 100644
--- a/doc/CallDel.3
+++ b/doc/CallDel.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: CallDel.3,v 1.7 2008/06/29 22:28:23 dkf Exp $
+'\" RCS: @(#) $Id: CallDel.3,v 1.8 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_CallWhenDeleted 3 7.0 Tcl "Tcl Library Procedures"
@@ -28,7 +28,6 @@ Procedure to call when \fIinterp\fR is deleted.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIproc\fR.
.BE
-
.SH DESCRIPTION
.PP
\fBTcl_CallWhenDeleted\fR arranges for \fIproc\fR to be called by
@@ -38,11 +37,13 @@ is deleted, but the interpreter will still be valid at the
time of the call.
\fIProc\fR should have arguments and result that match the
type \fBTcl_InterpDeleteProc\fR:
+.PP
.CS
typedef void \fBTcl_InterpDeleteProc\fR(
ClientData \fIclientData\fR,
Tcl_Interp *\fIinterp\fR);
.CE
+.PP
The \fIclientData\fR and \fIinterp\fR parameters are
copies of the \fIclientData\fR and \fIinterp\fR arguments given
to \fBTcl_CallWhenDeleted\fR.
@@ -58,6 +59,11 @@ deleted.
If there is no deletion callback that matches \fIinterp\fR,
\fIproc\fR, and \fIclientData\fR then the call to
\fBTcl_DontCallWhenDeleted\fR has no effect.
-
+.PP
+Note that if the callback is being used to delete a resource that \fImust\fR
+be released on exit, \fBTcl_CreateExitHandler\fR should be used to ensure that
+a callback is received even if the application terminates without deleting the interpreter.
+.SH "SEE ALSO"
+Tcl_CreateExitHandler(3), Tcl_CreateThreadExitHandler(3)
.SH KEYWORDS
-callback, delete, interpreter
+callback, cleanup, delete, interpreter
diff --git a/doc/CrtCommand.3 b/doc/CrtCommand.3
index d9aab23..02081bf 100644
--- a/doc/CrtCommand.3
+++ b/doc/CrtCommand.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: CrtCommand.3,v 1.15 2008/06/29 22:28:23 dkf Exp $
+'\" RCS: @(#) $Id: CrtCommand.3,v 1.16 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_CreateCommand 3 "" Tcl "Tcl Library Procedures"
@@ -76,6 +76,7 @@ the process of being deleted, then it does not create a new command
and it returns NULL.
\fIProc\fR should have arguments and result that match the type
\fBTcl_CmdProc\fR:
+.PP
.CS
typedef int \fBTcl_CmdProc\fR(
ClientData \fIclientData\fR,
@@ -83,6 +84,7 @@ typedef int \fBTcl_CmdProc\fR(
int \fIargc\fR,
const char *\fIargv\fR[]);
.CE
+.PP
When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR
parameters will be copies of the \fIclientData\fR and \fIinterp\fR
arguments given to \fBTcl_CreateCommand\fR.
@@ -130,10 +132,12 @@ or by replacing \fIcmdName\fR in another call to \fBTcl_CreateCommand\fR.
application an opportunity to release any structures associated
with the command. \fIDeleteProc\fR should have arguments and
result that match the type \fBTcl_CmdDeleteProc\fR:
+.PP
.CS
typedef void \fBTcl_CmdDeleteProc\fR(
ClientData \fIclientData\fR);
.CE
+.PP
The \fIclientData\fR argument will be the same as the \fIclientData\fR
argument passed to \fBTcl_CreateCommand\fR.
.SH "SEE ALSO"
diff --git a/doc/CrtFileHdlr.3 b/doc/CrtFileHdlr.3
index 4b352ba..00a6a48 100644
--- a/doc/CrtFileHdlr.3
+++ b/doc/CrtFileHdlr.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: CrtFileHdlr.3,v 1.9 2008/06/29 22:28:23 dkf Exp $
+'\" RCS: @(#) $Id: CrtFileHdlr.3,v 1.10 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_CreateFileHandler 3 8.0 Tcl "Tcl Library Procedures"
@@ -50,11 +50,13 @@ as \fBvwait\fR.
.PP
\fIProc\fR should have arguments and result that match the
type \fBTcl_FileProc\fR:
+.PP
.CS
typedef void \fBTcl_FileProc\fR(
ClientData \fIclientData\fR,
int \fImask\fR);
.CE
+.PP
The \fIclientData\fR parameter to \fIproc\fR is a copy
of the \fIclientData\fR
argument given to \fBTcl_CreateFileHandler\fR when the callback
@@ -65,7 +67,6 @@ of the requested conditions actually exists for the file; it
will contain a subset of the bits in the \fImask\fR argument
to \fBTcl_CreateFileHandler\fR.
.PP
-.PP
There may exist only one handler for a given file at a given time.
If \fBTcl_CreateFileHandler\fR is called when a handler already
exists for \fIfd\fR, then the new callback replaces the information
@@ -86,5 +87,7 @@ blocking or nonblocking mode as required.
.PP
Note that these interfaces are only supported by the Unix
implementation of the Tcl notifier.
+.SH "SEE ALSO"
+fileevent(n), Tcl_CreateTimerHandler(3), Tcl_DoWhenIdle(3)
.SH KEYWORDS
callback, file, handler
diff --git a/doc/CrtObjCmd.3 b/doc/CrtObjCmd.3
index 2e30de9..43a855b 100644
--- a/doc/CrtObjCmd.3
+++ b/doc/CrtObjCmd.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: CrtObjCmd.3,v 1.18 2008/06/29 22:28:24 dkf Exp $
+'\" RCS: @(#) $Id: CrtObjCmd.3,v 1.19 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures"
@@ -90,6 +90,7 @@ the process of being deleted, then it does not create a new command
and it returns NULL.
\fIproc\fR should have arguments and result that match the type
\fBTcl_ObjCmdProc\fR:
+.PP
.CS
typedef int \fBTcl_ObjCmdProc\fR(
ClientData \fIclientData\fR,
@@ -97,6 +98,7 @@ typedef int \fBTcl_ObjCmdProc\fR(
int \fIobjc\fR,
Tcl_Obj *const \fIobjv\fR[]);
.CE
+.PP
When \fIproc\fR is invoked, the \fIclientData\fR and \fIinterp\fR parameters
will be copies of the \fIclientData\fR and \fIinterp\fR arguments given to
\fBTcl_CreateObjCommand\fR. Typically, \fIclientData\fR points to an
@@ -161,10 +163,12 @@ or by replacing \fIname\fR in another call to \fBTcl_CreateObjCommand\fR.
application an opportunity to release any structures associated
with the command. \fIDeleteProc\fR should have arguments and
result that match the type \fBTcl_CmdDeleteProc\fR:
+.PP
.CS
typedef void \fBTcl_CmdDeleteProc\fR(
ClientData \fIclientData\fR);
.CE
+.PP
The \fIclientData\fR argument will be the same as the \fIclientData\fR
argument passed to \fBTcl_CreateObjCommand\fR.
.PP
@@ -199,6 +203,7 @@ Otherwise it places information about the command
in the \fBTcl_CmdInfo\fR structure
pointed to by \fIinfoPtr\fR and returns 1.
A \fBTcl_CmdInfo\fR structure has the following fields:
+.PP
.CS
typedef struct Tcl_CmdInfo {
int \fIisNativeObjectProc\fR;
@@ -211,6 +216,7 @@ typedef struct Tcl_CmdInfo {
Tcl_Namespace *\fInamespacePtr\fR;
} \fBTcl_CmdInfo\fR;
.CE
+.PP
The \fIisNativeObjectProc\fR field has the value 1
if \fBTcl_CreateObjCommand\fR was called to register the command;
it is 0 if only \fBTcl_CreateCommand\fR was called.
@@ -293,6 +299,6 @@ specified by the name in a \fBTcl_Obj\fR.
The command name is resolved relative to the current namespace.
Returns NULL if the command is not found.
.SH "SEE ALSO"
-Tcl_CreateCommand, Tcl_ResetResult, Tcl_SetObjResult
+Tcl_CreateCommand(3), Tcl_ResetResult(3), Tcl_SetObjResult(3)
.SH KEYWORDS
bind, command, create, delete, namespace, object
diff --git a/doc/CrtTimerHdlr.3 b/doc/CrtTimerHdlr.3
index 7e0368f..841b465 100644
--- a/doc/CrtTimerHdlr.3
+++ b/doc/CrtTimerHdlr.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: CrtTimerHdlr.3,v 1.7 2008/06/29 22:28:24 dkf Exp $
+'\" RCS: @(#) $Id: CrtTimerHdlr.3,v 1.8 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_CreateTimerHandler 3 7.5 Tcl "Tcl Library Procedures"
@@ -50,10 +50,12 @@ are other pending events to process before the call to
.PP
\fIProc\fR should have arguments and return value that match
the type \fBTcl_TimerProc\fR:
+.PP
.CS
typedef void \fBTcl_TimerProc\fR(
ClientData \fIclientData\fR);
.CE
+.PP
The \fIclientData\fR parameter to \fIproc\fR is a
copy of the \fIclientData\fR argument given to
\fBTcl_CreateTimerHandler\fR when the callback
@@ -70,5 +72,7 @@ has been invoked then \fBTcl_DeleteTimerHandler\fR does nothing.
The tokens returned by \fBTcl_CreateTimerHandler\fR never have
a value of NULL, so if NULL is passed to \fBTcl_DeleteTimerHandler\fR
then the procedure does nothing.
+.SH "SEE ALSO"
+after(n), Tcl_CreateFileHandler(3), Tcl_DoWhenIdle(3)
.SH KEYWORDS
callback, clock, handler, timer
diff --git a/doc/CrtTrace.3 b/doc/CrtTrace.3
index 1248619..0c02776 100644
--- a/doc/CrtTrace.3
+++ b/doc/CrtTrace.3
@@ -6,7 +6,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: CrtTrace.3,v 1.15 2008/06/29 22:28:24 dkf Exp $
+'\" RCS: @(#) $Id: CrtTrace.3,v 1.16 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_CreateTrace 3 "" Tcl "Tcl Library Procedures"
@@ -65,6 +65,7 @@ interpreter.
.PP
\fIobjProc\fR should have arguments and result that match the type,
\fBTcl_CmdObjTraceProc\fR:
+.PP
.CS
typedef int \fBTcl_CmdObjTraceProc\fR(
\fBClientData\fR \fIclientData\fR,
@@ -75,6 +76,7 @@ typedef int \fBTcl_CmdObjTraceProc\fR(
int \fIobjc\fR,
\fBTcl_Obj\fR *const \fIobjv\fR[]);
.CE
+.PP
The \fIclientData\fR and \fIinterp\fR parameters are copies of the
corresponding arguments given to \fBTcl_CreateTrace\fR.
\fIClientData\fR typically points to an application-specific data
@@ -141,10 +143,12 @@ When \fBTcl_DeleteTrace\fR is called, the interpreter invokes the
\fIdeleteProc\fR that was passed as a parameter to
\fBTcl_CreateObjTrace\fR. The \fIdeleteProc\fR must match the type,
\fBTcl_CmdObjTraceDeleteProc\fR:
+.PP
.CS
typedef void \fBTcl_CmdObjTraceDeleteProc\fR(
\fBClientData\fR \fIclientData\fR);
.CE
+.PP
The \fIclientData\fR parameter will be the same as the
\fIclientData\fR parameter that was originally passed to
\fBTcl_CreateObjTrace\fR.
@@ -155,6 +159,7 @@ compatibility with code that was developed for older versions of the
Tcl interpreter. It is similar to \fBTcl_CreateObjTrace\fR, except
that its \fIproc\fR parameter should have arguments and result that
match the type \fBTcl_CmdTraceProc\fR:
+.PP
.CS
typedef void \fBTcl_CmdTraceProc\fR(
ClientData \fIclientData\fR,
@@ -166,6 +171,7 @@ typedef void \fBTcl_CmdTraceProc\fR(
int \fIargc\fR,
const char *\fIargv\fR[]);
.CE
+.PP
The parameters to the \fIproc\fR callback are similar to those of the
\fIobjProc\fR callback above. The \fIcommandToken\fR is
replaced with \fIcmdProc\fR, a pointer to the (string-based) command
diff --git a/doc/DoWhenIdle.3 b/doc/DoWhenIdle.3
index b75de55..37b4cec 100644
--- a/doc/DoWhenIdle.3
+++ b/doc/DoWhenIdle.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: DoWhenIdle.3,v 1.6 2008/06/29 22:28:24 dkf Exp $
+'\" RCS: @(#) $Id: DoWhenIdle.3,v 1.7 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_DoWhenIdle 3 7.5 Tcl "Tcl Library Procedures"
@@ -42,10 +42,12 @@ use \fBTcl_DoOneEvent\fR to dispatch events.
.PP
\fIProc\fR should have arguments and result that match the
type \fBTcl_IdleProc\fR:
+.PP
.CS
typedef void \fBTcl_IdleProc\fR(
ClientData \fIclientData\fR);
.CE
+.PP
The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR
argument given to \fBTcl_DoWhenIdle\fR. Typically, \fIclientData\fR
points to a data structure containing application-specific information about
@@ -81,5 +83,7 @@ continuously. This will interact badly with certain features of Tk
that attempt to wait for all idle callbacks to complete. If you would
like for an idle callback to reschedule itself continuously, it is
better to use a timer handler with a zero timeout period.
+.SH "SEE ALSO"
+after(n), Tcl_CreateFileHandler(3), Tcl_CreateTimerHandler(3)
.SH KEYWORDS
callback, defer, idle callback
diff --git a/doc/Encoding.3 b/doc/Encoding.3
index a824b2f..5fadc44 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.30 2008/06/29 22:28:24 dkf Exp $
+'\" RCS: @(#) $Id: Encoding.3,v 1.31 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures"
@@ -282,6 +282,7 @@ and the
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 pseudo-code):
+.PP
.CS
if (running NT) {
encoding <- Tcl_GetEncoding("unicode");
@@ -291,6 +292,7 @@ if (running NT) {
nativeBuffer <- Tcl_UtfToExternal(NULL, utfBuffer);
}
.CE
+.PP
\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
diff --git a/doc/Exit.3 b/doc/Exit.3
index 61fb222..f95a9d1 100644
--- a/doc/Exit.3
+++ b/doc/Exit.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: Exit.3,v 1.8 2008/08/01 18:22:29 hobbs Exp $
+'\" RCS: @(#) $Id: Exit.3,v 1.9 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_Exit 3 8.5 Tcl "Tcl Library Procedures"
@@ -92,10 +92,12 @@ by \fBTcl_FinalizeThread\fR and \fBTcl_ExitThread\fR.
This provides a hook for cleanup operations such as flushing buffers
and freeing global memory.
\fIProc\fR should match the type \fBTcl_ExitProc\fR:
+.PP
.CS
typedef void \fBTcl_ExitProc\fR(
ClientData \fIclientData\fR);
.CE
+.PP
The \fIclientData\fR parameter to \fIproc\fR is a
copy of the \fIclientData\fR argument given to
\fBTcl_CreateExitHandler\fR or \fBTcl_CreateThreadExitHandler\fR when
diff --git a/doc/FileSystem.3 b/doc/FileSystem.3
index b3baf8f..bec5e23 100644
--- a/doc/FileSystem.3
+++ b/doc/FileSystem.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: FileSystem.3,v 1.66 2008/10/05 22:25:35 nijtmans Exp $
+'\" RCS: @(#) $Id: FileSystem.3,v 1.67 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Filesystem 3 8.4 Tcl "Tcl Library Procedures"
@@ -1583,7 +1583,7 @@ cleanup action required.
typedef void \fBTcl_FSUnloadFileProc\fR(
Tcl_LoadHandle \fIloadHandle\fR);
.CE
-.SS GETCWDPROC
+.SS GETCWDPROC
.PP
Function to process a \fBTcl_FSGetCwd\fR call. Most filesystems need not
implement this. It will usually only be called once, if \fBgetcwd\fR is
diff --git a/doc/GetStdChan.3 b/doc/GetStdChan.3
index 074d237..fb91517 100644
--- a/doc/GetStdChan.3
+++ b/doc/GetStdChan.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: GetStdChan.3,v 1.8 2007/12/13 15:22:31 dgp Exp $
+'\" RCS: @(#) $Id: GetStdChan.3,v 1.9 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_GetStdChannel 3 7.5 Tcl "Tcl Library Procedures"
@@ -55,9 +55,11 @@ set to NULL.
.PP
If a non-NULL value for \fIchannel\fR is passed to \fBTcl_SetStdChannel\fR,
then that same value should be passed to \fBTcl_RegisterChannel\fR, like so:
+.PP
.CS
Tcl_RegisterChannel(NULL, channel);
.CE
+.PP
This is a workaround for a misfeature in \fBTcl_SetStdChannel\fR that it
fails to do some reference counting housekeeping. This misfeature cannot
be corrected without contradicting the assumptions of some existing
diff --git a/doc/GetTime.3 b/doc/GetTime.3
index c3f7134..a180860 100644
--- a/doc/GetTime.3
+++ b/doc/GetTime.3
@@ -80,6 +80,7 @@ of the OS. The arguments to the function are allowed to be NULL; and
any argument which is NULL is ignored and not set.
.PP
The signatures of the handler functions are as follows:
+.PP
.CS
typedef void \fBTcl_GetTimeProc\fR(
Tcl_Time *\fItimebuf\fR,
@@ -88,6 +89,7 @@ typedef void \fBTcl_ScaleTimeProc\fR(
Tcl_Time *\fItimebuf\fR,
ClientData \fIclientData\fR);
.CE
+.PP
The \fItimebuf\fR fields contain the time to manipulate, and the
\fIclientData\fR fields contain a pointer supplied at the time the
handler functions were registered.
diff --git a/doc/Hash.3 b/doc/Hash.3
index 9ed9c1b..13bfe3b 100644
--- a/doc/Hash.3
+++ b/doc/Hash.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: Hash.3,v 1.28 2008/10/04 11:51:25 nijtmans Exp $
+'\" RCS: @(#) $Id: Hash.3,v 1.29 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_Hash 3 "" Tcl "Tcl Library Procedures"
@@ -280,31 +280,37 @@ circular dependency.
.PP
The \fIhashKeyProc\fR member contains the address of a function called to
calculate a hash value for the key.
+.PP
.CS
typedef unsigned int \fBTcl_HashKeyProc\fR(
Tcl_HashTable *\fItablePtr\fR,
void *\fIkeyPtr\fR);
.CE
+.PP
If this is NULL then \fIkeyPtr\fR is used and
\fBTCL_HASH_KEY_RANDOMIZE_HASH\fR is assumed.
.PP
The \fIcompareKeysProc\fR member contains the address of a function called to
compare two keys.
+.PP
.CS
typedef int \fBTcl_CompareHashKeysProc\fR(
void *\fIkeyPtr\fR,
Tcl_HashEntry *\fIhPtr\fR);
.CE
+.PP
If this is NULL then the \fIkeyPtr\fR pointers are compared. If the keys do
not match then the function returns 0, otherwise it returns 1.
.PP
The \fIallocEntryProc\fR member contains the address of a function called to
allocate space for an entry and initialize the key and clientData.
+.PP
.CS
typedef Tcl_HashEntry *\fBTcl_AllocHashEntryProc\fR(
Tcl_HashTable *\fItablePtr\fR,
void *\fIkeyPtr\fR);
.CE
+.PP
If this is NULL then Tcl_Alloc is used to allocate enough space for a
Tcl_HashEntry, the key pointer is assigned to key.oneWordValue and the
clientData is set to NULL. String keys and array keys use this function to
@@ -316,10 +322,12 @@ object.
.PP
The \fIfreeEntryProc\fR member contains the address of a function called to
free space for an entry.
+.PP
.CS
typedef void \fBTcl_FreeHashEntryProc\fR(
Tcl_HashEntry *\fIhPtr\fR);
.CE
+.PP
If this is NULL then Tcl_Free is used to free the space for the entry.
Tcl_Obj* keys use this function to decrement the reference count on the
object.
diff --git a/doc/Notifier.3 b/doc/Notifier.3
index 4eddc54..74aa77b 100644
--- a/doc/Notifier.3
+++ b/doc/Notifier.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: Notifier.3,v 1.23 2008/07/24 21:54:43 nijtmans Exp $
+'\" RCS: @(#) $Id: Notifier.3,v 1.24 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Notifier 3 8.1 Tcl "Tcl Library Procedures"
@@ -229,11 +229,13 @@ The procedure \fBTcl_CreateEventSource\fR creates a new event source.
Its arguments specify the setup procedure and check procedure for
the event source.
\fISetupProc\fR should match the following prototype:
+.PP
.CS
typedef void \fBTcl_EventSetupProc\fR(
ClientData \fIclientData\fR,
int \fIflags\fR);
.CE
+.PP
The \fIclientData\fR argument will be the same as the \fIclientData\fR
argument to \fBTcl_CreateEventSource\fR; it is typically used to
point to private information managed by the event source.
@@ -268,12 +270,14 @@ connection.
The \fItimePtr\fR argument to \fBTcl_WaitForEvent\fR points to
a structure that describes a time interval in seconds and
microseconds:
+.PP
.CS
typedef struct Tcl_Time {
long \fIsec\fR;
long \fIusec\fR;
} \fBTcl_Time\fR;
.CE
+.PP
The \fIusec\fR field should be less than 1000000.
.PP
Information provided to \fBTcl_SetMaxBlockTime\fR
@@ -303,11 +307,13 @@ The second procedure provided by each event source is its check
procedure, indicated by the \fIcheckProc\fR argument to
\fBTcl_CreateEventSource\fR. \fICheckProc\fR must match the
following prototype:
+.PP
.CS
typedef void \fBTcl_EventCheckProc\fR(
ClientData \fIclientData\fR,
int \fIflags\fR);
.CE
+.PP
The arguments to this procedure are the same as those for \fIsetupProc\fR.
\fBCheckProc\fR is invoked by \fBTcl_DoOneEvent\fR after it has waited
for events. Presumably at least one event source is now prepared to
@@ -326,12 +332,14 @@ to that event source. However, the first element of the structure
must be a structure of type \fBTcl_Event\fR, and the address of this
structure is used when communicating between the event source and the
rest of the notifier. A \fBTcl_Event\fR has the following definition:
+.PP
.CS
typedef struct {
Tcl_EventProc *\fIproc\fR;
struct Tcl_Event *\fInextPtr\fR;
} \fBTcl_Event\fR;
.CE
+.PP
The event source must fill in the \fIproc\fR field of
the event before calling \fBTcl_QueueEvent\fR.
The \fInextPtr\fR is used to link together the events in the queue
@@ -359,11 +367,13 @@ When it is time to handle an event from the queue (steps 1 and 4
above) \fBTcl_ServiceEvent\fR will invoke the \fIproc\fR specified
in the first queued \fBTcl_Event\fR structure.
\fIProc\fR must match the following prototype:
+.PP
.CS
typedef int \fBTcl_EventProc\fR(
Tcl_Event *\fIevPtr\fR,
int \fIflags\fR);
.CE
+.PP
The first argument to \fIproc\fR is a pointer to the event, which will
be the same as the first argument to the \fBTcl_QueueEvent\fR call that
added the event to the queue.
@@ -416,11 +426,13 @@ events from the event queue. \fBTcl_DeleteEvents\fR calls \fIproc\fR
for each event in the queue, deleting those for with the procedure
returns 1. Events for which the procedure returns 0 are left in the
queue. \fIProc\fR should match the following prototype:
+.PP
.CS
typedef int \fBTcl_EventDeleteProc\fR(
Tcl_Event *\fIevPtr\fR,
ClientData \fIclientData\fR);
.CE
+.PP
The \fIclientData\fR argument will be the same as the \fIclientData\fR
argument to \fBTcl_DeleteEvents\fR; it is typically used to point to
private information managed by the event source. The \fIevPtr\fR will
@@ -537,6 +549,7 @@ to another program, such as a Web browser plugin.
To do this, the extension makes a call to \fBTcl_SetNotifier\fR
passing a pointer to a \fBTcl_NotifierProcs\fR data structure. The
structure has the following layout:
+.PP
.CS
typedef struct Tcl_NotifierProcs {
Tcl_SetTimerProc *setTimerProc;
@@ -549,6 +562,7 @@ typedef struct Tcl_NotifierProcs {
Tcl_ServiceModeHookProc *serviceModeHookProc;
} \fBTcl_NotifierProcs\fR;
.CE
+.PP
Following the call to \fBTcl_SetNotifier\fR, the pointers given in
the \fBTcl_NotifierProcs\fR structure replace whatever notifier had
been installed in the process.
diff --git a/doc/Object.3 b/doc/Object.3
index 3b6abc8..00b4cec 100644
--- a/doc/Object.3
+++ b/doc/Object.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: Object.3,v 1.21 2008/07/27 22:18:21 nijtmans Exp $
+'\" RCS: @(#) $Id: Object.3,v 1.22 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_Obj 3 8.5 Tcl "Tcl Library Procedures"
@@ -109,6 +109,7 @@ by defining their own \fBTcl_ObjType\fR structs.
.PP
Each Tcl object is represented by a \fBTcl_Obj\fR structure
which is defined as follows.
+.PP
.CS
typedef struct Tcl_Obj {
int \fIrefCount\fR;
@@ -131,6 +132,7 @@ typedef struct Tcl_Obj {
} \fIinternalRep\fR;
} \fBTcl_Obj\fR;
.CE
+.PP
The \fIbytes\fR and the \fIlength\fR members together hold
an object's UTF-8 string representation,
which is a \fIcounted string\fR not containing null bytes (UTF-8 null
@@ -232,20 +234,26 @@ to see how to create a new object type.
.PP
As an example of the lifetime of an object,
consider the following sequence of commands:
+.PP
.CS
\fBset x 123\fR
.CE
+.PP
This assigns to \fIx\fR an untyped object whose
\fIbytes\fR member points to \fB123\fR and \fIlength\fR member contains 3.
The object's \fItypePtr\fR member is NULL.
+.PP
.CS
\fBputs "x is $x"\fR
.CE
+.PP
\fIx\fR's string representation is valid (since \fIbytes\fR is non-NULL)
and is fetched for the command.
+.PP
.CS
\fBincr x\fR
.CE
+.PP
The \fBincr\fR command first gets an integer from \fIx\fR's object
by calling \fBTcl_GetIntFromObj\fR.
This procedure checks whether the object is already an integer object.
@@ -260,9 +268,11 @@ then invalidates its string representation
(by calling \fBTcl_InvalidateStringRep\fR)
since the string representation
no longer corresponds to the internal representation.
+.PP
.CS
\fBputs "x is now $x"\fR
.CE
+.PP
The string representation of \fIx\fR's object is needed
and is recomputed.
The string representation is now \fB124\fR
diff --git a/doc/Preserve.3 b/doc/Preserve.3
index e4ae2dc..1a48a56 100644
--- a/doc/Preserve.3
+++ b/doc/Preserve.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: Preserve.3,v 1.7 2008/06/29 22:28:24 dkf Exp $
+'\" RCS: @(#) $Id: Preserve.3,v 1.8 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_Preserve 3 7.5 Tcl "Tcl Library Procedures"
@@ -79,10 +79,12 @@ calls to \fBTcl_Release\fR then \fIfreeProc\fR will be called by
All the work of freeing the object is carried out by \fIfreeProc\fR.
\fIFreeProc\fR must have arguments and result that match the
type \fBTcl_FreeProc\fR:
+.PP
.CS
typedef void \fBTcl_FreeProc\fR(
char *\fIblockPtr\fR);
.CE
+.PP
The \fIblockPtr\fR argument to \fIfreeProc\fR will be the
same as the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR.
The type of \fIblockPtr\fR (\fBchar *\fR) is different than the type of the
diff --git a/doc/SetResult.3 b/doc/SetResult.3
index 0c7f1ec..da3b3f9 100644
--- a/doc/SetResult.3
+++ b/doc/SetResult.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: SetResult.3,v 1.19 2008/06/29 22:28:24 dkf Exp $
+'\" RCS: @(#) $Id: SetResult.3,v 1.20 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_SetResult 3 8.0 Tcl "Tcl Library Procedures"
@@ -215,10 +215,12 @@ This allows applications to use non-standard storage allocators.
When Tcl no longer needs the storage for the string, it will
call \fIfreeProc\fR. \fIFreeProc\fR should have arguments and
result that match the type \fBTcl_FreeProc\fR:
+.PP
.CS
typedef void \fBTcl_FreeProc\fR(
char *\fIblockPtr\fR);
.CE
+.PP
When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to
the value of \fIresult\fR passed to \fBTcl_SetResult\fR.
.SH "SEE ALSO"
diff --git a/doc/SplitList.3 b/doc/SplitList.3
index 04986d5..e70199a 100644
--- a/doc/SplitList.3
+++ b/doc/SplitList.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: SplitList.3,v 1.14 2008/06/29 22:28:24 dkf Exp $
+'\" RCS: @(#) $Id: SplitList.3,v 1.15 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_SplitList 3 8.0 Tcl "Tcl Library Procedures"
@@ -81,15 +81,18 @@ also holds copies of all the list elements. It is the caller's
responsibility to free up all of this storage.
For example, suppose that you have called \fBTcl_SplitList\fR with
the following code:
+.PP
.CS
int argc, code;
char *string;
char **argv;
\&...
code = Tcl_SplitList(interp, string, &argc, &argv);
+.PP
.CE
Then you should eventually free the storage with a call like the
following:
+.PP
.CS
Tcl_Free((char *) argv);
.CE
diff --git a/doc/SplitPath.3 b/doc/SplitPath.3
index d7380de..e992db4 100644
--- a/doc/SplitPath.3
+++ b/doc/SplitPath.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: SplitPath.3,v 1.9 2004/10/07 15:15:48 dkf Exp $
+'\" RCS: @(#) $Id: SplitPath.3,v 1.10 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_SplitPath 3 7.5 Tcl "Tcl Library Procedures"
@@ -61,6 +61,7 @@ holds copies of all the path elements. It is the caller's
responsibility to free all of this storage.
For example, suppose that you have called \fBTcl_SplitPath\fR with the
following code:
+.PP
.CS
int argc;
char *path;
@@ -68,8 +69,10 @@ char **argv;
\&...
Tcl_SplitPath(string, &argc, &argv);
.CE
+.PP
Then you should eventually free the storage with a call like the
following:
+.PP
.CS
Tcl_Free((char *) argv);
.CE
diff --git a/doc/StaticPkg.3 b/doc/StaticPkg.3
index ad50fa6..975b961 100644
--- a/doc/StaticPkg.3
+++ b/doc/StaticPkg.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: StaticPkg.3,v 1.10 2008/06/29 22:28:24 dkf Exp $
+'\" RCS: @(#) $Id: StaticPkg.3,v 1.11 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_StaticPackage 3 7.5 Tcl "Tcl Library Procedures"
@@ -53,10 +53,12 @@ be invoked, depending on whether the target interpreter is safe
or not.
\fIinitProc\fR and \fIsafeInitProc\fR must both match the
following prototype:
+.PP
.CS
typedef int \fBTcl_PackageInitProc\fR(
Tcl_Interp *\fIinterp\fR);
.CE
+.PP
The \fIinterp\fR argument identifies the interpreter in which the package
is to be loaded. The initialization procedure must return \fBTCL_OK\fR or
\fBTCL_ERROR\fR to indicate whether or not it completed successfully; in
diff --git a/doc/StringObj.3 b/doc/StringObj.3
index 99bfdfb..5e08d8e 100644
--- a/doc/StringObj.3
+++ b/doc/StringObj.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: StringObj.3,v 1.28 2008/06/29 22:28:24 dkf Exp $
+'\" RCS: @(#) $Id: StringObj.3,v 1.29 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures"
@@ -275,9 +275,11 @@ bytes is necessary to append only whole multi-byte characters.
\fBTcl_Format\fR is the C-level interface to the engine of the \fBformat\fR
command. The actual command procedure for \fBformat\fR is little more
than
+.PP
.CS
Tcl_Format(interp, Tcl_GetString(objv[1]), objc-2, objv+2);
.CE
+.PP
The \fIobjc\fR Tcl_Obj values in \fIobjv\fR are formatted into a string
according to the conversion specification in \fIformat\fR argument, following
the documentation for the \fBformat\fR command. The resulting formatted
@@ -287,22 +289,26 @@ returned, and an error message is recorded in \fIinterp\fR, if \fIinterp\fR
is non-NULL.
.PP
\fBTcl_AppendFormatToObj\fR is an appending alternative form
-of \fBTcl_Format\fR with functionality equivalent to
+of \fBTcl_Format\fR with functionality equivalent to:
+.PP
.CS
Tcl_Obj *newPtr = Tcl_Format(interp, format, objc, objv);
if (newPtr == NULL) return TCL_ERROR;
Tcl_AppendObjToObj(objPtr, newPtr);
return TCL_OK;
.CE
+.PP
but with greater convenience and efficiency when the appending
functionality is needed.
.PP
\fBTcl_ObjPrintf\fR serves as a replacement for the common sequence
+.PP
.CS
char buf[SOME_SUITABLE_LENGTH];
sprintf(buf, format, ...);
Tcl_NewStringObj(buf, -1);
.CE
+.PP
but with greater convenience and no need to
determine \fBSOME_SUITABLE_LENGTH\fR. The formatting is done with the same
core formatting engine used by \fBTcl_Format\fR. This means the set of
@@ -316,19 +322,23 @@ passing around than the number of encoded characters those bytes happen
to represent. The variable number of arguments passed in should be of
the types that would be suitable for passing to \fBsprintf\fR. Note in
this example usage, \fIx\fR is of type \fBlong\fR.
+.PP
.CS
long x = 5;
Tcl_Obj *objPtr = Tcl_ObjPrintf("Value is %d", x);
.CE
+.PP
If the value of \fIformat\fR contains internal inconsistencies or invalid
specifier formats, the formatted string result produced by
\fBTcl_ObjPrintf\fR will be an error message describing the error.
.PP
\fBTcl_AppendPrintfToObj\fR is an appending alternative form
of \fBTcl_ObjPrintf\fR with functionality equivalent to
+.PP
.CS
Tcl_AppendObjToObj(objPtr, Tcl_ObjPrintf(format, ...));
.CE
+.PP
but with greater convenience and efficiency when the appending
functionality is needed.
.PP
diff --git a/doc/Tcl.n b/doc/Tcl.n
index b62a6e9..e486869 100644
--- a/doc/Tcl.n
+++ b/doc/Tcl.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: Tcl.n,v 1.19 2008/06/29 22:28:24 dkf Exp $
+'\" RCS: @(#) $Id: Tcl.n,v 1.20 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl n "8.5" Tcl "Tcl Built-In Commands"
@@ -123,7 +123,7 @@ substitutions are performed on the characters of \fIindex\fR.
.
\fIName\fR is the name of a scalar variable. It may contain any
characters whatsoever except for close braces.
-.LP
+.PP
There may be any number of variable substitutions in a single word.
Variable substitution is not performed on words enclosed in braces.
.RE
@@ -194,7 +194,7 @@ be 0.
The hexadecimal digits \fIhhhh\fR (one, two, three, or four of them) give a
sixteen-bit hexadecimal value for the Unicode character that will be
inserted.
-.LP
+.PP
Backslash substitution is not performed on words enclosed in braces,
except for backslash-newline as described above.
.RE
@@ -219,13 +219,15 @@ no substitutions are performed before making the recursive
call and no additional substitutions are performed on the result
of the nested script.
.RS
-.LP
+.PP
Substitutions take place from left to right, and each substitution is
evaluated completely before attempting to evaluate the next. Thus, a
sequence like
+.PP
.CS
set y [set x 0][incr x][incr x]
.CE
+.PP
will always set the variable \fIy\fR to the value, \fI012\fR.
.RE
.IP "[12] \fBSubstitution and word boundaries.\fR"
diff --git a/doc/TraceCmd.3 b/doc/TraceCmd.3
index 813f6a1..ee8198f 100644
--- a/doc/TraceCmd.3
+++ b/doc/TraceCmd.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.
'\"
-'\" CVS: @(#) $Id: TraceCmd.3,v 1.12 2008/06/29 22:28:24 dkf Exp $
+'\" CVS: @(#) $Id: TraceCmd.3,v 1.13 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_TraceCommand 3 7.4 Tcl "Tcl Library Procedures"
@@ -64,6 +64,7 @@ Invoke \fIproc\fR when the command is deleted.
Whenever one of the specified operations occurs to the command,
\fIproc\fR will be invoked. It should have arguments and result that
match the type \fBTcl_CommandTraceProc\fR:
+.PP
.CS
typedef void \fBTcl_CommandTraceProc\fR(
ClientData \fIclientData\fR,
@@ -72,6 +73,7 @@ typedef void \fBTcl_CommandTraceProc\fR(
const char *\fInewName\fR,
int \fIflags\fR);
.CE
+.PP
The \fIclientData\fR and \fIinterp\fR parameters will have the same
values as those passed to \fBTcl_TraceCommand\fR when the trace was
created. \fIClientData\fR typically points to an application-specific
diff --git a/doc/TraceVar.3 b/doc/TraceVar.3
index 02e4c0d..65fa9a7 100644
--- a/doc/TraceVar.3
+++ b/doc/TraceVar.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: TraceVar.3,v 1.20 2008/06/29 22:28:24 dkf Exp $
+'\" RCS: @(#) $Id: TraceVar.3,v 1.21 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_TraceVar 3 7.4 Tcl "Tcl Library Procedures"
@@ -123,6 +123,7 @@ Whenever one of the specified operations occurs on the variable,
\fIproc\fR will be invoked.
It should have arguments and result that match the type
\fBTcl_VarTraceProc\fR:
+.PP
.CS
typedef char *\fBTcl_VarTraceProc\fR(
ClientData \fIclientData\fR,
@@ -131,6 +132,7 @@ typedef char *\fBTcl_VarTraceProc\fR(
char *\fIname2\fR,
int \fIflags\fR);
.CE
+.PP
The \fIclientData\fR and \fIinterp\fR parameters will
have the same values as those passed to \fBTcl_TraceVar\fR when the
trace was created.
diff --git a/doc/WrongNumArgs.3 b/doc/WrongNumArgs.3
index daa729c..323ad40 100644
--- a/doc/WrongNumArgs.3
+++ b/doc/WrongNumArgs.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: WrongNumArgs.3,v 1.12 2007/12/13 15:22:32 dgp Exp $
+'\" RCS: @(#) $Id: WrongNumArgs.3,v 1.13 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_WrongNumArgs 3 8.0 Tcl "Tcl Library Procedures"
@@ -31,7 +31,6 @@ Additional error information to print after leading arguments
from \fIobjv\fR. This typically gives the acceptable syntax
of the command. This argument may be NULL.
.BE
-
.SH DESCRIPTION
.PP
\fBTcl_WrongNumArgs\fR is a utility procedure that is invoked by
@@ -45,13 +44,17 @@ elements of \fIobjv\fR plus \fImessage\fR. For example, if
.QW "\fBfileName count\fR"
then \fIinterp\fR's result object will be set to the following
string:
+.PP
.CS
wrong # args: should be "foo fileName count"
.CE
+.PP
If \fIobjc\fR is 2, the result will be set to the following string:
+.PP
.CS
wrong # args: should be "foo bar fileName count"
.CE
+.PP
\fIObjc\fR is usually 1, but may be 2 or more for commands like
\fBstring\fR and the Tk widget commands, which use the first argument
as a subcommand.
@@ -68,12 +71,11 @@ originally passed in. Using the above example, let us assume that
\fIbar\fR is actually an abbreviation for \fIbarfly\fR and the object
is now an indexObject because it was passed to
\fBTcl_GetIndexFromObj\fR. In this case the error message would be:
+.PP
.CS
wrong # args: should be "foo barfly fileName count"
.CE
-
.SH "SEE ALSO"
-Tcl_GetIndexFromObj
-
+Tcl_GetIndexFromObj(3)
.SH KEYWORDS
command, error message, wrong number of arguments
diff --git a/doc/after.n b/doc/after.n
index 4e5dfdd..e6d2dd0 100644
--- a/doc/after.n
+++ b/doc/after.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: after.n,v 1.11 2008/06/13 05:45:07 mistachkin Exp $
+'\" RCS: @(#) $Id: after.n,v 1.12 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH after n 7.5 Tcl "Tcl Built-In Commands"
@@ -26,7 +26,6 @@ after \- Execute a command after a time delay
.sp
\fBafter info \fR?\fIid\fR?
.BE
-
.SH DESCRIPTION
.PP
This command is used to delay execution of the program or to execute
@@ -34,12 +33,14 @@ a command in background sometime in the future. It has several forms,
depending on the first argument to the command:
.TP
\fBafter \fIms\fR
+.
\fIMs\fR must be an integer giving a time in milliseconds.
The command sleeps for \fIms\fR milliseconds and then returns.
While the command is sleeping the application does not respond to
events.
.TP
\fBafter \fIms \fR?\fIscript script script ...\fR?
+.
In this form the command returns immediately, but it arranges
for a Tcl command to be executed \fIms\fR milliseconds later as an
event handler.
@@ -55,6 +56,7 @@ The \fBafter\fR command returns an identifier that can be used
to cancel the delayed command using \fBafter cancel\fR.
.TP
\fBafter cancel \fIid\fR
+.
Cancels the execution of a delayed command that
was previously scheduled.
\fIId\fR indicates which command should be canceled; it must have
@@ -63,6 +65,7 @@ If the command given by \fIid\fR has already been executed then
the \fBafter cancel\fR command has no effect.
.TP
\fBafter cancel \fIscript script ...\fR
+.
This command also cancels the execution of a delayed command.
The \fIscript\fR arguments are concatenated together with space
separators (just as in the \fBconcat\fR command).
@@ -71,6 +74,7 @@ canceled and will never be executed; if no such command is
currently pending then the \fBafter cancel\fR command has no effect.
.TP
\fBafter idle \fIscript \fR?\fIscript script ...\fR?
+.
Concatenates the \fIscript\fR arguments together with space
separators (just as in the \fBconcat\fR command), and arranges
for the resulting script to be evaluated later as an idle callback.
@@ -83,6 +87,7 @@ background error will be reported by the command
registered with \fB interp bgerror\fR.
.TP
\fBafter info \fR?\fIid\fR?
+.
This command returns information about existing event handlers.
If no \fIid\fR argument is supplied, the command returns
a list of the identifiers for all existing
@@ -106,6 +111,7 @@ and \fBupdate\fR commands.
.SH "EXAMPLES"
This defines a command to make Tcl do nothing at all for \fIN\fR
seconds:
+.PP
.CS
proc sleep {N} {
\fBafter\fR [expr {int($N * 1000)}]
@@ -114,6 +120,7 @@ proc sleep {N} {
.PP
This arranges for the command \fIwake_up\fR to be run in eight hours
(providing the event loop is active at that time):
+.PP
.CS
\fBafter\fR [expr {1000 * 60 * 60 * 8}] wake_up
.CE
@@ -128,6 +135,7 @@ processing steps (arranging for the next step to be done using an
already-triggered timer event only when the event queue has been
drained) and is useful when you want to ensure that a Tk GUI remains
responsive during a slow task.
+.PP
.CS
proc doOneStep {} {
if {[::my_calc::one_step]} {
@@ -136,9 +144,10 @@ proc doOneStep {} {
}
doOneStep
.CE
-
.SH "SEE ALSO"
concat(n), interp(n), update(n), vwait(n)
-
.SH KEYWORDS
cancel, delay, idle callback, sleep, time
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/append.n b/doc/append.n
index 5bf99e4..c044c08 100644
--- a/doc/append.n
+++ b/doc/append.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: append.n,v 1.10 2007/12/13 15:22:32 dgp Exp $
+'\" RCS: @(#) $Id: append.n,v 1.11 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH append n "" Tcl "Tcl Built-In Commands"
@@ -16,7 +16,6 @@ append \- Append to variable
.SH SYNOPSIS
\fBappend \fIvarName \fR?\fIvalue value value ...\fR?
.BE
-
.SH DESCRIPTION
.PP
Append all of the \fIvalue\fR arguments to the current value
@@ -34,6 +33,7 @@ is much more efficient than
if \fB$a\fR is long.
.SH EXAMPLE
Building a string of comma-separated numbers piecemeal using a loop.
+.PP
.CS
set var 0
for {set i 1} {$i<=10} {incr i} {
@@ -42,9 +42,10 @@ for {set i 1} {$i<=10} {incr i} {
puts $var
# Prints 0,1,2,3,4,5,6,7,8,9,10
.CE
-
.SH "SEE ALSO"
concat(n), lappend(n)
-
.SH KEYWORDS
append, variable
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/chan.n b/doc/chan.n
index 5277dff..d79c717 100644
--- a/doc/chan.n
+++ b/doc/chan.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: chan.n,v 1.21 2008/10/14 14:02:55 dkf Exp $
+'\" RCS: @(#) $Id: chan.n,v 1.22 2008/10/15 10:43:37 dkf Exp $
.so man.macros
.TH chan n 8.5 Tcl "Tcl Built-In Commands"
.BS
@@ -655,9 +655,11 @@ in which \fBchan configure\fR will alter input).
.PP
When reading from a serial port, most applications should configure
the serial port channel to be nonblocking, like this:
+.PP
.CS
\fBchan configure \fIchannelId \fB\-blocking \fI0\fR.
.CE
+.PP
Then \fBchan read\fR behaves much like described above. Note that
most serial ports are comparatively slow; it is entirely possible to
get a \fBreadable\fR event for each character read from them. Care
diff --git a/doc/clock.n b/doc/clock.n
index 600722b..d4bb1b9 100644
--- a/doc/clock.n
+++ b/doc/clock.n
@@ -754,6 +754,7 @@ The C library's idea of the local time zone, as defined by the
.PP
In case [1] \fIonly,\fR the string is tested to see if it is one
of the strings:
+.PP
.CS
gmt ut utc bst wet wat at
nft nst ndt ast adt est edt
@@ -765,6 +766,7 @@ of the strings:
cadt east eadt gst nzt nzst nzdt
idle
.CE
+.PP
If it is a string in the above list, it designates a known
time zone, and is interpreted as such.
.PP
diff --git a/doc/dict.n b/doc/dict.n
index f2ab912..308e367 100644
--- a/doc/dict.n
+++ b/doc/dict.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: dict.n,v 1.18 2007/12/31 00:17:44 dkf Exp $
+'\" RCS: @(#) $Id: dict.n,v 1.19 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH dict n 8.5 Tcl "Tcl Built-In Commands"
@@ -23,33 +23,39 @@ below for a description), depending on \fIoption\fR. The legal
\fIoption\fRs (which may be abbreviated) are:
.TP
\fBdict append \fIdictionaryVariable key \fR?\fIstring ...\fR?
+.
This appends the given string (or strings) to the value that the given
key maps to in the dictionary value contained in the given variable,
writing the resulting dictionary value back to that variable.
Non-existent keys are treated as if they map to an empty string.
.TP
\fBdict create \fR?\fIkey value ...\fR?
+.
Create a new dictionary that contains each of the key/value mappings
listed as arguments (keys and values alternating, with each key being
followed by its associated value.)
.TP
\fBdict exists \fIdictionaryValue key \fR?\fIkey ...\fR?
+.
This returns a boolean value indicating whether the given key (or path
of keys through a set of nested dictionaries) exists in the given
dictionary value. This returns a true value exactly when \fBdict
get\fR on that path will succeed.
.TP
\fBdict filter \fIdictionaryValue filterType arg \fR?\fIarg ...\fR?
+.
This takes a dictionary value and returns a new dictionary that
contains just those key/value pairs that match the specified filter
type (which may be abbreviated.) Supported filter types are:
.RS
.TP
\fBdict filter \fIdictionaryValue \fBkey \fIglobPattern\fR
+.
The key rule only matches those key/value pairs whose keys match the
given pattern (in the style of \fBstring match\fR.)
.TP
\fBdict filter \fIdictionaryValue \fBscript {\fIkeyVar valueVar\fB} \fIscript\fR
+.
The script rule tests for matching by assigning the key to the
\fIkeyVar\fR and the value to the \fIvalueVar\fR, and then evaluating
the given script which should return a boolean value (with the
@@ -63,11 +69,13 @@ result. The key/value pairs are tested in the order in which the keys
were inserted into the dictionary.
.TP
\fBdict filter \fIdictionaryValue \fBvalue \fIglobPattern\fR
+.
The value rule only matches those key/value pairs whose values match
the given pattern (in the style of \fBstring match\fR.)
.RE
.TP
\fBdict for {\fIkeyVar valueVar\fB} \fIdictionaryValue body\fR
+.
This command takes three arguments, the first a two-element list of
variable names (for the key and value respectively of each mapping in
the dictionary), the second the dictionary value to iterate across,
@@ -82,6 +90,7 @@ normal \fBTCL_OK\fR result. The order of iteration is the order in
which the keys were inserted into the dictionary.
.TP
\fBdict get \fIdictionaryValue \fR?\fIkey ...\fR?
+.
Given a dictionary value (first argument) and a key (second argument),
this will retrieve the value for that key. Where several keys are
supplied, the behaviour of the command shall be as if the result of
@@ -90,20 +99,23 @@ supplied, the behaviour of the command shall be as if the result of
subsequent) arguments. This facilitates lookups in nested
dictionaries. For example, the following two commands are equivalent:
.RS
+.PP
.CS
dict get $dict foo bar spong
dict get [dict get [dict get $dict foo] bar] spong
.CE
+.PP
If no keys are provided, dict would return a list containing pairs of
elements in a manner similar to \fBarray get\fR. That is, the first
element of each pair would be the key and the second element would be
the value for that key.
-
+.PP
It is an error to attempt to retrieve a value for a key that is not
present in the dictionary.
.RE
.TP
\fBdict incr \fIdictionaryVariable key \fR?\fIincrement\fR?
+.
This adds the given increment value (an integer that defaults to 1 if
not specified) to the value that the given key maps to in the
dictionary value contained in the given variable, writing the
@@ -112,6 +124,7 @@ are treated as if they map to 0. It is an error to increment a value
for an existing key if that value is not an integer.
.TP
\fBdict info \fIdictionaryValue\fR
+.
This returns information (intended for display to people) about the
given dictionary though the format of this data is dependent on the
implementation of the dictionary. For dictionaries that are
@@ -119,12 +132,14 @@ implemented by hash tables, it is expected that this will return the
string produced by \fBTcl_HashStats\fR, similar to \fBarray info\fR.
.TP
\fBdict keys \fIdictionaryValue \fR?\fIglobPattern\fR?
+.
Return a list of all keys in the given dictionary value. If a pattern
is supplied, only those keys that match it (according to the rules of
\fBstring match\fR) will be returned. The returned keys will be in the
order that they were inserted into the dictionary.
.TP
\fBdict lappend \fIdictionaryVariable key \fR?\fIvalue ...\fR?
+.
This appends the given items to the list value that the given key maps
to in the dictionary value contained in the given variable, writing
the resulting dictionary value back to that variable. Non-existent
@@ -133,6 +148,7 @@ there to be no items to append to the list. It is an error for the
value that the key maps to to not be representable as a list.
.TP
\fBdict merge \fR?\fIdictionaryValue ...\fR?
+.
Return a dictionary that contains the contents of each of the
\fIdictionaryValue\fR arguments. Where two (or more) dictionaries
contain a mapping for the same key, the resulting dictionary maps that
@@ -140,6 +156,7 @@ key to the value according to the last dictionary on the command line
containing a mapping for that key.
.TP
\fBdict remove \fIdictionaryValue \fR?\fIkey ...\fR?
+.
Return a new dictionary that is a copy of an old one passed in as
first argument except without mappings for each of the keys listed.
It is legal for there to be no keys to remove, and it also legal for
@@ -147,6 +164,7 @@ any of the keys to be removed to not be present in the input
dictionary in the first place.
.TP
\fBdict replace \fIdictionaryValue \fR?\fIkey value ...\fR?
+.
Return a new dictionary that is a copy of an old one passed in as
first argument except with some values different or some extra
key/value pairs added. It is legal for this command to be called with
@@ -154,6 +172,7 @@ no key/value pairs, but illegal for this command to be called with a
key but no value.
.TP
\fBdict set \fIdictionaryVariable key \fR?\fIkey ...\fR? \fIvalue\fR
+.
This operation takes the name of a variable containing a dictionary
value and places an updated dictionary value in that variable
containing a mapping from the given key to the given value. When
@@ -161,9 +180,11 @@ multiple keys are present, this operation creates or updates a chain
of nested dictionaries.
.TP
\fBdict size \fIdictionaryValue\fR
+.
Return the number of key/value mappings in the given dictionary value.
.TP
\fBdict unset \fIdictionaryVariable key \fR?\fIkey ...\fR?
+.
This operation (the companion to \fBdict set\fR) takes the name of a
variable containing a dictionary value and places an updated
dictionary value in that variable that does not contain a mapping for
@@ -173,6 +194,7 @@ must be specified, but the last key on the key-path need not exist.
All other components on the path must exist.
.TP
\fBdict update \fIdictionaryVariable key varName \fR?\fIkey varName ...\fR? \fIbody\fR
+.
Execute the Tcl script in \fIbody\fR with the value for each \fIkey\fR
(as found by reading the dictionary value in \fIdictionaryVariable\fR)
mapped to the variable \fIvarName\fR. There may be multiple
@@ -189,6 +211,7 @@ does not use traces; changes to the \fIdictionaryVariable\fR's
contents only happen when \fIbody\fR terminates.
.TP
\fBdict values \fIdictionaryValue \fR?\fIglobPattern\fR?
+.
Return a list of all values in the given dictionary value. If a
pattern is supplied, only those values that match it (according to the
rules of \fBstring match\fR) will be returned. The returned values
@@ -196,6 +219,7 @@ will be in the order of that the keys associated with those values
were inserted into the dictionary.
.TP
\fBdict with \fIdictionaryVariable \fR?\fIkey ...\fR? \fIbody\fR
+.
Execute the Tcl script in \fIbody\fR with the value for each key in
\fIdictionaryVariable\fR mapped (in a manner similarly to \fBdict
update\fR) to a variable with the same name. Where one or more
@@ -229,7 +253,9 @@ and
.QW "apple carrot apple banana"
are equivalent dictionaries (with different string representations).
.SH EXAMPLES
+.PP
Constructing and using nested dictionaries:
+.PP
.CS
# Data for one employee
\fBdict set\fR employeeInfo 12345-A forenames "Joe"
@@ -263,6 +289,7 @@ foreach id [\fBdict keys\fR $employeeInfo] {
.CE
.PP
A localizable version of \fBstring toupper\fR:
+.PP
.CS
# Set up the basic C locale
set capital [\fBdict create\fR C [\fBdict create\fR]]
@@ -285,3 +312,6 @@ set upperCase [string map $upperCaseMap $string]
append(n), array(n), foreach(n), incr(n), list(n), lappend(n), set(n)
.SH KEYWORDS
dictionary, create, update, lookup, iterate, filter
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/encoding.n b/doc/encoding.n
index 1a6983d..c4c9637 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.16 2008/06/29 22:28:24 dkf Exp $
+'\" RCS: @(#) $Id: encoding.n,v 1.17 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH encoding n "8.1" Tcl "Tcl Built-In Commands"
@@ -83,9 +83,11 @@ contain a sequence of Latin-1 characters that correspond to the bytes
of the original string. The \fBencoding\fR command can be used to
convert this string to the expected Japanese Unicode characters. For
example,
+.PP
.CS
set s [\fBencoding convertfrom\fR euc-jp "\exA4\exCF"]
.CE
+.PP
would return the Unicode string
.QW "\eu306F" ,
which is the Hiragana letter HA.
diff --git a/doc/error.n b/doc/error.n
index ffc3ebb..5c81878 100644
--- a/doc/error.n
+++ b/doc/error.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: error.n,v 1.11 2007/12/13 15:22:32 dgp Exp $
+'\" RCS: @(#) $Id: error.n,v 1.12 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH error n "" Tcl "Tcl Built-In Commands"
@@ -39,14 +39,17 @@ with the \fBcatch\fR command:
if a caught error cannot be handled successfully, \fIinfo\fR can be used
to return a stack trace reflecting the original point of occurrence
of the error:
+.PP
.CS
\fBcatch {...} errMsg
set savedInfo $::errorInfo
\&...
error $errMsg $savedInfo\fR
.CE
+.PP
When working with Tcl 8.5 or later, the following code
should be used instead:
+.PP
.CS
\fBcatch {...} errMsg options
\&...
diff --git a/doc/eval.n b/doc/eval.n
index 5156360..1f32697 100644
--- a/doc/eval.n
+++ b/doc/eval.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: eval.n,v 1.11 2008/06/29 22:28:24 dkf Exp $
+'\" RCS: @(#) $Id: eval.n,v 1.12 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH eval n "" Tcl "Tcl Built-In Commands"
@@ -27,11 +27,13 @@ evaluation (or any error generated by it).
Note that the \fBlist\fR command quotes sequences of words in such a
way that they are not further expanded by the \fBeval\fR command.
.SH EXAMPLES
+.PP
Often, it is useful to store a fragment of a script in a variable and
execute it later on with extra values appended. This technique is used
in a number of places throughout the Tcl core (e.g. in \fBfcopy\fR,
\fBlsort\fR and \fBtrace\fR command callbacks). This example shows how
to do this using core Tcl commands:
+.PP
.CS
set script {
puts "logging now"
@@ -57,6 +59,7 @@ easier to make robust in practice.
The following procedure acts in a way that is analogous to the
\fBlappend\fR command, except it inserts the argument values at the
start of the list in the variable:
+.PP
.CS
proc lprepend {varName args} {
upvar 1 $varName var
@@ -66,6 +69,7 @@ proc lprepend {varName args} {
set var [\fBeval\fR [list linsert $var 0] $args]
}
.CE
+.PP
However, the last line would now normally be written without
\fBeval\fR, like this:
.CS
diff --git a/doc/exec.n b/doc/exec.n
index 6626835..c44ee29 100644
--- a/doc/exec.n
+++ b/doc/exec.n
@@ -6,7 +6,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: exec.n,v 1.24 2008/06/29 22:28:24 dkf Exp $
+'\" RCS: @(#) $Id: exec.n,v 1.25 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH exec n 8.5 Tcl "Tcl Built-In Commands"
@@ -366,9 +366,11 @@ console window is not available to them.
.
The \fBexec\fR command is fully functional and works as described.
.SH "UNIX EXAMPLES"
+.PP
Here are some examples of the use of the \fBexec\fR command on Unix.
.PP
To execute a simple program and get its result:
+.PP
.CS
\fBexec\fR uname -a
.CE
@@ -376,6 +378,7 @@ To execute a simple program and get its result:
To execute a program that can return a non-zero result, you should
wrap the call to \fBexec\fR in \fBcatch\fR and check the contents
of the \fB\-errorcode\fR return option if you have an error:
+.PP
.CS
set status 0
if {[catch {\fBexec\fR grep foo bar.txt} results options]} {
@@ -391,10 +394,13 @@ if {[catch {\fBexec\fR grep foo bar.txt} results options]} {
When translating a command from a Unix shell invocation, care should
be taken over the fact that single quote characters have no special
significance to Tcl. Thus:
+.PP
.CS
awk '{sum += $1} END {print sum}' numbers.list
.CE
+.PP
would be translated into something like:
+.PP
.CS
\fBexec\fR awk {{sum += $1} END {print sum}} numbers.list
.CE
@@ -403,19 +409,23 @@ If you are converting invocations involving shell globbing, you should
remember that Tcl does not handle globbing or expand things into
multiple arguments by default. Instead you should write things like
this:
+.PP
.CS
\fBexec\fR ls -l {*}[glob *.tcl]
.CE
.SH "WINDOWS EXAMPLES"
+.PP
Here are some examples of the use of the \fBexec\fR command on Windows.
.PP
To start an instance of \fInotepad\fR editing a file without waiting
for the user to finish editing the file:
+.PP
.CS
\fBexec\fR notepad myfile.txt &
.CE
.PP
To print a text file using \fInotepad\fR:
+.PP
.CS
\fBexec\fR notepad /p myfile.txt
.CE
@@ -423,10 +433,13 @@ To print a text file using \fInotepad\fR:
If a program calls other programs, such as is common with compilers,
then you may need to resort to batch files to hide the console windows
that sometimes pop up:
+.PP
.CS
\fBexec\fR cmp.bat somefile.c -o somefile
.CE
+.PP
With the file \fIcmp.bat\fR looking something like:
+.PP
.CS
@gcc %1 %2 %3 %4 %5 %6 %7 %8 %9
.CE
@@ -444,6 +457,7 @@ applies especially when you want to run
commands like
\fIdir\fR from a Tcl script (if you just want to list filenames, use
the \fBglob\fR command.) To do that, use this:
+.PP
.CS
\fBexec\fR {*}[auto_execok dir] *.tcl
.CE
diff --git a/doc/expr.n b/doc/expr.n
index 613a3bc..b078873 100644
--- a/doc/expr.n
+++ b/doc/expr.n
@@ -6,7 +6,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: expr.n,v 1.35 2008/06/29 22:28:24 dkf Exp $
+'\" RCS: @(#) $Id: expr.n,v 1.36 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH expr n 8.5 Tcl "Tcl Built-In Commands"
@@ -28,9 +28,11 @@ as the corresponding C operators.
Expressions almost always yield numeric results
(integer or floating-point values).
For example, the expression
+.PP
.CS
\fBexpr 8.2 + 6\fR
.CE
+.PP
evaluates to 14.2.
Tcl expressions differ from C expressions in the way that
operands are specified. Also, Tcl expressions support
@@ -205,18 +207,22 @@ divide operators, and produces a result that is the same as the output
of the \fBpow\fR function (after any type conversions.)
All of the binary operators group left-to-right within the same
precedence level. For example, the command
+.PP
.CS
\fBexpr\fR {4*2 < 7}
.CE
+.PP
returns 0.
.PP
The \fB&&\fR, \fB||\fR, and \fB?:\fR operators have
.QW "lazy evaluation" ,
just as in C, which means that operands are not evaluated if they are
not needed to determine the outcome. For example, in the command
+.PP
.CS
\fBexpr {$v ? [a] : [b]}\fR
.CE
+.PP
only one of
.QW \fB[a]\fR
or
@@ -235,14 +241,19 @@ When the expression parser encounters a mathematical function
such as \fBsin($x)\fR, it replaces it with a call to an ordinary
Tcl function in the \fBtcl::mathfunc\fR namespace. The processing
of an expression such as:
+.PP
.CS
\fBexpr {sin($x+$y)}\fR
.CE
+.PP
is the same in every way as the processing of:
+.PP
.CS
\fBexpr {[tcl::mathfunc::sin [expr {$x+$y}]]}\fR
.CE
+.PP
which in turn is the same as the processing of:
+.PP
.CS
\fBtcl::mathfunc::sin [expr {$x+$y}]\fR
.CE
@@ -280,23 +291,29 @@ and string operands is done automatically as needed.
For arithmetic computations, integers are used until some
floating-point number is introduced, after which floating-point is used.
For example,
+.PP
.CS
\fBexpr\fR {5 / 4}
.CE
+.PP
returns 1, while
+.PP
.CS
\fBexpr\fR {5 / 4.0}
\fBexpr\fR {5 / ( [string length "abcd"] + 0.0 )}
.CE
+.PP
both return 1.25.
Floating-point values are always returned with a
.QW \fB.\fR
or an
.QW \fBe\fR
so that they will not look like integer values. For example,
+.PP
.CS
\fBexpr\fR {20.0/5.0}
.CE
+.PP
returns \fB4.0\fR, not \fB4\fR.
.SS "STRING OPERATIONS"
.PP
@@ -311,10 +328,12 @@ Canonical string representation for integer values is a decimal string
format. Canonical string representation for floating-point values
is that produced by the \fB%g\fR format specifier of Tcl's
\fBformat\fR command. For example, the commands
+.PP
.CS
\fBexpr {"0x03" > "2"}\fR
\fBexpr {"0y" < "0x12"}\fR
.CE
+.PP
both return 1. The first comparison is done using integer
comparison, and the second is done using string comparison after
the second operand is converted to the string \fB18\fR.
@@ -332,11 +351,13 @@ This allows the Tcl bytecode compiler to generate the best code.
As mentioned above, expressions are substituted twice:
once by the Tcl parser and once by the \fBexpr\fR command.
For example, the commands
+.PP
.CS
\fBset a 3\fR
\fBset b {$a + 2}\fR
\fBexpr $b*4\fR
.CE
+.PP
return 11, not a multiple of 4.
This is because the Tcl parser will first substitute \fB$a + 2\fR for
the variable \fBb\fR,
@@ -362,6 +383,7 @@ operator, consider using the commands documented in the \fBmathfunc\fR(n) or
Define a procedure that computes an
.QW interesting
mathematical function:
+.PP
.CS
proc tcl::mathfunc::calc {x y} {
\fBexpr\fR { ($x**2 - $y**2) / exp($x**2 + $y**2) }
@@ -369,6 +391,7 @@ proc tcl::mathfunc::calc {x y} {
.CE
.PP
Convert polar coordinates into cartesian coordinates:
+.PP
.CS
# convert from ($radius,$angle)
set x [\fBexpr\fR { $radius * cos($angle) }]
@@ -376,6 +399,7 @@ set y [\fBexpr\fR { $radius * sin($angle) }]
.CE
.PP
Convert cartesian coordinates into polar coordinates:
+.PP
.CS
# convert from ($x,$y)
set radius [\fBexpr\fR { hypot($y, $x) }]
@@ -384,12 +408,14 @@ set angle [\fBexpr\fR { atan2($y, $x) }]
.PP
Print a message describing the relationship of two string values to
each other:
+.PP
.CS
puts "a and b are [\fBexpr\fR {$a eq $b ? {equal} : {different}}]"
.CE
.PP
Set a variable to whether an environment variable is both defined at
all and also set to a true boolean value:
+.PP
.CS
set isTrue [\fBexpr\fR {
[info exists ::env(SOME_ENV_VAR)] &&
@@ -398,6 +424,7 @@ set isTrue [\fBexpr\fR {
.CE
.PP
Generate a random integer in the range 0..99 inclusive:
+.PP
.CS
set randNum [\fBexpr\fR { int(100 * rand()) }]
.CE
diff --git a/doc/file.n b/doc/file.n
index be3cefa..beeca80 100644
--- a/doc/file.n
+++ b/doc/file.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: file.n,v 1.54 2008/09/24 19:31:28 dgp Exp $
+'\" RCS: @(#) $Id: file.n,v 1.55 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH file n 8.3 Tcl "Tcl Built-In Commands"
@@ -138,20 +138,26 @@ only contains one path element, then returns
If \fIname\fR refers to a root directory, then the root directory is
returned. For example,
.RS
+.PP
.CS
\fBfile dirname c:/\fR
.CE
+.PP
returns \fBc:/\fR.
.PP
Note that tilde substitution will only be
performed if it is necessary to complete the command. For example,
+.PP
.CS
\fBfile dirname ~/src/foo.c\fR
.CE
+.PP
returns \fB~/src\fR, whereas
+.PP
.CS
\fBfile dirname ~\fR
.CE
+.PP
returns \fB/home\fR (or something similar).
.RE
.TP
@@ -187,9 +193,11 @@ relative, then it will be joined to the previous file name argument.
Otherwise, any earlier arguments will be discarded, and joining will
proceed from the current argument. For example,
.RS
+.PP
.CS
\fBfile join a b /foo bar\fR
.CE
+.PP
returns \fB/foo/bar\fR.
.PP
Note that any of the names can contain separators, and that the result
@@ -372,10 +380,14 @@ All other elements will be relative. Path separators will be discarded
unless they are needed ensure that an element is unambiguously relative.
For example, under Unix
.RS
+.PP
.CS
file split /foo/~bar/baz
.CE
-returns \fB/\0\0foo\0\0./~bar\0\0baz\fR to ensure that later commands
+.PP
+returns
+.QW \fB/\0\0foo\0\0./~bar\0\0baz\fR
+to ensure that later commands
that use the third component do not attempt to perform tilde
substitution.
.RE
@@ -453,9 +465,11 @@ Returns \fB1\fR if file \fIname\fR is writable by the current user,
These commands always operate using the real user and group identifiers,
not the effective ones.
.SH EXAMPLES
+.PP
This procedure shows how to search for C files in a given directory
that have a correspondingly-named object file in the current
directory:
+.PP
.CS
proc findMatchingCFiles {dir} {
set files {}
@@ -479,6 +493,7 @@ proc findMatchingCFiles {dir} {
.PP
Rename a file and leave a symbolic link pointing from the old location
to the new place:
+.PP
.CS
set oldName foobar.txt
set newName foo/bar.txt
@@ -495,6 +510,7 @@ On Windows, a file can be
easily enough (equivalent to double-clicking on it in the Explorer
interface) but the name passed to the operating system must be in
native format:
+.PP
.CS
exec {*}[auto_execok start] {} [\fBfile nativename\fR ~/example.txt]
.CE
diff --git a/doc/fileevent.n b/doc/fileevent.n
index ba35bdf..05d68f3 100644
--- a/doc/fileevent.n
+++ b/doc/fileevent.n
@@ -6,7 +6,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: fileevent.n,v 1.14 2008/06/24 14:42:51 patthoyts Exp $
+'\" RCS: @(#) $Id: fileevent.n,v 1.15 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH fileevent n 7.5 Tcl "Tcl Built-In Commands"
@@ -107,12 +107,14 @@ In addition, the file event handler is deleted if it ever returns
an error; this is done in order to prevent infinite loops due to
buggy handlers.
.SH EXAMPLE
+.PP
In this setup \fBGetData\fR will be called with the channel as an
argument whenever $chan becomes readable. The \fBread\fR call will
read whatever binary data is currently available without blocking.
Here the channel has the fileevent removed when an end of file
occurs to avoid being continually called (see above). Alternatively
the channel may be closed on this condition.
+.PP
.CS
proc GetData {chan} {
set data [read $chan]
@@ -125,8 +127,10 @@ proc GetData {chan} {
fconfigure $chan -blocking 0 -encoding binary
fileevent $chan readable [list GetData $chan]
.CE
+.PP
The next example demonstrates use of \fBgets\fR to read line-oriented
data.
+.PP
.CS
proc GetData {chan} {
if {[gets $chan line] >= 0} {
@@ -140,15 +144,12 @@ proc GetData {chan} {
fconfigure $chan -blocking 0 -buffering line -translation crlf
fileevent $chan readable [list GetData $chan]
.CE
-
.SH CREDITS
.PP
\fBfileevent\fR is based on the \fBaddinput\fR command created
by Mark Diekhans.
-
.SH "SEE ALSO"
fconfigure(n), gets(n), interp(n), puts(n), read(n), Tcl_StandardChannels(3)
-
.SH KEYWORDS
asynchronous I/O, blocking, channel, event handler, nonblocking, readable,
script, writable.
diff --git a/doc/glob.n b/doc/glob.n
index a7cf7ad..e254e6d 100644
--- a/doc/glob.n
+++ b/doc/glob.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: glob.n,v 1.23 2008/09/29 16:03:29 dgp Exp $
+'\" RCS: @(#) $Id: glob.n,v 1.24 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH glob n 8.3 Tcl "Tcl Built-In Commands"
@@ -98,11 +98,13 @@ The two forms may be mixed, so \fB\-types {d f r w}\fR will find all
regular files OR directories that have both read AND write permissions.
The following are equivalent:
.RS
+.PP
.CS
\fBglob \-type d *\fR
\fBglob */\fR
.CE
.RE
+.PP
except that the first case doesn't return the trailing
.QW /
and is more platform independent.
@@ -206,18 +208,22 @@ to use the Unix style forward slash as a path separator. Windows style
paths can be converted to Unix style paths with the command \fBfile
join $path\fR (or \fBfile normalize $path\fR in Tcl 8.4).
.SH EXAMPLES
+.PP
Find all the Tcl files in the current directory:
+.PP
.CS
\fBglob\fR *.tcl
.CE
.PP
Find all the Tcl files in the user's home directory, irrespective of
what the current directory is:
+.PP
.CS
\fBglob\fR \-directory ~ *.tcl
.CE
.PP
Find all subdirectories of the current directory:
+.PP
.CS
\fBglob\fR \-type d *
.CE
@@ -228,12 +234,11 @@ a
.QW b
or the sequence
.QW cde :
+.PP
.CS
\fBglob\fR \-type f *{a,b,cde}*
.CE
-
.SH "SEE ALSO"
file(n)
-
.SH KEYWORDS
exist, file, glob, pattern