More minor doc fixes for greater clarity

3 files changed, 113 insertions, 106 deletions

diff --git a/ChangeLog b/ChangeLog
index 173f6ab..a610791 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2004-11-12  Donal K. Fellows  <donal.k.fellows@man.ac.uk>
+
+	* doc/binary.n, doc/upvar.n: More minor fixes.
+
 2004-11-12  Daniel Steffen  <das@users.sourceforge.net>
 
 	* doc/CrtChannel.3:
diff --git a/doc/binary.n b/doc/binary.n
index a4f7008..51e9bab 100644
--- a/doc/binary.n
+++ b/doc/binary.n
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: binary.n,v 1.23 2004/11/12 09:01:25 das Exp $
+'\" RCS: @(#) $Id: binary.n,v 1.24 2004/11/12 11:03:16 dkf Exp $
 '\" 
 .so man.macros
 .TH binary n 8.0 Tcl "Tcl Built-In Commands"
@@ -48,7 +48,7 @@ that consume arguments, then an error is generated.
 Here is a small example to clarify the relation between the field
 specifiers and the arguments:
 .CS
-\fBbinary format d3d {1.0 2.0 3.0 4.0} 0.1\fR
+\fBbinary format\fR d3d {1.0 2.0 3.0 4.0} 0.1
 .CE
 .PP
 The first argument is a list of four numbers, but because of the count
@@ -78,11 +78,11 @@ formatted.  If \fIcount\fR is omitted, then one character will be
 formatted.  For example,
 .RS
 .CS
-\fBbinary format a7a*a alpha bravo charlie\fR
+\fBbinary format\fR a7a*a alpha bravo charlie
 .CE
 will return a string equivalent to \fBalpha\\000\\000bravoc\fR and
 .CS
-\fBbinary format a* [encoding convertto utf-8 \\u20ac]\fR
+\fBbinary format\fR a* [encoding convertto utf-8 \\u20ac]
 .CE
 will return a string equivalent to \fB\\342\\202\\254\fR (which is the
 UTF-8 byte sequence for a Euro-currency character).
@@ -92,7 +92,7 @@ This form is the same as \fBa\fR except that spaces are used for
 padding instead of nulls.  For example,
 .RS
 .CS
-\fBbinary format A6A*A alpha bravo charlie\fR
+\fBbinary format\fR A6A*A alpha bravo charlie
 .CE
 will return \fBalpha bravoc\fR.
 .RE
@@ -111,7 +111,7 @@ does not end at a byte boundary, the remaining bits of the last byte
 will be zeros.  For example,
 .RS
 .CS
-\fBbinary format b5b* 11100 111000011010\fR
+\fBbinary format\fR b5b* 11100 111000011010
 .CE
 will return a string equivalent to \fB\\x07\\x87\\x05\fR.
 .RE
@@ -120,7 +120,7 @@ This form is the same as \fBb\fR except that the bits are stored in
 high-to-low order within each byte.  For example,
 .RS
 .CS
-\fBbinary format B5B* 11100 111000011010\fR
+\fBbinary format\fR B5B* 11100 111000011010
 .CE
 will return a string equivalent to \fB\\xe0\\xe1\\xa0\fR.
 .RE
@@ -139,7 +139,7 @@ number of digits formatted does not end at a byte boundary, the
 remaining bits of the last byte will be zeros.  For example,
 .RS
 .CS
-\fBbinary format h3h* AB def\fR
+\fBbinary format\fR h3h* AB def
 .CE
 will return a string equivalent to \fB\\xba\\x00\\xed\\x0f\fR.
 .RE
@@ -148,7 +148,7 @@ This form is the same as \fBh\fR except that the digits are stored in
 high-to-low order within each byte.  For example,
 .RS
 .CS
-\fBbinary format H3H* ab DEF\fR
+\fBbinary format\fR H3H* ab DEF
 .CE
 will return a string equivalent to \fB\\xab\\x00\\xde\\xf0\fR.
 .RE
@@ -164,12 +164,12 @@ error is generated.  If the number of elements in the list is greater
 than \fIcount\fR, then the extra elements are ignored.  For example,
 .RS
 .CS
-\fBbinary format c3cc* {3 -3 128 1} 260 {2 5}\fR
+\fBbinary format\fR c3cc* {3 -3 128 1} 260 {2 5}
 .CE
 will return a string equivalent to
 \fB\\x03\\xfd\\x80\\x04\\x02\\x05\fR, whereas
 .CS
