Doc updates for 3.2

[David Bateman]

Since we are working towards a 3.2 release in the near future we have to
start updating the documentation for the changes that have been made.
The attached patch documents some of the functions that have been
recently added in a minimalistic fashion, and documents the single
precision type and the demotion of double to single precision values.

Other documentation updates that will be needed before a 3.2 release
seem to be to be

* Document the graphics changes made by Shai/Michael as needed.
* Document the object oriented stuff in a new chapter.
* Document the use of private directories.
* Document other functions that were ported from octave-forge (eg
imread, dlmwrite, etc)
* NEWS file.
* Other things ?

Maybe these should be added to your 3.1 status report John?

Regards
David

-- 
David Bateman                                address@hidden
Motorola Labs - Paris                        +33 1 69 35 48 04 (Ph) 
Parc Les Algorithmes, Commune de St Aubin    +33 6 72 01 06 33 (Mob) 
91193 Gif-Sur-Yvette FRANCE                  +33 1 69 35 77 01 (Fax) 

The information contained in this communication has been classified as: 

[x] General Business Information 
[ ] Motorola Internal Use Only 
[ ] Motorola Confidential Proprietary

# HG changeset patch
# User David Bateman <address@hidden>
# Date 1217252860 -7200
# Node ID c8c68f642e598e5d00cbc4815661584a48544922
# Parent  1fe0ba7bcb9ab897b9f56786e0ac7ec72b8897eb
Some documentation updates

diff --git a/doc/ChangeLog b/doc/ChangeLog
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,30 @@ 2008-07-27  David Bateman  <address@hidden
+2008-07-28  David Bateman  <address@hidden>
+
+       * interpreter/arith.txi: Document reallog, realpow and realsqrt.
+       * interpreter/dbug.txi: Document the means of setting a breakpoint
+       in a sub-function
+       * interpreter/func.txi: Document nargoutchk and symvar.
+       * interpreter/geometry.txi: Document rectint.
+       * interpreter/image.txi: Document contrast.
+       * interpreter/interp.txi: Document interp1q.
+       * interpreter/linalg.txi: Document planerot, rcond and subspace.
+       * interpreter/numbers.txi: Document data type demotion and single
+       precision data type.
+       * interpreter/plot.txi: Document ginput, gtext,
+       waitforbuttonpress, ezcontour, ezcontourf, ezpolar, ezplot3,
+       ezmesh, ezmeshc, ezsurf, ezsurfc, allchild, findobj and findall
+       functions.
+       * interpreter/quad.txi: Document quadv, quadgk, dblquad and
+       triplequad functions.
+       * interpreter/strings.txi: Document validstring, regexptranslate
+       and isstrprop functions.
+       * interpreter/system.txi: Document addtodate, filemarker and perl
+       functions.
+       * interpreter/var.txi: Document the genvarname and namelengthmax
+       functions.
+       * interpreter/octave.texi: Update table of contents for the above
+       changes.
+
 2008-07-27  David Bateman  <address@hidden>
 
        * interpreter/plot.txi: Document contourf.
diff --git a/doc/interpreter/arith.txi b/doc/interpreter/arith.txi
--- a/doc/interpreter/arith.txi
+++ b/doc/interpreter/arith.txi
@@ -90,6 +90,12 @@ each element of the matrix.
 
 @DOCSTRING(primes)
 
address@hidden(reallog)
+
address@hidden(realpow)
+
address@hidden(realsqrt)
+
 @DOCSTRING(rem)
 
 @DOCSTRING(round)
diff --git a/doc/interpreter/debug.txi b/doc/interpreter/debug.txi
--- a/doc/interpreter/debug.txi
+++ b/doc/interpreter/debug.txi
@@ -114,6 +114,32 @@ dbclear ("asind", dbstatus ("asind"));
 dbclear ("asind", dbstatus ("asind"));
 @end example
 
+A breakpoint can be set in a subfunction. For example if a file contains
+the functions
+
address@hidden
+function y = func1 (x)
+  y = func2 (x);
+endfunction
+function y = func2 (x)
+  y = x + 1;
+endfunction
address@hidden example
+
address@hidden
+then a breakpoint can be set at the start of the subfunction directly
+with
+
address@hidden
address@hidden
+dbstop (["func1", filemarker(), "func2"])
address@hidden 5
address@hidden group
address@hidden example
+
+Note that @code{filemarker} returns a character that marks the
+subfunctions from the file containing them.
+
 Another simple means of setting a breakpoint in an Octave script is the
 use of the @code{keyboard} function.
 
