Remove over-wide lines from nroff output.

7 files changed, 117 insertions, 56 deletions

diff --git a/doc/clock.n b/doc/clock.n
index 0493389..0f85a7d 100644
--- a/doc/clock.n
+++ b/doc/clock.n
@@ -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]
diff --git a/doc/fcopy.n b/doc/fcopy.n
index 6513542..77135b9 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.10 2007/07/04 14:45:19 dkf 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/http.n b/doc/http.n
index f316153..afe7253 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.25 2007/07/04 14:45:19 dkf 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/lsort.n b/doc/lsort.n
index 09962d2..5eda016 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.22 2007/07/04 14:45:19 dkf 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..a3e3489 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.15 2007/07/04 14:45:19 dkf 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..21ba5d2 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.8 2007/07/04 14:45:19 dkf 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..fb3a184 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.48 2007/07/04 14:45:19 dkf 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