From 6e47a3ff9a5adbccedc0346d443f6c4aac9c09c6 Mon Sep 17 00:00:00 2001 From: dkf Date: Thu, 13 Dec 2007 11:10:13 +0000 Subject: Clarified documentation of enterstep and leavestep traces. [Bug 1701540] --- ChangeLog | 5 +++++ doc/trace.n | 36 ++++++++++++++++++++---------------- 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 + + * doc/trace.n: Clarified documentation of enterstep and leavestep + traces. [Bug 1701540] + 2007-12-12 Don Porter * 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 -- cgit v0.12