From 3ec9fd99b36055e6d272e64c1de04a93fdc9416b Mon Sep 17 00:00:00 2001
From: dkf <donal.k.fellows@manchester.ac.uk>
Date: Wed, 27 Oct 2004 12:52:31 +0000
Subject: More doc fix backporting

---
 ChangeLog        |   2 +-
 doc/fblocked.n   |  38 ++++++++++++++++-
 doc/fconfigure.n |  63 +++++++++++++++++++++++++++-
 doc/file.n       |  49 +++++++++++++++++++---
 doc/fileevent.n  |  15 +++----
 doc/filename.n   |  11 ++++-
 doc/flush.n      |  10 ++++-
 doc/for.n        |  29 +++++++++++--
 doc/foreach.n    |   8 ++--
 doc/format.n     |  55 +++++++++++++++++++++---
 doc/gets.n       |  14 ++++++-
 doc/glob.n       |  34 ++++++++++++++-
 doc/global.n     |  37 ++++++++++++----
 doc/history.n    |   4 +-
 doc/http.n       | 104 +++++++++++++++++++++++----------------------
 doc/if.n         |  37 +++++++++++++++-
 doc/incr.n       |  25 ++++++++++-
 doc/info.n       |  32 ++++++++++++--
 doc/interp.n     | 126 +++++++++++++++++++++++++++++++++++--------------------
 doc/join.n       |  18 +++++++-
 doc/lappend.n    |  12 +++++-
 doc/lindex.n     |  22 +++++-----
 doc/linsert.n    |  15 +++++--
 doc/list.n       |  17 ++++----
 doc/llength.n    |  28 ++++++++++++-
 doc/load.n       |  47 ++++++++++++++++++---
 doc/lrange.n     |  31 +++++++++++++-
 doc/lreplace.n   |  22 +++++++++-
 doc/lsearch.n    |  19 +++++----
 doc/lsort.n      |  35 ++++++----------
 30 files changed, 743 insertions(+), 216 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 9020650..4570acf 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,6 +1,6 @@
 2004-10-26  Donal K. Fellows  <donal.k.fellows@man.ac.uk>
 
-	* doc/[a-e]*.n: First stage of backporting documentation updates.
+	* doc/[a-l]*.n: First stage of backporting documentation updates.
 
 2004-10-26  Don Porter  <dgp@users.sourceforge.net>
 
diff --git a/doc/fblocked.n b/doc/fblocked.n
index 7f8fe54..2cb7d85 100644
--- a/doc/fblocked.n
+++ b/doc/fblocked.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: fblocked.n,v 1.4 2001/09/14 19:20:40 andreas_kupries Exp $
+'\" RCS: @(#) $Id: fblocked.n,v 1.4.8.1 2004/10/27 12:52:39 dkf Exp $
 .so man.macros
 .TH fblocked n 7.5 Tcl "Tcl Built-In Commands"
 .BS
@@ -31,9 +31,43 @@ Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR),
 the return value from an invocation of \fBopen\fR or \fBsocket\fR, or
 the result of a channel creation command provided by a Tcl extension.
 .VE
+.SH EXAMPLE
+The \fBfblocked\fR command is particularly useful when writing network
+servers, as it allows you to write your code in a line-by-line style
+without preventing the servicing of other connections.  This can be
+seen in this simple echo-service:
+.PP
+.CS
+# This is called whenever a new client connects to the server
+proc connect {chan host port} {
+    set clientName [format <%s:%d> $host $port]
+    puts "connection from $clientName"
+    fconfigure $chan -blocking 0 -buffering line
+    fileevent $chan readable [list echoLine $chan $clientName]
+}
+
+# This is called whenever either at least one byte of input
+# data is available, or the channel was closed by the client.
+proc echoLine {chan clientName} {
+    gets $chan line
+    if {[eof $chan]} {
+        puts "finishing connection from $clientName"
+        close $chan
+    } elseif {![\fBfblocked\fR $chan]} {
+        # Didn't block waiting for end-of-line
+        puts "$clientName - $line"
+        puts $chan $line
+    }
+}
+
+# Create the server socket and enter the event-loop to wait
+# for incoming connections...
+socket -server connect 12345
+vwait forever
+.CE
 
 .SH "SEE ALSO"
-gets(n), open(n), read(n), Tcl_StandardChannels(3)
+gets(n), open(n), read(n), socket(n), Tcl_StandardChannels(3)
 
 .SH KEYWORDS
 blocking, nonblocking
diff --git a/doc/fconfigure.n b/doc/fconfigure.n
index d903b55..16b81ad 100644
--- a/doc/fconfigure.n
+++ b/doc/fconfigure.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: fconfigure.n,v 1.7.2.1 2003/04/18 00:32:34 dkf Exp $
+'\" RCS: @(#) $Id: fconfigure.n,v 1.7.2.2 2004/10/27 12:52:40 dkf Exp $
 '\"
 .so man.macros
 .TH fconfigure n 8.3 Tcl "Tcl Built-In Commands"
@@ -192,7 +192,6 @@ during either input or output.  This mode is typically used on UNIX
 platforms.
 .RE
 .PP
-
 .SH "STANDARD CHANNELS"
 .PP
 The Tcl standard channels (\fBstdin\fR, \fBstdout\fR, and \fBstderr\fR)
@@ -202,6 +201,66 @@ will also support any special option according to their current type.
 If, for example, a Tcl application is started by the \fBinet\fR
 super-server common on Unix system its Tcl standard channels will be
 sockets and thus support the socket options.
+.SH EXAMPLES
+Instruct Tcl to always send output to \fBstdout\fR immediately,
+whether or not it is to a terminal:
+.CS
+\fBfconfigure\fR stdout -buffering none
+.CE
+.PP
+Open a socket and read lines from it without ever blocking the
+processing of other events:
+.CS
+set s [socket some.where.com 12345]
+\fBfconfigure\fR $s -blocking 0
+fileevent $s readable "readMe $s"
+proc readMe chan {
+   if {[gets $chan line] < 0} {
+      if {[eof $chan]} {
+         close $chan
+         return
+      }
+      # Could not read a complete line this time; Tcl's
+      # internal buffering will hold the partial line for us
+      # until some more data is available over the socket.
+   } else {
+      puts stdout $line
+   }
+}
+.CE
+.PP
+Read a PPM-format image from a file:
+.CS
+# Open the file and put it into Unix ASCII mode
+set f [open teapot.ppm]
+\fBfconfigure\fR $f \-encoding ascii \-translation lf
+
+# Get the header
+if {[gets $f] ne "P6"} {
+   error "not a raw\-bits PPM"
+}
+
+# Read lines until we have got non-comment lines
+# that supply us with three decimal values.
+set words {}
+while {[llength $words] < 3} {
+   gets $f line
+   if {[string match "#*" $line]} continue
+   lappend words [eval concat [scan $line %d%d%d]]
+}
+
+# Those words supply the size of the image and its
+# overall depth per channel. Assign to variables.
+foreach {xSize ySize depth} $words {break}
+
+# Now switch to binary mode to pull in the data,
+# one byte per channel (red,green,blue) per pixel.
+\fBfconfigure\fR $f \-translation binary
+set numDataBytes [expr {3 * $xSize * $ySize}]
+set data [read $f $numDataBytes]
+
+close $f
+.CE
 
 .SH "SEE ALSO"
 close(n), flush(n), gets(n), open(n), puts(n), read(n), socket(n),
diff --git a/doc/file.n b/doc/file.n
index 7fc2b07..d97f2b0 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 2003/02/28 12:11:49 vincentdarley Exp $
+'\" RCS: @(#) $Id: file.n,v 1.23.2.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH file n 8.3 Tcl "Tcl Built-In Commands"
@@ -101,7 +101,7 @@ overwritten unless the \fB\-force\fR option is specified.  When copying
 within a single filesystem, \fIfile copy\fR will copy soft links (i.e.
 the links themselves are copied, not the things they point to).  Trying
 to overwrite a non-empty directory, overwrite a directory with a file,
-or a file with a directory will all result in errors even if
+or overwrite a file with a directory will all result in errors even if
 \fI\-force\fR was specified.  Arguments are processed in the order
 specified, halting at the first error, if any.  A \fB\-\|\-\fR marks
 the end of switches; the argument following the \fB\-\|\-\fR will be
@@ -200,8 +200,8 @@ If only one argument is given, that argument is assumed to be
 seems to be the case with hard links, which look just like ordinary
 files), then an error is returned.
 .
