Backport many doc fixes

21 files changed, 463 insertions, 105 deletions

diff --git a/ChangeLog b/ChangeLog
index f9aaa1f..9020650 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2004-10-26  Donal K. Fellows  <donal.k.fellows@man.ac.uk>
+
+	* doc/[a-e]*.n: First stage of backporting documentation updates.
+
 2004-10-26  Don Porter  <dgp@users.sourceforge.net>
 
 	* tests/subst.test (subst-12.3-5):	More tests for Bug 1036649.
diff --git a/doc/after.n b/doc/after.n
index 7e9a767..4db2815 100644
--- a/doc/after.n
+++ b/doc/after.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: after.n,v 1.3 2000/09/07 14:27:45 poenitz Exp $
+'\" RCS: @(#) $Id: after.n,v 1.3.18.1 2004/10/27 09:35:38 dkf Exp $
 '\" 
 .so man.macros
 .TH after n 7.5 Tcl "Tcl Built-In Commands"
@@ -102,6 +102,43 @@ In applications that are not normally event-driven, such as
 \fBtclsh\fR, the event loop can be entered with the \fBvwait\fR
 and \fBupdate\fR commands.
 
+.SH "EXAMPLES"
+This defines a command to make Tcl do nothing at all for \fIN\fR
+seconds:
+
+.CS
+proc sleep {N} {
+    \fBafter\fR [expr {int($N * 1000)}]
+}
+.CE
+
+This arranges for the command \fIwake_up\fR to be run in eight hours
+(providing the event loop is active at that time):
+
+.CS
+\fBafter\fR [expr {1000 * 60 * 60 * 8}] wake_up
+.CE
+
+The following command can be used to do long-running calculations (as
+represented here by \fI::my_calc::one_step\fR, which is assumed to
+return a boolean indicating whether another step should be performed)
+in a step-by-step fashion, though the calculation itself needs to be
+arranged so it can work step-wise.  This technique is extra careful to
+ensure that the event loop is not starved by the rescheduling of
+processing steps (arranging for the next step to be done using an
+already-triggered timer event only when the event queue has been
+drained) and is useful when you want to ensure that a Tk GUI remains
+responsive during a slow task.
+
+.CS
+proc doOneStep {} {
+    if {[::my_calc::one_step]} {
+        \fBafter\fR idle [list \fBafter\fR 0 doOneStep]
+    }
+}
+doOneStep
+.CE
+
 .SH "SEE ALSO"
 bgerror(n), concat(n), update(n), vwait(n)
 
diff --git a/doc/append.n b/doc/append.n
index 5f1a3c7..ec0e965 100644
--- a/doc/append.n
+++ b/doc/append.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: append.n,v 1.4 2003/02/10 13:32:22 dkf Exp $
+'\" RCS: @(#) $Id: append.n,v 1.4.2.1 2004/10/27 09:35:38 dkf Exp $
 '\" 
 .so man.macros
 .TH append n "" Tcl "Tcl Built-In Commands"
@@ -29,6 +29,16 @@ This command provides an efficient way to build up long
 variables incrementally.
 For example, ``\fBappend a $b\fR'' is much more efficient than
 ``\fBset a $a$b\fR'' if \fB$a\fR is long.
+.SH EXAMPLE
+Building a string of comma-separated numbers piecemeal using a loop.
+.CS
+set var 0
+for {set i 1} {$i<=10} {incr i} {
+   \fBappend\fR var "," $i
+}
+puts $var
+# Prints 0,1,2,3,4,5,6,7,8,9,10
+.CE
 
 .SH "SEE ALSO"
 concat(n), lappend(n)
diff --git a/doc/bgerror.n b/doc/bgerror.n
index a78782f..3addf2d 100644
--- a/doc/bgerror.n
+++ b/doc/bgerror.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: bgerror.n,v 1.4 2000/09/07 14:27:45 poenitz Exp $
+'\" RCS: @(#) $Id: bgerror.n,v 1.4.18.1 2004/10/27 09:35:38 dkf Exp $
 '\" 
 .so man.macros
 .TH bgerror n 7.5 Tcl "Tcl Built-In Commands"
@@ -71,6 +71,22 @@ the command to be run.  The text of the stack trace is appended to the
 command when it is evaluated.  If either of these options is set to
 the empty string, then the additional button will not be displayed in
 the dialog.
+.PP
+If you are writing code that will be used by others as part of a
+package or other kind of library, consider avoiding \fBbgerror\fR.
+The reason for this is that the application programmer may also want
+to define a \fBbgerror\fR, or use other code that does and thus will
+have trouble integrating your code.
+.SH "EXAMPLE"
+This \fBbgerror\fR procedure appends errors to a file, with a timestamp.
+.CS
+proc bgerror {message} {
+    set timestamp [clock format [clock seconds]]
+    set fl [open mylog.txt {WRONLY CREAT APPEND}]
+    puts $fl "$timestamp: bgerror in $::argv '$message'"
+    close $fl
+}
+.CE
 
 .SH "SEE ALSO"
 after(n), tclvars(n)
diff --git a/doc/binary.n b/doc/binary.n
index 320d94f..4e38f64 100644
--- a/doc/binary.n
+++ b/doc/binary.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: binary.n,v 1.11.2.5 2003/07/14 18:26:29 hobbs Exp $
+'\" RCS: @(#) $Id: binary.n,v 1.11.2.6 2004/10/27 09:35:38 dkf Exp $
 '\" 
 .so man.macros
 .TH binary n 8.0 Tcl "Tcl Built-In Commands"
