More examples

4 files changed, 67 insertions, 3 deletions

diff --git a/ChangeLog b/ChangeLog
index 4cdeca7..380c20f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2004-04-30  Donal K. Fellows  <donal.k.fellows@man.ac.uk>
+
+	* doc/if.n, doc/rename.n, doc/time.n: More examples.
+
 2004-04-30  Don Porter  <dgp@users.sourceforge.net>
 
 	* generic/tclInt.h:		Replaced Kevin Kenny's temporary
diff --git a/doc/if.n b/doc/if.n
index 7f9032f..90ae0ce 100644
--- a/doc/if.n
+++ b/doc/if.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: if.n,v 1.3 2000/09/07 14:27:48 poenitz Exp $
+'\" RCS: @(#) $Id: if.n,v 1.4 2004/04/30 20:25:26 dkf Exp $
 '\" 
 .so man.macros
 .TH if n "" Tcl "Tcl Built-In Commands"
@@ -38,6 +38,41 @@ There may be any number of \fBelseif\fR clauses, including zero.
 The return value from the command is the result of the body script
 that was executed, or an empty string
 if none of the expressions was non-zero and there was no \fIbodyN\fR.
+.SH EXAMPLES
+A simple conditional:
+.CS
+if {$vbl == 1} { puts "vbl is one" }
+.CE
+
+With an \fBelse\fR-clause:
+.CS
+if {$vbl == 1} {
+   puts "vbl is one"
+} else {
+   puts "vbl is not one"
+}
+.CE
+
+With an \fBelseif\fR-clause too:
+.CS
+if {$vbl == 1} {
+   puts "vbl is one"
+} elseif {$vbl == 2} {
+   puts "vbl is two"
+} else {
+   puts "vbl is not one or two"
+}
+.CE
+
+Remember, expressions can be multi-line, but in that case it can be a
+good idea to use the optional \fBthen\fR keyword for clarity:
+.CS
+if {
+   $vbl == 1 || $vbl == 2 || $vbl == 3
+} then {
+   puts "vbl is one, two or three"
+}
+.CE
 
 .SH "SEE ALSO"
 expr(n), for(n), foreach(n)
diff --git a/doc/rename.n b/doc/rename.n
index 2630ad4..96e0507 100644
--- a/doc/rename.n
+++ b/doc/rename.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: rename.n,v 1.3 2000/09/07 14:27:51 poenitz Exp $
+'\" RCS: @(#) $Id: rename.n,v 1.4 2004/04/30 20:25:26 dkf Exp $
 '\" 
 .so man.macros
 .TH rename n "" Tcl "Tcl Built-In Commands"
@@ -27,6 +27,20 @@ If \fInewName\fR is an empty string then \fIoldName\fR is deleted.
 If a command is renamed into a different namespace,
 future invocations of it will execute in the new namespace.
 The \fBrename\fR command returns an empty string as result.
+.SH EXAMPLE
+The \fBrename\fR command can be used to wrap the standard Tcl commands
+with your own monitoring machinery.  For example, you might wish to
+count how often the \fBsource\fR command is called:
+
+.CS
+rename ::source ::theRealSource
+set sourceCount 0
+proc ::source args {
+    global sourceCount
+    puts "called source for the [incr sourceCount]'th time"
+    uplevel 1 ::theRealSource $args
+}
+.CE
 
 .SH "SEE ALSO"
 namespace(n), proc(n)
diff --git a/doc/time.n b/doc/time.n
index 11d123f..31965bb 100644
--- a/doc/time.n
+++ b/doc/time.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: time.n,v 1.3 2000/09/07 14:27:52 poenitz Exp $
+'\" RCS: @(#) $Id: time.n,v 1.4 2004/04/30 20:25:26 dkf Exp $
 '\" 
 .so man.macros
 .TH time n "" Tcl "Tcl Built-In Commands"
@@ -28,6 +28,17 @@ specified).  It will then return a string of the form
 which indicates the average amount of time required per iteration,
 in microseconds.
 Time is measured in elapsed time, not CPU time.
+.SH EXAMPLE
+Estimate how long it takes for a simple Tcl \fBfor\fR loop to count to
+a thousand:
+
+.CS
+time {
+    for {set i 0} {$i<1000} {incr i} {
+        # empty body
+    }
+}
+.CE
 
 .SH "SEE ALSO"
 clock(n)