Clarified documentation of enterstep and leavestep traces. [Bug 1701540]

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