@@ -634,12 +634,33 @@ by \fIcount\fR.  Note that position 0 refers to the first byte in
 will return \fB2\fR with \fB1 2\fR stored in \fBvar1\fR and \fB020304\fR
 stored in \fBvar2\fR.
 .RE
-
 .SH "PLATFORM ISSUES"
 Sometimes it is desirable to format or scan integer values in the
 native byte order for the machine.  Refer to the \fBbyteOrder\fR
 element of the \fBtcl_platform\fR array to decide which type character
 to use when formatting or scanning integers.
+.SH EXAMPLES
+This is a procedure to write a Tcl string to a binary-encoded channel as
+UTF-8 data preceded by a length word:
+.CS
+proc writeString {channel string} {
+    set data [encoding convertto utf-8 $string]
+    puts -nonewline [\fBbinary\fR format Ia* \e
+            [string length $data] $data]
+}
+.CE
+.PP
+This procedure reads a string from a channel that was written by the
+previously presented \fBwriteString\fR procedure:
+.CS
+proc readString {channel} {
+    if {![\fBbinary\fR scan [read $channel 4] I length]} {
+        error "missing length"
+    }
+    set data [read $channel $length]
+    return [encoding convertfrom utf-8 $data]
+}
+.CE
 
 .SH "SEE ALSO"
 format(n), scan(n), tclvars(n)
diff --git a/doc/break.n b/doc/break.n
index 32432eb..7f7462e 100644
--- a/doc/break.n
+++ b/doc/break.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: break.n,v 1.3 2000/09/07 14:27:46 poenitz Exp $
+'\" RCS: @(#) $Id: break.n,v 1.3.18.1 2004/10/27 09:35:38 dkf Exp $
 '\" 
 .so man.macros
 .TH break n "" Tcl "Tcl Built-In Commands"
@@ -21,7 +21,7 @@ break \- Abort looping command
 .PP
 This command is typically invoked inside the body of a looping command
 such as \fBfor\fR or \fBforeach\fR or \fBwhile\fR.
-It returns a TCL_BREAK code, which causes a break exception
+It returns a \fBTCL_BREAK\fR code, which causes a break exception
 to occur.
 The exception causes the current script to be aborted
 out to the innermost containing loop command, which then
@@ -29,9 +29,19 @@ aborts its execution and returns normally.
 Break exceptions are also handled in a few other situations, such
 as the \fBcatch\fR command, Tk event bindings, and the outermost
 scripts of procedure bodies.
+.SH EXAMPLE
+Print a line for each of the integers from 0 to 5:
+.CS
+for {set x 0} {$x<10} {incr x} {
+   if {$x > 5} {
+      \fBbreak\fR
+   }
+   puts "x is $x"
+}
+.CE
 
 .SH "SEE ALSO"
-catch(n), continue(n), for(n), foreach(n), while(n)
+catch(n), continue(n), for(n), foreach(n), return(n), while(n)
 
 .SH KEYWORDS
 abort, break, loop
diff --git a/doc/catch.n b/doc/catch.n
index 01d0628..5bae0c6 100644
--- a/doc/catch.n
+++ b/doc/catch.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: catch.n,v 1.5 2000/09/07 14:27:46 poenitz Exp $
+'\" RCS: @(#) $Id: catch.n,v 1.5.18.1 2004/10/27 09:35:38 dkf Exp $
 '\" 
 .so man.macros
 .TH catch n "8.0" Tcl "Tcl Built-In Commands"
@@ -31,7 +31,7 @@ given, then the variable it names is set to the error message from
 interpreting \fIscript\fR.
 .PP
 If \fIscript\fR does not raise an error, \fBcatch\fR will return 0
-(TCL_OK) and set the variable to the value returned from \fIscript\fR.
+(\fBTCL_OK\fR) and set the variable to the value returned from \fIscript\fR.
 .PP
 Note that \fBcatch\fR catches all exceptions, including those
 generated by \fBbreak\fR and \fBcontinue\fR as well as errors.  The
@@ -42,23 +42,21 @@ script is compiled as well and any syntax errors will generate a Tcl
 error. 
 
 .SH EXAMPLES
-
 The \fBcatch\fR command may be used in an \fBif\fR to branch based on
 the success of a script.
-
 .CS
