--- a/libinterp/corefcn/sparse.cc	Fri Jun 06 12:29:53 2014 -0400
+++ b/libinterp/corefcn/sparse.cc	Sun Jun 08 16:32:12 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;
@@ -191,10 +223,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\
@@ -215,8 +248,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\