--- a/.hgignore	Fri May 24 15:41:52 2013 -0400
+++ b/.hgignore	Thu Jul 04 10:09:58 2013 -0400
@@ -26,7 +26,7 @@
 ^build-.*($|/)
 ^configure$
 ^autom4te\.cache($|/)
-^config\.h\.in$
+^config\.in\.h$
 
 # e.g. doc/faq/OctaveFAQ.info
 #      doc/interpreter/octave.info-4

--- a/Makefile.am	Fri May 24 15:41:52 2013 -0400
+++ b/Makefile.am	Thu Jul 04 10:09:58 2013 -0400
@@ -69,16 +69,21 @@
 
 include m4/module.mk
 
-# Subdirectories in which to run `make all'.  Including "." here
-# is an attempt to force all preceding directories in the list to
-# be processed before the current directory so that the
+# Subdirectories in which to run `make all'.  Including "." before
+# @DOCDIR@ is an attempt to force all preceding directories in the list
+# to be processed before the current directory so that the
 # scripts/DOCSTRINGS libinterp/DOCSTRINGS files are built before
-# attempting to build AUTHORS and BUGS.
+# attempting to build AUTHORS and BUGS.  Including "." again at the end
+# of the list ensures that we display the "Octave sucessfully built..."
+# message at the very end of the output from Make.  Another fix for
+# these problems would be to continue eliminating the recursive make
+# invocations so that we have better control over the dependencies and
+# the order that things are built.
 SUBDIRS = libgnu liboctave libinterp
 if AMCOND_BUILD_GUI
 SUBDIRS += libgui
 endif
-SUBDIRS += src scripts . @DOCDIR@ examples test
+SUBDIRS += src scripts . @DOCDIR@ examples test .
 
 if ! AMCOND_BUILD_DOCS
 dist-hook:

--- a/NEWS	Fri May 24 15:41:52 2013 -0400
+++ b/NEWS	Thu Jul 04 10:09:58 2013 -0400
@@ -17,41 +17,6 @@
 Summary of important user-visible changes for version 3.8:
 ---------------------------------------------------------
 
- ** strsplit has been modified to be compatible with Matlab.  There
-    are two instances where backward compatibility is broken.
-
-    (1) Delimiters are now string vectors, not scalars.
-
-    Octave's legacy behavior
-
-      strsplit ("1 2, 3", ", ")
-      ans = 
-      {
-       [1,1] = 1
-       [1,2] = 2
-       [1,3] = 
-       [1,4] = 3
-      }
-
-    Matlab compatible behavior
-
-      strsplit ("1 2, 3", ", ")
-      ans = 
-      {
-       [1,1] = 1 2
-       [1,2] = 3
-      }
-
-    (2) By default, Matlab treats consecutive delimiters are as a single
-    delimiter.  By default, Octave's legacy behavior was to return an
-    empty string for the part between the delmiters.
-
-    Where the legacy behavior is desired, the call to strsplit() should
-    specify that the delimitertype is "legacy".
-
-    strsplit (str, del, "collapsedelimiters", false,
-      "delimitertype", "legacy")
-
  ** Octave now supports nested functions with scoping rules that are
     compatible with Matlab.  A nested function is one declared and defined
     within the body of another function.  The nested function is only
@@ -117,12 +82,6 @@
     Octave:array-as-scalar => Octave:array-to-scalar
     Octave:array-as-vector => Octave:array-to-vector
 
- ** The colormap function now provides new options--"list", "register",
-    and "unregister"--to list all available colormap functions, and to
-    add or remove a function name from the list of known colormap
-    functions.  Packages that implement extra colormaps should use these
-    commands with PKG_ADD and PKG_DEL statements.
-
  ** The m-files in the image directory have been overhauled.
 
     The principal benefit is that Octave will now no longer automatically
@@ -135,6 +94,45 @@
     colormap depending on the image class (integer images have a -1 offset to
     the colormap row number).
 
+ ** The colormap function now provides new options--"list", "register",
+    and "unregister"--to list all available colormap functions, and to
+    add or remove a function name from the list of known colormap
+    functions.  Packages that implement extra colormaps should use these
+    commands with PKG_ADD and PKG_DEL statements.
+
+ ** strsplit has been modified to be compatible with Matlab.  There
+    are two instances where backward compatibility is broken.
+
+    (1) Delimiters are now string vectors, not scalars.
+
+    Octave's legacy behavior
+
+      strsplit ("1 2, 3", ", ")
+      ans = 
+      {
+       [1,1] = 1
+       [1,2] = 2
+       [1,3] = 
+       [1,4] = 3
+      }
+
+    Matlab compatible behavior
+
+      strsplit ("1 2, 3", ", ")
+      ans = 
+      {
+       [1,1] = 1 2
+       [1,2] = 3
+      }
+
+    (2) By default, Matlab treats consecutive delimiters are as a single
+    delimiter.  By default, Octave's legacy behavior was to return an
+    empty string for the part between the delmiters.
+
+    Where the legacy behavior is desired, the call to strsplit() may be
+    replaced by ostrsplit(), which is Octave's original implementation of
+    strsplit().
+
  ** The datevec function has been extended for better Matlab compatibility.
     It now accepts string inputs in the following numerical formats: 12, 21,
     22, 26, 29, 31.  This is undocumented, but verifiable, Matlab behavior.
@@ -178,20 +176,28 @@
 
  ** Other new functions added in 3.8.0:
 
-      betaincinv   ellipj    findfigs     polyeig       tetramesh
-      cmpermute    ellipke   fminsearch   rgbplot       waterfall
-      cmunique     erfcinv   importdata   shrinkfaces   gallery
-      colorcube    erfi      iscolormap   splinefit
-      dawson       expint    lines        strjoin
+      base64_decode               ellipke         lines      
+      base64_encode               erfcinv         polyeig                   
+      betaincinv                  erfi            readline_re_read_init_file
+      built_in_docstrings_file    expint          readline_read_init_file 
+      cmpermute                   findfigs        rgbplot               
+      cmunique                    fminsearch      save_default_options  
+      colorcube                   gallery         shrinkfaces           
+      copyobj                     gco             splinefit             
+      dawson                      hdl2struct      stemleaf           
+      dblist                      history_save    strjoin             
+      debug_jit                   importdata      struct2hdl          
+      doc_cache_create            iscolormap      tetramesh           
+      ellipj                      jit_enable      waterfall  
 
  ** Deprecated functions.
 
     The following functions were deprecated in Octave 3.4 and have been
     removed from Octave 3.8.
                                            
-      autocor    dispatch              is_global    strerror
-      autocov    fstat                 krylovb      values  
-      betai      gammai                perror               
+      autocor    dispatch              is_global    setstr
+      autocov    fstat                 krylovb      strerror
+      betai      gammai                perror       values
       cellidx    glpkmex               replot               
       cquad      is_duplicate_entry    saveimage            
       
@@ -199,16 +205,14 @@
     be removed from Octave 3.12 (or whatever version is the second major
     release after 3.8):
 
-      java_convert_matrix
-      java_debug
-      java_get
-      java_invoke
-      java_new
-      java_set
-      java_unsigned_conversion
-      javafields
-      javamethods
-
+      default_save_options    java_set                  
+      gen_doc_cache           java_unsigned_conversion  
+      java_convert_matrix     javafields                
+      java_debug              javamethods               
+      java_get                re_read_readline_init_file
+      java_invoke             read_readline_init_file   
+      java_new                saving_history            
+      
     The following keywords have been deprecated in Octave 3.8 and will
     be removed from Octave 3.12 (or whatever version is the second major
     release after 3.8):

--- a/configure.ac	Fri May 24 15:41:52 2013 -0400
+++ b/configure.ac	Thu Jul 04 10:09:58 2013 -0400
@@ -2645,7 +2645,7 @@
       ## Let's assume Qscintilla library is at the same location as
       ## other regular Qt libraries.
       QT_LIBS="$QT_LIBS -lqscintilla2"
-      OCTAVE_CHECK_FUNC_FINDFIRST_MODERN
+      OCTAVE_CHECK_VERSION_2_6_0
       AC_DEFINE(HAVE_QSCINTILLA, 1, 
         [Define to 1 if the QScintilla library and header files are available])
 

--- a/doc/interpreter/Makefile.am	Fri May 24 15:41:52 2013 -0400
+++ b/doc/interpreter/Makefile.am	Thu Jul 04 10:09:58 2013 -0400
@@ -58,7 +58,6 @@
   $(top_srcdir)/examples/addtwomatrices.cc \
   $(top_srcdir)/examples/celldemo.cc \
   $(top_srcdir)/examples/embedded.cc \
-  $(top_srcdir)/examples/firstmexdemo.c \
   $(top_srcdir)/examples/fortdemo.cc \
   $(top_srcdir)/examples/fortsub.f \
   $(top_srcdir)/examples/funcdemo.cc \
@@ -67,6 +66,7 @@
   $(top_srcdir)/examples/mycell.c \
   $(top_srcdir)/examples/myfeval.c \
   $(top_srcdir)/examples/myfunc.c \
+  $(top_srcdir)/examples/myhello.c \
   $(top_srcdir)/examples/mypow2.c \
   $(top_srcdir)/examples/mysparse.c \
   $(top_srcdir)/examples/mystring.c \
@@ -125,7 +125,7 @@
   debug.texi \
   diffeq.texi \
   diagperm.texi \
-  dynamic.texi \
+  external.texi \
   emacs.texi \
   errors.texi \
   eval.texi \

--- a/doc/interpreter/arith.txi	Fri May 24 15:41:52 2013 -0400
+++ b/doc/interpreter/arith.txi	Thu Jul 04 10:09:58 2013 -0400
@@ -311,7 +311,7 @@
 
 @DOCSTRING(legendre)
 
-@anchor{doc-gammaln}
+@anchor{docXgammaln}
 @DOCSTRING(lgamma)
 
 @node Rational Approximations

--- a/doc/interpreter/basics.txi	Fri May 24 15:41:52 2013 -0400
+++ b/doc/interpreter/basics.txi	Thu Jul 04 10:09:58 2013 -0400
@@ -67,6 +67,13 @@
 
 
 @table @code
+
+@item --built-in-docstrings-file @var{filename}
+@cindex @code{--built-in-docstrings-file @var{filename}}
+Specify the name of the file containing documentation strings for the
+built-in functions of Octave.  This value is normally correct and should
+only need to specified in extraordinary situations.
+
 @item  --debug
 @itemx -d
 @cindex @code{--debug}
@@ -75,6 +82,10 @@
 parser to print a lot of information about the commands it reads, and is
 probably only useful if you are actually trying to debug the parser.
 
+@item --debug-jit
+@cindex @code{--debug-jit}
+Enable JIT compiler debugging and tracing.
+
 @item --doc-cache-file @var{filename}
 @cindex @code{--doc-cache-file @var{filename}}
 Specify the name of the doc cache file to use.  The value of @var{filename}
@@ -145,10 +156,6 @@
 remote shell command or inside an Emacs shell buffer.  For another way
 to run Octave within Emacs, see @ref{Emacs Octave Support}.
 
-@item --jit-debug
-@cindex @code{--jit-debug}
-Enable JIT compiler debugging and tracing.
-
 @item --line-editing
 @cindex @code{--line-editing}
 Force readline use for command-line editing.
@@ -185,7 +192,8 @@
 @cindex @code{--no-site-file}
 Don't read the site-wide @file{octaverc} initialization files.
 