-if { [catch {open $someFile w} fid] } {
+if { [\fBcatch\fR {open $someFile w} fid] } {
     puts stderr "Could not open $someFile for writing\\n$fid"
     exit 1
 }
 .CE
+.PP
 The \fBcatch\fR command will not catch compiled syntax errors.  The
 first time proc \fBfoo\fR is called, the body will be compiled and a
 Tcl error will be generated. 
-
 .CS
 proc foo {} {
-    catch {expr {1 +- }}
+    \fBcatch\fR {expr {1 +- }}
 }
 .CE
 
diff --git a/doc/cd.n b/doc/cd.n
index b915a67..f42e924 100644
--- a/doc/cd.n
+++ b/doc/cd.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: cd.n,v 1.3 2000/09/07 14:27:46 poenitz Exp $
+'\" RCS: @(#) $Id: cd.n,v 1.3.18.1 2004/10/27 09:35:38 dkf Exp $
 '\" 
 .so man.macros
 .TH cd n "" Tcl "Tcl Built-In Commands"
@@ -23,6 +23,20 @@ Change the current working directory to \fIdirName\fR, or to the
 home directory (as specified in the HOME environment variable) if
 \fIdirName\fR is not given.
 Returns an empty string.
+Note that the current working directory is a per-process resource; the
+\fBcd\fR command changes the working directory for all interpreters
+and (in a threaded environment) all threads.
+.SH EXAMPLES
+Change to the home directory of the user \fBfred\fR:
+.CS
+\fBcd\fR ~fred
+.CE
+.PP
+Change to the directory \fBlib\fR that is a sibling directory of the
+current one:
+.CS
+\fBcd\fR ../lib
+.CE
 
 .SH "SEE ALSO"
 filename(n), glob(n), pwd(n)
diff --git a/doc/clock.n b/doc/clock.n
index 41a1cef..630683e 100644
--- a/doc/clock.n
+++ b/doc/clock.n
@@ -10,7 +10,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: clock.n,v 1.11.2.2 2004/05/18 21:52:56 kennykb Exp $
+'\" RCS: @(#) $Id: clock.n,v 1.11.2.3 2004/10/27 09:35:38 dkf Exp $
 '\" 
 .so man.macros
 .TH clock n 8.4 Tcl "Tcl Built-In Commands"
@@ -268,9 +268,9 @@ different results will be given for \fBclock scan "1 day"\fR and
 \fBclock scan "24 hours"\fR:
 .CS
 .ta 6c
-\fB% clock scan "1 day" -base [clock scan 1999-10-31]
+\fB% \fBclock\fR scan "1 day" -base [\fBclock\fR scan 1999-10-31]
 941443200
-% clock scan "24 hours" -base [clock scan 1999-10-31]
+% \fBclock\fR scan "24 hours" -base [\fBclock\fR scan 1999-10-31]
 941439600\fR
 .CE
 .RE
diff --git a/doc/close.n b/doc/close.n
index 501d282..28fe971 100644
--- a/doc/close.n
+++ b/doc/close.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: close.n,v 1.4 2001/09/14 19:20:40 andreas_kupries Exp $
+'\" RCS: @(#) $Id: close.n,v 1.4.8.1 2004/10/27 09:35:38 dkf Exp $
 '\" 
 .so man.macros
 .TH close n 7.5 Tcl "Tcl Built-In Commands"
@@ -59,7 +59,24 @@ that all output is correctly flushed before the process exits.
 .VE
 .PP
 The command returns an empty string, and may generate an error if
-an error occurs while flushing output.
+an error occurs while flushing output.  If a command in a command
+pipeline created with \fBopen\fR returns an error, \fBclose\fR
+generates an error (similar to the \fBexec\fR command.)
+.SH EXAMPLE
+This illustrates how you can use Tcl to ensure that files get closed
+even when errors happen by combining \fBcatch\fR, \fBclose\fR and
+\fBreturn\fR:
+.CS
+proc withOpenFile {filename channelVar script} {
+    upvar 1 $channelVar chan
+    set chan [open $filename]
+    catch {
+        uplevel 1 $script
+    } result options
+    \fBclose\fR $chan
+    return -options $options $result
+}
+.CE
 
 .SH "SEE ALSO"
 file(n), open(n), socket(n), eof(n), Tcl_StandardChannels(3)
diff --git a/doc/concat.n b/doc/concat.n
index 52f4094..aaabe6e 100644
--- a/doc/concat.n
+++ b/doc/concat.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: concat.n,v 1.4 2002/07/01 10:50:21 dkf Exp $
+'\" RCS: @(#) $Id: concat.n,v 1.4.2.1 2004/10/27 09:35:38 dkf Exp $
 '\" 
 .so man.macros
 .TH concat n 8.3 Tcl "Tcl Built-In Commands"
@@ -20,28 +20,30 @@ concat \- Join lists together
 .SH DESCRIPTION
 .PP
 This command joins each of its arguments together with spaces after
-trimming leading and trailing spaces from each of them.  If all the
+trimming leading and trailing white-space from each of them.  If all the
 arguments are lists, this has the same effect as concatenating them
 into a single list.
-It permits any number of arguments.  For example, the command
+It permits any number of arguments;
+if no \fIarg\fRs are supplied, the result is an empty string.
+.SH EXAMPLES
+Although \fBconcat\fR will concatenate lists (so the command:
 .CS
-\fBconcat a b {c d e} {f {g h}}\fR
+\fBconcat\fR a b {c d e} {f {g h}}
 .CE
-will return
+will return "\fBa b c d e f {g h}\fR" as its result), it will also
+concatenate things that are not lists, and hence the command:
 .CS
-\fBa b c d e f {g h}\fR
+\fBconcat\fR " a b {c   " d "  e} f"
 .CE
-as its result, and
-.CS
-\fBconcat " a b {c   " d "  e} f"\fR
-.CE
-will return
+will return "\fBa b {c d e} f\fR" as its result.
+.PP
+Note that the concatenation does not remove spaces from the middle of
+its arguments, so the command:
 .CS
-\fBa b {c d e} f\fR
+\fBconcat\fR "a   b   c" { d e f }
 .CE
-as its result.
-.PP
-If no \fIarg\fRs are supplied, the result is an empty string.
+will return "\fBa   b   c d e f\fR" (i.e. with three spaces between
+the \fBa\fR, the \fBb\fR and the \fBc\fR).
 
 .SH "SEE ALSO"
 append(n), eval(n)
diff --git a/doc/continue.n b/doc/continue.n
index 698f9c9..39fe2ed 100644
--- a/doc/continue.n
+++ b/doc/continue.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: continue.n,v 1.3 2000/09/07 14:27:46 poenitz Exp $
+'\" RCS: @(#) $Id: continue.n,v 1.3.18.1 2004/10/27 09:35:38 dkf Exp $
 '\" 
 .so man.macros
 .TH continue n "" Tcl "Tcl Built-In Commands"
@@ -21,7 +21,7 @@ continue \- Skip to the next iteration of a loop
 .PP
 This command is typically invoked inside the body of a looping command
 such as \fBfor\fR or \fBforeach\fR or \fBwhile\fR.
-It returns a TCL_CONTINUE code, which causes a continue exception
+It returns a \fBTCL_CONTINUE\fR code, which causes a continue exception
 to occur.
 The exception causes the current script to be aborted
 out to the innermost containing loop command, which then
@@ -29,9 +29,19 @@ continues with the next iteration of the loop.
 Catch exceptions are also handled in a few other situations, such
 as the \fBcatch\fR command and the outermost scripts of procedure
 bodies.
+.SH EXAMPLE
+Print a line for each of the integers from 0 to 10 \fIexcept\fR 5:
+.CS
+for {set x 0} {$x<10} {incr x} {
+   if {$x == 5} {
+      \fBcontinue\fR
+   }
+   puts "x is $x"
+}
+.CE
 
 .SH "SEE ALSO"
-break(n), for(n), foreach(n), while(n)
+break(n), for(n), foreach(n), return(n), while(n)
 
 .SH KEYWORDS
 continue, iteration, loop
diff --git a/doc/dde.n b/doc/dde.n
index 19b1e66..1e81f87 100644
--- a/doc/dde.n
+++ b/doc/dde.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: dde.n,v 1.8 2002/06/27 22:29:08 dgp Exp $
+'\" RCS: @(#) $Id: dde.n,v 1.8.2.1 2004/10/27 09:35:38 dkf Exp $
 '\" 
 .so man.macros
 .TH dde n 1.2 dde "Tcl Bundled Packages"
@@ -137,6 +137,13 @@ without adding the \fB&\fR to place the process in the background).
 If for any reason the event queue is not flushed, DDE commands may
 hang until the event queue is flushed.  This can create a deadlock
 situation.
