merge updates from HEAD

13 files changed, 191 insertions, 143 deletions

diff --git a/doc/StdChannels.3 b/doc/StdChannels.3
index 73a5776..20cdb46 100644
--- a/doc/StdChannels.3
+++ b/doc/StdChannels.3
@@ -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: StdChannels.3,v 1.9 2004/09/06 09:44:57 dkf Exp $
+'\" RCS: @(#) $Id: StdChannels.3,v 1.9.12.1 2007/07/04 15:13:41 dgp Exp $
 '\" 
 .so man.macros
 .TH "Standard Channels" 3 7.5 Tcl "Tcl Library Procedures"
@@ -28,8 +28,7 @@ output and the other for error messages.
 .PP
 Tcl generalizes this concept in a cross-platform way and
 exposes standard channels to the script level.
-
-.SH APIs
+.SS "APPLICATION PROGRAMMING INTERFACES"
 .PP
 The public API procedures dealing directly with standard channels are
 \fBTcl_GetStdChannel\fR and \fBTcl_SetStdChannel\fR. Additional public
@@ -51,9 +50,11 @@ Windows NT service.)
 A single standard channel is initialized when it is explicitly
 specified in a call to \fBTcl_SetStdChannel\fR.  The states of the
 other standard channels are unaffected.
-.sp
+.RS
+.PP
 Missing platform-specific standard channels do not matter here. This
 approach is not available at the script level.
+.RE
 .TP
 2)
 All uninitialized standard channels are initialized to
@@ -69,9 +70,7 @@ when information about any standard channel is requested with a call
 to \fBTcl_GetStdChannel\fR, or with a call to \fBTcl_GetChannel\fR
 which specifies one of the standard names (\fBstdin\fR, \fBstdout\fR
 and \fBstderr\fR).
-.RE
-.sp
-.RS
+.PP
 In case of missing platform-specific standard channels, the Tcl
 standard channels are considered as initialized and then immediately
 closed. This means that the first three Tcl channels then opened by
@@ -82,14 +81,13 @@ the application are designated as the Tcl standard channels.
 All uninitialized standard channels are initialized to
 platform-specific default values when a user-requested channel is
 registered with \fBTcl_RegisterChannel\fR.
-.sp
+.PP
 In case of unavailable platform-specific standard channels the channel
 whose creation caused the initialization of the Tcl standard channels
 is made a normal channel.  The next three Tcl channels opened by the
 application are designated as the Tcl standard channels.  In other
 words, of the first four Tcl channels opened by the application the
 second to fourth are designated as the Tcl standard channels.
-.PP
 .SH "RE-INITIALIZATION OF TCL STANDARD CHANNELS"
 .PP
 Once a Tcl standard channel is initialized through one of the methods
@@ -103,21 +101,20 @@ channel, too. If more than one Tcl standard channel was closed
 that slot was not initialized before. It is this behavior which
 enables an application to employ method 1 of initialization, i.e. to
 create and designate their own Tcl standard channels.
-
-.SH tclsh
+.SH "SHELL-SPECIFIC DETAILS"
+.SS tclsh
 .PP
-The Tcl shell (or rather \fBTcl_Main\fR) uses method 2 to initialize
+The Tcl shell (or rather the function \fBTcl_Main\fR, which forms the
+core of the shell's implementation) uses method 2 to initialize
 the standard channels.
-
-.SH wish
+.SS wish
 .PP
-The windowing shell (or rather \fBTk_MainEx\fR) uses method 1 to
+The windowing shell (or rather the function \fBTk_MainEx\fR, which
+forms the core of the shell's implementation) uses method 1 to
 initialize the standard channels (See \fBTk_InitConsoleChannels\fR)
 on non-Unix platforms.  On Unix platforms, \fBTk_MainEx\fR implicitly
 uses method 2 to initialize the standard channels.
-
 .SH "SEE ALSO"
 Tcl_CreateChannel(3), Tcl_RegisterChannel(3), Tcl_GetChannel(3), Tcl_GetStdChannel(3), Tcl_SetStdChannel(3), Tk_InitConsoleChannels(3), tclsh(1), wish(1), Tcl_Main(3), Tk_MainEx(3)
-
 .SH KEYWORDS
 standard channels
diff --git a/doc/clock.n b/doc/clock.n
index 745f0a0..0f85a7d 100644
--- a/doc/clock.n
+++ b/doc/clock.n
@@ -69,7 +69,7 @@ See \fBSCANNING TIMES\fR for a full description.
 .TP
 \fBclock seconds\fR 
 Returns the current time as an integer number of seconds.
-.SH "PARAMETERS"
+.SS "PARAMETERS"
 .TP
 \fIcount\fR
 An integer representing a count of some unit of time.  See
@@ -91,7 +91,7 @@ One of the words, \fBseconds\fR, \fBminutes\fR, \fBhours\fR,
 any unique prefix of such a word. Used in conjunction with \fIcount\fR
 to identify an interval of time, for example, \fI3 seconds\fR or
 \fI1 year\fR.
-.SH "OPTIONS"
+.SS "OPTIONS"
 .TP
 \fB-base\fR time
 Specifies that any relative times present in a \fBclock scan\fR command
@@ -191,7 +191,8 @@ the following code sets the value of \fBx\fR to \fB04:00:00\fR because
 the clock has changed in the interval in question.
 .CS
 set s [\fBclock scan\fR {2004-10-30 05:00:00} \\
-           -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York]
+           -format {%Y-%m-%d %H:%M:%S} \\
+           -timezone :America/New_York]
 set a [\fBclock add\fR $s 24 hours -timezone :America/New_York]
 set x [\fBclock format\fR $a \\
            -format {%H:%M:%S} -timezone :America/New_York]
@@ -210,7 +211,8 @@ results in the \fIsame local time\fR on the day in question.  For
 instance, the following code sets the value of \fBx\fR to \fB05:00:00\fR.
 .CS
 set s [\fBclock scan\fR {2004-10-30 05:00:00} \\
-           -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York]
+           -format {%Y-%m-%d %H:%M:%S} \\
+           -timezone :America/New_York]
 set a [\fBclock add\fR $s 1 day -timezone :America/New_York]
 set x [\fBclock format\fR $a \\
            -format {%H:%M:%S} -timezone :America/New_York]
