docs

diff --git a/doc/matrices.texi b/doc/matrices.texi
index d0e3b7be55ae4b8d61d96e1fd5936ffa5e8eac14..8adf29b035f862e16bd80dc2e02566456e9922e3 100644 (file)
--- a/doc/matrices.texi
+++ b/doc/matrices.texi
@@ -1120,10 +1120,23 @@ Examples:
 
 The matrix language support numerous functions in multiple categories.
 The following subsections document each of the currently supported
 
 The matrix language support numerous functions in multiple categories.
 The following subsections document each of the currently supported

-functions.  In the descriptions, function arguments that must be
-scalars are given names beginning with @var{s}, those that must be
-vectors are given names beginning with @var{v}, and general matrix
-arguments are given names beginning with @var{m}.
+functions.  The first letter of each parameter's name indicate the
+required argument type:
+
+@table @samp
+@item s
+Any scalar.
+
+@item n
+A scalar with a nonnegative integer value.  (Non-integers are rounded
+down to the nearest integer.)
+
+@item v
+A row or column vector.
+
+@item m
+A matrix.
+@end table

 
 @node Matrix Elementwise Functions
 @subsubsection Elementwise Functions
 
 @node Matrix Elementwise Functions
 @subsubsection Elementwise Functions


@@ -1179,7 +1192,6 @@ Takes the square root of each element of @var{m}, which must not be
 negative.
 @end deftypefn
 
 negative.
 @end deftypefn
 

-

 @node Matrix Logical Functions
 @subsubsection Logical Functions
 
 @node Matrix Logical Functions
 @subsubsection Logical Functions
 


@@ -1196,105 +1208,143 @@ nonzero, or 0 if all of them are zero.
 @node Matrix Construction Functions
 @subsubsection Matrix Construction Functions
 
 @node Matrix Construction Functions
 @subsubsection Matrix Construction Functions
 

-@deftypefn {Matrix Function} {} BLOCK (@var{m1}, @var{m2}, @dots{})
+@deftypefn {Matrix Function} {} BLOCK (@var{m1}, @dots{}, @var{mn})
+Returns a block diagonal matrix with as many rows as the sum of its
+arguments' row counts and as many columns as the sum of their columns.
+Each argument matrix is placed along the main diagonal of the result,
+and all other elements are zero.

 @end deftypefn
 
 @end deftypefn
 

-@deftypefn {Matrix Function} {} IDENT (@var{s})
-@deftypefnx {Matrix Function} {} IDENT (@var{sr}, @var{sc})
+@deftypefn {Matrix Function} {} IDENT (@var{n})
+@deftypefnx {Matrix Function} {} IDENT (@var{nr}, @var{nc})
+Returns an identity matrix, whose main diagonal elements are one and
+whose other elements are zero.  The returned matrix has @var{n} rows
+and columns or @var{nr} rows and @var{nc} columns, respectively.

 @end deftypefn
 
 @end deftypefn
 

-
-@deftypefn {Matrix Function} {} MAGIC (@var{m})
+@deftypefn {Matrix Function} {} MAGIC (@var{n})
+Returns an @math{@var{n}@times{}@var{n}} matrix that contains each of
+the integers @math{1@dots{}@var{n}} once, in which each column, each
+row, and each diagonal sums to @math{n(n^2+1)/2}.  There are many
+magic squares with given dimensions, but this function always returns
+the same one for a given value of @var{n}.

 @end deftypefn
 
 @end deftypefn
 

-
-@deftypefn {Matrix Function} {} MAKE (@var{sr}, @var{sc}, @var{sv})
+@deftypefn {Matrix Function} {} MAKE (@var{nr}, @var{nc}, @var{s})
+Returns an @math{@var{nr}@times{}@var{nc}} matrix whose elements are
+all @var{s}.

 @end deftypefn
 
 @end deftypefn
 

-

 @deftypefn {Matrix Function} {} MDIAG (@var{v})
 @deftypefn {Matrix Function} {} MDIAG (@var{v})