diff --git a/doc/interpreter/func.txi b/doc/interpreter/func.txi
--- a/doc/interpreter/func.txi
+++ b/doc/interpreter/func.txi
@@ -334,6 +334,8 @@ along with a warning.
 
 @DOCSTRING(nargchk)
 
address@hidden(nargoutchk)
+
 @node Variable-length Argument Lists
 @section Variable-length Argument Lists
 @cindex variable-length argument lists
@@ -1063,6 +1065,8 @@ writing @code{f(x)}.
 
 @DOCSTRING(vectorize)
 
address@hidden(symvar)
+
 @node Commands
 @section Commands
 
diff --git a/doc/interpreter/geometry.txi b/doc/interpreter/geometry.txi
--- a/doc/interpreter/geometry.txi
+++ b/doc/interpreter/geometry.txi
@@ -336,7 +336,11 @@ endfor
 @end group
 @end example
 
-Facets of the Voronoi diagram with a vertex at infinity have infinity area.
+Facets of the Voronoi diagram with a vertex at infinity have infinity
+area. A simplified version of @code{polyarea} for rectangles is
+available with @code{rectint}
+
address@hidden(rectint)
 
 @DOCSTRING(inpolygon)
 
diff --git a/doc/interpreter/image.txi b/doc/interpreter/image.txi
--- a/doc/interpreter/image.txi
+++ b/doc/interpreter/image.txi
@@ -152,6 +152,8 @@ between 0 and 1.
 
 @DOCSTRING(winter)
 
address@hidden(contrast)
+
 An additional colormap is @code{gmap40}. This code map contains only
 colors with integer values of the red, green and blue components. This
 workaround a limitation on gnuplot 4.0, that does not allow the color of
diff --git a/doc/interpreter/interp.txi b/doc/interpreter/interp.txi
--- a/doc/interpreter/interp.txi
+++ b/doc/interpreter/interp.txi
@@ -81,6 +81,12 @@ interpolation methods for a step functio
 interpolation methods for a step function}
 @end float
 @end ifnotinfo
+
+A simplified version of @code{interp1} that performs only linear
+interpolation is available in @code{interp1q}. This argument is slightly
+faster than @code{interp1} as to performs little error checking.
+
address@hidden(interp1q)
 
 Fourier interpolation, is a resampling technique where a signal is
 converted to the frequency domain, padded with zeros and then
diff --git a/doc/interpreter/linalg.txi b/doc/interpreter/linalg.txi
--- a/doc/interpreter/linalg.txi
+++ b/doc/interpreter/linalg.txi
@@ -95,6 +95,8 @@ flag a non-Hermitian matrix.
 
 @DOCSTRING(givens)
 
address@hidden(planerot)
+
 @DOCSTRING(inv)
 
 @DOCSTRING(matrix_type)
@@ -108,6 +110,8 @@ flag a non-Hermitian matrix.
 @DOCSTRING(pinv)
 
 @DOCSTRING(rank)
+
address@hidden(rcond)
 
 @DOCSTRING(trace)
 
@@ -142,6 +146,8 @@ flag a non-Hermitian matrix.
 
 @DOCSTRING(schur)
 
address@hidden(subspace)
+
 @DOCSTRING(svd)
 
 @c FIXME -- should there be a new section here?
diff --git a/doc/interpreter/numbers.txi b/doc/interpreter/numbers.txi
--- a/doc/interpreter/numbers.txi
+++ b/doc/interpreter/numbers.txi
@@ -84,16 +84,16 @@ You may also use @samp{j}, @samp{I}, or 
 
 @DOCSTRING(double)
 
address@hidden(single)
-
 @DOCSTRING(complex)
 
 @menu
-* Matrices::                    
-* Ranges::                      
+* Matrices::
+* Ranges::
+* Single Precision Data Types::
 * Integer Data Types::
 * Bit Manipulations::
-* Logical Values::              
+* Logical Values:: 
+* Promotion and Demotion of Data Types::
 * Predicates for Numeric Objects::  
 @end menu
 
@@ -399,6 +399,42 @@ expression to determine whether they are
 expression to determine whether they are all constants.  If they are, it
 replaces the range expression with a single range constant.
 