+.SH EXAMPLE
+This asks Internet Explorer (which must already be running) to go to a
+particularly important website:
+.CS
+package require dde
+\fBdde\fR execute iexplore WWW_OpenURL http://www.tcl.tk/
+.CE
 
 .SH "SEE ALSO"
 tk(n), winfo(n), send(n)
diff --git a/doc/encoding.n b/doc/encoding.n
index f2ddbb7..cf59cd1 100644
--- a/doc/encoding.n
+++ b/doc/encoding.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: encoding.n,v 1.3.18.1 2003/06/24 21:24:08 dkf Exp $
+'\" RCS: @(#) $Id: encoding.n,v 1.3.18.2 2004/10/27 09:35:38 dkf Exp $
 '\" 
 .so man.macros
 .TH encoding n "8.1" Tcl "Tcl Built-In Commands"
@@ -71,7 +71,7 @@ of the original string.  The \fBencoding\fR command can be used to
 convert this string to the expected Japanese Unicode characters.  For
 example,
 .CS
-	set s [encoding convertfrom euc-jp "\\xA4\\xCF"]
+set s [\fBencoding\fR convertfrom euc-jp "\\xA4\\xCF"]
 .CE
 would return the Unicode string "\\u306F", which is the Hiragana
 letter HA.
diff --git a/doc/eof.n b/doc/eof.n
index ad5f90f..ed93dff 100644
--- a/doc/eof.n
+++ b/doc/eof.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: eof.n,v 1.4 2001/09/14 19:20:40 andreas_kupries Exp $
+'\" RCS: @(#) $Id: eof.n,v 1.4.8.1 2004/10/27 09:35:38 dkf Exp $
 '\" 
 .so man.macros
 .TH eof n 7.5 Tcl "Tcl Built-In Commands"
@@ -23,12 +23,38 @@ Returns 1 if an end of file condition occurred during the most
 recent input operation on \fIchannelId\fR (such as \fBgets\fR),
 0 otherwise.
 .PP
-.VS
 \fIChannelId\fR must be an identifier for an open channel such as a
 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 EXAMPLES
+Read and print out the contents of a file line-by-line:
+.CS
+set f [open somefile.txt]
+while {1} {
+    set line [gets $f]
+    if {[\fBeof\fR $f]} {
+        close $f
+        break
+    }
+    puts "Read line: $line"
+}
+.CE
+.PP
+Read and print out the contents of a file by fixed-size records:
+.CS
+set f [open somefile.dat]
+fconfigure $f -translation binary
+set recordSize 40
+while {1} {
+    set record [read $f $recordSize]
+    if {[\fBeof\fR $f]} {
+        close $f
+        break
+    }
+    puts "Read record: $record"
+}
+.CE
 
 .SH "SEE ALSO"
 file(n), open(n), close(n), fblocked(n), Tcl_StandardChannels(3)
diff --git a/doc/error.n b/doc/error.n
index 075f5ec..4cfb044 100644
--- a/doc/error.n
+++ b/doc/error.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: error.n,v 1.3 2000/09/07 14:27:47 poenitz Exp $
+'\" RCS: @(#) $Id: error.n,v 1.3.18.1 2004/10/27 09:35:38 dkf Exp $
 '\" 
 .so man.macros
 .TH error n "" Tcl "Tcl Built-In Commands"
@@ -19,7 +19,7 @@ error \- Generate an error
 
 .SH DESCRIPTION
 .PP
-Returns a TCL_ERROR code, which causes command interpretation to be
+Returns a \fBTCL_ERROR\fR code, which causes command interpretation to be
 unwound.  \fIMessage\fR is a string that is returned to the application
 to indicate what went wrong.
 .PP