-If 2 arguments are given, then these are assumed to be \fIlinkName\fR and
-\fItarget\fR. If \fIlinkName\fR already exists, or if \fItarget\fR
+If 2 arguments are given, then these are assumed to be \fIlinkName\fR
+and \fItarget\fR. If \fIlinkName\fR already exists, or if \fItarget\fR
 doesn't exist, an error will be returned.  Otherwise, Tcl creates a new
 link called \fIlinkName\fR which points to the existing filesystem object
 at \fItarget\fR, where the type of the link is platform-specific (on Unix
@@ -258,14 +258,14 @@ under Windows or AppleScript on the Macintosh.
 \fBfile normalize \fIname\fR
 .
 .RS
-Returns a unique normalised path representation for the file-system
+Returns a unique normalized path representation for the file-system
 object (file, directory, link, etc), whose string value can be used as a
 unique identifier for it.  A normalized path is an absolute path which has
 all '../', './' removed.  Also it is one which is in the ``standard''
 format for the native platform.  On MacOS, Unix, this means the segments
 leading up to the path must be free of symbolic links/aliases (but the
 very last path component may be a symbolic link), and on Windows it also
-means means we want the long form with that form's case-dependence (which
+means we want the long form with that form's case-dependence (which
 gives us a unique, case-dependent path).  The one exception concerning the
 last link in the path is necessary, because Tcl or the user may wish to
 operate on the actual symbolic link itself (for example 'file delete', 'file
@@ -418,6 +418,43 @@ Returns \fB1\fR if file \fIname\fR is writable by the current user,
 .
 These commands always operate using the real user and group identifiers,
 not the effective ones. 
+.SH EXAMPLES
+This procedure shows how to search for C files in a given directory
+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
+}
+.CE
+.PP
+Rename a file and leave a symbolic link pointing from the old location
+to the new place:
+.CS
+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]
+}
+\fBfile\fR rename $oldName $newName
+\fBfile\fR link -symbolic $oldName $newName
+.CE
 
 .SH "SEE ALSO"
 filename(n), open(n), close(n), eof(n), gets(n), tell(n), seek(n),
diff --git a/doc/fileevent.n b/doc/fileevent.n
index 8e82564..73f2104 100644
--- a/doc/fileevent.n
+++ b/doc/fileevent.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: fileevent.n,v 1.5 2001/09/27 05:50:56 andreas_kupries Exp $
+'\" RCS: @(#) $Id: fileevent.n,v 1.5.6.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH fileevent n 7.5 Tcl "Tcl Built-In Commands"
@@ -100,21 +100,18 @@ If an error occurs while executing the script then the
 In addition, the file event handler is deleted if it ever returns
 an error;  this is done in order to prevent infinite loops due to
 buggy handlers.
-
 .SH EXAMPLE
-.PP
+In this setup \fBGetData\fR will be called with the channel as an
+argument whenever $chan becomes readable.
 .CS
- proc GetData {chan} {
+proc GetData {chan} {
     if {![eof $chan]} {
         puts [gets $chan]
     }
- }
-
- fileevent $chan readable [list GetData $chan]
+}
 
+\fBfileevent\fR $chan readable [list GetData $chan]
 .CE
-In this setup \fBGetData\fR will be called with the channel as an
-argument whenever $chan becomes readable.
 
 .SH CREDITS
 .PP
diff --git a/doc/filename.n b/doc/filename.n
index c0e2a68..02b102f 100644
--- a/doc/filename.n
+++ b/doc/filename.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: filename.n,v 1.7 2001/09/04 18:06:34 vincentdarley Exp $
+'\" RCS: @(#) $Id: filename.n,v 1.7.12.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH filename n 7.5 Tcl "Tcl Built-In Commands"
@@ -208,7 +208,14 @@ more than 3 characters.
 On Windows platforms there are file and path length restrictions. 
 Complete paths or filenames longer than about 260 characters will lead
 to errors in most file operations.
-
+.PP
+Another Windows peculiarity is that any number of trailing dots '.'  in
+filenames are totally ignored, so, for example, attempts to create a
+file or directory with a name "foo." will result in the creation of a
+file/directory with name "foo".  This fact is reflected in the
+results of 'file normalize'.  Furthermore, a file name consisting only
+of dots '.........' or dots with trailing characters '.....abc' is
+illegal.
 .SH KEYWORDS
 current directory, absolute file name, relative file name,
 volume-relative file name, portability
diff --git a/doc/flush.n b/doc/flush.n
index 172555c..c94a9af 100644
--- a/doc/flush.n
+++ b/doc/flush.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: flush.n,v 1.4 2001/09/14 19:20:40 andreas_kupries Exp $
+'\" RCS: @(#) $Id: flush.n,v 1.4.8.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH flush n 7.5 Tcl "Tcl Built-In Commands"
@@ -34,6 +34,14 @@ buffered output has been flushed to the channel. If the channel is in
 nonblocking mode, the command may return before all buffered output has been
 flushed; the remainder will be flushed in the background as fast as the
 underlying file or device is able to absorb it.
+.SH EXAMPLE
+Prompt for the user to type some information in on the console:
+.CS
+puts -nonewline "Please type your name: "
+\fBflush\fR stdout
+gets stdin name
+puts "Hello there, $name!"
+.CE
 
 .SH "SEE ALSO"
 file(n), open(n), socket(n), Tcl_StandardChannels(3)
diff --git a/doc/for.n b/doc/for.n
index 5cf267c..08ed1ff 100644
--- a/doc/for.n
+++ b/doc/for.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: for.n,v 1.3 2000/09/07 14:27:48 poenitz Exp $
+'\" RCS: @(#) $Id: for.n,v 1.3.18.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH for n "" Tcl "Tcl Built-In Commands"
@@ -48,11 +48,32 @@ This is likely to result in an infinite loop.  If \fItest\fR is
 enclosed in braces, variable substitutions are delayed until the
 expression is evaluated (before
 each loop iteration), so changes in the variables will be visible.
-For an example, try the following script with and without the braces
-around \fB$x<10\fR:
+See below for an example:
+.SH EXAMPLES
+Print a line for each of the integers from 0 to 10:
 .CS
 for {set x 0} {$x<10} {incr x} {
-	puts "x is $x"
+   puts "x is $x"
+}
+.CE
+.PP
+Either loop infinitely or not at all because the expression being
+evaluated is actually the constant, or even generate an error!  The
+actual behaviour will depend on whether the variable \fIx\fR exists
+before the \fBfor\fR command is run and whether its value is a value
+that is less than or greater than/equal to ten, and this is because
+the expression will be substituted before the \fBfor\fR command is
+executed.
+.CS
+for {set x 0} $x<10 {incr x} {
+   puts "x is $x"
+}
+.CE
+.PP
+Print out the powers of two from 1 to 1024:
+.CS
+for {set x 1} {$x<=1024} {set x [expr {$x * 2}]} {
+   puts "x is $x"
 }
 .CE
 
diff --git a/doc/foreach.n b/doc/foreach.n
index 09faa2a..9308d05 100644
--- a/doc/foreach.n
+++ b/doc/foreach.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: foreach.n,v 1.3 2000/09/07 14:27:48 poenitz Exp $
+'\" RCS: @(#) $Id: foreach.n,v 1.3.18.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH foreach n "" Tcl "Tcl Built-In Commands"
@@ -56,7 +56,7 @@ The following loop uses i and j as loop variables to iterate over
 pairs of elements of a single list.
 .DS
 set x {}
