summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2007-12-13 11:10:13 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2007-12-13 11:10:13 (GMT)
commit6e47a3ff9a5adbccedc0346d443f6c4aac9c09c6 (patch)
tree13bf431c9f1dfacd1f325cae9d021625e2bbfab0 /doc
parente43b853122c93adaf440e35c97fc76bd8dc896af (diff)
downloadtcl-6e47a3ff9a5adbccedc0346d443f6c4aac9c09c6.zip
tcl-6e47a3ff9a5adbccedc0346d443f6c4aac9c09c6.tar.gz
tcl-6e47a3ff9a5adbccedc0346d443f6c4aac9c09c6.tar.bz2
Clarified documentation of enterstep and leavestep traces. [Bug 1701540]
Diffstat (limited to 'doc')
-rw-r--r--doc/trace.n36
1 files changed, 20 insertions, 16 deletions
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