@@ -53,9 +53,16 @@ If the \fIcode\fR argument is not
 present, then \fBerrorCode\fR is automatically reset to
 ``NONE'' by the Tcl interpreter as part of processing the
 error generated by the command.
+.SH EXAMPLE
+Generate an error if a basic mathematical operation fails:
+.CS
+if {1+2 != 3} {
+    \fBerror\fR "something is very wrong with addition"
+}
+.CE
 
 .SH "SEE ALSO"
-catch(n), tclvars(n)
+catch(n), return(n), tclvars(n)
 
 .SH KEYWORDS
 error, errorCode, errorInfo
diff --git a/doc/eval.n b/doc/eval.n
index 76c37f2..8ae0457 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.4.2.1 2004/10/27 09:35:38 dkf Exp $
 '\" 
 .so man.macros
 .TH eval n "" Tcl "Tcl Built-In Commands"
@@ -27,6 +27,19 @@ 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
+This procedure acts in a way that is analogous to the \fBlappend\fR
+command, except it inserts the argument values at the start of the
+list in the variable:
+.CS
+proc lprepend {varName args} {
+   upvar 1 $varName var
+   # Ensure that the variable exists and contains a list
+   lappend var
+   # Now we insert all the arguments in one go
+   set var [\fBeval\fR [list linsert $var 0] $args]
+}
+.CE
 
 .SH KEYWORDS
 concatenate, evaluate, script
diff --git a/doc/exec.n b/doc/exec.n
index f61db59..6e52ca1 100644
--- a/doc/exec.n
+++ b/doc/exec.n
@@ -5,14 +5,14 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: exec.n,v 1.6 2002/04/23 19:06:10 hobbs Exp $
+'\" RCS: @(#) $Id: exec.n,v 1.6.2.1 2004/10/27 09:35:38 dkf Exp $
 '\" 
 .so man.macros
 .TH exec n 7.6 Tcl "Tcl Built-In Commands"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-exec \- Invoke subprocess(es)
+exec \- Invoke subprocesses
 .SH SYNOPSIS
 \fBexec \fR?\fIswitches\fR? \fIarg \fR?\fIarg ...\fR?
 .BE
@@ -38,7 +38,7 @@ Normally a trailing newline will be deleted.
 Marks the end of switches.  The argument following this one will
 be treated as the first \fIarg\fR even if it starts with a \fB\-\fR.
 .PP
-If an \fIarg\fR (or pair of \fIarg\fR's) has one of the forms
+If an \fIarg\fR (or pair of \fIarg\fRs) has one of the forms
 described below then it is used by \fBexec\fR to control the
 flow of input and output among the subprocess(es).
 Such arguments will not be passed to the subprocess(es).  In forms
@@ -217,7 +217,7 @@ example.
 .br
 2) TUI -- Textmode User Interface, any application that accesses the console
 API for doing such things as cursor movement, setting text color, detecting
-key presses and mouse movement, etc...  An example would be \fBtelnet.exe\fR
+key presses and mouse movement, etc.  An example would be \fBtelnet.exe\fR
 from Windows 2000.  These types of applications are not common in a windows
 environment, but do exist.
 .RE
@@ -225,8 +225,7 @@ environment, but do exist.
 present, as is done when launching applications under wish.  It is desirable
 to have console applications hidden and detached.  This is a designed-in
 limitation as \fBexec\fR wants to communicate over pipes.  The Expect
-extension addresses this issue when communication between a TUI application
-is desired.
+extension addresses this issue when communicating with a TUI application.
 .sp
 .RE
 .TP
@@ -254,12 +253,13 @@ The Windows NT home directory.
 The directories listed in the path.
 .RE
 .sp
-In order to execute the shell builtin commands like \fBdir\fR and \fBcopy\fR,
-the caller must prepend ``\fBcmd.exe /c\0\fR'' to the desired command.
+In order to execute shell built-in commands like \fBdir\fR and \fBcopy\fR,
+the caller must prepend the desired command with ``\fBcmd.exe /c\0\fR''
+because built-in commands are not implemented using executables.
 .sp
 .RE
 .TP
-\fBWindows 95\fR
+\fBWindows 9x\fR
 .
 When attempting to execute an application, \fBexec\fR first searches for
 the name as it was specified.  Then, in order, \fB.com\fR, \fB.exe\fR, and
@@ -274,15 +274,16 @@ The directory from which the Tcl executable was loaded.
 .br
 The current directory.
 .br
-The Windows 95 system directory.
+The Windows 9x system directory.
 .br
-The Windows 95 home directory.
+The Windows 9x home directory.
 .br
 The directories listed in the path.
 .RE
 .sp
-In order to execute the shell builtin commands like \fBdir\fR and \fBcopy\fR,
-the caller must prepend ``\fBcommand.com /c\0\fR'' to the desired command.
+In order to execute shell built-in commands like \fBdir\fR and \fBcopy\fR,
+the caller must prepend the desired command with ``\fBcommand.com /c\0\fR''
+because built-in commands are not implemented using executables.
 .sp
 Once a 16-bit DOS application has read standard input from a console and 
 then quit, all subsequently run 16-bit DOS applications will see the 
@@ -322,6 +323,87 @@ The \fBexec\fR command is not implemented and does not exist under Macintosh.
 \fBUnix\fR\0\0\0\0\0\0\0
 The \fBexec\fR command is fully functional and works as described.
 