-foreach {i j} {a b c d e f} {
+\fBforeach\fR {i j} {a b c d e f} {
     lappend x $j $i
 }
 # The value of x is "b a d c f e"
@@ -66,7 +66,7 @@ foreach {i j} {a b c d e f} {
 The next loop uses i and j to iterate over two lists in parallel.
 .DS
 set x {}
-foreach i {a b c} j {d e f g} {
+\fBforeach\fR i {a b c} j {d e f g} {
     lappend x $i $j
 }
 # The value of x is "a d b e c f {} g"
@@ -76,7 +76,7 @@ foreach i {a b c} j {d e f g} {
 The two forms are combined in the following example.
 .DS
 set x {}
-foreach i {a b c} {j k} {d e f g} {
+\fBforeach\fR i {a b c} {j k} {d e f g} {
     lappend x $i $j $k
 }
 # The value of x is "a d e b f g c {} {}"
diff --git a/doc/format.n b/doc/format.n
index b69a8f6..471774c 100644
--- a/doc/format.n
+++ b/doc/format.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: format.n,v 1.7 2002/02/19 10:26:24 dkf Exp $
+'\" RCS: @(#) $Id: format.n,v 1.7.2.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH format n 8.1 Tcl "Tcl Built-In Commands"
@@ -26,7 +26,6 @@ implementation).
 \fB%\fR conversion specifiers as in \fBsprintf\fR, and the additional
 arguments, if any, provide values to be substituted into the result.
 The return value from \fBformat\fR is the formatted string.
-
 .SH "DETAILS ON FORMATTING"
 .PP
 The command operates by scanning \fIformatString\fR from left to right. 
@@ -133,7 +132,7 @@ truncated to a 16-bit value before converting.
 This option is rarely useful.
 .VS 8.4
 If it is \fBl\fR it specifies that the numeric value should be (at
-least) a 64-bit value.  If neither \fBh\fR or \fBl\fR are present,
+least) a 64-bit value.  If neither \fBh\fR nor \fBl\fR are present,
 numeric values are interpreted as being values of the width of the
 native machine word, as described by \fBtcl_platform(wordSize)\fR.
 .VE
@@ -196,7 +195,6 @@ For the numerical conversions the argument being converted must
 be an integer or floating-point string; format converts the argument
 to binary and then converts it back to a string according to 
 the conversion specifier.
-
 .SH "DIFFERENCES FROM ANSI SPRINTF"
 .PP
 The behavior of the format command is the same as the
@@ -218,9 +216,56 @@ of real and integer values, respectively).
 If the \fBh\fR modifier is specified then integer values are truncated
 to \fBshort\fR before conversion.  Both \fBh\fR and \fBl\fR modifiers
 are ignored on all other conversions.
+.SH EXAMPLES
+Convert the output of \fBtime\fR into seconds to an accuracy of
+hundredths of a second:
+.CS
+set us [lindex [time $someTclCode] 0]
+puts [\fBformat\fR "%.2f seconds to execute" [expr {$us / 1e6}]]
+.CE
+.PP
+Create a packed X11 literal color specification:
+.CS
+# Each color-component should be in range (0..255)
+set color [\fBformat\fR "#%02x%02x%02x" $r $g $b]
+.CE
+.PP
+Use XPG3 format codes to allow reordering of fields (a technique that
+is often used in localized message catalogs; see \fBmsgcat\fR) without
+reordering the data values passed to \fBformat\fR:
+.CS
+set fmt1 "Today, %d shares in %s were bought at $%.2f each"
+puts [\fBformat\fR $fmt1 123 "Global BigCorp" 19.37]
+
+set fmt2 "Bought %2\\$s equity ($%3$.2f x %1\\$d) today"
+puts [\fBformat\fR $fmt2 123 "Global BigCorp" 19.37]
+.CE
+.PP
+Print a small table of powers of three:
+.CS
+# Set up the column widths
+set w1 5
+set w2 10
+
+# Make a nice header (with separator) for the table first
+set sep +-[string repeat - $w1]-+-[string repeat - $w2]-+
+puts $sep
+puts [\fBformat\fR "| %-*s | %-*s |" $w1 "Index" $w2 "Power"]
+puts $sep
+
+# Print the contents of the table
+set p 1
+for {set i 0} {$i<=20} {incr i} {
+   puts [\fBformat\fR "| %*d | %*ld |" $w1 $i $w2 $p]
+   set p [expr {wide($p) * 3}]
+}
+
+# Finish off by printing the separator again
+puts $sep
+.CE
 
 .SH "SEE ALSO"
-sprintf(3), string(n)
+scan(n), sprintf(3), string(n)
 
 .SH KEYWORDS
 conversion specifier, format, sprintf, string, substitution
diff --git a/doc/gets.n b/doc/gets.n
index f884d11..9c8c5db 100644
--- a/doc/gets.n
+++ b/doc/gets.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: gets.n,v 1.4 2001/09/14 19:20:40 andreas_kupries Exp $
+'\" RCS: @(#) $Id: gets.n,v 1.4.8.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH gets n 7.5 Tcl "Tcl Built-In Commands"
@@ -51,6 +51,18 @@ produce the same results as if there were an input line consisting
 only of the end-of-line character(s).
 The \fBeof\fR and \fBfblocked\fR commands can be used to distinguish
 these three cases.
+.SH "EXAMPLE"
+This example reads a file one line at a time and prints it out with
+the current line number attached to the start of each line.
+.PP
+.CS
+set chan [open "some.file.txt"]
+set lineNumber 0
+while {[\fBgets\fR $chan line] >= 0} {
+    puts "[incr lineNumber]: $line"
+}
+close $chan
+.CE
 
 .SH "SEE ALSO"
 file(n), eof(n), fblocked(n), Tcl_StandardChannels(3)
diff --git a/doc/glob.n b/doc/glob.n
index 15ae60c..871f668 100644
--- a/doc/glob.n
+++ b/doc/glob.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: glob.n,v 1.12 2002/07/01 18:24:39 jenglish Exp $
+'\" RCS: @(#) $Id: glob.n,v 1.12.2.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH glob n 8.3 Tcl "Tcl Built-In Commands"
@@ -78,6 +78,9 @@ the Unix find command:
 \fIp\fR (named pipe),
 or \fIs\fR (socket), where multiple types may be specified in the list.
 \fBGlob\fR will return all files which match at least one of the types given.
+Note that symbolic links will be returned both if \fB\-types l\fR is given, 
+or if the target of a link matches the requested type.  So, a link to
+a directory will be returned if \fB\-types d\fR was specified.
 .RS
 .PP
 The second form specifies types where all the types given must match.
@@ -149,7 +152,13 @@ command if you want the list sorted).
 Second, \fBglob\fR only returns the names of files that actually
 exist;  in csh no check for existence is made unless a pattern
 contains a ?, *, or [] construct.
-
+.LP
+When the \fBglob\fR command returns relative paths whose filenames
+start with a tilde ``~'' (for example through \fBglob *\fR or 
+\fBglob -tails\fR, the returned list will not quote the tilde with
+``./''.  This means care must be taken if those names are later to
+be used with \fBfile join\fR, to avoid them being interpreted as
+absolute paths pointing to a given user's home directory.
 .SH "PORTABILITY ISSUES"
 .PP
 Unlike other Tcl commands that will accept both network and native
@@ -184,6 +193,27 @@ When using the options, \fB\-directory\fR, \fB\-join\fR or \fB\-path\fR, glob
 assumes the directory separator for the entire pattern is the standard
 ``:''.  When not using these options, glob examines each pattern argument
 and uses ``/'' unless the pattern contains a ``:''.
+.SH EXAMPLES
+Find all the Tcl files in the current directory:
+.CS
+\fBglob\fR *.tcl
+.CE
+.PP
+Find all the Tcl files in the user's home directory, irrespective of
+what the current directory is:
+.CS
+\fBglob\fR \-directory ~ *.tcl
+.CE
+.PP
+Find all subdirectories of the current directory:
+.CS
+\fBglob\fR \-type d *
+.CE
+.PP
+Find all files whose name contains an "a", a "b" or the sequence "cde":
+.CS
+\fBglob\fR \-type f *{a,b,cde}*
+.CE
 
 .SH "SEE ALSO"
 file(n)
diff --git a/doc/global.n b/doc/global.n
index d4fd4c0..ece44a1 100644
--- a/doc/global.n
+++ b/doc/global.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: global.n,v 1.4 2002/06/11 13:22:35 msofer Exp $
+'\" RCS: @(#) $Id: global.n,v 1.4.2.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH global n "" Tcl "Tcl Built-In Commands"
@@ -19,15 +19,34 @@ global \- Access global variables
 
 .SH DESCRIPTION
 .PP
-This command is ignored unless a Tcl procedure is being interpreted.
-If so then it declares the given \fIvarname\fR's to be global variables
-rather than local ones.
-Global variables are variables in the global namespace.
-For the duration of the current procedure
-(and only while executing in the current procedure),
-any reference to any of the \fIvarname\fRs
-will refer to the global variable by the same name.
+This command has no effect unless executed in the context of a proc body.
+If the \fBglobal\fR command is executed in the context of a proc body, it
+creates local variables linked to the corresponding global variables (and
+therefore these variables are listed by info locals).
 .PP
+If \fIvarname\fR contains namespace qualifiers, the local variable's name is
+the unqualified name of the global variable, as determined by the
+\fBnamespace tail\fR command. 
+.SH EXAMPLES
+This procedure sets the namespace variable \fI::a::x\fR
+.CS
+proc reset {} {
+    \fBglobal\fR a::x
+    set x 0
+}
+.CE
+.PP
+This procedure accumulates the strings passed to it in a global
+buffer, separated by newlines.  It is useful for situations when you
+want to build a message piece-by-piece (as if with \fBputs\fR) but
+send that full message in a single piece (e.g. over a connection
+opened with \fBsocket\fR or as part of a counted HTTP response).
+.CS
+proc accum {string} {
+    \fBglobal\fR accumulator
+    append accumulator $string \\n
+}
+.CE
 
 .SH "SEE ALSO"
 namespace(n), upvar(n), variable(n)
diff --git a/doc/history.n b/doc/history.n
index 4e0716a..d8beb08 100644
--- a/doc/history.n
+++ b/doc/history.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: history.n,v 1.2 1998/09/14 18:39:53 stanton Exp $
+'\" RCS: @(#) $Id: history.n,v 1.2.40.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH history n "" Tcl "Tcl Built-In Commands"
@@ -82,7 +82,7 @@ in the history list.  It is useful for things like printing the
 event number in command-line prompts.
 .TP
 \fBhistory redo \fR?\fIevent\fR?
-Re-executes the command indicated by \fIevent\fR and return its result.
+Re-executes the command indicated by \fIevent\fR and returns its result.
 \fIEvent\fR defaults to \fB\-1\fR.  This command results in history
 revision:  see below for details.
 .SH "HISTORY REVISION"
diff --git a/doc/http.n b/doc/http.n
index a76e6ff..95efcd6 100644
--- a/doc/http.n
+++ b/doc/http.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: http.n,v 1.18.2.2 2004/05/25 22:50:46 hobbs Exp $
+'\" RCS: @(#) $Id: http.n,v 1.18.2.3 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH "http" n 2.5 http "Tcl Bundled Packages"
@@ -55,7 +55,7 @@ firewalls.  The package is compatible with the \fBSafesock\fR security
 policy, so it can be used by untrusted applets to do URL fetching from
 a restricted set of hosts. This package can be extended to support
 additional HTTP transport protocols, such as HTTPS, by providing
-a custom \fBsocket\fR command, via \fBhttp::register\fR.
+a custom \fBsocket\fR command, via \fB::http::register\fR.
 .PP
 The \fB::http::geturl\fR procedure does a HTTP transaction.
 Its \fIoptions \fR determine whether a GET, POST, or HEAD transaction
@@ -88,7 +88,7 @@ flags and values that define the configuration:
 \fB\-accept\fP \fImimetypes\fP
 The Accept header of the request.  The default is */*, which means that
 all types of documents are accepted.  Otherwise you can supply a 
-comma separated list of mime type patterns that you are
+comma-separated list of mime type patterns that you are
 willing to receive.  For example, "image/gif, image/jpeg, text/*".
 .TP
 \fB\-proxyhost\fP \fIhostname\fP
@@ -103,7 +103,7 @@ The command is a callback that is made during
 \fB::http::geturl\fR
 to determine if a proxy is required for a given host.  One argument, a
 host name, is added to \fIcommand\fR when it is invoked.  If a proxy
-is required, the callback should return a two element list containing
+is required, the callback should return a two-element list containing
 the proxy server and proxy port.  Otherwise the filter should return
 an empty list.  The default filter returns the values of the
 \fB\-proxyhost\fR and \fB\-proxyport\fR settings if they are
@@ -137,13 +137,13 @@ that is invoked when the HTTP transaction completes.
 .RS
 .TP
 \fB\-binary\fP \fIboolean\fP
-Specifies whether to force interpreting the url data as binary.  Normally
+Specifies whether to force interpreting the URL data as binary.  Normally
 this is auto-detected (anything not beginning with a \fBtext\fR content
 type or whose content encoding is \fBgzip\fR or \fBcompress\fR is
 considered binary data).
 .TP
 \fB\-blocksize\fP \fIsize\fP
-The blocksize used when reading the URL.
+The block size used when reading the URL.
 At most \fIsize\fR bytes are read at once.  After each block, a call to the
 \fB\-progress\fR callback is made (if that option is specified).
 .TP
@@ -217,12 +217,12 @@ proc httpProgress {token total current} {
 .TP
 \fB\-query\fP \fIquery\fP
 This flag causes \fB::http::geturl\fR to do a POST request that passes the
-\fIquery\fR to the server. The \fIquery\fR must be a x-url-encoding
+\fIquery\fR to the server. The \fIquery\fR must be an x-url-encoding
 formatted query.  The \fB::http::formatQuery\fR procedure can be used to
 do the formatting.
 .TP
 \fB\-queryblocksize\fP \fIsize\fP
-The blocksize used when posting query data to the URL.
+The block size used when posting query data to the URL.
 At most 
 \fIsize\fR
 bytes are written at once.  After each block, a call to the
@@ -231,7 +231,8 @@ callback is made (if that option is specified).
 .TP
 \fB\-querychannel\fP \fIchannelID\fP
 This flag causes \fB::http::geturl\fR to do a POST request that passes the
-data contained in \fIchannelID\fR to the server. The data contained in \fIchannelID\fR must be a x-url-encoding
+data contained in \fIchannelID\fR to the server. The data contained in
+\fIchannelID\fR must be an x-url-encoding
 formatted query unless the \fB\-type\fP option below is used.
 If a Content-Length header is not specified via the \fB\-headers\fR options,
 \fB::http::geturl\fR attempts to determine the size of the post data
@@ -328,18 +329,18 @@ command to execute to create the Tcl \fBchannel\fR. E.g.:
 package require http
 package require tls
 
-http::register https 443 ::tls::socket
+::http::register https 443 ::tls::socket
 
-set token [http::geturl https://my.secure.site/]
+set token [::http::geturl https://my.secure.site/]
 .CE
 .RE
 .TP
 \fB::http::unregister\fP \fIproto\fP
 This procedure unregisters a protocol handler that was previously
-registered via \fBhttp::register\fR.
+registered via \fB::http::register\fR.
 
 .SH "ERRORS"
-The \fBhttp::geturl\fP procedure will raise errors in the following cases:
+The \fB::http::geturl\fP procedure will raise errors in the following cases:
 invalid command line options,
 an invalid URL,
 a URL on a non-existent host,
@@ -371,17 +372,17 @@ to know the result of the asynchronous HTTP request, it can call
 callback does.
 .PP
 In any case, you must still call
-\fBhttp::cleanup\fP to delete the state array when you're done.
+\fB::http::cleanup\fP to delete the state array when you're done.
 .PP
 There are other possible results of the HTTP transaction
-determined by examining the status from \fBhttp::status\fP.
+determined by examining the status from \fB::http::status\fP.
 These are described below.
 .TP
 ok
 If the HTTP transaction completes entirely, then status will be \fBok\fP.
-However, you should still check the \fBhttp::code\fP value to get
-the HTTP status.  The \fBhttp::ncode\fP procedure provides just
-the numeric error (e.g., 200, 404 or 500) while the \fBhttp::code\fP
+However, you should still check the \fB::http::code\fP value to get
+the HTTP status.  The \fB::http::ncode\fP procedure provides just
+the numeric error (e.g., 200, 404 or 500) while the \fB::http::code\fP
 procedure returns a value like "HTTP 404 File not found".
 .TP
 eof
@@ -392,11 +393,11 @@ error
 The error message will also be stored in the \fBerror\fP status
 array element, accessible via \fB::http::error\fP.
 .PP
-Another error possibility is that \fBhttp::geturl\fP is unable to
+Another error possibility is that \fB::http::geturl\fP is unable to
 write all the post query data to the server before the server
 responds and closes the socket.
 The error message is saved in the \fBposterror\fP status array
-element and then  \fBhttp::geturl\fP attempts to complete the
+element and then  \fB::http::geturl\fP attempts to complete the
 transaction.
 If it can read the server's response
 it will end up with an \fBok\fP status, otherwise it will have
@@ -409,9 +410,9 @@ Use this construct to create an easy-to-use array variable:
 .CS
 upvar #0 $token state
 .CE
-Once the data associated with the url is no longer needed, the state
+Once the data associated with the URL is no longer needed, the state
 array should be unset to free up storage.
-The \fBhttp::cleanup\fP procedure is provided for that purpose.
+The \fB::http::cleanup\fP procedure is provided for that purpose.
 The following elements of
 the array are supported:
 .RS
@@ -496,38 +497,41 @@ A copy of the \fBContent-Type\fR meta-data value.
 The requested URL.
 .RE
 .SH EXAMPLE
-.DS
+.CS
 # Copy a URL to a file and print meta-data
-proc ::http::copy { url file {chunk 4096} } {
-    set out [open $file w]
-    set token [geturl $url -channel $out -progress ::http::Progress \\
-	-blocksize $chunk]
-    close $out
-    # This ends the line started by http::Progress
-    puts stderr ""
-    upvar #0 $token state
-    set max 0
-    foreach {name value} $state(meta) {
-	if {[string length $name] > $max} {
-	    set max [string length $name]
-	}
-	if {[regexp -nocase ^location$ $name]} {
-	    # Handle URL redirects
-	    puts stderr "Location:$value"
-	    return [copy [string trim $value] $file $chunk]
-	}
-    }
-    incr max
-    foreach {name value} $state(meta) {
-	puts [format "%-*s %s" $max $name: $value]
-    }
+proc httpcopy { url file {chunk 4096} } {
+   set out [open $file w]
+   set token [\fB::http::geturl\fR $url -channel $out \\
+          -progress httpCopyProgress -blocksize $chunk]
+   close $out
+
+   # This ends the line started by httpCopyProgress
+   puts stderr ""
 
-    return $token
+   upvar #0 $token state
+   set max 0
+   foreach {name value} $state(meta) {
+      if {[string length $name] > $max} {
+         set max [string length $name]
+      }
+      if {[regexp -nocase ^location$ $name]} {
+         # Handle URL redirects
+         puts stderr "Location:$value"
+         return [httpcopy [string trim $value] $file $chunk]
+      }
+   }
+   incr max
+   foreach {name value} $state(meta) {
+      puts [format "%-*s %s" $max $name: $value]
+   }
+
+   return $token
 }
-proc ::http::Progress {args} {
-    puts -nonewline stderr . ; flush stderr
+proc httpCopyProgress {args} {
+   puts -nonewline stderr .
+   flush stderr
 }
-.DE
+.CE
 
 .SH "SEE ALSO"
 safe(n), socket(n), safesock(n)
diff --git a/doc/if.n b/doc/if.n
index 7f9032f..a23dd5f 100644
--- a/doc/if.n
+++ b/doc/if.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: if.n,v 1.3 2000/09/07 14:27:48 poenitz Exp $
+'\" RCS: @(#) $Id: if.n,v 1.3.18.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH if n "" Tcl "Tcl Built-In Commands"
@@ -38,6 +38,41 @@ There may be any number of \fBelseif\fR clauses, including zero.
 The return value from the command is the result of the body script
 that was executed, or an empty string
 if none of the expressions was non-zero and there was no \fIbodyN\fR.
+.SH EXAMPLES
+A simple conditional:
+.CS
+\fBif\fR {$vbl == 1} { puts "vbl is one" }
+.CE
+.PP
+With an \fBelse\fR-clause:
+.CS
+\fBif\fR {$vbl == 1} {
+   puts "vbl is one"
+} \fBelse\fR {
+   puts "vbl is not one"
+}
+.CE
+.PP
+With an \fBelseif\fR-clause too:
+.CS
+\fBif\fR {$vbl == 1} {
+   puts "vbl is one"
+} \fBelseif\fR {$vbl == 2} {
+   puts "vbl is two"
+} \fBelse\fR {
+   puts "vbl is not one or two"
+}
+.CE
+.PP
+Remember, expressions can be multi-line, but in that case it can be a
+good idea to use the optional \fBthen\fR keyword for clarity:
+.CS
+\fBif\fR {
+   $vbl == 1 || $vbl == 2 || $vbl == 3
+} \fBthen\fR {
+   puts "vbl is one, two or three"
+}
+.CE
 
 .SH "SEE ALSO"
 expr(n), for(n), foreach(n)
diff --git a/doc/incr.n b/doc/incr.n
index 68f3114..7ad644a 100644
--- a/doc/incr.n
+++ b/doc/incr.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: incr.n,v 1.3 2000/09/07 14:27:48 poenitz Exp $
+'\" RCS: @(#) $Id: incr.n,v 1.3.18.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH incr n "" Tcl "Tcl Built-In Commands"
@@ -26,6 +26,29 @@ integer) is added to the value of variable \fIvarName\fR;  otherwise
 1 is added to \fIvarName\fR.
 The new value is stored as a decimal string in variable \fIvarName\fR
 and also returned as result.
+.SH EXAMPLES
+Add one to the contents of the variable \fIx\fR:
+.CS
+\fBincr\fR x
+.CE
+.PP
+Add 42 to the contents of the variable \fIx\fR:
+.CS
+\fBincr\fR x 42
+.CE
+.PP
+Add the contents of the variable \fIy\fR to the contents of the
+variable \fIx\fR:
+.CS
+\fBincr\fR x $y
+.CE
+.PP
+Add nothing at all to the variable \fIx\fR (often useful for checking
+whether an argument to a procedure is actually numeric and generating
+an error if it is not):
+.CS
+\fBincr\fR x 0
+.CE
 
 .SH "SEE ALSO"
 expr(n)
diff --git a/doc/info.n b/doc/info.n
index 7f66d39..dc94649 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.1 2004/02/13 01:29:16 hobbs Exp $
+'\" RCS: @(#) $Id: info.n,v 1.8.2.2 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH info n 8.4 Tcl "Tcl Built-In Commands"
@@ -48,7 +48,7 @@ only those names matching \fIpattern\fR are returned.
 Matching is determined using the same rules as for \fBstring match\fR.
 \fIpattern\fR can be a qualified name like \fBFoo::print*\fR.
 That is, it may specify a particular namespace
-using a sequence of namespace names separated by \fB::\fRs,
+using a sequence of namespace names separated by double colons (\fB::\fR),
 and may have pattern matching special characters
 at the end to specify a set of commands in that namespace.
 If \fIpattern\fR is a qualified name,
@@ -57,7 +57,7 @@ of the specified namespace.
 .TP
 \fBinfo complete \fIcommand\fR
 Returns 1 if \fIcommand\fR is a complete Tcl command in the sense of
-having no unclosed quotes, braces, brackets or array element names,
+having no unclosed quotes, braces, brackets or array element names.
 If the command doesn't appear to be complete then 0 is returned.
 This command is typically used in line-oriented input environments
 to allow users to type in commands that span multiple lines;  if the
@@ -163,6 +163,11 @@ only those procedure names in the current namespace
 matching \fIpattern\fR are returned.
 Matching is determined using the same rules as for
 \fBstring match\fR.
+If \fIpattern\fR contains any namespace separators, they are used to
+select a namespace relative to the current namespace (or relative to
+the global namespace if \fIpattern\fR starts with \fB::\fR) to match
+within; the matching pattern is taken to be the part after the last
+namespace separator.
 .TP
 \fBinfo script\fR ?\fIfilename\fR?
 If a Tcl script file is currently being evaluated (i.e. there is a
@@ -193,7 +198,7 @@ are returned.  Matching is determined using the same rules as for
 \fBstring match\fR.
 \fIpattern\fR can be a qualified name like \fBFoo::option*\fR.
 That is, it may specify a particular namespace
-using a sequence of namespace names separated by \fB::\fRs,
+using a sequence of namespace names separated by double colons (\fB::\fR),
 and may have pattern matching special characters
 at the end to specify a set of variables in that namespace.
 If \fIpattern\fR is a qualified name,
@@ -202,6 +207,25 @@ has each matching namespace variable qualified with the name
 of its namespace.
 Note that a currently-visible variable may not yet "exist" if it has not
 been set (e.g. a variable declared but not set by \fBvariable\fR).
+.SH EXAMPLE
+This command prints out a procedure suitable for saving in a Tcl
+script:
+.CS
+proc printProc {procName} {
+    set result [list proc $procName]
+    set formals {}
+    foreach var [\fBinfo\fR args $procName] {
+        if {[\fBinfo\fR default $procName $var def]} {
+            lappend formals [list $var $def]
+        } else {
+            # Still need the list-quoting because variable
+            # names may properly contain spaces.
+            lappend formals [list $var]
+        }
+    }
+    puts [lappend result $formals [\fBinfo\fR body $procName]]
+}
+.CE
 
 .SH "SEE ALSO"
 global(n), proc(n)
diff --git a/doc/interp.n b/doc/interp.n
index ac8adfb..a118e50 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 2002/07/01 18:24:39 jenglish Exp $
+'\" RCS: @(#) $Id: interp.n,v 1.9.2.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH interp n 7.6 Tcl "Tcl Built-In Commands"
@@ -48,15 +48,16 @@ application's environment. For example, all IO channel creation
 commands and subprocess creation commands are made inaccessible to safe
 interpreters.
 .VS
-See SAFE INTERPRETERS below for more information on
+See \fBSAFE INTERPRETERS\fR below for more information on
 what features are present in a safe interpreter.
 The dangerous functionality is not removed from the safe interpreter;
 instead, it is \fIhidden\fR, so that only trusted interpreters can obtain
 access to it. For a detailed explanation of hidden commands, see
-HIDDEN COMMANDS, below.
+\fBHIDDEN COMMANDS\fR, below.
 The alias mechanism can be used for protected communication (analogous to a
-kernel call) between a slave interpreter and its master. See ALIAS
-INVOCATION, below, for more details on how the alias mechanism works.
+kernel call) between a slave interpreter and its master. 
+See \fBALIAS INVOCATION\fR, below, for more details 
+on how the alias mechanism works.
 .VE
 .PP
 A qualified interpreter name is a proper Tcl lists containing a subset of its
@@ -74,27 +75,24 @@ it is impossible to refer to a master (ancestor) interpreter by name in a
 slave interpreter except through aliases. Also, there is no global name by
 which one can refer to the first interpreter created in an application.
 Both restrictions are motivated by safety concerns.
-
-.VS
 .SH "THE INTERP COMMAND"
 .PP
-.VE
 The \fBinterp\fR command is used to create, delete, and manipulate
 slave interpreters, and to share or transfer
 channels between interpreters.  It can have any of several forms, depending
 on the \fIoption\fR argument:
 .TP
-\fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcCmd\fR
+\fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcToken\fR
 Returns a Tcl list whose elements are the \fItargetCmd\fR and
-\fIarg\fRs associated with the alias named \fIsrcCmd\fR
-(all of these are the values specified when the alias was
-created; it is possible that the actual source command in the
-slave is different from \fIsrcCmd\fR if it was renamed).
+\fIarg\fRs associated with the alias represented by \fIsrcToken\fR
+(this is the value returned when the alias was
+created; it is possible that the name of the source command in the
+slave is different from \fIsrcToken\fR).
 .TP
-\fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcCmd\fR \fB{}\fR
-Deletes the alias for \fIsrcCmd\fR in the slave interpreter identified by
+\fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcToken\fR \fB{}\fR
+Deletes the alias for \fIsrcToken\fR in the slave interpreter identified by
 \fIsrcPath\fR.
-\fIsrcCmd\fR refers to the name under which the alias
+\fIsrcToken\fR refers to the value returned when the alias
 was created;  if the source command has been renamed, the renamed
 command will be deleted.
 .TP
@@ -119,12 +117,18 @@ in the invocation of \fIsrcCmd\fR.
 already exist; it is not created by this command.
 The alias arranges for the given target command to be invoked
 in the target interpreter whenever the given source command is
-invoked in the source interpreter.  See ALIAS INVOCATION below for
-more details.
+invoked in the source interpreter.  See \fBALIAS INVOCATION\fR below for
+more details. 
+The command returns a token that uniquely identifies the command created
+\fIsrcCmd\fR, even if the command is renamed afterwards. The token may but
+does not have to be equal to \fIsrcCmd\fR.
 .TP
 \fBinterp\fR \fBaliases \fR?\fIpath\fR?
-This command returns a Tcl list of the names of all the source commands for
-aliases defined in the interpreter identified by \fIpath\fR.
+This command returns a Tcl list of the tokens of all the source commands for
+aliases defined in the interpreter identified by \fIpath\fR. The tokens
+correspond to the values returned when 
+the aliases were created (which may not be the same 
+as the current names of the commands).
 .TP
 \fBinterp\fR \fBcreate \fR?\fB\-safe\fR? ?\fB\-\|\-\fR? ?\fIpath\fR?
 Creates a slave interpreter identified by \fIpath\fR and a new command,
@@ -164,6 +168,11 @@ a Tcl script in the slave interpreter identified by \fIpath\fR. The result
 of this evaluation (including error information such as the \fBerrorInfo\fR
 and \fBerrorCode\fR variables, if an error occurs) is returned to the
 invoking interpreter.
+Note that the script will be executed in the current context stack frame of the
+\fIpath\fR interpreter; this is so that the implementations (in a master
+interpreter) of aliases in a slave interpreter can execute scripts in
+the slave that find out information about the slave's current state
+and stack frame.
 .TP
 \fBinterp exists \fIpath\fR
 Returns  \fB1\fR if a slave interpreter by the specified \fIpath\fR
@@ -179,7 +188,7 @@ in the interpreter
 denoted by \fIpath\fR.
 If an exposed command with the targeted name already exists, this command
 fails.
-Hidden commands are explained in more detail in HIDDEN COMMANDS, below.
+Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below.
 .TP
 \fBinterp\fR \fBhide\fR \fIpath\fR \fIexposedCmdName\fR ?\fIhiddenCmdName\fR?
 Makes the exposed command \fIexposedCmdName\fR hidden, renaming
@@ -194,7 +203,7 @@ Commands to be hidden by \fBinterp hide\fR are looked up in the global
 namespace even if the current namespace is not the global one. This
 prevents slaves from fooling a master interpreter into hiding the wrong
 command, by making the current namespace be different from the global one.
-Hidden commands are explained in more detail in HIDDEN COMMANDS, below.
+Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below.
 .TP
 \fBinterp\fR \fBhidden\fR \fIpath\fR
 Returns a list of the names of all hidden commands in the interpreter
@@ -208,7 +217,7 @@ If the \fB-global\fR flag is present, the hidden command is invoked at the
 global level in the target interpreter; otherwise it is invoked at the
 current call frame and can access local variables in that and outer call
 frames.
-Hidden commands are explained in more detail in HIDDEN COMMANDS, below.
+Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below.
 .VE
 .TP
 \fBinterp issafe\fR ?\fIpath\fR?
@@ -269,7 +278,6 @@ The target command does not have to be defined at the time of this invocation.
 Causes the IO channel identified by \fIchannelId\fR to become available in
 the interpreter identified by \fIdestPath\fR and unavailable in the
 interpreter identified by \fIsrcPath\fR.
-
 .SH "SLAVE COMMAND"
 .PP
 For each slave interpreter created with the \fBinterp\fR command, a
@@ -285,22 +293,21 @@ and the \fIarg\fRs determine the exact behavior of the command.
 The valid forms of this command are:
 .TP
 \fIslave \fBaliases\fR
-Returns a Tcl list whose elements are the names of all the
-aliases in \fIslave\fR.  The names returned are the \fIsrcCmd\fR
-values used when the aliases were created (which may not be the same
-as the current names of the commands, if they have been
-renamed).
+Returns a Tcl list whose elements are the tokens of all the
+aliases in \fIslave\fR.  The tokens correspond to the values returned when
+the aliases were created (which may not be the same 
+as the current names of the commands).
 .TP
-\fIslave \fBalias \fIsrcCmd\fR
+\fIslave \fBalias \fIsrcToken\fR
 Returns a Tcl list whose elements are the \fItargetCmd\fR and
-\fIarg\fRs associated with the alias named \fIsrcCmd\fR
-(all of these are the values specified when the alias was
+\fIarg\fRs associated with the alias represented by \fIsrcToken\fR
+(this is the value returned when the alias was
 created; it is possible that the actual source command in the
-slave is different from \fIsrcCmd\fR if it was renamed).
+slave is different from \fIsrcToken\fR).
 .TP
-\fIslave \fBalias \fIsrcCmd \fB{}\fR
-Deletes the alias for \fIsrcCmd\fR in the slave interpreter.
-\fIsrcCmd\fR refers to the name under which the alias
+\fIslave \fBalias \fIsrcToken \fB{}\fR
+Deletes the alias for \fIsrcToken\fR in the slave interpreter.
+\fIsrcToken\fR refers to the value returned when the alias
 was created;  if the source command has been renamed, the renamed
 command will be deleted.
 .TP
@@ -310,7 +317,10 @@ in \fIslave\fR, \fItargetCmd\fR is invoked in the master.
 The \fIarg\fR arguments will be passed to \fItargetCmd\fR as additional
 arguments, prepended before any arguments passed in the invocation of
 \fIsrcCmd\fR.
-See ALIAS INVOCATION below for details.
+See \fBALIAS INVOCATION\fR below for details.
+The command returns a token that uniquely identifies the command created
+\fIsrcCmd\fR, even if the command is renamed afterwards. The token may but
+does not have to be equal to \fIsrcCmd\fR.
 .TP
 \fIslave \fBeval \fIarg \fR?\fIarg ..\fR?
 This command concatenates all of the \fIarg\fR arguments in
@@ -319,6 +329,11 @@ the resulting string as a Tcl script in \fIslave\fR.
 The result of this evaluation (including error information
 such as the \fBerrorInfo\fR and \fBerrorCode\fR variables, if an
 error occurs) is returned to the invoking interpreter.
+Note that the script will be executed in the current context stack frame
+of \fIslave\fR; this is so that the implementations (in a master
+interpreter) of aliases in a slave interpreter can execute scripts in
+the slave that find out information about the slave's current state
+and stack frame.
 .VS "" BR
 .TP
 \fIslave \fBexpose \fIhiddenName \fR?\fIexposedCmdName\fR?
@@ -328,12 +343,12 @@ accepted only if it is a valid global name space name without any ::),
 in \fIslave\fR.
 If an exposed command with the targeted name already exists, this command
 fails.
-For more details on hidden commands, see HIDDEN COMMANDS, below.
+For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below.
 .TP
 \fIslave \fBhide \fIexposedCmdName\fR ?\fIhiddenCmdName\fR?
 This command hides the exposed command \fIexposedCmdName\fR, renaming it to 
 the hidden command \fIhiddenCmdName\fR, or keeping the same name if the
-the argument is not given, in the \fIslave\fR interpreter.
+argument is not given, in the \fIslave\fR interpreter.
 If a hidden command with the targeted name already exists, this command
 fails.
 Currently both \fIexposedCmdName\fR and \fIhiddenCmdName\fR can 
@@ -342,7 +357,7 @@ Commands to be hidden are looked up in the global
 namespace even if the current namespace is not the global one. This
 prevents slaves from fooling a master interpreter into hiding the wrong
 command, by making the current namespace be different from the global one.
-For more details on hidden commands, see HIDDEN COMMANDS, below.
+For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below.
 .TP
 \fIslave \fBhidden\fR
 Returns a list of the names of all hidden commands in \fIslave\fR.
@@ -354,8 +369,8 @@ applied to the arguments.
 If the \fB-global\fR flag is given, the command is invoked at the global
 level in the slave; otherwise it is invoked at the current call frame and
 can access local variables in that or outer call frames.
-For more details on hidden commands, see HIDDEN
-COMMANDS, below.
+For more details on hidden commands,
+see \fBHIDDEN COMMANDS\fR, below.
 .VE
 .TP
 \fIslave \fBissafe\fR
@@ -433,7 +448,7 @@ creates a safe interpreter:
 .DS
 .ta 1.2i 2.4i 3.6i
 \fBcd	encoding	exec	exit
-fconfigure file	glob	load
+fconfigure	file	glob	load
 open	pwd	socket	source\fR
 .DE
 These commands can be recreated later as Tcl procedures or aliases, or
@@ -487,7 +502,6 @@ management of extensions for safety see the manual entries for
 .PP
 A safe interpreter may not alter the recursion limit of any interpreter,
 including itself.
-
 .SH "ALIAS INVOCATION"
 .PP
 The alias mechanism has been carefully designed so that it can
@@ -528,7 +542,6 @@ evaluated or substituted, since this would provide an escape
 mechanism whereby the slave interpreter could execute arbitrary
 code in the master.  This in turn would compromise the security
 of the system.
-
 .VS
 .SH "HIDDEN COMMANDS"
 .PP
@@ -571,7 +584,7 @@ handling an alias invocation, great care must be taken to avoid evaluating
 any arguments passed in through the alias invocation.
 Otherwise, malicious slave interpreters could cause a trusted master
 interpreter to execute dangerous commands on their behalf. See the section
-on ALIAS INVOCATION for a more complete discussion of this topic.
+on \fBALIAS INVOCATION\fR for a more complete discussion of this topic.
 To help avoid this problem, no substitutions or evaluations are
 applied to arguments of \fBinterp invokehidden\fR.
 .PP
@@ -602,6 +615,27 @@ command, by making the current namespace be different from the global one.
 .PP
 This mechanism is based on the Safe-Tcl prototype implemented
 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}
+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
+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\fR eval $i $someUntrustedScript
+.CE
 
 .SH "SEE ALSO"
 load(n), safe(n), Tcl_CreateSlave(3)
diff --git a/doc/join.n b/doc/join.n
index 45c6bda..79f85d2 100644
--- a/doc/join.n
+++ b/doc/join.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: join.n,v 1.3 2000/09/07 14:27:48 poenitz Exp $
+'\" RCS: @(#) $Id: join.n,v 1.3.18.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH join n "" Tcl "Tcl Built-In Commands"
@@ -24,9 +24,23 @@ This command returns the string
 formed by joining all of the elements of \fIlist\fR together with
 \fIjoinString\fR separating each adjacent pair of elements.
 The \fIjoinString\fR argument defaults to a space character.
+.SH EXAMPLES
+Making a comma-separated list:
+.CS
+set data {1 2 3 4 5}
+\fBjoin\fR $data ", "
+     \fB=> 1, 2, 3, 4, 5\fR
+.CE
+.PP
+Using \fBjoin\fR to flatten a list by a single level:
+.CS
+set data {1 {2 3} 4 {5 {6 7} 8}}
+\fBjoin\fR $data
+     \fB=> 1 2 3 4 5 {6 7} 8\fR
+.CE
 
 .SH "SEE ALSO"
-list(n), lappend(n)
+list(n), lappend(n), split(n)
 
 .SH KEYWORDS
 element, join, list, separator
diff --git a/doc/lappend.n b/doc/lappend.n
index 6a0d9bc..a79caf1 100644
--- a/doc/lappend.n
+++ b/doc/lappend.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: lappend.n,v 1.6 2001/11/14 23:38:39 hobbs Exp $
+'\" RCS: @(#) $Id: lappend.n,v 1.6.4.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH lappend n "" Tcl "Tcl Built-In Commands"
@@ -31,6 +31,16 @@ This command provides a relatively efficient way to build up
 large lists.  For example, ``\fBlappend a $b\fR'' is much
 more efficient than ``\fBset a [concat $a [list $b]]\fR'' when
 \fB$a\fR is long.
+.SH EXAMPLE
+Using \fBlappend\fR to build up a list of numbers.
+.CS
+% set var 1
+1
+% \fBlappend\fR var 2
+1 2
+% \fBlappend\fR var 3 4 5
+1 2 3 4 5
+.CE
 
 .SH "SEE ALSO"
 list(n), lindex(n), linsert(n), llength(n), 
diff --git a/doc/lindex.n b/doc/lindex.n
index 81e8bd0..04ba9e1 100644
--- a/doc/lindex.n
+++ b/doc/lindex.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: lindex.n,v 1.7 2001/11/14 23:15:33 hobbs Exp $
+'\" RCS: @(#) $Id: lindex.n,v 1.7.4.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH lindex n 8.4 Tcl "Tcl Built-In Commands"
@@ -69,16 +69,16 @@ lindex [lindex [lindex $a 1] 2] 3
 .CE
 .SH EXAMPLES
 .CS
-lindex {a b c}  => a b c
-lindex {a b c} {} => a b c
-lindex {a b c} 0 => a
-lindex {a b c} 2 => c
-lindex {a b c} end => c
-lindex {a b c} end-1 => b
-lindex {{a b c} {d e f} {g h i}} 2 1 => h
-lindex {{a b c} {d e f} {g h i}} {2 1} => h
-lindex {{{a b} {c d}} {{e f} {g h}}} 1 1 0 => g
-lindex {{{a b} {c d}} {{e f} {g h}}} {1 1 0} => g
+\fBlindex\fR {a b c}  \fI=> a b c\fR
+\fBlindex\fR {a b c} {} \fI=> a b c\fR
+\fBlindex\fR {a b c} 0 \fI=> a\fR
+\fBlindex\fR {a b c} 2 \fI=> c\fR
+\fBlindex\fR {a b c} end \fI=> c\fR
+\fBlindex\fR {a b c} end-1 \fI=> b\fR
+\fBlindex\fR {{a b c} {d e f} {g h i}} 2 1 \fI=> h\fR
+\fBlindex\fR {{a b c} {d e f} {g h i}} {2 1} \fI=> h\fR
+\fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} 1 1 0 \fI=> g\fR
+\fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} {1 1 0} \fI=> g\fR
 .CE
 .VE
 .SH "SEE ALSO"
diff --git a/doc/linsert.n b/doc/linsert.n
index 3a0a66d..8119955 100644
--- a/doc/linsert.n
+++ b/doc/linsert.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: linsert.n,v 1.7 2001/11/14 23:38:39 hobbs Exp $
+'\" RCS: @(#) $Id: linsert.n,v 1.7.4.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH linsert n 8.2 Tcl "Tcl Built-In Commands"
@@ -21,7 +21,7 @@ linsert \- Insert elements into a list
 .SH DESCRIPTION
 .PP
 This command produces a new list from \fIlist\fR by inserting all of the
-\fIelement\fR arguments just before the \fIindex\fRth element of
+\fIelement\fR arguments just before the \fIindex\fR'th element of
 \fIlist\fR.  Each \fIelement\fR argument will become a separate element of
 the new list.  If \fIindex\fR is less than or equal to zero, then the new
 elements are inserted at the beginning of the list.  If \fIindex\fR has the
@@ -29,7 +29,16 @@ value \fBend\fR, or if it is greater than or equal to the number of
 elements in the list, then the new elements are appended to the list.
 \fBend\-\fIinteger\fR refers to the last element in the list minus the
 specified integer offset.
-
+.SH EXAMPLE
+Putting some values into a list, first indexing from the start and
+then indexing from the end, and then chaining them together:
+.CS
+set oldList {the fox jumps over the dog}
+set midList [\fBlinsert\fR $oldList 1 quick]
+set newList [\fBlinsert\fR $midList end-1 lazy]
+# The old lists still exist though...
+set newerList [\fBlinsert\fR [\fBlinsert\fR $oldList end-1 quick] 1 lazy]
+.CE
 
 .SH "SEE ALSO"
 .VS 8.4
diff --git a/doc/list.n b/doc/list.n
index 19a9034..cf41408 100644
--- a/doc/list.n
+++ b/doc/list.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: list.n,v 1.7 2001/12/05 22:26:43 dgp Exp $
+'\" RCS: @(#) $Id: list.n,v 1.7.4.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH list n "" Tcl "Tcl Built-In Commands"
@@ -29,13 +29,14 @@ so that \fBeval\fR may be used to execute the resulting list, with
 its arguments.  \fBList\fR produces slightly different results than
 \fBconcat\fR:  \fBconcat\fR removes one level of grouping before forming
 the list, while \fBlist\fR works directly from the original arguments.
-For example, the command
+.SH EXAMPLE
+The command
 .CS
-\fBlist a b {c d e} {f {g h}}\fR
+\fBlist\fR a b "c d e  " "  f {g h}"
 .CE
 will return
 .CS
-\fBa b {c d e} {f {g h}}\fR
+\fBa b {c d e  } {  f {g h}}\fR
 .CE
 while \fBconcat\fR with the same arguments will return
 .CS
@@ -43,12 +44,12 @@ while \fBconcat\fR with the same arguments will return
 .CE
 
 .SH "SEE ALSO"
-lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 
+lappend(n), lindex(n), linsert(n), llength(n), lrange(n),
+lreplace(n), lsearch(n),
 .VS 8.4
 lset(n),
-.VE
-lsort(n),
-lrange(n), lreplace(n)
+.VE 8.4
+lsort(n)
 
 .SH KEYWORDS
 element, list
diff --git a/doc/llength.n b/doc/llength.n
index 68dd1d8..fbec234 100644
--- a/doc/llength.n
+++ b/doc/llength.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: llength.n,v 1.6 2001/11/14 23:38:39 hobbs Exp $
+'\" RCS: @(#) $Id: llength.n,v 1.6.4.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH llength n "" Tcl "Tcl Built-In Commands"
@@ -23,6 +23,32 @@ llength \- Count the number of elements in a list
 Treats \fIlist\fR as a list and returns a decimal string giving
 the number of elements in it.
 
+.SH EXAMPLES
+The result is the number of elements:
+.CS
+% \fBllength\fR {a b c d e}
+5
+% \fBllength\fR {a b c}
+3
+% \fBllength\fR {}
+0
+.CE
+.PP
+Elements are not guaranteed to be exactly words in a dictionary sense
+of course, especially when quoting is used:
+.CS
+% \fBllength\fR {a b {c d} e}
+4
+% \fBllength\fR {a b { } c d e}
+6
+.CE
+.PP
+An empty list is not necessarily an empty string:
+.CS
+% set var { }; puts "[string length $var],[\fBllength\fR $var]"
+1,0
+.CE
+
 .SH "SEE ALSO"
 .VS 8.4
 list(n), lappend(n), lindex(n), linsert(n), lsearch(n), 
diff --git a/doc/load.n b/doc/load.n
index 5f404e1..ea5c7f3 100644
--- a/doc/load.n
+++ b/doc/load.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: load.n,v 1.7 2002/07/01 18:24:39 jenglish Exp $
+'\" RCS: @(#) $Id: load.n,v 1.7.2.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH load n 7.5 Tcl "Tcl Built-In Commands"
@@ -105,7 +105,6 @@ package by that name, and uses it if it is found.  If several
 different files have been \fBload\fRed with different versions of
 the package, Tcl picks the file that was loaded first.
 .VE
-
 .SH "PORTABILITY ISSUES"
 .TP
 \fBWindows\fR\0\0\0\0\0
@@ -116,17 +115,55 @@ type ``dumpbin -imports <dllname>'' in a DOS console to see what the
 library must import.
 When loading a DLL in the current directory, Windows will ignore ``./'' as
 a path specifier and use a search heuristic to find the DLL instead.
-To avoid this, load the DLL with
+To avoid this, load the DLL with:
 .CS
-    load [file join [pwd] mylib.DLL]
+\fBload\fR [file join [pwd] mylib.DLL]
 .CE
-
 .SH BUGS
 .PP
 If the same file is \fBload\fRed by different \fIfileName\fRs, it will
 be loaded into the process's address space multiple times.  The
 behavior of this varies from system to system (some systems may
 detect the redundant loads, others may not).
+.SH EXAMPLE
+The following is a minimal extension:
+.PP
+.CS
+#include <tcl.h>
+#include <stdio.h>
+static int fooCmd(ClientData clientData,
+        Tcl_Interp *interp, int objc, char * CONST objv[]) {
+    printf("called with %d arguments\\n", objc);
+    return TCL_OK;
+}
+int Foo_Init(Tcl_Interp *interp) {
+    if (Tcl_InitStubs(interp, "8.1", 0) == NULL) {
+	return TCL_ERROR;
+    }
+    printf("creating foo command");
+    Tcl_CreateObjCommand(interp, "foo", fooCmd, NULL, NULL);
+    return TCL_OK;
+}
+.CE
+.PP
+When built into a shared/dynamic library with a suitable name
+(e.g. \fBfoo.dll\fR on Windows, \fBlibfoo.so\fR on Solaris and Linux)
+it can then be loaded into Tcl with the following:
+.PP
+.CS
+# Load the extension
+switch $tcl_platform(platform) {
+   windows {
+      \fBload\fR ./foo.dll
+   }
+   unix {
+      \fBload\fR ./libfoo[info sharedlibextension]
+   }
+}
+
+# Now execute the command defined by the extension
+foo
+.CE
 
 .SH "SEE ALSO"
 info sharedlibextension, Tcl_StaticPackage(3), safe(n)
diff --git a/doc/lrange.n b/doc/lrange.n
index bafc0a2..9274f35 100644
--- a/doc/lrange.n
+++ b/doc/lrange.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: lrange.n,v 1.6 2001/11/14 23:38:39 hobbs Exp $
+'\" RCS: @(#) $Id: lrange.n,v 1.6.4.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH lrange n 7.4 Tcl "Tcl Built-In Commands"
@@ -35,6 +35,35 @@ Note: ``\fBlrange \fIlist first first\fR'' does not always produce the
 same result as ``\fBlindex \fIlist first\fR'' (although it often does
 for simple fields that aren't enclosed in braces); it does, however,
 produce exactly the same results as ``\fBlist [lindex \fIlist first\fB]\fR''
+.SH EXAMPLES
+Selecting the first two elements:
+.CS
+% \fBlrange\fR {a b c d e} 0 1
+a b
+.CE
+.PP
+Selecting the last three elements:
+.CS
+% \fBlrange\fR {a b c d e} end-2 end
+c d e
+.CE
+.PP
+Selecting everything except the first and last element:
+.CS
+% \fBlrange\fR {a b c d e} 1 end-1
+b c d
+.CE
+.PP
+Selecting a single element with \fBlrange\fR is not the same as doing
+so with \fBlindex\fR:
+.CS
+% set var {some {elements to} select}
+some {elements to} select
+% lindex $var 1
+elements to
+% \fBlrange\fR $var 1 1
+{elements to}
+.CE
 
 .SH "SEE ALSO"
 .VS 8.4
diff --git a/doc/lreplace.n b/doc/lreplace.n
index 02164ac..cf059a6 100644
--- a/doc/lreplace.n
+++ b/doc/lreplace.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: lreplace.n,v 1.8 2001/11/14 23:38:39 hobbs Exp $
+'\" RCS: @(#) $Id: lreplace.n,v 1.8.4.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH lreplace n 7.4 Tcl "Tcl Built-In Commands"
@@ -43,6 +43,26 @@ Each \fIelement\fR argument will become a separate element of
 the list.  If no \fIelement\fR arguments are specified, then the elements
 between \fIfirst\fR and \fIlast\fR are simply deleted.  If \fIlist\fR
 is empty, any \fIelement\fR arguments are added to the end of the list.
+.SH EXAMPLES
+Replacing an element of a list with another:
+.CS
+% \fBlreplace\fR {a b c d e} 1 1 foo
+a foo c d e
+.CE
+.PP
+Replacing two elements of a list with three:
+.CS
+% \fBlreplace\fR {a b c d e} 1 2 three more elements
+a three more elements d e
+.CE
+.PP
+Deleting the last element from a list in a variable:
+.CS
+% set var {a b c d e}
+a b c d e
+% set var [\fBlreplace\fR $var end end]
+a b c d
+.CE
 
 .SH "SEE ALSO"
 .VS 8.4
diff --git a/doc/lsearch.n b/doc/lsearch.n
index 98cd8d3..b8a6f18 100644
--- a/doc/lsearch.n
+++ b/doc/lsearch.n
@@ -1,4 +1,5 @@
-'\"
+'\" -*- nroff -*-
+'\" 
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
 '\" Copyright (c) 2001 Kevin B. Kenny.  All rights reserved.
@@ -6,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: lsearch.n,v 1.13.2.2 2004/09/02 13:58:58 dkf Exp $
+'\" RCS: @(#) $Id: lsearch.n,v 1.13.2.3 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH lsearch n 8.4 Tcl "Tcl Built-In Commands"
@@ -119,13 +120,13 @@ precedence.
 .VS 8.4
 .SH EXAMPLES
 .CS
-lsearch {a b c d e} c => 2
-lsearch -all {a b c a b c} c => 2 5
-lsearch -inline {a20 b35 c47} b* => b35
-lsearch -inline -not {a20 b35 c47} b* => a20
-lsearch -all -inline -not {a20 b35 c47} b* => a20 c47
-lsearch -all -not {a20 b35 c47} b* => 0 2
-lsearch -start 3 {a b c a b c} c => 5
+\fBlsearch\fR {a b c d e} c \fI=> 2\fR
+\fBlsearch\fR -all {a b c a b c} c \fI=> 2 5\fR
+\fBlsearch\fR -inline {a20 b35 c47} b* \fI=> b35\fR
+\fBlsearch\fR -inline -not {a20 b35 c47} b* \fI=> a20\fR
+\fBlsearch\fR -all -inline -not {a20 b35 c47} b* \fI=> a20 c47\fR
+\fBlsearch\fR -all -not {a20 b35 c47} b* \fI=> 0 2\fR
+\fBlsearch\fR -start 3 {a b c a b c} c \fI=> 5\fR
 .CE
 .VE 8.4
 
diff --git a/doc/lsort.n b/doc/lsort.n
index 1e8a1fd..edd25e0 100644
--- a/doc/lsort.n
+++ b/doc/lsort.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: lsort.n,v 1.12.4.1 2003/03/17 14:25:20 dkf Exp $
+'\" RCS: @(#) $Id: lsort.n,v 1.12.4.2 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH lsort n 8.3 Tcl "Tcl Built-In Commands"
@@ -33,7 +33,7 @@ abbreviations are accepted):
 .TP 20
 \fB\-ascii\fR
 Use string comparison with Unicode code-point collation order (the
-name is for backward-compatability reasons.)  This is the default.
+name is for backward-compatibility reasons.)  This is the default.
 .TP 20
 \fB\-dictionary\fR
 Use dictionary-style comparison.  This is the same as \fB\-ascii\fR
@@ -102,7 +102,6 @@ determined relative to the comparison used in the sort.  Thus if
 \fI-index 0\fR is used, \fB{1 a}\fR and \fB{1 b}\fR would be
 considered duplicates and only the second element, \fB{1 b}\fR, would
 be retained.
-
 .SH "NOTES"
 .PP
 The options to \fBlsort\fR only control what sort of comparison is
@@ -113,60 +112,52 @@ sorted has fewer than two elements.
 The \fBlsort\fR command is reentrant, meaning it is safe to use as
 part of the implementation of a command used in the \fB\-command\fR
 option.
-
 .SH "EXAMPLES"
-
 .PP
 Sorting a list using ASCII sorting:
 .CS
-% lsort {a10 B2 b1 a1 a2}
+% \fBlsort\fR {a10 B2 b1 a1 a2}
 B2 a1 a10 a2 b1
 .CE
-
 .PP
 Sorting a list using Dictionary sorting:
 .CS
-% lsort -dictionary {a10 B2 b1 a1 a2}
+% \fBlsort\fR -dictionary {a10 B2 b1 a1 a2}
 a1 a2 a10 b1 B2
 .CE
-
 .PP
 Sorting lists of integers:
 .CS
-% lsort -integer {5 3 1 2 11 4}
+% \fBlsort\fR -integer {5 3 1 2 11 4}
 1 2 3 4 5 11
-% lsort -integer {1 2 0x5 7 0 4 -1}
+% \fBlsort\fR -integer {1 2 0x5 7 0 4 -1}
 -1 0 1 2 4 0x5 7
 .CE
-
 .PP
 Sorting lists of floating-point numbers:
 .CS
-% lsort -real {5 3 1 2 11 4}
+% \fBlsort\fR -real {5 3 1 2 11 4}
 1 2 3 4 5 11
-% lsort -real {.5 0.07e1 0.4 6e-1}
+% \fBlsort\fR -real {.5 0.07e1 0.4 6e-1}
 0.4 .5 6e-1 0.07e1
 .CE
-
 .PP
 Sorting using indices:
 .CS
 % # Note the space character before the c
-% lsort {{a 5} { c 3} {b 4} {e 1} {d 2}}
+% \fBlsort\fR {{a 5} { c 3} {b 4} {e 1} {d 2}}
 { c 3} {a 5} {b 4} {d 2} {e 1}
-% lsort -index 0 {{a 5} { c 3} {b 4} {e 1} {d 2}}
+% \fBlsort\fR -index 0 {{a 5} { c 3} {b 4} {e 1} {d 2}}
 {a 5} {b 4} { c 3} {d 2} {e 1}
-% lsort -index 1 {{a 5} { c 3} {b 4} {e 1} {d 2}}
+% \fBlsort\fR -index 1 {{a 5} { c 3} {b 4} {e 1} {d 2}}
 {e 1} {d 2} { c 3} {b 4} {a 5}
 .CE
-
 .PP
 Stripping duplicate values using sorting:
 .CS
-% lsort -unique {a b c a b c a b c}
+% \fBlsort\fR -unique {a b c a b c a b c}
 a b c
 .CE
-
 .PP
 More complex sorting using a comparison function:
 .CS
@@ -180,7 +171,7 @@ More complex sorting using a comparison function:
     }
     return [string compare [lindex $a 1] [lindex $b 1]]
 }
-% lsort -command compare \\
+% \fBlsort\fR -command compare \\
         {{3 apple} {0x2 carrot} {1 dingo} {2 banana}}
 {1 dingo} {2 banana} {0x2 carrot} {3 apple}
 .CE
-- 
cgit v0.12