-\fBbinary format c {2 5}\fR
+\fBbinary format\fR c {2 5}
 .CE
 will generate an error.
 .RE
@@ -181,7 +181,7 @@ the cursor position with the least significant byte stored first.  For
 example,
 .RS
 .CS
-\fBbinary format s3 {3 -3 258 1}\fR
+\fBbinary format\fR s3 {3 -3 258 1}
 .CE
 will return a string equivalent to 
 \fB\\x03\\x00\\xfd\\xff\\x02\\x01\fR.
@@ -192,7 +192,7 @@ This form is the same as \fBs\fR except that it stores one or more
 example,
 .RS
 .CS
-\fBbinary format S3 {3 -3 258 1}\fR
+\fBbinary format\fR S3 {3 -3 258 1}
 .CE
 will return a string equivalent to 
 \fB\\x00\\x03\\xff\\xfd\\x01\\x02\fR.
@@ -213,7 +213,7 @@ the cursor position with the least significant byte stored first.  For
 example,
 .RS
 .CS
-\fBbinary format i3 {3 -3 65536 1}\fR
+\fBbinary format\fR i3 {3 -3 65536 1}
 .CE
 will return a string equivalent to 
 \fB\\x03\\x00\\x00\\x00\\xfd\\xff\\xff\\xff\\x00\\x00\\x01\\x00\fR
@@ -224,7 +224,7 @@ or more 32-bit integers in big-endian byte order in the output string.
 For example,
 .RS
 .CS
-\fBbinary format I3 {3 -3 65536 1}\fR
+\fBbinary format\fR I3 {3 -3 65536 1}
 .CE
 will return a string equivalent to 
 \fB\\x00\\x00\\x00\\x03\\xff\\xff\\xff\\xfd\\x00\\x01\\x00\\x00\fR
@@ -246,7 +246,7 @@ the cursor position with the least significant byte stored first.  For
 example,
 .RS
 .CS
-\fBbinary format w 7810179016327718216\fR
+\fBbinary format\fR w 7810179016327718216
 .CE
 will return the string \fBHelloTcl\fR
 .RE
@@ -256,7 +256,7 @@ or more 64-bit integers in big-endian byte order in the output string.
 For example,
 .RS
 .CS
-\fBbinary format Wc 4785469626960341345 110\fR
+\fBbinary format\fR Wc 4785469626960341345 110
 .CE
 will return the string \fBBigEndian\fR
 .RE
@@ -284,7 +284,7 @@ loss of precision in the conversion to single-precision.  For example,
 on a Windows system running on an Intel Pentium processor,
 .RS
 .CS
-\fBbinary format f2 {1.6 3.4}\fR
+\fBbinary format\fR f2 {1.6 3.4}
 .CE
 will return a string equivalent to 
 \fB\\xcd\\xcc\\xcc\\x3f\\x9a\\x99\\x59\\x40\fR.
@@ -309,7 +309,7 @@ representation in the output string.  For example, on a
 Windows system running on an Intel Pentium processor,
 .RS
 .CS
-\fBbinary format d1 {1.6}\fR
+\fBbinary format\fR d1 {1.6}
 .CE
 will return a string equivalent to 
 \fB\\x9a\\x99\\x99\\x99\\x99\\x99\\xf9\\x3f\fR.
@@ -334,7 +334,7 @@ generates an error.  This type does not consume an argument.  For
 example,
 .RS
 .CS
-\fBbinary format a3xa3x2a3 abc def ghi\fR
+\fBbinary format\fR a3xa3x2a3 abc def ghi
 .CE
 will return a string equivalent to \fBabc\\000def\\000\\000ghi\fR.
 .RE
@@ -347,7 +347,7 @@ omitted then the cursor is moved back one byte.  This type does not
 consume an argument.  For example,
 .RS
 .CS
-\fBbinary format a3X*a3X2a3 abc def ghi\fR
+\fBbinary format\fR a3X*a3X2a3 abc def ghi
 .CE
 will return \fBdghi\fR.
 .RE
@@ -362,7 +362,7 @@ the output string.  If \fIcount\fR is omitted, then an error will be
 generated.  This type does not consume an argument. For example,
 .RS
 .CS
-\fBbinary format a5@2a1@*a3@10a1 abcde f ghi j\fR
+\fBbinary format\fR a5@2a1@*a3@10a1 abcde f ghi j
 .CE
 will return \fBabfdeghi\\000\\000j\fR.
 .RE