+.SH "UNIX EXAMPLES"
+Here are some examples of the use of the \fBexec\fR command on Unix.
+.PP
+To execute a simple program and get its result:
+.CS
+\fBexec\fR uname -a
+.CE
+.PP
+To execute a program that can return a non-zero result, you should
+wrap the call to \fBexec\fR in \fBcatch\fR and check what the contents
+of the global \fBerrorCode\fR variable is if you have an error:
+.CS
+set status 0
+if {[catch {\fBexec\fR grep foo bar.txt} results]} {
+   if {[lindex $::errorCode 0] eq "CHILDSTATUS"} {
+      set status [lindex $::errorCode 2]
+   } else {
+      # Some kind of unexpected failure
+   }
+}
+.CE
+.PP
+When translating a command from a Unix shell invocation, care should
+be taken over the fact that single quote characters have no special
+significance to Tcl.  Thus:
+.CS
+awk '{sum += $1} END {print sum}' numbers.list
+.CE
+would be translated into something like:
+.CS
+\fBexec\fR awk {{sum += $1} END {print sum}} numbers.list
+.CE
+.PP
+If you are converting invocations involving shell globbing, you should
+remember that Tcl does not handle globbing or expand things into
+multiple arguments by default.  Instead you should write things like
+this:
+.CS
+eval [list \fBexec\fR ls -l] [glob *.tcl]
+.CE
+.PP
+.SH "WINDOWS EXAMPLES"
+Here are some examples of the use of the \fBexec\fR command on Windows.
+.PP
+To start an instance of \fInotepad\fR editing a file without waiting
+for the user to finish editing the file:
+.CS
+\fBexec\fR notepad myfile.txt &
+.CE
+.PP
+To print a text file using \fInotepad\fR:
+.CS
+\fBexec\fR notepad /p myfile.txt
+.CE
+.PP
+If a program calls other programs, such as is common with compilers,
+then you may need to resort to batch files to hide the console windows
+that sometimes pop up:
+.CS
+\fBexec\fR cmp.bat somefile.c -o somefile
+.CE
+With the file \fIcmp.bat\fR looking something like:
+.CS
+@gcc %1 %2 %3 %4 %5 %6 %7 %8 %9
+.CE
+.PP
+Sometimes you need to be careful, as different programs may have the
+same name and be in the path. It can then happen that typing a command
+at the DOS prompt finds \fIa different program\fR than the same
+command run via \fBexec\fR. This is because of the (documented)
+differences in behaviour between \fBexec\fR and DOS batch files.
+.PP
+When in doubt, use the command \fBauto_execok\fR: it will return the
+complete path to the program as seen by the \fBexec\fR command.  This
+applies especially when you want to run "internal" commands like
+\fIdir\fR from a Tcl script (if you just want to list filenames, use
+the \fBglob\fR command.)  To do that, use this:
+.CS
+eval [list \fBexec\fR] [auto_execok dir] [list *.tcl]
+.CE
+
 .SH "SEE ALSO"
 error(n), open(n)
 
diff --git a/doc/exit.n b/doc/exit.n
index 5f72946..f0300a7 100644
--- a/doc/exit.n
+++ b/doc/exit.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: exit.n,v 1.3 2000/09/07 14:27:47 poenitz Exp $
+'\" RCS: @(#) $Id: exit.n,v 1.3.18.1 2004/10/27 09:35:38 dkf Exp $
 '\" 
 .so man.macros
 .TH exit n "" Tcl "Tcl Built-In Commands"
@@ -23,6 +23,28 @@ Terminate the process, returning \fIreturnCode\fR to the
 system as the exit status.
 If \fIreturnCode\fR isn't specified then it defaults
 to 0.
+.SH EXAMPLE
+Since non-zero exit codes are usually interpreted as error cases by
+the calling process, the \fBexit\fR command is an important part of
+signalling that something fatal has gone wrong.  This code fragment is
+useful in scripts to act as a general problem trap:
+.CS
+proc main {} {
+    # ... put the real main code in here ...
+}
+
+if {[catch {main} msg]} {
+    puts stderr "unexpected script error: $msg"
+    if {[info exist env(DEBUG)]} {
+        puts stderr "---- BEGIN TRACE ----"
+        puts stderr $errorInfo
+        puts stderr "---- END TRACE ----"
+    }
+
+    # Reserve code 1 for "expected" error exits...
+    \fBexit\fR 2
+}
+.CE
 
 .SH "SEE ALSO"
 exec(n), tclvars(n)
diff --git a/doc/expr.n b/doc/expr.n
index b43765c..c9c1f81 100644
--- a/doc/expr.n
+++ b/doc/expr.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: expr.n,v 1.10.2.1 2003/07/04 22:25:23 dkf Exp $
+'\" RCS: @(#) $Id: expr.n,v 1.10.2.2 2004/10/27 09:35:38 dkf Exp $
 '\" 
 .so man.macros
 .TH expr n 8.4 Tcl "Tcl Built-In Commands"
@@ -19,7 +19,7 @@ expr \- Evaluate an expression
 
 .SH DESCRIPTION
 .PP
-Concatenates \fIarg\fR's (adding separator spaces between them),
+Concatenates \fIarg\fRs (adding separator spaces between them),
 evaluates the result as a Tcl expression, and returns the value.
 The operators permitted in Tcl expressions are a subset of
 the operators permitted in C expressions, and they have the
@@ -51,9 +51,10 @@ ways accepted by an ANSI-compliant C compiler (except that the
 \fBf\fR, \fBF\fR, \fBl\fR, and \fBL\fR suffixes will not be permitted in
 most installations).  For example, all of the
 following are valid floating-point numbers:  2.1, 3., 6e4, 7.91e+16.
