Documentation improvements (small; some revision to parsing script) to improve

the quality of HTML doc builds.

34 files changed, 147 insertions, 110 deletions

diff --git a/doc/after.n b/doc/after.n
index 32d3f40..d6181c6 100644
--- a/doc/after.n
+++ b/doc/after.n
@@ -49,7 +49,7 @@ The command will be executed at global level (outside the context
 of any Tcl procedure).
 If an error occurs while executing the delayed command then 
 the background error will be reported by the command
-registered with \fB interp bgerror\fR.
+registered with \fBinterp bgerror\fR.
 The \fBafter\fR command returns an identifier that can be used
 to cancel the delayed command using \fBafter cancel\fR.
 .TP
@@ -82,7 +82,7 @@ The command returns an identifier that can be used
 to cancel the delayed command using \fBafter cancel\fR.
 If an error occurs while executing the script then the
 background error will be reported by the command
-registered with \fB interp bgerror\fR.
+registered with \fBinterp bgerror\fR.
 .TP
 \fBafter info \fR?\fIid\fR?
 .
diff --git a/doc/break.n b/doc/break.n
index 26b9a18..cef37c6 100644
--- a/doc/break.n
+++ b/doc/break.n
@@ -18,7 +18,7 @@ break \- Abort looping command
 .PP
 This command is typically invoked inside the body of a looping command
 such as \fBfor\fR or \fBforeach\fR or \fBwhile\fR.
-It returns a \fBTCL_BREAK\fR code, which causes a break exception
+It returns a 3 (\fBTCL_BREAK\fR) result code, which causes a break exception
 to occur.
 The exception causes the current script to be aborted
 out to the innermost containing loop command, which then
diff --git a/doc/catch.n b/doc/catch.n
index c4960fe..1da163d 100644
--- a/doc/catch.n
+++ b/doc/catch.n
@@ -78,13 +78,13 @@ the corresponding level; or it may be
 in which case the parameter is
 the relative level (as in \fBuplevel\fR) of the previous \fBCALL\fR. The
 salient differences wrt \fB\-errorinfo\fR are that:
-.IP (1)
+.IP [1]
 it is a machine-readable form that is amenable to processing with
 [\fBforeach\fR {tok prm} ...],
-.IP (2)
+.IP [2]
 it contains the true (substituted) values passed to the functions, instead of
 the static text of the calling sites, and
-.IP (3)
+.IP [3]
 it is coarser-grained, with only one element per stack frame (like procs; no
 separate elements for \fBforeach\fR constructs for example).
 .VE 8.6
diff --git a/doc/continue.n b/doc/continue.n
index e92e450..de2f07c 100644
--- a/doc/continue.n
+++ b/doc/continue.n
@@ -18,8 +18,8 @@ continue \- Skip to the next iteration of a loop
 .PP
 This command is typically invoked inside the body of a looping command
 such as \fBfor\fR or \fBforeach\fR or \fBwhile\fR.
-It returns a \fBTCL_CONTINUE\fR code, which causes a continue exception
-to occur.
+It returns a 4 (\fBTCL_CONTINUE\fR) result code, which causes a continue
+exception to occur.
 The exception causes the current script to be aborted
 out to the innermost containing loop command, which then
 continues with the next iteration of the loop.
