--- a/.hgtags	Fri Jun 06 09:43:54 2014 -0400
+++ b/.hgtags	Sun Jun 08 16:36:54 2014 -0700
@@ -87,3 +87,4 @@
 02ce68d63fba31cd14ac060c087212a032ae3202 rc-3-8-1-3
 dd669c2ae76c167613f54d6f4db0130fa2124cac rc-3-8-1-4
 43cc202335dc4a53a3d8fc9ca90acaa81d2e63d3 release-3-8-1
+492c5614953571a0b07f4c1621cc7bc5c85c0251 rc-3-8-2-1

--- a/configure.ac	Fri Jun 06 09:43:54 2014 -0400
+++ b/configure.ac	Sun Jun 08 16:36:54 2014 -0700
@@ -33,7 +33,7 @@
 
 OCTAVE_COPYRIGHT="Copyright (C) 2013 John W. Eaton and others."
 
-OCTAVE_RELEASE_DATE="2013-12-27"
+OCTAVE_RELEASE_DATE="2014-06-06"
 
 ## The "API version" is used as a way of checking that interfaces in the
 ## liboctave and libinterp libraries haven't changed in a backwardly

--- a/libinterp/corefcn/data.cc	Fri Jun 06 09:43:54 2014 -0400
+++ b/libinterp/corefcn/data.cc	Sun Jun 08 16:36:54 2014 -0700
@@ -112,11 +112,11 @@
 @deftypefn  {Built-in Function} {} all (@var{x})\n\
 @deftypefnx {Built-in Function} {} all (@var{x}, @var{dim})\n\
 For a vector argument, return true (logical 1) if all elements of the vector\n\
-are nonzero.\n\
+are non-zero.\n\
 \n\
 For a matrix argument, return a row vector of logical ones and\n\
 zeros with each element indicating whether all of the elements of the\n\
-corresponding column of the matrix are nonzero.  For example:\n\
+corresponding column of the matrix are non-zero.  For example:\n\
 \n\
 @example\n\
 @group\n\
@@ -159,11 +159,11 @@
 @deftypefn  {Built-in Function} {} any (@var{x})\n\
 @deftypefnx {Built-in Function} {} any (@var{x}, @var{dim})\n\
 For a vector argument, return true (logical 1) if any element of the vector\n\
-is nonzero.\n\
+is non-zero.\n\
 \n\
 For a matrix argument, return a row vector of logical ones and\n\
 zeros with each element indicating whether any of the elements of the\n\
-corresponding column of the matrix are nonzero.  For example:\n\
+corresponding column of the matrix are non-zero.  For example:\n\
 \n\
 @example\n\
 @group\n\
