changeset 6620:bf4bdc21dc8d

[project @ 2007-05-14 17:35:46 by jwe]
author jwe
date Mon, 14 May 2007 17:38:38 +0000
parents b2b3b0509586
children 80a8e2019d39
files doc/ChangeLog doc/interpreter/basics.txi doc/interpreter/data.txi doc/interpreter/intro.txi doc/interpreter/numbers.txi doc/interpreter/octave.texi doc/interpreter/preface.txi doc/interpreter/sparse.txi src/ChangeLog src/DLD-FUNCTIONS/fft.cc src/DLD-FUNCTIONS/svd.cc src/help.cc src/input.cc src/toplev.cc
diffstat 14 files changed, 425 insertions(+), 660 deletions(-) [+]
line wrap: on
line diff
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,9 @@
+2007-05-14  John W. Eaton  <jwe@octave.org>
+
+	* interpreter/basics.txi, interpreter/data.txi,
+	interpreter/intro.txi, interpreter/numbers.txi,
+	interpreter/octave.texi, interpreter/preface.txi: Doc fixes.
+
 2007-04-18  Søren Hauberg  <hauberg@gmail.com>
 
 	* interpreter/package.texi: Document "*" flag for loaded packages.
--- a/doc/interpreter/basics.txi
+++ b/doc/interpreter/basics.txi
@@ -11,7 +11,7 @@
 from your shell.
 
 @menu
-* Invoking Octave::             
+* Invoking Octave from the Command Line::             
 * Quitting Octave::             
 * Getting Help::                
 * Command Line Editing::        
@@ -20,8 +20,8 @@
 * Comments::                    
 @end menu
 
-@node Invoking Octave
-@section Invoking Octave
+@node Invoking Octave from the Command Line
+@section Invoking Octave from the Command Line
 
 Normally, Octave is used interactively by running the program
 @samp{octave} without any arguments.  Once started, Octave reads
@@ -51,6 +51,7 @@
 Here is a complete list of all the command line options that Octave
 accepts.
 
+
 @table @code
 @item --debug
 @itemx -d
@@ -86,6 +87,12 @@
 @cindex @code{-?}
 Print short help message and exit.
 
+@item --image-path @var{path}
+@cindex @code{--image-path @var{path}}
+Specify the path to search for images.  The value of @var{path}
+specified on the command line will set the value of
+@code{IMAGE_PATH} found in the environment.
+
 @item --info-file @var{filename}
 @cindex @code{--info-file @var{filename}}
 Specify the name of the info file to use.  The value of @var{filename}
@@ -219,8 +226,8 @@
 
 @example
 printf ("%s", program_name ());
+arg_list = argv ();
 for i = 1:nargin
-  arg_list = argv ();
   printf (" %s", arg_list@{i@});
 endfor
 printf ("\n");
@@ -236,8 +243,9 @@
 @cindex initialization
 @cindex startup
 
-When Octave starts, it looks for commands to execute from the following
-files:
+When Octave starts, it looks for commands to execute from the files in
+the following list. These files may contain any valid Octave commands,
+including function definitions.
 
 @cindex startup files
 
@@ -280,9 +288,6 @@
 invoke Octave with the @code{--verbose} option but without the
 @code{--silent} option.
 
-Startup files may contain any valid Octave commands, including function
-definitions.
-
 @DOCSTRING(OCTAVE_HOME)
 
 @DOCSTRING(version)
@@ -304,7 +309,7 @@
 @cindex help, on-line
 
 The entire text of this manual is available from the Octave prompt
-via the command @kbd{help -i}.  In addition, the documentation for
+via the command @kbd{doc}.  In addition, the documentation for
 individual user-written functions and variables is also available via
 the @kbd{help} command.  This section describes the commands used for
 reading the manual and the documentation strings for user-supplied
@@ -317,9 +322,9 @@
 
 @DOCSTRING(lookfor)
 
-The help command can give you information about operators, but not the
-comma and semicolons that are used as command separators.  To get help
-for those, you must type @kbd{help comma} or @kbd{help semicolon}.
+The following function can be used to change which programs are used
+for displaying the documentation, and where the documentation can be
+found.
 
 @DOCSTRING(info_file)
 
@@ -422,12 +427,14 @@
 forward a word.  It is a loose convention that control keystrokes
 operate on characters while meta keystrokes operate on words.
 
-There is also a function available so that you can clear the screen from
-within Octave programs.
-
 @cindex clearing the screen
 
+The function @code{clc} will allow you to clear the screen from within
+Octave programs.
+
+@ifinfo
 @DOCSTRING(clc)
+@end ifinfo
 
 @node Killing and Yanking
 @subsection Killing and Yanking
@@ -506,7 +513,7 @@
 (or following) word, moving the cursor to the end of the word.
 
 @item M-l
-Lowecase the characters following the cursor to the end of the current
+Lowercase the characters following the cursor to the end of the current
 (or following) word, moving the cursor to the end of the word.
 
 @item M-c
@@ -592,7 +599,8 @@
 
 @DOCSTRING(run_history)
 
-@DOCSTRING(EDITOR)
+Octave also allows you customize the details of how and where the history
+is saved.
 
 @DOCSTRING(history_file)
 
@@ -602,9 +610,15 @@
 
 @DOCSTRING(history_timestamp_format_string)
 
+@DOCSTRING(EDITOR)
+
 @node Customizing readline
 @subsection Customizing @code{readline}
 
+As mentioned earlier Octave uses the GNU readline library for
+command-line editing and history features. It is possible to
+customize how readline works through a configuration file.
+
 @c FIXME -- need a brief description of the ~/.inputrc file here.
 
 @DOCSTRING(read_readline_init_file)
@@ -748,6 +762,7 @@
 @end group
 @end example
 
+@noindent
 This error message has several parts, and gives you quite a bit of
 information to help you locate the source of the error.  The messages
 are generated from the point of the innermost error, and provide a
@@ -834,7 +849,7 @@
 usually specified in stand-alone Octave programs to prevent them from
 printing the normal startup message, and to keep them from behaving
 differently depending on the contents of a particular user's
