1 files changed, 163 insertions, 171 deletions
diff --git a/doc/TraceCmd.3 b/doc/TraceCmd.3
index 10714a1..1278269 100644
--- a/doc/TraceCmd.3
+++ b/doc/TraceCmd.3
@@ -1,171 +1,163 @@
-'\"
-'\" Copyright (c) 2002 Donal K. Fellows
-'\"
-'\" 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.8 2004/10/07 15:15:48 dkf Exp $
-'\" 
-.so man.macros
-.TH Tcl_TraceCommand 3 7.4 Tcl "Tcl Library Procedures"
-.BS
-.SH NAME
-Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand \- monitor renames and deletes of a command
-.SH SYNOPSIS
-.nf
-\fB#include <tcl.h>\fR
-.sp
-ClientData
-\fBTcl_CommandTraceInfo(\fIinterp, cmdName, flags, proc, prevClientData\fB)\fR
-.sp
-int
-\fBTcl_TraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR
-.sp
-void
-\fBTcl_UntraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR
-.SH ARGUMENTS
-.AS Tcl_CommandTraceProc prevClientData
-.AP Tcl_Interp *interp in
-Interpreter containing the command.
-.AP "const char" *cmdName in
-Name of command.
-.AP int flags in
-OR-ed collection of the values \fBTCL_TRACE_RENAME\fR and
-\fBTCL_TRACE_DELETE\fR.
-.AP Tcl_CommandTraceProc *proc in
-Procedure to call when specified operations occur to \fIcmdName\fR.
-.AP ClientData clientData in
-Arbitrary argument to pass to \fIproc\fR.
-.AP ClientData prevClientData in
-If non-NULL, gives last value returned by \fBTcl_CommandTraceInfo\fR,
-so this call will return information about next trace.  If NULL, this
-call will return information about first trace.
-.BE
-
-.SH DESCRIPTION
-.PP
-\fBTcl_TraceCommand\fR allows a C procedure to monitor operations
-performed on a Tcl command, so that the C procedure is invoked
-whenever the command is renamed or deleted.  If the trace is created
-successfully then \fBTcl_TraceCommand\fR returns \fBTCL_OK\fR. If an error
-occurred (e.g. \fIcmdName\fR specifies a non-existent command) then
-\fBTCL_ERROR\fR is returned and an error message is left in the
-interpreter's result.
-.PP
-The \fIflags\fR argument to \fBTcl_TraceCommand\fR indicates when the
-trace procedure is to be invoked.  It consists of an OR-ed combination
-of any of the following values:
-.TP
-\fBTCL_TRACE_RENAME\fR
-Invoke \fIproc\fR whenever the command is renamed.
-.TP
-\fBTCL_TRACE_DELETE\fR
-Invoke \fIproc\fR when the command is deleted.
-.PP
-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:
-.CS
-typedef void Tcl_CommandTraceProc(
-        ClientData \fIclientData\fR,
-        Tcl_Interp *\fIinterp\fR,
-        const char *\fIoldName\fR,
-        const char *\fInewName\fR,
-        int \fIflags\fR);
-.CE
-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
-data structure that describes what to do when \fIproc\fR is invoked.
-\fIOldName\fR gives the name of the command being renamed, and
-\fInewName\fR gives the name that the command is being renamed to (or
-an empty string or NULL when the command is being deleted.)
-\fIFlags\fR is an OR-ed combination of bits potentially providing
-several pieces of information.  One of the bits \fBTCL_TRACE_RENAME\fR and
-\fBTCL_TRACE_DELETE\fR will be set in \fIflags\fR to indicate which
-operation is being performed on the command.  The bit
-\fBTCL_TRACE_DESTROYED\fR will be set in \fIflags\fR if the trace is about
-to be destroyed; this information may be useful to \fIproc\fR so that
-it can clean up its own internal data structures (see the section
-\fBTCL_TRACE_DESTROYED\fR below for more details).  Lastly, the bit
-\fBTCL_INTERP_DESTROYED\fR will be set if the entire interpreter is being
-destroyed.  When this bit is set, \fIproc\fR must be especially
-careful in the things it does (see the section \fBTCL_INTERP_DESTROYED\fR
-below).
-.PP
-\fBTcl_UntraceCommand\fR may be used to remove a trace.  If the
-command specified by \fIinterp\fR, \fIcmdName\fR, and \fIflags\fR has
-a trace set with \fIflags\fR, \fIproc\fR, and \fIclientData\fR, then
-the corresponding trace is removed.  If no such trace exists, then the
-call to \fBTcl_UntraceCommand\fR has no effect.  The same bits are
-valid for \fIflags\fR as for calls to \fBTcl_TraceCommand\fR.
-.PP
-\fBTcl_CommandTraceInfo\fR may be used to retrieve information about
-traces set on a given command.
-The return value from \fBTcl_CommandTraceInfo\fR is the \fIclientData\fR
-associated with a particular trace.
-The trace must be on the command specified by the \fIinterp\fR,
-\fIcmdName\fR, and \fIflags\fR arguments (note that currently the
-flags are ignored; \fIflags\fR should be set to 0 for future
-compatibility) and its trace procedure must the same as the \fIproc\fR
-argument.
-If the \fIprevClientData\fR argument is NULL then the return
-value corresponds to the first (most recently created) matching
-trace, or NULL if there are no matching traces.
-If the \fIprevClientData\fR argument isn't NULL, then it should
-be the return value from a previous call to \fBTcl_CommandTraceInfo\fR.
-In this case, the new return value will correspond to the next
-matching trace after the one whose \fIclientData\fR matches
-\fIprevClientData\fR, or NULL if no trace matches \fIprevClientData\fR
-or if there are no more matching traces after it.
-This mechanism makes it possible to step through all of the
-traces for a given command that have the same \fIproc\fR.
-
-.SH "CALLING COMMANDS DURING TRACES"
-.PP
-During rename traces, the command being renamed is visible with both
-names simultaneously, and the command still exists during delete
-traces (if \fBTCL_INTERP_DESTROYED\fR is not set).  However, there is no
-mechanism for signaling that an error occurred in a trace procedure,
-so great care should be taken that errors do not get silently lost.
-
-.SH "MULTIPLE TRACES"
-.PP
-It is possible for multiple traces to exist on the same command.
-When this happens, all of the trace procedures will be invoked on each
-access, in order from most-recently-created to least-recently-created.
-Attempts to delete the command during a delete trace will fail
-silently, since the command is already scheduled for deletion anyway.
-If the command being renamed is renamed by one of its rename traces,
-that renaming takes precedence over the one that triggered the trace
-and the collection of traces will not be reexecuted; if several traces
-rename the command, the last renaming takes precedence.
-
-.SH "TCL_TRACE_DESTROYED FLAG"
-.PP
-In a delete callback to \fIproc\fR, the \fBTCL_TRACE_DESTROYED\fR bit
-is set in \fIflags\fR.
-
-'\" Perhaps need some more comments here? - DKF
-
-.SH "TCL_INTERP_DESTROYED"
-.PP
-When an interpreter is destroyed, unset traces are called for
-all of its commands.
-The \fBTCL_INTERP_DESTROYED\fR bit will be set in the \fIflags\fR
-argument passed to the trace procedures.
-Trace procedures must be extremely careful in what they do if
-the \fBTCL_INTERP_DESTROYED\fR bit is set.
-It is not safe for the procedures to invoke any Tcl procedures
-on the interpreter, since its state is partially deleted.
-All that trace procedures should do under these circumstances is
-to clean up and free their own internal data structures.
-
-.SH BUGS
-.PP
-Tcl doesn't do any error checking to prevent trace procedures
-from misusing the interpreter during traces with \fBTCL_INTERP_DESTROYED\fR
-set.
-
-.SH KEYWORDS
-clientData, trace, command
+'\"
+'\" Copyright (c) 2002 Donal K. Fellows
+'\"
+'\" 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.9 2007/10/28 14:17:40 dkf Exp $
+'\" 
+.so man.macros
+.TH Tcl_TraceCommand 3 7.4 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand \- monitor renames and deletes of a command
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+ClientData
+\fBTcl_CommandTraceInfo(\fIinterp, cmdName, flags, proc, prevClientData\fB)\fR
+.sp
+int
+\fBTcl_TraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR
+.sp
+void
+\fBTcl_UntraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR
+.SH ARGUMENTS
+.AS Tcl_CommandTraceProc prevClientData
+.AP Tcl_Interp *interp in
+Interpreter containing the command.
+.AP "const char" *cmdName in
+Name of command.
+.AP int flags in
+OR'ed collection of the values \fBTCL_TRACE_RENAME\fR and
+\fBTCL_TRACE_DELETE\fR.
+.AP Tcl_CommandTraceProc *proc in
+Procedure to call when specified operations occur to \fIcmdName\fR.
+.AP ClientData clientData in
+Arbitrary argument to pass to \fIproc\fR.
+.AP ClientData prevClientData in
+If non-NULL, gives last value returned by \fBTcl_CommandTraceInfo\fR,
+so this call will return information about next trace.  If NULL, this
+call will return information about first trace.
+.BE
+.SH DESCRIPTION
+.PP
+\fBTcl_TraceCommand\fR allows a C procedure to monitor operations
+performed on a Tcl command, so that the C procedure is invoked
+whenever the command is renamed or deleted.  If the trace is created
+successfully then \fBTcl_TraceCommand\fR returns \fBTCL_OK\fR. If an error
+occurred (e.g. \fIcmdName\fR specifies a non-existent command) then
+\fBTCL_ERROR\fR is returned and an error message is left in the
+interpreter's result.
+.PP
+The \fIflags\fR argument to \fBTcl_TraceCommand\fR indicates when the
+trace procedure is to be invoked.  It consists of an OR'ed combination
+of any of the following values:
+.TP
+\fBTCL_TRACE_RENAME\fR
+Invoke \fIproc\fR whenever the command is renamed.
+.TP
+\fBTCL_TRACE_DELETE\fR
+Invoke \fIproc\fR when the command is deleted.
+.PP
+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:
+.CS
+typedef void Tcl_CommandTraceProc(
+        ClientData \fIclientData\fR,
+        Tcl_Interp *\fIinterp\fR,
+        const char *\fIoldName\fR,
+        const char *\fInewName\fR,
+        int \fIflags\fR);
+.CE
+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
+data structure that describes what to do when \fIproc\fR is invoked.
+\fIOldName\fR gives the name of the command being renamed, and
+\fInewName\fR gives the name that the command is being renamed to (or
+an empty string or NULL when the command is being deleted.)
+\fIFlags\fR is an OR'ed combination of bits potentially providing
+several pieces of information.  One of the bits \fBTCL_TRACE_RENAME\fR and
+\fBTCL_TRACE_DELETE\fR will be set in \fIflags\fR to indicate which
+operation is being performed on the command.  The bit
+\fBTCL_TRACE_DESTROYED\fR will be set in \fIflags\fR if the trace is about
+to be destroyed; this information may be useful to \fIproc\fR so that
+it can clean up its own internal data structures (see the section
+\fBTCL_TRACE_DESTROYED\fR below for more details).  Lastly, the bit
+\fBTCL_INTERP_DESTROYED\fR will be set if the entire interpreter is being
+destroyed.  When this bit is set, \fIproc\fR must be especially
+careful in the things it does (see the section \fBTCL_INTERP_DESTROYED\fR
+below).
+.PP
+\fBTcl_UntraceCommand\fR may be used to remove a trace.  If the
+command specified by \fIinterp\fR, \fIcmdName\fR, and \fIflags\fR has
+a trace set with \fIflags\fR, \fIproc\fR, and \fIclientData\fR, then
+the corresponding trace is removed.  If no such trace exists, then the
+call to \fBTcl_UntraceCommand\fR has no effect.  The same bits are
+valid for \fIflags\fR as for calls to \fBTcl_TraceCommand\fR.
+.PP
+\fBTcl_CommandTraceInfo\fR may be used to retrieve information about
+traces set on a given command.
+The return value from \fBTcl_CommandTraceInfo\fR is the \fIclientData\fR
+associated with a particular trace.
+The trace must be on the command specified by the \fIinterp\fR,
+\fIcmdName\fR, and \fIflags\fR arguments (note that currently the
+flags are ignored; \fIflags\fR should be set to 0 for future
+compatibility) and its trace procedure must the same as the \fIproc\fR
+argument.
+If the \fIprevClientData\fR argument is NULL then the return
+value corresponds to the first (most recently created) matching
+trace, or NULL if there are no matching traces.
+If the \fIprevClientData\fR argument is not NULL, then it should
+be the return value from a previous call to \fBTcl_CommandTraceInfo\fR.
+In this case, the new return value will correspond to the next
+matching trace after the one whose \fIclientData\fR matches
+\fIprevClientData\fR, or NULL if no trace matches \fIprevClientData\fR
+or if there are no more matching traces after it.
+This mechanism makes it possible to step through all of the
+traces for a given command that have the same \fIproc\fR.
+.SH "CALLING COMMANDS DURING TRACES"
+.PP
+During rename traces, the command being renamed is visible with both
+names simultaneously, and the command still exists during delete
+traces (if \fBTCL_INTERP_DESTROYED\fR is not set).  However, there is no
+mechanism for signaling that an error occurred in a trace procedure,
+so great care should be taken that errors do not get silently lost.
+.SH "MULTIPLE TRACES"
+.PP
+It is possible for multiple traces to exist on the same command.
+When this happens, all of the trace procedures will be invoked on each
+access, in order from most-recently-created to least-recently-created.
+Attempts to delete the command during a delete trace will fail
+silently, since the command is already scheduled for deletion anyway.
+If the command being renamed is renamed by one of its rename traces,
+that renaming takes precedence over the one that triggered the trace
+and the collection of traces will not be reexecuted; if several traces
+rename the command, the last renaming takes precedence.
+.SH "TCL_TRACE_DESTROYED FLAG"
+.PP
+In a delete callback to \fIproc\fR, the \fBTCL_TRACE_DESTROYED\fR bit
+is set in \fIflags\fR.
+.\" Perhaps need some more comments here? - DKF
+.SH "TCL_INTERP_DESTROYED"
+.PP
+When an interpreter is destroyed, unset traces are called for
+all of its commands.
+The \fBTCL_INTERP_DESTROYED\fR bit will be set in the \fIflags\fR
+argument passed to the trace procedures.
+Trace procedures must be extremely careful in what they do if
+the \fBTCL_INTERP_DESTROYED\fR bit is set.
+It is not safe for the procedures to invoke any Tcl procedures
+on the interpreter, since its state is partially deleted.
+All that trace procedures should do under these circumstances is
+to clean up and free their own internal data structures.
+.SH BUGS
+.PP
+Tcl does not do any error checking to prevent trace procedures
+from misusing the interpreter during traces with \fBTCL_INTERP_DESTROYED\fR
+set.
+.SH KEYWORDS
+clientData, trace, command