@@ -2839,9 +2839,9 @@
 
 DEFUN (nnz, args, ,
        "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {@var{scalar} =} nnz (@var{a})\n\
-Return the number of non zero elements in @var{a}.\n\
-@seealso{sparse, nzmax}\n\
+@deftypefn {Built-in Function} {@var{n} =} nnz (@var{a})\n\
+Return the number of non-zero elements in @var{a}.\n\
+@seealso{nzmax, nonzeros, find}\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -2856,12 +2856,12 @@
 
 DEFUN (nzmax, args, ,
        "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {@var{scalar} =} nzmax (@var{SM})\n\
+@deftypefn {Built-in Function} {@var{n} =} nzmax (@var{SM})\n\
 Return the amount of storage allocated to the sparse matrix @var{SM}.\n\
+\n\
 Note that Octave tends to crop unused memory at the first opportunity\n\
-for sparse objects.  There are some cases of user created sparse objects\n\
-where the value returned by @dfn{nzmax} will not be the same as @dfn{nnz},\n\
-but in general they will give the same result.\n\
+for sparse objects.  Thus, in general the value of @code{nzmax} will be the\n\
+the same as @code{nnz} except for some cases of user-created sparse objects.\n\
 @seealso{nnz, spalloc, sparse}\n\
 @end deftypefn")
 {
@@ -5393,9 +5393,9 @@
 DEFUN (full, args, ,
        "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {@var{FM} =} full (@var{SM})\n\
-Return a full storage matrix from a sparse, diagonal, permutation matrix\n\
+Return a full storage matrix from a sparse, diagonal, permutation matrix,\n\
 or a range.\n\
-@seealso{sparse}\n\
+@seealso{sparse, issparse}\n\
 @end deftypefn")
 {
   octave_value retval;

--- a/libinterp/corefcn/sparse.cc	Fri Jun 06 09:43:54 2014 -0400
+++ b/libinterp/corefcn/sparse.cc	Sun Jun 08 16:36:54 2014 -0700
@@ -60,37 +60,69 @@
 DEFUN (sparse, args, ,
        "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {@var{s} =} sparse (@var{a})\n\
-@deftypefnx {Built-in Function} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n}, @var{nzmax})\n\
+@deftypefnx {Built-in Function} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n})\n\
 @deftypefnx {Built-in Function} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv})\n\
+@deftypefnx {Built-in Function} {@var{s} =} sparse (@var{m}, @var{n})\n\
 @deftypefnx {Built-in Function} {@var{s} =} sparse (@var{i}, @var{j}, @var{s}, @var{m}, @var{n}, \"unique\")\n\
-@deftypefnx {Built-in Function} {@var{s} =} sparse (@var{m}, @var{n})\n\
-Create a sparse matrix from the full matrix or row, column, value triplets.\n\
+@deftypefnx {Built-in Function} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n}, @var{nzmax})\n\
+Create a sparse matrix from a full matrix or row, column, value triplets.\n\
+\n\
 If @var{a} is a full matrix, convert it to a sparse matrix representation,\n\
 removing all zero values in the process.\n\
 \n\
-Given the integer index vectors @var{i} and @var{j}, a 1-by-@code{nnz} vector\n\
-of real of complex values @var{sv}, overall dimensions @var{m} and @var{n}\n\
-of the sparse matrix.  The argument @code{nzmax} is ignored but accepted for\n\
-compatibility with @sc{matlab}.  If @var{m} or @var{n} are not specified\n\
-their values are derived from the maximum index in the vectors @var{i} and\n\
-@var{j} as given by @code{@var{m} = max (@var{i})},\n\
-@code{@var{n} = max (@var{j})}.\n\
+Given the integer index vectors @var{i} and @var{j}, and a 1-by-@code{nnz}\n\
+vector of real or complex values @var{sv}, construct the sparse matrix\n\
+@code{S(@var{i}(@var{k}),@var{j}(@var{k})) = @var{sv}(@var{k})} with overall\n\
+dimensions @var{m} and @var{n}.  If any of @var{sv}, @var{i} or @var{j} are\n\
+scalars, they are expanded to have a common size.\n\
+\n\
+If @var{m} or @var{n} are not specified their values are derived from the\n\
+maximum index in the vectors @var{i} and @var{j} as given by\n\
+@code{@var{m} = max (@var{i})}, @code{@var{n} = max (@var{j})}.\n\
+\n\
+@strong{Note}: if multiple values are specified with the same @var{i},\n\
+@var{j} indices, the corresponding value in @var{s} will be the sum of the\n\
+values at the repeated location.  See @code{accumarray} for an example of how\n\
+to produce different behavior, such as taking the minimum instead.\n\
+\n\
+If the option @qcode{\"unique\"} is given, and more than one value is\n\
+specified at the same @var{i}, @var{j} indices, then the last specified\n\
+value will be used.\n\
+\n\
+@code{sparse (@var{m}, @var{n})} will create an empty @var{m}x@var{n} sparse\n\
+matrix and is equivalent to @code{sparse ([], [], [], @var{m}, @var{n})}\n\
+\n\
+The argument @code{nzmax} is ignored but accepted for compatibility with\n\
+@sc{matlab}.\n\
+\n\
+Example 1 (sum at repeated indices):\n\
 \n\
-@strong{Note}: if multiple values are specified with the same\n\
-@var{i}, @var{j} indices, the corresponding values in @var{s} will\n\
-be added.  See @code{accumarray} for an example of how to produce different\n\
-behavior, such as taking the minimum instead.\n\
+@example\n\
+@group\n\
+@var{i} = [1 1 2]; @var{j} = [1 1 2]; @var{sv} = [3 4 5];\n\
+sparse (@var{i}, @var{j}, @var{sv}, 3, 4)\n\
+@result{} \n\
+Compressed Column Sparse (rows = 3, cols = 4, nnz = 2 [17%])\n\
+\n\
+  (1, 1) ->  7\n\
+  (2, 2) ->  5\n\
+@end group\n\
+@end example\n\
 \n\
-Given the option @qcode{\"unique\"}, if more than two values are specified\n\
-for the same @var{i}, @var{j} indices, the last specified value will be\n\
-used.\n\
+Example 2 (\"unique\" option):\n\
 \n\
-@code{sparse (@var{m}, @var{n})} is equivalent to\n\
-@code{sparse ([], [], [], @var{m}, @var{n}, 0)}\n\
+@example\n\
+@group\n\
+@var{i} = [1 1 2]; @var{j} = [1 1 2]; @var{sv} = [3 4 5];\n\
+sparse (@var{i}, @var{j}, @var{sv}, 3, 4, \"unique\")\n\
+@result{} \n\
+Compressed Column Sparse (rows = 3, cols = 4, nnz = 2 [17%])\n\
 \n\
-If any of @var{sv}, @var{i} or @var{j} are scalars, they are expanded\n\
-to have a common size.\n\
-@seealso{full, accumarray}\n\
+  (1, 1) ->  4\n\
+  (2, 2) ->  5\n\
+@end group\n\
+@end example\n\
+@seealso{full, accumarray, spalloc, spdiags, speye, spones, sprand, sprandn, sprandsym, spconvert, spfun}\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -192,10 +224,11 @@
        "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {@var{s} =} spalloc (@var{m}, @var{n}, @var{nz})\n\
 Create an @var{m}-by-@var{n} sparse matrix with pre-allocated space for at\n\
-most @var{nz} nonzero elements.  This is useful for building the matrix\n\
-incrementally by a sequence of indexed assignments.  Subsequent indexed\n\
-assignments will reuse the pre-allocated memory, provided they are of one of\n\
-the simple forms\n\
+most @var{nz} nonzero elements.\n\
+\n\
+This is useful for building a matrix incrementally by a sequence of indexed\n\
+assignments.  Subsequent indexed assignments after @code{spalloc} will reuse\n\
+the pre-allocated memory, provided they are of one of the simple forms\n\
 \n\
 @itemize\n\
 @item @code{@var{s}(I:J) = @var{x}}\n\
@@ -216,8 +249,8 @@
 @end itemize\n\
 \n\
 Partial movement of data may still occur, but in general the assignment will\n\
-be more memory and time-efficient under these circumstances.  In particular,\n\
-it is possible to efficiently build a pre-allocated sparse matrix from\n\
+be more memory and time efficient under these circumstances.  In particular,\n\
+it is possible to efficiently build a pre-allocated sparse matrix from a\n\
 contiguous block of columns.\n\
 \n\
 The amount of pre-allocated memory for a given matrix may be queried using\n\

--- a/libinterp/corefcn/spparms.cc	Fri Jun 06 09:43:54 2014 -0400
+++ b/libinterp/corefcn/spparms.cc	Sun Jun 08 16:36:54 2014 -0700
@@ -100,6 +100,7 @@
 @qcode{\"defaults\"}.  The special keyword @qcode{\"tight\"} can be used to\n\
 set the mmd solvers to attempt a sparser solution at the potential cost of\n\
 longer running time.\n\
+@seealso{chol, colamd, lu, qr, symamd}\n\
 @end deftypefn")
 {
   octave_value_list retval;

--- a/libinterp/dldfcn/amd.cc	Fri Jun 06 09:43:54 2014 -0400
+++ b/libinterp/dldfcn/amd.cc	Sun Jun 08 16:36:54 2014 -0700
@@ -73,7 +73,7 @@
 The value of dense must be a positive scalar and its default value is 10.0\n\
 \n\
 @item @var{opts}.aggressive\n\
-If this value is a non zero scalar, then @code{amd} performs aggressive\n\
+If this value is a nonzero scalar, then @code{amd} performs aggressive\n\
 absorption.  The default is not to perform aggressive absorption.\n\
 @end table\n\
 \n\

--- a/scripts/sparse/nonzeros.m	Fri Jun 06 09:43:54 2014 -0400
+++ b/scripts/sparse/nonzeros.m	Sun Jun 08 16:36:54 2014 -0700
@@ -19,6 +19,7 @@
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {} nonzeros (@var{s})
 ## Return a vector of the non-zero values of the sparse matrix @var{s}.
+## @seealso{find, nnz}
 ## @end deftypefn
 
 function t = nonzeros (s)

--- a/scripts/sparse/spaugment.m	Fri Jun 06 09:43:54 2014 -0400
+++ b/scripts/sparse/spaugment.m	Sun Jun 08 16:36:54 2014 -0700
@@ -18,7 +18,9 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {@var{s} =} spaugment (@var{A}, @var{c})
-## Create the augmented matrix of @var{A}.  This is given by
+## Create the augmented matrix of @var{A}.
+##
+## This is given by
 ##
 ## @example
 ## @group
@@ -47,7 +49,7 @@
 ## As the matrix @var{s} is symmetric indefinite it can be factorized
 ## with @code{lu}, and the minimum norm solution can therefore be found
 ## without the need for a @code{qr} factorization.  As the residual
-## error will be @code{zeros (@var{m}, @var{m})} for under determined
+## error will be @code{zeros (@var{m}, @var{m})} for underdetermined
 ## problems, and example can be
 ##
 ## @example
@@ -69,6 +71,7 @@
 ##
 ## In general the left division operator is more stable and faster than
 ## using the @code{spaugment} function.
+## @seealso{mldivide}
 ## @end deftypefn
 
 function s = spaugment (A, c)

--- a/scripts/sparse/spconvert.m	Fri Jun 06 09:43:54 2014 -0400
+++ b/scripts/sparse/spconvert.m	Sun Jun 08 16:36:54 2014 -0700
@@ -18,12 +18,14 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {@var{x} =} spconvert (@var{m})
-## This function converts for a simple sparse matrix format easily
-## produced by other programs into Octave's internal sparse format.  The
-## input @var{x} is either a 3 or 4 column real matrix, containing
-## the row, column, real and imaginary parts of the elements of the
+## Convert a simple sparse matrix format easily generated by other programs
+## into Octave's internal sparse format.
+##
+## The input @var{m} is either a 3 or 4 column real matrix, containing
+## the row, column, real, and imaginary parts of the elements of the
 ## sparse matrix.  An element with a zero real and imaginary part can
 ## be used to force a particular matrix size.
+## @seealso{sparse}
 ## @end deftypefn
 
 function s = spconvert (m)

--- a/scripts/sparse/speye.m	Fri Jun 06 09:43:54 2014 -0400
+++ b/scripts/sparse/speye.m	Sun Jun 08 16:36:54 2014 -0700
@@ -17,17 +17,18 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {@var{y} =} speye (@var{m})
-## @deftypefnx {Function File} {@var{y} =} speye (@var{m}, @var{n})
-## @deftypefnx {Function File} {@var{y} =} speye (@var{sz})
-## Return a sparse identity matrix.  This is significantly more
-## efficient than @code{sparse (eye (@var{m}))} as the full matrix
-## is not constructed.
+## @deftypefn  {Function File} {@var{s} =} speye (@var{m}, @var{n})
+## @deftypefnx {Function File} {@var{s} =} speye (@var{m})
+## @deftypefnx {Function File} {@var{s} =} speye (@var{sz})
+## Return a sparse identity matrix of size @var{m}x@var{n}.
 ##
-## Called with a single argument a square matrix of size @var{m} by
-## @var{m} is created.  Otherwise a matrix of @var{m} by @var{n} is
-## created.  If called with a single vector argument, this argument
-## is taken to be the size of the matrix to create.
+## The implementation is significantly more efficient than
+## @code{sparse (eye (@var{m}))} as the full matrix is not constructed.
+##
+## Called with a single argument a square matrix of size
+## @var{m}-by-@var{m} is created.  If called with a single vector argument
+## @var{sz}, this argument is taken to be the size of the matrix to create.
+## @seealso{sparse, spdiags, eye}
 ## @end deftypefn
 
 function s = speye (m, n)

--- a/scripts/sparse/spones.m	Fri Jun 06 09:43:54 2014 -0400
+++ b/scripts/sparse/spones.m	Sun Jun 08 16:36:54 2014 -0700
@@ -20,6 +20,7 @@
 ## @deftypefn {Function File} {@var{r} =} spones (@var{S})
 ## Replace the non-zero entries of @var{S} with ones.  This creates a
 ## sparse matrix with the same structure as @var{S}.
+## @seealso{sparse, sprand, sprandn, sprandsym, spfun, spy}
 ## @end deftypefn
 
 function r = spones (S)

--- a/scripts/sparse/sprandsym.m	Fri Jun 06 09:43:54 2014 -0400
+++ b/scripts/sparse/sprandsym.m	Sun Jun 08 16:36:54 2014 -0700
@@ -20,15 +20,15 @@
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} sprandsym (@var{n}, @var{d})
 ## @deftypefnx {Function File} {} sprandsym (@var{s})
-## Generate a symmetric random sparse matrix.  The size of the matrix will be
-## @var{n} by @var{n}, with a density of values given by @var{d}.
-## @var{d} should be between 0 and 1.  Values will be normally
-## distributed with mean of zero and variance 1.
+## Generate a symmetric random sparse matrix.
 ##
-## If called with a single matrix argument, a random sparse matrix is
-## generated wherever the matrix @var{S} is non-zero in its lower
-## triangular part.
-## @seealso{sprand, sprandn}
+## The size of the matrix will be @var{n}x@var{n}, with a density of values
+## given by @var{d}.  @var{d} must be between 0 and 1 inclusive.  Values will
+## be normally distributed with a mean of zero and a variance of 1.
+##
+## If called with a single matrix argument, a random sparse matrix is generated
+## wherever the matrix @var{S} is non-zero in its lower triangular part.
+## @seealso{sprand, sprandn, spones, sparse}
 ## @end deftypefn
 
 function S = sprandsym (n, d)

--- a/scripts/sparse/spy.m	Fri Jun 06 09:43:54 2014 -0400
+++ b/scripts/sparse/spy.m	Sun Jun 08 16:36:54 2014 -0700
@@ -20,11 +20,12 @@
 ## @deftypefn  {Function File} {} spy (@var{x})
 ## @deftypefnx {Function File} {} spy (@dots{}, @var{markersize})
 ## @deftypefnx {Function File} {} spy (@dots{}, @var{line_spec})
-## Plot the sparsity pattern of the sparse matrix @var{x}.  If the argument
-## @var{markersize} is given as a scalar value, it is used to determine the
-## point size in the plot.  If the string @var{line_spec} is given it is
-## passed to @code{plot} and determines the appearance of the plot.
-## @seealso{plot}
+## Plot the sparsity pattern of the sparse matrix @var{x}.
+## 
+## If the argument @var{markersize} is given as a scalar value, it is used to
+## determine the point size in the plot.  If the string @var{line_spec} is
+## given it is passed to @code{plot} and determines the appearance of the plot.
+## @seealso{plot, gplot}
 ## @end deftypefn
 
 function spy (x, varargin)