Clarify.

1 files changed, 31 insertions, 17 deletions

diff --git a/doc/mathop.n b/doc/mathop.n
index f6d50f8..ae01583 100644
--- a/doc/mathop.n
+++ b/doc/mathop.n
@@ -1,10 +1,10 @@
 .\" -*- nroff -*-
-.\" Copyright (c) 2006 Donal K. Fellows.
+.\" Copyright (c) 2006-2007 Donal K. Fellows.
 .\"
 .\" See the file "license.terms" for information on usage and redistribution
 .\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 .\"
-.\" RCS: @(#) $Id: mathop.n,v 1.7 2007/11/01 23:36:46 dkf Exp $
+.\" RCS: @(#) $Id: mathop.n,v 1.8 2007/11/13 20:41:17 dkf Exp $
 .\"
 .so man.macros
 .TH mathop n 8.5 Tcl "Tcl Mathematical Operator Commands"
@@ -119,16 +119,28 @@ argument must be given.
 \fB%\fR \fInumber number\fR
 .
 Returns the integral modulus of the first argument with respect to the second.
-Each \fInumber\fR must have an integral value.
+Each \fInumber\fR must have an integral value. Note that Tcl defines this
+operation exactly even for negative numbers, so that the following equality
+holds true:
+.RS
+.CS
+(\fIx \fB/ \fIy\fR) \fB* \fIy \fB== \fIx \fB-\fR (\fIx \fB% \fIy\fR)
+.CE
+.RE
 .TP
 \fB**\fR ?\fInumber\fR ...?
 .
 Returns the result of raising each value to the power of the result of
 recursively operating on the result of processing the following arguments, so
-\fB** 2 3 4\fR is the same as \fB** 2 [** 3 4]\fR. Each \fInumber\fR may be
+.QW "\fB** 2 3 4\fR"
+is the same as
+.QW "\fB** 2 [** 3 4]\fR" .
+Each \fInumber\fR may be
 any numeric value, though the second number must not be fractional if the
 first is negative. If no arguments are given, the result will be one, and if
-only one argument is given, the result will be that argument.
+only one argument is given, the result will be that argument. The
+result will have an integral value only when all arguments are
+integral values.
 .TP
 \fB&\fR ?\fInumber\fR ...?
 .
@@ -140,8 +152,7 @@ result will be minus one.
 .
 Returns the bit-wise OR of each of the arbitrarily many arguments. Each
 \fInumber\fR must have an integral value. If no arguments are given, the
-result will be zero.
-.TP
+result will be zero..TP
 \fB^\fR ?\fInumber\fR ...?
 .
 Returns the bit-wise XOR of each of the arbitrarily many arguments. Each
@@ -150,22 +161,22 @@ result will be zero.
 .TP
 \fB<<\fR \fInumber number\fR
 .
-Returns the result of shifting the first argument left by the number of bits
-specified in the second argument. Each \fInumber\fR must have an integral
-value.
+Returns the result of bit-wise shifting the first argument left by the
+number of bits specified in the second argument. Each \fInumber\fR
+must have an integral value.
 .TP
 \fB>>\fR \fInumber number\fR
 .
-Returns the result of shifting the first argument right by the number of bits
-specified in the second argument. Each \fInumber\fR must have an integral
-value.
+Returns the result of bit-wise shifting the first argument right by
+the number of bits specified in the second argument. Each \fInumber\fR
+must have an integral value.
 .TP
 \fB==\fR ?\fIarg\fR ...?
 .
 Returns whether each argument is equal to the arguments on each side of it in
 the sense of the \fBexpr\fR == operator (\fIi.e.\fR, numeric comparison if
-possible). If fewer than two arguments are given, this operation always
-returns a true value.
+possible, exact string comparison otherwise). If fewer than two arguments
+are given, this operation always returns a true value.
 .TP
 \fBeq\fR ?\fIarg\fR ...?
 .
@@ -223,20 +234,23 @@ The simplest way to use the operators is often by using \fBnamespace path\fR
 to make the commands available. This has the advantage of not affecting the
 set of commands defined by the current namespace.
 .CS
-namespace path {::tcl::mathop ::tcl::mathfunc}
+namespace path {\fB::tcl::mathop\fR ::tcl::mathfunc}
 
 \fI# Compute the sum of some numbers\fR
 set sum [\fB+\fR 1 2 3]
 
 \fI# Compute the average of a list\fR
 set list {1 2 3 4 5 6}
-set mean [\fB/\fR [\fB+\fR {expand}$list] [double [llength $list]]]
+set mean [\fB/\fR [\fB+\fR {*}$list] [double [llength $list]]]
 
 \fI# Test for list membership\fR
 set gotIt [\fBin\fR 3 $list]
 
 \fI# Test to see if a value is within some defined range\fR
 set inRange [\fB<=\fR 1 $x 5]
+
+\fI# Test to see if a list is sorted\fR
+set sorted [\fB<=\fR {*}$list]
 .CE
 .SH "SEE ALSO"
 expr(n), mathfunc(n), namespace(n)