summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2004-10-27 09:36:58 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2004-10-27 09:36:58 (GMT)
commitcd7e7ec95e76bcb5bf66d7cc9e6d60aad70dba07 (patch)
tree2f66883fc243d05145536a48036f61275d482016
parentdfe0bb63c25ec4b9669b67071a6540448d5a7379 (diff)
downloadtcl-cd7e7ec95e76bcb5bf66d7cc9e6d60aad70dba07.zip
tcl-cd7e7ec95e76bcb5bf66d7cc9e6d60aad70dba07.tar.gz
tcl-cd7e7ec95e76bcb5bf66d7cc9e6d60aad70dba07.tar.bz2
Many minor doc fixes
-rw-r--r--ChangeLog4
-rw-r--r--doc/after.n8
-rw-r--r--doc/append.n4
-rw-r--r--doc/binary.n10
-rw-r--r--doc/break.n4
-rw-r--r--doc/catch.n6
-rw-r--r--doc/cd.n6
-rw-r--r--doc/clock.n32
-rw-r--r--doc/close.n4
-rw-r--r--doc/concat.n10
-rw-r--r--doc/continue.n4
-rw-r--r--doc/dde.n4
-rw-r--r--doc/encoding.n4
-rw-r--r--doc/eof.n8
-rw-r--r--doc/error.n4
-rw-r--r--doc/eval.n26
-rw-r--r--doc/exec.n38
-rw-r--r--doc/exit.n4
-rw-r--r--doc/expr.n30
-rw-r--r--doc/string.n6
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 <donal.k.fellows@man.ac.uk>
+
+ * doc/[a-e]*.n: Many small general documentation fixes.
+
2004-10-26 David Gravereaux <davygrvy@pobox.com>
* 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