+Returns a @math{|@var{v}|@times{}|@var{v}|} matrix whose main diagonal
+comes from @var{v} and whose other elements are zero.

 @end deftypefn
 
 @end deftypefn
 

-@deftypefn {Matrix Function} {} RESHAPE (@var{m}, @var{sr}, @var{sc})
+@deftypefn {Matrix Function} {} RESHAPE (@var{m}, @var{nr}, @var{nc})
+Returns an @math{@var{nr}@times{}@var{nc}} matrix whose elements come
+from @var{m}, which must have the same number of elements as the new
+matrix, copying elements from @var{m} to the new matrix row by row.

 @end deftypefn
 
 @end deftypefn
 

-@deftypefn {Matrix Function} {} TRANSPOS (@var{m})
-@deftypefnx {Matrix Function} {} T (@var{m})
+@deftypefn {Matrix Function} {} T (@var{m})
+@deftypefnx {Matrix Function} {} TRANSPOS (@var{m})
+Returns @var{m} with rows exchanged for columns.

 @end deftypefn
 
 @end deftypefn
 

-@deftypefn {Matrix Function} {} UNIFORM (@var{sr}, @var{sc})
+@deftypefn {Matrix Function} {} UNIFORM (@var{nr}, @var{nc})
+Returns a @math{@var{nr}@times{}@var{nc}} matrix in which each element
+is randomly chosen from a uniform distribution of real numbers between
+0 and 1.

 @end deftypefn
 
 @node Matrix Minimum and Maximum and Sum Functions
 @subsubsection Minimum, Maximum, and Sum Functions
 
 @end deftypefn
 
 @node Matrix Minimum and Maximum and Sum Functions
 @subsubsection Minimum, Maximum, and Sum Functions
 

-@deftypefn {Matrix Function} {} CMAX (@var{m})
-@end deftypefn
-

 @deftypefn {Matrix Function} {} CMIN (@var{m})
 @deftypefn {Matrix Function} {} CMIN (@var{m})

+@deftypefnx {Matrix Function} {} CMAX (@var{m})
+@deftypefnx {Matrix Function} {} CSUM (@var{m})
+@deftypefnx {Matrix Function} {} CSSQ (@var{m})
+Returns a row vector with the same number of columns as @var{m}, in
+which each element is the minimum, maximum, sum, or sum of squares,
+respectively, of the elements in the same column of @var{m}.

 @end deftypefn
 
 @end deftypefn
 

-@deftypefn {Matrix Function} {} CSSQ (@var{m})
-@end deftypefn
-
-@deftypefn {Matrix Function} {} CSUM (@var{m})
-@end deftypefn
-
-@deftypefn {Matrix Function} {} MMAX (@var{m})
-@end deftypefn
-
-

 @deftypefn {Matrix Function} {} MMIN (@var{m})
 @deftypefn {Matrix Function} {} MMIN (@var{m})

+@deftypefnx {Matrix Function} {} MMAX (@var{m})
+@deftypefnx {Matrix Function} {} MSUM (@var{m})
+@deftypefnx {Matrix Function} {} MSSQ (@var{m})
+Returns the minimum, maximum, sum, or sum of squares, respectively, of
+the elements of @var{m}.

 @end deftypefn
 
 @end deftypefn
 

-
-@deftypefn {Matrix Function} {} MSSQ (@var{m})
-@end deftypefn
-
-
-@deftypefn {Matrix Function} {} MSUM (@var{m})
-@end deftypefn
-
-@deftypefn {Matrix Function} {} RMAX (@var{m})
-@end deftypefn
-
-

 @deftypefn {Matrix Function} {} RMIN (@var{m})
 @deftypefn {Matrix Function} {} RMIN (@var{m})

+@deftypefnx {Matrix Function} {} RMAX (@var{m})
+@deftypefnx {Matrix Function} {} RSUM (@var{m})
+@deftypefnx {Matrix Function} {} RSSQ (@var{m})
+Returns a column vector with the same number of rows as @var{m}, in
+which each element is the minimum, maximum, sum, or sum of squares,
+respectively, of the elements in the same row of @var{m}.

 @end deftypefn
 
 @end deftypefn
 