diff --git a/doc/coroutine.n b/doc/coroutine.n
index 90674f7..f4b5d5b 100644
--- a/doc/coroutine.n
+++ b/doc/coroutine.n
@@ -111,7 +111,7 @@ for {set i 1} {$i <= 20} {incr i} {
 .SS "DETAILED SEMANTICS"
 .PP
 This example demonstrates that coroutines start from the global namespace, and
-that\fIcommand\fR resolution happens before the coroutine stack is created.
+that \fIcommand\fR resolution happens before the coroutine stack is created.
 .PP
 .CS
 proc report {where level} {
diff --git a/doc/error.n b/doc/error.n
index 31af917..d61bd7b 100644
--- a/doc/error.n
+++ b/doc/error.n
@@ -39,19 +39,19 @@ to return a stack trace reflecting the original point of occurrence
 of the error:
 .PP
 .CS
-\fBcatch {...} errMsg
+catch {...} errMsg
 set savedInfo $::errorInfo
 \&...
-error $errMsg $savedInfo\fR
+\fBerror\fR $errMsg $savedInfo
 .CE
 .PP
 When working with Tcl 8.5 or later, the following code
 should be used instead:
 .PP
 .CS
-\fBcatch {...} errMsg options
+catch {...} errMsg options
 \&...
-return -options $options $errMsg\fR
+return -options $options $errMsg
 .CE
 .PP
 If the \fIcode\fR argument is present, then its value is stored
@@ -73,3 +73,6 @@ if {1+2 != 3} {
 catch(n), return(n)
 .SH KEYWORDS
 error, exception
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/exec.n b/doc/exec.n
index 8dd213f..5072d61 100644
--- a/doc/exec.n
+++ b/doc/exec.n
@@ -239,7 +239,7 @@ names must use the short, cryptic, path format (e.g., using
 instead of
 .QW applbakery.default ),
 which can be obtained with the
-.QW "\fBfile attributes \fIfileName \fB\-shortname\fR"
+.QW "\fBfile attributes\fI fileName \fB\-shortname\fR"
 command.
 .PP
 Two or more forward or backward slashes in a row in a path refer to a
diff --git a/doc/expr.n b/doc/expr.n
index 46e6cf3..2ecd501 100644
--- a/doc/expr.n
+++ b/doc/expr.n
@@ -28,7 +28,7 @@ Expressions almost always yield numeric results
 For example, the expression
 .PP
 .CS
-\fBexpr 8.2 + 6\fR
+\fBexpr\fR 8.2 + 6
 .CE
 .PP
 evaluates to 14.2.
@@ -68,7 +68,8 @@ Operands may be specified in any of the following ways:
 .IP [1]
 As a numeric value, either integer or floating-point.
 .IP [2]
-As a boolean value, using any form understood by \fBstring is boolean\fR.
+As a boolean value, using any form understood by \fBstring is\fR
+\fBboolean\fR.
 .IP [3]
 As a Tcl variable, using standard \fB$\fR notation.
 The variable's value will be used as the operand.
@@ -225,7 +226,7 @@ just as in C, which means that operands are not evaluated if they are
 not needed to determine the outcome.  For example, in the command
 .PP
 .CS
-\fBexpr {$v ? [a] : [b]}\fR
+\fBexpr\fR {$v ? [a] : [b]}
 .CE
 .PP
 only one of
@@ -248,19 +249,19 @@ Tcl function in the \fBtcl::mathfunc\fR namespace.  The processing
 of an expression such as:
 .PP
 .CS
-\fBexpr {sin($x+$y)}\fR
+\fBexpr\fR {sin($x+$y)}
 .CE
 .PP
 is the same in every way as the processing of:
 .PP
 .CS
-\fBexpr {[tcl::mathfunc::sin [expr {$x+$y}]]}\fR
+\fBexpr\fR {[tcl::mathfunc::sin [\fBexpr\fR {$x+$y}]]}
 .CE
 .PP
 which in turn is the same as the processing of:
 .PP
 .CS
-\fBtcl::mathfunc::sin [expr {$x+$y}]\fR
+tcl::mathfunc::sin [\fBexpr\fR {$x+$y}]
 .CE
 .PP
 The executor will search for \fBtcl::mathfunc::sin\fR using the usual
@@ -335,8 +336,8 @@ is that produced by the \fB%g\fR format specifier of Tcl's
 \fBformat\fR command.  For example, the commands
 .PP
 .CS
-\fBexpr {"0x03" > "2"}\fR
-\fBexpr {"0y" < "0x12"}\fR
+\fBexpr\fR {"0x03" > "2"}
+\fBexpr\fR {"0y" < "0x12"}
 .CE
 .PP
 both return 1.  The first comparison is done using integer
@@ -358,9 +359,9 @@ once by the Tcl parser and once by the \fBexpr\fR command.
 For example, the commands
 .PP
 .CS
-\fBset a 3\fR
-\fBset b {$a + 2}\fR
-\fBexpr $b*4\fR
+set a 3
+set b {$a + 2}
+\fBexpr\fR $b*4
 .CE
 .PP
 return 11, not a multiple of 4.
@@ -444,3 +445,6 @@ Copyright (c) 1993 The Regents of the University of California.
 Copyright (c) 1994-2000 Sun Microsystems Incorporated.
 Copyright (c) 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
 .fi
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/file.n b/doc/file.n
index 7874807..9205d3b 100644
--- a/doc/file.n
+++ b/doc/file.n
@@ -138,7 +138,7 @@ returned.  For example,
 .RS
 .PP
 .CS
-\fBfile dirname c:/\fR
+\fBfile dirname\fR c:/
 .CE
 .PP
 returns \fBc:/\fR. 
@@ -147,13 +147,13 @@ Note that tilde substitution will only be
 performed if it is necessary to complete the command. For example,
 .PP
 .CS
-\fBfile dirname ~/src/foo.c\fR
+\fBfile dirname\fR ~/src/foo.c
 .CE
 .PP
 returns \fB~/src\fR, whereas
 .PP
 .CS
-\fBfile dirname ~\fR
+\fBfile dirname\fR ~
 .CE
 .PP
 returns \fB/home\fR (or something similar).
@@ -193,7 +193,7 @@ proceed from the current argument.  For example,
 .RS
 .PP
 .CS
-\fBfile join a b /foo bar\fR
+\fBfile join\fR a b /foo bar
 .CE
 .PP
 returns \fB/foo/bar\fR.
@@ -380,7 +380,7 @@ For example, under Unix
 .RS
 .PP
 .CS
-file split /foo/~bar/baz
+\fBfile split\fR /foo/~bar/baz
 .CE
 .PP
 returns
diff --git a/doc/fileevent.n b/doc/fileevent.n
index 7a3d2f7..df48d2a 100644
--- a/doc/fileevent.n
+++ b/doc/fileevent.n
@@ -123,7 +123,7 @@ proc GetData {chan} {
 }
 
 fconfigure $chan -blocking 0 -encoding binary
-fileevent $chan readable [list GetData $chan]
+\fBfileevent\fR $chan readable [list GetData $chan]
 .CE
 .PP
 The next example demonstrates use of \fBgets\fR to read line-oriented
@@ -140,7 +140,7 @@ proc GetData {chan} {
 }
 
 fconfigure $chan -blocking 0 -buffering line -translation crlf
-fileevent $chan readable [list GetData $chan]
+\fBfileevent\fR $chan readable [list GetData $chan]
 .CE
 .SH CREDITS
 .PP
diff --git a/doc/filename.n b/doc/filename.n
index 1fe22f0..d481fc9 100644
--- a/doc/filename.n
+++ b/doc/filename.n
@@ -38,7 +38,7 @@ 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:
+\fBplatform\fR element of the \fBtcl_platform\fR array:
 .TP 10
 \fBUnix\fR
 On Unix and Apple MacOS X platforms, Tcl uses path names where the
diff --git a/doc/format.n b/doc/format.n
index 422e389..23dfe60 100644
--- a/doc/format.n
+++ b/doc/format.n
@@ -141,7 +141,8 @@ function of the \fBexpr\fR command (at least a 64-bit range).
 If neither \fBh\fR nor \fBl\fR are present, the integer value is
 truncated to the same range as that produced by the \fBint()\fR
 function of the \fBexpr\fR command (at least a 32-bit range, but
-determined by the value of \fBtcl_platform(wordSize)\fR).
+determined by the value of the \fBwordSize\fR element of the
+\fBtcl_platform\fR array).
 .SS "MANDATORY CONVERSION TYPE"
 .PP
 The last thing in a conversion specifier is an alphabetic character
diff --git a/doc/glob.n b/doc/glob.n
index 2cff41e..7b71189 100644
--- a/doc/glob.n
+++ b/doc/glob.n
@@ -230,9 +230,9 @@ and will not be
 interpreted as a wildcard character. One solution to this problem is
 to use the Unix style forward slash as a path separator. Windows style
 paths can be converted to Unix style paths with the command
-.QW "\fBfile join $path\fR"
+.QW "\fBfile join\fR \fB$path\fR"
 or
-.QW "\fBfile normalize $path\fR" .
+.QW "\fBfile normalize\fR \fB$path\fR" .
 .SH EXAMPLES
 .PP
 Find all the Tcl files in the current directory:
diff --git a/doc/info.n b/doc/info.n
index cb5c6e6..0001ae9 100644
--- a/doc/info.n
+++ b/doc/info.n
@@ -507,8 +507,8 @@ class named \fIclass\fR.
 .VS 8.6
 This subcommand returns a list of direct subclasses of class \fIclass\fR. If
 the optional \fIpattern\fR argument is present, it constrains the list of
-returned classes to those that match it according to the rules of \fBstring
-match\fR.
+returned classes to those that match it according to the rules of
+\fBstring match\fR.
 .VE 8.6
 .TP
 \fBinfo class superclasses\fI class\fR
diff --git a/doc/interp.n b/doc/interp.n
index 2cc082b..02421e1 100644
--- a/doc/interp.n
+++ b/doc/interp.n
@@ -61,10 +61,18 @@ on how the alias mechanism works.
 A qualified interpreter name is a proper Tcl lists containing a subset of its
 ancestors in the interpreter hierarchy, terminated by the string naming the
 interpreter in its immediate master. Interpreter names are relative to the
-interpreter in which they are used. For example, if \fBa\fR is a slave of
-the current interpreter and it has a slave \fBa1\fR, which in turn has a
-slave \fBa11\fR, the qualified name of \fBa11\fR in \fBa\fR is the list
-\fBa1 a11\fR.
+interpreter in which they are used. For example, if
+.QW \fBa\fR
+is a slave of the current interpreter and it has a slave
+.QW \fBa1\fR ,
+which in turn has a slave
+.QW \fBa11\fR ,
+the qualified name of
+.QW \fBa11\fR
+in
+.QW \fBa\fR
+is the list
+.QW "\fBa1 a11\fR" .
 .PP
 The \fBinterp\fR command, described below, accepts qualified interpreter
 names as arguments; the interpreter in which the command is being evaluated
@@ -108,10 +116,12 @@ invoking the command.
 interpreter.  For example,
 .QW "\fBa b\fR"
 identifies an interpreter
-\fBb\fR, which is a slave of interpreter \fBa\fR, which is a slave
-of the invoking interpreter.  An empty list specifies the interpreter
-invoking the command.  \fIsrcCmd\fR gives the name of a new
-command, which will be created in the source interpreter.
+.QW \fBb\fR ,
+which is a slave of interpreter
+.QW \fBa\fR ,
+which is a slave of the invoking interpreter.  An empty list specifies
+the interpreter invoking the command.  \fIsrcCmd\fR gives the name of
+a new command, which will be created in the source interpreter.
 \fITargetPath\fR and \fItargetCmd\fR specify a target interpreter
 and command, and the \fIarg\fR arguments, if any, specify additional
 arguments to \fItargetCmd\fR which are prepended to any arguments specified
@@ -194,8 +204,8 @@ and the current setting is returned.
 This only effects the output of \fBinfo frame\fR, in that exact
 frame-level information for command invocation at the bytecode level
 is only captured with this setting on.
-.PP
 .RS
+.PP
 For example, with code like
 .PP
 .CS
@@ -332,7 +342,7 @@ already trusted.
 Returns the maximum allowable nesting depth for the interpreter
 specified by \fIpath\fR.  If \fInewlimit\fR is specified,
 the interpreter recursion limit will be set so that nesting
-of more than \fInewlimit\fR calls to \fBTcl_Eval()\fR
+of more than \fInewlimit\fR calls to \fBTcl_Eval\fR
 and related procedures in that interpreter will return an error.
 The \fInewlimit\fR value is also returned.
 The \fInewlimit\fR value must be a positive integer between 1 and the
diff --git a/doc/lassign.n b/doc/lassign.n
index f09acfc..6f5042b 100644
--- a/doc/lassign.n
+++ b/doc/lassign.n
@@ -28,17 +28,17 @@ An illustration of how multiple assignment works, and what happens
 when there are either too few or too many elements.
 .PP
 .CS
-lassign {a b c} x y z       ;# Empty return
+\fBlassign\fR {a b c} x y z       ;# Empty return
 puts $x                     ;# Prints "a"
 puts $y                     ;# Prints "b"
 puts $z                     ;# Prints "c"
 
-lassign {d e} x y z         ;# Empty return
+\fBlassign\fR {d e} x y z         ;# Empty return
 puts $x                     ;# Prints "d"
 puts $y                     ;# Prints "e"
 puts $z                     ;# Prints ""
 
-lassign {f g h i} x y       ;# Returns "h i"
+\fBlassign\fR {f g h i} x y       ;# Returns "h i"
 puts $x                     ;# Prints "f"
 puts $y                     ;# Prints "g"
 .CE
@@ -49,10 +49,10 @@ the analogue of the
 command in many shell languages like this:
 .PP
 .CS
-set ::argv [lassign $::argv argumentToReadOff]
+set ::argv [\fBlassign\fR $::argv argumentToReadOff]
 .CE
 .SH "SEE ALSO"
-lindex(n), list(n), lset(n), set(n)
+lindex(n), list(n), lrange(n), lset(n), set(n)
 .SH KEYWORDS
 assign, element, list, multiple, set, variable
 '\"Local Variables:
diff --git a/doc/lindex.n b/doc/lindex.n
index 537b09b..bb272a6 100644
--- a/doc/lindex.n
+++ b/doc/lindex.n
@@ -26,13 +26,13 @@ Tcl list and presented as a single argument.
 If no indices are presented, the command takes the form:
 .PP
 .CS
-lindex list
+\fBlindex \fIlist\fR
 .CE
 .PP
 or
 .PP
 .CS
-lindex list {}
+\fBlindex \fIlist\fR {}
 .CE
 .PP
 In this case, the return value of \fBlindex\fR is simply the value of the
@@ -57,19 +57,19 @@ used in turn to select an element from the previous indexing operation,
 allowing the script to select elements from sublists.  The command,
 .PP
 .CS
-lindex $a 1 2 3
+\fBlindex\fR $a 1 2 3
 .CE
 .PP
 or
 .PP
 .CS
-lindex $a {1 2 3}
+\fBlindex\fR $a {1 2 3}
 .CE
 .PP
 is synonymous with
 .PP
 .CS
-lindex [lindex [lindex $a 1] 2] 3
+\fBlindex\fR [\fBlindex\fR [\fBlindex\fR $a 1] 2] 3
 .CE
 .SH EXAMPLES
 .PP
diff --git a/doc/lset.n b/doc/lset.n
index ec84e09..805de16 100755
--- a/doc/lset.n
+++ b/doc/lset.n
@@ -26,13 +26,13 @@ Finally, it accepts a new value for an element of \fIvarName\fR.
 If no indices are presented, the command takes the form:
 .PP
 .CS
-lset varName newValue
+\fBlset\fR varName newValue
 .CE
 .PP
 or
 .PP
 .CS
-lset varName {} newValue
+\fBlset\fR varName {} newValue
 .CE
 .PP
 In this case, \fInewValue\fR replaces the old value of the variable
@@ -68,13 +68,13 @@ allowing the script to alter elements in sublists (or append elements
 to sublists).  The command,
 .PP
 .CS
-lset a 1 2 newValue
+\fBlset\fR a 1 2 newValue
 .CE
 .PP
 or
 .PP
 .CS
-lset a {1 2} newValue
+\fBlset\fR a {1 2} newValue
 .CE
 .PP
 replaces element 2 of sublist 1 with \fInewValue\fR.
diff --git a/doc/lsort.n b/doc/lsort.n
index 10b8162..8e85f5a 100644
--- a/doc/lsort.n
+++ b/doc/lsort.n
@@ -88,7 +88,7 @@ For example,
 .RS
 .PP
 .CS
-lsort -integer -index 1 \e
+\fBlsort\fR -integer -index 1 \e
       {{First 24} {Second 18} {Third 30}}
 .CE
 .PP
@@ -98,7 +98,7 @@ returns \fB{Second 18} {First 24} {Third 30}\fR,
 '\" This example is from the test suite!
 '\"
 .CS
-lsort -index end-1 \e
+\fBlsort\fR -index end-1 \e
         {{a 1 e i} {b 2 3 f g} {c 4 5 6 d h}}
 .CE
 .PP
@@ -106,7 +106,7 @@ returns \fB{c 4 5 6 d h} {a 1 e i} {b 2 3 f g}\fR,
 and
 .PP
 .CS
-lsort -index {0 1} {
+\fBlsort\fR -index {0 1} {
     {{b i g} 12345}
     {{d e m o} 34512}
     {{c o d e} 54321}
@@ -135,7 +135,7 @@ in turn must be at least 2.
 For example,
 .PP
 .CS
-lsort \-stride 2 {carrot 10 apple 50 banana 25}
+\fBlsort\fR \-stride 2 {carrot 10 apple 50 banana 25}
 .CE
 .PP
 returns
@@ -143,7 +143,7 @@ returns
 and
 .PP
 .CS
-lsort \-stride 2 \-index 1 \-integer {carrot 10 apple 50 banana 25}
+\fBlsort\fR \-stride 2 \-index 1 \-integer {carrot 10 apple 50 banana 25}
 .CE
 .PP
 returns
diff --git a/doc/mathfunc.n b/doc/mathfunc.n
index 0977220..3da6d5a 100644
--- a/doc/mathfunc.n
+++ b/doc/mathfunc.n
@@ -195,16 +195,19 @@ Returns the floating-point remainder of the division of \fIx\fR by
 .TP
 \fBhypot \fIx y\fR
 .
-Computes the length of the hypotenuse of a right-angled triangle
-.QW "\fBsqrt\fR [\fBexpr\fR {\fIx\fB*\fIx\fB+\fIy\fB*\fIy\fR}]".
+Computes the length of the hypotenuse of a right-angled triangle,
+approximately
+.QW "\fBsqrt\fR [\fBexpr\fR {\fIx\fB*\fIx\fB+\fIy\fB*\fIy\fR}]"
+except for being more numerically stable when the two arguments have
+substantially different magnitudes.
 .TP
 \fBint \fIarg\fR
 .
 The argument may be any numeric value.  The integer part of \fIarg\fR
 is determined, and then the low order bits of that integer value up
 to the machine word size are returned as an integer value.  For reference,
-the number of bytes in the machine word are stored in
-\fBtcl_platform(wordSize)\fR.
+the number of bytes in the machine word are stored in the \fBwordSize\fR
+element of the \fBtcl_platform\fR array.
 .TP
 \fBisqrt \fIarg\fR
 .
diff --git a/doc/next.n b/doc/next.n
index 222d8b3..8eb2ba6 100644
--- a/doc/next.n
+++ b/doc/next.n
@@ -34,7 +34,7 @@ chain.
 .PP
 The \fBnextto\fR command is the same as the \fBnext\fR command, except that it
 takes an additional \fIclass\fR argument that identifies a class whose
-implementation of the current method chain (see \fBinfo object call\fR) should
+implementation of the current method chain (see \fBinfo object\fR \fBcall\fR) should
 be used; the method implementation selected will be the one provided by the
 given class, and it must refer to an existing non-filter invocation that lies
 further along the chain than the current implementation.
diff --git a/doc/open.n b/doc/open.n
index fd12962..d4842f2 100644
--- a/doc/open.n
+++ b/doc/open.n
@@ -67,8 +67,8 @@ Set the initial access position  to the end of the file.
 .PP
 All of the legal \fIaccess\fR values above may have the character
 \fBb\fR added as the second or third character in the value to
-indicate that the opened channel should be configured with the
-\fB\-translation binary\fR option, making the channel suitable for 
+indicate that the opened channel should be configured as if with the
+\fBfconfigure\fR \fB\-translation binary\fR option, making the channel suitable for 
 reading or writing of binary data.
 .PP
 In the second form, \fIaccess\fR consists of a list of any of the
@@ -131,7 +131,7 @@ conjunction with the process's file mode creation mask.
 .SH "COMMAND PIPELINES"
 .PP
 If the first character of \fIfileName\fR is
-.QW |
+.QW \fB|\fR
 then the
 remaining characters of \fIfileName\fR are treated as a list of arguments
 that describe a command pipeline to invoke, in the same style as the
@@ -139,10 +139,12 @@ arguments for \fBexec\fR.
 In this case, the channel identifier returned by \fBopen\fR may be used
 to write to the command's input pipe or read from its output pipe,
 depending on the value of \fIaccess\fR.
-If write-only access is used (e.g. \fIaccess\fR is \fBw\fR), then
-standard output for the pipeline is directed to the current standard
+If write-only access is used (e.g. \fIaccess\fR is
+.QW \fBw\fR ),
+then standard output for the pipeline is directed to the current standard
 output unless overridden by the command.
-If read-only access is used (e.g. \fIaccess\fR is \fBr\fR),
+If read-only access is used (e.g. \fIaccess\fR is
+.QW \fBr\fR ),
 standard input for the pipeline is taken from the current standard
 input unless overridden by the command.
 The id of the spawned process is accessible through the \fBpid\fR
@@ -271,7 +273,7 @@ in the second form both input and output buffers are defined.
 (Windows only). This option is query only.
 In case of a serial communication error, \fBread\fR or \fBputs\fR
 returns a general Tcl file I/O error.
-\fBfconfigure -lasterror\fR can be called to get a list of error details.
+\fBfconfigure\fR \fB\-lasterror\fR can be called to get a list of error details.
 See below for an explanation of the various error codes.
 .SH "SERIAL PORT SIGNALS"
 .PP
@@ -283,29 +285,29 @@ lines and handshaking. Here we are using the terms \fIworkstation\fR for
 your computer and \fImodem\fR for the external device, because some signal
 names (DCD, RI) come from modems. Of course your external device may use
 these signal lines for other purposes.
-.IP \fBTXD(output)\fR
+.IP \fBTXD\fR(output)
 \fBTransmitted Data:\fR Outgoing serial data.
-.IP \fBRXD(input)\fR
+.IP \fBRXD\fR(input)
 \fBReceived Data:\fRIncoming serial data.
-.IP \fBRTS(output)\fR
+.IP \fBRTS\fR(output)
 \fBRequest To Send:\fR This hardware handshake line informs the modem that
 your workstation is ready to receive data. Your workstation may
 automatically reset this signal to indicate that the input buffer is full.
-.IP \fBCTS(input)\fR
+.IP \fBCTS\fR(input)
 \fBClear To Send:\fR The complement to RTS. Indicates that the modem is
 ready to receive data.
-.IP \fBDTR(output)\fR
+.IP \fBDTR\fR(output)
 \fBData Terminal Ready:\fR This signal tells the modem that the workstation
 is ready to establish a link. DTR is often enabled automatically whenever a
 serial port is opened.
-.IP \fBDSR(input)\fR
+.IP \fBDSR\fR(input)
 \fBData Set Ready:\fR The complement to DTR. Tells the workstation that the
 modem is ready to establish a link.
-.IP \fBDCD(input)\fR
+.IP \fBDCD\fR(input)
 \fBData Carrier Detect:\fR This line becomes active when a modem detects a
 .QW Carrier
 signal.
-.IP \fBRI(input)\fR
+.IP \fBRI\fR(input)
 \fBRing Indicator:\fR Goes active when the modem detects an incoming call.
 .IP \fBBREAK\fR
 A BREAK condition is not a hardware signal line, but a logical zero on the
@@ -321,13 +323,13 @@ event polling in background. The external device may have been switched
 off, the data lines may be noisy, system buffers may overrun or your mode
 settings may be wrong.  That is why a reliable software should always
 \fBcatch\fR serial read operations.  In cases of an error Tcl returns a
-general file I/O error.  Then \fBfconfigure -lasterror\fR may help to
+general file I/O error.  Then \fBfconfigure\fR \fB\-lasterror\fR may help to
 locate the problem.  The following error codes may be returned.
 .TP 10
 \fBRXOVER\fR
 .
 Windows input buffer overrun. The data comes faster than your scripts reads
-it or your system is overloaded. Use \fBfconfigure -sysbuffer\fR to avoid a
+it or your system is overloaded. Use \fBfconfigure\fR \fB\-sysbuffer\fR to avoid a
 temporary bottleneck and/or make your script faster.
 .TP 10
 \fBTXFULL\fR
@@ -345,13 +347,13 @@ and/or setup a lower(1) interrupt threshold value.
 \fBRXPARITY\fR
 .
 A parity error has been detected by your UART.
-Wrong parity settings with \fBfconfigure -mode\fR or a noisy data line (RXD)
+Wrong parity settings with \fBfconfigure\fR \fB\-mode\fR or a noisy data line (RXD)
 may cause this error.
 .TP 10
 \fBFRAME\fR
 .
 A stop-bit error has been detected by your UART.
-Wrong mode settings with \fBfconfigure -mode\fR or a noisy data line (RXD)
+Wrong mode settings with \fBfconfigure\fR \fB\-mode\fR or a noisy data line (RXD)
 may cause this error.
 .TP 10
 \fBBREAK\fR
@@ -458,3 +460,6 @@ puts(n), exec(n), pid(n), fopen(3)
 .SH KEYWORDS
 access mode, append, create, file, non-blocking, open, permissions,
 pipeline, process, serial
+'\"Local Variables:
+'\"mode: nroff
+'\"End:
diff --git a/doc/package.n b/doc/package.n
index c59b645..6cf8991 100644
--- a/doc/package.n
+++ b/doc/package.n
@@ -12,7 +12,7 @@
 package \- Facilities for package loading and version control
 .SH SYNOPSIS
 .nf
-\fBpackage forget ?\fIpackage package ...\fR?
+\fBpackage forget\fR ?\fIpackage package ...\fR?
 \fBpackage ifneeded \fIpackage version\fR ?\fIscript\fR?
 \fBpackage names\fR
 \fBpackage present \fIpackage \fR?\fIrequirement...\fR?
@@ -43,7 +43,7 @@ primarily by system scripts that maintain the package database.
 The behavior of the \fBpackage\fR command is determined by its first argument.
 The following forms are permitted:
 .TP
-\fBpackage forget ?\fIpackage package ...\fR?
+\fBpackage forget\fR ?\fIpackage package ...\fR?
 .
 Removes all information about each specified package from this interpreter,
 including information provided by both \fBpackage ifneeded\fR and
@@ -175,7 +175,7 @@ If \fIcommand\fR is specified as an empty string, then the current
 .
 Compares the two version numbers given by \fIversion1\fR and \fIversion2\fR.
 Returns -1 if \fIversion1\fR is an earlier version than \fIversion2\fR,
-0 if they are equal, and 1 if \fIversion1\fR is later than \fBversion2\fR.
+0 if they are equal, and 1 if \fIversion1\fR is later than \fIversion2\fR.
 .TP
 \fBpackage versions \fIpackage\fR
 .
diff --git a/doc/pkgMkIndex.n b/doc/pkgMkIndex.n
index 93a5f79..07370ef 100644
--- a/doc/pkgMkIndex.n
+++ b/doc/pkgMkIndex.n
@@ -12,7 +12,7 @@
 pkg_mkIndex \- Build an index for automatic loading of packages
 .SH SYNOPSIS
 .nf
-\fBpkg_mkIndex ?\fIoptions...\fR? \fIdir\fR ?\fIpattern pattern ...\fR?
+\fBpkg_mkIndex\fR ?\fIoptions...\fR? \fIdir\fR ?\fIpattern pattern ...\fR?
 .fi
 .BE
 .SH DESCRIPTION
@@ -228,3 +228,6 @@ the binary file may mask the package defined by the scripts.
 package(n)
 .SH KEYWORDS
 auto-load, index, package, version
+'\"Local Variables:
+'\"mode: nroff
+'\"End:
diff --git a/doc/read.n b/doc/read.n
index a64e079..007c0ac 100644
--- a/doc/read.n
+++ b/doc/read.n
@@ -54,7 +54,7 @@ which \fBfconfigure\fR will alter input.
 '\" Note:  this advice actually applies to many versions of Tcl
 .PP
 For most applications a channel connected to a serial port should be
-configured to be nonblocking: \fBfconfigure \fIchannelId \fB\-blocking
+configured to be nonblocking: \fBfconfigure\fI channelId \fB\-blocking
 \fI0\fR.  Then \fBread\fR behaves much like described above.  Care
 must be taken when using \fBread\fR on blocking serial ports:
 .TP
@@ -66,7 +66,7 @@ from the serial port.
 \fBread \fIchannelId\fR 
 .
 In this form \fBread\fR blocks until the reception of the end-of-file
-character, see \fBfconfigure -eofchar\fR. If there no end-of-file
+character, see \fBfconfigure\fR \fB\-eofchar\fR. If there no end-of-file
 character has been configured for the channel, then \fBread\fR will
 block forever.
 .SH "EXAMPLE"
@@ -84,3 +84,6 @@ set lines [split $data \en]
 file(n), eof(n), fblocked(n), fconfigure(n), Tcl_StandardChannels(3)
 .SH KEYWORDS
 blocking, channel, end of line, end of file, nonblocking, read, translation, encoding
+'\"Local Variables:
+'\"mode: nroff
+'\"End:
diff --git a/doc/refchan.n b/doc/refchan.n
index c4066b6..a51c3d7 100644
--- a/doc/refchan.n
+++ b/doc/refchan.n
@@ -17,10 +17,10 @@ refchan \- command handler API of reflected channels
 .PP
 The Tcl-level handler for a reflected channel has to be a command with
 subcommands (termed an \fIensemble\fR, as it is a command such as that
-created by \fBnamespace ensemble create\fR, though the implementation
+created by \fBnamespace ensemble\fR \fBcreate\fR, though the implementation
 of handlers for reflected channel \fIis not\fR tied to \fBnamespace
-ensemble\fRs in any way; see \fBEXAMPLE\fR below for how to build a
-\fBclass\fR that supports the API). Note that \fIcmdPrefix\fR is whatever was
+ensemble\fRs in any way; see \fBEXAMPLE\fR below for how to build an
+\fBoo::class\fR that supports the API). Note that \fIcmdPrefix\fR is whatever was
 specified in the call to \fBchan create\fR, and may consist of
 multiple arguments; this will be expanded to multiple words in place
 of the prefix.
diff --git a/doc/registry.n b/doc/registry.n
index b9b36d1..2e69b1e 100644
--- a/doc/registry.n
+++ b/doc/registry.n
@@ -103,7 +103,7 @@ data, see \fBSUPPORTED TYPES\fR, below.
 If \fIpattern\fR is not specified, returns a list of names of all the
 subkeys 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.  If the
+using the same rules as for \fBstring match\fR.  If the
 specified \fIkeyName\fR does not exist, then an error is generated.
 .TP
 \fBregistry set \fIkeyName\fR ?\fIvalueName data \fR?\fItype\fR??
@@ -127,7 +127,7 @@ Returns the type of the value \fIvalueName\fR in the key
 If \fIpattern\fR is not 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.
+using the same rules as for \fBstring match\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
diff --git a/doc/return.n b/doc/return.n
index 6bfa346..b59a93d 100644
--- a/doc/return.n
+++ b/doc/return.n
@@ -317,7 +317,8 @@ proc myReturn {args} {
 }
 .CE
 .SH "SEE ALSO"
-break(n), catch(n), continue(n), dict(n), error(n), proc(n), source(n), tclvars(n)
+break(n), catch(n), continue(n), dict(n), error(n), proc(n),
+source(n), tclvars(n), throw(n), try(n)
 .SH KEYWORDS
 break, catch, continue, error, exception, procedure, result, return
 .\" Local Variables:
diff --git a/doc/safe.n b/doc/safe.n
index 843eaf5..a5acb02 100644
--- a/doc/safe.n
+++ b/doc/safe.n
@@ -76,7 +76,7 @@ If the \fIslave\fR argument is omitted, a name will be generated.
 \fB::safe::interpInit\fR \fIslave\fR ?\fIoptions...\fR?
 This command is similar to \fBinterpCreate\fR except it that does not
 create the safe interpreter. \fIslave\fR must have been created by some
-other means, like \fBinterp create \-safe\fR.
+other means, like \fBinterp create\fR \fB\-safe\fR.
 .TP
 \fB::safe::interpConfigure\fR \fIslave\fR ?\fIoptions...\fR?
 If no \fIoptions\fR are given, returns the settings for all options for the
@@ -354,3 +354,6 @@ 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
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/self.n b/doc/self.n
index 11779ff..348c38f 100644
--- a/doc/self.n
+++ b/doc/self.n
@@ -29,7 +29,7 @@ object\fR was invoked. The supported subcommands are:
 .
 This returns a two-element list describing the method implementations used to
 implement the current call chain. The first element is the same as would be
-reported by \fBinfo object call\fR for the current method (except that this
+reported by \fBinfo object\fR \fBcall\fR for the current method (except that this
 also reports useful values from within constructors and destructors, whose
 names are reported as \fB<constructor>\fR and \fB<destructor>\fR
 respectively), and the second element is an index into the first element's
diff --git a/doc/socket.n b/doc/socket.n
index 0cb0595..9c9366d 100644
--- a/doc/socket.n
+++ b/doc/socket.n
@@ -88,7 +88,7 @@ mode using:
 \fBchan configure \fIchan \fB\-blocking 0\fR
 .CE
 .PP
-See the \fBchan\fR \fBconfigure\fR command for more details.
+See the \fBchan configure\fR command for more details.
 
 The Tcl event loop should be running while an asynchronous connection
 is in progress, because it may have to do several connection attempts
diff --git a/doc/tclvars.n b/doc/tclvars.n
index 27f9cc2..b126b7f 100644
--- a/doc/tclvars.n
+++ b/doc/tclvars.n
@@ -102,7 +102,8 @@ This variable is only used when initializing the \fBauto_path\fR variable.
 .TP
 \fBenv(TCL_INTERP_DEBUG_FRAME)\fR
 .
-If existing, it has the same effect as running \fBinterp debug {} -frame 1\fR
+If existing, it has the same effect as running \fBinterp debug\fR
+\fB{} -frame 1\fR
 as the very first command of each new Tcl interpreter.
 .RE
 .TP
diff --git a/doc/throw.n b/doc/throw.n
index a76609b..d49fb24 100644
--- a/doc/throw.n
+++ b/doc/throw.n
@@ -40,7 +40,7 @@ The following produces an error that is identical to that produced by
 \fBthrow\fR {ARITH DIVZERO {divide by zero}} {divide by zero}
 .CE
 .SH "SEE ALSO"
-catch(n), error(n), return(n), try(n)
+catch(n), error(n), return(n), tclvars(n), try(n)
 .SH "KEYWORDS"
 error, exception
 '\" Local Variables:
diff --git a/doc/transchan.n b/doc/transchan.n
index 9de9a87..e308e13 100644
--- a/doc/transchan.n
+++ b/doc/transchan.n
@@ -54,7 +54,7 @@ if the interpreter is deleted.
 This mandatory subcommand is called first, and then never again (for the given
 \fIhandle\fR). Its responsibility is to initialize all parts of the
 transformation at the Tcl level. The \fImode\fR is a list containing any of
-\fBread\fR and \fBwrite\fR.
+\fBread \fRand \fBwrite\fR.
 .RS
 .TP
 \fBwrite\fR
@@ -73,7 +73,7 @@ as error thrown by \fBchan push\fR.
 .SS "READ-RELATED SUBCOMMANDS"
 .PP
 These subcommands are used for handling transformations applied to readable
-channels; though strictly \fBread\fR is optional, it must be supported if any
+channels; though strictly \fBread \fRis optional, it must be supported if any
 of the others is or the channel will be made non-readable.
 .TP
 \fIcmdPrefix \fBdrain \fIhandle\fR