diff options
| -rw-r--r-- | ChangeLog | 2 | ||||
| -rw-r--r-- | doc/tcltest.n | 42 | ||||
| -rw-r--r-- | doc/tclvars.n | 9 | ||||
| -rw-r--r-- | doc/tell.n | 3 | ||||
| -rw-r--r-- | doc/time.n | 3 | ||||
| -rw-r--r-- | doc/trace.n | 18 | ||||
| -rw-r--r-- | doc/unset.n | 6 | ||||
| -rw-r--r-- | doc/uplevel.n | 10 | ||||
| -rw-r--r-- | doc/upvar.n | 16 | ||||
| -rw-r--r-- | doc/variable.n | 10 | ||||
| -rw-r--r-- | doc/vwait.n | 10 | ||||
| -rw-r--r-- | doc/while.n | 12 |
12 files changed, 69 insertions, 72 deletions
@@ -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 @@ -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] @@ -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 |