-
-@deftypefn {Matrix Function} {} RSSQ (@var{m})
+@deftypefn {Matrix Function} {} SSCP (@var{m})
+Returns @code{T(@var{m}) * @var{m}}.

 @end deftypefn
 
 @end deftypefn
 

-
-@deftypefn {Matrix Function} {} RSUM (@var{m})
+@deftypefn {Matrix Function} {} TRACE (@var{m})
+Returns the sum of the elements along @var{m}'s main diagonal,
+equivalent to @code{MSUM(DIAG(@var{m}))}.

 @end deftypefn
 
 @end deftypefn
 

-@deftypefn {Matrix Function} {} SSCP (@var{m})
-@end deftypefn

 
 @node Matrix Property Functions
 @subsubsection Matrix Property Functions
 
 
 @node Matrix Property Functions
 @subsubsection Matrix Property Functions
 

-@deftypefn {Matrix Function} {} DIAG (@var{m})
-@end deftypefn
-
-@deftypefn {Matrix Function} {} NCOL (@var{m})
+@deftypefn {Matrix Function} {} NROW (@var{m})
+@deftypefnx {Matrix Function} {} NCOL (@var{m})
+Returns the number of row or columns, respectively, in @var{m}.

 @end deftypefn
 
 @end deftypefn
 

-@deftypefn {Matrix Function} {} NROW (@var{m})
+@deftypefn {Matrix Function} {} DIAG (@var{m})
+Returns a column vector containing a copy of @var{m}'s main diagonal.
+The vector's length is the lesser of @code{NCOL(@var{m})} and
+@code{NROW(@var{m})}.

 @end deftypefn
 
 @node Matrix Rank Ordering Functions
 @subsubsection Matrix Rank Ordering Functions
 
 @deftypefn {Matrix Function} {} GRADE (@var{m})
 @end deftypefn
 
 @node Matrix Rank Ordering Functions
 @subsubsection Matrix Rank Ordering Functions
 
 @deftypefn {Matrix Function} {} GRADE (@var{m})

+Returns a matrix with the same dimensions as @var{m} in which each
+elements is a unique integer, from 1 to the number of elements in
+@var{m}, that corresponds to its rank within @var{m}.  The smallest
+element in @var{m} corresponds to value 1 in the returned matrix, the
+next smallest to value 2, and so on.  When multiple elements in
+@var{m} have the same value, they are assigned consecutive unique
+ranks in the return matrix.

 @end deftypefn
 
 @end deftypefn
 

+@noindent
+The @code{GRADE} function can be used to sort a vector.  For example,
+the following syntax:
+
+@example
+MATRIX.
+COMPUTE v=@{2, 5, 1, 4, 9, 7, 8, 10, 6, 3@}.
+COMPUTE v(GRADE(v))=v.
+PRINT v.
+END MATRIX.
+@end example
+
+@noindent yields the following sorted output:
+
+@example
+v
+   1   2   3   4   5   6   7   8   9  10
+@end example
+

 @deftypefn {Matrix Function} {} RNKORDER (@var{m})
 @end deftypefn
 
 @deftypefn {Matrix Function} {} RNKORDER (@var{m})
 @end deftypefn
 

-

 @node Matrix Algebra Functions
 @subsubsection Matrix Algebra Functions
 
 @node Matrix Algebra Functions
 @subsubsection Matrix Algebra Functions
 


@@ -1341,11 +1391,7 @@ nonzero, or 0 if all of them are zero.
 @end deftypefn
 
 
 @end deftypefn
 
 

-@deftypefn {Matrix Function} {} SWEEP (@var{m}, @var{s})
-@end deftypefn
-
-
-@deftypefn {Matrix Function} {} TRACE (@var{m})
+@deftypefn {Matrix Function} {} SWEEP (@var{m}, @var{n})

 @end deftypefn
 
 
 @end deftypefn