1 files changed, 21 insertions, 42 deletions
diff --git a/doc/TraceCmd.3 b/doc/TraceCmd.3
index 10714a1..99914a6 100644
--- a/doc/TraceCmd.3
+++ b/doc/TraceCmd.3
@@ -3,11 +3,9 @@
 '\"
 '\" 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"
+.so man.macros
 .BS
 .SH NAME
 Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand \- monitor renames and deletes of a command
@@ -30,7 +28,7 @@ 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
+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.
@@ -41,7 +39,6 @@ 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
@@ -53,7 +50,7 @@ occurred (e.g. \fIcmdName\fR specifies a non-existent command) then
 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
+trace procedure is to be invoked.  It consists of an OR'ed combination
 of any of the following values:
 .TP
 \fBTCL_TRACE_RENAME\fR
@@ -65,33 +62,38 @@ 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 Tcl_CommandTraceProc(
+typedef void \fBTcl_CommandTraceProc\fR(
         ClientData \fIclientData\fR,
         Tcl_Interp *\fIinterp\fR,
         const char *\fIoldName\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
 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
+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).
+\fBTCL_TRACE_DESTROYED\fR below for more details).  Because the
+deletion of commands can take place as part of the deletion of the interp
+that contains them, \fIproc\fR must be careful about checking what
+the passed in \fIinterp\fR value can be called upon to do.
+The routine \fBTcl_InterpDeleted\fR is an important tool for this.
+When \fBTcl_InterpDeleted\fR returns 1, \fIproc\fR will not be able
+to invoke any scripts in \fIinterp\fR.  The function of \fIproc\fR
+in that circumstance is limited to the cleanup of its own data structures.
 .PP
 \fBTcl_UntraceCommand\fR may be used to remove a trace.  If the
 command specified by \fIinterp\fR, \fIcmdName\fR, and \fIflags\fR has
@@ -112,7 +114,7 @@ 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
+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
@@ -120,15 +122,14 @@ matching trace after the one whose \fIclientData\fR matches
 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
+traces, unless the interp that contains it is being deleted.
+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.
@@ -140,32 +141,10 @@ 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.
-
+.\" Perhaps need some more comments here? - DKF
 .SH KEYWORDS
 clientData, trace, command