@@ -396,7 +396,7 @@ A similar example as with \fBbinary format\fR should explain the
 relation between field specifiers and arguments in case of the binary
 scan subcommand:
 .CS
-\fBbinary scan $bytes s3s first second\fR
+\fBbinary scan\fR $bytes s3s first second
 .CE
 .PP
 This command (provided the binary string in the variable \fIbytes\fR
@@ -407,31 +407,31 @@ integers), no assignment to \fIsecond\fR will be made, and if
 \fIbytes\fR contains fewer than 6 bytes (i.e. three 2-byte integers),
 no assignment to \fIfirst\fR will be made.  Hence:
 .CS
-\fBputs [binary scan abcdefg s3s first second]\fR
-\fBputs $first\fR
-\fBputs $second\fR
+puts [\fBbinary scan\fR abcdefg s3s first second]
+puts $first
+puts $second
 .CE
 will print (assuming neither variable is set previously):
 .CS
-\fB1\fR
-\fB25185 25699 26213\fR
-\fIcan't read "second": no such variable\fR
+1
+25185 25699 26213
+can't read "second": no such variable
 .CE
 .PP
-It is \fBimportant\fR to note that the \fBc\fR, \fBs\fR, and \fBS\fR
+It is \fIimportant\fR to note that the \fBc\fR, \fBs\fR, and \fBS\fR
 (and \fBi\fR and \fBI\fR on 64bit systems) will be scanned into
 long data size values.  In doing this, values that have their high
 bit set (0x80 for chars, 0x8000 for shorts, 0x80000000 for ints),
 will be sign extended.  Thus the following will occur:
 .CS
-\fBset signShort [binary format s1 0x8000]\fR
-\fBbinary scan $signShort s1 val; \fI# val == 0xFFFF8000\fR
+set signShort [\fBbinary format\fR s1 0x8000]
+\fBbinary scan\fR $signShort s1 val; \fI# val == 0xFFFF8000\fR
 .CE
 If you want to produce an unsigned value, then you can mask the return 
 value to the desired size.  For example, to produce an unsigned short 
 value:
 .CS
-\fBset val [expr {$val & 0xFFFF}]; \fI# val == 0x8000\fR
+set val [expr {$val & 0xFFFF}]; \fI# val == 0x8000\fR
 .CE
 .PP
 Each type-count pair moves an imaginary cursor through the binary data,
@@ -449,19 +449,19 @@ needed if the string is not an ISO 8859\-1 string.
 For example,
 .RS
 .CS
-\fBbinary scan abcde\\000fghi a6a10 var1 var2\fR
+\fBbinary scan\fR abcde\\000fghi a6a10 var1 var2
 .CE
 will return \fB1\fR with the string equivalent to \fBabcde\\000\fR
-stored in \fBvar1\fR and \fBvar2\fR left unmodified.
+stored in \fIvar1\fR and \fIvar2\fR left unmodified.
 .RE
 .IP \fBA\fR 5
 This form is the same as \fBa\fR, except trailing blanks and nulls are stripped from
 the scanned value before it is stored in the variable.  For example,
 .RS
 .CS
-\fBbinary scan "abc efghi  \\000" A* var1\fR
+\fBbinary scan\fR "abc efghi  \\000" A* var1
 .CE
-will return \fB1\fR with \fBabc efghi\fR stored in \fBvar1\fR.
+will return \fB1\fR with \fBabc efghi\fR stored in \fIvar1\fR.
 .RE
 .IP \fBb\fR 5
 The data is turned into a string of \fIcount\fR binary digits in
@@ -469,24 +469,24 @@ low-to-high order represented as a sequence of ``1'' and ``0''
 characters.  The data bytes are scanned in first to last order with
 the bits being taken in low-to-high order within each byte.  Any extra
 bits in the last byte are ignored.  If \fIcount\fR is \fB*\fR, then
-all of the remaining bits in \fBstring\fR will be scanned.  If
+all of the remaining bits in \fIstring\fR will be scanned.  If
 \fIcount\fR is omitted, then one bit will be scanned.  For example,
 .RS
 .CS
-\fBbinary scan \\x07\\x87\\x05 b5b* var1 var2\fR
+\fBbinary scan\fR \\x07\\x87\\x05 b5b* var1 var2
 .CE
