Finished user-level documentation backport

13 files changed, 275 insertions, 70 deletions

diff --git a/doc/tcltest.n b/doc/tcltest.n
index b019def..64b3dd4 100644
--- a/doc/tcltest.n
+++ b/doc/tcltest.n
@@ -8,7 +8,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: tcltest.n,v 1.38.2.4 2004/02/18 01:43:49 dgp Exp $
+'\" RCS: @(#) $Id: tcltest.n,v 1.38.2.5 2004/10/27 14:43:13 dkf Exp $
 '\" 
 .so man.macros
 .TH "tcltest" n 2.2 tcltest "Tcl Bundled Packages"
@@ -378,7 +378,7 @@ also influence how [\fBtest\fR] operates.
 The valid options for [\fBtest\fR] are summarized:
 .CS
 .ta 0.8i
-test \fIname\fR \fIdescription\fR
+\fBtest\fR \fIname\fR \fIdescription\fR
 	?-constraints \fIkeywordList|expression\fR?
 	?-setup \fIsetupScript\fR?
 	?-body \fItestScript\fR?
@@ -663,7 +663,7 @@ only constraints from the [\fBconfigure -constraints\fR] list
 are run; all others are skipped.  For example, one might set
 up a configuration with
 .CS
-configure -constraints knownBug \e
+\fBconfigure\fR -constraints knownBug \e
           -limitconstraints true \e
           -verbose pass
 .CE
@@ -683,7 +683,7 @@ that match any of the patterns in [\fBconfigure -file\fR] and
 match none of the patterns in [\fBconfigure -notfile\fR] is generated
 and sorted.  Then each file will be evaluated in turn.  If
 [\fBconfigure -singleproc\fR] is true, then each file will
-be [\fBsource\fR]d in the caller's context.  If if is false,
+be [\fBsource\fR]d in the caller's context.  If it is false,
 then a copy of [\fBinterpreter\fR] will be [\fBexec\fR]d to
 evaluate each file.  The multi-process operation is useful
 when testing can cause errors so severe that a process 
@@ -873,7 +873,7 @@ command.  We begin with several examples.
 .IP [1]
 Test of a script that returns normally.
 .CS
