Documentation patch fo func.txi

[David Bateman]

Here is a patch that addresses a cut and paste error in the argnames
function and adds a little bit more explanation of the locking and
dispatch capabilities of Octave.

D.

Index: doc/interpreter/func.txi
===================================================================
RCS file: /usr/local/cvsroot/octave/doc/interpreter/func.txi,v
retrieving revision 1.24
diff -u -r1.24 func.txi
--- doc/interpreter/func.txi    24 Apr 2007 23:06:56 -0000      1.24
+++ doc/interpreter/func.txi    18 May 2007 22:32:51 -0000
@@ -599,12 +599,6 @@
 
 @DOCSTRING(mfilename)
 
address@hidden(mlock)
-
address@hidden(munlock)
-
address@hidden(mislocked)
-
 @DOCSTRING(addpath)
 
 @DOCSTRING(genpath)
@@ -625,14 +619,11 @@
 
 @DOCSTRING(ignore_function_time_stamp)
 
address@hidden(autoload)
-
address@hidden(builtin)
-
address@hidden(dispatch)
 
 @menu
 * Subfunctions::
+* Overloading and Autoloading::
+* Function Locking::
 @end menu
 
 @node Subfunctions
@@ -664,6 +655,71 @@
 function @code{f} or from the other subfunctions, but not from outside
 the file @file{f.m}.
 
address@hidden Overloading and Autoloading
address@hidden Overloading and Autoloading
+
+The @code{dispatch} function can be used to alias one function name to
+another. It can be used to alias all calls to a particular function name
+to another function, or the alias can be limited to only a particular
+variable type. Consider the example
+
address@hidden
address@hidden
+function y = spsin (x)
+  printf ("Calling spsin\n");
+  fflush(stdout);
+  y = spfun ("sin", x);
+endfunction
+
+dispatch ("sin", "spsin", "sparse matrix");
+y0 = sin(eye(3));
+y1 = sin(speye(3));
address@hidden group
address@hidden example
+
+Which aliases the @code{spsin} to @code{sin}, but only for real sparse
+matrices. Note that the builtin @code{sin} already  correctly treats
+sparse matrices and so this example is only illustrative.
+
address@hidden(dispatch)
+
address@hidden(builtin)
+
+A single dynamically linked file might define several
+functions. However, as Octave searches for functions based on the
+functions filename, Octave needs a manner in which to find each of the
+functions in the dynamically linked file. On operating systems that
+support symbolic links, it is possible to create a symbolic link to the
+original file for each of the functions which it contains.
+
+However, there is at least one well known operating system that doesn't
+support symbolic links. Making copies of the original file for each of
+the functions is also possible, but is undesirable as it multiples the
+amount of disk space used by Octave. Instead Octave supplies the
address@hidden function, that permits the user to define in which
+file a certain function will be found.
+
address@hidden(autoload)
+
address@hidden Function Locking
address@hidden Function Locking
+
+It is sometime desirable to lock a function into memory with the
address@hidden function. This is typically used for dynamically linked
+functions in Oct-files or mex-files, that contain some initialization,
+and it is desireable that a @code{clear} does not remove this
+initialization.
+
+This might equally be used to prevent changes to a function from having
+effect in Octave, though a similar effect can be had with the
address@hidden function.
+
address@hidden(mlock)
+
address@hidden(munlock)
+
address@hidden(mislocked)
+
 @node Script Files
 @section Script Files
 
Index: src/ov-fcn-inline.cc
===================================================================
RCS file: /usr/local/cvsroot/octave/src/ov-fcn-inline.cc,v
retrieving revision 1.32
diff -u -r1.32 ov-fcn-inline.cc
--- src/ov-fcn-inline.cc        16 May 2007 08:49:48 -0000      1.32
+++ src/ov-fcn-inline.cc        18 May 2007 22:32:52 -0000
@@ -809,7 +809,7 @@
 
 DEFUN (vectorize, args, ,
   "-*- texinfo -*-\n\
address@hidden {Built-in Function} {} argnames (@var{fun})\n\
address@hidden {Built-in Function} {} vectorize (@var{fun})\n\
 Create a vectorized version of the inline function @var{fun}\n\
 by replacing all occurrences of @code{*}, @code{/}, etc., with\n\
 @code{.*}, @code{./}, etc.\n\