-will return \fB2\fR with \fB11100\fR stored in \fBvar1\fR and
-\fB1110000110100000\fR stored in \fBvar2\fR.
+will return \fB2\fR with \fB11100\fR stored in \fIvar1\fR and
+\fB1110000110100000\fR stored in \fIvar2\fR.
 .RE
 .IP \fBB\fR 5
 This form is the same as \fBb\fR, except the bits are taken in
 high-to-low order within each byte.  For example,
 .RS
 .CS
-\fBbinary scan \\x70\\x87\\x05 B5B* var1 var2\fR
+\fBbinary scan\fR \\x70\\x87\\x05 B5B* var1 var2
 .CE
-will return \fB2\fR with \fB01110\fR stored in \fBvar1\fR and
-\fB1000011100000101\fR stored in \fBvar2\fR.
+will return \fB2\fR with \fB01110\fR stored in \fIvar1\fR and
+\fB1000011100000101\fR stored in \fIvar2\fR.
 .RE
 .IP \fBh\fR 5
 The data is turned into a string of \fIcount\fR hexadecimal digits in
@@ -494,61 +494,61 @@ low-to-high order represented as a sequence of characters in the set
 ``0123456789abcdef''.  The data bytes are scanned in first to last
 order with the hex digits being taken in low-to-high order within each
 byte.  Any extra bits in the last byte are ignored.  If \fIcount\fR
-is \fB*\fR, then all of the remaining hex digits in \fBstring\fR will be
+is \fB*\fR, then all of the remaining hex digits in \fIstring\fR will be
 scanned.  If \fIcount\fR is omitted, then one hex digit will be
 scanned.  For example,
 .RS
 .CS
-\fBbinary scan \\x07\\x86\\x05 h3h* var1 var2\fR
+\fBbinary scan\fR \\x07\\x86\\x05 h3h* var1 var2
 .CE
-will return \fB2\fR with \fB706\fR stored in \fBvar1\fR and
-\fB50\fR stored in \fBvar2\fR.
+will return \fB2\fR with \fB706\fR stored in \fIvar1\fR and
+\fB50\fR stored in \fIvar2\fR.
 .RE
 .IP \fBH\fR 5
 This form is the same as \fBh\fR, except the digits are taken in
 high-to-low order within each byte.  For example,
 .RS
 .CS
-\fBbinary scan \\x07\\x86\\x05 H3H* var1 var2\fR
+\fBbinary scan\fR \\x07\\x86\\x05 H3H* var1 var2
 .CE
-will return \fB2\fR with \fB078\fR stored in \fBvar1\fR and
-\fB05\fR stored in \fBvar2\fR.
+will return \fB2\fR with \fB078\fR stored in \fIvar1\fR and
+\fB05\fR stored in \fIvar2\fR.
 .RE
 .IP \fBc\fR 5
 The data is turned into \fIcount\fR 8-bit signed integers and stored
 in the corresponding variable as a list. If \fIcount\fR is \fB*\fR,
-then all of the remaining bytes in \fBstring\fR will be scanned.  If
+then all of the remaining bytes in \fIstring\fR will be scanned.  If
 \fIcount\fR is omitted, then one 8-bit integer will be scanned.  For
 example,
 .RS
 .CS
-\fBbinary scan \\x07\\x86\\x05 c2c* var1 var2\fR
+\fBbinary scan\fR \\x07\\x86\\x05 c2c* var1 var2
 .CE
-will return \fB2\fR with \fB7 -122\fR stored in \fBvar1\fR and \fB5\fR
-stored in \fBvar2\fR.  Note that the integers returned are signed, but
+will return \fB2\fR with \fB7 -122\fR stored in \fIvar1\fR and \fB5\fR
+stored in \fIvar2\fR.  Note that the integers returned are signed, but
 they can be converted to unsigned 8-bit quantities using an expression
 like:
 .CS
-\fBexpr ( $num + 0x100 ) % 0x100\fR
+expr { ( $num + 0x100 ) % 0x100 }
 .CE
 .RE
 .IP \fBs\fR 5
 The data is interpreted as \fIcount\fR 16-bit signed integers
 represented in little-endian byte order.  The integers are stored in
 the corresponding variable as a list.  If \fIcount\fR is \fB*\fR, then
-all of the remaining bytes in \fBstring\fR will be scanned.  If
+all of the remaining bytes in \fIstring\fR will be scanned.  If
 \fIcount\fR is omitted, then one 16-bit integer will be scanned.  For
 example,
 .RS
 .CS
