From cd7e7ec95e76bcb5bf66d7cc9e6d60aad70dba07 Mon Sep 17 00:00:00 2001 From: dkf Date: Wed, 27 Oct 2004 09:36:58 +0000 Subject: Many minor doc fixes --- ChangeLog | 4 ++++ doc/after.n | 8 ++++---- doc/append.n | 4 ++-- doc/binary.n | 10 +++++----- doc/break.n | 4 ++-- doc/catch.n | 6 ++---- doc/cd.n | 6 +++--- doc/clock.n | 32 ++++++++++++++++---------------- doc/close.n | 4 ++-- doc/concat.n | 10 +++++----- doc/continue.n | 4 ++-- doc/dde.n | 4 ++-- doc/encoding.n | 4 ++-- doc/eof.n | 8 +++----- doc/error.n | 4 ++-- doc/eval.n | 26 +++++++++++++++++++++++--- doc/exec.n | 38 +++++++++++++++++++------------------- doc/exit.n | 4 ++-- doc/expr.n | 30 +++++++++++++++--------------- doc/string.n | 6 +++--- 20 files changed, 118 insertions(+), 98 deletions(-) diff --git a/ChangeLog b/ChangeLog index c53a1bf..24a8d36 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2004-10-27 Donal K. Fellows + + * doc/[a-e]*.n: Many small general documentation fixes. + 2004-10-26 David Gravereaux * generic/tclPipe.c (TclCleanupChildren): bad cast of resolvedPid diff --git a/doc/after.n b/doc/after.n index 2dd9f2d..6e6ab1a 100644 --- a/doc/after.n +++ b/doc/after.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: after.n,v 1.4 2004/04/21 12:05:35 dkf Exp $ +'\" RCS: @(#) $Id: after.n,v 1.5 2004/10/27 09:36:58 dkf Exp $ '\" .so man.macros .TH after n 7.5 Tcl "Tcl Built-In Commands" @@ -108,7 +108,7 @@ seconds: .CS proc sleep {N} { - after [expr {int($N * 1000)}] + \fBafter\fR [expr {int($N * 1000)}] } .CE @@ -116,7 +116,7 @@ This arranges for the command \fIwake_up\fR to be run in eight hours (providing the event loop is active at that time): .CS -after [expr {1000 * 60 * 60 * 8}] wake_up +\fBafter\fR [expr {1000 * 60 * 60 * 8}] wake_up .CE The following command can be used to do long-running calculations (as @@ -133,7 +133,7 @@ responsive during a slow task. .CS proc doOneStep {} { if {[::my_calc::one_step]} { - after idle [list after 0 doOneStep] + \fBafter\fR idle [list \fBafter\fR 0 doOneStep] } } doOneStep diff --git a/doc/append.n b/doc/append.n index d829c71..cf03418 100644 --- a/doc/append.n +++ b/doc/append.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: append.n,v 1.5 2004/05/18 21:13:40 dkf Exp $ +'\" RCS: @(#) $Id: append.n,v 1.6 2004/10/27 09:36:58 dkf Exp $ '\" .so man.macros .TH append n "" Tcl "Tcl Built-In Commands" @@ -34,7 +34,7 @@ Building a string of comma-separated numbers piecemeal using a loop. .CS set var 0 for {set i 1} {$i<=10} {incr i} { - append var "," $i + \fBappend\fR var "," $i } puts $var # Prints 0,1,2,3,4,5,6,7,8,9,10 diff --git a/doc/binary.n b/doc/binary.n index 2c66eef..54bf6c4 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.20 2004/08/31 15:19:35 dkf Exp $ +'\" RCS: @(#) $Id: binary.n,v 1.21 2004/10/27 09:36:58 dkf Exp $ '\" .so man.macros .TH binary n 8.0 Tcl "Tcl Built-In Commands" @@ -745,21 +745,21 @@ universal. To transfer floating-point numbers portably between all architectures, use their textual representation (as produced by \fBformat\fR) instead. .SH EXAMPLES -This is a procedure write a Tcl string to a binary-encoded channel as +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} { set data [encoding convertto utf-8 $string] - puts -nonewline [binary format Ia* \e + puts -nonewline [\fBbinary\fR format Ia* \e [string length $data] $data] } .CE - +.PP This procedure reads a string from a channel that was written by the previously presented \fBwriteString\fR procedure: .CS proc readString {channel} { - if {![binary scan [read $channel 4] I length]} { + if {![\fBbinary\fR scan [read $channel 4] I length]} { error "missing length" } set data [read $channel $length] diff --git a/doc/break.n b/doc/break.n index b0350ad..53cae77 100644 --- a/doc/break.n +++ b/doc/break.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: break.n,v 1.6 2004/09/18 17:01:06 dkf Exp $ +'\" RCS: @(#) $Id: break.n,v 1.7 2004/10/27 09:36:58 dkf Exp $ '\" .so man.macros .TH break n "" Tcl "Tcl Built-In Commands" @@ -34,7 +34,7 @@ Print a line for each of the integers from 0 to 5: .CS for {set x 0} {$x<10} {incr x} { if {$x > 5} { - break + \fBbreak\fR } puts "x is $x" } diff --git a/doc/catch.n b/doc/catch.n index 4414893..54eb35c 100644 --- a/doc/catch.n +++ b/doc/catch.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: catch.n,v 1.11 2004/09/18 17:01:06 dkf Exp $ +'\" RCS: @(#) $Id: catch.n,v 1.12 2004/10/27 09:36:58 dkf Exp $ '\" .so man.macros .TH catch n "8.5" Tcl "Tcl Built-In Commands" @@ -80,12 +80,10 @@ above. .VE 8.5 .SH EXAMPLES - The \fBcatch\fR command may be used in an \fBif\fR to branch based on the success of a script. - .CS -if { [catch {open $someFile w} fid] } { +if { [\fBcatch\fR {open $someFile w} fid] } { puts stderr "Could not open $someFile for writing\\n$fid" exit 1 } diff --git a/doc/cd.n b/doc/cd.n index 894abbd..7cf138a 100644 --- a/doc/cd.n +++ b/doc/cd.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: cd.n,v 1.5 2004/05/25 20:27:38 dkf Exp $ +'\" RCS: @(#) $Id: cd.n,v 1.6 2004/10/27 09:36:58 dkf Exp $ '\" .so man.macros .TH cd n "" Tcl "Tcl Built-In Commands" @@ -29,13 +29,13 @@ and (in a threaded environment) all threads. .SH EXAMPLES Change to the home directory of the user \fBfred\fR: .CS -cd ~fred +\fBcd\fR ~fred .CE .PP Change to the directory \fBlib\fR that is a sibling directory of the current one: .CS -cd ../lib +\fBcd\fR ../lib .CE .SH "SEE ALSO" diff --git a/doc/clock.n b/doc/clock.n index c63d6c5..c1f1f4d 100644 --- a/doc/clock.n +++ b/doc/clock.n @@ -8,7 +8,7 @@ .SH "NAME" clock \- Obtain and manipulate dates and times .SH "SYNOPSIS" -package require \fBTcl 8.5\fR +package require \fBTcl 8.5\fR .sp \fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI-option value\fR? .sp @@ -190,10 +190,10 @@ that observe summer time (Daylight Saving Time). For example, the following code sets the value of \fBx\fR to \fB04:00:00\fR because the clock has changed in the interval in question. .CS -set s [clock scan {2004-10-30 05:00:00} \\ +set s [\fBclock\fR scan {2004-10-30 05:00:00} \\ -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York] -set a [clock add $s 24 hours -timezone :America/New_York] -set x [clock format $a \\ +set a [\fBclock\fR add $s 24 hours -timezone :America/New_York] +set x [\fBclock\fR format $a \\ -format {%H:%M:%S} -timezone :America/New_York] .CE .PP @@ -209,10 +209,10 @@ the time changes at the start or end of summer time (Daylight Saving Time) results in the \fIsame local time\fR on the day in question. For instance, the following code sets the value of \fBx\fR to \fB05:00:00\fR. .CS -set s [clock scan {2004-10-30 05:00:00} \\ +set s [\fBclock\fR scan {2004-10-30 05:00:00} \\ -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York] -set a [clock add $s 1 day -timezone :America/New_York] -set x [clock format $a \\ +set a [\fBclock\fR add $s 1 day -timezone :America/New_York] +set x [\fBclock\fR format $a \\ -format {%H:%M:%S} -timezone :America/New_York] .CE .PP @@ -223,10 +223,10 @@ Daylight Saving Time change using US rules), the time is converted as if the clock had not changed. Thus, the following code will set the value of \fBx\fR to \fB03:30:00\fR. .CS -set s [clock scan {2004-04-03 02:30:00} \\ +set s [\fBclock\fR scan {2004-04-03 02:30:00} \\ -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York] -set a [clock add $s 1 day -timezone :America/New_York] -set x [clock format $a \\ +set a [\fBclock\fR add $s 1 day -timezone :America/New_York] +set x [\fBclock\fR format $a \\ -format {%H:%M:%S} -timezone :America/New_York] .CE .PP @@ -234,9 +234,9 @@ Adding a given number of days or weeks works correctly across the conversion between the Julian and Gregorian calendars; the omitted days are skipped. The following code sets \fBz\fR to \fB1752-09-14\fR. .CS -set x [clock scan 1752-09-02 -format %Y-%m-%d -locale en_US] -set y [clock add $x 1 day -locale en_US] -set z [clock format $y -format %Y-%m-%d -locale en_US] +set x [\fBclock\fR scan 1752-09-02 -format %Y-%m-%d -locale en_US] +set y [\fBclock\fR add $x 1 day -locale en_US] +set z [\fBclock\fR format $y -format %Y-%m-%d -locale en_US] .CE .PP In the bizarre case that adding the given number of days yields a date @@ -794,7 +794,7 @@ an integer clock value. Only the date in this value is used, not the time. This is useful for determining the time on a specific day or doing other date-relative conversions. .PP -The \fIinputString\fR argument consists of zero or more specifications of the +The \fIinputString\fR argument consists of zero or more specifications of the following form: .TP \fItime\fR @@ -846,9 +846,9 @@ years. This means that when crossing the daylight savings time boundary, different results will be given for \fBclock scan "1 day"\fR and \fBclock scan "24 hours"\fR: .CS -% clock scan "1 day" -base [clock scan 1999-10-31] +% \fBclock\fR scan "1 day" -base [\fBclock\fR scan 1999-10-31] 941443200 -% clock scan "24 hours" -base [clock scan 1999-10-31] +% \fBclock\fR scan "24 hours" -base [\fBclock\fR scan 1999-10-31] 941439600 .CE .SH "SEE ALSO" diff --git a/doc/close.n b/doc/close.n index 78020b0..c14a480 100644 --- a/doc/close.n +++ b/doc/close.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: close.n,v 1.7 2004/09/06 09:44:56 dkf Exp $ +'\" RCS: @(#) $Id: close.n,v 1.8 2004/10/27 09:36:58 dkf Exp $ '\" .so man.macros .TH close n 7.5 Tcl "Tcl Built-In Commands" @@ -73,7 +73,7 @@ proc withOpenFile {filename channelVar script} { catch { uplevel 1 $script } result options - close $chan + \fBclose\fR $chan return -options $options $result } .CE diff --git a/doc/concat.n b/doc/concat.n index dded6a2..882ebbc 100644 --- a/doc/concat.n +++ b/doc/concat.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: concat.n,v 1.5 2004/05/22 00:19:37 dkf Exp $ +'\" RCS: @(#) $Id: concat.n,v 1.6 2004/10/27 09:36:58 dkf Exp $ '\" .so man.macros .TH concat n 8.3 Tcl "Tcl Built-In Commands" @@ -28,19 +28,19 @@ if no \fIarg\fRs are supplied, the result is an empty string. .SH EXAMPLES Although \fBconcat\fR will concatenate lists (so the command: .CS -concat a b {c d e} {f {g h}} +\fBconcat\fR a b {c d e} {f {g h}} .CE will return "\fBa b c d e f {g h}\fR" as its result), it will also concatenate things that are not lists, and hence the command: .CS -concat " a b {c " d " e} f" +\fBconcat\fR " a b {c " d " e} f" .CE will return "\fBa b {c d e} f\fR" as its result. - +.PP Note that the concatenation does not remove spaces from the middle of its arguments, so the command: .CS -concat "a b c" { d e f } +\fBconcat\fR "a b c" { d e f } .CE will return "\fBa b c d e f\fR" (i.e. with three spaces between the \fBa\fR, the \fBb\fR and the \fBc\fR). diff --git a/doc/continue.n b/doc/continue.n index 4fca93e..d2240b5 100644 --- a/doc/continue.n +++ b/doc/continue.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: continue.n,v 1.6 2004/09/18 17:01:06 dkf Exp $ +'\" RCS: @(#) $Id: continue.n,v 1.7 2004/10/27 09:36:58 dkf Exp $ '\" .so man.macros .TH continue n "" Tcl "Tcl Built-In Commands" @@ -34,7 +34,7 @@ Print a line for each of the integers from 0 to 10 \fIexcept\fR 5: .CS for {set x 0} {$x<10} {incr x} { if {$x == 5} { - continue + \fBcontinue\fR } puts "x is $x" } diff --git a/doc/dde.n b/doc/dde.n index 2f46adb..b984a75 100644 --- a/doc/dde.n +++ b/doc/dde.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: dde.n,v 1.14 2004/08/31 15:19:36 dkf Exp $ +'\" RCS: @(#) $Id: dde.n,v 1.15 2004/10/27 09:36:58 dkf Exp $ '\" .so man.macros .TH dde n 1.2 dde "Tcl Bundled Packages" @@ -149,7 +149,7 @@ This asks Internet Explorer (which must already be running) to go to a particularly important website: .CS package require dde -dde execute iexplore WWW_OpenURL http://www.tcl.tk/ +\fBdde\fR execute iexplore WWW_OpenURL http://www.tcl.tk/ .CE .SH "SEE ALSO" diff --git a/doc/encoding.n b/doc/encoding.n index fcbb67f..e97db96 100644 --- a/doc/encoding.n +++ b/doc/encoding.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: encoding.n,v 1.4 2003/06/24 21:26:02 dkf Exp $ +'\" RCS: @(#) $Id: encoding.n,v 1.5 2004/10/27 09:36:58 dkf Exp $ '\" .so man.macros .TH encoding n "8.1" Tcl "Tcl Built-In Commands" @@ -71,7 +71,7 @@ of the original string. The \fBencoding\fR command can be used to convert this string to the expected Japanese Unicode characters. For example, .CS - set s [encoding convertfrom euc-jp "\\xA4\\xCF"] +set s [\fBencoding\fR convertfrom euc-jp "\\xA4\\xCF"] .CE would return the Unicode string "\\u306F", which is the Hiragana letter HA. diff --git a/doc/eof.n b/doc/eof.n index dca00c9..eed48cb 100644 --- a/doc/eof.n +++ b/doc/eof.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: eof.n,v 1.5 2004/05/28 12:09:59 dkf Exp $ +'\" RCS: @(#) $Id: eof.n,v 1.6 2004/10/27 09:36:58 dkf Exp $ '\" .so man.macros .TH eof n 7.5 Tcl "Tcl Built-In Commands" @@ -23,19 +23,17 @@ Returns 1 if an end of file condition occurred during the most recent input operation on \fIchannelId\fR (such as \fBgets\fR), 0 otherwise. .PP -.VS \fIChannelId\fR must be an identifier for an open channel such as a Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR), the return value from an invocation of \fBopen\fR or \fBsocket\fR, or the result of a channel creation command provided by a Tcl extension. -.VE .SH EXAMPLES Read and print out the contents of a file line-by-line: .CS set f [open somefile.txt] while {1} { set line [gets $f] - if {[eof $f]} { + if {[\fBeof\fR $f]} { close $f break } @@ -50,7 +48,7 @@ fconfigure $f -translation binary set recordSize 40 while {1} { set record [read $f $recordSize] - if {[eof $f]} { + if {[\fBeof\fR $f]} { close $f break } diff --git a/doc/error.n b/doc/error.n index b992d47..35bad4d 100644 --- a/doc/error.n +++ b/doc/error.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: error.n,v 1.5 2004/09/18 17:01:06 dkf Exp $ +'\" RCS: @(#) $Id: error.n,v 1.6 2004/10/27 09:36:58 dkf Exp $ '\" .so man.macros .TH error n "" Tcl "Tcl Built-In Commands" @@ -57,7 +57,7 @@ error generated by the command. Generate an error if a basic mathematical operation fails: .CS if {1+2 != 3} { - error "something is very wrong with addition" + \fBerror\fR "something is very wrong with addition" } .CE diff --git a/doc/eval.n b/doc/eval.n index f027c76..ed46f0c 100644 --- a/doc/eval.n +++ b/doc/eval.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: eval.n,v 1.5 2004/05/28 10:37:04 dkf Exp $ +'\" RCS: @(#) $Id: eval.n,v 1.6 2004/10/27 09:36:58 dkf Exp $ '\" .so man.macros .TH eval n "" Tcl "Tcl Built-In Commands" @@ -27,7 +27,7 @@ Tcl interpreter recursively, and returns the result of that evaluation (or any error generated by it). Note that the \fBlist\fR command quotes sequences of words in such a way that they are not further expanded by the \fBeval\fR command. -.SH EXAMPLE +.SH EXAMPLES Often, it is useful to store a fragment of a script in a variable and execute it later on with extra values appended. This technique is used in a number of places throughout the Tcl core (e.g. in \fBfcopy\fR, @@ -46,9 +46,10 @@ for {set i 0} {$i<10} {incr i} { # Introduce a random delay after [expr {int(5000 * rand())}] update ;# Check for the asynch log switch - eval $script $i [clock clicks] + \fBeval\fR $script $i [clock clicks] } .CE +.PP .VS 8.5 Note that in the most common case (where the script fragment is actually just a list of words forming a command prefix), it is better @@ -56,6 +57,25 @@ to use \fB{expand}$script\fR when doing this sort of invokation pattern. It is less general than the \fBeval\fR command, and hence easier to make robust in practice. .VE 8.5 +The following procedure acts in a way that is analogous to the +\fBlappend\fR command, except it inserts the argument values at the +start of the list in the variable: +.CS +proc lprepend {varName args} { + upvar 1 $varName var + # Ensure that the variable exists and contains a list + lappend var + # Now we insert all the arguments in one go + set var [\fBeval\fR [list linsert $var 0] $args] +} +.CE +.VS 8.5 +However, the last line would now normally be written without +\fBeval\fR, like this: +.CS +set var [linsert $var 0 {expand}$args] +.CE +.VE 8.5 .SH KEYWORDS concatenate, evaluate, script diff --git a/doc/exec.n b/doc/exec.n index 62ff872..43893d8 100644 --- a/doc/exec.n +++ b/doc/exec.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: exec.n,v 1.11 2004/08/31 15:19:36 dkf Exp $ +'\" RCS: @(#) $Id: exec.n,v 1.12 2004/10/27 09:36:58 dkf Exp $ '\" .so man.macros .TH exec n 8.5 Tcl "Tcl Built-In Commands" @@ -330,18 +330,18 @@ The \fBexec\fR command is fully functional and works as described. .SH "UNIX EXAMPLES" Here are some examples of the use of the \fBexec\fR command on Unix. - +.PP To execute a simple program and get its result: .CS -exec uname -a +\fBexec\fR uname -a .CE - +.PP To execute a program that can return a non-zero result, you should wrap the call to \fBexec\fR in \fBcatch\fR and check what the contents of the global \fBerrorCode\fR variable is if you have an error: .CS set status 0 -if {[catch {exec grep foo bar.txt} results]} { +if {[catch {\fBexec\fR grep foo bar.txt} results]} { if {[lindex $::errorCode 0] eq "CHILDSTATUS"} { set status [lindex $::errorCode 2] } else { @@ -349,7 +349,7 @@ if {[catch {exec grep foo bar.txt} results]} { } } .CE - +.PP When translating a command from a Unix shell invocation, care should be taken over the fact that single quote characters have no special significance to Tcl. Thus: @@ -358,55 +358,55 @@ awk '{sum += $1} END {print sum}' numbers.list .CE would be translated into something like: .CS -exec awk {{sum += $1} END {print sum}} numbers.list +\fBexec\fR awk {{sum += $1} END {print sum}} numbers.list .CE - +.PP If you are converting invocations involving shell globbing, you should remember that Tcl does not handle globbing or expand things into multiple arguments by default. Instead you should write things like this: .CS -exec ls -l {expand}[glob *.tcl] +\fBexec\fR ls -l {expand}[glob *.tcl] .CE - +.PP .SH "WINDOWS EXAMPLES" Here are some examples of the use of the \fBexec\fR command on Windows. - +.PP To start an instance of \fInotepad\fR editing a file without waiting for the user to finish editing the file: .CS -exec notepad myfile.txt & +\fBexec\fR notepad myfile.txt & .CE - +.PP To print a text file using \fInotepad\fR: .CS -exec notepad /p myfile.txt +\fBexec\fR notepad /p myfile.txt .CE - +.PP If a program calls other programs, such as is common with compilers, then you may need to resort to batch files to hide the console windows that sometimes pop up: .CS -exec cmp.bat somefile.c -o somefile +\fBexec\fR cmp.bat somefile.c -o somefile .CE With the file \fIcmp.bat\fR looking something like: .CS @gcc %1 %2 %3 %4 %5 %6 %7 %8 %9 .CE - +.PP Sometimes you need to be careful, as different programs may have the same name and be in the path. It can then happen that typing a command at the DOS prompt finds \fIa different program\fR than the same command run via \fBexec\fR. This is because of the (documented) differences in behaviour between \fBexec\fR and DOS batch files. - +.PP When in doubt, use the command \fBauto_execok\fR: it will return the complete path to the program as seen by the \fBexec\fR command. This applies especially when you want to run "internal" commands like \fIdir\fR from a Tcl script (if you just want to list filenames, use the \fBglob\fR command.) To do that, use this: .CS -exec {expand}[auto_execok dir] *.tcl +\fBexec\fR {expand}[auto_execok dir] *.tcl .CE .SH "SEE ALSO" diff --git a/doc/exit.n b/doc/exit.n index 5caf6a9..394ad05 100644 --- a/doc/exit.n +++ b/doc/exit.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: exit.n,v 1.4 2004/05/24 13:00:55 dkf Exp $ +'\" RCS: @(#) $Id: exit.n,v 1.5 2004/10/27 09:36:58 dkf Exp $ '\" .so man.macros .TH exit n "" Tcl "Tcl Built-In Commands" @@ -42,7 +42,7 @@ if {[catch {main} msg]} { } # Reserve code 1 for "expected" error exits... - exit 2 + \fBexit\fR 2 } .CE diff --git a/doc/expr.n b/doc/expr.n index d3135c8..6779c93 100644 --- a/doc/expr.n +++ b/doc/expr.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: expr.n,v 1.17 2004/10/26 10:24:59 dkf Exp $ +'\" RCS: @(#) $Id: expr.n,v 1.18 2004/10/27 09:36:58 dkf Exp $ '\" .so man.macros .TH expr n 8.5 Tcl "Tcl Built-In Commands" @@ -89,7 +89,7 @@ functions. .LP Where the above substitutions occur (e.g. inside quoted strings), they are performed by the expression's instructions. -However, the command parser may already have performed one layer of +However, the command parser may already have performed one round of substitution before the expression processor was called. As discussed below, it is usually best to enclose expressions in braces to prevent the command parser from performing substitutions @@ -431,42 +431,42 @@ Define a procedure that computes an "interesting" mathematical function: .CS proc calc {x y} { - expr { ($x**2 - $y**2) / exp($x**2 + $y**2) } + \fBexpr\fR { ($x**2 - $y**2) / exp($x**2 + $y**2) } } .CE - +.PP Convert polar coordinates into cartesian coordinates: .CS # convert from ($radius,$angle) -set x [expr { $radius * cos($angle) }] -set y [expr { $radius * sin($angle) }] +set x [\fBexpr\fR { $radius * cos($angle) }] +set y [\fBexpr\fR { $radius * sin($angle) }] .CE - +.PP Convert cartesian coordinates into polar coordinates: .CS # convert from ($x,$y) -set radius [expr { hypot($y, $x) }] -set angle [expr { atan2($y, $x) }] +set radius [\fBexpr\fR { hypot($y, $x) }] +set angle [\fBexpr\fR { atan2($y, $x) }] .CE - +.PP Print a message describing the relationship of two string values to each other: .CS -puts "a and b are [expr {$a eq $b ? {equal} : {different}}]" +puts "a and b are [\fBexpr\fR {$a eq $b ? {equal} : {different}}]" .CE - +.PP Set a variable to whether an environment variable is both defined at all and also set to a true boolean value: .CS -set isTrue [expr { +set isTrue [\fBexpr\fR { [info exists ::env(SOME_ENV_VAR)] && [string is true -strict $::env(SOME_ENV_VAR)] }] .CE - +.PP Generate a random integer in the range 0..99 inclusive: .CS -set randNum [expr { int(100 * rand()) }] +set randNum [\fBexpr\fR { int(100 * rand()) }] .CE .SH "SEE ALSO" diff --git a/doc/string.n b/doc/string.n index 0bfe19b..02e5ed2 100644 --- a/doc/string.n +++ b/doc/string.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: string.n,v 1.22 2004/10/25 22:11:11 dkf Exp $ +'\" RCS: @(#) $Id: string.n,v 1.23 2004/10/27 09:36:58 dkf Exp $ '\" .so man.macros .TH string n 8.1 Tcl "Tcl Built-In Commands" @@ -321,11 +321,11 @@ single character other than these. Test if the string in the variable \fIstring\fR is a proper non-empty prefix of the string \fBfoobar\fR. .CS -set length [string length $string] +set length [\fBstring\fR length $string] if {$length == 0} { set isPrefix 0 } else { - set isPrefix [string equal -length $string $string "foobar"] + set isPrefix [\fBstring\fR equal -length $string $string "foobar"] } .CE -- cgit v0.12