address@hidden Single Precision Data Types
address@hidden Single Precision Data Types
+
+Octave includes support for single precision data types, and most of the
+functions in Octave accept single precision values and return single
+precion answers. A single precision variable is created with the
address@hidden function.
+
address@hidden(single)
+
+for example
+
address@hidden
+sngl = single (rand (2, 2))
+    @result{} sngl = 0.37569   0.92982
+               0.11962   0.50876
+class (sngl)
+    @result{} single
address@hidden example
+
+Many functions can also return single precision values directly. For
+example
+
address@hidden
+ones (2, 2, "single")
+zeros (2, 2, "single")
+eye (2, 2,  "single")
+rand (2, 2, "single")
+NaN (2, 2, "single")
+NA (2, 2, "single")
+Inf (2, 2, "single")
address@hidden example
+
address@hidden
+will all return single precision matrices.
+
 @node Integer Data Types
 @section Integer Data Types
 
@@ -482,6 +518,8 @@ result is often floored to the nearest i
 result is often floored to the nearest integer. So, the result of
 @code{int32(5)./int32(8)} is @code{1}.
 
address@hidden(idivide)
+
 @node Bit Manipulations
 @section Bit Manipulations
 
@@ -606,6 +644,76 @@ or @code{false} functions.
 
 @DOCSTRING(false)
 
address@hidden Promotion and Demotion of Data Types
address@hidden Promotion and Demotion of Data Types
+
+Many operators and functions can work with mixed data types. For example
+
address@hidden
+uint8 (1) + 1
+    @result{} 2
address@hidden example
+
address@hidden
+where the above operator works with an 8-bit integer and a double precision
+value and returns an 8-bit integer value. Note that the type is demoted
+to an 8-bit integer, rather than promoted to a double precision value as
+might be expected. The reason is that if Octave promoted values in
+expressions like the above with all numerical constants would need to be
+explicitly cast to the appropriate data type type like
+
address@hidden
+uint8 (1) + uint8 (1)
+    @result{} 2
address@hidden example
+
address@hidden
+which becomes difficult for the user to apply uniformly and might allow
+hard to find bugs to be introduced. The same applies to single precision
+values where a mixed operation such as
+
address@hidden
+single (1) + 1
+    @result{} 2
address@hidden example
+
address@hidden
+returns a single precision value. The mixed operations that are valid
+and their returned data types are
+
address@hidden @columnfraction .2 .3 .3 .2
address@hidden @tab Mixed Operation @tab  Result @tab 
address@hidden @tab double OP single @tab single @tab
address@hidden @tab double OP integer @tab integer @tab
address@hidden @tab double OP char @tab double @tab
address@hidden @tab double OP logical @tab double @tab
address@hidden @tab single OP integer @tab integer @tab
address@hidden @tab single OP char @tab single @tab
address@hidden @tab single OP logical @tab single @tab
+
+The same logic applies to functions with mixed arguments such as
+
address@hidden
+min (single (1), 0)
+   @result 0
address@hidden example
+
address@hidden
+where the returned value is single precision.
+
+In the case of mixed type indexed assignments, the type is not
+changed. For example
+
address@hidden
+x = ones (2, 2);
+x (1, 1) = single (2)
+    @result{} x = 2   1
+            1   1
address@hidden example
+
address@hidden
+where @code{x} remains of the double precision. 
+
 @node Predicates for Numeric Objects
 @section Predicates for Numeric Objects
 
diff --git a/doc/interpreter/octave.texi b/doc/interpreter/octave.texi
--- a/doc/interpreter/octave.texi
+++ b/doc/interpreter/octave.texi
@@ -261,11 +261,13 @@ Built-in Data Types
 
 Numeric Data Types
 
-* Matrices::                    
-* Ranges::                      
+* Matrices::
+* Ranges::
+* Single Precision Data Types::
 * Integer Data Types::
 * Bit Manipulations::
-* Logical Values::              
+* Logical Values:: 
+* Promotion and Demotion of Data Types::
 * Predicates for Numeric Objects::  
 
 Matrices
diff --git a/doc/interpreter/optim.txi b/doc/interpreter/optim.txi
--- a/doc/interpreter/optim.txi
+++ b/doc/interpreter/optim.txi
@@ -137,3 +137,4 @@ the @code{gls} is needed.
 
 @DOCSTRING(gls)
 