-\fBbinary scan \\x05\\x00\\x07\\x00\\xf0\\xff s2s* var1 var2\fR
+\fBbinary scan\fR \\x05\\x00\\x07\\x00\\xf0\\xff s2s* var1 var2
 .CE
-will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR
-stored in \fBvar2\fR.  Note that the integers returned are signed, but
+will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB-16\fR
+stored in \fIvar2\fR.  Note that the integers returned are signed, but
 they can be converted to unsigned 16-bit quantities using an expression
 like:
 .CS
-\fBexpr ( $num + 0x10000 ) % 0x10000\fR
+expr { ( $num + 0x10000 ) % 0x10000 }
 .CE
 .RE
 .IP \fBS\fR 5
@@ -557,10 +557,10 @@ as \fIcount\fR 16-bit signed integers represented in big-endian byte
 order.  For example,
 .RS
 .CS
-\fBbinary scan \\x00\\x05\\x00\\x07\\xff\\xf0 S2S* var1 var2\fR
+\fBbinary scan\fR \\x00\\x05\\x00\\x07\\xff\\xf0 S2S* var1 var2
 .CE
-will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR
-stored in \fBvar2\fR. 
+will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB-16\fR
+stored in \fIvar2\fR. 
 .RE
 .IP \fBt\fR 5
 .VS 8.5
@@ -574,15 +574,16 @@ the \fBbyteOrder\fR element of the \fBtcl_platform\fR array.
 The data is interpreted as \fIcount\fR 32-bit signed integers
 represented in little-endian byte order.  The integers are stored in
 the corresponding variable as a list.  If \fIcount\fR is \fB*\fR, then
-all of the remaining bytes in \fBstring\fR will be scanned.  If
+all of the remaining bytes in \fIstring\fR will be scanned.  If
 \fIcount\fR is omitted, then one 32-bit integer will be scanned.  For
 example,
 .RS
 .CS
-\fBbinary scan \\x05\\x00\\x00\\x00\\x07\\x00\\x00\\x00\\xf0\\xff\\xff\\xff i2i* var1 var2\fR
+set str \\x05\\x00\\x00\\x00\\x07\\x00\\x00\\x00\\xf0\\xff\\xff\\xff
+\fBbinary scan\fR $str i2i* var1 var2
 .CE
-will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR
-stored in \fBvar2\fR.  Note that the integers returned are signed and
+will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB-16\fR
+stored in \fIvar2\fR.  Note that the integers returned are signed and
 cannot be represented by Tcl as unsigned values.
 .RE
 .IP \fBI\fR 5
@@ -591,10 +592,11 @@ as \fIcount\fR 32-bit signed integers represented in big-endian byte
 order.  For example,
 .RS
 .CS
-\fBbinary scan \\x00\\x00\\x00\\x05\\x00\\x00\\x00\\x07\\xff\\xff\\xff\\xf0 I2I* var1 var2\fR
+set str \\x00\\x00\\x00\\x05\\x00\\x00\\x00\\x07\\xff\\xff\\xff\\xf0
+\fBbinary scan\fR $str I2I* var1 var2
 .CE
-will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR
-stored in \fBvar2\fR.
+will return \fB2\fR with \fB5 7\fR stored in \fIvar1\fR and \fB-16\fR
+stored in \fIvar2\fR.
 .RE
 .IP \fBn\fR 5
 .VS 8.5
@@ -608,15 +610,16 @@ the \fBbyteOrder\fR element of the \fBtcl_platform\fR array.
 The data is interpreted as \fIcount\fR 64-bit signed integers
 represented in little-endian byte order.  The integers are stored in
 the corresponding variable as a list.  If \fIcount\fR is \fB*\fR, then
-all of the remaining bytes in \fBstring\fR will be scanned.  If
+all of the remaining bytes in \fIstring\fR will be scanned.  If
 \fIcount\fR is omitted, then one 64-bit integer will be scanned.  For
 example,
 .RS
 .CS
-\fBbinary scan \\x05\\x00\\x00\\x00\\x07\\x00\\x00\\x00\\xf0\\xff\\xff\\xff wi* var1 var2\fR
+set str \\x05\\x00\\x00\\x00\\x07\\x00\\x00\\x00\\xf0\\xff\\xff\\xff
+\fBbinary scan\fR $str wi* var1 var2
 .CE
