From 45beb64f7dcb09a6ce83532702bca760f72e6f4d Mon Sep 17 00:00:00 2001
From: dkf <donal.k.fellows@manchester.ac.uk>
Date: Wed, 27 Oct 2004 14:23:38 +0000
Subject: Yet more doc update backporting

---
 ChangeLog       |   2 +-
 doc/after.n     |  18 ++---
 doc/array.n     |  15 ++--
 doc/binary.n    |   6 +-
 doc/clock.n     |   6 +-
 doc/dde.n       |   4 +-
 doc/encoding.n  |  10 +--
 doc/file.n      |  42 +++++------
 doc/info.n      |   8 +-
 doc/interp.n    |  14 ++--
 doc/msgcat.n    |  54 +++++++------
 doc/namespace.n | 229 +++++++++++++++++++++++++++++++++-----------------------
 doc/open.n      |  25 ++++++-
 doc/package.n   |  31 +++++++-
 doc/pid.n       |  17 ++++-
 doc/proc.n      |  22 +++++-
 doc/puts.n      |  27 ++++++-
 doc/pwd.n       |  20 ++++-
 doc/read.n      |  12 ++-
 doc/regexp.n    |  29 ++++++-
 doc/registry.n  |  21 +++++-
 doc/regsub.n    |  30 +++++++-
 doc/rename.n    |  15 +++-
 doc/return.n    | 118 +++++++++++++++++++++--------
 doc/safe.n      |   8 +-
 doc/scan.n      |  53 ++++++++++++-
 doc/seek.n      |  23 +++++-
 doc/set.n       |  28 ++++++-
 doc/socket.n    |  34 +++++++--
 doc/source.n    |  17 ++++-
 doc/split.n     |  53 +++++++++++--
 doc/string.n    |   8 +-
 doc/subst.n     |  26 +++----
 doc/switch.n    |  58 +++++++-------
 34 files changed, 772 insertions(+), 311 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 4570acf..c7d379b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,6 +1,6 @@
 2004-10-26  Donal K. Fellows  <donal.k.fellows@man.ac.uk>
 
-	* doc/[a-l]*.n: First stage of backporting documentation updates.
+	* doc/[a-s]*.n: Backporting of documentation updates.
 
 2004-10-26  Don Porter  <dgp@users.sourceforge.net>
 
diff --git a/doc/after.n b/doc/after.n
index 4db2815..ea6aa0b 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.18.1 2004/10/27 09:35:38 dkf Exp $
+'\" RCS: @(#) $Id: after.n,v 1.3.18.2 2004/10/27 14:23:41 dkf Exp $
 '\" 
 .so man.macros
 .TH after n 7.5 Tcl "Tcl Built-In Commands"
@@ -101,24 +101,21 @@ will not be executed unless the application enters the event loop.
 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)}]
+   \fBafter\fR [expr {int($N * 1000)}]
 }
 .CE
-
+.PP
 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
-
+.PP
 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)
@@ -129,12 +126,11 @@ 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]
-    }
+   if {[::my_calc::one_step]} {
+      \fBafter idle\fR [list \fBafter\fR 0 doOneStep]
+   }
 }
 doOneStep
 .CE
diff --git a/doc/array.n b/doc/array.n
index c62e772..d0db722 100644
--- a/doc/array.n
+++ b/doc/array.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: array.n,v 1.8.18.2 2003/07/15 22:18:02 dkf Exp $
+'\" RCS: @(#) $Id: array.n,v 1.8.18.3 2004/10/27 14:23:41 dkf Exp $
 '\" 
 .so man.macros
 .TH array n 8.3 Tcl "Tcl Built-In Commands"
@@ -137,26 +137,25 @@ error will be raised.  If \fIpattern\fR is omitted and \fIarrayName\fR is
 an array variable, then the command unsets the entire array.
 The command always returns an empty string.
 .VE 8.3
-
 .SH EXAMPLES
 .CS