address@hidden(lsqnonneg)
diff --git a/doc/interpreter/plot.txi b/doc/interpreter/plot.txi
--- a/doc/interpreter/plot.txi
+++ b/doc/interpreter/plot.txi
@@ -42,6 +42,7 @@ If you need finer control over graphics,
 * Multiple Plots on One Page::  
 * Multiple Plot Windows::       
 * Printing Plots::              
+* Interacting with plots::
 * Test Plotting Functions::     
 @end menu
 
@@ -67,23 +68,7 @@ command will open a separate plot window
 @caption{Simple Two-Dimensional Plot.}
 @end float
 
-The function @code{fplot} also generates two-dimensional plots with
-linear axes using a function name and limits for the range of the
-x-coordinate instead of the x and y data.  For example,
-
address@hidden
address@hidden
-fplot (@@sin, [-10, 10], 201);
address@hidden group
address@hidden example
-
address@hidden
-produces a plot that is equivalent to the one above, but also includes a
-legend displaying the name of the plotted function.
-
 @DOCSTRING(plot)
-
address@hidden(fplot)
 
 The functions @code{semilogx}, @code{semilogy}, and @code{loglog} are
 similar to the @code{plot} function, but produce plots in which one or
@@ -195,6 +180,37 @@ function.
 function.
 
 @DOCSTRING(caxis)
+
address@hidden Two-dimensional Function Plotting
address@hidden Two-dimensional Function Plotting
+
+Octave can plot a function from a function handle inline function or
+string defining the function without the user needing to explicitly
+create the data to be plotted. The function @code{fplot} also generates
+two-dimensional plots with linear axes using a function name and limits
+for the range of the x-coordinate instead of the x and y data.  For
+example,
+
address@hidden
address@hidden
+fplot (@@sin, [-10, 10], 201);
address@hidden group
address@hidden example
+
address@hidden
+produces a plot that is equivalent to the one above, but also includes a
+legend displaying the name of the plotted function.
+
address@hidden(fplot)
+
+Other functions that can create two-dimensional plots directly from a
+function include @code{ezcontour}, @code{ezcontourf} and @code{ezpolar}.
+
address@hidden(ezcontour)
+
address@hidden(ezcontourf)
+
address@hidden(ezpolar)
 
 @node Three-Dimensional Plotting
 @subsection Three-Dimensional Plotting
@@ -267,6 +283,19 @@ three-dimensional plots.
 @DOCSTRING(view)
 
 @DOCSTRING(shading)
+
address@hidden Two-dimensional Function Plotting
address@hidden Two-dimensional Function Plotting
+
address@hidden(ezplot3)
+
address@hidden(ezmesh)
+
address@hidden(ezmeshc)
+
address@hidden(ezsurf)
+
address@hidden(ezsurfc)
 
 @node Plot Annotations
 @subsection Plot Annotations
@@ -364,6 +393,19 @@ writes the current figure to an encapsul
 @DOCSTRING(print)
 
 @DOCSTRING(orient)
+
address@hidden Interacting with plots
address@hidden Interacting with plots
+
+The user can select points on a plot with the @code{ginput} function or
+selction the position at which to place text on the plot with the
address@hidden function using the mouse.
+
address@hidden(ginput)
+
address@hidden(waitforbuttonpress)
+
address@hidden(gtext)
 
 @node Test Plotting Functions
 @subsection Test Plotting Functions
@@ -506,6 +548,8 @@ objects.
 
 @DOCSTRING(ancestor)
 
address@hidden(allchild)
+
 You can create axes, line, and patch objects directly using the
 @code{axes}, @code{line}, and @code{patch} functions.  These objects
 become children of the current axes object.
@@ -579,6 +623,7 @@ figure window, call the @code{close} fun
 * Image Properties::            
 * Patch Properties::            
 * Surface Properties::          
+* Seacrhing Properties::
 @end menu
 
 @node Root Figure Properties
@@ -1138,6 +1183,14 @@ future version of Octave.
 future version of Octave.
 @end table
 
address@hidden Seacrhing Properties
address@hidden Seacrhing Properties
+
address@hidden(findobj)
+
address@hidden(findall)
+
+
 @node Managing Default Properties
 @subsection Managing Default Properties
 