-@file{~/.octaverc} file.  @xref{Invoking Octave}.
+@file{~/.octaverc} file.  @xref{Invoking Octave from the Command Line}.
 
 Note that some operating systems may place a limit on the number of
 characters that are recognized after @samp{#!}.  Also, the various
@@ -875,8 +890,8 @@
 @group
 #! /bin/octave -qf
 printf ("%s", program_name ());
+arg_list = argv ();
 for i = 1:nargin
-  arg_list = argv ();
   printf (" %s", arg_list@{i@});
 endfor
 printf ("\n");
--- a/doc/interpreter/data.txi
+++ b/doc/interpreter/data.txi
@@ -7,8 +7,8 @@
 @cindex data types
 
 All versions of Octave include a number of built-in data types,
-including real and complex scalars and matrices, character strings, and
-a data structure type.
+including real and complex scalars and matrices, character strings,
+a data structure type, and an array that can contain all data types.
 
 It is also possible to define new specialized data types by writing a
 small amount of C++ code.  On some systems, new data types can be loaded
@@ -32,12 +32,15 @@
 @cindex built-in data types
 
 The standard built-in data types are real and complex scalars and
-matrices, ranges, character strings, and a data structure type.
-Additional built-in data types may be added in future versions.  If you
-need a specialized data type that is not currently provided as a
+matrices, ranges, character strings, a data structure type, and cell
+arrays. Additional built-in data types may be added in future versions.
+If you need a specialized data type that is not currently provided as a
 built-in type, you are encouraged to write your own user-defined data
 type and contribute it for distribution in a future release of Octave.
 
+The data type of a variable can be determined and changed through the
+use of the following functions.
+
 @DOCSTRING(class)
 
 @DOCSTRING(isa)
@@ -56,27 +59,27 @@
 @cindex numeric constant
 @cindex numeric value
 
-Octave's built-in numeric objects include real and complex scalars and
-matrices.  All built-in numeric data is currently stored as double
-precision numbers.  On systems that use the IEEE floating point format,
-values in the range of approximately
+Octave's built-in numeric objects include real, complex, and integer
+scalars and matrices.  All built-in floating point numeric data is
+currently stored as double precision numbers.  On systems that use the
+IEEE floating point format, values in the range of approximately
 @iftex
 @tex
  $2.2251\times10^{-308}$ to $1.7977\times10^{308}$
 @end tex
 @end iftex
-@ifinfo
+@ifnottex
  2.2251e-308 to 1.7977e+308
-@end ifinfo
+@end ifnottex
  can be stored, and the relative precision is approximately
 @iftex
 @tex
  $2.2204\times10^{-16}$.
 @end tex
 @end iftex
-@ifinfo
+@ifnottex
  2.2204e-16.
-@end ifinfo
+@end ifnottex
 The exact values are given by the variables @code{realmin},
 @code{realmax}, and @code{eps}, respectively.
 
@@ -90,6 +93,12 @@
 @subsection Missing Data
 @cindex missing data
 
+It is possible to represent missing data explicitly in Octave using
+@code{NA} (short for ``Not Available''). Missing data can only be
+represented when data is represented as floating point numbers. In this
+case missing data is represented as a special case of the representation
+of @code{NaN}.
+
 @DOCSTRING(NA)
 
 @DOCSTRING(isna)
@@ -120,6 +129,15 @@
 
 @xref{Data Structures}, for more information.
 
+@node Cell Array Objects
+@subsection Cell Array Objects
+@cindex cell arrays
+
+A Cell Array in Octave is general array that can hold any number of
+different data types.
+
+@xref{Cell Arrays}, for more information.
+
 @node User-defined Data Types
 @section User-defined Data Types
 @cindex user-defined data types
--- a/doc/interpreter/intro.txi
+++ b/doc/interpreter/intro.txi
@@ -6,7 +6,7 @@
 @chapter A Brief Introduction to Octave
 @cindex introduction
 
-This manual documents how to run, install and port GNU Octave, and how
+This manual documents how to install, run, and use GNU Octave, and how
 to report bugs.
 
 GNU Octave is a high-level language, primarily intended for numerical
@@ -72,7 +72,7 @@
 refer to it later, type the command
 
 @example
-octave:1> a = [ 1, 1, 2; 3, 5, 8; 13, 21, 34 ]
+octave:1> A = [ 1, 1, 2; 3, 5, 8; 13, 21, 34 ]
 @end example
 
 @noindent
@@ -81,7 +81,7 @@
 of a command.  For example
 
 @example
-octave:2> b = rand (3, 2);
+octave:2> B = rand (3, 2);
 @end example
 
 @noindent
@@ -90,10 +90,10 @@
 
 To display the value of any variable, simply type the name of the
 variable.  For example, to display the value stored in the matrix
-@code{b}, type the command
+@code{B}, type the command
 
 @example
-octave:3> b
+octave:3> B
 @end example
 
 @unnumberedsubsec Matrix Arithmetic
@@ -103,49 +103,51 @@
 value, type the command
 
 @example
-octave:4> 2 * a
+octave:4> 2 * A
 @end example
 
+@noindent
 To multiply the two matrices @code{a} and @code{b}, type the command
 
 @example
-octave:5> a * b
+octave:5> A * B
 @end example
 
-To form the matrix product
+@noindent
+and to form the matrix product
 @iftex
 @tex
-$@code{a}^T@code{a}$,
+$@code{A}^T@code{A}$,
 @end tex
 @end iftex
-@ifinfo
-@code{transpose (a) * a},
-@end ifinfo
+@ifnottex
+@code{transpose (A) * A},
+@end ifnottex
 type the command
 
 @example
-octave:6> a' * a
+octave:6> A' * A
 @end example
 
 @unnumberedsubsec Solving Linear Equations
 
-To solve the set of linear equations @code{a@var{x} = b},
+To solve the set of linear equations @code{A@var{x} = b},
 use the left division operator, @samp{\}:
 
 @example
-octave:7> a \ b
+octave:7> A \ b
 @end example
 
 @noindent
 This is conceptually equivalent to
 @iftex
 @tex
-$@code{a}^{-1}@code{b}$,
+$@code{A}^{-1}@code{b}$,
 @end tex
 @end iftex
-@ifinfo
+@ifnottex
 @code{inv (a) * b},
-@end ifinfo
+@end ifnottex
 but avoids computing the inverse of a matrix directly.
 
 If the coefficient matrix is singular, Octave will print a warning
@@ -162,7 +164,7 @@
 $$
 @end tex
 @end iftex
-@ifinfo
+@ifnottex
 
 @example
 @group
@@ -178,7 +180,7 @@
 @example
 x(t = t0) = x0
 @end example
-@end ifinfo
+@end ifnottex
 
 @noindent
 For Octave to integrate equations of this form, you must first provide a
@@ -188,9 +190,9 @@
 $f (x, t)$.
 @end tex
 @end iftex
-@ifinfo
+@ifnottex
 @code{f(x,t)}.
-@end ifinfo
+@end ifnottex
 This is straightforward, and may be accomplished by entering the
 function body directly on the command line.  For example, the following
 commands define the right hand side function for an interesting pair of
@@ -253,10 +255,11 @@
 plot (t, x)
 @end example
 
-If you are using the X Window System, Octave will automatically create
+@noindent
+If you are using a graphical user interface, Octave will automatically create
 a separate window to display the plot.
 
-To print a plot once it has been displayed on the screen, use the print
+To save a plot once it has been displayed on the screen, use the print
 command.  For example,
 
 @example
@@ -273,19 +276,18 @@
 
 @noindent
 explains more options for the @code{print} command and provides a list
-of additional output devices.
+of additional output file formats.
 
 @unnumberedsubsec Editing What You Have Typed
 
 At the Octave prompt, you can recall, edit, and reissue previous
 commands using Emacs- or vi-style editing commands.  The default
 keybindings use Emacs-style commands.  For example, to recall the
-previous command, type @kbd{Control-p} (usually written @kbd{C-p} for
-short).  @kbd{C-p} gets its name from the fact that you type it by
-holding down @key{CTRL} and then pressing @key{p}.  Doing this will
-normally bring back the previous line of input.  @kbd{C-n} will bring up
-the next line of input, @kbd{C-b} will move the cursor backward on the
-line, @kbd{C-f} will move the cursor forward on the line, etc.
+previous command, press @kbd{Control-p} (usually written @kbd{C-p} for
+short). Doing this will normally bring back the previous line of input.
+@kbd{C-n} will bring up the next line of input, @kbd{C-b} will move
+the cursor backward on the line, @kbd{C-f} will move the cursor forward
+on the line, etc.
 
 A complete description of the command line editing capability is given
 in this manual in @ref{Command Line Editing}.
@@ -301,9 +303,13 @@
 that you want to use.  This name of the function may not always be
 obvious, but a good place to start is to just type @code{help}.
 This will show you all the operators, reserved words, functions,
-built-in variables, and function files.  You can then get more
-help on anything that is listed by simply including the name as an
-argument to help.  For example,
+built-in variables, and function files. An alternative is to search the
+documentation using the @code{lookfor} function. This function is
+described in @ref{Getting Help}.
+
+Once you know the name of the function you wish to use, you can get more
+help on the function by simply including the name as an argument to help.
+For example,
 
 @example
 help plot
@@ -511,6 +517,11 @@
 way that the function is defined.  These additional tags include
 
 @table @asis
+@item Function File
+@cindex function file
+The function described is defined using Octave commands stored in a text
+file.  @xref{Function Files}.
+
 @item Built-in Function
 @cindex built-in function
 The function described is written in a language like C++, C, or Fortran,
@@ -523,11 +534,6 @@
 may be automatically linked while Octave is running, but only if it is
 needed.  @xref{Dynamically Linked Functions}.
 
-@item Function File
-@cindex function file
-The function described is defined using Octave commands stored in a text
-file.  @xref{Function Files}.
-
 @item Mapping Function
 @cindex mapping function
 The function described works element-by-element for matrix and vector
--- a/doc/interpreter/numbers.txi
+++ b/doc/interpreter/numbers.txi
@@ -12,11 +12,12 @@
 
 The simplest form of a numeric constant, a scalar, is a single number
 that can be an integer, a decimal fraction, a number in scientific
-(exponential) notation, or a complex number.  Note that all numeric
+(exponential) notation, or a complex number.  Note that by default numeric
 constants are represented within Octave in double-precision floating
 point format (complex constants are stored as pairs of double-precision
-floating point values).  Here are some examples of real-valued numeric
-constants, which all have the same value:
+floating point values).  It is however possible to represent real
+integers as described in @ref{Integer Data Types}. Here are some examples
+of real-valued numeric constants, which all have the same value:
 
 @example
 @group