-@item --no-window-system
+@item  --no-window-system
+@itemx -W
 @cindex @code{--no-window-system}
 Disable use of a windowing system including graphics.  This forces a
 strictly terminal-only environment.
@@ -240,7 +248,7 @@
 beep_on_error                   = true
 confirm_recursive_rmdir         = false
 crash_dumps_octave_core         = false
-default_save_options            = "-mat-binary"
+save_default_options            = "-mat-binary"
 do_braindead_shortcircuit_evaluation = true
 fixed_point_format              = true
 history_timestamp_format_string = "%%-- %D %I:%M %p --%%"
@@ -264,8 +272,8 @@
 @noindent
 Note that this does not enable the @code{Octave:matlab-incompatible}
 warning, which you might want if you want to be told about writing code
-that works in Octave but not Matlab (@pxref{doc-warning},
-@pxref{doc-warning_ids}).
+that works in Octave but not @sc{matlab} (@pxref{docXwarning},
+@pxref{docXwarning_ids}).
 
 @item  --verbose
 @itemx -V
@@ -425,13 +433,15 @@
 
 @DOCSTRING(doc_cache_file)
 
+@DOCSTRING(built_in_docstrings_file)
+
 @DOCSTRING(suppress_verbose_help_message)
 
 The following functions are principally used internally by Octave for
 generating the documentation.  They are documented here for completeness
 and because they may occasionally be useful for users.
 
-@DOCSTRING(gen_doc_cache)
+@DOCSTRING(doc_cache_create)
 
 @DOCSTRING(get_help_text)
 
@@ -712,7 +722,7 @@
 Octave also allows you customize the details of when, where, and how history
 is saved.
 
-@DOCSTRING(saving_history)
+@DOCSTRING(history_save)
 
 @DOCSTRING(history_control)
 
@@ -739,9 +749,9 @@
 Octave provides two commands for initializing Readline and thereby changing
 the command line behavior.
 
-@DOCSTRING(read_readline_init_file)
+@DOCSTRING(readline_read_init_file)
 
-@DOCSTRING(re_read_readline_init_file)
+@DOCSTRING(readline_re_read_init_file)
 
 @node Customizing the Prompt
 @subsection Customizing the Prompt

--- a/doc/interpreter/container.txi	Fri May 24 15:41:52 2013 -0400
+++ b/doc/interpreter/container.txi	Thu Jul 04 10:09:58 2013 -0400
@@ -38,7 +38,7 @@
 @cindex structures
 @cindex data structures
 
-Octave includes support for organizing data in structures. The current
+Octave includes support for organizing data in structures.  The current
 implementation uses an associative array with indices limited to
 strings, but the syntax is more like C-style structures.
 
@@ -392,7 +392,7 @@
 
 @noindent
 Dynamic indexing also allows you to use arbitrary strings, not merely
-valid Octave identifiers (note that this does not work on @sc{Matlab}):
+valid Octave identifiers (note that this does not work on @sc{matlab}):
 
 @example
 @group
@@ -410,7 +410,7 @@
 
 @noindent
 The warning id @code{Octave:matlab-incompatible} can be enabled to warn
-about this usage. @xref{doc-warning_ids}.
+about this usage.  @xref{docXwarning_ids}.
 
 More realistically, all of the functions that operate on strings can be used
 to build the correct field name before it is entered into the data structure.
@@ -529,7 +529,7 @@
 The simplest way to process data in a structure is within a @code{for}
 loop (@pxref{Looping Over Structure Elements}).  A similar effect can be
 achieved with the @code{structfun} function, where a user defined
-function is applied to each field of the structure.  @xref{doc-structfun}.
+function is applied to each field of the structure.  @xref{docXstructfun}.
 
 Alternatively, to process the data in a structure, the structure might
 be converted to another type of container before being treated.
@@ -683,10 +683,10 @@
 @end example
 
 @noindent
-As can be seen, the @ref{doc-size, @code{size}} function also works
+As can be seen, the @ref{docXsize, @code{size}} function also works
 for cell arrays.  As do other functions describing the size of an