diff --git a/doc/interpreter/quad.txi b/doc/interpreter/quad.txi
--- a/doc/interpreter/quad.txi
+++ b/doc/interpreter/quad.txi
@@ -50,6 +50,12 @@ Numerical integration based on Gaussian 
 @item quadl
 Numerical integration using an adaptive Lobatto rule.
 
address@hidden quadgk
+Numerical integration using an adaptive Guass-Konrod rule.
+
address@hidden quadv
+Numerical integration using an adaptive vectorized Simpson's rule.
+
 @item trapz
 Numerical integration using the trapezoidal method.
 @end table
@@ -117,6 +123,10 @@ if you move the lower bound to 0.1, then
 if you move the lower bound to 0.1, then 0.01, then 0.001, etc.).
 
 @DOCSTRING(quadl)
+
address@hidden(quadgk)
+
address@hidden(quadv)
 
 @DOCSTRING(trapz)
 
@@ -173,10 +183,10 @@ u = [ 0; (at - alpha * bt) \ rhs; 1]
 @node Functions of Multiple Variables
 @section Functions of Multiple Variables
 
-Octave does not have built-in functions for computing the integral
-of functions of multiple variables.  It is however possible to compute
-the integral of a function of multiple variables using the functions
-for one-dimensional integrals.
+Octave does not have built-in functions for computing the integral of
+functions of multiple variables directly.  It is however possible to
+compute the integral of a function of multiple variables using the
+functions for one-dimensional integrals.
 
 To illustrate how the integration can be performed, we will integrate
 the function
@@ -215,6 +225,19 @@ I = quadl("g", 0, 1)
       @result{} 0.30022
 @end example
 
+The above process can be simplified with the @code{dblquad} and
address@hidden functions for integrals over two and three
+variables. For example
+
address@hidden
+I =  dblquad (@(x, y) sin(pi.*x.*y).*sqrt(x.*y), 0, 1, 0, 1)
+      @result{} 0.30022
address@hidden example
+
address@hidden(dblquad)
+
address@hidden(triplequad)
+
 The above mentioned approach works but is fairly slow, and that problem
 increases exponentially with the dimensionality the problem.  Another
 possible solution is to use Orthogonal Collocation as described in the
@@ -250,4 +273,3 @@ of the approximation.  If the integratio
 
 
 
-
diff --git a/doc/interpreter/strings.txi b/doc/interpreter/strings.txi
--- a/doc/interpreter/strings.txi
+++ b/doc/interpreter/strings.txi
@@ -228,6 +228,8 @@ functions exist for doing case-insensiti
 
 @DOCSTRING(strncmpi)
 
address@hidden(validstring)
+
 @node Manipulating Strings
 @section Manipulating Strings
 
@@ -273,6 +275,8 @@ general regular expressions, the followi
 
 @DOCSTRING(regexprep)
 
address@hidden(regexptranslate)
+
 @node String Conversions
 @section String Conversions
 
@@ -358,3 +362,5 @@ isalpha ("!Q@@WERT^Y&")
 @DOCSTRING(isupper)
 
 @DOCSTRING(isxdigit)
+
address@hidden(isstrprop)
diff --git a/doc/interpreter/system.txi b/doc/interpreter/system.txi
--- a/doc/interpreter/system.txi
+++ b/doc/interpreter/system.txi
@@ -129,11 +129,13 @@ useful.
 
 @DOCSTRING(usleep)
 
address@hidden(  datenum)
address@hidden(datenum)
 
 @DOCSTRING(datestr)
 
 @DOCSTRING(datevec)
+
address@hidden(addtodate)
 
 @DOCSTRING(calendar)
 
@@ -195,6 +197,8 @@ about the status of files.
 @DOCSTRING(fileparts)
 
 @DOCSTRING(filesep)
+
address@hidden(filemarker)
 
 @DOCSTRING(fullfile)
 
@@ -250,6 +254,8 @@ higher-level functions.
 @DOCSTRING(unix)
 
 @DOCSTRING(dos)
+
address@hidden(perl)
 
 @DOCSTRING(popen)
 
diff --git a/doc/interpreter/var.txi b/doc/interpreter/var.txi
--- a/doc/interpreter/var.txi
+++ b/doc/interpreter/var.txi
@@ -70,6 +70,10 @@ before they have been given a value.  Do
 
 @DOCSTRING(isvarname)
 
address@hidden(genvarname)
+
address@hidden(namelengthmax)
+
 @menu
 * Global Variables::            
 * Persistent Variables::