-test example-1.0 {normal return} {
+\fBtest\fR example-1.0 {normal return} {
     format %s value
 } value
 .CE
@@ -881,7 +881,7 @@ test example-1.0 {normal return} {
 Test of a script that requires context setup and cleanup.  Note the
 bracing and indenting style that avoids any need for line continuation.
 .CS
-test example-1.1 {test file existence} -setup {
+\fBtest\fR example-1.1 {test file existence} -setup {
     set file [makeFile {} test]
 } -body {
     file exists $file
@@ -892,14 +892,14 @@ test example-1.1 {test file existence} -setup {
 .IP [3]
 Test of a script that raises an error.
 .CS
-test example-1.2 {error return} -body {
+\fBtest\fR example-1.2 {error return} -body {
     error message
 } -returnCodes error -result message
 .CE
 .IP [4]
 Test with a constraint.
 .CS
-test example-1.3 {user owns created files} -constraints {
+\fBtest\fR example-1.3 {user owns created files} -constraints {
     unix
 } -setup {
     set file [makeFile {} test]
@@ -923,8 +923,8 @@ Use constraints to skip tests, rather than conditional evaluation
 of [\fBtest\fR].  That is, do this:
 .IP [5]
 .CS
-testConstraint X [expr $myRequirement]
-test goodConditionalTest {} X {
+\fBtestConstraint\fR X [expr $myRequirement]
+\fBtest\fR goodConditionalTest {} X {
     # body
 } result
 .CE
@@ -967,23 +967,23 @@ should be called.
 Here is a sketch of a sample test file illustrating those points:
 .CS
 package require tcltest 2.2
-eval tcltest::configure $argv
+eval \fB::tcltest::configure\fR $argv
 package require example
 namespace eval ::example::test {
     namespace import ::tcltest::*
-    testConstraint X [expr {...}]
+    \fBtestConstraint\fR X [expr {...}]
     variable SETUP {#common setup code}
     variable CLEANUP {#common cleanup code}
-    test example-1 {} -setup $SETUP -body {
+    \fBtest\fR example-1 {} -setup $SETUP -body {
 	# First test
     } -cleanup $CLEANUP -result {...}
-    test example-2 {} -constraints X -setup $SETUP -body {
+    \fBtest\fR example-2 {} -constraints X -setup $SETUP -body {
 	# Second test; constrained
     } -cleanup $CLEANUP -result {...}
-    test example-3 {} {
+    \fBtest\fR example-3 {} {
 	# Third test; no context required
     } {...}
-    cleanupTests
+    \fBcleanupTests\fR
 }
 namespace delete ::example::test
 .CE
@@ -1000,10 +1000,10 @@ Here is a sketch of a sample test suite master script:
 package require Tcl 8.4
 package require tcltest 2.2
 package require example
-tcltest::configure -testdir \
+\fB::tcltest::configure\fR -testdir \
         [file dirname [file normalize [info script]]]
-eval tcltest::configure $argv
-tcltest::runAllTests
+eval \fB::tcltest::configure\fR $argv
+\fB::tcltest::runAllTests\fR
 .CE
 .SH COMPATIBILITY
 .PP
@@ -1021,7 +1021,7 @@ that depend on the old behavior that \fBtcltest\fR was automatically
 configured from command line arguments.  New test files should not
 depend on this, but should explicitly include
 .CS
-eval tcltest::configure $::argv
+eval \fB::tcltest::configure\fR $::argv
 .CE
 to establish a configuration from command line arguments.
 .SH "KNOWN ISSUES"
@@ -1030,9 +1030,9 @@ The first issue relates to the stack level in which test scripts are
 executed.  Tests nested within other tests may be executed at the same
 stack level as the outermost test.  For example, in the following code: 
 .CS
-test level-1.1 {level 1} {
+\fBtest\fR level-1.1 {level 1} {
     -body {
-        test level-2.1 {level 2} {
+        \fBtest\fR level-2.1 {level 2} {
         }
     }
 }
diff --git a/doc/tclvars.n b/doc/tclvars.n
index 92de6a5..f3c58f4 100644
--- a/doc/tclvars.n
+++ b/doc/tclvars.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: tclvars.n,v 1.13 2002/07/01 18:24:39 jenglish Exp $
+'\" RCS: @(#) $Id: tclvars.n,v 1.13.2.1 2004/10/27 14:43:14 dkf Exp $
 '\" 
 .so man.macros
 .TH tclvars n 8.0 Tcl "Tcl Built-In Commands"
@@ -247,7 +247,6 @@ be defined, but they may have empty strings as values if Tcl couldn't
 retrieve any relevant information.  In addition, extensions
 and applications may add additional values to the array.  The
 predefined elements are:
-
 .RS
 .VS
 .TP
@@ -257,10 +256,11 @@ The native byte order of this machine: either \fBlittleEndian\fR or
 .VE
 .TP
 \fBdebug\fR
-If this variable exists, then the interpreter
-was compiled with debugging symbols enabled.  This variable will only
-exist on Windows so extension writers can specify which package to load
-depending on the C run-time library that is loaded.
+If this variable exists, then the interpreter was compiled with and linked
+to a debug-enabled C run-time.  This variable will only exist on Windows,
+so extension writers can specify which package to load depending on the
+C run-time library that is in use.  This is not an indication that this core
+contains symbols.
 .TP
 \fBmachine\fR
 The instruction set executed by this machine, such as
@@ -343,24 +343,24 @@ The value of this variable can be set to control
 how much tracing information
 is displayed during bytecode compilation.
 By default, tcl_traceCompile is zero and no information is displayed.
-Setting tcl_traceCompile to 1 generates a one line summary in stdout
-whenever a procedure or top level command is compiled.
+Setting tcl_traceCompile to 1 generates a one-line summary in stdout
+whenever a procedure or top-level command is compiled.
 Setting it to 2 generates a detailed listing in stdout of the
 bytecode instructions emitted during every compilation.
 This variable is useful in
 tracking down suspected problems with the Tcl compiler.
 It is also occasionally useful when converting
 existing code to use Tcl8.0.
-
+.PP
 This variable and functionality only exist if
-TCL_COMPILE_DEBUG was defined during Tcl's compilation.
+\fBTCL_COMPILE_DEBUG\fR was defined during Tcl's compilation.
 .TP
 \fBtcl_traceExec\fR
 The value of this variable can be set to control
 how much tracing information
 is displayed during bytecode execution.
 By default, tcl_traceExec is zero and no information is displayed.
-Setting tcl_traceExec to 1 generates a one line trace in stdout
+Setting tcl_traceExec to 1 generates a one-line trace in stdout
 on each call to a Tcl procedure.
 Setting it to 2 generates a line of output
 whenever any Tcl command is invoked
@@ -368,7 +368,7 @@ that contains the name of the command and its arguments.
 Setting it to 3 produces a detailed trace showing the result of
 executing each bytecode instruction.
 Note that when tcl_traceExec is 2 or 3,
-commands such as set and incr
+commands such as \fBset\fR and \fBincr\fR
 that have been entirely replaced by a sequence
 of bytecode instructions are not shown.
 Setting this variable is useful in
@@ -376,9 +376,9 @@ tracking down suspected problems with the bytecode compiler
 and interpreter.
 It is also occasionally useful when converting
 code to use Tcl8.0.
-
+.PP
 This variable and functionality only exist if
-TCL_COMPILE_DEBUG was defined during Tcl's compilation.
+\fBTCL_COMPILE_DEBUG\fR was defined during Tcl's compilation.
 .TP
 \fBtcl_wordchars\fR
 The value of this variable is a regular expression that can be set to
diff --git a/doc/tell.n b/doc/tell.n
index c9475ed..134ae36 100644
--- a/doc/tell.n
+++ b/doc/tell.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: tell.n,v 1.5 2001/09/14 19:20:40 andreas_kupries Exp $
+'\" RCS: @(#) $Id: tell.n,v 1.5.8.1 2004/10/27 14:43:14 dkf Exp $
 '\" 
 .so man.macros
 .TH tell n 8.1 Tcl "Tcl Built-In Commands"
@@ -34,6 +34,19 @@ Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR),
 the return value from an invocation of \fBopen\fR or \fBsocket\fR, or
 the result of a channel creation command provided by a Tcl extension.
 .VE
+.SH EXAMPLE
+Read a line from a file channel only if it starts with \fBfoobar\fR:
+.CS
+# Save the offset in case we need to undo the read...
+set offset [\fBtell\fR $chan]
+if {[read $chan 6] eq "foobar"} {
+    gets $chan line
+} else {
+    set line {}
+    # Undo the read...
+    seek $chan $offset
+}
+.CE
 
 .SH "SEE ALSO"
 file(n), open(n), close(n), gets(n), seek(n), Tcl_StandardChannels(3)
diff --git a/doc/time.n b/doc/time.n
index 11d123f..8eeab73 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.3.18.1 2004/10/27 14:43:14 dkf Exp $
 '\" 
 .so man.macros
 .TH time n "" Tcl "Tcl Built-In Commands"
@@ -28,6 +28,16 @@ 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)
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)
diff --git a/doc/unknown.n b/doc/unknown.n
index 2ef5b14..bb7549b 100644
--- a/doc/unknown.n
+++ b/doc/unknown.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: unknown.n,v 1.4 2001/06/27 21:00:45 hobbs Exp $
+'\" RCS: @(#) $Id: unknown.n,v 1.4.12.1 2004/10/27 14:43:15 dkf Exp $
 '\" 
 .so man.macros
 .TH unknown n "" Tcl "Tcl Built-In Commands"
@@ -71,6 +71,20 @@ auto-exec step is skipped.
 Under normal circumstances the return value from \fBunknown\fR
 is the return value from the command that was eventually
 executed.
+.SH EXAMPLE
+Arrange for the \fBunknown\fR command to have its standard behavior
+except for first logging the fact that a command was not found:
+.PP
+.CS
+# Save the original one so we can chain to it
+rename \fBunknown\fR _original_unknown
+
+# Provide our own implementation
+proc \fBunknown\fR args {
+    puts stderr "WARNING: unknown command: $args"
+    uplevel 1 [list _original_unknown {expand}$args]
+}
+.CE
 
 .SH "SEE ALSO"
 info(n), proc(n), interp(n), library(n)
diff --git a/doc/unset.n b/doc/unset.n
index e68c3f2..47124e9 100644
--- a/doc/unset.n
+++ b/doc/unset.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: unset.n,v 1.5.18.1 2004/05/07 22:29:05 msofer Exp $
+'\" RCS: @(#) $Id: unset.n,v 1.5.18.2 2004/10/27 14:43:15 dkf Exp $
 '\" 
 .so man.macros
 .TH unset n 8.4 Tcl "Tcl Built-In Commands"
@@ -39,9 +39,30 @@ If an error occurs, any variables after the named one causing the error not
 deleted.  An error can occur when the named variable doesn't exist, or the
 name refers to an array element but the variable is a scalar, or the name
 refers to a variable in a non-existent namespace.
+.SH EXAMPLE
+Create an array containing a mapping from some numbers to their
+squares and remove the array elements for non-prime numbers:
+.CS
+array set squares {
+    1 1    6 36
+    2 4    7 49
+    3 9    8 64
+    4 16   9 81
+    5 25  10 100
+}
+
+puts "The squares are:"
+parray squares
+
+\fBunset\fR squares(1) squares(4) squares(6)
+\fBunset\fR squares(8) squares(9) squares(10)
+
+puts "The prime squares are:"
+parray squares
+.CE
 
 .SH "SEE ALSO"
-set(n), trace(n), unset(n)
+set(n), trace(n), upvar(n)
 
 .SH KEYWORDS
 remove, variable
diff --git a/doc/update.n b/doc/update.n
index 87c2a7d..162c859 100644
--- a/doc/update.n
+++ b/doc/update.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: update.n,v 1.4 2000/09/07 14:27:52 poenitz Exp $
+'\" RCS: @(#) $Id: update.n,v 1.4.18.1 2004/10/27 14:43:15 dkf Exp $
 '\" 
 .so man.macros
 .TH update n 7.5 Tcl "Tcl Built-In Commands"
@@ -43,6 +43,22 @@ you are performing a long-running computation but you still want
 the application to respond to events such as user interactions;  if
 you occasionally call \fBupdate\fR then user input will be processed
 during the next call to \fBupdate\fR.
+.SH EXAMPLE
+Run computations for about a second and then finish:
+.CS
+set x 1000
+set done 0
+after 1000 set done 1
+while {!$done} {
+    # A very silly example!
+    set x [expr {log($x) ** 2.8}]
+
+    # Test to see if our time-limit has been hit.  This would
+    # also give a chance for serving network sockets and, if
+    # the Tk package is loaded, updating a user interface.
+    \fBupdate\fR
+}
+.CE
 
 .SH "SEE ALSO"
 after(n), bgerror(n)
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)
diff --git a/doc/upvar.n b/doc/upvar.n
index 2b2175e..b73d6a4 100644
--- a/doc/upvar.n
+++ b/doc/upvar.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: upvar.n,v 1.5 2000/11/21 15:56:21 dkf Exp $
+'\" RCS: @(#) $Id: upvar.n,v 1.5.18.1 2004/10/27 14:43:15 dkf Exp $
 '\" 
 .so man.macros
 .TH upvar n "" Tcl "Tcl Built-In Commands"
@@ -47,8 +47,8 @@ as Tcl procedures.
 For example, consider the following procedure:
 .CS
 \fBproc add2 name {
-	upvar $name x
-	set x [expr $x+2]
+   \fBupvar\fR $name x
+   set x [expr $x+2]
 }\fR
 .CE
 \fBAdd2\fR is invoked with an argument giving the name of a variable,
@@ -75,8 +75,7 @@ upvar variable.  There is no way to unset an upvar variable except
 by exiting the procedure in which it is defined.  However, it is
 possible to retarget an upvar variable by executing another \fBupvar\fR
 command.
-
-.SH Traces and upvar
+.SH "TRACES AND UPVAR"
 .PP
 Upvar interacts with traces in a straightforward but possibly
 unexpected manner.  If a variable trace is defined on \fIotherVar\fR, that
@@ -86,24 +85,33 @@ than the name of \fIotherVar\fR.  Thus, the output of the following code
 will be \fBlocalVar\fR rather than \fBoriginalVar\fR:
 .CS
 \fBproc traceproc { name index op } {
-	puts $name
+   puts $name
 }
 proc setByUpvar { name value } {
-	upvar $name localVar
-	set localVar $value
+   \fBupvar\fR $name localVar
+   set localVar $value
 }
 set originalVar 1
 trace variable originalVar w traceproc
 setByUpvar originalVar 2
 }\fR
 .CE
-
+.PP
 If \fIotherVar\fR refers to an element of an array, then variable
 traces set for the entire array will not be invoked when \fImyVar\fR
 is accessed (but traces on the particular element will still be
 invoked).  In particular, if the array is \fBenv\fR, then changes
 made to \fImyVar\fR will not be passed to subprocesses correctly.
 .VE
+.SH EXAMPLE
+A \fBdecr\fR command that works like \fBincr\fR except it subtracts
+the value from the variable instead of adding it:
+.CS
+proc decr {varName {decrement 1}} {
+    \fBupvar\fR 1 $varName var
+    incr var [expr {-$decrement}]
+}
+.CE
 
 .SH "SEE ALSO"
 global(n), namespace(n), uplevel(n), variable(n)
diff --git a/doc/variable.n b/doc/variable.n
index 9ef4738..908e5ae 100644
--- a/doc/variable.n
+++ b/doc/variable.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: variable.n,v 1.4 2000/11/21 15:56:21 dkf Exp $
+'\" RCS: @(#) $Id: variable.n,v 1.4.18.1 2004/10/27 14:43:15 dkf Exp $
 '\" 
 .so man.macros
 .TH variable n 8.0 Tcl "Tcl Built-In Commands"
@@ -58,6 +58,39 @@ and the initialization \fIvalue\fR should be left off.
 After the variable has been declared,
 elements within the array can be set using ordinary
 \fBset\fR or \fBarray\fR commands.
+.SH EXAMPLES
+Create a variable in a namespace:
+.CS
+namespace eval foo {
+    \fBvariable\fR bar 12345
+}
+.CE
+.PP
+Create an array in a namespace:
+.CS
+namespace eval someNS {
+    \fBvariable\fR someAry
+    array set someAry {
+        someName  someValue
+        otherName otherValue
+    }
+}
+.CE
+.PP
+Access variables in namespaces from a procedure:
+.CS
+namespace eval foo {
+    proc spong {} {
+        # Variable in this namespace
+        \fBvariable\fR bar
+        puts "bar is $bar"
+
+        # Variable in another namespace
+        \fBvariable\fR ::someNS::someAry
+        parray someAry
+    }
+}
+.CE
 
 .SH "SEE ALSO"
 global(n), namespace(n), upvar(n)
diff --git a/doc/vwait.n b/doc/vwait.n
index 4febe1b..041d79b 100644
--- a/doc/vwait.n
+++ b/doc/vwait.n
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: vwait.n,v 1.4 2000/09/07 14:27:52 poenitz Exp $
+'\" RCS: @(#) $Id: vwait.n,v 1.4.18.1 2004/10/27 14:43:15 dkf Exp $
 '\" 
 .so man.macros
 .TH vwait n 8.0 Tcl "Tcl Built-In Commands"
@@ -35,9 +35,47 @@ if an event handler sets \fIvarName\fR and then itself calls
 for a long time.  During this time the top-level \fBvwait\fR is
 blocked waiting for the event handler to complete, so it cannot
 return either.
+.SH EXAMPLES
+Run the event-loop continually until some event calls \fBexit\fR.
+(You can use any variable not mentioned elsewhere, but the name
+\fIforever\fR reminds you at a glance of the intent.)
+.CS
+\fBvwait\fR forever
+.CE
+.PP
+Wait five seconds for a connection to a server socket, otherwise
+close the socket and continue running the script:
+.CS
+# Initialise the state
+after 5000 set state timeout
+set server [socket -server accept 12345]
+proc accept {args} {
+   global state connectionInfo
+   set state accepted
+   set connectionInfo $args
+}
+
+# Wait for something to happen
+\fBvwait\fR state
+
+# Clean up events that could have happened
+close $server
+after cancel set state timeout
+
+# Do something based on how the vwait finished...
+switch $state {
+   timeout {
+      puts "no connection on port 12345"
+   }
+   accepted {
+      puts "connection: $connectionInfo"
+      puts [lindex $connectionInfo 0] "Hello there!"
+   }
+}
+.CE
 
 .SH "SEE ALSO"
-global(n)
+global(n), update(n)
 
 .SH KEYWORDS
 event, variable, wait
diff --git a/doc/while.n b/doc/while.n
index ba5a584..dcaf8fc 100644
--- a/doc/while.n
+++ b/doc/while.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: while.n,v 1.3 2000/09/07 14:27:52 poenitz Exp $
+'\" RCS: @(#) $Id: while.n,v 1.3.18.1 2004/10/27 14:43:15 dkf Exp $
 '\" 
 .so man.macros
 .TH while n "" Tcl "Tcl Built-In Commands"
@@ -45,9 +45,18 @@ For an example, try the following script with and without the braces
 around \fB$x<10\fR:
 .CS
 set x 0
-while {$x<10} {
-	puts "x is $x"
-	incr x
+\fBwhile\fR {$x<10} {
+    puts "x is $x"
+    incr x
+}
+.CE
+.SH EXAMPLE
+Read lines from a channel until we get to the end of the stream, and
+print them out with a line-number prepended:
+.CS
+set lineCount 0
+\fBwhile\fR {[gets $chan line] >= 0} {
+    puts "[incr lineCount]: $line"
 }
 .CE