Clarify.

2 files changed, 45 insertions, 27 deletions

diff --git a/ChangeLog b/ChangeLog
index 22d5c43..ba8d404 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,8 +1,12 @@
+2007-11-13  Donal K. Fellows  <dkf@users.sf.net>
+
+	* doc/mathop.n: Clarify definitions of some operations.
+
 2007-11-13  Miguel Sofer  <msofer@users.sf.net>
 
 	* unix/tclUnixInit.c: the TCL_NO_STACK_CHECK was being incorrectly
-	undefined here; this should be set (or not) in the compile
-	options, it is used elsewhere and needs to be consistent. 
+	undefined here; this should be set (or not) in the compile options, it
+	is used elsewhere and needs to be consistent.
 
 2007-11-13  Pat Thoyts  <patthoyts@users.sourceforge.net>
 
@@ -39,7 +43,7 @@
 
 2007-11-12  Miguel Sofer  <msofer@users.sf.net>
 
-	* generic/tclBasic.c:     New macro TclResetResult, new iPtr flag 
+	* generic/tclBasic.c:     New macro TclResetResult, new iPtr flag
 	* generic/tclExecute.c:   bit INTERP_RESULT_UNCLEAN: shortcut for
 	* generic/tclInt.h:       Tcl_ResetResult for the "normal" case:
 	* generic/tclProc.c:      TCL_OK, no return options, no errorCode
@@ -49,8 +53,8 @@
 
 	THIS PATCH WAS REVERTED: initial (mis)measurements overstated the
 	perfomance wins, which turn out to be tiny. Not worth the
-	complication. 
-	
+	complication.
+
 2007-11-11  Jeff Hobbs  <jeffh@ActiveState.com>
 
 	* generic/tclCompCmds.c, generic/tclCompile.c, generic/tclCompile.h:
@@ -64,11 +68,11 @@
 2007-11-11  Miguel Sofer  <msofer@users.sf.net>
 
 	* generic/tclResult.c (ResetObjResult): clarify the logic.
-	
+
 	* generic/tclBasic.c:       Increased usage of macros to detect
-	* generic/tclBinary.c:      and take advantage of objTypes. Added 
+	* generic/tclBinary.c:      and take advantage of objTypes. Added
 	* generic/tclClock.c:       macros TclGet(Int|Long)FromObj,
-	* generic/tclCmdAH.c:       TclGetIntForIndexM and TclListObjLength, 
+	* generic/tclCmdAH.c:       TclGetIntForIndexM and TclListObjLength,
 	* generic/tclCmdIL.c:       modified TclListObjGetElements.
 	* generic/tclCmdMZ.c:
 	* generic/tclCompCmds.c:    The TclGetInt* macros are only a shortcut
@@ -77,8 +81,8 @@
 	* generic/tclDictObj.c:     also to other cases.
 	* generic/tclExecute.c:
 	* generic/tclGet.c:         As this patch touches many files it has
-	* generic/tclIO.c:          been recorded as [Patch 1830038] in order to
-	* generic/tclIOCmd.c:       facilitate reviewing.
+	* generic/tclIO.c:          been recorded as [Patch 1830038] in order
+	* generic/tclIOCmd.c:       to facilitate reviewing.
 	* generic/tclIOGT.c:
 	* generic/tclIndexObj.c:
 	* generic/tclInt.h:
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)