@@ -224,7 +226,8 @@ as if the clock had not changed.  Thus, the following code
 will set the value of \fBx\fR to \fB03:30:00\fR.
 .CS
 set s [\fBclock scan\fR {2004-04-03 02:30:00} \\
-           -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York]
+           -format {%Y-%m-%d %H:%M:%S} \\
+           -timezone :America/New_York]
 set a [\fBclock add\fR $s 1 day -timezone :America/New_York]
 set x [\fBclock format\fR $a \\
            -format {%H:%M:%S} -timezone :America/New_York]
@@ -861,6 +864,8 @@ the day is produced after allowing for daylight savings time
 differences and the correct date is given when going from the end
 of a long month to a short month.
 .SH "SEE ALSO"
-msgcat
+msgcat(n)
+.SH KEYWORDS
+clock, date, time
 .SH "COPYRIGHT"
 Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
diff --git a/doc/exec.n b/doc/exec.n
index cd965b2..9acc4ef 100644
--- a/doc/exec.n
+++ b/doc/exec.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: exec.n,v 1.15 2006/12/04 23:13:20 dkf Exp $
+'\" RCS: @(#) $Id: exec.n,v 1.15.2.1 2007/07/04 15:13:42 dgp Exp $
 '\" 
 .so man.macros
 .TH exec n 8.5 Tcl "Tcl Built-In Commands"
@@ -185,7 +185,6 @@ If the name contains a slash then it must refer to an executable
 reachable from the current directory.
 No ``glob'' expansion or other shell-like substitutions
 are performed on the arguments to commands.
-
 .SH "PORTABILITY ISSUES"
 .TP
 \fBWindows\fR (all versions)
@@ -196,12 +195,13 @@ application will hang and a 32-bit application will return immediately with
 end-of-file.  When either type of application writes to a socket, the
 information is instead sent to the console, if one is present, or is
 discarded.
-.sp
+.RS
+.PP
 The Tk console text widget does not provide real standard IO capabilities.
 Under Tk, when redirecting from standard input, all applications will see an
 immediate end-of-file; information redirected to standard output or standard
 error will be discarded.  
-.sp
+.PP
 Either forward or backward slashes are accepted as path separators for
 arguments to Tcl commands.  When executing an application, the path name
 specified for the application may also contain forward or backward slashes
@@ -212,12 +212,12 @@ path name with forward slashes will not automatically be converted to use
 the backslash character.  If an argument contains forward slashes as the
 path separator, it may or may not be recognized as a path name, depending on
 the program.  
-.sp
+.PP
 Additionally, when calling a 16-bit DOS or Windows 3.X application, all path
 names must use the short, cryptic, path format (e.g., using ``applba~1.def''
 instead of ``applbakery.default''), which can be obtained with the
 \fBfile attributes $fileName -shortname\fR command.
-.sp
+.PP
 Two or more forward or backward slashes in a row in a path refer to a
 network path.  For example, a simple concatenation of the root directory
 \fBc:/\fR with a subdirectory \fB/windows/system\fR will yield
@@ -226,25 +226,29 @@ point called \fBsystem\fR on the machine called \fBwindows\fR (and the
 \fBc:/\fR is ignored), and is not equivalent to \fBc:/windows/system\fR,
 which describes a directory on the current computer.  The \fBfile join\fR
 command should be used to concatenate path components.
-.sp
-.RS
+.PP
 Note that there are two general types of Win32 console applications:
 .RS
-1) CLI -- CommandLine Interface, simple stdio exchange. \fBnetstat.exe\fR for
+.TP
+1) CLI
+.
+CommandLine Interface, simple stdio exchange. \fBnetstat.exe\fR for
 example.
-.br
-2) TUI -- Textmode User Interface, any application that accesses the console
+.TP
+2) TUI
+.
+Textmode User Interface, any application that accesses the console
 API for doing such things as cursor movement, setting text color, detecting
 key presses and mouse movement, etc.  An example would be \fBtelnet.exe\fR
 from Windows 2000.  These types of applications are not common in a windows
 environment, but do exist.
 .RE
+.PP
 \fBexec\fR will not work well with TUI applications when a console is not
 present, as is done when launching applications under wish.  It is desirable
 to have console applications hidden and detached.  This is a designed-in
 limitation as \fBexec\fR wants to communicate over pipes.  The Expect
 extension addresses this issue when communicating with a TUI application.
-.sp
 .RE
 .TP
 \fBWindows NT\fR
