Added example, cross-references, and a note that {expand} is usually a

better choice!

1 files changed, 31 insertions, 2 deletions

diff --git a/doc/eval.n b/doc/eval.n
index 76c37f2..f027c76 100644
--- a/doc/eval.n
+++ b/doc/eval.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: eval.n,v 1.4 2002/08/28 14:46:50 dkf Exp $
+'\" RCS: @(#) $Id: eval.n,v 1.5 2004/05/28 10:37:04 dkf Exp $
 '\" 
 .so man.macros
 .TH eval n "" Tcl "Tcl Built-In Commands"
@@ -27,9 +27,38 @@ Tcl interpreter recursively, and returns the result of that
 evaluation (or any error generated by it).
 Note that the \fBlist\fR command quotes sequences of words in such a
 way that they are not further expanded by the \fBeval\fR command.
+.SH EXAMPLE
+Often, it is useful to store a fragment of a script in a variable and
+execute it later on with extra values appended. This technique is used
+in a number of places throughout the Tcl core (e.g. in \fBfcopy\fR,
+\fBlsort\fR and \fBtrace\fR command callbacks). This example shows how
+to do this using core Tcl commands:
+.CS
+set script {
+    puts "logging now"
+    lappend $myCurrentLogVar
+}
+set myCurrentLogVar log1
+# Set up a switch of logging variable part way through!
+after 20000 set myCurrentLogVar log2
+
+for {set i 0} {$i<10} {incr i} {
+    # Introduce a random delay
+    after [expr {int(5000 * rand())}]
+    update    ;# Check for the asynch log switch
+    eval $script $i [clock clicks]
+}
+.CE
+.VS 8.5
+Note that in the most common case (where the script fragment is
+actually just a list of words forming a command prefix), it is better
+to use \fB{expand}$script\fR when doing this sort of invokation
+pattern.  It is less general than the \fBeval\fR command, and hence
+easier to make robust in practice.
+.VE 8.5
 
 .SH KEYWORDS
 concatenate, evaluate, script
 
 .SH "SEE ALSO"
-catch(n), concat(n), error(n), list(n), subst(n), tclvars(n)
+catch(n), concat(n), error(n), interp(n), list(n), namespace(n), subst(n), tclvars(n), uplevel(n)