-will return \fB2\fR with \fB30064771077\fR stored in \fBvar1\fR and
-\fB-16\fR stored in \fBvar2\fR.  Note that the integers returned are
+will return \fB2\fR with \fB30064771077\fR stored in \fIvar1\fR and
+\fB-16\fR stored in \fIvar2\fR.  Note that the integers returned are
 signed and cannot be represented by Tcl as unsigned values.
 .RE
 .IP \fBW\fR 5
@@ -625,10 +628,11 @@ as \fIcount\fR 64-bit signed integers represented in big-endian byte
 order.  For example,
 .RS
 .CS
-\fBbinary scan \\x00\\x00\\x00\\x05\\x00\\x00\\x00\\x07\\xff\\xff\\xff\\xf0 WI* var1 var2\fR
+set str \\x00\\x00\\x00\\x05\\x00\\x00\\x00\\x07\\xff\\xff\\xff\\xf0
+\fBbinary scan\fR $str WI* var1 var2
 .CE
-will return \fB2\fR with \fB21474836487\fR stored in \fBvar1\fR and \fB-16\fR
-stored in \fBvar2\fR.
+will return \fB2\fR with \fB21474836487\fR stored in \fIvar1\fR and \fB-16\fR
+stored in \fIvar2\fR.
 .RE
 .IP \fBm\fR 5
 .VS 8.5
@@ -643,7 +647,7 @@ The data is interpreted as \fIcount\fR single-precision floating point
 numbers in the machine's native representation.  The floating point
 numbers are stored in the corresponding variable as a list.  If
 \fIcount\fR is \fB*\fR, then all of the remaining bytes in
-\fBstring\fR will be scanned.  If \fIcount\fR is omitted, then one
+\fIstring\fR will be scanned.  If \fIcount\fR is omitted, then one
 single-precision floating point number will be scanned.  The size of a
 floating point number may vary across architectures, so the number of
 bytes that are scanned may vary.  If the data does not represent a
@@ -652,10 +656,10 @@ compiler dependent.  For example, on a Windows system running on an
 Intel Pentium processor,
 .RS
 .CS
-\fBbinary scan \\x3f\\xcc\\xcc\\xcd f var1\fR
+\fBbinary scan\fR \\x3f\\xcc\\xcc\\xcd f var1
 .CE
 will return \fB1\fR with \fB1.6000000238418579\fR stored in
-\fBvar1\fR.
+\fIvar1\fR.
 .RE
 .IP \fBr\fR 5
 .VS 8.5
@@ -678,10 +682,10 @@ machine's native representation. For example, on a Windows system
 running on an Intel Pentium processor,
 .RS
 .CS
-\fBbinary scan \\x9a\\x99\\x99\\x99\\x99\\x99\\xf9\\x3f d var1\fR
+\fBbinary scan\fR \\x9a\\x99\\x99\\x99\\x99\\x99\\xf9\\x3f d var1
 .CE
 will return \fB1\fR with \fB1.6000000000000001\fR
-stored in \fBvar1\fR.
+stored in \fIvar1\fR.
 .RE
 .IP \fBq\fR 5
 .VS 8.5
@@ -706,9 +710,9 @@ cursor is moved forward one byte.  Note that this type does not
 consume an argument.  For example,
 .RS
 .CS
-\fBbinary scan \\x01\\x02\\x03\\x04 x2H* var1\fR
+\fBbinary scan\fR \\x01\\x02\\x03\\x04 x2H* var1
 .CE
-will return \fB1\fR with \fB0304\fR stored in \fBvar1\fR.
+will return \fB1\fR with \fB0304\fR stored in \fIvar1\fR.
 .RE
 .IP \fBX\fR 5
 Moves the cursor back \fIcount\fR bytes in \fIstring\fR.  If
@@ -719,10 +723,10 @@ is omitted then the cursor is moved back one byte.  Note that this
 type does not consume an argument.  For example,
 .RS
 .CS
-\fBbinary scan \\x01\\x02\\x03\\x04 c2XH* var1 var2\fR
+\fBbinary scan\fR \\x01\\x02\\x03\\x04 c2XH* var1 var2
 .CE
-will return \fB2\fR with \fB1 2\fR stored in \fBvar1\fR and \fB020304\fR
-stored in \fBvar2\fR.
+will return \fB2\fR with \fB1 2\fR stored in \fIvar1\fR and \fB020304\fR
+stored in \fIvar2\fR.
 .RE
 .IP \fB@\fR 5
 Moves the cursor to the absolute location in the data string specified
