summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--ChangeLog5
-rw-r--r--doc/trace.n36
2 files changed, 25 insertions, 16 deletions
diff --git a/ChangeLog b/ChangeLog
index 3622807..98a1365 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2007-12-13 Donal K. Fellows <donal.k.fellows@manchester.ac.uk>
+
+ * doc/trace.n: Clarified documentation of enterstep and leavestep
+ traces. [Bug 1701540]
+
2007-12-12 Don Porter <dgp@users.sourceforge.net>
* doc/IntObj.3: Update docs for the Tcl_GetBignumAndClearObj() ->
diff --git a/doc/trace.n b/doc/trace.n
index 2b69afc..781921a 100644
--- a/doc/trace.n
+++ b/doc/trace.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: trace.n,v 1.22 2007/10/29 01:42:19 dkf Exp $
+'\" RCS: @(#) $Id: trace.n,v 1.23 2007/12/13 11:10:20 dkf Exp $
'\"
.so man.macros
.TH trace n "8.4" Tcl "Tcl Built-In Commands"
@@ -92,34 +92,38 @@ Invoke \fIcommand\fR whenever the command \fIname\fR is executed,
just after the actual execution takes place.
.TP
\fBenterstep\fR
-Invoke \fIcommand\fR for every Tcl command which is executed
-inside the procedure \fIname\fR, just before the actual execution
-takes place. For example if we have
+.
+Invoke \fIcommand\fR for every Tcl command which is executed from the
+start of the execution of the procedure \fIname\fR until that
+procedure finishes. \fICommand\fR is invoked just before the actual
+execution of the Tcl command being reported takes place. For example
+if we have
.QW "proc foo {} { puts \N'34'hello\N'34' }" ,
-then an \fIenterstep\fR trace would be
-invoked just before
+then an \fIenterstep\fR trace would be invoked just before
.QW "\fIputs \N'34'hello\N'34'\fR"
is executed.
-Setting an \fIenterstep\fR trace on a \fIcommand\fR
+Setting an \fIenterstep\fR trace on a \fIcommand\fR that is not a procedure
will not result in an error and is simply ignored.
.TP
\fBleavestep\fR
-Invoke \fIcommand\fR for every Tcl command which is executed
-inside the procedure \fIname\fR, just after the actual execution
-takes place.
-Setting a \fIleavestep\fR trace on a \fIcommand\fR
-will not result in an error and is simply ignored.
+.
+Invoke \fIcommand\fR for every Tcl command which is executed from the
+start of the execution of the procedure \fIname\fR until that
+procedure finishes. \fICommand\fR is invoked just after the actual
+execution of the Tcl command being reported takes place.
+Setting a \fIleavestep\fR trace on a \fIcommand\fR that is not a
+procedure will not result in an error and is simply ignored.
.PP
-When the trace triggers, depending on the operations being traced, a
-number of arguments are appended to \fIcommand\fR so that the actual
+When the trace triggers, depending on the operations being traced, a
+number of arguments are appended to \fIcommand\fR so that the actual
command is as follows:
.PP
For \fBenter\fR and \fBenterstep\fR operations:
.CS
\fIcommand command-string op\fR
.CE
-\fICommand-string\fR gives the complete current command being
-executed (the traced command for a \fBenter\fR operation, an
+\fICommand-string\fR gives the complete current command being
+executed (the traced command for a \fBenter\fR operation, an
arbitrary command for a \fBenterstep\fR operation), including
all arguments in their fully expanded form.
\fIOp\fR indicates what operation is being performed on the