@@ -255,26 +259,23 @@ the name as it was specified.  Then, in order, \fB.com\fR, \fB.exe\fR, and
 for the longer name.  If a directory name was not specified as part of the
 application name, the following directories are automatically searched in
 order when attempting to locate the application:
-.sp
-.RS
 .RS
+.IP \(bu
 The directory from which the Tcl executable was loaded.
-.br
+.IP \(bu
 The current directory.
-.br
+.IP \(bu
 The Windows NT 32-bit system directory.
-.br
+.IP \(bu
 The Windows NT 16-bit system directory.
-.br
+.IP \(bu
 The Windows NT home directory.
-.br
+.IP \(bu
 The directories listed in the path.
-.RE
-.sp
+.PP
 In order to execute shell built-in commands like \fBdir\fR and \fBcopy\fR,
 the caller must prepend the desired command with ``\fBcmd.exe /c\0\fR''
 because built-in commands are not implemented using executables.
-.sp
 .RE
 .TP
 \fBWindows 9x\fR
@@ -285,31 +286,29 @@ the name as it was specified.  Then, in order, \fB.com\fR, \fB.exe\fR, and
 for the longer name.  If a directory name was not specified as part of the
 application name, the following directories are automatically searched in
 order when attempting to locate the application:
-.sp
-.RS
 .RS
+.IP \(bu
 The directory from which the Tcl executable was loaded.
-.br
+.IP \(bu
 The current directory.
-.br
+.IP \(bu
 The Windows 9x system directory.
-.br
+.IP \(bu
 The Windows 9x home directory.
-.br
+.IP \(bu
 The directories listed in the path.
-.RE
-.sp
+.PP
 In order to execute shell built-in commands like \fBdir\fR and \fBcopy\fR,
 the caller must prepend the desired command with ``\fBcommand.com /c\0\fR''
 because built-in commands are not implemented using executables.
-.sp
+.PP
 Once a 16-bit DOS application has read standard input from a console and 
 then quit, all subsequently run 16-bit DOS applications will see the 
 standard input as already closed.  32-bit applications do not have this
 problem and will run correctly, even after a 16-bit DOS application thinks 
 that standard input is closed.  There is no known workaround for this bug
 at this time.
-.sp
+.PP
 Redirection between the \fBNUL:\fR device and a 16-bit application does not
 always work.  When redirecting from \fBNUL:\fR, some applications may hang,
 others will get an infinite stream of ``0x01'' bytes, and some will actually
@@ -317,7 +316,7 @@ correctly get an immediate end-of-file; the behavior seems to depend upon
 something compiled into the application itself.  When redirecting greater than
 4K or so to \fBNUL:\fR, some applications will hang.  The above problems do not
 happen with 32-bit applications.  
-.sp
+.PP
 All DOS 16-bit applications are run synchronously.  All standard input from
 a pipe to a 16-bit DOS application is collected into a temporary file; the
 other end of the pipe must be closed before the 16-bit DOS application
@@ -327,7 +326,7 @@ must terminate before the temporary files are redirected to the next stage
 of the pipeline.  This is due to a workaround for a Windows 95 bug in the
 implementation of pipes, and is how the standard Windows 95 DOS shell
 handles pipes itself.
-.sp
+.PP
 Certain applications, such as \fBcommand.com\fR, should not be executed
 interactively.  Applications which directly access the console window,
 rather than reading from their standard input and writing to their standard
@@ -337,7 +336,6 @@ console window is not available to them.
 .TP
 \fBUnix\fR\0\0\0\0\0\0\0
 The \fBexec\fR command is fully functional and works as described.
-
 .SH "UNIX EXAMPLES"
 Here are some examples of the use of the \fBexec\fR command on Unix.
 .PP
@@ -379,7 +377,6 @@ this:
 .CS
 \fBexec\fR ls -l {*}[glob *.tcl]
 .CE
-.PP
 .SH "WINDOWS EXAMPLES"
 Here are some examples of the use of the \fBexec\fR command on Windows.
 .PP
@@ -419,9 +416,7 @@ the \fBglob\fR command.)  To do that, use this:
 .CS
 \fBexec\fR {*}[auto_execok dir] *.tcl
 .CE
-
 .SH "SEE ALSO"
 error(n), open(n)
-
 .SH KEYWORDS
 execute, pipeline, redirection, subprocess
diff --git a/doc/fconfigure.n b/doc/fconfigure.n
index 044b21e..63b65c6 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.17 2006/11/15 09:23:01 dkf Exp $
+'\" RCS: @(#) $Id: fconfigure.n,v 1.17.2.1 2007/07/04 15:13:42 dgp Exp $
 '\"
 .so man.macros
 .TH fconfigure n 8.3 Tcl "Tcl Built-In Commands"
@@ -168,8 +168,8 @@ No end-of-line translations are performed.  This is nearly identical to
 end-of-file character to the empty string (which disables it) and sets the
 encoding to \fBbinary\fR (which disables encoding filtering).  See the
 description of \fB\-eofchar\fR and \fB\-encoding\fR for more information.
-.PP
 .RS
+.PP
 Internally, i.e. when it comes to the actual behaviour of the
 translator this value \fBis\fR identical to \fBlf\fR and is therefore
 reported as such when queried. Even if \fBbinary\fR was used to set
diff --git a/doc/fcopy.n b/doc/fcopy.n
index 6513542..14f1cf5 100644
--- a/doc/fcopy.n
+++ b/doc/fcopy.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: fcopy.n,v 1.9 2007/01/29 16:51:38 dgp Exp $
+'\" RCS: @(#) $Id: fcopy.n,v 1.9.2.1 2007/07/04 15:13:42 dgp Exp $
 '\" 
 .so man.macros
 .TH fcopy n 8.0 Tcl "Tcl Built-In Commands"
@@ -132,15 +132,16 @@ proc CopyMore {in out chunk bytes {error {}}} {
 	close $in
 	close $out
     } else {
-	\fBfcopy\fR $in $out -command [list CopyMore $in $out $chunk] \\
-	    -size $chunk
+	\fBfcopy\fR $in $out -size $chunk \\
+                -command [list CopyMore $in $out $chunk]
     }
 }
 set in [open $file1]
 set out [socket $server $port]
 set chunk 1024
 set total 0
-\fBfcopy\fR $in $out -command [list CopyMore $in $out $chunk] -size $chunk
+\fBfcopy\fR $in $out -size $chunk \\
+        -command [list CopyMore $in $out $chunk]
 vwait done
 .DE
 
diff --git a/doc/file.n b/doc/file.n
index d8e4938..156812b 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.43 2007/04/05 14:08:40 dkf Exp $
+'\" RCS: @(#) $Id: file.n,v 1.43.2.1 2007/07/04 15:13:42 dgp Exp $
 '\" 
 .so man.macros
 .TH file n 8.3 Tcl "Tcl Built-In Commands"
@@ -427,8 +427,11 @@ Returns \fB1\fR if file \fIname\fR is writable by the current user,
 .TP
 \fBUnix\fR\0\0\0\0\0\0\0
 .
-These commands always operate using the real user and group identifiers,
-not the effective ones. 
+The subcommands that test whether a particular mode of access is permitted
+always operate using the real user and group identifiers, not the effective
+ones. As such, robust code should just \fBopen\fR a file for reading instead
+of testing to see whether it is readable with \fBfile readable\fR. This also
+avoids potential race conditions.
 .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
@@ -470,6 +473,5 @@ if {![\fBfile isdirectory\fR [\fBfile dirname\fR $newName]]} {
 .SH "SEE ALSO"
 chan(n), close(n), eof(n), fblocked(n), filename(n), flush(n), gets(n),
 open(n), seek(n), tell(n)
-
 .SH KEYWORDS
 attributes, copy files, delete files, directory, file, move files, name, rename files, stat
diff --git a/doc/filename.n b/doc/filename.n
index d7dda13..ef18249 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.14 2006/05/24 10:31:27 dkf Exp $
+'\" RCS: @(#) $Id: filename.n,v 1.14.6.1 2007/07/04 15:13:42 dgp Exp $
 '\" 
 .so man.macros
 .TH filename n 7.5 Tcl "Tcl Built-In Commands"
@@ -25,7 +25,6 @@ to be portable should not assume a particular form for file names.
 Instead, portable scripts must use the \fBfile split\fR and \fBfile
 join\fR commands to manipulate file names (see the \fBfile\fR manual
 entry for more details).
-
 .SH "PATH TYPES"
 .PP
 File names are grouped into three general types based on the starting point
@@ -38,13 +37,12 @@ qualified, either giving the path relative to the root directory on the
 current volume, or relative to the current directory of the specified
 volume.  The \fBfile pathtype\fR command can be used to determine the
 type of a given path.
-
 .SH "PATH SYNTAX"
 .PP
 The rules for native names depend on the value reported in the Tcl
 array element \fBtcl_platform(platform)\fR:
 .TP 10
-\fBunix\fR
+\fBUnix\fR
 On Unix and Apple MacOS X platforms, Tcl uses path names where the
 components are separated by slashes.  Path names may be relative or
 absolute, and file names may contain any character other than slash.
@@ -55,10 +53,10 @@ separator.  Any number of trailing slash characters at the end of a
 path are simply ignored, so the paths \fBfoo\fR, \fBfoo/\fR and
 \fBfoo//\fR are all identical, and in particular \fBfoo/\fR does not
 necessarily mean a directory is being referred.
+.RS
 .PP
 The following examples illustrate various forms of path
 names:
-.RS
 .TP 15
 \fB/\fR
 Absolute path to the root directory.
@@ -82,7 +80,7 @@ Relative path to the file \fBfoo\fR in the directory above the current
 directory. 
 .RE
 .TP
-\fBwindows\fR
+\fBWindows\fR
 On Microsoft Windows platforms, Tcl supports both drive-relative and UNC
 style names.  Both \fB/\fR and \fB\e\fR may be used as directory separators
 in either type of name.  Drive-relative names consist of an optional drive
@@ -122,7 +120,6 @@ Volume-relative path to a file \fBfoo\fR in the root directory of the current
 volume.  This is not a valid UNC path, so the assumption is that the
 extra backslashes are superfluous.
 .RE
-
 .SH "TILDE SUBSTITUTION"
 .PP
 In addition to the file name rules described above, Tcl also supports
@@ -143,7 +140,6 @@ file.  The behaviour of these paths when not trying to interpret them is
 the same as on Unix.  File names that have a tilde without a user name
 will be correctly substituted using the \fB$HOME\fR environment
 variable, just like for Unix.
-
 .SH "PORTABILITY ISSUES"
 .PP
 Not all file systems are case sensitive, so scripts should avoid code
@@ -172,6 +168,5 @@ illegal.
 .SH KEYWORDS
 current directory, absolute file name, relative file name,
 volume-relative file name, portability
-
 .SH "SEE ALSO"
 file(n), glob(n)
diff --git a/doc/http.n b/doc/http.n
index f316153..e1edd3e 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.24 2006/11/15 09:23:01 dkf Exp $
+'\" RCS: @(#) $Id: http.n,v 1.24.2.1 2007/07/04 15:13:42 dgp Exp $
 '\" 
 .so man.macros
 .TH "http" n 2.5 http "Tcl Bundled Packages"
@@ -179,10 +179,12 @@ of bytes read from the socket.  Here is a template for the callback:
 proc httpHandlerCallback {socket token} {
     upvar #0 $token state
     # Access socket, and state as a Tcl array
+    # For example...
     ...
-    (example: set data [read $socket 1000];set nbytes [string length $data])
+    set data [read $socket 1000]
+    set nbytes [string length $data]
     ...
-    return nbytes
+    return $nbytes
 }
 .CE
 .RE
diff --git a/doc/info.n b/doc/info.n
index 5b23525..18b3b4a 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.18 2006/11/28 22:20:27 andreas_kupries Exp $
+'\" RCS: @(#) $Id: info.n,v 1.18.2.1 2007/07/04 15:13:42 dgp Exp $
 '\" 
 .so man.macros
 .TH info n 8.4 Tcl "Tcl Built-In Commands"
@@ -82,7 +82,6 @@ into variable \fIvarname\fR.
 Returns \fB1\fR if the variable named \fIvarName\fR exists in the
 current context (either as a global or local variable) and has been
 defined by being given a value, returns \fB0\fR otherwise.
-
 .TP
 \fBinfo frame\fR ?\fInumber\fR?
 This command provides access to all frames on the stack, even those
@@ -116,17 +115,17 @@ for the command. The recognized values are \fBsource\fR, \fBproc\fR,
 \fBeval\fR, and \fBprecompiled\fR.
 .RS
 .TP
-\fBsource\fR
+\fBsource\fR\0\0\0\0\0\0\0\0
 means that the command is found in a script loaded by the \fBsource\fR
 command.
 .TP
-\fBproc\fR
+\fBproc\fR\0\0\0\0\0\0\0\0
 means that the command is found in dynamically created procedure body.
 .TP
-\fBeval\fR
+\fBeval\fR\0\0\0\0\0\0\0\0
 means that the command is executed by \fBeval\fR or \fBuplevel\fR.
 .TP
-\fBprecompiled\fR
+\fBprecompiled\fR\0\0\0\0\0\0\0\0
 means that the command is found in a precompiled script (loadable by
 the package \fBtbcload\fR), and no further information will be
 available.
@@ -163,28 +162,26 @@ definition of the lambda in question.
 This entry is present only if the queried frame has a corresponding
 frame returned by \fBinfo level\fR. It provides the index of this
 frame, relative to the current level (0 and negative numbers).
-.RE
-.sp
-.RS
+.PP
 A thing of note is that for procedures statically defined in files the
 locations of commands in their bodies will be reported with type
 \fBsource\fR and absolute line numbers, and not as type
 \fBproc\fR. The same is true for procedures nested in statically
 defined procedures, and literal eval scripts in files or statically
 defined procedures.
-.sp
+.PP
 In contrast, a procedure definition or \fBeval\fR within a dynamically
 \fBeval\fRuated environment count linenumbers relative to the start of
 their script, even if they would be able to count relative to the
 start of the outer dynamic script. That type of number usually makes
 more sense.
-.sp
+.PP
 A different way of describing this behaviour is that file based
 locations are tracked as deeply as possible, and where this is not
 possible the lines are counted based on the smallest possible
 \fBeval\fR or procedure body, as that scope is usually easier to find
 than any dynamic outer scope.
-.sp
+.PP
 The syntactic form \fB{expand}\fR is handled like \fBeval\fR. I.e. if it
 is given a literal list argument the system tracks the linenumber
 within the list words as well, and otherwise all linenumbers are
@@ -321,6 +318,7 @@ 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:
+.PP
 .CS
 proc printProc {procName} {
     set result [list proc $procName]
@@ -337,10 +335,8 @@ proc printProc {procName} {
     puts [lappend result $formals [\fBinfo body\fR $procName]]
 }
 .CE
-
 .SH "SEE ALSO"
 global(n), proc(n)
-
 .SH KEYWORDS
 command, information, interpreter, level, namespace, procedure, variable
 
diff --git a/doc/lsort.n b/doc/lsort.n
index 09962d2..1a4c1e7 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.21 2005/06/01 11:00:33 dkf Exp $
+'\" RCS: @(#) $Id: lsort.n,v 1.21.8.1 2007/07/04 15:13:43 dgp Exp $
 '\" 
 .so man.macros
 .TH lsort n 8.5 Tcl "Tcl Built-In Commands"
@@ -83,20 +83,26 @@ each sublist
 For example,
 .RS
 .CS
-lsort -integer -index 1 {{First 24} {Second 18} {Third 30}}
+lsort -integer -index 1 \\
+      {{First 24} {Second 18} {Third 30}}
 .CE
 returns \fB{Second 18} {First 24} {Third 30}\fR, and
 '\"
 '\" This example is from the test suite!
 '\"
 .CS
-lsort -index end-1 {{a 1 e i} {b 2 3 f g} {c 4 5 6 d h}}
+lsort -index end-1 \\
+      {{a 1 e i} {b 2 3 f g} {c 4 5 6 d h}}
 .CE
 returns \fB{c 4 5 6 d h} {a 1 e i} {b 2 3 f g}\fR,
 .VS 8.5
 and
 .CS
-lsort -index {0 1} {{{b i g} 12345} {{d e m o} 34512} {{c o d e} 54321}}
+lsort -index {0 1} {
+   {{b i g} 12345}
+   {{d e m o} 34512}
+   {{c o d e} 54321}
+}
 .CE
 returns \fB{{d e m o} 34512} {{b i g} 12345} {{c o d e} 54321}\fR
 (because \fBe\fR sorts before \fBi\fR which sorts before \fBo\fR.)
diff --git a/doc/registry.n b/doc/registry.n
index d1cb370..defb9a2 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.14 2005/05/10 18:34:03 kennykb Exp $
+'\" RCS: @(#) $Id: registry.n,v 1.14.8.1 2007/07/04 15:13:43 dgp Exp $
 '\" 
 .so man.macros
 .TH registry n 1.1 registry "Tcl Bundled Packages"
@@ -58,12 +58,22 @@ 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
 requiring a logoff/logon step (assumes admin privileges):
+.RS
+.PP
 .CS
-set regPath {HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment}
-set curPath [registry get $regPath "Path"]
-registry set $regPath "Path" "$curPath;$addPath"
-registry broadcast "Environment"
+set regPath [join {
+    HKEY_LOCAL_MACHINE
+    SYSTEM
+    CurrentControlSet
+    Control
+    {Session Manager}
+    Environment
+} "\\\\"]
+set curPath [\fBregistry get\fR $regPath "Path"]
+\fBregistry set\fR $regPath "Path" "$curPath;$addPath"
+\fBregistry broadcast\fR "Environment"
 .CE
+.RE
 .TP
 \fBregistry delete \fIkeyName\fR ?\fIvalueName\fR?
 .
@@ -111,7 +121,6 @@ If \fIpattern\fR isn't specified, returns a list of names of all the
 values of \fIkeyName\fR.  If \fIpattern\fR is specified, only those
 names matching \fIpattern\fR are returned.  Matching is determined
 using the same rules as for \fBstring\fR \fBmatch\fR.
-
 .SH "SUPPORTED TYPES"
 Each value under a key in the registry contains some data of a
 particular type in a type-specific representation.  The \fBregistry\fR
@@ -180,6 +189,7 @@ 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:
+.PP
 .CS
 package require registry
 set ext .tcl
@@ -193,6 +203,5 @@ set command [\fBregistry get\fR $path {}]
 
 puts "$ext opens with $command"
 .CE
-
 .SH KEYWORDS
 registry
diff --git a/doc/safe.n b/doc/safe.n
index acfb80d..3d9df3a 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.7 2004/09/06 09:44:57 dkf Exp $
+'\" RCS: @(#) $Id: safe.n,v 1.7.12.1 2007/07/04 15:13:44 dgp Exp $
 '\" 
 .so man.macros
 .TH "Safe Tcl" n 8.0 Tcl "Tcl Built-In Commands"
@@ -26,7 +26,7 @@ Safe\ Base \- A mechanism for creating and manipulating safe interpreters
 \fB::safe::interpFindInAccessPath\fR \fIslave\fR \fIdirectory\fR
 .sp
 \fB::safe::setLogCmd\fR ?\fIcmd arg...\fR?
-.SH OPTIONS
+.SS OPTIONS
 .PP
 ?\fB\-accessPath\fR \fIpathList\fR?
 ?\fB\-statics\fR \fIboolean\fR? ?\fB\-noStatics\fR?
@@ -63,8 +63,7 @@ Different levels of security can be selected by using the optional flags
 of the commands described below.
 .PP
 All commands provided in the master interpreter by the Safe Base reside in
-the \fBsafe\fR namespace:
-
+the \fBsafe\fR namespace.
 .SH COMMANDS
 The following commands are provided in the master interpreter:
 .TP
@@ -95,14 +94,17 @@ safe interpreter and change each and only the provided options.
 See the section on \fBOPTIONS\fR below for options description.
 Example of use:
 .RS
+.PP
 .CS
-# Create a new interp with the same configuration as "$i0" :
-set i1 [eval safe::interpCreate [safe::interpConfigure $i0]]
+# Create new interp with the same configuration as "$i0":
+set i1 [safe::interpCreate {*}[safe::interpConfigure $i0]]
+
 # Get the current deleteHook
 set dh [safe::interpConfigure $i0  \-del]
-# Change (only) the statics loading ok attribute of an interp
-# and its deleteHook (leaving the rest unchanged) :
-safe::interpConfigure $i0  \-delete {foo bar} \-statics 0 ;
+
+# Change (only) the statics loading ok attribute of an
+# interp and its deleteHook (leaving the rest unchanged):
+safe::interpConfigure $i0  \-delete {foo bar} \-statics 0
 .CE
 .RE
 .TP
@@ -119,8 +121,10 @@ This command finds and returns the token for the real directory
 It generates an error if the directory is not found.
 Example of use:
 .RS
+.PP
 .CS
-$slave eval [list set tk_library [::safe::interpFindInAccessPath $name $tk_library]]
+$slave eval [list set tk_library \\
+      [::safe::interpFindInAccessPath $name $tk_library]]
 .CE
 .RE
 .TP
@@ -132,8 +136,10 @@ If the directory is already in the virtual path, it only returns the token
 without adding the directory to the virtual path again.
 Example of use:
 .RS
+.PP
 .CS
-$slave eval [list set tk_library [::safe::interpAddToAccessPath $name $tk_library]]
+$slave eval [list set tk_library \\
+      [::safe::interpAddToAccessPath $name $tk_library]]
 .CE
 .RE
 .TP
@@ -153,13 +159,16 @@ and other events that might contain sensitive information such as real
 directory names.
 .RS
 Example of use:
+.PP
 .CS
 ::safe::setLogCmd puts stderr
 .CE
+.PP
 Below is the output of a sample session in which a safe interpreter
 attempted to source a file not found in its virtual access path.
 Note that the safe interpreter only received an error message saying that
 the file was not found:
+.PP
 .CS
 NOTICE for slave interp10 : Created
 NOTICE for slave interp10 : Setting accessPath=(/foo/bar) staticsok=1 nestedok=0 deletehook=()
@@ -167,8 +176,7 @@ NOTICE for slave interp10 : auto_path in interp10 has been set to {$p(:0:)}
 ERROR for slave interp10 : /foo/bar/init.tcl: no such file or directory
 .CE
 .RE
-
-.SH OPTIONS
+.SS OPTIONS
 The following options are common to 
 \fB::safe::interpCreate\fR, \fB::safe::interpInit\fR, 
 and \fB::safe::interpConfigure\fR.
@@ -254,7 +262,6 @@ the system encoding, but allows all other subcommands including
 \fBexit\fR
 The calling interpreter is deleted and its computation is stopped, but the
 Tcl process in which this interpreter exists is not terminated.
-
 .SH SECURITY
 The Safe Base does not attempt to completely prevent annoyance and
 denial of service attacks. These forms of attack prevent the
@@ -340,10 +347,8 @@ When the \fIaccessPath\fR is changed after the first creation or
 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.
-
 .SH "SEE ALSO"
 interp(n), library(n), load(n), package(n), source(n), unknown(n)
- 
 .SH KEYWORDS
 alias, auto\-loading, auto_mkindex, load, master interpreter, safe
 interpreter, slave interpreter, source
diff --git a/doc/tcltest.n b/doc/tcltest.n
index e177f1e..9605b76 100644
--- a/doc/tcltest.n
+++ b/doc/tcltest.n
@@ -8,7 +8,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: tcltest.n,v 1.47 2007/02/20 17:54:02 dgp Exp $
+'\" RCS: @(#) $Id: tcltest.n,v 1.47.2.1 2007/07/04 15:13:44 dgp Exp $
 '\" 
 .so man.macros
 .TH "tcltest" n 2.3 tcltest "Tcl Bundled Packages"
@@ -376,24 +376,27 @@ the expected result.  Some configuration options of \fBtcltest\fR
 also influence how [\fBtest\fR] operates.
 .PP
 The valid options for [\fBtest\fR] are summarized:
+.PP
 .CS
-.ta 0.8i
 \fBtest\fR \fIname\fR \fIdescription\fR
-	?-constraints \fIkeywordList|expression\fR?
-	?-setup \fIsetupScript\fR?
-	?-body \fItestScript\fR?
-	?-cleanup \fIcleanupScript\fR?
-	?-result \fIexpectedAnswer\fR?
-	?-output \fIexpectedOutput\fR?
-	?-errorOutput \fIexpectedError\fR?
-	?-returnCodes \fIcodeList\fR?
-	?-match \fImode\fR?
+        ?-constraints \fIkeywordList|expression\fR?
+        ?-setup \fIsetupScript\fR?
+        ?-body \fItestScript\fR?
+        ?-cleanup \fIcleanupScript\fR?
+        ?-result \fIexpectedAnswer\fR?
+        ?-output \fIexpectedOutput\fR?
+        ?-errorOutput \fIexpectedError\fR?
+        ?-returnCodes \fIcodeList\fR?
+        ?-match \fImode\fR?
 .CE
+.PP
 The \fIname\fR may be any string.  It is conventional to choose
 a \fIname\fR according to the pattern:
+.PP
 .CS
 \fItarget\fR-\fImajorNum\fR.\fIminorNum\fR
 .CE
+.PP
 For white-box (regression) tests, the target should be the name of the
 C function or Tcl procedure being tested.  For black-box tests, the
 target should be the name of the feature being tested.  Some conventions
@@ -662,11 +665,13 @@ when both options [\fBconfigure -constraints\fR] and
 only constraints from the [\fBconfigure -constraints\fR] list
 are run; all others are skipped.  For example, one might set
 up a configuration with
+.PP
 .CS
 \fBconfigure\fR -constraints knownBug \e
           -limitconstraints true \e
           -verbose pass
 .CE
+.PP
 to run exactly those tests that exercise known bugs, and discover
 whether any of them pass, indicating the bug had been fixed.  
 .SH "RUNNING ALL TESTS"
@@ -874,14 +879,19 @@ The fundamental element of a test suite is the individual [\fBtest\fR]
 command.  We begin with several examples.
 .IP [1]
 Test of a script that returns normally.
+.RS
+.PP
 .CS
 \fBtest\fR example-1.0 {normal return} {
     format %s value
 } value
 .CE
+.RE
 .IP [2]
 Test of a script that requires context setup and cleanup.  Note the
 bracing and indenting style that avoids any need for line continuation.
+.RS
+.PP
 .CS
 \fBtest\fR example-1.1 {test file existence} -setup {
     set file [makeFile {} test]
@@ -891,15 +901,21 @@ bracing and indenting style that avoids any need for line continuation.
     removeFile test
 } -result 1
 .CE
+.RE
 .IP [3]
 Test of a script that raises an error.
+.RS
+.PP
 .CS
 \fBtest\fR example-1.2 {error return} -body {
     error message
 } -returnCodes error -result message
 .CE
+.RE
 .IP [4]
 Test with a constraint.
+.RS
+.PP
 .CS
 \fBtest\fR example-1.3 {user owns created files} -constraints {
     unix
@@ -911,6 +927,7 @@ Test with a constraint.
     removeFile test
 } -result $::tcl_platform(user)
 .CE
+.RE
 .PP
 At the next higher layer of organization, several [\fBtest\fR] commands
 are gathered together into a single test file.  Test files should have
@@ -922,23 +939,32 @@ together, keeping tests synchronized with code changes.
 .PP 
 Most of the code in the test file should be the [\fBtest\fR] commands.
 Use constraints to skip tests, rather than conditional evaluation
-of [\fBtest\fR].  That is, do this:
+of [\fBtest\fR].
 .IP [5]
+Recommended system for writing conditional tests, using constraints to
+guard:
+.RS
+.PP
 .CS
 \fBtestConstraint\fR X [expr $myRequirement]
 \fBtest\fR goodConditionalTest {} X {
     # body
 } result
 .CE
-and do not do this:
+.RE
 .IP [6]
+Discouraged system for writing conditional tests, using \fBif\fR to
+guard:
+.RS
+.PP
 .CS
 if $myRequirement {
     test badConditionalTest {} {
-	#body
+        #body
     } result
 }
 .CE
+.RE
 .PP
 Use the \fB-setup\fR and \fB-cleanup\fR options to establish and release
 all context requirements of the test body.  Do not make tests depend on
@@ -967,6 +993,8 @@ After all [\fBtest\fR]s in a test file, the command [\fBcleanupTests\fR]
 should be called.
 .IP [7]
 Here is a sketch of a sample test file illustrating those points:
+.RS
+.PP
 .CS
 package require tcltest 2.2
 eval \fB::tcltest::configure\fR $argv
@@ -977,18 +1005,19 @@ namespace eval ::example::test {
     variable SETUP {#common setup code}
     variable CLEANUP {#common cleanup code}
     \fBtest\fR example-1 {} -setup $SETUP -body {
-	# First test
+        # First test
     } -cleanup $CLEANUP -result {...}
     \fBtest\fR example-2 {} -constraints X -setup $SETUP -body {
-	# Second test; constrained
+        # Second test; constrained
     } -cleanup $CLEANUP -result {...}
     \fBtest\fR example-3 {} {
-	# Third test; no context required
+        # Third test; no context required
     } {...}
     \fBcleanupTests\fR
 }
 namespace delete ::example::test
 .CE
+.RE
 .PP
 The next level of organization is a full test suite, made up of several
 test files.  One script is used to control the entire suite.  The
@@ -998,15 +1027,18 @@ because that's the default name used by [\fBrunAllTests\fR] when combining
 multiple test suites into one testing run.
 .IP [8]
 Here is a sketch of a sample test suite master script:
+.RS
+.PP
 .CS
 package require Tcl 8.4
 package require tcltest 2.2
 package require example
-\fB::tcltest::configure\fR -testdir \
+\fB::tcltest::configure\fR -testdir \\
         [file dirname [file normalize [info script]]]
 eval \fB::tcltest::configure\fR $argv
 \fB::tcltest::runAllTests\fR
 .CE
+.RE
 .SH COMPATIBILITY
 .PP
 A number of commands and variables in the \fB::tcltest\fR namespace
@@ -1022,15 +1054,18 @@ from the variable \fB::argv\fR.  This is to support test suites
 that depend on the old behavior that \fBtcltest\fR was automatically
 configured from command line arguments.  New test files should not
 depend on this, but should explicitly include
+.PP
 .CS
 eval \fB::tcltest::configure\fR $::argv
 .CE
+.PP
 to establish a configuration from command line arguments.
 .SH "KNOWN ISSUES"
 There are two known issues related to nested evaluations of [\fBtest\fR].  
 The first issue relates to the stack level in which test scripts are
 executed.  Tests nested within other tests may be executed at the same
 stack level as the outermost test.  For example, in the following code: 
+.PP
 .CS
 \fBtest\fR level-1.1 {level 1} {
     -body {
@@ -1039,6 +1074,7 @@ stack level as the outermost test.  For example, in the following code:
     }
 }
 .CE
+.PP
 any script executed in level-2.1 may be executed at the same stack
 level as the script defined for level-1.1.  
 .PP
@@ -1060,6 +1096,5 @@ directly from C applications will not be caught by the test command.
 Therefore, usage of the \fB-output\fR and \fB-errorOutput\fR
 options to [\fBtest\fR] is useful only for pure Tcl applications
 that use [\fB::puts\fR] to produce output. 
-
 .SH KEYWORDS
 test, test harness, test suite