@@ -732,10 +736,10 @@ by \fIcount\fR.  Note that position 0 refers to the first byte in
 \fIcount\fR is omitted, then an error will be generated.  For example,
 .RS
 .CS
-\fBbinary scan \\x01\\x02\\x03\\x04 c2@1H* var1 var2\fR
+\fBbinary scan\fR \\x01\\x02\\x03\\x04 c2@1H* var1 var2
 .CE
-will return \fB2\fR with \fB1 2\fR stored in \fBvar1\fR and \fB020304\fR
-stored in \fBvar2\fR.
+will return \fB2\fR with \fB1 2\fR stored in \fIvar1\fR and \fB020304\fR
+stored in \fIvar2\fR.
 .RE
 .SH "PORTABILITY ISSUES"
 The \fBr\fR, \fBR\fR, \fBq\fR and \fBQ\fR conversions will only work
@@ -748,7 +752,7 @@ architectures, use their textual representation (as produced by
 This is a procedure to write a Tcl string to a binary-encoded channel as
 UTF-8 data preceded by a length word:
 .CS
-proc writeString {channel string} {
+proc \fIwriteString\fR {channel string} {
     set data [encoding convertto utf-8 $string]
     puts -nonewline [\fBbinary format\fR Ia* \e
             [string length $data] $data]
@@ -756,9 +760,9 @@ proc writeString {channel string} {
 .CE
 .PP
 This procedure reads a string from a channel that was written by the
-previously presented \fBwriteString\fR procedure:
+previously presented \fIwriteString\fR procedure:
 .CS
-proc readString {channel} {
+proc \fIreadString\fR {channel} {
     if {![\fBbinary scan\fR [read $channel 4] I length]} {
         error "missing length"
     }
diff --git a/doc/upvar.n b/doc/upvar.n
index 145adf9..15fc3b8 100644
--- a/doc/upvar.n
+++ b/doc/upvar.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: upvar.n,v 1.9 2004/11/12 09:01:25 das Exp $
+'\" RCS: @(#) $Id: upvar.n,v 1.10 2004/11/12 11:03:16 dkf Exp $
 '\" 
 .so man.macros
 .TH upvar n "" Tcl "Tcl Built-In Commands"
@@ -46,14 +46,14 @@ procedure calling and also makes it easier to build new control constructs
 as Tcl procedures.
 For example, consider the following procedure:
 .CS
-proc \fBadd2\fR name {
+proc \fIadd2\fR name {
    \fBupvar\fR $name x
-   set x [expr $x+2]
+   set x [expr {$x + 2}]
 }
 .CE
-\fBadd2\fR is invoked with an argument giving the name of a variable,
-and it adds two to the value of that variable.
-Although \fBadd2\fR could have been implemented using \fBuplevel\fR
+If \fIadd2\fR is invoked with an argument giving the name of a variable,
+it adds two to the value of that variable.
+Although \fIadd2\fR could have been implemented using \fBuplevel\fR
 instead of \fBupvar\fR, \fBupvar\fR makes it simpler for \fBadd2\fR
 to access the variable in the caller's procedure frame.
 .PP
@@ -82,19 +82,18 @@ unexpected manner.  If a variable trace is defined on \fIotherVar\fR, that
 trace will be triggered by actions involving \fImyVar\fR.  However,
 the trace procedure will be passed the name of \fImyVar\fR, rather
 than the name of \fIotherVar\fR.  Thus, the output of the following code
-will be \fBlocalVar\fR rather than \fBoriginalVar\fR:
+will be "\fIlocalVar\fR" rather than "\fIoriginalVar\fR":
 .CS
-proc \fBtraceproc\fR { name index op } {
+proc \fItraceproc\fR { name index op } {
    puts $name
 }
-proc \fBsetByUpvar\fR { name value } {
+proc \fIsetByUpvar\fR { name value } {
    \fBupvar\fR $name localVar
    set localVar $value
 }
 set originalVar 1
-trace variable originalVar w \fBtraceproc\fR
-\fBsetByUpvar\fR originalVar 2
-}
+trace variable originalVar w \fItraceproc\fR
+\fIsetByUpvar\fR originalVar 2
 .CE
 .PP
 If \fIotherVar\fR refers to an element of an array, then variable