-If no numeric interpretation is possible, then an operand is left
-as a string (and only a limited set of operators may be applied to
-it).
+If no numeric interpretation is possible (note that all literal
+operands that are not numeric or boolean must be quoted with either
+braces or with double quotes), then an operand is left as a string
+(and only a limited set of operators may be applied to it).
 .PP
 .VS 8.4
 On 32-bit systems, integer values MAX_INT (0x7FFFFFFF) and MIN_INT
@@ -64,33 +65,34 @@ possible at all.)
 .PP
 Operands may be specified in any of the following ways:
 .IP [1]
-As an numeric value, either integer or floating-point.
+As a numeric value, either integer or floating-point.
 .IP [2]
+As a boolean value, using any form understood by \fBstring is boolean\fR.
+.IP [3]
 As a Tcl variable, using standard \fB$\fR notation.
 The variable's value will be used as the operand.
-.IP [3]
+.IP [4]
 As a string enclosed in double-quotes.
 The expression parser will perform backslash, variable, and
 command substitutions on the information between the quotes,
 and use the resulting value as the operand
-.IP [4]
+.IP [5]
 As a string enclosed in braces.
 The characters between the open brace and matching close brace
 will be used as the operand without any substitutions.
-.IP [5]
+.IP [6]
 As a Tcl command enclosed in brackets.
 The command will be executed and its result will be used as
 the operand.
-.IP [6]
+.IP [7]
 As a mathematical function whose arguments have any of the above
 forms for operands, such as \fBsin($x)\fR.  See below for a list of defined
 functions.
 .LP
-Where substitutions occur above (e.g. inside quoted strings), they
+Where the above substitutions occur (e.g. inside quoted strings), they
 are performed by the expression's instructions.
-However, an additional layer of substitution may already have
-been performed by the command parser before the expression
-processor was called.
+However, the command parser may already have performed one round of
+substitution before the expression processor was called.
 As discussed below, it is usually best to enclose expressions
 in braces to prevent the command parser from performing substitutions
 on the contents.
@@ -113,12 +115,12 @@ The valid operators are listed below, grouped in decreasing order
 of precedence:
 .TP 20
 \fB\-\0\0+\0\0~\0\0!\fR
-Unary minus, unary plus, bit-wise NOT, logical NOT.  None of these operands
+Unary minus, unary plus, bit-wise NOT, logical NOT.  None of these operators
 may be applied to string operands, and bit-wise NOT may be
 applied only to integers.
 .TP 20
 \fB*\0\0/\0\0%\fR
-Multiply, divide, remainder.  None of these operands may be
+Multiply, divide, remainder.  None of these operators may be
 applied to string operands, and remainder may be applied only
 to integers.
 The remainder will always have the same sign as the divisor and
@@ -169,7 +171,7 @@ Valid for boolean and numeric (integers or floating-point) operands only.
 If-then-else, as in C.  If \fIx\fR
 evaluates to non-zero, then the result is the value of \fIy\fR.
 Otherwise the result is the value of \fIz\fR.
-The \fIx\fR operand must have a numeric value.
+The \fIx\fR operand must have a boolean or numeric value.
 .LP
 See the C manual for more details on the results
 produced by each operator.
@@ -359,7 +361,6 @@ example,
 \fBexpr 20.0/5.0\fR
 .CE
 returns \fB4.0\fR, not \fB4\fR.
-
 .SH "STRING OPERATIONS"
 .PP
 String values may be used as operands of the comparison operators,
@@ -420,9 +421,51 @@ The most expensive code is required for
 unbraced expressions that contain command substitutions.
 These expressions must be implemented by generating new code
 each time the expression is executed.
+.SH EXAMPLES
+Define a procedure that computes an "interesting" mathematical
+function:
+.CS
+proc calc {x y} {
+    \fBexpr\fR { ($x*$x - $y*$y) / exp($x*$x + $y*$y) }
+}
+.CE
+.PP
+Convert polar coordinates into cartesian coordinates:
+.CS
+# convert from ($radius,$angle)
+set x [\fBexpr\fR { $radius * cos($angle) }]
+set y [\fBexpr\fR { $radius * sin($angle) }]
+.CE
+.PP
+Convert cartesian coordinates into polar coordinates:
+.CS
+# convert from ($x,$y)
+set radius [\fBexpr\fR { hypot($y, $x) }]
+set angle  [\fBexpr\fR { atan2($y, $x) }]
+.CE
+.PP
+Print a message describing the relationship of two string values to
+each other:
+.CS
+puts "a and b are [\fBexpr\fR {$a eq $b ? {equal} : {different}}]"
+.CE
+.PP
+Set a variable to whether an environment variable is both defined at
+all and also set to a true boolean value:
+.CS
+set isTrue [\fBexpr\fR {
+    [info exists ::env(SOME_ENV_VAR)] &&
+    [string is true -strict $::env(SOME_ENV_VAR)]
+}]
+.CE
+.PP
+Generate a random integer in the range 0..99 inclusive:
+.CS
+set randNum [\fBexpr\fR { int(100 * rand()) }]
+.CE
 
 .SH "SEE ALSO"
-array(n), string(n), Tcl(n)
+array(n), for(n), if(n), string(n), Tcl(n), while(n)
 
 .SH KEYWORDS
 arithmetic, boolean, compare, expression, fuzzy comparison
diff --git a/doc/string.n b/doc/string.n
index 30c5adb..49ef611 100644
--- a/doc/string.n
+++ b/doc/string.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: string.n,v 1.17.2.1 2003/04/11 20:49:53 dgp Exp $
+'\" RCS: @(#) $Id: string.n,v 1.17.2.2 2004/10/27 09:35:38 dkf Exp $
 '\" 
 .so man.macros
 .TH string n 8.1 Tcl "Tcl Built-In Commands"
