summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--ChangeLog2
-rw-r--r--doc/tcltest.n42
-rw-r--r--doc/tclvars.n9
-rw-r--r--doc/tell.n3
-rw-r--r--doc/time.n3
-rw-r--r--doc/trace.n18
-rw-r--r--doc/unset.n6
-rw-r--r--doc/uplevel.n10
-rw-r--r--doc/upvar.n16
-rw-r--r--doc/variable.n10
-rw-r--r--doc/vwait.n10
-rw-r--r--doc/while.n12
12 files changed, 69 insertions, 72 deletions
diff --git a/ChangeLog b/ChangeLog
index 891890d..18bbe67 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,6 +1,6 @@
2004-10-27 Donal K. Fellows <donal.k.fellows@man.ac.uk>
- * doc/[a-s]*.n: Many small general documentation fixes.
+ * doc/*.n: Many small general documentation fixes.
2004-10-26 David Gravereaux <davygrvy@pobox.com>
diff --git a/doc/tcltest.n b/doc/tcltest.n
index 5a27864..b673db7 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.43 2004/09/06 09:44:57 dkf Exp $
+'\" RCS: @(#) $Id: tcltest.n,v 1.44 2004/10/27 14:43:54 dkf Exp $
'\"
.so man.macros
.TH "tcltest" n 2.2 tcltest "Tcl Bundled Packages"
@@ -378,7 +378,7 @@ also influence how [\fBtest\fR] operates.
The valid options for [\fBtest\fR] are summarized:
.CS
.ta 0.8i
-test \fIname\fR \fIdescription\fR
+\fBtest\fR \fIname\fR \fIdescription\fR
?-constraints \fIkeywordList|expression\fR?
?-setup \fIsetupScript\fR?
?-body \fItestScript\fR?
@@ -663,7 +663,7 @@ only constraints from the [\fBconfigure -constraints\fR] list
are run; all others are skipped. For example, one might set
up a configuration with
.CS
-configure -constraints knownBug \e
+\fBconfigure\fR -constraints knownBug \e
-limitconstraints true \e
-verbose pass
.CE
@@ -873,7 +873,7 @@ command. We begin with several examples.
.IP [1]
Test of a script that returns normally.
.CS
-test example-1.0 {normal return} {
+\fBtest\fR example-1.0 {normal return} {
format %s value
} value
.CE
@@ -881,7 +881,7 @@ test example-1.0 {normal return} {
Test of a script that requires context setup and cleanup. Note the
bracing and indenting style that avoids any need for line continuation.
.CS
-test example-1.1 {test file existence} -setup {
+\fBtest\fR example-1.1 {test file existence} -setup {
set file [makeFile {} test]
} -body {
file exists $file
@@ -892,14 +892,14 @@ test example-1.1 {test file existence} -setup {
.IP [3]
Test of a script that raises an error.
.CS
-test example-1.2 {error return} -body {
+\fBtest\fR example-1.2 {error return} -body {
error message
} -returnCodes error -result message
.CE
.IP [4]
Test with a constraint.
.CS
-test example-1.3 {user owns created files} -constraints {
+\fBtest\fR example-1.3 {user owns created files} -constraints {
unix
} -setup {
set file [makeFile {} test]
@@ -923,8 +923,8 @@ Use constraints to skip tests, rather than conditional evaluation
of [\fBtest\fR]. That is, do this:
.IP [5]
.CS
-testConstraint X [expr $myRequirement]
-test goodConditionalTest {} X {
+\fBtestConstraint\fR X [expr $myRequirement]
+\fBtest\fR goodConditionalTest {} X {
# body
} result
.CE
@@ -967,23 +967,23 @@ should be called.
Here is a sketch of a sample test file illustrating those points:
.CS
package require tcltest 2.2
-eval tcltest::configure $argv
+eval \fB::tcltest::configure\fR $argv
package require example
namespace eval ::example::test {
namespace import ::tcltest::*
- testConstraint X [expr {...}]
+ \fBtestConstraint\fR X [expr {...}]
variable SETUP {#common setup code}
variable CLEANUP {#common cleanup code}
- test example-1 {} -setup $SETUP -body {
+ \fBtest\fR example-1 {} -setup $SETUP -body {
# First test
} -cleanup $CLEANUP -result {...}
- test example-2 {} -constraints X -setup $SETUP -body {
+ \fBtest\fR example-2 {} -constraints X -setup $SETUP -body {
# Second test; constrained
} -cleanup $CLEANUP -result {...}
- test example-3 {} {
+ \fBtest\fR example-3 {} {
# Third test; no context required
} {...}
- cleanupTests
+ \fBcleanupTests\fR
}
namespace delete ::example::test
.CE
@@ -1000,10 +1000,10 @@ Here is a sketch of a sample test suite master script:
package require Tcl 8.4
package require tcltest 2.2
package require example
-tcltest::configure -testdir \
+\fB::tcltest::configure\fR -testdir \
[file dirname [file normalize [info script]]]
-eval tcltest::configure $argv
-tcltest::runAllTests
+eval \fB::tcltest::configure\fR $argv
+\fB::tcltest::runAllTests\fR
.CE
.SH COMPATIBILITY
.PP
@@ -1021,7 +1021,7 @@ 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
.CS
-eval tcltest::configure $::argv
+eval \fB::tcltest::configure\fR $::argv
.CE
to establish a configuration from command line arguments.
.SH "KNOWN ISSUES"
@@ -1030,9 +1030,9 @@ 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:
.CS
-test level-1.1 {level 1} {
+\fBtest\fR level-1.1 {level 1} {
-body {
- test level-2.1 {level 2} {
+ \fBtest\fR level-2.1 {level 2} {
}
}
}
diff --git a/doc/tclvars.n b/doc/tclvars.n
index 1cdb78d..ffb2122 100644
--- a/doc/tclvars.n
+++ b/doc/tclvars.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: tclvars.n,v 1.17 2004/09/18 17:01:06 dkf Exp $
+'\" RCS: @(#) $Id: tclvars.n,v 1.18 2004/10/27 14:43:54 dkf Exp $
'\"
.so man.macros
.TH tclvars n 8.0 Tcl "Tcl Built-In Commands"
@@ -189,7 +189,6 @@ be defined, but they may have empty strings as values if Tcl couldn't
retrieve any relevant information. In addition, extensions
and applications may add additional values to the array. The
predefined elements are:
-
.RS
.VS
.TP
@@ -200,7 +199,7 @@ The native byte order of this machine: either \fBlittleEndian\fR or
.TP
\fBdebug\fR
If this variable exists, then the interpreter was compiled with and linked
-to a debug enabled C run-time. This variable will only exist on Windows,
+to a debug-enabled C run-time. This variable will only exist on Windows,
so extension writers can specify which package to load depending on the
C run-time library that is in use. This is not an indication that this core
contains symbols.
@@ -285,7 +284,7 @@ This variable is useful in
tracking down suspected problems with the Tcl compiler.
It is also occasionally useful when converting
existing code to use Tcl8.0.
-
+.PP
This variable and functionality only exist if
\fBTCL_COMPILE_DEBUG\fR was defined during Tcl's compilation.
.TP
@@ -310,7 +309,7 @@ tracking down suspected problems with the bytecode compiler
and interpreter.
It is also occasionally useful when converting
code to use Tcl8.0.
-
+.PP
This variable and functionality only exist if
\fBTCL_COMPILE_DEBUG\fR was defined during Tcl's compilation.
.TP
diff --git a/doc/tell.n b/doc/tell.n
index ab3d6ee..e8a37aa 100644
--- a/doc/tell.n
+++ b/doc/tell.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: tell.n,v 1.6 2004/05/28 12:48:36 dkf Exp $
+'\" RCS: @(#) $Id: tell.n,v 1.7 2004/10/27 14:43:54 dkf Exp $
'\"
.so man.macros
.TH tell n 8.1 Tcl "Tcl Built-In Commands"
@@ -36,7 +36,6 @@ the result of a channel creation command provided by a Tcl extension.
.VE
.SH EXAMPLE
Read a line from a file channel only if it starts with \fBfoobar\fR:
-
.CS
# Save the offset in case we need to undo the read...
set offset [\fBtell\fR $chan]
diff --git a/doc/time.n b/doc/time.n
index 31965bb..47f967f 100644
--- a/doc/time.n
+++ b/doc/time.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: time.n,v 1.4 2004/04/30 20:25:26 dkf Exp $
+'\" RCS: @(#) $Id: time.n,v 1.5 2004/10/27 14:43:54 dkf Exp $
'\"
.so man.macros
.TH time n "" Tcl "Tcl Built-In Commands"
@@ -31,7 +31,6 @@ Time is measured in elapsed time, not CPU time.
.SH EXAMPLE
Estimate how long it takes for a simple Tcl \fBfor\fR loop to count to
a thousand:
-
.CS
time {
for {set i 0} {$i<1000} {incr i} {
diff --git a/doc/trace.n b/doc/trace.n
index ad82b0a..c8d7914 100644
--- a/doc/trace.n
+++ b/doc/trace.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: trace.n,v 1.17 2004/08/31 15:19:36 dkf Exp $
+'\" RCS: @(#) $Id: trace.n,v 1.18 2004/10/27 14:43:54 dkf Exp $
'\"
.so man.macros
.TH trace n "8.4" Tcl "Tcl Built-In Commands"
@@ -141,7 +141,7 @@ Note that the creation of many \fBenterstep\fR or
\fBleavestep\fR traces can lead to unintuitive results, since the
invoked commands from one trace can themselves lead to further
command invocations for other traces.
-
+.PP
\fICommand\fR executes in the same context as the code that invoked
the traced operation: thus the \fIcommand\fR, if invoked from a procedure,
will have access to the same local variables as code in the procedure.
@@ -149,19 +149,19 @@ This context may be different than the context in which the trace was
created. If \fIcommand\fR invokes a procedure (which it normally does)
then the procedure will have to use upvar or uplevel commands if it wishes
to access the local variables of the code which invoked the trace operation.
-
+.PP
While \fIcommand\fR is executing during an execution trace, traces
on \fIname\fR are temporarily disabled. This allows the \fIcommand\fR
to execute \fIname\fR in its body without invoking any other traces again.
If an error occurs while executing the \fIcommand\fR body, then the
command \fIname\fR as a whole will return that same error.
-
+.PP
When multiple traces are set on \fIname\fR, then for \fIenter\fR
and \fIenterstep\fR operations, the traced commands are invoked
in the reverse order of how the traces were originally created;
and for \fIleave\fR and \fIleavestep\fR operations, the traced
commands are invoked in the original order of creation.
-
+.PP
The behavior of execution traces is currently undefined for a command
\fIname\fR imported into another namespace.
.RE
@@ -363,8 +363,8 @@ proc tracer {varname args} {
upvar #0 $varname var
puts "$varname was updated to be \e"$var\e""
}
-trace add variable foo write "tracer foo"
-trace add variable bar write "tracer bar"
+\fBtrace add\fR variable foo write "tracer foo"
+\fBtrace add\fR variable bar write "tracer bar"
.CE
.PP
Ensure that the global variable \fBfoobar\fR always contains the
@@ -374,8 +374,8 @@ proc doMult args {
global foo bar foobar
set foobar [expr {$foo * $bar}]
}
-trace add variable foo write doMult
-trace add variable bar write doMult
+\fBtrace add\fR variable foo write doMult
+\fBtrace add\fR variable bar write doMult
.CE
.SH "SEE ALSO"
diff --git a/doc/unset.n b/doc/unset.n
index 142b3ae..367ab41 100644
--- a/doc/unset.n
+++ b/doc/unset.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: unset.n,v 1.7 2004/05/27 15:45:43 dkf Exp $
+'\" RCS: @(#) $Id: unset.n,v 1.8 2004/10/27 14:43:54 dkf Exp $
'\"
.so man.macros
.TH unset n 8.4 Tcl "Tcl Built-In Commands"
@@ -54,8 +54,8 @@ array set squares {
puts "The squares are:"
parray squares
-unset squares(1) squares(4) squares(6)
-unset squares(8) squares(9) squares(10)
+\fBunset\fR squares(1) squares(4) squares(6)
+\fBunset\fR squares(8) squares(9) squares(10)
puts "The prime squares are:"
parray squares
diff --git a/doc/uplevel.n b/doc/uplevel.n
index abbc4f2..ee4f6c7 100644
--- a/doc/uplevel.n
+++ b/doc/uplevel.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: uplevel.n,v 1.4 2004/05/17 22:31:31 dkf Exp $
+'\" RCS: @(#) $Id: uplevel.n,v 1.5 2004/10/27 14:43:54 dkf Exp $
'\"
.so man.macros
.TH uplevel n "" Tcl "Tcl Built-In Commands"
@@ -44,14 +44,14 @@ The \fBuplevel\fR command causes the invoking procedure to disappear
from the procedure calling stack while the command is being executed.
In the above example, suppose \fBc\fR invokes the command
.CS
-\fBuplevel 1 {set x 43; d}\fR
+\fBuplevel\fR 1 {set x 43; d}
.CE
where \fBd\fR is another Tcl procedure. The \fBset\fR command will
modify the variable \fBx\fR in \fBb\fR's context, and \fBd\fR will execute
at level 3, as if called from \fBb\fR. If it in turn executes
the command
.CS
-\fBuplevel {set x 42}\fR
+\fBuplevel\fR {set x 42}
.CE
then the \fBset\fR command will modify the same variable \fBx\fR in \fBb\fR's
context: the procedure \fBc\fR does not appear to be on the call stack
@@ -85,8 +85,8 @@ proc do {body while condition} {
}
set conditionCmd [list expr $condition]
while {1} {
- uplevel 1 $body
- if {![uplevel 1 $conditionCmd]} {
+ \fBuplevel\fR 1 $body
+ if {![\fBuplevel\fR 1 $conditionCmd]} {
break
}
}
diff --git a/doc/upvar.n b/doc/upvar.n
index bb25fee..8cc28a6 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.7 2004/05/18 21:29:22 dkf Exp $
+'\" RCS: @(#) $Id: upvar.n,v 1.8 2004/10/27 14:43:54 dkf Exp $
'\"
.so man.macros
.TH upvar n "" Tcl "Tcl Built-In Commands"
@@ -47,8 +47,8 @@ as Tcl procedures.
For example, consider the following procedure:
.CS
\fBproc add2 name {
- upvar $name x
- set x [expr $x+2]
+ \fBupvar\fR $name x
+ set x [expr $x+2]
}\fR
.CE
\fBAdd2\fR is invoked with an argument giving the name of a variable,
@@ -85,18 +85,18 @@ than the name of \fIotherVar\fR. Thus, the output of the following code
will be \fBlocalVar\fR rather than \fBoriginalVar\fR:
.CS
\fBproc traceproc { name index op } {
- puts $name
+ puts $name
}
proc setByUpvar { name value } {
- upvar $name localVar
- set localVar $value
+ \fBupvar\fR $name localVar
+ set localVar $value
}
set originalVar 1
trace variable originalVar w traceproc
setByUpvar originalVar 2
}\fR
.CE
-
+.PP
If \fIotherVar\fR refers to an element of an array, then variable
traces set for the entire array will not be invoked when \fImyVar\fR
is accessed (but traces on the particular element will still be
@@ -108,7 +108,7 @@ A \fBdecr\fR command that works like \fBincr\fR except it subtracts
the value from the variable instead of adding it:
.CS
proc decr {varName {decrement 1}} {
- upvar 1 $varName var
+ \fBupvar\fR 1 $varName var
incr var [expr {-$decrement}]
}
.CE
diff --git a/doc/variable.n b/doc/variable.n
index 2f13edd..1676913 100644
--- a/doc/variable.n
+++ b/doc/variable.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: variable.n,v 1.5 2004/05/27 22:13:45 dkf Exp $
+'\" RCS: @(#) $Id: variable.n,v 1.6 2004/10/27 14:43:54 dkf Exp $
'\"
.so man.macros
.TH variable n 8.0 Tcl "Tcl Built-In Commands"
@@ -62,14 +62,14 @@ elements within the array can be set using ordinary
Create a variable in a namespace:
.CS
namespace eval foo {
- variable bar 12345
+ \fBvariable\fR bar 12345
}
.CE
.PP
Create an array in a namespace:
.CS
namespace eval someNS {
- variable someAry
+ \fBvariable\fR someAry
array set someAry {
someName someValue
otherName otherValue
@@ -82,11 +82,11 @@ Access variables in namespaces from a procedure:
namespace eval foo {
proc spong {} {
# Variable in this namespace
- variable bar
+ \fBvariable\fR bar
puts "bar is $bar"
# Variable in another namespace
- variable ::someNS::someAry
+ \fBvariable\fR ::someNS::someAry
parray someAry
}
}
diff --git a/doc/vwait.n b/doc/vwait.n
index 6cd8be2..568f23a 100644
--- a/doc/vwait.n
+++ b/doc/vwait.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: vwait.n,v 1.5 2004/05/20 22:58:14 dkf Exp $
+'\" RCS: @(#) $Id: vwait.n,v 1.6 2004/10/27 14:43:54 dkf Exp $
'\"
.so man.macros
.TH vwait n 8.0 Tcl "Tcl Built-In Commands"
@@ -40,9 +40,9 @@ Run the event-loop continually until some event calls \fBexit\fR.
(You can use any variable not mentioned elsewhere, but the name
\fIforever\fR reminds you at a glance of the intent.)
.CS
-vwait forever
+\fBvwait\fR forever
.CE
-
+.PP
Wait five seconds for a connection to a server socket, otherwise
close the socket and continue running the script:
.CS
@@ -56,7 +56,7 @@ proc accept {args} {
}
# Wait for something to happen
-vwait state
+\fBvwait\fR state
# Clean up events that could have happened
close $server
@@ -75,7 +75,7 @@ switch $state {
.CE
.SH "SEE ALSO"
-global(n)
+global(n), update(n)
.SH KEYWORDS
event, variable, wait
diff --git a/doc/while.n b/doc/while.n
index e1c2ec3..bd74f45 100644
--- a/doc/while.n
+++ b/doc/while.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: while.n,v 1.4 2004/05/05 22:08:10 dkf Exp $
+'\" RCS: @(#) $Id: while.n,v 1.5 2004/10/27 14:43:54 dkf Exp $
'\"
.so man.macros
.TH while n "" Tcl "Tcl Built-In Commands"
@@ -45,9 +45,9 @@ For an example, try the following script with and without the braces
around \fB$x<10\fR:
.CS
set x 0
-while {$x<10} {
- puts "x is $x"
- incr x
+\fBwhile\fR {$x<10} {
+ puts "x is $x"
+ incr x
}
.CE
.SH EXAMPLE
@@ -55,8 +55,8 @@ Read lines from a channel until we get to the end of the stream, and
print them out with a line-number prepended:
.CS
set lineCount 0
-while {[gets $chan line] >= 0} {
- puts "[incr lineCount]: $line"
+\fBwhile\fR {[gets $chan line] >= 0} {
+ puts "[incr lineCount]: $line"
}
.CE