Added examples and more cross-references

1 files changed, 49 insertions, 9 deletions

diff --git a/doc/expr.n b/doc/expr.n
index b7425f1..5053bd1 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.12 2003/09/12 23:55:32 dkf Exp $
+'\" RCS: @(#) $Id: expr.n,v 1.13 2004/05/24 12:47:56 dkf Exp $
 '\" 
 .so man.macros
 .TH expr n 8.5 Tcl "Tcl Built-In Commands"
@@ -34,7 +34,7 @@ evaluates to 14.2.
 Tcl expressions differ from C expressions in the way that
 operands are specified.  Also, Tcl expressions support
 non-numeric operands and string comparisons.
-.SH OPERANDS
+.SS OPERANDS
 .PP
 A Tcl expression consists of a combination of operands, operators,
 and parentheses.
@@ -105,7 +105,7 @@ expr 2 + "$a.$b"	5.6
 expr 4*[llength "6 2"]	8
 expr {{word one} < "word $a"}	0\fR
 .CE
-.SH OPERATORS
+.SS OPERATORS
 .PP
 The valid operators are listed below, grouped in decreasing order
 of precedence:
@@ -199,7 +199,7 @@ depending on the value of \fB$v\fR.  Note, however, that this is
 only true if the entire expression is enclosed in braces;  otherwise
 the Tcl parser will evaluate both \fB[a]\fR and \fB[b]\fR before
 invoking the \fBexpr\fR command.
-.SH "MATH FUNCTIONS"
+.SS "MATH FUNCTIONS"
 .PP
 Tcl supports the following mathematical functions in expressions, all
 of which work solely with floating-point numbers unless otherwise noted:
@@ -326,7 +326,7 @@ if \fIarg\fR is a 32-bit number) if it is not one already.
 .PP
 In addition to these predefined functions, applications may
 define additional functions using \fBTcl_CreateMathFunc\fR().
-.SH "TYPES, OVERFLOW, AND PRECISION"
+.SS "TYPES, OVERFLOW, AND PRECISION"
 .PP
 All internal computations involving integers are done with the C type
 \fIlong\fR, and all internal computations involving floating-point are
@@ -362,8 +362,7 @@ example,
 \fBexpr 20.0/5.0\fR
 .CE
 returns \fB4.0\fR, not \fB4\fR.
-
-.SH "STRING OPERATIONS"
+.SS "STRING OPERATIONS"
 .PP
 String values may be used as operands of the comparison operators,
 although the expression evaluator tries to do comparisons as integer
@@ -386,7 +385,6 @@ possible, it isn't generally a good idea to use operators like \fB==\fR
 when you really want string comparison and the values of the
 operands could be arbitrary;  it's better in these cases to use
 the \fBeq\fR or \fBne\fR operators, or the \fBstring\fR command instead.
-
 .SH "PERFORMANCE CONSIDERATIONS"
 .PP
 Enclose expressions in braces for the best speed and the smallest
@@ -418,9 +416,51 @@ The most expensive code is required for
 unbraced expressions that contain command substitutions.
 These expressions must be implemented by generating new code
 each time the expression is executed.
+.SH EXAMPLES
+Define a procedure that computes an "interesting" mathematical
+function:
+.CS
+proc calc {x y} {
+    expr { ($x**2 - $y**2) / exp($x**2 + $y**2) }
+}
+.CE
+
+Convert polar coordinates into cartesian coordinates:
+.CS
+# convert from ($radius,$angle)
+set x [expr { $radius * cos($angle) }]
+set y [expr { $radius * sin($angle) }]
+.CE
+
+Convert cartesian coordinates into polar coordinates:
+.CS
+# convert from ($x,$y)
+set radius [expr { hypot($y, $x) }]
+set angle  [expr { atan2($y, $x) }]
+.CE
+
+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}}]"
+.CE
+
+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 {
+    [info exists ::env(SOME_ENV_VAR)] &&
+    [string is true -strict $::env(SOME_ENV_VAR)]
+}]
+.CE
+
+Generate a random integer in the range 0..99 inclusive:
+.CS
+set randNum [expr { int(100 * rand()) }]
+.CE
 
 .SH "SEE ALSO"
-array(n), string(n), Tcl(n)
+array(n), for(n), if(n), string(n), Tcl(n), while(n)
 
 .SH KEYWORDS
 arithmetic, boolean, compare, expression, fuzzy comparison