@@ -36,6 +37,7 @@
 @end group
 @end example
 
+@noindent
 all of which are equivalent.  The letter @samp{i} in the previous example
 stands for the pure imaginary constant, defined as
 @iftex
@@ -43,9 +45,9 @@
   $\sqrt{-1}$.
 @end tex
 @end iftex
-@ifinfo
+@ifnottex
   @code{sqrt (-1)}.
-@end ifinfo
+@end ifnottex
 
 For Octave to recognize a value as the imaginary part of a complex
 constant, a space must not appear between the number and the @samp{i}.
@@ -62,6 +64,7 @@
 @end group
 @end example
 
+@noindent
 You may also use @samp{j}, @samp{I}, or @samp{J} in place of the
 @samp{i} above.  All four forms are equivalent.
 
@@ -103,7 +106,7 @@
 $$ a = \left[ \matrix{ 1 & 2 \cr 3 & 4 } \right] $$
 @end tex
 @end iftex
-@ifinfo
+@ifnottex
 
 @example
 @group
@@ -116,7 +119,7 @@
 
 @end group
 @end example
-@end ifinfo
+@end ifnottex
 
 Elements of a matrix may be arbitrary expressions, provided that the
 dimensions all make sense when combining the various pieces.  For
@@ -234,7 +237,7 @@
 @end example
 
 @noindent
-because to not do so would cause trouble when parsing the valid expression
+because not doing so would cause trouble when parsing the valid expression
 
 @example
 [ a 'foo' ]
@@ -299,7 +302,7 @@
 $$
 @end tex
 @end iftex
-@ifinfo
+@ifnottex
 Briefly, given a scalar @var{s}, an @var{m} by
 @var{n} matrix @code{M(mxn)}, and an @var{m} by @var{n} empty matrix
 @code{[](mxn)} (with either one or both dimensions equal to zero), the
@@ -318,7 +321,7 @@
     [](mx0) * [](0xn) =  0(mxn)
 @end group
 @end example
-@end ifinfo
+@end ifnottex
 
 By default, dimensions of the empty matrix are printed along with the
 empty matrix symbol, @samp{[]}.  The built-in variable
@@ -384,6 +387,31 @@
 @node Integer Data Types
 @section Integer Data Types
 
+Octave supports integer matrices as an alternative to using double
+precision. It is possible to use both signed and unsigned integers
+represented by 8, 16, 32, or 64 bits. It should be noted that most
+computations require floating point data, meaning that integers will
+often change type when involved in numeric computations. For this
+reason integers are most often used to store data, and not for
+calculations.
+
+In general most integer matrices are created by casting
+existing matrices to integers. The following example shows how to cast
+a matrix into 32 bit integers.
+
+@example
+float = rand (2, 2)
+     @result{} float = 0.37569   0.92982
+                0.11962   0.50876
+integer = int32 (float)
+     @result{} integer = 0  1
+                  0  1
+@end example
+
+@noindent
+As can be seen, floating point values are rounded to the nearest integer
+when converted.
+
 @DOCSTRING(isinteger)
 
 @DOCSTRING(int8)
@@ -406,9 +434,65 @@
 
 @DOCSTRING(intmin)
 
+@node Integer Arithmetic
+@subsection Integer Arithmetic
+
+While many numerical computations can't be carried out in integers,
+Octave does support basic operations like addition and multiplication
+on integers. The operators @code{+}, @code{-}, @code{.*}, and @code{./}
+works on integers of the same type. So, it is possible to add two 32 bit
+integers, but not to add a 32 bit integer and a 16 bit integer.
+
+When doing integer arithmetic one should consider the possibility of
+underflow and overflow. This happens when the result of the computation
+can't be represented using the chosen integer type. As an example it is
+not possible to represent the result of @math{10 - 20} when using
+unsigned integers. Octave makes sure that the result of integer
+computations is the integer that is closest to the true result. So, the
+result of @math{10 - 20} when using unsigned integers is zero.
+
+When doing integer division Octave will round the result to the nearest
+integer. This is different from most programming languages, where the
+result is often floored to the nearest integer. So, the result of
+@code{int32(5)./int32(8)} is @code{1}.
+
 @node Logical Values
 @section Logical Values
 
+Octave has built-in support for logical values, i.e. variables that
+are either @code{true} or @code{false}. When comparing two variables,
+the result will be a logical value whose value depends on whether or
+not the comparison is true.
+
+The basic logical operations are @code{&}, @code{|}, and @code{!},
+that corresponds to ``Logical And'', ``Logical Or'', and ``Logical
+Negation''. These operations all follow the rules of logic.
+
+It is also possible to use logical values as part of standard numerical
+calculations. In this case @code{true} is converted to @code{1}, and
+@code{false} to 0, both represented using double precision floating
+point numbers. So, the result of @code{true*22 - false/6} is @code{22}.
+
+Logical values can also be used to index matrices and cell arrays.
+When indexing with a logical array the result will be a vector containing
+the values corresponding to @code{true} parts of the logical array.
+The following example illustrates this.
+
+@example
+data = [ 1, 2; 3, 4 ];
+idx = (data <= 2);
+data(idx)
+     @result{} ans = [ 1; 4 ]
+@end example
+
+@noindent
+Instead of creating the @code{idx} array it is possible to replace
+@code{data(idx)} with @code{data( data <= 2 )} in the above code.
+
+Besides when doing comparisons, logical values can be constructed by
+casting numeric objects to logical values, or by using the @code{true}
+or @code{false} functions.
+
 @DOCSTRING(logical)
 
 @DOCSTRING(true)