-array set colorcount {
+\fBarray set\fR colorcount {
     red   1
     green 5
     blue  4
     white 9
 }
 
-foreach {color count} [array get colorcount] {
-    puts "Color: $color Count: $count" 
+foreach {color count} [\fBarray get\fR colorcount] {
+   puts "Color: $color Count: $count" 
 }
  => Color: blue Count: 4
     Color: white Count: 9
     Color: green Count: 5
     Color: red Count: 1
 
-foreach color [array names colorcount] {
-    puts "Color: $color Count: $colorcount($color)" 
+foreach color [\fBarray names\fR colorcount] {
+   puts "Color: $color Count: $colorcount($color)" 
 }
  => Color: blue Count: 4
     Color: white Count: 9
@@ -171,7 +170,7 @@ foreach color [lsort [array names colorcount]] {
     Color: red Count: 1
     Color: white Count: 9
 
-array statistics colorcount
+\fBarray statistics\fR colorcount
  => 4 entries in table, 4 buckets
     number of buckets with 0 entries: 1
     number of buckets with 1 entries: 2
diff --git a/doc/binary.n b/doc/binary.n
index 4e38f64..582b562 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.6 2004/10/27 09:35:38 dkf Exp $
+'\" RCS: @(#) $Id: binary.n,v 1.11.2.7 2004/10/27 14:23:41 dkf Exp $
 '\" 
 .so man.macros
 .TH binary n 8.0 Tcl "Tcl Built-In Commands"
@@ -645,7 +645,7 @@ 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
+    puts -nonewline [\fBbinary format\fR Ia* \e
             [string length $data] $data]
 }
 .CE
@@ -654,7 +654,7 @@ 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]} {
+    if {![\fBbinary scan\fR [read $channel 4] I length]} {
         error "missing length"
     }
     set data [read $channel $length]
diff --git a/doc/clock.n b/doc/clock.n
index 630683e..436e7da 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.3 2004/10/27 09:35:38 dkf Exp $
+'\" RCS: @(#) $Id: clock.n,v 1.11.2.4 2004/10/27 14:23:41 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% \fBclock\fR scan "1 day" -base [\fBclock\fR scan 1999-10-31]
+\fB% \fBclock scan\fR "1 day" -base [\fBclock scan\fR 1999-10-31]
 941443200
-% \fBclock\fR scan "24 hours" -base [\fBclock\fR scan 1999-10-31]
+% \fBclock scan\fR "24 hours" -base [\fBclock scan\fR 1999-10-31]
 941439600\fR
 .CE
 .RE
diff --git a/doc/dde.n b/doc/dde.n
index 1e81f87..925d622 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.2.1 2004/10/27 09:35:38 dkf Exp $
+'\" RCS: @(#) $Id: dde.n,v 1.8.2.2 2004/10/27 14:23:56 dkf Exp $
 '\" 
 .so man.macros
 .TH dde n 1.2 dde "Tcl Bundled Packages"
@@ -142,7 +142,7 @@ 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/
+\fBdde execute\fR iexplore WWW_OpenURL http://www.tcl.tk/
 .CE
 
 .SH "SEE ALSO"
diff --git a/doc/encoding.n b/doc/encoding.n
index cf59cd1..3c8893f 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.2 2004/10/27 09:35:38 dkf Exp $
+'\" RCS: @(#) $Id: encoding.n,v 1.3.18.3 2004/10/27 14:23:56 dkf Exp $
 '\" 
 .so man.macros
 .TH encoding n "8.1" Tcl "Tcl Built-In Commands"
@@ -21,13 +21,12 @@ Strings in Tcl are encoded using 16-bit Unicode characters.  Different
 operating system interfaces or applications may generate strings in
 other encodings such as Shift-JIS.  The \fBencoding\fR command helps
 to bridge the gap between Unicode and these other formats.
-
 .SH DESCRIPTION
 .PP
 Performs one of several encoding related operations, depending on
 \fIoption\fR.  The legal \fIoption\fRs are:
 .TP
-\fBencoding convertfrom ?\fIencoding\fR? \fIdata\fR
+\fBencoding convertfrom\fR ?\fIencoding\fR? \fIdata\fR
 Convert \fIdata\fR to Unicode from the specified \fIencoding\fR.  The
 characters in \fIdata\fR are treated as binary data where the lower
 8-bits of each character is taken as a single byte.  The resulting
@@ -35,7 +34,7 @@ sequence of bytes is treated as a string in the specified
 \fIencoding\fR.  If \fIencoding\fR is not specified, the current
 system encoding is used.
 .TP
-\fBencoding convertto ?\fIencoding\fR? \fIstring\fR
+\fBencoding convertto\fR ?\fIencoding\fR? \fIstring\fR
 Convert \fIstring\fR from Unicode to the specified \fIencoding\fR.
 The result is a sequence of bytes that represents the converted
 string.  Each byte is stored in the lower 8-bits of a Unicode
@@ -50,7 +49,6 @@ currently available.
 Set the system encoding to \fIencoding\fR. If \fIencoding\fR is
 omitted then the command returns the current system encoding.  The
 system encoding is used whenever Tcl passes strings to system calls.
-
 .SH EXAMPLE
 .PP
 It is common practice to write script files using a text editor that
@@ -71,7 +69,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 [\fBencoding\fR convertfrom euc-jp "\\xA4\\xCF"]
+set s [\fBencoding convertfrom\fR euc-jp "\\xA4\\xCF"]
 .CE
 would return the Unicode string "\\u306F", which is the Hiragana
 letter HA.
diff --git a/doc/file.n b/doc/file.n
index d97f2b0..bd32dee 100644
--- a/doc/file.n
+++ b/doc/file.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: file.n,v 1.23.2.1 2004/10/27 12:52:40 dkf Exp $
+'\" RCS: @(#) $Id: file.n,v 1.23.2.2 2004/10/27 14:23:56 dkf Exp $
 '\" 
 .so man.macros
 .TH file n 8.3 Tcl "Tcl Built-In Commands"
@@ -424,22 +424,22 @@ that have a correspondingly-named object file in the current
 directory:
 .CS
 proc findMatchingCFiles {dir} {
-    set files {}
-    switch $::tcl_platform(platform) {
-        windows {
-            set ext .obj
-        }
-        unix {
-            set ext .o
-        }
-    }
-    foreach file [glob -nocomplain -directory $dir *.c] {
-        set objectFile [\fBfile\fR tail [\fBfile\fR rootname $file]]$ext
-        if {[\fBfile\fR exists $objectFile]} {
-            lappend files $file
-        }
-    }
-    return $files
+   set files {}
+   switch $::tcl_platform(platform) {
+      windows {
+         set ext .obj
+      }
+      unix {
+         set ext .o
+      }
+   }
+   foreach file [glob -nocomplain -directory $dir *.c] {
+      set objectFile [\fBfile tail\fR [\fBfile rootname\fR $file]]$ext
+      if {[\fBfile exists\fR $objectFile]} {
+         lappend files $file
+      }
+   }
+   return $files
 }
 .CE
 .PP
@@ -449,11 +449,11 @@ to the new place:
 set oldName foobar.txt
 set newName foo/bar.txt
 # Make sure that where we're going to move to exists...
-if {![\fBfile\fR isdirectory [\fBfile\fR dirname $newName]]} {
-    \fBfile\fR mkdir [\fBfile\fR dirname $newName]
+if {![\fBfile isdirectory\fR [\fBfile dirname\fR $newName]]} {
+   \fBfile mkdir\fR [\fBfile dirname\fR $newName]
 }
-\fBfile\fR rename $oldName $newName
-\fBfile\fR link -symbolic $oldName $newName
+\fBfile rename\fR $oldName $newName
+\fBfile link\fR -symbolic $oldName $newName
 .CE
 
 .SH "SEE ALSO"
diff --git a/doc/info.n b/doc/info.n
index dc94649..181c4f7 100644
--- a/doc/info.n
+++ b/doc/info.n
@@ -7,7 +7,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: info.n,v 1.8.2.2 2004/10/27 12:52:40 dkf Exp $
+'\" RCS: @(#) $Id: info.n,v 1.8.2.3 2004/10/27 14:23:56 dkf Exp $
 '\" 
 .so man.macros
 .TH info n 8.4 Tcl "Tcl Built-In Commands"
@@ -214,8 +214,8 @@ script:
 proc printProc {procName} {
     set result [list proc $procName]
     set formals {}
-    foreach var [\fBinfo\fR args $procName] {
-        if {[\fBinfo\fR default $procName $var def]} {
+    foreach var [\fBinfo args\fR $procName] {
+        if {[\fBinfo default\fR $procName $var def]} {
             lappend formals [list $var $def]
         } else {
             # Still need the list-quoting because variable
@@ -223,7 +223,7 @@ proc printProc {procName} {
             lappend formals [list $var]
         }
     }
-    puts [lappend result $formals [\fBinfo\fR body $procName]]
+    puts [lappend result $formals [\fBinfo body\fR $procName]]
 }
 .CE
 
diff --git a/doc/interp.n b/doc/interp.n
index a118e50..8b1815a 100644
--- a/doc/interp.n
+++ b/doc/interp.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: interp.n,v 1.9.2.1 2004/10/27 12:52:40 dkf Exp $
+'\" RCS: @(#) $Id: interp.n,v 1.9.2.2 2004/10/27 14:23:56 dkf Exp $
 '\" 
 .so man.macros
 .TH interp n 7.6 Tcl "Tcl Built-In Commands"
@@ -618,23 +618,23 @@ by Nathaniel Borenstein and Marshall Rose.
 .SH EXAMPLES
 Creating and using an alias for a command in the current interpreter:
 .CS
-\fBinterp\fR alias {} getIndex {} lsearch {alpha beta gamma delta}
+\fBinterp alias\fR {} getIndex {} lsearch {alpha beta gamma delta}
 set idx [getIndex delta]
 .CE
 .PP
 Executing an arbitrary command in a safe interpreter where every
 invokation of \fBlappend\fR is logged:
 .CS
-set i [\fBinterp\fR create -safe]
-\fBinterp\fR hide $i lappend
-\fBinterp\fR alias $i lappend {} loggedLappend $i
+set i [\fBinterp create\fR -safe]
+\fBinterp hide\fR $i lappend
+\fBinterp alias\fR $i lappend {} loggedLappend $i
 proc loggedLappend {i args} {
    puts "logged invokation of lappend $args"
    # Be extremely careful about command construction
    eval [linsert $args 0 \\
-         \fBinterp\fR invokehidden $i lappend]
+         \fBinterp invokehidden\fR $i lappend]
 }
-\fBinterp\fR eval $i $someUntrustedScript
+\fBinterp eval\fR $i $someUntrustedScript
 .CE
 
 .SH "SEE ALSO"
diff --git a/doc/msgcat.n b/doc/msgcat.n
index f7ba2fc..87626b2 100644
--- a/doc/msgcat.n
+++ b/doc/msgcat.n
@@ -48,7 +48,6 @@ the message catalog.
 Use of the message catalog is optional by any application
 or package, but is encouraged if the application or package
 wishes to be enabled for multi-lingual applications.
-
 .SH COMMANDS
 .TP
 \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR?
@@ -56,7 +55,7 @@ Returns a translation of \fIsrc-string\fR according to the
 user's current locale.  If additional arguments past \fIsrc-string\fR
 are given, the \fBformat\fR command is used to substitute the
 additional arguments in the translation of \fIsrc-string\fR.
-
+.PP
 \fB::msgcat::mc\fR will search the messages defined
 in the current namespace for a translation of \fIsrc-string\fR; if
 none is found, it will search in the parent of the current namespace,
@@ -91,10 +90,10 @@ Returns an ordered list of the locales preferred by
 the user, based on the user's language specification.
 The list is ordered from most specific to least
 preference.  The list is derived from the current
-locale set in msgcat by \fBmsgcat::mclocale\fR, and
+locale set in msgcat by \fB::msgcat::mclocale\fR, and
 cannot be set independently.  For example, if the
-current locale is en_US_funky, then \fBmsgcat::mcpreferences\fR
-returns {en_US_funky en_US en}.
+current locale is en_US_funky, then \fB::msgcat::mcpreferences\fR
+returns \fB{en_US_funky en_US en}\fR.
 .TP
 \fB::msgcat::mcload \fIdirname\fR
 Searches the specified directory for files that match
@@ -120,8 +119,8 @@ Sets the translation for multiple source strings in
 namespace.
 \fIsrc-trans-list\fR must have an even number of elements and is in
 the form {\fIsrc-string translate-string\fR ?\fIsrc-string
-translate-string ...\fR?} \fBmsgcat::mcmset\fR can be significantly
-faster than multiple invocations of \fBmsgcat::mcset\fR. The function
+translate-string ...\fR?} \fB::msgcat::mcmset\fR can be significantly
+faster than multiple invocations of \fB::msgcat::mcset\fR. The function
 returns the number of translations set.
 .TP
 \fB::msgcat::mcunknown \fIlocale src-string\fR
@@ -134,7 +133,6 @@ string.  The \fB::msgcat::mcunknown\fR procedure is invoked at the
 same stack context as the call to \fB::msgcat::mc\fR.  The return value
 of \fB::msgcat::mcunknown\fR is used as the return value for the call
 to \fB::msgcat::mc\fR.  
-
 .SH "LOCALE SPECIFICATION"
 .PP
 The locale is specified to \fBmsgcat\fR by a locale string
@@ -155,7 +153,7 @@ initial locale.  The value is parsed according to the XPG4 pattern
 language[_country][.codeset][@modifier]
 .CE
 to extract its parts.  The initial locale is then set by calling
-\fBmsgcat::mclocale\fR with the argument 
+\fB::msgcat::mclocale\fR with the argument 
 .CS
 language[_country][_modifier]
 .CE
@@ -171,7 +169,6 @@ en_GB_Funky, the locales ``en_GB_Funky'', ``en_GB'', and ``en'' are
 searched in order until a matching translation string is found.  If no
 translation string is available, then \fB::msgcat::unknown\fR is
 called.
-
 .SH "NAMESPACES AND MESSAGE CATALOGS"
 .PP
 Strings stored in the message catalog are stored relative
@@ -183,10 +180,12 @@ error.
 .PP
 For example, executing the code
 .CS
-mcset en hello "hello from ::"
-namespace eval foo {mcset en hello "hello from ::foo"}
-puts [mc hello]
-namespace eval foo {puts [mc hello]}
+\fB::msgcat::mcset\fR en hello "hello from ::"
+namespace eval foo {
+   \fB::msgcat::mcset\fR en hello "hello from ::foo"
+}
+puts [\fB::msgcat::mc\fR hello]
+namespace eval foo {puts [\fB::msgcat::mc\fR hello]}
 .CE
 will print
 .CS
@@ -202,19 +201,20 @@ to "inherit" messages from their parent namespace.
 .PP
 For example, executing (in the ``en'' locale) the code 
 .CS
-mcset en m1 ":: message1"
-mcset en m2 ":: message2"
-mcset en m3 ":: message3"
+\fB::msgcat::mcset\fR en m1 ":: message1"
+\fB::msgcat::mcset\fR en m2 ":: message2"
+\fB::msgcat::mcset\fR en m3 ":: message3"
 namespace eval ::foo {
-    mcset en m2 "::foo message2"
-    mcset en m3 "::foo message3"
+   \fB::msgcat::mcset\fR en m2 "::foo message2"
+   \fB::msgcat::mcset\fR en m3 "::foo message3"
 }
 namespace eval ::foo::bar {
-    mcset en m3 "::foo::bar message3"
+   \fB::msgcat::mcset\fR en m3 "::foo::bar message3"
 }
-puts "[mc m1]; [mc m2]; [mc m3]"
-namespace eval ::foo {puts "[mc m1]; [mc m2]; [mc m3]"}
-namespace eval ::foo::bar {puts "[mc m1]; [mc m2]; [mc m3]"}
+namespace import \fB::msgcat::mc\fR
+puts "[\fBmc\fR m1]; [\fBmc\fR m2]; [\fBmc\fR m3]"
+namespace eval ::foo {puts "[\fBmc\fR m1]; [\fBmc\fR m2]; [\fBmc\fR m3]"}
+namespace eval ::foo::bar {puts "[\fBmc\fR m1]; [\fBmc\fR m2]; [\fBmc\fR m3]"}
 .CE
 will print
 .CS
@@ -222,7 +222,6 @@ will print
 :: message1; ::foo message2; ::foo message3
 :: message1; ::foo message2; ::foo::bar message3
 .CE
-
 .SH "LOCATION AND FORMAT OF MESSAGE FILES"
 .PP
 Message files can be located in any directory, subject
@@ -244,10 +243,9 @@ so that all source strings are tied to the namespace of
 the package. For example, a short \fBes.msg\fR might contain:
 .CS
 namespace eval ::mypackage {
-    ::msgcat::mcset es "Free Beer!" "Cerveza Gracias!"
+   \fB::msgcat::mcset\fR es "Free Beer!" "Cerveza Gracias!"
 }
 .CE
-
 .SH "RECOMMENDED MESSAGE SETUP FOR PACKAGES"
 .PP
 If a package is installed into a subdirectory of the
@@ -263,9 +261,8 @@ Copy your *.msg files into that directory.
 initialization script:
 .CS
 # load language files, stored in msgs subdirectory
-::msgcat::mcload [file join [file dirname [info script]] msgs]
+\fB::msgcat::mcload\fR [file join [file dirname [info script]] msgs]
 .CE
-
 .SH "POSITIONAL CODES FOR FORMAT AND SCAN COMMANDS"
 .PP
 It is possible that a message string used as an argument
@@ -287,7 +284,6 @@ format "In location %2\\$s we produced %1\\$d units" $num $city
 .PP
 Similarly, positional parameters can be used with \fBscan\fR to
 extract values from internationalized strings.
-
 .SH CREDITS
 .PP
 The message catalog code was developed by Mark Harrison.
diff --git a/doc/namespace.n b/doc/namespace.n
index c79ce08..e93a704 100644
--- a/doc/namespace.n
+++ b/doc/namespace.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: namespace.n,v 1.9 2003/01/21 20:06:11 jenglish Exp $
+'\" RCS: @(#) $Id: namespace.n,v 1.9.2.1 2004/10/27 14:23:57 dkf Exp $
 '\" 
 .so man.macros
 .TH namespace n 8.0 Tcl "Tcl Built-In Commands"
@@ -24,8 +24,8 @@ The \fBnamespace\fR command lets you create, access, and destroy
 separate contexts for commands and variables.
 See the section \fBWHAT IS A NAMESPACE?\fR below
 for a brief overview of namespaces.
-The legal \fIoption\fR's are listed below.
-Note that you can abbreviate the \fIoption\fR's.
+The legal values of \fIoption\fR are listed below.
+Note that you can abbreviate the \fIoption\fRs.
 .TP
 \fBnamespace children \fR?\fInamespace\fR? ?\fIpattern\fR?
 Returns a list of all child namespaces that belong to the
@@ -33,14 +33,14 @@ namespace \fInamespace\fR.
 If \fInamespace\fR is not specified,
 then the children are returned for the current namespace.
 This command returns fully-qualified names,
-which start with \fB::\fR.
+which start with a double colon (\fB::\fR).
 If the optional \fIpattern\fR is given,
 then this command returns only the names that match the glob-style pattern.
 The actual pattern used is determined as follows:
-a pattern that starts with \fB::\fR is used directly,
+a pattern that starts with double colon (\fB::\fR) is used directly,
 otherwise the namespace \fInamespace\fR
 (or the fully-qualified name of the current namespace)
-is prepended onto the the pattern.
+is prepended onto the pattern.
 .TP
 \fBnamespace code \fIscript\fR
 Captures the current namespace context for later execution
@@ -66,7 +66,7 @@ extensions like Tk normally execute callback scripts
 in the global namespace.
 A scoped command captures a command together with its namespace context
 in a way that allows it to be executed properly later.
-See the section \fBSCOPED VALUES\fR for some examples
+See the section \fBSCOPED SCRIPTS\fR for some examples
 of how this is used to create callback scripts.
 .TP
 \fBnamespace current\fR
@@ -129,7 +129,7 @@ this command returns the namespace's current export list.
 Removes previously imported commands from a namespace.
 Each \fIpattern\fR is a simple or qualified name such as
 \fBx\fR, \fBfoo::x\fR or \fBa::b::p*\fR.
-Qualified names contain \fB::\fRs and qualify a name
+Qualified names contain double colons (\fB::\fR) and qualify a name
 with the name of one or more namespaces.
 Each \fIqualified pattern\fR is qualified with the name of an
 exporting namespace 
@@ -211,7 +211,7 @@ the fully-qualified name of the current namespace's parent is returned.
 .TP
 \fBnamespace qualifiers\fR \fIstring\fR
 Returns any leading namespace qualifiers for \fIstring\fR.
-Qualifiers are namespace names separated by \fB::\fRs.
+Qualifiers are namespace names separated by double colons (\fB::\fR).
 For the \fIstring\fR \fB::foo::bar::x\fR,
 this command returns \fB::foo::bar\fR,
 and for \fB::\fR it returns an empty string.
@@ -222,7 +222,7 @@ the names of currently defined namespaces.
 .TP
 \fBnamespace tail\fR \fIstring\fR
 Returns the simple name at the end of a qualified string.
-Qualifiers are namespace names separated by \fB::\fRs.
+Qualifiers are namespace names separated by double colons (\fB::\fR).
 For the \fIstring\fR \fB::foo::bar::x\fR,
 this command returns \fBx\fR,
 and for \fB::\fR it returns an empty string.
@@ -244,7 +244,6 @@ fully-qualified name of the variable.
 If no flag is given, \fIname\fR is treated as a command name.
 See the section \fBNAME RESOLUTION\fR below for an explanation of
 the rules regarding name resolution.
-
 .SH "WHAT IS A NAMESPACE?"
 .PP
 A namespace is a collection of commands and variables.
@@ -256,15 +255,15 @@ The global namespace holds all global variables and commands.
 The \fBnamespace eval\fR command lets you create new namespaces.
 For example,
 .CS
-\fBnamespace eval Counter {
-    namespace export bump
-    variable num 0
+\fBnamespace eval\fR Counter {
+   \fBnamespace export\fR bump
+   variable num 0
 
-    proc bump {} {
-        variable num
-        incr num
-    }
-}\fR
+   proc bump {} {
+      variable num
+      incr num
+   }
+}
 .CE
 creates a new namespace containing the variable \fBnum\fR and
 the procedure \fBbump\fR.
@@ -286,21 +285,21 @@ namespace over time using a series of \fBnamespace eval\fR commands.
 For example, the following series of commands has the same effect
 as the namespace definition shown above:
 .CS
-\fBnamespace eval Counter {
-    variable num 0
-    proc bump {} {
-        variable num
-        return [incr num]
-    }
+\fBnamespace eval\fR Counter {
+   variable num 0
+   proc bump {} {
+      variable num
+      return [incr num]
+   }
 }
-namespace eval Counter {
-    proc test {args} {
-        return $args
-    }
+\fBnamespace eval\fR Counter {
+   proc test {args} {
+      return $args
+   }
 }
-namespace eval Counter {
+\fBnamespace eval\fR Counter {
     rename test ""
-}\fR
+}
 .CE
 Note that the \fBtest\fR procedure is added to the \fBCounter\fR namespace,
 and later removed via the \fBrename\fR command.
@@ -309,7 +308,6 @@ Namespaces can have other namespaces within them,
 so they nest hierarchically.
 A nested namespace is encapsulated inside its parent namespace
 and can not interfere with other namespaces.
-
 .SH "QUALIFIED NAMES"
 .PP
 Each namespace has a textual name such as
@@ -325,8 +323,8 @@ The topmost or global namespace has the name ``'' (i.e., an empty string),
 although \fB::\fR is a synonym.
 As an example, the name \fB::safe::interp::create\fR
 refers to the command \fBcreate\fR in the namespace \fBinterp\fR
-that is a child of of namespace \fB::safe\fR,
-which in turn is a child of the global namespace \fB::\fR.
+that is a child of namespace \fB::safe\fR,
+which in turn is a child of the global namespace, \fB::\fR.
 .PP
 If you want to access commands and variables from another namespace,
 you must use some extra syntax.
@@ -334,12 +332,12 @@ Names must be qualified by the namespace that contains them.
 From the global namespace,
 we might access the \fBCounter\fR procedures like this:
 .CS
-\fBCounter::bump 5
-Counter::Reset\fR
+Counter::bump 5
+Counter::Reset
 .CE
 We could access the current count like this:
 .CS
-\fBputs "count = $Counter::num"\fR
+puts "count = $Counter::num"
 .CE
 When one namespace contains another, you may need more than one
 qualifier to reach its elements.
@@ -347,18 +345,18 @@ If we had a namespace \fBFoo\fR that contained the namespace \fBCounter\fR,
 you could invoke its \fBbump\fR procedure
 from the global namespace like this:
 .CS
-\fBFoo::Counter::bump 3\fR
+Foo::Counter::bump 3
 .CE
 .PP
 You can also use qualified names when you create and rename commands.
 For example, you could add a procedure to the \fBFoo\fR
 namespace like this:
 .CS
-\fBproc Foo::Test {args} {return $args}\fR
+proc Foo::Test {args} {return $args}
 .CE
 And you could move the same procedure to another namespace like this:
 .CS
-\fBrename Foo::Test Bar::Test\fR
+rename Foo::Test Bar::Test
 .CE
 .PP
 There are a few remaining points about qualified names
@@ -366,12 +364,11 @@ that we should cover.
 Namespaces have nonempty names except for the global namespace.
 \fB::\fR is disallowed in simple command, variable, and namespace names
 except as a namespace separator.
-Extra \fB:\fRs in a qualified name are ignored;
-that is, two or more \fB:\fRs are treated as a namespace separator.
+Extra colons in any separator part of a qualified name are ignored;
+i.e. two or more colons are treated as a namespace separator.
 A trailing \fB::\fR in a qualified variable or command name
 refers to the variable or command named {}.
 However, a trailing \fB::\fR in a qualified namespace name is ignored.
-
 .SH "NAME RESOLUTION"
 .PP
 In general, all Tcl commands that take variable and command names
@@ -392,10 +389,10 @@ by looking in only the current namespace.
 .PP
 In the following example,
 .CS
-\fBset traceLevel 0
-namespace eval Debug {
-    printTrace $traceLevel
-}\fR
+set traceLevel 0
+\fBnamespace eval\fR Debug {
+   printTrace $traceLevel
+}
 .CE
 Tcl looks for \fBtraceLevel\fR in the namespace \fBDebug\fR
 and then in the global namespace.
@@ -404,14 +401,14 @@ If a variable or command name is not found in either context,
 the name is undefined.
 To make this point absolutely clear, consider the following example:
 .CS
-\fBset traceLevel 0
-namespace eval Foo {
-    variable traceLevel 3
+set traceLevel 0
+\fBnamespace eval\fR Foo {
+   variable traceLevel 3
 
-    namespace eval Debug {
-        printTrace $traceLevel
-    }
-}\fR
+   \fBnamespace eval\fR Debug {
+      printTrace $traceLevel
+   }
+}
 .CE
 Here Tcl looks for \fBtraceLevel\fR first in the namespace \fBFoo::Debug\fR.
 Since it is not found there, Tcl then looks for it 
@@ -423,12 +420,12 @@ You can use the \fBnamespace which\fR command to clear up any question
 about name resolution.
 For example, the command:
 .CS
-\fBnamespace eval Foo::Debug {namespace which \-variable traceLevel}\fR
+\fBnamespace eval\fR Foo::Debug {\fBnamespace which\fR \-variable traceLevel}
 .CE
 returns \fB::traceLevel\fR.
 On the other hand, the command,
 .CS
-\fBnamespace eval Foo {namespace which \-variable traceLevel}\fR
+\fBnamespace eval\fR Foo {\fBnamespace which\fR \-variable traceLevel}
 .CE
 returns \fB::Foo::traceLevel\fR.
 .PP
@@ -439,7 +436,7 @@ Namespace names are always resolved in the current namespace.
 This means, for example,
 that a \fBnamespace eval\fR command that creates a new namespace
 always creates a child of the current namespace
-unless the new namespace name begins with a \fB::\fR.
+unless the new namespace name begins with \fB::\fR.
 .PP
 Tcl has no access control to limit what variables, commands,
 or namespaces you can reference.
@@ -459,7 +456,6 @@ to variables in the global namespace.
 It is not necessary to use a \fBvariable\fR command
 if you always refer to the namespace variable using an
 appropriate qualified name.
-
 .SH "IMPORTING COMMANDS"
 .PP
 Namespaces are often used to represent libraries.
@@ -469,21 +465,21 @@ For example, suppose that all of the commands in a package
 like BLT are contained in a namespace called \fBBlt\fR.
 Then you might access these commands like this:
 .CS
-\fBBlt::graph .g \-background red
-Blt::table . .g 0,0\fR
+Blt::graph .g \-background red
+Blt::table . .g 0,0
 .CE
 If you use the \fBgraph\fR and \fBtable\fR commands frequently,
 you may want to access them without the \fBBlt::\fR prefix.
 You can do this by importing the commands into the current namespace,
 like this:
 .CS
-\fBnamespace import Blt::*\fR
+\fBnamespace import\fR Blt::*
 .CE
 This adds all exported commands from the \fBBlt\fR namespace
 into the current namespace context, so you can write code like this:
 .CS
-\fBgraph .g \-background red
-table . .g 0,0\fR
+graph .g \-background red
+table . .g 0,0
 .CE
 The \fBnamespace import\fR command only imports commands
 from a namespace that that namespace exported
@@ -494,7 +490,7 @@ a bad idea since you don't know what you will get.
 It is better to import just the specific commands you need.
 For example, the command
 .CS
-\fBnamespace import Blt::graph Blt::table\fR
+\fBnamespace import\fR Blt::graph Blt::table
 .CE
 imports only the \fBgraph\fR and \fBtable\fR commands into the
 current context.
@@ -507,12 +503,12 @@ reissue the \fBnamespace import\fR command to pick up new commands
 that have appeared in a namespace.  In that case, you can use the
 \fB\-force\fR option, and existing commands will be silently overwritten:
 .CS
-\fBnamespace import \-force Blt::graph Blt::table\fR
+\fBnamespace import\fR \-force Blt::graph Blt::table
 .CE
 If for some reason, you want to stop using the imported commands,
-you can remove them with an \fBnamespace forget\fR command, like this:
+you can remove them with a \fBnamespace forget\fR command, like this:
 .CS
-\fBnamespace forget Blt::*\fR
+\fBnamespace forget\fR Blt::*
 .CE
 This searches the current namespace for any commands imported from \fBBlt\fR.
 If it finds any, it removes them.  Otherwise, it does nothing.
@@ -521,42 +517,41 @@ prefix.
 .PP
 When you delete a command from the exporting namespace like this:
 .CS
-\fBrename Blt::graph ""\fR
+rename Blt::graph ""
 .CE
 the command is automatically removed from all namespaces that import it.
-
 .SH "EXPORTING COMMANDS"
 You can export commands from a namespace like this:
 .CS
-\fBnamespace eval Counter {
-    namespace export bump reset
-    variable Num 0
-    variable Max 100
+\fBnamespace eval\fR Counter {
+   \fBnamespace export\fR bump reset
+   variable Num 0
+   variable Max 100
 
-    proc bump {{by 1}} {
-        variable Num
-        incr Num $by
-        Check
-        return $Num
-    }
-    proc reset {} {
-        variable Num
-        set Num 0
-    }
-    proc Check {} {
-        variable Num
-        variable Max
-        if {$Num > $Max} {
-            error "too high!"
-        }
-    }
-}\fR
+   proc bump {{by 1}} {
+      variable Num
+      incr Num $by
+      Check
+      return $Num
+   }
+   proc reset {} {
+      variable Num
+      set Num 0
+   }
+   proc Check {} {
+      variable Num
+      variable Max
+      if {$Num > $Max} {
+         error "too high!"
+      }
+   }
+}
 .CE
 The procedures \fBbump\fR and \fBreset\fR are exported,
 so they are included when you import from the \fBCounter\fR namespace,
 like this:
 .CS
-\fBnamespace import Counter::*\fR
+\fBnamespace import\fR Counter::*
 .CE
 However, the \fBCheck\fR procedure is not exported,
 so it is ignored by the import operation.
@@ -567,6 +562,56 @@ The \fBnamespace export\fR command specifies what commands
 may be imported by other namespaces.
 If a \fBnamespace import\fR command specifies a command
 that is not exported, the command is not imported.
+.SH "SCOPED SCRIPTS"
+The \fBnamespace code\fR command is the means by which a script may be
+packaged for evaluation in a namespace other than the one in which it
+was created.  It is used most often to create event handlers, Tk bindings,
+and traces for evaluation in the global context.  For instance, the following
+code indicates how to direct a variable trace callback into the current
+namespace:
+.CS
+\fBnamespace eval\fR a {
+   variable b
+   proc theTraceCallback { n1 n2 op } {
+      upvar 1 $n1 var
+      puts "the value of $n1 has changed to $var"
+      return
+   }
+   trace variable b w [\fBnamespace code\fR theTraceCallback]
+}
+set a::b c
+.CE
+When executed, it prints the message:
+.CS
+the value of a::b has changed to c
+.CE
+.SH EXAMPLES
+Create a namespace containing a variable and an exported command:
+.CS
+\fBnamespace eval\fR foo {
+   variable bar 0
+   proc grill {} {
+      variable bar
+      puts "called [incr bar] times"
+   }
+   \fBnamespace export\fR grill
+}
+.CE
+.PP
+Call the command defined in the previous example in various ways.
+.CS
+# Direct call
+foo::grill
+
+# Import into current namespace, then call local alias
+namespace import foo::grill
+grill
+.CE
+.PP
+Look up where the command imported in the previous example came from:
+.CS
+puts "grill came from [\fBnamespace which\fR grill]"
+.CE
 
 .SH "SEE ALSO"
 variable(n)
diff --git a/doc/open.n b/doc/open.n
index 9ef9754..4322dde 100644
--- a/doc/open.n
+++ b/doc/open.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: open.n,v 1.16.2.1 2003/04/18 00:32:34 dkf Exp $
+'\" RCS: @(#) $Id: open.n,v 1.16.2.2 2004/10/27 14:23:57 dkf Exp $
 '\" 
 .so man.macros
 .TH open n 8.3 Tcl "Tcl Built-In Commands"
@@ -132,7 +132,15 @@ standard input for the pipeline is taken from the current standard
 input unless overridden by the command.
 The id of the spawned process is accessible through the \fBpid\fR
 command, using the channel id returned by \fBopen\fR as argument.
-
+.PP
+If the command (or one of the commands) executed in the command
+pipeline returns an error (according to the definition in \fBexec\fR),
+a Tcl error is generated when \fBclose\fR is called on the channel
+(similar to the \fBclose\fR command.)
+.PP
+It is often useful to use the \fBfileevent\fR command with pipelines
+so other processing may happen at the same time as running the command
+in the background.
 .VS 8.4
 .SH "SERIAL COMMUNICATIONS"
 .PP
@@ -333,7 +341,7 @@ between the real console, if one is present, and a command pipeline that uses
 standard input or output.  If a command pipeline is opened for reading, some
 of the lines entered at the console will be sent to the command pipeline and
 some will be sent to the Tcl evaluator.  If a command pipeline is opened for
-writing, keystrokes entered into the console are not visible until the the
+writing, keystrokes entered into the console are not visible until the
 pipe is closed.  This behavior occurs whether the command pipeline is
 executing 16-bit or 32-bit applications.  These problems only occur because
 both Tcl and the child application are competing for the console at
@@ -356,7 +364,7 @@ standard input or output.  If a command pipeline is opened for reading from
 a 32-bit application, some of the keystrokes entered at the console will be
 sent to the command pipeline and some will be sent to the Tcl evaluator.  If
 a command pipeline is opened for writing to a 32-bit application, no output
-is visible on the console until the the pipe is closed.  These problems only
+is visible on the console until the pipe is closed.  These problems only
 occur because both Tcl and the child application are competing for the
 console at the same time.  If the command pipeline is started from a script,
 so that Tcl is not accessing the console, or if the command pipeline does
@@ -399,6 +407,15 @@ input, but is redirected from a file, then the above problem does not occur.
 See the PORTABILITY ISSUES section of the \fBexec\fR command for additional
 information not specific to command pipelines about executing
 applications on the various platforms
+.SH "EXAMPLE"
+Open a command pipeline and catch any errors:
+.CS
+set fl [\fBopen\fR "| ls this_file_does_not_exist"]
+set data [read $fl]
+if {[catch {close $fl} err]} {
+    puts "ls command failed: $err"
+}
+.CE
 
 .SH "SEE ALSO"
 file(n), close(n), filename(n), fconfigure(n), gets(n), read(n),
diff --git a/doc/package.n b/doc/package.n
index 1ede10f..02ac630 100644
--- a/doc/package.n
+++ b/doc/package.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: package.n,v 1.6 2002/01/27 17:35:06 dgp Exp $
+'\" RCS: @(#) $Id: package.n,v 1.6.2.1 2004/10/27 14:23:57 dkf Exp $
 '\" 
 .so man.macros
 .TH package n 7.5 Tcl "Tcl Built-In Commands"
@@ -90,7 +90,7 @@ provided by a previous \fBpackage provide\fR command.
 If the \fIversion\fR argument is omitted, then the command
 returns the version number that is currently provided, or an
 empty string if no \fBpackage provide\fR command has been
-invoked for \fIpackage\fR in this interpreter.
+invoked for \fIpackage\fR in this interpreter.  
 .TP
 \fBpackage require \fR?\fB\-exact\fR? \fIpackage \fR?\fIversion\fR?
 This command is typically invoked by Tcl code that wishes to use
@@ -161,7 +161,6 @@ Returns 1 if scripts written for \fIversion2\fR will work unchanged
 with \fIversion1\fR (i.e. \fIversion1\fR is equal to or greater
 than \fIversion2\fR and they both have the same major version
 number), 0 otherwise.
-
 .SH "VERSION NUMBERS"
 .PP
 Version numbers consist of one or more decimal numbers separated
@@ -181,7 +180,6 @@ work unchanged under versions 2.3.2, 2.4, and 2.5.1.
 Changes in the major version number signify incompatible changes:
 if code is written to use version 2.1 of a package, it is not guaranteed
 to work unmodified with either version 1.7.3 or version 3.1.
-
 .SH "PACKAGE INDICES"
 .PP
 The recommended way to use packages in Tcl is to invoke \fBpackage require\fR
@@ -190,6 +188,31 @@ and \fBpackage provide\fR commands in scripts, and use the procedure
 Once you've done this, packages will be loaded automatically
 in response to \fBpackage require\fR commands.
 See the documentation for \fBpkg_mkIndex\fR for details.
+.SH EXAMPLES
+To state that a Tcl script requires the Tk and http packages, put this
+at the top of the script:
+.CS
+\fBpackage require\fR Tk
+\fBpackage require\fR http
+.CE
+.PP
+To test to see if the Snack package is available and load if it is
+(often useful for optional enhancements to programs where the loss of
+the functionality is not critical) do this:
+.CS
+if {[catch {\fBpackage require\fR Snack}]} {
+   # We have the package, configure the app to use it
+} else {
+   # Set up a dummy interface to work around the absence
+}
+.CE
+.PP
+When writing a package implementation, you should put the following at
+the \fIbottom\fR of your library script so it is only called once the
+package has been successfully set up:
+.CS
+\fBpackage provide\fR foobar 1.0
+.CE
 
 .SH "SEE ALSO"
 msgcat(n), packagens(n), pkgMkIndex(n)
diff --git a/doc/pid.n b/doc/pid.n
index f835b5e..9811cb7 100644
--- a/doc/pid.n
+++ b/doc/pid.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: pid.n,v 1.3 2000/09/07 14:27:50 poenitz Exp $
+'\" RCS: @(#) $Id: pid.n,v 1.3.18.1 2004/10/27 14:23:57 dkf Exp $
 '\" 
 .so man.macros
 .TH pid n 7.0 Tcl "Tcl Built-In Commands"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-pid \- Retrieve process id(s)
+pid \- Retrieve process identifiers
 .SH SYNOPSIS
 \fBpid \fR?\fIfileId\fR?
 .BE
@@ -29,6 +29,19 @@ that isn't a process pipeline.
 If no \fIfileId\fR argument is given then \fBpid\fR returns the process
 identifier of the current process.
 All process identifiers are returned as decimal strings.
+.SH EXAMPLE
+Print process information about the processes in a pipeline using the
+SysV \fBps\fR program before reading the output of that pipeline:
+.PP
+.CS
+set pipeline [open "| zcat somefile.gz | grep foobar | sort -u"]
+# Print process information
+exec ps -fp [\fBpid\fR $pipeline] >@stdout
+# Print a separator and then the output of the pipeline
+puts [string repeat - 70]
+puts [read $pipeline]
+close $pipeline
+.CE
 
 .SH "SEE ALSO"
 exec(n), open(n)
diff --git a/doc/proc.n b/doc/proc.n
index 6735ef0..031d3ea 100644
--- a/doc/proc.n
+++ b/doc/proc.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: proc.n,v 1.3 2000/09/07 14:27:50 poenitz Exp $
+'\" RCS: @(#) $Id: proc.n,v 1.3.18.1 2004/10/27 14:23:57 dkf Exp $
 '\" 
 .so man.macros
 .TH proc n "" Tcl "Tcl Built-In Commands"
@@ -69,6 +69,26 @@ invoked, the procedure's return value is the value specified in a
 executed in the procedure's body.
 If an error occurs while executing the procedure
 body, then the procedure-as-a-whole will return that same error.
+.SH EXAMPLES
+This is a procedure that accepts arbitrarily many arguments and prints
+them out, one by one.
+.CS
+\fBproc\fR printArguments args {
+   foreach arg $args {
+      puts $arg
+   }
+}
+.CE
+.PP
+This procedure is a bit like the \fBincr\fR command, except it
+multiplies the contents of the named variable by the value, which
+defaults to \fB2\fR:
+.CS
+\fBproc\fR mult {varName {multiplier 2}} {
+   upvar 1 $varName var
+   set var [expr {$var * $multiplier}]
+}
+.CE
 
 .SH "SEE ALSO"
 info(n), unknown(n)
diff --git a/doc/puts.n b/doc/puts.n
index 9a4cbdd..d9e64a0 100644
--- a/doc/puts.n
+++ b/doc/puts.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: puts.n,v 1.5 2001/09/14 19:20:40 andreas_kupries Exp $
+'\" RCS: @(#) $Id: puts.n,v 1.5.8.1 2004/10/27 14:23:57 dkf Exp $
 '\" 
 .so man.macros
 .TH puts n 7.5 Tcl "Tcl Built-In Commands"
@@ -68,6 +68,31 @@ To avoid wasting memory, nonblocking I/O should normally
 be used in an event-driven fashion with the \fBfileevent\fR command
 (don't invoke \fBputs\fR unless you have recently been notified
 via a file event that the channel is ready for more output data).
+.SH EXAMPLES
+Write a short message to the console (or wherever \fBstdout\fR is
+directed):
+.CS
+\fBputs\fR "Hello, World!"
+.CE
+.PP
+Print a message in several parts:
+.CS
+\fBputs\fR -nonewline "Hello, "
+\fBputs\fR "World!"
+.CE
+.PP
+Print a message to the standard error channel:
+.CS
+\fBputs\fR stderr "Hello, World!"
+.CE
+.PP
+Append a log message to a file:
+.CS
+set chan [open my.log a]
+set timestamp [clock format [clock seconds]]
+\fBputs\fR $chan "$timestamp - Hello, World!"
+close $chan
+.CE
 
 .SH "SEE ALSO"
 file(n), fileevent(n), Tcl_StandardChannels(3)
diff --git a/doc/pwd.n b/doc/pwd.n
index 22ec376..4f3dcd6 100644
--- a/doc/pwd.n
+++ b/doc/pwd.n
@@ -5,21 +5,35 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: pwd.n,v 1.3 2000/09/07 14:27:50 poenitz Exp $
+'\" RCS: @(#) $Id: pwd.n,v 1.3.18.1 2004/10/27 14:23:57 dkf Exp $
 '\" 
 .so man.macros
 .TH pwd n "" Tcl "Tcl Built-In Commands"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-pwd \- Return the current working directory
+pwd \- Return the absolute path of the current working directory
 .SH SYNOPSIS
 \fBpwd\fR
 .BE
 
 .SH DESCRIPTION
 .PP
-Returns the path name of the current working directory.
+Returns the absolute path name of the current working directory.
+.SH EXAMPLE
+Sometimes it is useful to change to a known directory when running
+some external command using \fBexec\fR, but it is important to keep
+the application usually running in the directory that it was started
+in (unless the user specifies otherwise) since that minimises user
+confusion. The way to do this is to save the current directory while
+the external command is being run:
+.CS
+set tarFile [file normalize somefile.tar]
+set savedDir [\fBpwd\fR]
+cd /tmp
+exec tar -xf $tarFile
+cd $savedDir
+.CE
 
 .SH "SEE ALSO"
 file(n), cd(n), glob(n), filename(n)
diff --git a/doc/read.n b/doc/read.n
index b80f134..18e3d79 100644
--- a/doc/read.n
+++ b/doc/read.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: read.n,v 1.7 2001/09/14 19:20:40 andreas_kupries Exp $
+'\" RCS: @(#) $Id: read.n,v 1.7.8.1 2004/10/27 14:23:57 dkf Exp $
 '\" 
 .so man.macros
 .TH read n 8.1 Tcl "Tcl Built-In Commands"
@@ -73,7 +73,15 @@ In this form \fBread\fR blocks until the reception of the end-of-file
 character, see \fBfconfigure -eofchar\fR. If there no end-of-file
 character has been configured for the channel, then \fBread\fR will
 block forever.
-
+.SH "EXAMPLE"
+This example code reads a file all at once, and splits it into a list,
+with each line in the file corresponding to an element in the list:
+.CS
+set fl [open /proc/meminfo]
+set data [\fBread\fR $fl]
+close $fl
+set lines [split $data \\n]
+.CE
 
 .SH "SEE ALSO"
 file(n), eof(n), fblocked(n), fconfigure(n), Tcl_StandardChannels(3)
diff --git a/doc/regexp.n b/doc/regexp.n
index 4309d26..42dc589 100644
--- a/doc/regexp.n
+++ b/doc/regexp.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: regexp.n,v 1.12 2002/10/10 14:46:57 dgp Exp $
+'\" RCS: @(#) $Id: regexp.n,v 1.12.2.1 2004/10/27 14:23:57 dkf Exp $
 '\" 
 .so man.macros
 .TH regexp n 8.3 Tcl "Tcl Built-In Commands"
@@ -126,6 +126,33 @@ in \fIexp\fR doesn't match the string (e.g. because it was in a
 portion of the expression that wasn't matched), then the corresponding
 \fIsubMatchVar\fR will be set to ``\fB\-1 \-1\fR'' if \fB\-indices\fR
 has been specified or to an empty string otherwise.
+.SH EXAMPLES
+Find the first occurrence of a word starting with \fBfoo\fR in a
+string that is not actually an instance of \fBfoobar\fR, and get the
+letters following it up to the end of the word into a variable:
+.CS
+\fBregexp\fR {\\<foo(?!bar\\>)(\\w*)} $string \-> restOfWord
+.CE
+Note that the whole matched substring has been placed in the variable
+\fB\->\fR which is a name chosen to look nice given that we are not
+actually interested in its contents.
+.PP
+Find the index of the word \fBbadger\fR (in any case) within a string
+and store that in the variable \fBlocation\fR:
+.CS
+\fBregexp\fR \-indices {(?i)\\<badger\\>} $string location
+.CE
+.PP
+Count the number of octal digits in a string:
+.CS
+\fBregexp\fR \-all {[0\-7]} $string
+.CE
+.PP
+List all words (consisting of all sequences of non-whitespace
+characters) in a string:
+.CS
+\fBregexp\fR \-all \-inline {\\S+} $string
+.CE
 
 .SH "SEE ALSO"
 re_syntax(n), regsub(n)
diff --git a/doc/registry.n b/doc/registry.n
index e6a4902..549a2e1 100644
--- a/doc/registry.n
+++ b/doc/registry.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: registry.n,v 1.8 2002/10/19 01:48:46 hobbs Exp $
+'\" RCS: @(#) $Id: registry.n,v 1.8.2.1 2004/10/27 14:23:58 dkf Exp $
 '\" 
 .so man.macros
 .TH registry n 1.1 registry "Tcl Bundled Packages"
@@ -60,7 +60,7 @@ keys like Environment.  The timeout specifies the amount of time, in
 milliseconds, to wait for applications to respond to the broadcast message.
 It defaults to 3000.  The following example demonstrates how to add a path
 to the global Environment and notify applications of the change without
-reguiring a logoff/logon step (assumes admin privileges):
+requiring a logoff/logon step (assumes admin privileges):
 .CS
 set regPath {HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment}
 set curPath [registry get $regPath "Path"]
@@ -179,9 +179,24 @@ In addition to the symbolically named types listed above, unknown
 types are identified using a 32-bit integer that corresponds to the
 type code returned by the system interfaces.  In this case, the data
 is represented exactly in Tcl, including any embedded nulls.
-
 .SH "PORTABILITY ISSUES"
 The registry command is only available on Windows.
+.SH EXAMPLE
+Print out how double-clicking on a Tcl script file will invoke a Tcl
+interpreter:
+.CS
+package require registry
+set ext .tcl
+
+# Read the type name
+set type [\fBregistry get\fR HKEY_CLASSES_ROOT\e\e$ext {}]
+# Work out where to look for the command
+set path HKEY_CLASSES_ROOT\e\e$type\e\eShell\e\eOpen\e\ecommand
+# Read the command!
+set command [\fBregistry get\fR $path {}]
+
+puts "$ext opens with $command"
+.CE
 
 .SH KEYWORDS
 registry
diff --git a/doc/regsub.n b/doc/regsub.n
index d0c6e01..cccb2e4 100644
--- a/doc/regsub.n
+++ b/doc/regsub.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: regsub.n,v 1.9 2003/02/20 15:33:02 dkf Exp $
+'\" RCS: @(#) $Id: regsub.n,v 1.9.2.1 2004/10/27 14:23:58 dkf Exp $
 '\" 
 .so man.macros
 .TH regsub n 8.3 Tcl "Tcl Built-In Commands"
@@ -114,9 +114,35 @@ string after replacement is returned.
 .VE 8.4
 See the manual entry for \fBregexp\fR for details on the interpretation
 of regular expressions.
+.SH EXAMPLES
+Replace (in the string in variable \fIstring\fR) every instance of
+\fBfoo\fR which is a word by itself with \fBbar\fR:
+.CS
+\fBregsub\fR -all {\e<foo\e>} $string bar string
+.CE
+.PP
+Insert double-quotes around the first instance of the word
+\fBinteresting\fR, however it is capitalised.
+.CS
+\fBregsub\fR -nocase {\e<interesting\e>} $string {"&"} string
+.CE
+.PP
+Convert all non-ASCII and Tcl-significant characters into \eu escape
+sequences by using \fBregsub\fR and \fBsubst\fR in combination:
+.CS
+# This RE is just a character class for everything "bad"
+set RE {[][{}\e$\es\eu0100-\euffff]}
+
+# We will substitute with a fragment of Tcl script in brackets
+set substitution {[format \e\e\e\eu%04x [scan "\e\e&" %c]]}
+
+# Now we apply the substitution to get a subst-string that
+# will perform the computational parts of the conversion.
+set quoted [subst [\fBregsub\fR -all $RE $string $substitution]]
+.CE
 
 .SH "SEE ALSO"
-regexp(n), re_syntax(n)
+regexp(n), re_syntax(n), subst(n)
 
 .SH KEYWORDS
 match, pattern, regular expression, substitute
diff --git a/doc/rename.n b/doc/rename.n
index 2630ad4..c1cce2e 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.3.18.1 2004/10/27 14:23:58 dkf Exp $
 '\" 
 .so man.macros
 .TH rename n "" Tcl "Tcl Built-In Commands"
@@ -27,6 +27,19 @@ 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
+\fBrename\fR ::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/return.n b/doc/return.n
index 2ea381d..685e0be 100644
--- a/doc/return.n
+++ b/doc/return.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: return.n,v 1.3 2000/09/07 14:27:51 poenitz Exp $
+'\" RCS: @(#) $Id: return.n,v 1.3.18.1 2004/10/27 14:23:58 dkf Exp $
 '\" 
 .so man.macros
 .TH return n 7.0 Tcl "Tcl Built-In Commands"
@@ -23,43 +23,45 @@ Return immediately from the current procedure
 (or top-level command or \fBsource\fR command),
 with \fIstring\fR as the return value.  If \fIstring\fR is not specified then
 an empty string will be returned as result.
-
-.SH "EXCEPTIONAL RETURNS"
+.SH "EXCEPTIONAL RETURN CODES"
 .PP
+In addition to the result of a procedure, the return
+code of a procedure may also be set by \fBreturn\fR
+through use of the \fB-code\fR option.
 In the usual case where the \fB\-code\fR option isn't
-specified the procedure will return normally (its completion
-code will be TCL_OK).
+specified the procedure will return normally.
 However, the \fB\-code\fR option may be used to generate an
 exceptional return from the procedure.
 \fICode\fR may have any of the following values:
-.TP 10
-\fBok\fR
-Normal return:  same as if the option is omitted.
-.TP 10
-\fBerror\fR
-Error return: same as if the \fBerror\fR command were used to
-terminate the procedure, except for handling of \fBerrorInfo\fR
-and \fBerrorCode\fR variables (see below).
-.TP 10
-\fBreturn\fR
-The current procedure will return with a completion code of
-TCL_RETURN, so that the procedure that invoked it will return
-also.
-.TP 10
-\fBbreak\fR
-The current procedure will return with a completion code of
-TCL_BREAK, which will terminate the innermost nested loop in
-the code that invoked the current procedure.
-.TP 10
-\fBcontinue\fR
-The current procedure will return with a completion code of
-TCL_CONTINUE, which will terminate the current iteration of
-the innermost nested loop in the code that invoked the current
-procedure.
-.TP 10
+.TP 13
+\fBok (or 0)\fR
+Normal return:  same as if the option is omitted.  The return code
+of the procedure is 0 (\fBTCL_OK\fR).
+.TP 13
+\fBerror (1)\fR
+Error return: the return code of the procedure is 1 (\fBTCL_ERROR\fR).
+The procedure command behaves in its calling context as if it
+were the command \fBerror \fIresult\fR.  See below for additional
+options.
+.TP 13
+\fBreturn (2)\fR
+The return code of the procedure is 2 (\fBTCL_RETURN\fR).  The
+procedure command behaves in its calling context as if it
+were the command \fBreturn\fR (with no arguments).
+.TP 13
+\fBbreak (3)\fR
+The return code of the procedure is 3 (\fBTCL_BREAK\fR).  The
+procedure command behaves in its calling context as if it
+were the command \fBbreak\fR.
+.TP 13
+\fBcontinue (4)\fR
+The return code of the procedure is 4 (\fBTCL_CONTINUE\fR).  The
+procedure command behaves in its calling context as if it
+were the command \fBcontinue\fR.
+.TP 13
 \fIvalue\fR
 \fIValue\fR must be an integer;  it will be returned as the
-completion code for the current procedure.
+return code for the current procedure.
 .LP
 The \fB\-code\fR option is rarely used.
 It is provided so that procedures that implement
@@ -84,9 +86,59 @@ If the \fB\-errorcode\fR option is specified then \fIcode\fR provides
 a value for the \fBerrorCode\fR variable.
 If the option is not specified then \fBerrorCode\fR will
 default to \fBNONE\fR.
+.SH EXAMPLES
+First, a simple example of using \fBreturn\fR to return from a
+procedure, interrupting the procedure body.
+.CS
+proc printOneLine {} {
+   puts "line 1"    ;# This line will be printed.
+   \fBreturn\fR		
+   puts "line 2"    ;# This line will not be printed.
+}
+.CE
+.PP
+Next, an example of using \fBreturn\fR to set the value
+returned by the procedure.
+.CS
+proc returnX {} {\fBreturn\fR X}
+puts [returnX]    ;# prints "X"
+.CE
+.PP
+Next, a more complete example, using \fBreturn -code error\fR
+to report invalid arguments.
+.CS
+proc factorial {n} {
+   if {![string is integer $n] || ($n < 0)} {
+      \fBreturn\fR -code error \\
+            "expected non-negative integer,\\
+             but got \\"$n\\""
+   }
+   if {$n < 2} {
+      \fBreturn\fR 1
+   }
+   set m [expr {$n - 1}]
+   set code [catch {factorial $m} factor]
+   if {$code != 0} {
+      \fBreturn\fR -code $code $factor
+   }
+   set product [expr {$n * $factor}]
+   if {$product < 0} {
+      \fBreturn\fR -code error \\
+            "overflow computing factorial of $n"
+   }
+   \fBreturn\fR $product
+}
+.CE
+.PP
+Next, a procedure replacement for \fBbreak\fR.
+.CS
+proc myBreak {} {
+   \fBreturn\fR -code break
+}
+.CE
 
 .SH "SEE ALSO"
-break(n), continue(n), error(n), proc(n)
+break(n), catch(n), continue(n), error(n), proc(n), source(n), tclvars(n)
 
 .SH KEYWORDS
-break, continue, error, procedure, return
+break, catch, continue, error, procedure, return
diff --git a/doc/safe.n b/doc/safe.n
index 38bc360..39f54ae 100644
--- a/doc/safe.n
+++ b/doc/safe.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: safe.n,v 1.4 2002/07/01 18:24:39 jenglish Exp $
+'\" RCS: @(#) $Id: safe.n,v 1.4.2.1 2004/10/27 14:23:58 dkf Exp $
 '\" 
 .so man.macros
 .TH "Safe Tcl" n 8.0 Tcl "Tcl Built-In Commands"
@@ -209,7 +209,7 @@ thus specifies the safe interpreter will be allowed
 to load packages into its own sub-interpreters.
 .TP 
 \fB\-deleteHook\fR \fIscript\fR
-When this option is given an non empty \fIscript\fR, it will be
+When this option is given a non-empty \fIscript\fR, it will be
 evaluated in the master with the name of
 the safe interpreter as an additional argument
 just before actually deleting the safe interpreter.
@@ -288,7 +288,7 @@ executing.
 The only valid file names arguments
 for the \fBsource\fR and \fBload\fR aliases provided to the slave
 are path in the form of 
-\fB[file join \fR\fItoken filename\fR\fB]\fR (ie, when using the
+\fB[file join \fR\fItoken filename\fR\fB]\fR (i.e. when using the
 native file path formats: \fItoken\fR\fB/\fR\fIfilename\fR
 on Unix, \fItoken\fR\fB\\\fIfilename\fR on Windows, 
 and \fItoken\fR\fB:\fR\fIfilename\fR on the Mac),
@@ -338,7 +338,7 @@ explicitly specifying your directory list with the \fB\-accessPath\fR flag
 instead of relying on this default mechanism.
 .PP
 When the \fIaccessPath\fR is changed after the first creation or
-initialization (ie through \fBinterpConfigure -accessPath \fR\fIlist\fR),
+initialization (i.e. through \fBinterpConfigure -accessPath \fR\fIlist\fR),
 an \fBauto_reset\fR is automatically evaluated in the safe interpreter
 to synchronize its \fBauto_index\fR with the new token list.
 
diff --git a/doc/scan.n b/doc/scan.n
index 81ff539..3e32f4a 100644
--- a/doc/scan.n
+++ b/doc/scan.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: scan.n,v 1.9 2002/07/01 18:24:39 jenglish Exp $
+'\" RCS: @(#) $Id: scan.n,v 1.9.2.1 2004/10/27 14:23:58 dkf Exp $
 '\" 
 .so man.macros
 .TH scan n 8.4 Tcl "Tcl Built-In Commands"
@@ -33,7 +33,6 @@ inline manner, returning the data that would otherwise be stored in the
 variables as a list.  In the inline case, an empty string is returned when
 the end of the input string is reached before any conversions have been
 performed.
-
 .SH "DETAILS ON SCANNING"
 .PP
 \fBScan\fR operates by scanning \fIstring\fR and \fIformat\fR together.
@@ -188,7 +187,6 @@ white-space character is encountered or when the maximum field
 width has been reached, whichever comes first.
 If a \fB*\fR is present in the conversion specifier 
 then no variable is assigned and the next scan argument is not consumed.
-
 .SH "DIFFERENCES FROM ANSI SSCANF"
 .PP
 The behavior of the \fBscan\fR command is the same as the behavior of
@@ -209,6 +207,55 @@ modifiers are ignored when converting real values (i.e. type
 .IP [4]
 If the end of the input string is reached before any conversions have been
 performed and no variables are given, an empty string is returned.
+.SH EXAMPLES
+Parse a simple color specification of the form \fI#RRGGBB\fR using
+hexadecimal conversions with field sizes:
+.CS
+set string "#08D03F"
+\fBscan\fR $string "#%2x%2x%2x" r g b
+.CE
+.PP
+Parse a \fIHH:MM\fR time string, noting that this avoids problems with
+octal numbers by forcing interpretation as decimals (if we did not
+care, we would use the \fB%i\fR conversion instead):
+.CS
+set string "08:08"   ;# *Not* octal!
+if {[\fBscan\fR $string "%d:%d" hours minutes] != 2} {
+   error "not a valid time string"
+}
+# We have to understand numeric ranges ourselves...
+if {$minutes < 0 || $minutes > 59} {
+   error "invalid number of minutes"
+}
+.CE
+.PP
+Break a string up into sequences of non-whitespace characters (note
+the use of the \fB%n\fR conversion so that we get skipping over
+leading whitespace correct):
+.CS
+set string " a string {with braced words} + leading space "
+set words {}
+while {[\fBscan\fR $string %s%n word length] == 2} {
+   lappend words $word
+   set string [string range $string $length end]
+}
+.CE
+.PP
+Parse a simple coordinate string, checking that it is complete by
+looking for the terminating character explicitly:
+.CS
+set string "(5.2,-4e-2)"
+# Note that the spaces before the literal parts of
+# the scan pattern are significant, and that ")" is
+# the Unicode character \\u0029
+if {
+   [\fBscan\fR $string " (%f ,%f %c" x y last] != 3
+   || $last != 0x0029
+} then {
+   error "invalid coordinate string"
+}
+puts "X=$x, Y=$y"
+.CE
 
 .SH "SEE ALSO"
 format(n), sscanf(3)
diff --git a/doc/seek.n b/doc/seek.n
index 5f3118a..efd6ef7 100644
--- a/doc/seek.n
+++ b/doc/seek.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: seek.n,v 1.5 2001/09/14 19:20:40 andreas_kupries Exp $
+'\" RCS: @(#) $Id: seek.n,v 1.5.8.1 2004/10/27 14:23:58 dkf Exp $
 '\" 
 .so man.macros
 .TH seek n 8.1 Tcl "Tcl Built-In Commands"
@@ -62,6 +62,27 @@ Note that \fIoffset\fR values are byte offsets, not character
 offsets.  Both \fBseek\fR and \fBtell\fR operate in terms of bytes,
 not characters, unlike \fBread\fR.
 .VE 8.1
+.SH EXAMPLES
+Read a file twice:
+.CS
+set f [open file.txt]
+set data1 [read $f]
+\fBseek\fR $f 0
+set data2 [read $f]
+close $f
+# $data1 == $data2 if the file wasn't updated
+.CE
+.PP
+Read the last 10 bytes from a file:
+.CS
+set f [open file.data]
+# This is guaranteed to work with binary data but
+# may fail with other encodings...
+fconfigure $f -translation binary
+\fBseek\fR $f -10 end
+set data [read $f 10]
+close $f
+.CE
 
 .SH "SEE ALSO"
 file(n), open(n), close(n), gets(n), tell(n), Tcl_StandardChannels(3)
diff --git a/doc/set.n b/doc/set.n
index 1ab7ac5..25a000a 100644
--- a/doc/set.n
+++ b/doc/set.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: set.n,v 1.3.18.1 2004/05/24 19:24:37 msofer Exp $
+'\" RCS: @(#) $Id: set.n,v 1.3.18.2 2004/10/27 14:23:58 dkf Exp $
 '\" 
 .so man.macros
 .TH set n "" Tcl "Tcl Built-In Commands"
@@ -41,6 +41,32 @@ If a procedure is active and \fIvarName\fR is unqualified, then
 \fIvarName\fR refers to a parameter or local variable of the procedure,
 unless \fIvarName\fR was declared to resolve differently through one of the 
 \fBglobal\fR, \fBvariable\fR or \fBupvar\fR commands.
+.SH EXAMPLES
+Store a random number in the variable \fIr\fR:
+.CS
+\fBset\fR r [expr rand()]
+.CE
+.PP
+Store a short message in an array element:
+.CS
+\fBset\fR anAry(msg) "Hello, World!"
+.CE
+.PP
+Store a short message in an array element specified by a variable:
+.CS
+\fBset\fR elemName "msg"
+\fBset\fR anAry($elemName) "Hello, World!"
+.CE
+.PP
+Copy a value into the variable \fIout\fR from a variable whose name is
+stored in the \fIvbl\fR (note that it is often easier to use arrays in
+practice instead of doing double-dereferencing):
+.CS
+\fBset\fR in0 "small random"
+\fBset\fR in1 "large random"
+\fBset\fR vbl in[expr {rand() >= 0.5}]
+\fBset\fR out [\fBset\fR $vbl]
+.CE
 
 .SH "SEE ALSO"
 expr(n), global(n), namespace(n), proc(n), trace(n), unset(n), upvar(n), variable(n)
diff --git a/doc/socket.n b/doc/socket.n
index ba0feb5..21dd33c 100644
--- a/doc/socket.n
+++ b/doc/socket.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: socket.n,v 1.7.2.2 2003/05/15 18:41:06 hobbs Exp $
+'\" RCS: @(#) $Id: socket.n,v 1.7.2.3 2004/10/27 14:23:58 dkf Exp $
 .so man.macros
 .TH socket n 8.0 Tcl "Tcl Built-In Commands"
 .BS
@@ -36,7 +36,6 @@ will need to use \fBfconfigure\fR to alter this to something else,
 such as \fIutf\-8\fR (ideal for communicating with other Tcl
 processes) or \fIiso8859\-1\fR (useful for many network protocols,
 especially the older ones).
-
 .SH "CLIENT SOCKETS"
 .PP
 If the \fB\-server\fR option is not specified, then the client side of a
@@ -47,7 +46,7 @@ to connect to;  there must be a server accepting connections on
 this port.  \fIPort\fR is an integer port number
 (or service name, where supported and understood by the host operating
 system) and \fIhost\fR
-is either a domain-style name such as \fBwww.sunlabs.com\fR or
+is either a domain-style name such as \fBwww.tcl.tk\fR or
 a numerical IP address such as \fB127.0.0.1\fR.
 Use \fIlocalhost\fR to refer to the host on which the command is invoked.
 .PP
@@ -78,13 +77,14 @@ operation will wait until the connection is completed or fails. If the
 socket is in nonblocking mode and a \fBgets\fR or \fBflush\fR is done on
 the socket before the connection attempt succeeds or fails, the operation
 returns immediately and \fBfblocked\fR on the socket returns 1.
-
 .SH "SERVER SOCKETS"
 .PP
 If the \fB\-server\fR option is specified then the new socket
 will be a server for the port given by \fIport\fR (either an integer
 or a service name, where supported and understood by the host
-operating system).
+operating system; if \fIport\fR is zero, the operating system will
+allocate a free port to the server socket which may be discovered by
+using \fBfconfigure\fR to read the \fB\-sockname\fR option).
 Tcl will automatically accept connections to the given port.
 For each connection Tcl will create a new channel that may be used to
 communicate with the client.  Tcl then invokes \fIcommand\fR
@@ -116,10 +116,9 @@ will be accepted.
 .PP
 If \fIport\fR is specified as zero, the operating system will allocate
 an unused port for use as a server socket.  The port number actually
-allocated my be retrieved from the created server socket using the
+allocated may be retrieved from the created server socket using the
 \fBfconfigure\fR command to retrieve the \fB\-sockname\fR option as
 described below.
-
 .SH "CONFIGURATION OPTIONS"
 The \fBfconfigure\fR command can be used to query several readonly
 configuration options for socket channels:
@@ -143,6 +142,27 @@ address, the host name and the port to which the peer socket is connected
 or bound. If the host name cannot be computed, the second element of the
 list is identical to the address, its first element.
 .PP
+.SH "EXAMPLES"
+Here is a very simple time server:
+.CS
+proc Server {channel clientaddr clientport} {
+   puts "Connection from $clientaddr registered"
+   puts $channel [clock format [clock seconds]]
+   close $channel
+}
+
+\fBsocket\fR -server Server 9900
+vwait forever
+.CE
+.PP
+And here is the corresponding client to talk to the server:
+.CS
+set server localhost
+set sockChan [\fBsocket\fR $server 9900]
+gets $sockChan line
+close $sockChan
+puts "The time on $server is $line"
+.CE
 
 .SH "SEE ALSO"
 fconfigure(n), flush(n), open(n), read(n)
diff --git a/doc/source.n b/doc/source.n
index 7276a9c..a864733 100644
--- a/doc/source.n
+++ b/doc/source.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: source.n,v 1.5 2000/09/07 14:27:51 poenitz Exp $
+'\" RCS: @(#) $Id: source.n,v 1.5.18.1 2004/10/27 14:23:58 dkf Exp $
 '\" 
 .so man.macros
 .TH source n "" Tcl "Tcl Built-In Commands"
@@ -50,9 +50,22 @@ what \fBTEXT\fR resource to source by either name or id.  By default Tcl
 searches all open resource files, which include the current
 application and any loaded C extensions.  Alternatively, you may
 specify the \fIfileName\fR where the \fBTEXT\fR resource can be found.
+.SH EXAMPLE
+Run the script in the file \fBfoo.tcl\fR and then the script in the
+file \fBbar.tcl\fR:
+.CS
+\fBsource\fR foo.tcl
+\fBsource\fR bar.tcl
+.CE
+Alternatively:
+.CS
+foreach scriptFile {foo.tcl bar.tcl} {
+   \fBsource\fR $scriptFile
+}
+.CE
 
 .SH "SEE ALSO"
-file(n), cd(n)
+file(n), cd(n), info(n)
 
 .SH KEYWORDS
 file, script
diff --git a/doc/split.n b/doc/split.n
index b42c978..5caade5 100644
--- a/doc/split.n
+++ b/doc/split.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: split.n,v 1.3 2000/09/07 14:27:51 poenitz Exp $
+'\" RCS: @(#) $Id: split.n,v 1.3.18.1 2004/10/27 14:23:58 dkf Exp $
 '\" 
 .so man.macros
 .TH split n "" Tcl "Tcl Built-In Commands"
@@ -30,15 +30,56 @@ character of \fIstring\fR is in \fIsplitChars\fR.
 If \fIsplitChars\fR is an empty string then each character of
 \fIstring\fR becomes a separate element of the result list.
 \fISplitChars\fR defaults to the standard white-space characters.
-For example,
+.SH EXAMPLES
+Divide up a USENET group name into its hierarchical components:
 .CS
-\fBsplit "comp.unix.misc" .\fR
+\fBsplit\fR "comp.lang.tcl.announce" .
+     \fI=> comp lang tcl announce\fR
 .CE
-returns \fB"comp unix misc"\fR and
+.PP
+See how the \fBsplit\fR command splits on \fIevery\fR character in
+\fIsplitChars\fR, which can result in information loss if you are not
+careful:
+.CS
+\fBsplit\fR "alpha beta gamma" "temp"
+     \fI=> al {ha b} {} {a ga} {} a\fR
+.CE
+.PP
+Extract the list words from a string that is not a well-formed list:
+.CS
+\fBsplit\fR "Example with {unbalanced brace character"
+     \fI=> Example with \\{unbalanced brace character\fR
+.CE
+.PP
+Split a string into its constituent characters
 .CS
-\fBsplit "Hello world" {}\fR
+\fBsplit\fR "Hello world" {}
+     \fI=> H e l l o { } w o r l d\fR
+.CE
+.SH "PARSING RECORD-ORIENTED FILES"
+Parse a Unix /etc/passwd file, which consists of one entry per line,
+with each line consisting of a colon-separated list of fields:
+.CS
+## Read the file
+set fid [open /etc/passwd]
+set content [read $fid]
+close $fid
+
+## Split into records on newlines
+set records [\fBsplit\fR $content "\\n"]
+
+## Iterate over the records
+foreach rec $records {
+
+   ## Split into fields on colons
+   set fields [\fBsplit\fR $rec ":"]
+
+   ## Assign fields to variables and print some out...
+   lassign $fields \\
+         userName password uid grp longName homeDir shell
+   puts "$longName uses [file tail $shell] for a login shell"
+}
 .CE
-returns \fB"H e l l o { } w o r l d"\fR.
 
 .SH "SEE ALSO"
 join(n), list(n), string(n)
diff --git a/doc/string.n b/doc/string.n
index 49ef611..92925a0 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.2 2004/10/27 09:35:38 dkf Exp $
+'\" RCS: @(#) $Id: string.n,v 1.17.2.3 2004/10/27 14:23:58 dkf Exp $
 '\" 
 .so man.macros
 .TH string n 8.1 Tcl "Tcl Built-In Commands"
@@ -315,11 +315,11 @@ single character other than these.
 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]
+set length [\fBstring length\fR $string]
 if {$length == 0} {
-    set isPrefix 0
+   set isPrefix 0
 } else {
-    set isPrefix [\fBstring\fR equal -length $string $string "foobar"]
+   set isPrefix [\fBstring equal\fR -length $string $string "foobar"]
 }
 .CE
 
diff --git a/doc/subst.n b/doc/subst.n
index 829b077..71b17f6 100644
--- a/doc/subst.n
+++ b/doc/subst.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: subst.n,v 1.5 2002/04/18 16:31:40 dgp Exp $
+'\" RCS: @(#) $Id: subst.n,v 1.5.2.1 2004/10/27 14:23:58 dkf Exp $
 '\" 
 .so man.macros
 .TH subst n 7.4 Tcl "Tcl Built-In Commands"
@@ -66,31 +66,31 @@ When it performs its substitutions, \fIsubst\fR does not give any
 special treatment to double quotes or curly braces (except within
 command substitutions) so the script
 .CS
-\fBset a 44
-subst {xyz {$a}}\fR
+set a 44
+\fBsubst\fR {xyz {$a}}
 .CE
 returns ``\fBxyz {44}\fR'', not ``\fBxyz {$a}\fR''
 .VS 8.4
 and the script
 .CS
-\fBset a "p\\} q \\{r"
-subst {xyz {$a}}\fR
+set a "p\\} q \\{r"
+\fBsubst\fR {xyz {$a}}
 .CE
 return ``\fBxyz {p} q {r}\fR'', not ``\fBxyz {p\\} q \\{r}\fR''.
 .PP
 When command substitution is performed, it includes any variable
 substitution necessary to evaluate the script.  
 .CS
-\fBset a 44
-subst -novariables {$a [format $a]}\fR
+set a 44
+\fBsubst\fR -novariables {$a [format $a]}
 .CE
 returns ``\fB$a 44\fR'', not ``\fB$a $a\fR''.  Similarly, when
 variable substitution is performed, it includes any command
 substitution necessary to retrieve the value of the variable.
 .CS
-\fBproc b {} {return c}
+proc b {} {return c}
 array set a {c c [b] tricky}
-subst -nocommands {[b] $a([b])}\fR
+\fBsubst\fR -nocommands {[b] $a([b])}
 .CE
 returns ``\fB[b] c\fR'', not ``\fB[b] tricky\fR''.
 .PP
@@ -99,21 +99,21 @@ prevent substitution of the rest of the command substitution and the
 rest of \fIstring\fR respectively, giving script authors more options
 when processing text using \fIsubst\fR.  For example, the script
 .CS
-\fBsubst {abc,[break],def}\fR
+\fBsubst\fR {abc,[break],def}
 .CE
 returns ``\fBabc,\fR'', not ``\fBabc,,def\fR'' and the script
 .CS
-\fBsubst {abc,[continue;expr 1+2],def}\fR
+\fBsubst\fR {abc,[continue;expr 1+2],def}
 .CE
 returns ``\fBabc,,def\fR'', not ``\fBabc,3,def\fR''.
 .PP
 Other exceptional return codes substitute the returned value
 .CS
-\fBsubst {abc,[return foo;expr 1+2],def}\fR
+\fBsubst\fR {abc,[return foo;expr 1+2],def}
 .CE
 returns ``\fBabc,foo,def\fR'', not ``\fBabc,3,def\fR'' and
 .CS
-\fBsubst {abc,[return -code 10 foo;expr 1+2],def}\fR
+\fBsubst\fR {abc,[return -code 10 foo;expr 1+2],def}
 .CE
 also returns ``\fBabc,foo,def\fR'', not ``\fBabc,3,def\fR''.
 .VE
diff --git a/doc/switch.n b/doc/switch.n
index a17dd93..6d9bdc1 100644
--- a/doc/switch.n
+++ b/doc/switch.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: switch.n,v 1.5 2000/09/07 14:27:51 poenitz Exp $
+'\" RCS: @(#) $Id: switch.n,v 1.5.18.1 2004/10/27 14:23:58 dkf Exp $
 '\" 
 .so man.macros
 .TH switch n 7.0 Tcl "Tcl Built-In Commands"
@@ -78,37 +78,43 @@ several patterns.
 Beware of how you place comments in \fBswitch\fR commands.  Comments
 should only be placed \fBinside\fR the execution body of one of the
 patterns, and not intermingled with the patterns.
-.PP
-Below are some examples of \fBswitch\fR commands:
+.SH "EXAMPLES"
+The \fBswitch\fR command can match against variables and not just
+literals, as shown here (the result is \fI2\fR):
 .CS
-\fBswitch\0abc\0a\0\-\0b\0{format 1}\0abc\0{format 2}\0default\0{format 3}\fR
+set foo "abc"
+\fBswitch\fR abc a \- b {expr 1} $foo {expr 2} default {expr 3}
 .CE
-will return \fB2\fR, 
+.PP
+Using glob matching and the fall-through body is an alternative to
+writing regular expressions with alternations, as can be seen here
+(this returns \fI1\fR):
 .CS
-\fBswitch\0\-regexp\0aaab {
-	^a.*b$\0\-
-	b\0{format 1}
-	a*\0{format 2}
-	default\0{format 3}
-}\fR
+\fBswitch\fR \-glob aaab {
+   a*b     \-
+   b       {expr 1}
+   a*      {expr 2}
+   default {expr 3}
+}
 .CE
-will return \fB1\fR, and
+.PP
+Whenever nothing matches, the \fBdefault\fR clause (which must be
+last) is taken.  This example has a result of \fI3\fR:
 .CS
-\fBswitch\0xyz {
-	a
-		\-
-	b
-		{
-		# Correct Comment Placement
-		format 1
-	}
-	a*
-		{format 2}
-	default
-		{format 3}
-}\fR
+\fBswitch\fR xyz {
+   a  \-
+   b {
+      # Correct Comment Placement
+      expr 1
+   }
+   c {
+      expr 2
+   }
+   default {
+      expr 3
+   }
+}
 .CE
-will return \fB3\fR.
 
 .SH "SEE ALSO"
 for(n), if(n), regexp(n)
-- 
cgit v0.12