Finished user-level documentation backport

1 files changed, 32 insertions, 9 deletions

diff --git a/doc/trace.n b/doc/trace.n
index b81d275..377d257 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.13.2.1 2003/10/08 17:51:07 dgp Exp $
+'\" RCS: @(#) $Id: trace.n,v 1.13.2.2 2004/10/27 14:43:14 dkf Exp $
 '\" 
 .so man.macros
 .TH trace n "8.4" Tcl "Tcl Built-In Commands"
@@ -90,16 +90,16 @@ 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 
+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 'proc foo {} { puts "hello" }',
-then a \fIenterstep\fR trace would be 
+then an \fIenterstep\fR trace would be 
 invoked just before \fIputs "hello"\fR is executed.
-Setting a \fIenterstep\fR trace on a \fIcommand\fR
+Setting an \fIenterstep\fR trace on a \fIcommand\fR
 will not result in an error and is simply ignored.
 .TP
 \fBleavestep\fR
-Invoke \fIcommand\fR for every tcl command which is executed 
+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
@@ -141,7 +141,7 @@ Note that the creation of many \fBenterstep\fR or
 \fBleavestep\fR traces can lead to unintuitive results, since the
 invoked commands from one trace can themselves lead to further
 command invocations for other traces.
-
+.PP
 \fICommand\fR executes in the same context as the code that invoked
 the traced operation: thus the \fIcommand\fR, if invoked from a procedure,
 will have access to the same local variables as code in the procedure.
@@ -149,19 +149,19 @@ This context may be different than the context in which the trace was
 created. If \fIcommand\fR invokes a procedure (which it normally does)
 then the procedure will have to use upvar or uplevel commands if it wishes
 to access the local variables of the code which invoked the trace operation.
-
+.PP
 While \fIcommand\fR is executing during an execution trace, traces
 on \fIname\fR are temporarily disabled. This allows the \fIcommand\fR
 to execute \fIname\fR in its body without invoking any other traces again.
 If an error occurs while executing the \fIcommand\fR body, then the
 command \fIname\fR as a whole will return that same error.
-
+.PP
 When multiple traces are set on \fIname\fR, then for \fIenter\fR
 and \fIenterstep\fR operations, the traced commands are invoked
 in the reverse order of how the traces were originally created;
 and for \fIleave\fR and \fIleavestep\fR operations, the traced
 commands are invoked in the original order of creation.
-
+.PP
 The behavior of execution traces is currently undefined for a command 
 \fIname\fR imported into another namespace.
 .RE
@@ -354,6 +354,29 @@ future version of Tcl.  They use an older syntax in which \fBarray\fR,
 \fBw\fR and \fBu\fR respectively, and the \fIops\fR argument is not a
 list, but simply a string concatenation of the operations, such as
 \fBrwua\fR.
+.SH EXAMPLES
+Print a message whenever either of the global variables \fBfoo\fR and
+\fBbar\fR are updated, even if they have a different local name at the
+time (which can be done with the \fBupvar\fR command):
+.CS
+proc tracer {varname args} {
+    upvar #0 $varname var
+    puts "$varname was updated to be \e"$var\e""
+}
+\fBtrace add\fR variable foo write "tracer foo"
+\fBtrace add\fR variable bar write "tracer bar"
+.CE
+.PP
+Ensure that the global variable \fBfoobar\fR always contains the
+product of the global variables \fBfoo\fR and \fBbar\fR:
+.CS
+proc doMult args {
+    global foo bar foobar
+    set foobar [expr {$foo * $bar}]
+}
+\fBtrace add\fR variable foo write doMult
+\fBtrace add\fR variable bar write doMult
+.CE
 
 .SH "SEE ALSO"
 set(n), unset(n)