@@ -95,50 +95,50 @@ will be stored in the variable named \fIvarname\fR.  The \fIvarname\fR
 will not be set if the function returns 1.  The following character
 classes are recognized (the class name can be abbreviated):
 .RS
-.IP \fBalnum\fR 10
+.IP \fBalnum\fR 12
 Any Unicode alphabet or digit character.
-.IP \fBalpha\fR 10
+.IP \fBalpha\fR 12
 Any Unicode alphabet character.
-.IP \fBascii\fR 10
+.IP \fBascii\fR 12
 Any character with a value less than \\u0080 (those that are in the
 7\-bit ascii range).
-.IP \fBboolean\fR 10
+.IP \fBboolean\fR 12
 Any of the forms allowed to \fBTcl_GetBoolean\fR.
-.IP \fBcontrol\fR 10
+.IP \fBcontrol\fR 12
 Any Unicode control character.
-.IP \fBdigit\fR 10
+.IP \fBdigit\fR 12
 Any Unicode digit character.  Note that this includes characters
 outside of the [0\-9] range.
-.IP \fBdouble\fR 10
+.IP \fBdouble\fR 12
 Any of the valid forms for a double in Tcl, with optional surrounding
 whitespace.  In case of under/overflow in the value, 0 is returned and
 the \fIvarname\fR will contain \-1.
-.IP \fBfalse\fR 10
+.IP \fBfalse\fR 12
 Any of the forms allowed to \fBTcl_GetBoolean\fR where the value is
 false.
-.IP \fBgraph\fR 10
+.IP \fBgraph\fR 12
 Any Unicode printing character, except space.
-.IP \fBinteger\fR 10
-Any of the valid forms for a 32-bit integer in Tcl, with optional
+.IP \fBinteger\fR 12
+Any of the valid forms for an ordinary integer in Tcl, with optional
 surrounding whitespace.  In case of under/overflow in the value, 0 is
 returned and the \fIvarname\fR will contain \-1.
-.IP \fBlower\fR 10
+.IP \fBlower\fR 12
 Any Unicode lower case alphabet character.
-.IP \fBprint\fR 10
+.IP \fBprint\fR 12
 Any Unicode printing character, including space.
-.IP \fBpunct\fR 10
+.IP \fBpunct\fR 12
 Any Unicode punctuation character.
-.IP \fBspace\fR 10
+.IP \fBspace\fR 12
 Any Unicode space character.
-.IP \fBtrue\fR 10
+.IP \fBtrue\fR 12
 Any of the forms allowed to \fBTcl_GetBoolean\fR where the value is
 true.
-.IP \fBupper\fR 10
+.IP \fBupper\fR 12
 Any upper case alphabet character in the Unicode character set.
-.IP \fBwordchar\fR 10
+.IP \fBwordchar\fR 12
 Any Unicode word character.  That is any alphanumeric character, and
 any Unicode connector punctuation characters (e.g. underscore).
-.IP \fBxdigit\fR 10
+.IP \fBxdigit\fR 12
 Any hexadecimal digit character ([0\-9A\-Fa\-f]).
 .PP
 In the case of \fBboolean\fR, \fBtrue\fR and \fBfalse\fR, if the
@@ -172,9 +172,9 @@ number of bytes used to store the string.  If the object is a
 ByteArray object (such as those returned from reading a binary encoded
 channel), then this will return the actual byte length of the object.
 .TP
-\fBstring map\fR ?\fB\-nocase\fR? \fIcharMap string\fR
-Replaces characters in \fIstring\fR based on the key-value pairs in
-\fIcharMap\fR.  \fIcharMap\fR is a list of \fIkey value key value ...\fR
+\fBstring map\fR ?\fB\-nocase\fR? \fImapping string\fR
+Replaces substrings in \fIstring\fR based on the key-value pairs in
+\fImapping\fR.  \fImapping\fR is a list of \fIkey value key value ...\fR
 as in the form returned by \fBarray get\fR.  Each instance of a
 key in the string will be replaced with its corresponding value.  If
 \fB\-nocase\fR is specified, then matching is done without regard to
@@ -188,6 +188,14 @@ will have no affect for later key matches.  For example,
 \fBstring map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc\fR
 .CE
 will return the string \fB01321221\fR.
+.PP
+Note that if an earlier \fIkey\fR is a prefix of a later one, it will
+completely mask the later one.  So if the previous example is
+reordered like this,
+.CS
+\fBstring map {1 0 ab 2 a 3 abc 1} 1abcaababcabababc\fR
+.CE
+it will return the string \fB02c322c222c\fR.
 .RE
 .TP
 \fBstring match\fR ?\fB\-nocase\fR? \fIpattern\fR \fIstring\fR
@@ -303,6 +311,17 @@ specified as for the \fBindex\fR method.  A word is considered to be any
 contiguous range of alphanumeric (Unicode letters or decimal digits)
 or underscore (Unicode connector punctuation) characters, or any
 single character other than these.
+.SH EXAMPLE
+Test if the string in the variable \fIstring\fR is a proper non-empty
+prefix of the string \fBfoobar\fR.
+.CS
+set length [\fBstring\fR length $string]
+if {$length == 0} {
+    set isPrefix 0
+} else {
+    set isPrefix [\fBstring\fR equal -length $string $string "foobar"]
+}
+.CE
 
 .SH "SEE ALSO"
 expr(n), list(n)