-object, such as @ref{doc-length, @code{length}}, @ref{doc-numel,
-@code{numel}}, @ref{doc-rows, @code{rows}}, and @ref{doc-columns,
+object, such as @ref{docXlength, @code{length}}, @ref{docXnumel,
+@code{numel}}, @ref{docXrows, @code{rows}}, and @ref{docXcolumns,
 @code{columns}}.
 
 @DOCSTRING(cell)
@@ -907,7 +907,7 @@
 is to iterate through it using one or more @code{for} loops.  The same
 idea can be implemented more easily through the use of the @code{cellfun}
 function that calls a user-specified function on all elements of a cell
-array.  @xref{doc-cellfun}.
+array.  @xref{docXcellfun}.
 
 An alternative is to convert the data to a different container, such as
 a matrix or a data structure.  Depending on the data this is possible

--- a/doc/interpreter/contrib.txi	Fri May 24 15:41:52 2013 -0400
+++ b/doc/interpreter/contrib.txi	Thu Jul 04 10:09:58 2013 -0400
@@ -41,7 +41,7 @@
 development of Octave core, i.e., code that goes to Octave directly.
 You may consider developing and publishing a package instead; a great
 place for this is the allied Octave-Forge project
-(@url{http://octave.sourceforge.net}).  Note that the Octave project is
+(@url{http://octave.sourceforge.net}).  Note that the Octave core project is
 inherently more conservative and follows narrower rules.
 
 @node Building the Development Sources
@@ -56,8 +56,8 @@
 @section Basics of Generating a Changeset
 
 The preferable form of contribution is creating a Mercurial changeset
-and submit it to the @uref{http://savannah.gnu.org/bugs/?group=octave, bug} or
-@uref{http://savannah.gnu.org/patch/?func=additem&group=octave, patch}
+and submit it to the @url{http://savannah.gnu.org/bugs/?group=octave, bug} or
+@url{http://savannah.gnu.org/patch/?func=additem&group=octave, patch}
 trackers@footnote{Please use the patch tracker only for patches which add new
 features.  If you have a patch to submit that fixes a bug, you should use the
 bug tracker instead.}.
@@ -89,7 +89,18 @@
 @end example
 
 You may want to get familiar with Mercurial queues to manage your
-changesets.  Here is a slightly more complex example using Mercurial
+changesets.  For working with queues you have to activate the extension
+@nospell{mq} with the following entry in Mercurial's configuration file
+@file{.hgrc} (or @file{Mercurial.ini} on Windows):
+
+@example
+@group
+[extensions]
+mq=
+@end group
+@end example
+
+Here is a slightly more complex example using Mercurial
 queues, where work on two unrelated changesets is done in parallel and
 one of the changesets is updated after discussion on the bug tracker:
 
@@ -122,6 +133,60 @@
 # attach ../nasty2.diff to your bug report
 @end example
 
+Mercurial has a more useful extensions that really should be enabled.
+They are not enabled by default due to a number of factors
+(mostly because they don't work in all terminal types).
+
+The following entries in the @file{.hgrc} are recommended
+
+@example
+@group
+[extensions]
+graphlog=
+color=
+progress=
+pager=
+@end group
+@end example
+
+For the color extension, default color and formatting
+of @code{hg status} can be modified by
+
+@example
+@group
+[color]
+status.modified = magenta bold
+status.added = green bold
+status.removed = red bold
+status.deleted = cyan bold
+status.unknown = black  bold
+status.ignored = black bold
+@end group
+@end example
+
+Sometimes a few further improvements for the pager extension are
+necessary.  The following options should not be enabled unless paging
+isn't working correctly:
+
+@example
+@group
+[pager]
+# Some options for the less pager, see less(1) for their meaning.
+pager = LESS='FSRX' less
+
+# Some commands that aren't paged by default; also enable paging
+# for them
+attend = tags, help, annotate, cat, diff, export, status, \
+         outgoing, incoming
+@end group
+@end example
+
+Enabling the described extensions should immediately lead to a difference
+when using the command line version of @nospell{hg}.  Of these options, the
+only one that enables a new command is @nospell{graphlog}.  It is recommanded
+that you use the command @code{hg glog} instead of @code{hg log} for a better
+feel what commits are being based on.
+
 @node General Guidelines
 @section General Guidelines
 
@@ -364,7 +429,7 @@
 @node Other Sources
 @section Other Sources
 Apart from C++ and Octave language (m-files), Octave's sources include
-files written in C, Fortran, M4, Perl, Unix shell, AWK, Texinfo and
+files written in C, Fortran, M4, Perl, Unix shell, AWK, Texinfo, and
 @TeX{}.  There are not many rules to follow when using these other
 languages; some of them are summarized below.  In any case, the golden
 rule is: if you modify a source file, try to follow any conventions you

--- a/doc/interpreter/contributors.in	Fri May 24 15:41:52 2013 -0400
+++ b/doc/interpreter/contributors.in	Thu Jul 04 10:09:58 2013 -0400
@@ -36,6 +36,7 @@
 Clinton Chee
 Albert Chin-A-Young
 Carsten Clark
+Catalin Codreanu
 J. D. Cole
 Martin Costabel
 Michael Creel

--- a/doc/interpreter/data.txi	Fri May 24 15:41:52 2013 -0400
+++ b/doc/interpreter/data.txi	Thu Jul 04 10:09:58 2013 -0400
@@ -27,10 +27,10 @@
 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
 dynamically while Octave is running, so it is not necessary to recompile
-all of Octave just to add a new type.  @xref{Dynamically Linked
-Functions}, for more information about Octave's dynamic linking
-capabilities.  @ref{User-defined Data Types} describes what you must do
-to define a new data type for Octave.
+all of Octave just to add a new type.  @xref{External Code Interface}, for
+more information about Octave's dynamic linking capabilities.
+@ref{User-defined Data Types} describes what you must do to define a
+new data type for Octave.
 
 @DOCSTRING(typeinfo)
 

--- a/doc/interpreter/debug.txi	Fri May 24 15:41:52 2013 -0400
+++ b/doc/interpreter/debug.txi	Thu Jul 04 10:09:58 2013 -0400
@@ -91,32 +91,33 @@
 @example
 @group
 dbstop ("asind", 1)
-@result{} 28
+@result{} 29
 @end group
 @end example
 
 @noindent
-Note that the return value of @code{27} means that the breakpoint was
-effectively set to line 27.  The status of breakpoints in a function can
+Note that the return value of @code{29} means that the breakpoint was
+effectively set to line 29.  The status of breakpoints in a function can
 be queried with the @code{dbstatus} function.
 
 @DOCSTRING(dbstatus)
 
 @noindent
-Taking the above as an example, @code{dbstatus ("asind")} should return
-28.  The breakpoints can then be cleared with the @code{dbclear} function
+Reusing the previous example, @code{dbstatus ("asind")} will return
+29.  The breakpoints listed can then be cleared with the @code{dbclear}
+function.
 
 @DOCSTRING(dbclear)
 
 @noindent
-These functions can be used to clear all the breakpoints in a function.  For
-example:
+These functions can be used together to clear all the breakpoints in a
+particular function.  For example:
 
 @example
 dbclear ("asind", dbstatus ("asind"));
 @end example
 
-A breakpoint can be set in a subfunction.  For example if a file contains
+A breakpoint may also be set in a subfunction.  For example, if a file contains
 the functions
 
 @example
@@ -151,13 +152,13 @@
 
 @noindent
 The @code{keyboard} function is typically placed in a script at the
-point where the user desires that the execution is stopped.  It
+point where the user desires that the execution be stopped.  It
 automatically sets the running script into the debug mode.
 
 @node Debug Mode
 @section Debug Mode
 
-There are two additional support functions that allow the user to
+There are three additional support functions that allow the user to
 interrogate where in the execution of a script Octave entered the debug
 mode and to print the code in the script surrounding the point where
 Octave entered debug mode.
@@ -166,16 +167,23 @@
 
 @DOCSTRING(dbtype)
 
+@DOCSTRING(dblist)
+
 You may also use @code{isdebugmode} to determine whether the debugger is
 currently active.
 
 @DOCSTRING(isdebugmode)
 
 Debug mode also allows single line stepping through a function using
-the commands @code{dbstep}.
+the command @code{dbstep}.
 
 @DOCSTRING(dbstep)
 
+When in debug mode the @key{RETURN} will execute the last entered command.
+This is useful, for example, after hitting a breakpoint and entering
+@code{dbstep}.  After that one can advance line by line through the code
+with only a single key stroke.
+
 @node Call Stack
 @section Call Stack
 

--- a/doc/interpreter/diagperm.txi	Fri May 24 15:41:52 2013 -0400
+++ b/doc/interpreter/diagperm.txi	Thu Jul 04 10:09:58 2013 -0400
@@ -519,6 +519,7 @@
 
 @item permutation matrix * matrix is equivalent to permuting rows
 @end itemize
+
 all of these natural mathematical truths would be invalidated by treating
 assumed zeros as numerical ones.
 

--- a/doc/interpreter/diffeq.txi	Fri May 24 15:41:52 2013 -0400
+++ b/doc/interpreter/diffeq.txi	Thu Jul 04 10:09:58 2013 -0400
@@ -69,6 +69,7 @@
 
 @example
 @group
+## oregonator differential equation
 function xdot = f (x, t)
 
   xdot = zeros (3,1);
@@ -109,6 +110,10 @@
 Solvers}, in Scientific Computing, R. S. Stepleman, editor, (1983) for
 more information about the inner workings of @code{lsode}.
 
+An m-file for the differential equation used above is included with the
+Octave distribution in the examples directory under the name
+@file{oregonator.m}.
+
 @node Differential-Algebraic Equations
 @section Differential-Algebraic Equations
 

--- a/doc/interpreter/doccheck/aspell-octave.en.pws	Fri May 24 15:41:52 2013 -0400
+++ b/doc/interpreter/doccheck/aspell-octave.en.pws	Thu Jul 04 10:09:58 2013 -0400
@@ -20,8 +20,11 @@
 anova
 Anymap
 API
+APIs
+appdata
 approximant
 arg
+args
 ARMA
 arpack
 ascii
@@ -49,6 +52,7 @@
 Backends
 backends
 bartlett
+BaseValue
 Bateman
 BDF
 bdf
@@ -82,6 +86,7 @@
 boxxyerrorbars
 bracketx
 brackety
+braindead
 breakpoint
 Brenan
 broadcastable
@@ -97,11 +102,10 @@
 CallbackObject
 callee's
 camd
+CancelString
 cauchy
 caxis
 ccolamd
-CCR
-CCS
 cd
 cdata
 CDF
@@ -116,6 +120,7 @@
 changesets
 Chaves
 chdir
+Chebyshev
 chisq
 chisquare
 chol
@@ -129,6 +134,7 @@
 classpath
 classpaths
 Clenshaw
+CLI
 clim
 cloglog
 clubsuit
@@ -136,6 +142,7 @@
 cmd
 cmember
 cntrl
+codebases
 cof
 coffset
 colamd
@@ -176,6 +183,7 @@
 cumprod
 cumsum
 cURL
+CurrentObject
 Cuthill
 cxsparse
 Cygwin
@@ -192,7 +200,6 @@
 davis
 ddd
 dddd
-dddddddddd
 deallocate
 deallocated
 deconv
@@ -206,18 +213,18 @@
 demi
 Demmel
 DeskJet
-Deskjet
 det
 diag
 diamondsuit
 dir
 disp
+DisplayName
+DisplayNames
 displayrange
 dMatrix
 dmperm
-DMS
-Dn
 Dobkin
+docstrings
 dOmega
 dotall
 dotexceptnewline
@@ -260,6 +267,7 @@
 equispaced
 erf
 erfc
+erfi
 errno
 Errorbar
 errorbar
@@ -290,7 +298,7 @@
 fftpack
 FFTs
 fftw
-FG
+Fiedler
 fieldname
 fieldnames
 filename
@@ -309,6 +317,7 @@
 forall
 foregroundcolor
 formfeed
+Forsythe
 Fortran
 fpdf
 fprintf
@@ -337,7 +346,6 @@
 geoinv
 geopdf
 geornd
-GEP
 geq
 gesdd
 gesvd
@@ -394,6 +402,7 @@
 Hessenberg
 heteroscedascity
 hggroup
+hggroups
 hh
 HH
 Higham
@@ -417,13 +426,12 @@
 Hyndman
 Hypergeometric
 hypergeometric
+IEC
 IEEE
 ifelse
-iff
 ifft
 ifftn
 ignorecase
-IIP
 ij
 Im
 imag
@@ -433,6 +441,7 @@
 indices
 infty
 init
+InitialValue
 inline
 Inline
 inpolygon
@@ -446,6 +455,7 @@
 Interpolants
 interquartile
 inv
+involutory
 ipermute
 ishandle
 ishghandle
@@ -458,17 +468,19 @@
 iter
 ith
 iy
+iz
 Jacobian
 Jacobians
 javaaddpath
 javamem
-ji
 JIT
 jpeg
 JPEG
 jpg
 jvm
 JVM's
+Kac
+Kahan
 keybindings
 keypress
 Kolmogorov
@@ -487,6 +499,7 @@
 laplace
 Larimore
 LaserJet
+Lauchli
 lceil
 ldiv
 ldivide
@@ -496,6 +509,7 @@
 leftarrow
 Leftrightarrow
 leftrightarrow
+Lehmer
 Lehoucq
 leq
 Levinson
@@ -515,6 +529,8 @@
 linespoints
 linkprop
 listdlg
+ListSize
+ListString
 literalspacing
 Liu
 LLVM
@@ -532,6 +548,7 @@
 Lookup
 lookups
 Los
+Lotkin
 Lovato
 lpx
 lr
@@ -594,7 +611,6 @@
 mmmm
 mmmyy
 mmmyyyy
-modelled
 Moler
 Montanet
 mpoles
@@ -614,6 +630,8 @@
 myclass
 myfun
 nabla
+namespace
+NAMESPACE
 NaN
 NaNs
 nargin
@@ -638,11 +656,13 @@
 nnls
 nnz
 nocompute
+nodither
 nolabel
 noncommercially
 nonconformant
 nonsmooth
 nonzeros
+NOP
 noperm
 normcdf
 normest
@@ -655,13 +675,13 @@
 notin
 nthargout
 NTSC
-nul
+ntsc
 Numpy
-Nx
 nzmax
 oct
 octaverc
 ODEPACK
+OKString
 OLS
 onCleanup
 online
@@ -680,6 +700,7 @@
 papersize
 paperunits
 parseparams
+Parter
 pbm
 PBM
 PBMplus
@@ -693,6 +714,7 @@
 pcx
 pdf
 PDF
+pentadiagonal
 periodogram
 perp
 Petzold's
@@ -719,6 +741,7 @@
 postorder
 PostScript
 Pothen
+powerset
 pre
 preconditioner
 premultiplied
@@ -729,6 +752,8 @@
 priori
 Profiler
 profiler
+prolate
+PromptString
 propto
 proven
 ps
@@ -736,11 +761,10 @@
 pseudonorm
 pseudorandom
 Pseudospectra
+pseudospectrum
 ptrace
 punct
-PWS
 Pxx
-Qci
 Qhull
 qhull
 QP
@@ -773,10 +797,10 @@
 Readline
 readline
 recursing
+Redheffer
 reentrant
 regex
 regressor
-reimported
 Reindent
 relicensing
 ren
@@ -793,6 +817,7 @@
 RET
 returnonerror
 rfloor
+rgb
 RGB
 Riccati
 Rightarrow
@@ -806,13 +831,11 @@
 Rossum
 rpath
 RPMs
-rr
 runtime
 sa
 Saad
 Sandia
 SAS
-sB
 Schafer
 schar
 Schur
@@ -821,6 +844,7 @@
 se
 sed
 seealso
+SelectionMode
 semidefinite
 Sep
 Shampine
@@ -886,6 +910,7 @@
 strncmpi
 strread
 strread's
+strsplit
 struct
 structs
 subarrays
@@ -936,6 +961,7 @@
 symamd
 symbfact
 symrcm
+Szego
 tcdf
 Tcv
 terminal's
@@ -944,6 +970,7 @@
 Texinfo
 TextAlphaBits
 textfield
+textread
 textscan
 th
 ths
@@ -972,6 +999,7 @@
 triplot
 trnd
 Tsang
+Tukey
 tuples
 Tx
 txi
@@ -988,7 +1016,6 @@
 Ultrix
 umfpack
 uminus
-un
 Unary
 unary
 uncomment
@@ -1009,6 +1036,7 @@
 univariate
 unnormalized
 unpadded
+unpermuted
 unpivoted
 unregister
 unshare
@@ -1038,11 +1066,12 @@
 Villadsen
 voronoi
 Voronoi
-Wa
 waitbar
 waitbars
 wallis
 warndlg
+Wathen
+WAV
 wblcdf
 wblinv
 wblpdf
@@ -1066,7 +1095,6 @@
 windowstyle
 WinRand
 WIPO
-Wl
 wp
 wspace
 xb
@@ -1085,6 +1113,7 @@
 xPBTRF
 xPOTRF
 xPTSV
+xtest
 xTRTRS
 xu
 xwd
@@ -1104,7 +1133,6 @@
 yyyymmdd
 yyyymmddTHHMMSS
 Zechner
-zer
 Ziggurat
 zlib
 zlim

--- a/doc/interpreter/dynamic.txi	Fri May 24 15:41:52 2013 -0400
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,1726 +0,0 @@
-@c Copyright (C) 2007-2012 John W. Eaton and David Bateman
-@c Copyright (C) 2007 Paul Thomas and Christoph Spiel
-@c
-@c This file is part of Octave.
-@c
-@c Octave is free software; you can redistribute it and/or modify it
-@c under the terms of the GNU General Public License as published by the
-@c Free Software Foundation; either version 3 of the License, or (at
-@c your option) any later version.
-@c 
-@c Octave is distributed in the hope that it will be useful, but WITHOUT
-@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
-@c for more details.
-@c 
-@c You should have received a copy of the GNU General Public License
-@c along with Octave; see the file COPYING.  If not, see
-@c <http://www.gnu.org/licenses/>.
-
-@node Dynamically Linked Functions
-@appendix Dynamically Linked Functions
-@cindex dynamic-linking
-
-Octave has the possibility of including compiled code as dynamically
-linked extensions and then using these extensions as if they were part
-of Octave itself.  Octave can call C++ code
-through its native oct-file interface or C code through its mex
-interface.  It can also indirectly call functions written in any other
-language through a simple wrapper.  The reasons to write code in a
-compiled language might be either to link to an existing piece of code
-and allow it to be used within Octave, or to allow improved performance
-for key pieces of code.
-
-Before going further, you should first determine if you really need to
-use dynamically linked functions at all.  Before proceeding with writing
-any dynamically linked function to improve performance you should
-address ask yourself
-
-@itemize @bullet
-@item
-Can I get the same functionality using the Octave scripting language only?
-
-@item
-Is it thoroughly optimized Octave code?  Vectorization of Octave code,
-doesn't just make it concise, it generally significantly improves its
-performance.  Above all, if loops must be used, make sure that the
-allocation of space for variables takes place outside the loops using an
-assignment to a matrix of the right size, or zeros.
-
-@item
-Does it make as much use as possible of existing built-in library
-routines?  These are highly optimized and many do not carry the overhead
-of being interpreted.
-
-@item
-Does writing a dynamically linked function represent useful investment
-of your time, relative to staying in Octave?
-@end itemize
-
-Also, as oct- and mex-files are dynamically linked to Octave, they
-introduce the possibility of Octave crashing due to errors in
-the user code.  For example a segmentation violation in the user's code
-will cause Octave to abort.
-
-@menu
-* Oct-Files::                   
-* Mex-Files::                   
-* Standalone Programs::         
-@end menu
-
-@node Oct-Files
-@section Oct-Files
-@cindex oct-files
-@cindex mkoctfile
-@cindex oct
-
-@menu
-* Getting Started with Oct-Files::  
-* Matrices and Arrays in Oct-Files::  
-* Character Strings in Oct-Files::  
-* Cell Arrays in Oct-Files::    
-* Structures in Oct-Files::  
-* Sparse Matrices in Oct-Files::  
-* Accessing Global Variables in Oct-Files::  
-* Calling Octave Functions from Oct-Files::  
-* Calling External Code from Oct-Files::  
-* Allocating Local Memory in Oct-Files::  
-* Input Parameter Checking in Oct-Files::  
-* Exception and Error Handling in Oct-Files::  
-* Documentation and Test of Oct-Files::  
-@c * Application Programming Interface for Oct-Files::  
-@end menu
-
-@node Getting Started with Oct-Files
-@subsection Getting Started with Oct-Files
-
-The basic command to build oct-files is @code{mkoctfile} and it can be
-call from within octave or from the command line.
-
-@DOCSTRING(mkoctfile)
-
-Consider the short C++ example:
-
-@example
-@group
-@EXAMPLEFILE(helloworld.cc)
-@end group
-@end example
-
-This example although short introduces the basics of writing a C++
-function that can be dynamically linked to Octave.  The easiest way to
-make available most of the definitions that might be necessary for a C++
-oct-file in Octave is to use the @code{#include <octave/oct.h>} header.
-Note that @file{octave/oct.h} is a C++ header and cannot be directly
-@code{#include}'ed in a C source file, nor any other language.  What
-follows is mostly C++, with a discussion of other languages in section
-@ref{Calling External Code from Oct-Files}.
-
-The macro that defines the entry point into the dynamically loaded
-function is @w{@code{DEFUN_DLD}}.  This macro takes four arguments, these being
-
-@enumerate 1
-@item The function name as it will be seen in Octave,
-
-@item The list of arguments to the function of type @code{octave_value_list},
-
-@item The number of output arguments, which can and often is omitted if
-not used, and
-
-@item The string that will be seen as the help text of the function.
-@end enumerate
-
-The return type of functions defined with @w{@code{DEFUN_DLD}} is always
-@code{octave_value_list}.
-
-There are a couple of important considerations in the choice of function
-name.  Firstly, it must be a valid Octave function name and so must be a
-sequence of letters, digits and underscores, not starting with a
-digit.  Secondly, as Octave uses the function name to define the filename
-it attempts to find the function in, the function name in the
-@w{@code{DEFUN_DLD}} macro must match the filename of the oct-file.  Therefore,
-the above function should be in a file @file{helloworld.cc}, and it should be
-compiled to an oct-file using the command
-
-@example
-mkoctfile helloworld.cc
-@end example
-
-This will create a file called @file{helloworld.oct}, that is the compiled
-version of the function.  It should be noted that it is perfectly
-acceptable to have more than one @w{@code{DEFUN_DLD}} function in a source
-file.  However, there must either be a symbolic link to the oct-file for
-each of the functions defined in the source code with the @w{@code{DEFUN_DLD}}
-macro or the autoload (@ref{Function Files}) function should be used.
-
-The rest of this function then shows how to find the number of input
-arguments, how to print through the octave pager, and return from the
-function.  After compiling this function as above, an example of its use
-is
-
-@example
-@group
-helloworld (1, 2, 3)
-@print{} Hello World has 3 input arguments and 0 output arguments.
-@end group
-@end example
-
-@node Matrices and Arrays in Oct-Files
-@subsection Matrices and Arrays in Oct-Files
-
-Octave supports a number of different array and matrix classes, the
-majority of which are based on the Array class.  The exception is the
-sparse matrix types discussed separately below.  There are three basic
-matrix types
-
-@table @code
-@item Matrix
-A double precision matrix class defined in dMatrix.h,
-
-@item ComplexMatrix
-A complex matrix class defined in CMatrix.h, and
-
-@item BoolMatrix
-A boolean matrix class defined in boolMatrix.h.
-@end table
-
-These are the basic two-dimensional matrix types of octave.  In
-additional there are a number of multi-dimensional array types, these
-being
-
-@table @code
-@item NDArray
-A double precision array class defined in @file{dNDArray.h}
-
-@item ComplexNDarray
-A complex array class defined in @file{CNDArray.h}
-
-@item boolNDArray
-A boolean array class defined in @file{boolNDArray.h}
-
-@item int8NDArray
-@itemx int16NDArray
-@itemx int32NDArray
-@itemx int64NDArray
-8, 16, 32 and 64-bit signed array classes defined in
-@file{int8NDArray.h}, @file{int16NDArray.h}, etc.
-
-@item uint8NDArray
-@itemx uint16NDArray
-@itemx uint32NDArray
-@itemx uint64NDArray
-8, 16, 32 and 64-bit unsigned array classes defined in
-@file{uint8NDArray.h}, @file{uint16NDArray.h}, etc.
-@end table
-
-There are several basic means of constructing matrices of
-multi-dimensional arrays.  Considering the @code{Matrix} type as an
-example
-
-@itemize @bullet
-@item
-We can create an empty matrix or array with the empty constructor.  For
-example
-
-@example
-Matrix a;
-@end example
-
-This can be used on all matrix and array types
-
-@item
-Define the dimensions of the matrix or array with a dim_vector.  For
-example
-
-@example
-@group
-dim_vector dv (2);
-dv(0) = 2; dv(1) = 2;
-Matrix a (dv);
-@end group
-@end example
-
-This can be used on all matrix and array types
-
-@item
-Define the number of rows and columns in the matrix.  For example:
-
-@example
-Matrix a (2, 2)
-@end example
-
-However, this constructor can only be used with the matrix types.
-@end itemize
-
-These types all share a number of basic methods and operators, a
-selection of which include
-
-@deftypefn  Method T& {operator ()} (octave_idx_type)
-@deftypefnx Method T& elem (octave_idx_type)
-The @code{()} operator or @code{elem} method allow the values of the
-matrix or array to be read or set.  These can take a single argument,
-which is of type @code{octave_idx_type}, that is the index into the matrix or
-array.  Additionally, the matrix type allows two argument versions of the
-@code{()} operator and elem method, giving the row and column index of the
-value to obtain or set.
-@end deftypefn
-
-Note that these functions do significant error checking and so in some
-circumstances the user might prefer to access the data of the array or
-matrix directly through the @nospell{fortran_vec} method discussed below.
-
-@deftypefn Method octave_idx_type nelem (void) const
-The total number of elements in the matrix or array.
-@end deftypefn
-
-@deftypefn Method size_t byte_size (void) const
-The number of bytes used to store the matrix or array.
-@end deftypefn
-
-@deftypefn Method dim_vector dims (void) const
-The dimensions of the matrix or array in value of type dim_vector.
-@end deftypefn
-
-@deftypefn Method void resize (const dim_vector&)
-A method taking either an argument of type @code{dim_vector}, or in the
-case of a matrix two arguments of type @code{octave_idx_type} defining
-the number of rows and columns in the matrix.
-@end deftypefn
-
-@deftypefn Method T* fortran_vec (void)
-This method returns a pointer to the underlying data of the matrix or a
-array so that it can be manipulated directly, either within Octave or by
-an external library.
-@end deftypefn
-
-Operators such an @code{+}, @code{-}, or @code{*} can be used on the
-majority of the above types.  In addition there are a number of methods
-that are of interest only for matrices such as @code{transpose},
-@code{hermitian}, @code{solve}, etc.
-
-The typical way to extract a matrix or array from the input arguments of
-@w{@code{DEFUN_DLD}} function is as follows
-
-@example
-@group
-@EXAMPLEFILE(addtwomatrices.cc)
-@end group
-@end example
-
-To avoid segmentation faults causing Octave to abort, this function
-explicitly checks that there are sufficient arguments available before
-accessing these arguments.  It then obtains two multi-dimensional arrays
-of type @code{NDArray} and adds these together.  Note that the array_value
-method is called without using the @code{is_matrix_type} type, and instead the
-error_state is checked before returning @code{A + B}.  The reason to
-prefer this is that the arguments might be a type that is not an
-@code{NDArray}, but it would make sense to convert it to one.  The
-@code{array_value} method allows this conversion to be performed
-transparently if possible, and sets @code{error_state} if it is not.
-
-@code{A + B}, operating on two @code{NDArray}'s returns an
-@code{NDArray}, which is cast to an @code{octave_value} on the return
-from the function.  An example of the use of this demonstration function
-is
-
-@example
-@group
-addtwomatrices (ones (2, 2), ones (2, 2))
-      @result{}  2  2
-          2  2
-@end group
-@end example
-
-A list of the basic @code{Matrix} and @code{Array} types, the methods to
-extract these from an @code{octave_value} and the associated header is
-listed below.
-
-@multitable @columnfractions .3 .4 .3
-@item @code{RowVector} @tab @code{row_vector_value} @tab @file{dRowVector.h}
-@item @code{ComplexRowVector} @tab @code{complex_row_vector_value} @tab @file{CRowVector.h}
-@item @code{ColumnVector} @tab @code{column_vector_value} @tab @file{dColVector.h}
-@item @code{ComplexColumnVector} @tab @code{complex_column_vector_value} @tab @file{CColVector.h}
-@item @code{Matrix} @tab @code{matrix_value} @tab @file{dMatrix.h}
-@item @code{ComplexMatrix} @tab @code{complex_matrix_value} @tab @file{CMatrix.h}
-@item @code{boolMatrix} @tab @code{bool_matrix_value} @tab @file{boolMatrix.h}
-@item @code{charMatrix} @tab @code{char_matrix_value} @tab @file{chMatrix.h}
-@item @code{NDArray} @tab @code{array_value} @tab @file{dNDArray.h}
-@item @code{ComplexNDArray} @tab @code{complex_array_value} @tab @file{CNDArray.h}
-@item @code{boolNDArray} @tab @code{bool_array_value} @tab @file{boolNDArray.h}
-@item @code{charNDArray} @tab @code{char_array_value} @tab @file{charNDArray.h}
-@item @code{int8NDArray} @tab @code{int8_array_value} @tab @file{int8NDArray.h}
-@item @code{int16NDArray} @tab @code{int16_array_value} @tab @file{int16NDArray.h}
-@item @code{int32NDArray} @tab @code{int32_array_value} @tab @file{int32NDArray.h}
-@item @code{int64NDArray} @tab @code{int64_array_value} @tab @file{int64NDArray.h}
-@item @code{uint8NDArray} @tab @code{uint8_array_value} @tab @file{uint8NDArray.h}
-@item @code{uint16NDArray} @tab @code{uint16_array_value} @tab @file{uint16NDArray.h}
-@item @code{uint32NDArray} @tab @code{uint32_array_value} @tab @file{uint32NDArray.h}
-@item @code{uint64NDArray} @tab @code{uint64_array_value} @tab @file{uint64NDArray.h}
-@end multitable
-
-@node Character Strings in Oct-Files
-@subsection Character Strings in Oct-Files
-
-In Octave a character string is just a special @code{Array} class.
-Consider the example:
-
-@example
-@EXAMPLEFILE(stringdemo.cc)
-@end example
-
-An example of the use of this function is
-
-@example
-@group
-s0 = ["First String"; "Second String"];
-[s1,s2] = stringdemo (s0)
-@result{} s1 = Second String
-        First String
-
-@result{} s2 = First String
-        Second String
-
-typeinfo (s2)
-@result{} sq_string
-typeinfo (s1)
-@result{} string
-@end group
-@end example
-
-One additional complication of strings in Octave is the difference
-between single quoted and double quoted strings.  To find out if an
-@code{octave_value} contains a single or double quoted string an example is
-
-@example
-@group
-    if (args(0).is_sq_string ())
-      octave_stdout << 
-        "First argument is a singularly quoted string\n";
-    else if (args(0).is_dq_string ())
-      octave_stdout << 
-        "First argument is a doubly quoted string\n";
-@end group
-@end example
-
-Note however, that both types of strings are represented by the
-@code{charNDArray} type, and so when assigning to an
-@code{octave_value}, the type of string should be specified.  For example:
-
-@example
-@group
-octave_value_list retval;
-charNDArray c;
-@dots{}
-// Create single quoted string
-retval(1) = octave_value (ch, true, '\'');
-
-// Create a double quoted string
-retval(0) = octave_value (ch, true);
-@end group
-@end example
-
-@node Cell Arrays in Oct-Files
-@subsection Cell Arrays in Oct-Files
-
-Octave's cell type is equally accessible within oct-files.  A cell
-array is just an array of @code{octave_value}s, and so each element of the cell
-array can then be treated just like any other @code{octave_value}.  A simple
-example is
-
-@example
-@group
-@EXAMPLEFILE(celldemo.cc)
-@end group
-@end example
-
-Note that cell arrays are used less often in standard oct-files and so
-the @file{Cell.h} header file must be explicitly included.  The rest of this
-example extracts the @code{octave_value}s one by one from the cell array and
-returns be as individual return arguments.  For example consider
-
-@example
-@group
-[b1, b2, b3] = celldemo (@{1, [1, 2], "test"@})
-@result{}
-b1 =  1
-b2 =
-
-   1   2
-
-b3 = test
-@end group
-@end example
-
-@node Structures in Oct-Files
-@subsection Structures in Oct-Files
-
-A structure in Octave is map between a number of fields represented and
-their values.  The Standard Template Library @code{map} class is used,
-with the pair consisting of a @code{std::string} and an octave
-@code{Cell} variable.
-
-A simple example demonstrating the use of structures within oct-files is
-
-@example
-@EXAMPLEFILE(structdemo.cc)
-@end example
-
-An example of its use is
-
-@example
-@group
-x.a = 1; x.b = "test"; x.c = [1, 2];
-structdemo (x, "b")
-@result{} selected = test
-@end group
-@end example
-
-The commented code above demonstrates how to iterate over all of the
-fields of the structure, where as the following code demonstrates finding
-a particular field in a more concise manner.
-
-As can be seen the @code{contents} method of the @code{Octave_map} class
-returns a @code{Cell} which allows structure arrays to be represented.
-Therefore, to obtain the underlying @code{octave_value} we write
-
-@example
-octave_value tmp = arg0.contents (p1) (0);
-@end example
-
-@noindent
-where the trailing (0) is the () operator on the @code{Cell} object.  We
-can equally iterate of the elements of the Cell array to address the
-elements of the structure array.
-
-@node Sparse Matrices in Oct-Files
-@subsection Sparse Matrices in Oct-Files
-
-There are three classes of sparse objects that are of interest to the
-user.
-
-@table @code
-@item SparseMatrix
-A double precision sparse matrix class
-
-@item SparseComplexMatrix
-A complex sparse matrix class
-
-@item SparseBoolMatrix
-A boolean sparse matrix class
-@end table
-
-All of these classes inherit from the @code{Sparse<T>} template class,
-and so all have similar capabilities and usage.  The @code{Sparse<T>}
-class was based on Octave @code{Array<T>} class, and so users familiar
-with Octave's @code{Array} classes will be comfortable with the use of
-the sparse classes.
-
-The sparse classes will not be entirely described in this section, due
-to their similarity with the existing @code{Array} classes.  However,
-there are a few differences due the different nature of sparse objects,
-and these will be described.  Firstly, although it is fundamentally
-possible to have N-dimensional sparse objects, the Octave sparse classes do
-not allow them at this time.  So all operations of the sparse classes
-must be 2-dimensional.  This means that in fact @code{SparseMatrix} is
-similar to Octave's @code{Matrix} class rather than its
-@code{NDArray} class.
-
-@menu
-* Array and Sparse Differences::  
-* Creating Sparse Matrices in Oct-Files::  
-* Using Sparse Matrices in Oct-Files::  
-@end menu
-
-@node Array and Sparse Differences
-@subsubsection The Differences between the Array and Sparse Classes
-
-The number of elements in a sparse matrix is considered to be the number
-of non-zero elements rather than the product of the dimensions.  Therefore
-
-@example
-@group
-SparseMatrix sm;
-@dots{}
-int nel = sm.nelem ();
-@end group
-@end example
-
-@noindent
-returns the number of non-zero elements.  If the user really requires the
-number of elements in the matrix, including the non-zero elements, they
-should use @code{numel} rather than @code{nelem}.  Note that for very
-large matrices, where the product of the two dimensions is larger than
-the representation of an unsigned int, then @code{numel} can overflow.
-An example is @code{speye (1e6)} which will create a matrix with a million
-rows and columns, but only a million non-zero elements.  Therefore the
-number of rows by the number of columns in this case is more than two
-hundred times the maximum value that can be represented by an unsigned int.
-The use of @code{numel} should therefore be avoided useless it is known
-it won't overflow.
-
-Extreme care must be take with the elem method and the "()" operator,
-which perform basically the same function.  The reason is that if a
-sparse object is non-const, then Octave will assume that a
-request for a zero element in a sparse matrix is in fact a request
-to create this element so it can be filled.  Therefore a piece of
-code like
-
-@example
-@group
-SparseMatrix sm;
-@dots{}
-for (int j = 0; j < nc; j++)
-  for (int i = 0; i < nr; i++)
-    std::cerr << " (" << i << "," << j << "): " << sm(i,j)
-              << std::endl;
-@end group
-@end example
-
-@noindent
-is a great way of turning the sparse matrix into a dense one, and a
-very slow way at that since it reallocates the sparse object at each
-zero element in the matrix.
-
-An easy way of preventing the above from happening is to create a temporary
-constant version of the sparse matrix.  Note that only the container for
-the sparse matrix will be copied, while the actual representation of the
-data will be shared between the two versions of the sparse matrix.  So this
-is not a costly operation.  For example, the above would become
-
-@example
-@group
-SparseMatrix sm;
-@dots{}
-const SparseMatrix tmp (sm);
-for (int j = 0; j < nc; j++)
-  for (int i = 0; i < nr; i++)
-    std::cerr << " (" << i << "," << j << "): " << tmp(i,j)
-              << std::endl;
-@end group
-@end example
-
-Finally, as the sparse types aren't just represented as a contiguous
-block of memory, the @nospell{@code{fortran_vec}} method of the @code{Array<T>}
-is not available.  It is however replaced by three separate methods
-@code{ridx}, @code{cidx} and @code{data}, that access the raw compressed
-column format that the Octave sparse matrices are stored in.
-Additionally, these methods can be used in a manner similar to @code{elem},
-to allow the matrix to be accessed or filled.  However, in that case it is
-up to the user to respect the sparse matrix compressed column format
-discussed previous.
-
-@node Creating Sparse Matrices in Oct-Files
-@subsubsection Creating Sparse Matrices in Oct-Files
-
-You have several alternatives for creating a sparse matrix.
-You can first create the data as three vectors representing the
-row and column indexes and the data, and from those create the matrix.
-Or alternatively, you can create a sparse matrix with the appropriate
-amount of space and then fill in the values.  Both techniques have their
-advantages and disadvantages.
-
-Here is an example of how to create a small sparse matrix with the first
-technique
-
-@example
-@group
-int nz = 4, nr = 3, nc = 4;
-
-ColumnVector ridx (nz);
-ColumnVector cidx (nz);
-ColumnVector data (nz);
-
-ridx(0) = 0; ridx(1) = 0; ridx(2) = 1; ridx(3) = 2;
-cidx(0) = 0; cidx(1) = 1; cidx(2) = 3; cidx(3) = 3;
-data(0) = 1; data(1) = 2; data(2) = 3; data(3) = 4;
-
-SparseMatrix sm (data, ridx, cidx, nr, nc);
-@end group
-@end example
-
-@noindent
-which creates the matrix given in section
-@ref{Storage of Sparse Matrices}.  Note that the compressed matrix
-format is not used at the time of the creation of the matrix itself,
-however it is used internally.
-
-As previously mentioned, the values of the sparse matrix are stored
-in increasing column-major ordering.  Although the data passed by the
-user does not need to respect this requirement, the pre-sorting the
-data significantly speeds up the creation of the sparse matrix.
-
-The disadvantage of this technique of creating a sparse matrix is
-that there is a brief time where two copies of the data exists.  Therefore
-for extremely memory constrained problems this might not be the right
-technique to create the sparse matrix.
-
-The alternative is to first create the sparse matrix with the desired
-number of non-zero elements and then later fill those elements in.  The
-easiest way to do this is
-
-@example
-@group
-int nz = 4, nr = 3, nc = 4;
-SparseMatrix sm (nr, nc, nz);
-sm(0,0) = 1; sm(0,1) = 2; sm(1,3) = 3; sm(2,3) = 4;
-@end group
-@end example
-
-That creates the same matrix as previously.  Again, although it is not
-strictly necessary, it is significantly faster if the sparse matrix is
-created in this manner that the elements are added in column-major
-ordering.  The reason for this is that if the elements are inserted
-at the end of the current list of known elements then no element
-in the matrix needs to be moved to allow the new element to be
-inserted.  Only the column indexes need to be updated.
-
-There are a few further points to note about this technique of creating
-a sparse matrix.  Firstly, it is possible to create a sparse matrix
-with fewer elements than are actually inserted in the matrix.  Therefore
-
-@example
-@group
-int nz = 4, nr = 3, nc = 4;
-SparseMatrix sm (nr, nc, 0);
-sm(0,0) = 1; sm(0,1) = 2; sm(1,3) = 3; sm(2,3) = 4;
-@end group
-@end example
-
-@noindent 
-is perfectly valid.  However it is a very bad idea.  The reason is that
-as each new element is added to the sparse matrix the space allocated
-to it is increased by reallocating the memory.  This is an expensive
-operation, that will significantly slow this means of creating a sparse
-matrix.  Furthermore, it is possible to create a sparse matrix with
-too much storage, so having @var{nz} above equaling 6 is also valid.
-The disadvantage is that the matrix occupies more memory than strictly
-needed.
-
-It is not always easy to know the number of non-zero elements prior
-to filling a matrix.  For this reason the additional storage for the
-sparse matrix can be removed after its creation with the
-@dfn{maybe_compress} function.  Furthermore, the maybe_compress can
-deallocate the unused storage, but it can equally remove zero elements
-from the matrix.  The removal of zero elements from the matrix is
-controlled by setting the argument of the @dfn{maybe_compress} function
-to be @samp{true}.  However, the cost of removing the zeros is high because it
-implies resorting the elements.  Therefore, if possible it is better
-is the user doesn't add the zeros in the first place.  An example of
-the use of @dfn{maybe_compress} is
-
-@example
-@group
-  int nz = 6, nr = 3, nc = 4;
-
-  SparseMatrix sm1 (nr, nc, nz);
-  sm1(0,0) = 1; sm1(0,1) = 2; sm1(1,3) = 3; sm1(2,3) = 4;
-  sm1.maybe_compress ();  // No zero elements were added
-
-  SparseMatrix sm2 (nr, nc, nz);
-  sm2(0,0) = 1; sm2(0,1) = 2; sm(0,2) = 0; sm(1,2) = 0;
-  sm1(1,3) = 3; sm1(2,3) = 4;
-  sm2.maybe_compress (true);  // Zero elements were added
-@end group
-@end example
-
-The use of the @dfn{maybe_compress} function should be avoided if
-possible, as it will slow the creation of the matrices.
-
-A third means of creating a sparse matrix is to work directly with
-the data in compressed row format.  An example of this technique might
-be
-
-@c Note the @verbatim environment is a relatively new addition to Texinfo.
-@c Therefore use the @example environment and replace @, with @@,
-@c { with @{, etc
-
-@example
-octave_value arg;
-@dots{}
-int nz = 6, nr = 3, nc = 4;   // Assume we know the max no nz
-SparseMatrix sm (nr, nc, nz);
-Matrix m = arg.matrix_value ();
-
-int ii = 0;
-sm.cidx (0) = 0;
-for (int j = 1; j < nc; j++)
-  @{
-    for (int i = 0; i < nr; i++)
-      @{
-        double tmp = foo (m(i,j));
-        if (tmp != 0.)
-          @{
-            sm.data(ii) = tmp;
-            sm.ridx(ii) = i;
-            ii++;
-          @}
-      @}
-    sm.cidx(j+1) = ii;
- @}
-sm.maybe_compress ();  // If don't know a-priori 
-                       // the final no of nz.
-@end example
-
-@noindent
-which is probably the most efficient means of creating the sparse matrix.
-
-Finally, it might sometimes arise that the amount of storage initially
-created is insufficient to completely store the sparse matrix.  Therefore,
-the method @code{change_capacity} exists to reallocate the sparse memory.
-The above example would then be modified as
-
-@example
-octave_value arg;
-@dots{}
-int nz = 6, nr = 3, nc = 4;   // Assume we know the max no nz
-SparseMatrix sm (nr, nc, nz);
-Matrix m = arg.matrix_value ();
-
-int ii = 0;
-sm.cidx (0) = 0;
-for (int j = 1; j < nc; j++)
-  @{
-    for (int i = 0; i < nr; i++)
-      @{
-        double tmp = foo (m(i,j));
-        if (tmp != 0.)
-          @{
-            if (ii == nz)
-              @{
-                nz += 2;   // Add 2 more elements
-                sm.change_capacity (nz);
-              @}
-            sm.data(ii) = tmp;
-            sm.ridx(ii) = i;
-            ii++;
-          @}
-      @}
-    sm.cidx(j+1) = ii;
- @}
-sm.maybe_mutate ();  // If don't know a-priori 
-                     // the final no of nz.
-@end example
-
-Note that both increasing and decreasing the number of non-zero elements in
-a sparse matrix is expensive, as it involves memory reallocation.  Also as
-parts of the matrix, though not its entirety, exist as the old and new copy
-at the same time, additional memory is needed.  Therefore if possible this
-should be avoided.
-
-@node Using Sparse Matrices in Oct-Files
-@subsubsection Using Sparse Matrices in Oct-Files
-
-Most of the same operators and functions on sparse matrices that are
-available from the Octave are equally available with oct-files.
-The basic means of extracting a sparse matrix from an @code{octave_value}
-and returning them as an @code{octave_value}, can be seen in the
-following example.
-
-@example
-@group
-octave_value_list retval;
-
-SparseMatrix sm = args(0).sparse_matrix_value ();
-SparseComplexMatrix scm = 
-    args(1).sparse_complex_matrix_value ();
-SparseBoolMatrix sbm = args(2).sparse_bool_matrix_value ();
-@dots{}
-retval(2) = sbm;
-retval(1) = scm;
-retval(0) = sm;
-@end group
-@end example
-
-The conversion to an octave-value is handled by the sparse
-@code{octave_value} constructors, and so no special care is needed.
-
-@node Accessing Global Variables in Oct-Files
-@subsection Accessing Global Variables in Oct-Files
-
-Global variables allow variables in the global scope to be
-accessed.  Global variables can easily be accessed with oct-files using
-the support functions @code{get_global_value} and
-@code{set_global_value}.  @code{get_global_value} takes two arguments,
-the first is a string representing the variable name to obtain.  The
-second argument is a boolean argument specifying what to do in the case
-that no global variable of the desired name is found.  An example of the
-use of these two functions is
-
-@example
-@EXAMPLEFILE(globaldemo.cc)
-@end example
-
-An example of its use is
-
-@example
-@group
-global a b
-b = 10;
-globaldemo ("b")
-@result{} 10
-globaldemo ("c")
-@result{} "Global variable not found"
-num2str (a)
-@result{} 42
-@end group
-@end example
-
-@node Calling Octave Functions from Oct-Files
-@subsection Calling Octave Functions from Oct-Files
-
-There is often a need to be able to call another octave function from
-within an oct-file, and there are many examples of such within octave
-itself.  For example the @code{quad} function is an oct-file that
-calculates the definite integral by quadrature over a user supplied
-function.
-
-There are also many ways in which a function might be passed.  It might
-be passed as one of
-
-@enumerate 1
-@item Function Handle
-
-@item Anonymous Function Handle
-
-@item Inline Function
-
-@item String
-@end enumerate
-
-The example below demonstrates an example that accepts all four means of
-passing a function to an oct-file.
-
-@example
-@EXAMPLEFILE(funcdemo.cc)
-@end example
-
-The first argument to this demonstration is the user supplied function
-and the following arguments are all passed to the user function.
-
-@example
-@group
-funcdemo (@@sin,1)
-@result{} 0.84147
-funcdemo (@@(x) sin (x), 1)
-@result{} 0.84147
-funcdemo (inline ("sin (x)"), 1)
-@result{} 0.84147
-funcdemo ("sin",1)
-@result{} 0.84147
-funcdemo (@@atan2, 1, 1)
-@result{} 0.78540
-@end group
-@end example
-
-When the user function is passed as a string, the treatment of the
-function is different.  In some cases it is necessary to always have the
-user supplied function as an @code{octave_function} object.  In that
-case the string argument can be used to create a temporary function like
-
-@example
-@group
-std::octave fcn_name = unique_symbol_name ("__fcn__");
-std::string fname = "function y = ";
-fname.append (fcn_name);
-fname.append ("(x) y = ");
-fcn = extract_function (args(0), "funcdemo", fcn_name,
-                        fname, "; endfunction");
-@dots{}
-if (fcn_name.length ())
-  clear_function (fcn_name);
-@end group
-@end example
-
-There are two important things to know in this case.  The number of input
-arguments to the user function is fixed, and in the above is a single
-argument, and secondly to avoid leaving the temporary function in the
-Octave symbol table it should be cleared after use.
-
-@node Calling External Code from Oct-Files
-@subsection Calling External Code from Oct-Files
-
-Linking external C code to Octave is relatively simple, as the C
-functions can easily be called directly from C++.  One possible issue is
-the declarations of the external C functions might need to be explicitly
-defined as C functions to the compiler.  If the declarations of the
-external C functions are in the header @code{foo.h}, then the manner in
-which to ensure that the C++ compiler treats these declarations as C
-code is
-
-@example
-@group
-#ifdef __cplusplus
-extern "C"
-@{
-#endif
-#include "foo.h"
-#ifdef __cplusplus
-@}  /* end extern "C" */
-#endif
-@end group
-@end example
-
-Calling Fortran code however can pose some difficulties.  This is due to
-differences in the manner in compilers treat the linking of Fortran code
-with C or C++ code.  Octave supplies a number of macros that allow
-consistent behavior across a number of compilers.
-
-The underlying Fortran code should use the @code{XSTOPX} function to
-replace the Fortran @code{STOP} function.  @code{XSTOPX} uses the Octave
-exception handler to treat failing cases in the Fortran code
-explicitly.  Note that Octave supplies its own replacement @sc{blas}
-@code{XERBLA} function, which uses @code{XSTOPX}.
-
-If the underlying code calls @code{XSTOPX}, then the @w{@code{F77_XFCN}}
-macro should be used to call the underlying Fortran function.  The Fortran
-exception state can then be checked with the global variable
-@code{f77_exception_encountered}.  If @code{XSTOPX} will not be called,
-then the @w{@code{F77_FCN}} macro should be used instead to call the Fortran
-code.
-
-There is no harm in using @w{@code{F77_XFCN}} in all cases, except that for
-Fortran code that is short running and executes a large number of times,
-there is potentially an overhead in doing so.  However, if @w{@code{F77_FCN}}
-is used with code that calls @code{XSTOP}, Octave can generate a
-segmentation fault.
-
-An example of the inclusion of a Fortran function in an oct-file is
-given in the following example, where the C++ wrapper is
-
-@example
-@EXAMPLEFILE(fortdemo.cc)
-@end example
-
-@noindent
-and the Fortran function is
-
-@example
-@EXAMPLEFILE(fortsub.f)
-@end example
-
-This example demonstrates most of the features needed to link to an
-external Fortran function, including passing arrays and strings, as well
-as exception handling.  An example of the behavior of this function is
-
-@example
-@group
-[b, s] = fortdemo (1:3)
-@result{}
-  b = 1.00000   0.50000   0.33333
-  s = There are   3 values in the input vector
-[b, s] = fortdemo (0:3)
-error: fortsub:divide by zero
-error: exception encountered in Fortran subroutine fortsub_
-error: fortdemo: error in Fortran
-@end group
-@end example
-
-@node Allocating Local Memory in Oct-Files
-@subsection Allocating Local Memory in Oct-Files
-
-Allocating memory within an oct-file might seem easy as the C++
-new/delete operators can be used.  However, in that case care must be
-taken to avoid memory leaks.  The preferred manner in which to allocate
-memory for use locally is to use the @w{@code{OCTAVE_LOCAL_BUFFER}} macro.
-An example of its use is
-
-@example
-OCTAVE_LOCAL_BUFFER (double, tmp, len)
-@end example
-
-@noindent
-that returns a pointer @code{tmp} of type @code{double *} of length
-@code{len}.
-
-@node Input Parameter Checking in Oct-Files
-@subsection Input Parameter Checking in Oct-Files
-
-As oct-files are compiled functions they have the possibility of causing
-Octave to abort abnormally.  It is therefore important that
-each and every function has the minimum of parameter
-checking needed to ensure that Octave behaves well.
-
-The minimum requirement, as previously discussed, is to check the number
-of input arguments before using them to avoid referencing a non existent
-argument.  However, it some case this might not be sufficient as the
-underlying code imposes further constraints.  For example an external
-function call might be undefined if the input arguments are not
-integers, or if one of the arguments is zero.  Therefore, oct-files often
-need additional input parameter checking.
-
-There are several functions within Octave that might be useful for the
-purposes of parameter checking.  These include the methods of the
-octave_value class like @code{is_real_matrix}, etc., but equally include
-more specialized functions.  Some of the more common ones are
-demonstrated in the following example.
-
-@example
-@EXAMPLEFILE(paramdemo.cc)
-@end example
-
-@noindent
-An example of its use is:
-
-@example
-@group
-paramdemo ([1, 2, NaN, Inf])
-@result{} Properties of input array:
-      includes Inf or NaN values
-      includes other values than 1 and 0
-      includes only int, Inf or NaN values
-@end group
-@end example
-
-@node Exception and Error Handling in Oct-Files
-@subsection Exception and Error Handling in Oct-Files
-
-Another important feature of Octave is its ability to react to the user
-typing @kbd{Control-C} even during calculations.  This ability is based on the
-C++ exception handler, where memory allocated by the C++ new/delete
-methods are automatically released when the exception is treated.  When
-writing an oct-file, to allow Octave to treat the user typing @kbd{Control-C},
-the @w{@code{OCTAVE_QUIT}} macro is supplied.  For example:
-
-@example
-@group
-for (octave_idx_type i = 0; i < a.nelem (); i++)
-  @{
-    OCTAVE_QUIT;
-    b.elem (i) = 2. * a.elem (i);
-  @}
-@end group
-@end example
-
-The presence of the @w{@code{OCTAVE_QUIT}} macro in the inner loop allows
-Octave to treat the user request with the @kbd{Control-C}.  Without this macro,
-the user must either wait for the function to return before the interrupt is
-processed, or press @kbd{Control-C} three times to force Octave to exit.
-
-The @w{@code{OCTAVE_QUIT}} macro does impose a very small speed penalty, and so
-for loops that are known to be small it might not make sense to include
-@w{@code{OCTAVE_QUIT}}.
-
-When creating an oct-file that uses an external libraries, the function
-might spend a significant portion of its time in the external
-library.  It is not generally possible to use the @w{@code{OCTAVE_QUIT}} macro
-in this case.  The alternative in this case is
-
-@example
-@group
-BEGIN_INTERRUPT_IMMEDIATELY_IN_FOREIGN_CODE;
-@dots{}  some code that calls a "foreign" function @dots{}
-END_INTERRUPT_IMMEDIATELY_IN_FOREIGN_CODE;
-@end group
-@end example
-
-The disadvantage of this is that if the foreign code allocates any
-memory internally, then this memory might be lost during an interrupt,
-without being deallocated.  Therefore, ideally Octave itself should
-allocate any memory that is needed by the foreign code, with either the
-@nospell{fortran_vec} method or the @w{@code{OCTAVE_LOCAL_BUFFER}} macro.
-
-The Octave unwind_protect mechanism (@ref{The unwind_protect Statement})
-can also be used in oct-files.  In conjunction with the exception
-handling of Octave, it is important to enforce that certain code is run
-to allow variables, etc. to be restored even if an exception occurs.  An
-example of the use of this mechanism is
-
-@example
-@EXAMPLEFILE(unwinddemo.cc)
-@end example
-
-As can be seen in the example:
-
-@example
-@group
-unwinddemo (1, 0)
-@result{} Inf
-1 / 0
-@result{} warning: division by zero
-   Inf
-@end group
-@end example
-
-The division by zero (and in fact all warnings) is disabled in the
-@code{unwinddemo} function.
-
-@node Documentation and Test of Oct-Files
-@subsection Documentation and Test of Oct-Files
-
-The documentation of an oct-file is the fourth string parameter of the
-@w{@code{DEFUN_DLD}} macro.  This string can be formatted in the same manner
-as the help strings for user functions (@ref{Documentation Tips}),
-however there are some issue that are particular to the formatting of
-help strings within oct-files.
-
-The major issue is that the help string will typically be longer than a
-single line of text, and so the formatting of long help strings need to
-be taken into account.  There are several manners in which to treat this
-issue, but the most common is illustrated in the following example,
-
-@example
-@group
-DEFUN_DLD (do_what_i_want, args, nargout, 
-  "-*- texinfo -*-\n\
-@@deftypefn @{Function File@} @{@} do_what_i_say (@@var@{n@})\n\
-A function that does what the user actually wants rather\n\
-than what they requested.\n\
-@@end deftypefn")
-@{
-@dots{}
-@}
-@end group
-@end example
-
-@noindent
-where, as can be seen, end line of text within the help string is
-terminated by @code{\n\} which is an embedded new-line in the string
-together with a C++ string continuation character.  Note that the final
-@code{\} must be the last character on the line.
-
-Octave also includes the ability to embed the test and demonstration
-code for a function within the code itself (@ref{Test and Demo Functions}).
-This can be used from within oct-files (or in fact any file) with
-certain provisos.  Firstly, the test and demo functions of Octave look
-for a @code{%!} as the first characters on a new-line to identify test
-and demonstration code.  This is equally a requirement for
-oct-files.  Furthermore the test and demonstration code must be included
-in a comment block of the compiled code to avoid it being interpreted by
-the compiler.  Finally, the Octave test and demonstration code must have
-access to the source code of the oct-file and not just the compiled code
-as the tests are stripped from the compiled code.  An example in an
-oct-file might be
-
-@example
-@group
-/*
-
-%!error (sin ())
-%!error (sin (1,1))
-%!assert (sin ([1,2]),[sin(1),sin(2)])
-
-*/
-@end group
-@end example
-
-@c @node Application Programming Interface for Oct-Files
-@c @subsection Application Programming Interface for Oct-Files
-@c 
-@c WRITE ME, using Coda section 1.3 as a starting point.
-
-@node Mex-Files
-@section Mex-Files
-@cindex mex-files
-@cindex mex
-
-Octave includes an interface to allow legacy mex-files to be compiled
-and used with Octave.  This interface can also be used to share code
-between Octave and @sc{matlab} users.  However, as mex-files expose the
-@sc{matlab}'s internal API, and the internal structure of Octave is
-different, a mex-file can never have the same performance in Octave as
-the equivalent oct-file.  In particular to support the manner in which
-mex-files access the variables passed to mex functions, there are a
-significant number of additional copies of memory when calling or
-returning from a mex function.  For this reason, new code should be
-written using the oct-file interface discussed above if possible.
-
-@menu
-* Getting Started with Mex-Files::  
-* Working with Matrices and Arrays in Mex-Files::  
-* Character Strings in Mex-Files::  
-* Cell Arrays with Mex-Files::  
-* Structures with Mex-Files::  
-* Sparse Matrices with Mex-Files::  
-* Calling Other Functions in Mex-Files::  
-@c * Application Programming Interface for Mex-Files::  
-@end menu
-
-@node Getting Started with Mex-Files
-@subsection Getting Started with Mex-Files
-
-The basic command to build a mex-file is either @code{mkoctfile --mex}
-or @code{mex}.  The first can either be used from within Octave or from
-the command line.  However, to avoid issues with @sc{matlab}'s own @code{mex}
-command, the use of the command @code{mex} is limited to within Octave.
-
-@DOCSTRING(mex)
-
-@DOCSTRING(mexext)
-
-One important difference with the use of @code{mex} between @sc{matlab} and
-Octave is that the header file "matrix.h" is implicitly included through
-the inclusion of "mex.h".  This is to avoid a conflict with the Octave
-file "Matrix.h" with operating systems and compilers that don't
-distinguish between filenames in upper and lower case
-
-Consider the short example:
-
-@example
-@group
-@EXAMPLEFILE(firstmexdemo.c)
-@end group
-@end example
-
-This simple example demonstrates the basics of writing a mex-file.  The
-entry point into the mex-file is defined by @code{mexFunction}.  Note
-that the function name is not explicitly included in the
-@code{mexFunction} and so there can only be a single @code{mexFunction}
-entry point per-file.  Also the name of the function is determined by the
-name of the mex-file itself.  Therefore if the above function is in the
-file @file{firstmexdemo.c}, it can be compiled with
-
-@example
-mkoctfile --mex firstmexdemo.c
-@end example
-
-@noindent
-which creates a file @file{firstmexdemo.mex}.  The function can then be run
-from Octave as
-
-@example
-@group
-firstmexdemo ()
-@result{} 1.2346
-@end group
-@end example
-
-It should be noted that the mex-file contains no help string for the
-functions it contains.  To document mex-files, there should exist an
-m-file in the same directory as the mex-file itself.  Taking the above as
-an example, we would therefore have a file @file{firstmexdemo.m} that might
-contain the text
-
-@example
-%FIRSTMEXDEMO Simple test of the functionality of a mex-file.
-@end example
-
-In this case, the function that will be executed within Octave will be
-given by the mex-file, while the help string will come from the
-m-file.  This can also be useful to allow a sample implementation of the
-mex-file within the Octave language itself for testing purposes.
-
-Although we cannot have multiple entry points into a single mex-file,
-we can use the @code{mexFunctionName} function to determine what name
-the mex-file was called with.  This can be used to alter the behavior of
-the mex-file based on the function name.  For example if
-
-@example
-@group
-@EXAMPLEFILE(myfunc.c)
-@end group
-@end example
-
-@noindent
-is in file @file{myfunc.c}, and it is compiled with
-
-@example
-@group
-mkoctfile --mex myfunc.c
-ln -s myfunc.mex myfunc2.mex
-@end group
-@end example
-
-Then as can be seen by
-
-@example
-@group
-myfunc ()
-@result{} You called function: myfunc
-    This is the principal function
-myfunc2 ()
-@result{} You called function: myfunc2
-@end group
-@end example
-
-@noindent
-the behavior of the mex-file can be altered depending on the functions
-name.
-
-Allow the user should only include @code{mex.h} in their code, Octave
-declares additional functions, typedefs, etc., available to the user to
-write mex-files in the headers @code{mexproto.h} and @code{mxarray.h}.
-
-@node Working with Matrices and Arrays in Mex-Files
-@subsection Working with Matrices and Arrays in Mex-Files
-
-The basic mex type of all variables is @code{mxArray}.  All variables,
-such as matrices, cell arrays or structures are all stored in this basic
-type, and this type serves basically the same purpose as the
-octave_value class in oct-files.  That is it acts as a container for the
-more specialized types.
-
-The @code{mxArray} structure contains at a minimum, the variable it
-represents name, its dimensions, its type and whether the variable is
-real or complex.  It can however contain a number of additional fields
-depending on the type of the @code{mxArray}.  There are a number of
-functions to create @code{mxArray} structures, including
-@code{mxCreateCellArray}, @code{mxCreateSparse} and the generic
-@code{mxCreateNumericArray}.
-
-The basic functions to access the data contained in an array is
-@code{mxGetPr}.  As the mex interface assumes that the real and imaginary
-parts of a complex array are stored separately, there is an equivalent
-function @code{mxGetPi} that get the imaginary part.  Both of these
-functions are for use only with double precision matrices.  There also
-exists the generic function @code{mxGetData} and @code{mxGetImagData}
-that perform the same operation on all matrix types.  For example:
-
-@example
-@group
-mxArray *m;
-mwSize *dims;
-UINT32_T *pr;
-
-dims = (mwSize *) mxMalloc (2 * sizeof (mwSize));
-dims[0] = 2;
-dims[1] = 2;
-m = mxCreateNumericArray (2, dims, mxUINT32_CLASS, mxREAL);
-pr =  = (UINT32_T *) mxGetData (m);
-@end group
-@end example
-
-There are also the functions @code{mxSetPr}, etc., that perform the
-inverse, and set the data of an Array to use the block of memory pointed
-to by the argument of @code{mxSetPr}.
-
-Note the type @code{mwSize} used above, and @code{mwIndex} are defined
-as the native precision of the indexing in Octave on the platform on
-which the mex-file is built.  This allows both 32- and 64-bit platforms
-to support mex-files.  @code{mwSize} is used to define array dimension
-and maximum number or elements, while @code{mwIndex} is used to define
-indexing into arrays.
-
-An example that demonstration how to work with arbitrary real or complex
-double precision arrays is given by the file @file{mypow2.c} as given
-below.
-
-@example
-@EXAMPLEFILE(mypow2.c)
-@end example
-
-@noindent
-with an example of its use
-
-@example
-@group
-b = randn (4,1) + 1i * randn (4,1);
-all (b.^2 == mypow2 (b))
-@result{} 1
-@end group
-@end example
-
-
-The example above uses the functions @code{mxGetDimensions},
-@code{mxGetNumberOfElements}, and @code{mxGetNumberOfDimensions} to work
-with the dimensions of multi-dimensional arrays.  The functions
-@code{mxGetM}, and @code{mxGetN} are also available to find the number
-of rows and columns in a matrix.
-
-@node Character Strings in Mex-Files
-@subsection Character Strings in Mex-Files
-
-As mex-files do not make the distinction between single and double
-quoted strings within Octave, there is perhaps less complexity in the
-use of strings and character matrices in mex-files.  An example of their
-use, that parallels the demo in @file{stringdemo.cc}, is given in the
-file @file{mystring.c}, as seen below.
-
-@example
-@EXAMPLEFILE(mystring.c)
-@end example
-
-@noindent
-An example of its expected output is
-
-@example
-@group
-mystring (["First String"; "Second String"])
-@result{} s1 = Second String
-        First String
-@end group
-@end example
-
-Other functions in the mex interface for handling character strings are
-@code{mxCreateString}, @code{mxArrayToString}, and
-@code{mxCreateCharMatrixFromStrings}.  In a mex-file, a character string
-is considered to be a vector rather than a matrix.  This is perhaps an
-arbitrary distinction as the data in the mxArray for the matrix is
-consecutive in any case.
-
-@node Cell Arrays with Mex-Files
-@subsection Cell Arrays with Mex-Files
-
-We can perform exactly the same operations in Cell arrays in mex-files
-as we can in oct-files.  An example that reduplicates the functional of
-the @file{celldemo.cc} oct-file in a mex-file is given by
-@file{mycell.c} as below
-
-@example
-@group
-@EXAMPLEFILE(mycell.c)
-@end group
-@end example
-
-@noindent
-which as can be seen below has exactly the same behavior as the oct-file
-version.
-
-@example
-@group
-[b1, b2, b3] = mycell (@{1, [1, 2], "test"@})
-@result{}
-b1 =  1
-b2 =
-
-   1   2
-
-b3 = test
-@end group
-@end example
-
-Note in the example the use of the @code{mxDuplicateArray} function.  This
-is needed as the @code{mxArray} pointer returned by @code{mxGetCell}
-might be deallocated.  The inverse function to @code{mxGetCell} is
-@code{mcSetCell} and is defined as
-
-@example
-void mxSetCell (mxArray *ptr, int idx, mxArray *val);
-@end example
-
-Finally, to create a cell array or matrix, the appropriate functions are
-
-@example
-@group
-mxArray *mxCreateCellArray (int ndims, const int *dims);
-mxArray *mxCreateCellMatrix (int m, int n);
-@end group
-@end example
-
-@node Structures with Mex-Files
-@subsection Structures with Mex-Files
-
-The basic function to create a structure in a mex-file is
-@code{mxCreateStructMatrix}, which creates a structure array with a two
-dimensional matrix, or @code{mxCreateStructArray}.
-
-@example
-@group
-mxArray *mxCreateStructArray (int ndims, int *dims, 
-                              int num_keys, 
-                              const char **keys);
-mxArray *mxCreateStructMatrix (int rows, int cols, 
-                               int num_keys, 
-                               const char **keys);
-@end group
-@end example
-
-Accessing the fields of the structure can then be performed with the
-@code{mxGetField} and @code{mxSetField} or alternatively with the
-@code{mxGetFieldByNumber} and @code{mxSetFieldByNumber} functions.
-
-@example
-@group
-mxArray *mxGetField (const mxArray *ptr, mwIndex index,
-                     const char *key);
-mxArray *mxGetFieldByNumber (const mxArray *ptr, 
-                             mwIndex index, int key_num);
-void mxSetField (mxArray *ptr, mwIndex index, 
-                 const char *key, mxArray *val);
-void mxSetFieldByNumber (mxArray *ptr, mwIndex index, 
-                         int key_num, mxArray *val);
-@end group
-@end example
-
-A difference between the oct-file interface to structures and the
-mex-file version is that the functions to operate on structures in
-mex-files directly include an @code{index} over the elements of the
-arrays of elements per @code{field}.  Whereas the oct-file structure
-includes a Cell Array per field of the structure.
-
-An example that demonstrates the use of structures in mex-file can be
-found in the file @file{mystruct.c}, as seen below
-
-@example
-@EXAMPLEFILE(mystruct.c)
-@end example
-
-An example of the behavior of this function within Octave is then
-
-@example
-a(1).f1 = "f11"; a(1).f2 = "f12"; 
-a(2).f1 = "f21"; a(2).f2 = "f22";
-b = mystruct (a)
-@result{} field f1(0) = f11
-    field f1(1) = f21
-    field f2(0) = f12
-    field f2(1) = f22
-    b =
-    @{
-      this =
-    
-      (,
-        [1] = this1
-        [2] = this2
-        [3] = this3
-        [4] = this4
-      ,)
-    
-      that =
-    
-      (,
-        [1] = that1
-        [2] = that2
-        [3] = that3
-        [4] = that4
-      ,)
-    
-    @}
-@end example
-
-@node Sparse Matrices with Mex-Files
-@subsection Sparse Matrices with Mex-Files
-
-The Octave format for sparse matrices is identical to the mex format in
-that it is a compressed column sparse format.  Also in both, sparse
-matrices are required to be two-dimensional.  The only difference is that
-the real and imaginary parts of the matrix are stored separately.
-
-The mex-file interface, as well as using @code{mxGetM}, @code{mxGetN},
-@code{mxSetM}, @code{mxSetN}, @code{mxGetPr}, @code{mxGetPi},
-@code{mxSetPr} and @code{mxSetPi}, the mex-file interface supplies the
-functions
-
-@example
-@group
-mwIndex *mxGetIr (const mxArray *ptr);
-mwIndex *mxGetJc (const mxArray *ptr);
-mwSize mxGetNzmax (const mxArray *ptr);
-
-void mxSetIr (mxArray *ptr, mwIndex *ir);
-void mxSetJc (mxArray *ptr, mwIndex *jc);
-void mxSetNzmax (mxArray *ptr, mwSize nzmax);
-@end group
-@end example
-
-@noindent
-@code{mxGetNzmax} gets the maximum number of elements that can be stored
-in the sparse matrix.  This is not necessarily the number of non-zero
-elements in the sparse matrix.  @code{mxGetJc} returns an array with one
-additional value than the number of columns in the sparse matrix.  The
-difference between consecutive values of the array returned by
-@code{mxGetJc} define the number of non-zero elements in each column of
-the sparse matrix.  Therefore
-
-@example
-@group
-mwSize nz, n;
-mwIndex *Jc;
-mxArray *m;
-@dots{}
-n = mxGetN (m);
-Jc = mxGetJc (m);
-nz = Jc[n];
-@end group
-@end example
-
-@noindent
-returns the actual number of non-zero elements stored in the matrix in
-@code{nz}.  As the arrays returned by @code{mxGetPr} and @code{mxGetPi}
-only contain the non-zero values of the matrix, we also need a pointer
-to the rows of the non-zero elements, and this is given by
-@code{mxGetIr}.  A complete example of the use of sparse matrices in
-mex-files is given by the file @file{mysparse.c} as seen below
-
-@example
-@EXAMPLEFILE(mysparse.c)
-@end example
-
-@node Calling Other Functions in Mex-Files
-@subsection Calling Other Functions in Mex-Files
-
-It is also possible call other Octave functions from within a mex-file
-using @code{mexCallMATLAB}.  An example of the use of
-@code{mexCallMATLAB} can be see in the example below
-
-@example
-@EXAMPLEFILE(myfeval.c)
-@end example
-
-If this code is in the file @file{myfeval.c}, and is compiled to
-@file{myfeval.mex}, then an example of its use is
-
-@example
-@group
-myfeval ("sin", 1)
-a = myfeval ("sin", 1)
-@result{} Hello, World!
-    I have 2 inputs and 1 outputs
-    I'm going to call the interpreter function sin
-    a =  0.84147
-@end group
-@end example
-
-Note that it is not possible to use function handles or inline functions
-within a mex-file.
-
-@c @node Application Programming Interface for Mex-Files
-@c @subsection Application Programming Interface for Mex-Files
-@c 
-@c WRITE ME, refer to mex.h and mexproto.h
-
-@node Standalone Programs
-@section Standalone Programs
-
-The libraries Octave itself uses, can be utilized in standalone
-applications.  These applications then have access, for example, to the
-array and matrix classes as well as to all the Octave algorithms.  The
-following C++ program, uses class Matrix from @file{liboctave.a} or
-@file{liboctave.so}.
-
-@example
-@group
-@EXAMPLEFILE(standalone.cc)
-@end group
-@end example
-
-@noindent
-mkoctfile can then be used to build a standalone application with a
-command like
-
-@example
-@group
-$ mkoctfile --link-stand-alone standalone.cc -o standalone
-$ ./standalone
-Hello Octave world!
-  11 12
-  21 22
-$
-@end group
-@end example
-
-Note that the application @code{hello} will be dynamically linked
-against the octave libraries and any octave support libraries.  The above
-allows the Octave math libraries to be used by an application.  It does
-not however allow the script files, oct-files or builtin functions of
-Octave to be used by the application.  To do that the Octave interpreter
-needs to be initialized first.  An example of how to do this can then be
-seen in the code
-
-@example
-@group
-@EXAMPLEFILE(embedded.cc)
-@end group
-@end example
-
-@noindent
-which is compiled and run as before as a standalone application with
-
-@example
-@group
-$ mkoctfile --link-stand-alone embedded.cc -o embedded
-$ ./embedded
-GCD of [10, 15] is 5
-$
-@end group
-@end example
-