# HG changeset patch
# User David Bateman <dbateman@free.fr>
# Date 1221676804 14400
# Node ID 8a42498edb307217883272d040be42554766c840
# Parent  cd0d53b55f79720624e2aac8de190d749f8b3f77
Clarify doc for sparse function

diff --git a/doc/ChangeLog b/doc/ChangeLog
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+2008-09-15  David Bateman  <dbateman@free.fr>
+
+	* interpreter/sparse.txi: Minor clarificiation
+
 2008-08-28  John W. Eaton  <jwe@octave.org>
 
 	* doc/interpreter/func.txi, interpreter/plot.txi: Doc fixes
diff --git a/doc/interpreter/sparse.txi b/doc/interpreter/sparse.txi
--- a/doc/interpreter/sparse.txi
+++ b/doc/interpreter/sparse.txi
@@ -297,11 +297,11 @@
 
 @DOCSTRING(spconvert)
 
-The above problem can be avoided in oct-files. However, the construction
-of a sparse matrix from an oct-file is more complex than can be
-discussed in this brief introduction, and you are referred to chapter
-@ref{Dynamically Linked Functions}, to have a full description of the
-techniques involved.
+The above problem of memory reallocation can be avoided in
+oct-files. However, the construction of a sparse matrix from an oct-file
+is more complex than can be discussed in this brief introduction, and
+you are referred to chapter @ref{Dynamically Linked Functions}, to have
+a full description of the techniques involved.
 
 @node Information, Operators and Functions, Creation, Basics
 @subsection Finding out Information about Sparse Matrices
diff --git a/src/ChangeLog b/src/ChangeLog
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,7 @@
+2008-09-17  David Bateman  <dbateman@free.fr>
+
+	* DLD-FUNCTIONS/sparse.cc (Fsparse): Clarify the help string.
+
 2008-09-10  John W. Eaton  <jwe@octave.org>
 
 	* octave.cc (octave_main): Make all command-line arguments
diff --git a/src/DLD-FUNCTIONS/sparse.cc b/src/DLD-FUNCTIONS/sparse.cc
--- a/src/DLD-FUNCTIONS/sparse.cc
+++ b/src/DLD-FUNCTIONS/sparse.cc
@@ -57,14 +57,20 @@
 DEFUN_DLD (sparse, args, ,
     "-*- texinfo -*-\n\
 @deftypefn {Loadable Function} {@var{s} =} sparse (@var{a})\n\
-Create a sparse matrix from the full matrix @var{a}.\n\
-is forced back to a full matrix is resulting matrix is sparse\n\
+@deftypefnx {Loadable Function} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n}, @var{nzmax})\n\
+@deftypefnx {Loadable Function} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv})\n\
+@deftypefnx {Loadable Function} {@var{s} =} sparse (@var{i}, @var{j}, @var{s}, @var{m}, @var{n}, \"unique\")\n\
+@deftypefnx {Loadable Function} {@var{s} =} sparse (@var{m}, @var{n})\n\
+Create a sparse matrix from the full matrix or row, column, value triplets.\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\
-@deftypefnx {Loadable Function} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n}, @var{nzmax})\n\
-Create a sparse matrix given integer index vectors @var{i} and @var{j},\n\
-a 1-by-@code{nnz} vector of real of complex values @var{sv}, overall\n\
-dimensions @var{m} and @var{n} of the sparse matrix.  The argument\n\
-@code{nzmax} is ignored but accepted for compatibility with @sc{Matlab}.\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 their\n\
+values are derived from the maximum index in the vectors @var{i} and @var{j}\n\
+as given by @code{@var{m} = max (@var{i})}, @code{@var{n} = max (@var{j})}.\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\
@@ -80,15 +86,11 @@
 @end group\n\
 @end example\n\
 \n\
-@deftypefnx {Loadable Function} {@var{s} =} sparse (@var{i}, @var{j}, @var{s}, @var{m}, @var{n}, \"unique\")\n\
-Same as above, except that if more than two values are specified for the\n\
+Given the option \"unique\". if more than two values are specified for the\n\
 same @var{i}, @var{j} indices, the last specified value will be used.\n\
 \n\
-@deftypefnx {Loadable Function} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv})\n\
-Uses @code{@var{m} = max (@var{i})}, @code{@var{n} = max (@var{j})}\n\
-\n\
-@deftypefnx {Loadable Function} {@var{s} =} sparse (@var{m}, @var{n})\n\
-Equivalent to @code{sparse ([], [], [], @var{m}, @var{n}, 0)}\n\
+@code{sparse(@var{m}, @var{n})} is equivalent to\n\
+@code{sparse ([], [], [], @var{m}, @var{n}, 0)}\n\
 \n\
 If any of @var{sv}, @var{i} or @var{j} are scalars, they are expanded\n\
 to have a common size.\n\