@@ -418,6 +502,26 @@
 @node Predicates for Numeric Objects
 @section Predicates for Numeric Objects
 
+Since the type of a variable may change during the execution of a
+program, it can be necessary to type checking at run-time. Doing this
+also allows you to change the behaviour of a function depending on the
+type of the input. As an example, this naive implementation of @code{abs}
+return the absolute value of the input if it is a real number, and the
+length of the input if it is a complex number.
+
+@example
+function a = abs (x)
+  if (isreal (x))
+    a = sign (x) .* x;
+  elseif (iscomplex (x))
+    a = sqrt (real(x).^2 + imag(x).^2);
+  endif
+endfunction
+@end example
+
+The following functions are available for determining the type of a
+variable.
+
 @DOCSTRING(isnumeric)
 
 @DOCSTRING(isreal)
--- a/doc/interpreter/octave.texi
+++ b/doc/interpreter/octave.texi
@@ -11,9 +11,14 @@
 @c each group of functions and variables).
 
 @macro seealso {args}
+@iftex
+@vskip 2pt
+@end iftex
+@ifnottex
 @sp 1
+@end ifnottex
 @noindent
-See also: \args\.
+@strong{See also:} \args\.
 @end macro
 
 @ifinfo
@@ -205,7 +210,7 @@
 
 Getting Started
 
-* Invoking Octave::             
+* Invoking Octave from the Command Line::             
 * Quitting Octave::             
 * Getting Help::                
 * Command Line Editing::        
@@ -213,7 +218,7 @@
 * Executable Octave Programs::  
 * Comments::                    
 
-Invoking Octave
+Invoking Octave from the Command Line
 
 * Command Line Options::        
 * Startup Files::               
--- a/doc/interpreter/preface.txi
+++ b/doc/interpreter/preface.txi
@@ -166,5 +166,5 @@
 @end quotation
  
 Octave is also available on the Internet from
