Finished user-level documentation backport

1 files changed, 23 insertions, 3 deletions

diff --git a/doc/uplevel.n b/doc/uplevel.n
index 0d3bf6e..df4db5b 100644
--- a/doc/uplevel.n
+++ b/doc/uplevel.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: uplevel.n,v 1.3 2000/09/07 14:27:52 poenitz Exp $
+'\" RCS: @(#) $Id: uplevel.n,v 1.3.18.1 2004/10/27 14:43:15 dkf Exp $
 '\" 
 .so man.macros
 .TH uplevel n "" Tcl "Tcl Built-In Commands"
@@ -44,14 +44,14 @@ The \fBuplevel\fR command causes the invoking procedure to disappear
 from the procedure calling stack while the command is being executed.
 In the above example, suppose \fBc\fR invokes the command
 .CS
-\fBuplevel 1 {set x 43; d}\fR
+\fBuplevel\fR 1 {set x 43; d}
 .CE
 where \fBd\fR is another Tcl procedure.  The \fBset\fR command will
 modify the variable \fBx\fR in \fBb\fR's context, and \fBd\fR will execute
 at level 3, as if called from \fBb\fR.  If it in turn executes
 the command
 .CS
-\fBuplevel {set x 42}\fR
+\fBuplevel\fR {set x 42}
 .CE
 then the \fBset\fR command will modify the same variable \fBx\fR in \fBb\fR's
 context:  the procedure \fBc\fR does not appear to be on the call stack
@@ -72,6 +72,26 @@ describing a command that is either
 the outermost procedure call or the outermost \fBnamespace eval\fR command.
 Also, \fBuplevel #0\fR evaluates a script
 at top-level in the outermost namespace (the global namespace).
+.SH EXAMPLE
+As stated above, the \fBuplevel\fR command is useful for creating new
+control constructs.  This example shows how (without error handling)
+it can be used to create a \fBdo\fR command that is the counterpart of
+\fBwhile\fR except for always performing the test after running the
+loop body:
+.CS
+proc do {body while condition} {
+    if {$while ne "while"} {
+        error "required word missing"
+    }
+    set conditionCmd [list expr $condition]
+    while {1} {
+        \fBuplevel\fR 1 $body
+        if {![\fBuplevel\fR 1 $conditionCmd]} {
+            break
+        }
+    }
+}
+.CE
 
 .SH "SEE ALSO"
 namespace(n), upvar(n)