-@url{ftp://ftp.che.wisc.edu/pub/octave}, and additional information is
-available from @url{http://www.che.wisc.edu/octave}.
+@url{ftp://ftp.octave.org/pub/octave}, and additional information is
+available from @url{http://www.octave.org}.
--- a/doc/interpreter/sparse.txi
+++ b/doc/interpreter/sparse.txi
@@ -17,7 +17,6 @@
 * Sparse Linear Algebra:: Linear Algebra on Sparse Matrices
 * Iterative Techniques:: Iterative Techniques applied to Sparse Matrices
 * Real Life Example:: Real Life Example of the use of Sparse Matrices
-* Function Reference:: Documentation from the Specific Sparse Functions
 @end menu
 
 @node Basics, Sparse Linear Algebra, Sparse Matrices, Sparse Matrices
@@ -64,7 +63,7 @@
 that will be solved. A good summary of the available techniques for storing
 sparse matrix is given by Saad @footnote{Youcef Saad "SPARSKIT: A basic toolkit
 for sparse matrix computation", 1994,
-@url{ftp://ftp.cs.umn.edu/dept/sparse/SPARSKIT2/DOC/paper.ps}}.
+@url{http://www-users.cs.umn.edu/~saad/software/SPARSKIT/paper.ps}}.
 With full matrices, knowledge of the point of an element of the matrix
 within the matrix is implied by its position in the computers memory. 
 However, this is not the case for sparse matrices, and so the positions
@@ -200,6 +199,38 @@
 creates a sparse (@var{n}+1)-by-(@var{n}+1) sparse matrix with a single
 diagonal defined.
 
+@DOCSTRING(spatan2)
+
+@DOCSTRING(spcumprod)
+
+@DOCSTRING(spcumsum)
+
+@DOCSTRING(spdiag)
+
+@DOCSTRING(spdiags)
+
+@DOCSTRING(speye)
+
+@DOCSTRING(spfun)
+
+@DOCSTRING(spmax)
+
+@DOCSTRING(spmin)
+
+@DOCSTRING(spones)
+
+@DOCSTRING(spprod)
+
+@DOCSTRING(sprand)
+
+@DOCSTRING(sprandn)
+
+@DOCSTRING(sprandsym)
+
+@DOCSTRING(spsum)
+
+@DOCSTRING(spsumsq)
+
 The recommended way for the user to create a sparse matrix, is to create 
 two vectors containing the row and column index of the data and a third
 vector of the same size containing the data to be stored. For example
@@ -257,6 +288,16 @@
 as much as possible to minimize the number of assignments and reduce the
 number of memory allocations.
 
+@DOCSTRING(full)
+
+@DOCSTRING(spalloc)
+
+@DOCSTRING(sparse)
+
+@DOCSTRING(spconvert)
+
+@DOCSTRING(spfind)
+
 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
@@ -282,6 +323,16 @@
 the columns of a sparse matrix including the number of elements, the
 mean and the variance of each column.
 
+@DOCSTRING(issparse)
+
+@DOCSTRING(nnz)
+
+@DOCSTRING(nonzeros)
+
+@DOCSTRING(nzmax)
+
+@DOCSTRING(spstats)
+
 When solving linear equations involving sparse matrices Octave
 determines the means to solve the equation based on the type of the
 matrix as discussed in @ref{Sparse Linear Algebra}. Octave probes the
@@ -361,6 +412,16 @@
 graphically by the command @code{treeplot(etree(A))} if @code{A} is
 symmetric or @code{treeplot(etree(A+A'))} otherwise.
 
+@DOCSTRING(spy)
+
+@DOCSTRING(etree)
+
+@DOCSTRING(etreeplot)
+
+@DOCSTRING(gplot)
+
+@DOCSTRING(treeplot)
+
 @node Operators and Functions, , Information, Basics
 @subsection Basic Operators and Functions on Sparse Matrices
 
@@ -382,12 +443,13 @@
 sparse matrix specific version of the function can be used by
 explicitly calling its function name. 
 
-The table below lists all of the sparse functions of Octave
-together (with possible future extensions that are currently
-unimplemented, listed last). Note that in this specific sparse forms
-of the functions are typically the same as the general versions with a
-@dfn{sp} prefix. In the table below, and the rest of this article
-the specific sparse versions of the functions are used.
+The table below lists all of the sparse functions of Octave.  Note that
+in this specific sparse forms of the functions are typically the same as
+the general versions with a @dfn{sp} prefix. In the table below, and the
+rest of this article the specific sparse versions of the functions are
+used.
+
+@c Table includes in comments the missing sparse functions
 
 @table @asis
 @item Generate sparse matrices:
@@ -399,25 +461,29 @@
 
 @item Manipulate sparse matrices
   @dfn{issparse}, @dfn{nnz}, @dfn{nonzeros}, @dfn{nzmax},
-  @dfn{spfun}, @dfn{spones}, @dfn{spy},
+  @dfn{spfun}, @dfn{spones}, @dfn{spy}
 
 @item Graph Theory:
   @dfn{etree}, @dfn{etreeplot}, @dfn{gplot}, 
-  @dfn{treeplot}, (treelayout)
+  @dfn{treeplot}
+@c @dfn{treelayout}
 
 @item Sparse matrix reordering:
-  @dfn{ccolamd}, @dfn{colamd}, @dfn{colperm}, 
-  @dfn{csymamd}, @dfn{dmperm}, @dfn{symamd}, @dfn{randperm}, (symrcm)
+  @dfn{ccolamd}, @dfn{colamd}, @dfn{colperm}, @dfn{csymamd},
+  @dfn{dmperm}, @dfn{symamd}, @dfn{randperm}, @dfn{symrcm}
 
 @item Linear algebra:
   @dfn{matrix\_type}, @dfn{spchol}, @dfn{cpcholinv}, 
   @dfn{spchol2inv}, @dfn{spdet}, @dfn{spinv}, @dfn{spkron},
-  @dfn{splchol}, @dfn{splu}, @dfn{spqr}, (condest, eigs, normest, 
-  sprank, svds, spaugment)
+  @dfn{splchol}, @dfn{splu}, @dfn{spqr}, @dfn{normest}, 
+  @dfn{sprank}
+@c @dfn{condest}, @dfn{spaugment}
+@c @dfn{eigs}, @dfn{svds} but these are in octave-forge for now
 
 @item Iterative techniques:
-  @dfn{luinc}, @dfn{pcg}, @dfn{pcr}, (bicg, bicgstab, cholinc, cgs, 
-  gmres, lsqr, minres, qmr, symmlq)
+  @dfn{luinc}, @dfn{pcg}, @dfn{pcr}
+@c @dfn{bicg}, @dfn{bicgstab}, @dfn{cholinc}, @dfn{cgs}, @dfn{gmres}, 
+@c @dfn{lsqr}, @dfn{minres}, @dfn{qmr}, @dfn{symmlq}
 
 @item Miscellaneous:
   @dfn{spparms}, @dfn{symbfact}, @dfn{spstats}, 
@@ -639,6 +705,20 @@
 and ldiv (\) operators, and so no the user does not need to explicitly
 reorder the matrix to maximize performance.
 
+@DOCSTRING(ccolamd)
+
+@DOCSTRING(colamd)
+
+@DOCSTRING(colperm)
+
+@DOCSTRING(csymamd)
+
+@DOCSTRING(dmperm)
+
+@DOCSTRING(symamd)
+
+@DOCSTRING(symrcm)
+
 @node Sparse Linear Algebra, Iterative Techniques, Basics, Sparse Matrices
 @section Linear Algebra on Sparse Matrices
 
@@ -720,7 +800,7 @@
 narrow banded, triangular or diagonal matrices, the cost of
 calculating the condition number is significant, and can in fact
 exceed the cost of factoring the matrix. Therefore the condition
-number is not calculated in these case, and octave relies on simplier
+number is not calculated in these case, and Octave relies on simplier
 techniques to detect sinular matrices or the underlying LAPACK code in
 the case of banded matrices.
 
@@ -730,15 +810,54 @@
 will lead to unpredictable results, and so @code{matrix_type} should be
 used with care.
 
+@DOCSTRING(normest)
+
+@DOCSTRING(spchol)
+
+@DOCSTRING(spcholinv)
+
+@DOCSTRING(spchol2inv)
+
+@DOCSTRING(spdet)
+
+@DOCSTRING(spinv)
+
+@DOCSTRING(spkron)
+
+@DOCSTRING(splchol)
+
+@DOCSTRING(splu)
+
+@DOCSTRING(spparms)
+
+@DOCSTRING(spqr)
+
+@DOCSTRING(sprank)
+
+@DOCSTRING(symbfact)
+
 @node Iterative Techniques, Real Life Example, Sparse Linear Algebra, Sparse Matrices
 @section Iterative Techniques applied to sparse matrices
 
-There are three functions currently to document here, these being
-@dfn{luinc}, @dfn{pcg} and @dfn{pcr}.
+The left division @code{\} and right division @code{/} operators,
+discussed in the previous section, use direct solvers to resolve a
+linear equation of the form @code{@var{x} = @var{A} \ @var{b}} or
+@code{@var{x} = @var{b} / @var{A}}. Octave equally includes a number of
+functions to solve sparse linear equations using iterative techniques.
+
+@DOCSTRING(pcg)
+
+@DOCSTRING(pcr)
 
-WRITE ME.
+The speed with which an iterative solver converges to a solution can be
+accelerated with the use of a pre-conditioning matrix @var{M}. In this
+case the linear equation @code{@var{M}^-1 * @var{x} = @var{M}^-1 *
+@var{A} \ @var{b}} is solved instead. Typical pre-conditioning matrices
+are partial factorizations of the original matrix.
 
-@node Real Life Example, Function Reference, Iterative Techniques, Sparse Matrices
+@DOCSTRING(luinc)
+
+@node Real Life Example, , Iterative Techniques, Sparse Matrices
 @section Real Life Example of the use of Sparse Matrices
 
 A common application for sparse matrices is in the solution of Finite
@@ -1004,535 +1123,6 @@
 @end ifset
 @end ifset
 
-@node Function Reference, , Real Life Example, Sparse Matrices
-@section Function Reference
-
-@ifset htmltex
-@subsection Functions by Category
-@subsubsection Generate sparse matrix
-@table @asis
-@item @ref{spdiags}
-A generalization of the function `spdiag'.
-@item @ref{speye}
-Returns a sparse identity matrix.
-@item @ref{sprand}
-Generate a random sparse matrix.
-@item @ref{sprandn}
-Generate a random sparse matrix.
-@item @ref{sprandsym}
-Generate a symmetric random sparse matrix.
-@end table
-@subsubsection Sparse matrix conversion
-@table @asis
-@item @ref{full}
-returns a full storage matrix from a sparse one See also: sparse
-@item @ref{sparse}
-SPARSE: create a sparse matrix
-@item @ref{spconvert}
-This function converts for a simple sparse matrix format easily produced by other programs into Octave's internal sparse format.
-@item @ref{spfind}
-SPFIND: a sparse version of the find operator 1.
-@end table
-@subsubsection Manipulate sparse matrices
-@table @asis
-@item @ref{issparse}
-Return 1 if the value of the expression EXPR is a sparse matrix.
-@item @ref{nnz}
-returns number of non zero elements in SM See also: sparse
-@item @ref{nonzeros}
-Returns a vector of the non-zero values of the sparse matrix S
-@item @ref{nzmax}
-Returns the amount of storage allocated to the sparse matrix SM.
-@item @ref{spalloc}
-Returns an empty sparse matrix of size R-by-C.
-@item @ref{spfun}
-Compute `f(X)' for the non-zero values of X This results in a sparse matrix with the same structure as X.
-@item @ref{spones}
-Replace the non-zero entries of X with ones.
-@item @ref{spy}
-Plot the sparsity pattern of the sparse matrix X
-@end table
-@subsubsection Graph Theory
-@table @asis
-@item @ref{etree}
-Returns the elimination tree for the matrix S.
-@item @ref{etreeplot}
-Plots the elimination tree of the matrix @var{s} or @code{@var{s}+@var{s}'}
-if @var{s} in non-symmetric.
-@item @ref{gplot}
-Plots a graph defined by @var{A} and @var{xy} in the graph theory sense.
-@item treelayout
-@emph{Not implemented}
-@item @ref{treeplot}
-Produces a graph of a tree or forest.
-@end table
-@subsubsection Sparse matrix reordering
-@table @asis
-@item @ref{ccolamd}
-Constrained column approximate minimum degree permutation.
-@item @ref{colamd}
-Column approximate minimum degree permutation.
-@item @ref{colperm}
-Returns the column permutations such that the columns of `S (:, P)' are ordered in terms of increase number of non-zero elements.
-@item @ref{csymamd}
-For a symmetric positive definite matrix S, returns the permutation vector p such that `S (P, P)' tends to have a sparser Cholesky factor than S.
-@item @ref{dmperm}
-Perform a Deulmage-Mendelsohn permutation on the sparse matrix S.
-@item @ref{symamd}
-For a symmetric positive definite matrix S, returns the permutation vector p such that `S (P, P)' tends to have a sparser Cholesky factor than S.
-@item symrcm
-@emph{Not implemented}
-@end table
-@subsubsection Linear algebra
-@table @asis
-@item cholinc
-@emph{Not implemented}
-@item condest
-@emph{Not implemented}
-@item eigs
-@emph{Not implemented}
-@item @ref{normest}
-Estimates the 2-norm of the matrix @var{a} using a power series analysis.
-@item @ref{spchol}
-Compute the Cholesky factor, R, of the symmetric positive definite.
-@item @ref{spcholinv}
-Use the Cholesky factorization to compute the inverse of the
-sparse symmetric positive definite matrix A.
-@item @ref{spchol2inv}
-Invert a sparse symmetric, positive definite square matrix from its
-Cholesky decomposition, U.
-@item @ref{spdet}
-Compute the determinant of sparse matrix A using UMFPACK.
-@item @ref{spinv}
-Compute the inverse of the square matrix A.
-@item @ref{spkron}
-Form the kronecker product of two sparse matrices.
-@item @ref{splchol}
-Compute the Cholesky factor, L, of the symmetric positive definite.
-@item @ref{splu}
-Compute the LU decomposition of the sparse matrix A, using subroutines from UMFPACK.
-@item @ref{spqr}
-Compute the sparse QR factorization of @var{a}, using CSPARSE.
-@item @ref{sprank}
-Calculates the structural rank of a sparse matrix @var{s}.
-@item svds
-@emph{Not implemented}
-@end table
-@subsubsection Iterative techniques
-@table @asis
-@item bicg
-@emph{Not implemented}
-@item bicgstab
-@emph{Not implemented}
-@item cgs
-@emph{Not implemented}
-@item gmres
-@emph{Not implemented}
-@item @ref{luinc}
-Produce the incomplete LU factorization of the sparse matrix A.
-@item lsqr
-@emph{Not implemented}
-@item minres
-@emph{Not implemented}
-@item pcg
-Solves the linear system of equations @code{@var{A} * @var{x} =
-@var{b}} by means of the  Preconditioned Conjugate Gradient iterative
-method.
-@item pcr
-Solves the linear system of equations @code{@var{A} * @var{x} =
-@var{b}} by means of the  Preconditioned Conjugate Residual iterative
-method.
-@item qmr
-@emph{Not implemented}
-@item symmlq
-@emph{Not implemented}
-@end table
-@subsubsection Miscellaneous
-@table @asis
-@item spaugment
-@emph{Not implemented}
-@item @ref{spparms}
-Sets or displays the parameters used by the sparse solvers and factorization functions.
-@item @ref{symbfact}
-Performs a symbolic factorization analysis on the sparse matrix S.
-@item @ref{spstats}
-Return the stats for the non-zero elements of the sparse matrix S COUNT is the number of non-zeros in each column, MEAN is the mean of the non-zeros in each column, and VAR is the variance of the non-zeros in each column
-@item @ref{spprod}
-Product of elements along dimension DIM.
-@item @ref{spcumprod}
-Cumulative product of elements along dimension DIM.
-@item @ref{spcumsum}
-Cumulative sum of elements along dimension DIM.
-@item @ref{spsum}
-Sum of elements along dimension DIM.
-@item @ref{spsumsq}
-Sum of squares of elements along dimension DIM.
-@item @ref{spmin}
-For a vector argument, return the minimum value.
-@item @ref{spmax}
-For a vector argument, return the maximum value.
-@item @ref{spatan2}
-Compute atan (Y / X) for corresponding sparse matrix elements of Y and X.
-@item @ref{spdiag}
-Return a diagonal matrix with the sparse vector V on diagonal K.
-@end table
-
-@subsection Functions Alphabetically
-@end ifset
-
-@menu
-* ccolamd::	Constrained column approximate minimum degree permutation.
-* colamd::	Column approximate minimum degree permutation.
-* colperm::	Returns the column permutations such that the columns of `S
-		(:, P)' are ordered in terms of increase number of non-zero
-		elements.
-* csymamd::	For a symmetric positive definite matrix S, returns the
-		permutation vector p such that `S (P, P)' tends to have a
-		sparser Cholesky factor than S.
-* dmperm::	Perfrom a Deulmage-Mendelsohn permutation on the sparse
-		matrix S.
-* etree::	Returns the elimination tree for the matrix S.
-* etreeplot::   Plots the elimination tree of the matrix @var{s} or 
-		@code{@var{s}+@var{s}'} if @var{s} in non-symmetric.
-* full::	returns a full storage matrix from a sparse one See also:
-		sparse
-* gplot::	Plots a graph defined by @var{A} and @var{xy} in the graph 
-		theory sense.
-* issparse::	Return 1 if the value of the expression EXPR is a sparse
-		matrix.
-* luinc::	Produce the incomplete LU factorization of the sparse 
-		A.
-* normest:: 	Estimates the 2-norm of the matrix @var{a} using a power 
-		series analysis.
-* nnz:: 	returns number of non zero elements in SM See also: sparse
-* nonzeros::	Returns a vector of the non-zero values of the sparse
-		matrix S
-* nzmax::	Returns the amount of storage allocated to the sparse
-		matrix SM.
-* pcg::		Solves linear system of equations by means of the 
-		Preconditioned Conjugate Gradient iterative method.
-* pcr::		Solves linear system of equations by means of the 
-		Preconditioned Conjugate Residual iterative method.
-* spalloc::	Returns an empty sparse matrix of size R-by-C.
-* sparse::	SPARSE: create a sparse matrix
-* spatan2::	Compute atan (Y / X) for corresponding sparse matrix
-		elements of Y and X.
-* spchol::	Compute the Cholesky factor, R, of the symmetric 
-		positive definite.
-* spcholinv::	Use the Cholesky factorization to compute the inverse of the
-		sparse symmetric positive definite matrix A.
-* spchol2inv::	Invert a sparse symmetric, positive definite square matrix
-		from its Cholesky decomposition, U.
-* spconvert::	This function converts for a simple sparse matrix format
-		easily produced by other programs into Octave's internal
-		sparse format.
-* spcumprod::	Cumulative product of elements along dimension DIM.
-* spcumsum::	Cumulative sum of elements along dimension DIM.
-* spdet::	Compute the determinant of sparse matrix A using UMFPACK.
-* spdiag::	Return a diagonal matrix with the sparse vector V on
-		diagonal K.
-* spdiags::	A generalization of the function `spdiag'.
-* speye::	Returns a sparse identity matrix.
-* spfind::	SPFIND: a sparse version of the find operator 1.
-* spfun::	Compute `f(X)' for the non-zero values of X This results in
-		a sparse matrix with the same structure as X.
-* spinv::	Compute the inverse of the square matrix A.
-* spkron::	Form the kronecker product of two sparse matrices.
-* splchol::	Compute the Cholesky factor, L, of the symmetric positive 
-		definite.
-* splu::	Compute the LU decomposition of the sparse matrix A, using
-		subroutines from UMFPACK.
-* spmax::	For a vector argument, return the maximum value.
-* spmin::	For a vector argument, return the minimum value.
-* spones::	Replace the non-zero entries of X with ones.
-* spparms::	Sets or displays the parameters used by the sparse solvers
-		and factorization functions.
-* spprod::	Product of elements along dimension DIM.
-* spqr::	Compute the sparse QR factorization of @var{a}, using CSPARSE.
-* sprand::	Generate a random sparse matrix.
-* sprandn::	Generate a random sparse matrix.
-* sprandsym::	Generate a symmetric random sparse matrix.
-* sprank::	Calculates the structural rank of a sparse matrix @var{s}.
-* spstats::	Return the stats for the non-zero elements of the sparse
-		matrix S COUNT is the number of non-zeros in each column,
-		MEAN is the mean of the non-zeros in each column, and VAR
-		is the variance of the non-zeros in each column
-* spsum::	Sum of elements along dimension DIM.
-* spsumsq::	Sum of squares of elements along dimension DIM.
-* spy:: 	Plot the sparsity pattern of the sparse matrix X
-* symamd::	For a symmetric positive definite matrix S, returns the
-		permutation vector p such that `S (P, P)' tends to have a
-		sparser Cholesky factor than S.
-* symbfact::	Performs a symbolic factorization analysis on the sparse
-		matrix S.
-* treeplot::	Produces a graph of a tree or forest.
-@end menu
-
-@node colamd, ccolamd, , Function Reference
-@subsubsection colamd
-
-@DOCSTRING(colamd)
-
-@node ccolamd, colperm, colamd, Function Reference
-@subsubsection ccolamd
-
-@DOCSTRING(ccolamd)
-
-@node colperm, csymamd, ccolamd, Function Reference
-@subsubsection colperm
-
-@DOCSTRING(colperm)
-
-@node csymamd, dmperm, colperm, Function Reference
-@subsubsection csymamd
-
-@DOCSTRING(csymamd)
-
-@node dmperm, etree, csymamd, Function Reference
-@subsubsection dmperm
-
-@DOCSTRING(dmperm)
-
-@node etree, etreeplot, dmperm, Function Reference
-@subsubsection etree
-
-@DOCSTRING(etree)
-
-@node etreeplot, full, etree, Function Reference
-@subsubsection etreeplot
-
-@DOCSTRING(etreeplot)
-
-@node full, gplot, etreeplot, Function Reference
-@subsubsection full
-
-@DOCSTRING(full)
-
-@node gplot, issparse, full, Function Reference
-@subsubsection gplot
-
-@DOCSTRING(gplot)
-
-@node issparse, luinc, gplot, Function Reference
-@subsubsection issparse
-
-@DOCSTRING(issparse)
-
-@node luinc, normest, issparse, Function Reference
-@subsubsection luinc
-
-@DOCSTRING(luinc)
-
-@node normest, nnz, luinc, Function Reference
-@subsubsection normest
-
-@DOCSTRING(normest)
-
-@node nnz, nonzeros, normest, Function Reference
-@subsubsection nnz
-
-@DOCSTRING(nnz)
-
-@node nonzeros, nzmax, nnz, Function Reference
-@subsubsection nonzeros
-
-@DOCSTRING(nonzeros)
-
-@node nzmax, pcg, nonzeros, Function Reference
-@subsubsection nzmax
-
-@DOCSTRING(nzmax)
-
-@node pcg, pcr, nzmax, Function Reference
-@subsubsection pcg
-
-@DOCSTRING(pcg)
-
-@node pcr, spalloc, pcg, Function Reference
-@subsubsection pcr
-
-@DOCSTRING(pcr)
-
-@node spalloc, sparse, pcr, Function Reference
-@subsubsection spalloc
-
-@DOCSTRING(spalloc)
-
-@node sparse, spatan2, spalloc, Function Reference
-@subsubsection sparse
-
-@DOCSTRING(sparse)
-
-@node spatan2, spchol, sparse, Function Reference
-@subsubsection spatan2
-
-@DOCSTRING(spatan2)
-
-@node spchol, spcholinv, spatan2, Function Reference
-@subsubsection spchol
-
-@DOCSTRING(spchol)
-
-@node spcholinv, spchol2inv, spchol, Function Reference
-@subsubsection spcholinv
-
-@DOCSTRING(spcholinv)
-
-@node spchol2inv, spconvert, spcholinv, Function Reference
-@subsubsection spchol2inv
-
-@DOCSTRING(spchol2inv)
-
-@node spconvert, spcumprod, spchol2inv, Function Reference
-@subsubsection spconvert
-
-@DOCSTRING(spconvert)
-
-@node spcumprod, spcumsum, spconvert, Function Reference
-@subsubsection spcumprod
-
-@DOCSTRING(spcumprod)
-
-@node spcumsum, spdet, spcumprod, Function Reference
-@subsubsection spcumsum
-
-@DOCSTRING(spcumsum)
-
-@node spdet, spdiag, spcumsum, Function Reference
-@subsubsection spdet
-
-@DOCSTRING(spdet)
-
-@node spdiag, spdiags, spdet, Function Reference
-@subsubsection spdiag
-
-@DOCSTRING(spdiag)
-
-@node spdiags, speye, spdiag, Function Reference
-@subsubsection spdiags
-
-@DOCSTRING(spdiags)
-
-@node speye, spfind, spdiags, Function Reference
-@subsubsection speye
-
-@DOCSTRING(speye)
-
-@node spfind, spfun, speye, Function Reference
-@subsubsection spfind
-
-@DOCSTRING(spfind)
-
-@node spfun, spinv, spfind, Function Reference
-@subsubsection spfun
-
-@DOCSTRING(spfun)
-
-@node spinv, spkron, spfun, Function Reference
-@subsubsection spinv
-
-@DOCSTRING(spinv)
-
-@node spkron, splchol, spinv, Function Reference
-@subsubsection spkron
-
-@DOCSTRING(spkron)
-
-@node splchol, splu, spkron, Function Reference
-@subsubsection splchol
-
-@DOCSTRING(splchol)
-
-@node splu, spmax, splchol, Function Reference
-@subsubsection splu
-
-@DOCSTRING(splu)
-
-@node spmax, spmin, splu, Function Reference
-@subsubsection spmax
-
-@DOCSTRING(spmax)
-
-@node spmin, spones, spmax, Function Reference
-@subsubsection spmin
-
-@DOCSTRING(spmin)
-
-@node spones, spparms, spmin, Function Reference
-@subsubsection spones
-
-@DOCSTRING(spones)
-
-@node spparms, spprod, spones, Function Reference
-@subsubsection spparms
-
-@DOCSTRING(spparms)
-
-@node spprod, spqr, spparms, Function Reference
-@subsubsection spprod
-
-@DOCSTRING(spprod)
-
-@node spqr, sprand, spprod, Function Reference
-@subsubsection spqr
-
-@DOCSTRING(spqr)
-
-@node sprand, sprandn, spqr, Function Reference
-@subsubsection sprand
-
-@DOCSTRING(sprand)
-
-@node sprandn, sprandsym, sprand, Function Reference
-@subsubsection sprandn
-
-@DOCSTRING(sprandn)
-
-@node sprandsym, sprank, sprandn, Function Reference
-@subsubsection sprandsym
-
-@DOCSTRING(sprandsym)
-
-@node sprank, spstats, sprandsym, Function Reference
-@subsubsection sprank
-
-@DOCSTRING(sprank)
-
-@node spstats, spsum, sprank, Function Reference
-@subsubsection spstats
-
-@DOCSTRING(spstats)
-
-@node spsum, spsumsq, spstats, Function Reference
-@subsubsection spsum
-
-@DOCSTRING(spsum)
-
-@node spsumsq, spy, spsum, Function Reference
-@subsubsection spsumsq
-
-@DOCSTRING(spsumsq)
-
-@node spy, symamd, spsumsq, Function Reference
-@subsubsection spy
-
-@DOCSTRING(spy)
-
-@node symamd, symbfact, spy, Function Reference
-@subsubsection symamd
-
-@DOCSTRING(symamd)
-
-@node symbfact, treeplot, symamd, Function Reference
-@subsubsection symbfact
-
-@DOCSTRING(symbfact)
-
-@node treeplot, ,symbfact, Function Reference
-@subsubsection treeplot
-
-@DOCSTRING(treeplot)
-
 @c Local Variables: ***
 @c Mode: texinfo ***
 @c End: ***
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,17 @@
+2007-05-14  Bob Weigel  <rweigel@gmu.edu>
+
+	* DLD-FUNCTIONS/svd.cc: Doc fix.
+
+2007-05-14  Thomas Weber  <thomas.weber.mail@gmail.com>
+
+	* DLD-FUNCTIONS/fft.cc (do_fft): Handle empty matrices.  New tests.
+
+2007-05-14  Søren Hauberg  <soren@hauberg.org>
+
+	* toplev.cc (Fatexit): Simplify example in doc string.
+	* help.cc (Flookfor): Doc fix.
+	* input.cc, 
+
 2007-05-13  Søren Hauberg  <soren@hauberg.org>
 
 	* toplev.cc (Fquit): Doc fix.
--- a/src/DLD-FUNCTIONS/fft.cc
+++ b/src/DLD-FUNCTIONS/fft.cc
@@ -99,7 +99,7 @@
   if (dim < 0)
     {
       for (octave_idx_type i = 0; i < dims.length (); i++)
-	if ( dims(i) > 1)
+	if (dims(i) > 1)
 	  {
 	    dim = i;
 	    break;
@@ -115,8 +115,8 @@
   else
     dims (dim) = n_points;
 
-  if (dims.all_zero () || n_points == 0)
-    return octave_value (Matrix ());
+  if (dims.any_zero () || n_points == 0)
+    return octave_value (NDArray (dims));
 
   if (arg.is_real_type ())
     {
@@ -146,6 +146,21 @@
   return retval;
 }
 
+/*
+
+%!error(fft())
+%!assert(fft([]), [])
+%!assert(fft(zeros(-1,-1)), [])
+%!assert(fft(zeros(1,-1)), [])
+%!assert(fft(zeros(-1,1)), [])
+%!assert(fft(0), 0)
+%!assert(fft(1), 1)
+%!assert(fft(1), 1)
+%!assert(fft(ones(2,2)), [2,2; 0,0])
+%!assert(fft(eye(2,2)), [1,1; 1,-1])
+
+*/
+
 
 DEFUN_DLD (fft, args, ,
   "-*- texinfo -*-\n\
--- a/src/DLD-FUNCTIONS/svd.cc
+++ b/src/DLD-FUNCTIONS/svd.cc
@@ -44,14 +44,14 @@
 @iftex\n\
 @tex\n\
 $$\n\
- A = U\\Sigma V^H\n\
+ A = U S V^H\n\
 $$\n\
 @end tex\n\
 @end iftex\n\
 @ifinfo\n\
 \n\
 @example\n\
-a = u * sigma * v'\n\
+A = U*S*V'\n\
 @end example\n\
 @end ifinfo\n\
 \n\
--- a/src/help.cc
+++ b/src/help.cc
@@ -1232,16 +1232,8 @@
 @deffn {Command} type options name @dots{}\n\
 Display the definition of each @var{name} that refers to a function.\n\
 \n\
-Normally also displays if each @var{name} is user-defined or builtin;\n\
+Normally also displays whether each @var{name} is user-defined or built-in;\n\
 the @code{-q} option suppresses this behaviour.\n\
-\n\
-Currently, Octave can only display functions that can be compiled\n\
-cleanly, because it uses its internal representation of the function to\n\
-recreate the program text.\n\
-\n\
-Comments are not displayed because Octave's parser currently discards\n\
-them as it converts the text of a function file to its internal\n\
-representation.  This problem may be fixed in a future release.\n\
 @end deffn")
 {
   octave_value retval;
@@ -1764,10 +1756,10 @@
 \n\
 Note that the ability of @code{lookfor} to correctly identify the first\n\
 sentence of the help of the functions is dependent on the format of the\n\
-functions help. All of the functions in octave itself will correctly\n\
+functions help. All of the functions in Octave itself will correctly\n\
 find the first sentence, but the same can not be guaranteed for other\n\
 functions. Therefore the use of the '-all' argument might be necessary\n\
-to find related functions that are not part of octave.\n\
+to find related functions that are not part of Octave.\n\
 @seealso{help, which}\n\
 @end deffn")
 {
--- a/src/input.cc
+++ b/src/input.cc
@@ -1212,8 +1212,9 @@
 @deftypefnx {Built-in Function} {@var{old_val} =} PS4 (@var{new_val})\n\
 Query or set the character string used to prefix output produced\n\
 when echoing commands when @code{echo_executing_commands} is enabled.\n\
-The default value is @code{\"+ \"}.  @xref{Invoking Octave}, for\n\
-a description of @code{--echo-commands}.\n\
+The default value is @code{\"+ \"}.\n\
+@xref{Invoking Octave from the Command Line}, for a description of\n\
+@code{--echo-commands}.\n\
 @seealso{echo_executing_commands, PS1, PS2}\n\
 @end deftypefn")
 {
--- a/src/toplev.cc
+++ b/src/toplev.cc
@@ -665,16 +665,15 @@
 \n\
 @example\n\
 @group\n\
-function print_fortune ()\n\
-  printf (\"\\n%s\\n\", system (\"fortune\"));\n\
-  fflush (stdout);\n\
+function bye_bye ()\n\
+  disp (\"Bye bye\");\n\
 endfunction\n\
-atexit (\"print_fortune\");\n\
+atexit (\"bye_bye\");\n\
 @end group\n\
 @end example\n\
 \n\
 @noindent\n\
-will print a message when Octave exits.\n\
+will print the message \"Bye bye\" when Octave exits.\n\
 @end deftypefn")
 {
   octave_value_list retval;