--- a/doc/interpreter/external.txi	Wed Dec 28 13:58:01 2016 -0800
+++ b/doc/interpreter/external.txi	Wed Dec 28 17:49:02 2016 -0500
@@ -25,30 +25,29 @@
 @cindex Octave API
 
 "The sum of human wisdom is not contained in any one language"
-  ---Ezra Pound
+
+                                               --- Ezra Pound
 
 Octave is a fantastic language for solving many problems in science and
-engineering.  However, it is not the only computer language and there
-are times when you may want to use code written in other languages.
-Good reasons for doing so include: 1) not re-inventing the wheel; existing
-function libraries which have been thoroughly tested and debugged or
-large scale simulation codebases are a good example, 2) accessing unique
-capabilities of a different language; for example the well-known regular
-expression functions of Perl (but don't do that because @code{regexp}
-already exists in Octave).
+engineering.  However, it is not the only computer language and there are times
+when you may want to use code written in other languages.  Good reasons for
+doing so include: 1) not re-inventing the wheel; existing function libraries
+which have been thoroughly tested and debugged or large scale simulation
+codebases are a good example, 2) accessing unique capabilities of a different
+language; for example the well-known regular expression functions of Perl (but
+don't do that because @code{regexp} already exists in Octave).
 
 Performance should generally @strong{not} be a reason for using compiled
-extensions.  Although compiled extensions can run faster, particularly
-if they replace a loop in Octave code, this is almost never the best path
-to take.  First, there are many techniques to speed up Octave performance while
-remaining within the language.  Second, Octave is a high-level language that
-makes it easy to perform common mathematical tasks.  Giving that up means
-shifting the focus from solving the real problem to solving a computer
-programming problem.  It means returning to low-level constructs such as
-pointers, memory management, mathematical overflow/underflow, etc.  Because
-of the low level nature, and the fact that the compiled code is executed
-outside of Octave, there is the very real possibility of crashing the
-interpreter and losing work.
+extensions.  Although compiled extensions can run faster, particularly if they
+replace a loop in Octave code, this is almost never the best path to take.
+First, there are many techniques to speed up Octave performance while remaining
+within the language.  Second, Octave is a high-level language that makes it
+easy to perform common mathematical tasks.  Giving that up means shifting the
+focus from solving the real problem to solving a computer programming problem.
+It means returning to low-level constructs such as pointers, memory management,
+mathematical overflow/underflow, etc.  Because of the low level nature, and the
+fact that the compiled code is executed outside of Octave, there is the very
+real possibility of crashing the interpreter and losing work.
 
 Before going further, you should first determine if you really need to bother
 writing code outside of Octave.
@@ -57,42 +56,41 @@
 @item
 Can I get the same functionality using the Octave scripting language alone?
 
-Even when a function already exists outside the language, it may be
-better to simply reproduce the behavior in an m-file rather than attempt to
-interface to the outside code.
+Even when a function already exists outside the language, it may be better to
+simply reproduce the behavior in an m-file rather than attempt to interface to
+the outside code.
 
 @item
 Is the code thoroughly optimized for Octave?
 
 If performance is an issue you should always start with the in-language
 techniques for getting better performance.  Chief among these is vectorization
-(@pxref{Vectorization and Faster Code Execution}) which not only makes the
-code concise and more understandable but improves performance (10X-100X).
-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.
+(@pxref{Vectorization and Faster Code Execution}) which not only makes the code
+concise and more understandable but improves performance (10X-100X).  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 the code make as much use as possible of existing built-in library
 routines?
 
-These routines are highly optimized and many do not carry the overhead
-of being interpreted.
+These routines are highly optimized and many do not carry the overhead of being
+interpreted.
 
 @item
-Does writing a dynamically linked function represent a useful investment
-of your time, relative to staying in Octave?
+Does writing a dynamically linked function represent a useful investment of
+your time, relative to staying in Octave?
 
-It will take time to learn Octave's interface for external code and
-there will inevitably be issues with tools such as compilers.
+It will take time to learn Octave's interface for external code and there will
+inevitably be issues with tools such as compilers.
 @end itemize
 
-With that said, Octave offers a versatile interface for including chunks
-of compiled code as dynamically linked extensions.  These dynamically linked
-functions can be called from the interpreter in the same manner as any
-ordinary function.  The interface is bi-directional and external code can
-call Octave functions (like @code{plot}) which otherwise might be very
-difficult to develop.
+With that said, Octave offers a versatile interface for including chunks of
+compiled code as dynamically linked extensions.  These dynamically linked
+functions can be called from the interpreter in the same manner as any ordinary
+function.  The interface is bi-directional and external code can call Octave
+functions (like @code{plot}) which otherwise might be very difficult to
+develop.
 
 The interface is centered around supporting the languages C++, C, and Fortran.
 Octave itself is written in C++ and can call external C++/C code through its
@@ -100,9 +98,9 @@
 mex-file interface for compatibility with @sc{matlab}.  Fortran code is easiest
 to reach through the oct-file interface.
 
-Because many other languages provide C or C++ APIs it is relatively simple
-to build bridges between Octave and other languages.  This is also a way to
-bridge to hardware resources which often have device drivers written in C.
+Because many other languages provide C or C++ APIs it is relatively simple to
+build bridges between Octave and other languages.  This is also a way to bridge
+to hardware resources which often have device drivers written in C.
 
 @menu
 * Oct-Files::
@@ -130,16 +128,16 @@
 * 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::
+* Documentation and Testing of Oct-Files::
 @c * Application Programming Interface for Oct-Files::
 @end menu
 
 @node Getting Started with Oct-Files
 @subsection Getting Started with Oct-Files
 
-Oct-files are pieces of C++ code that have been compiled with the Octave
-API into a dynamically loadable object.  They take their name from the file
-which contains the object which has the extension @file{.oct}.
+Oct-files are pieces of C++ code that have been compiled with the Octave API
+into a dynamically loadable object.  They take their name from the file which
+contains the object which has the extension @file{.oct}.
 
 Finding a C++ compiler, using the correct switches, adding the right include
 paths for header files, etc.@: is a difficult task.  Octave automates this by
@@ -148,8 +146,8 @@
 
 @DOCSTRING(mkoctfile)
 
-Consider the following short example which introduces the basics of
-writing a C++ function that can be linked to Octave.
+Consider the following short example which introduces the basics of writing a
+C++ function that can be linked to Octave.
 
 @example
 @group
@@ -157,21 +155,20 @@
 @end group
 @end example
 
-The first critical line is @code{#include <octave/oct.h>} which
-makes available most of the definitions necessary for a C++ oct-file.
-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.
+The first critical line is @code{#include <octave/oct.h>} which makes available
+most of the definitions necessary for a C++ oct-file.  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.
 
-Included by @file{oct.h} is a definition for the macro
-@w{@code{DEFUN_DLD}} which creates a dynamically loaded function.  This
-macro takes four arguments:
+Included by @file{oct.h} is a definition for the macro @w{@code{DEFUN_DLD}}
+which creates a dynamically loaded function.  This macro takes four arguments:
 
 @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
+@item The number of output arguments, which can be---and often is---omitted if
 not used, and
 
 @item The string to use for the help text of the function.
@@ -180,28 +177,27 @@
 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.  First, it must be a valid Octave function name and so must be a
-sequence of letters, digits, and underscores not starting with a
-digit.  Second, 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 would be
-compiled to an oct-file using the command
+There are a couple of important considerations in the choice of function name.
+First, it must be a valid Octave function name and so must be a sequence of
+letters, digits, and underscores not starting with a digit.  Second, 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 would 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 @code{autoload} (@ref{Function Files}) function should be used.
+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
+@code{autoload} (@ref{Function Files}) function should be used.
 
-The rest of the function shows how to find the number of input arguments,
-how to print through the Octave pager, and return from the function.  After
+The rest of the function shows how to find the number of input arguments, how
+to print through the Octave pager, and how to return from the function.  After
 compiling this function as above, an example of its use is
 
 @example
@@ -212,33 +208,32 @@
 @end example
 
 Subsequent sections show how to use specific classes from Octave's core
-internals.  Base classes like dMatrix (a matrix of double values) are
+internals.  Base classes like @code{dMatrix} (a matrix of double values) are
 found in the directory @file{liboctave/array}.  The definitive reference for
-how to use a particular class is the header file itself.  However, it is
-often enough just to study the examples in the manual in order to be able
-to use the class.
+how to use a particular class is the header file itself.  However, it is often
+enough simply to study the examples in the manual in order to be able to use a
+class.
 
 @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
+Octave supports a number of different array and matrix classes, the majority of
+which are based on the @code{Array} class.  The exception are the sparse matrix
+types discussed separately below.  There are three basic matrix types:
 
 @table @code
 @item Matrix
-A double precision matrix class defined in @file{dMatrix.h},
+A double precision matrix class defined in @file{dMatrix.h}
 
 @item ComplexMatrix
-A complex matrix class defined in @file{CMatrix.h}, and
+A complex matrix class defined in @file{CMatrix.h}
 
 @item BoolMatrix
-A boolean matrix class defined in @file{boolMatrix.h}.
+A boolean matrix class defined in @file{boolMatrix.h}
 @end table
 
-These are the basic two-dimensional matrix types of Octave.  In
-addition there are a number of multi-dimensional array types including
+These are the basic two-dimensional matrix types of Octave.  In addition there
+are a number of multi-dimensional array types including
 
 @table @code
 @item NDArray
@@ -265,9 +260,8 @@
 @file{uint8NDArray.h}, @file{uint16NDArray.h}, etc.
 @end table
 
-There are several basic ways of constructing matrices or
-multi-dimensional arrays.  Using the class @code{Matrix} as an example
-one can
+There are several basic ways of constructing matrices or multi-dimensional
+arrays.  Using the class @code{Matrix} as an example one can
 
 @itemize @bullet
 @item
@@ -280,8 +274,8 @@
 This can be used for all matrix and array types.
 
 @item
-Define the dimensions of the matrix or array with a dim_vector which has
-the same characteristics as the vector returned from @code{size}.  For example:
+Define the dimensions of the matrix or array with a dim_vector which has the
+same characteristics as the vector returned from @code{size}.  For example:
 
 @example
 @group
@@ -290,7 +284,7 @@
 @end group
 @end example
 
-This can be used on all matrix and array types.
+This can be used for all matrix and array types.
 
 @item
 Define the number of rows and columns in the matrix.  For example:
@@ -299,28 +293,28 @@
 Matrix a (2, 2)
 @end example
 
-However, this constructor can only be used with matrix types.
+This constructor can @strong{only} be used with matrix types.
 @end itemize
 
-These types all share a number of basic methods and operators.  Many bear
-a resemblance to functions that exist in the interpreter.  A selection of
-useful methods include
+These types all share a number of basic methods and operators.  Many bear a
+resemblance to functions that exist in the interpreter.  A selection of useful
+methods 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.
+The @code{()} operator or @code{elem} method allow the values of the matrix or
+array to be read or set.  These methods 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 @code{elem} method, giving the row and column index of the value
+to get 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.
+circumstances the user might prefer to access the data of the array or matrix
+directly through the @code{fortran_vec} method discussed below.
 
-@deftypefn {Method} {} octave_idx_type numel (void) const
+@deftypefn {Method} {octave_idx_type} numel (void) const
 The total number of elements in the matrix or array.
 @end deftypefn
 
@@ -329,30 +323,31 @@
 @end deftypefn
 
 @deftypefn {Method} {dim_vector} dims (void) const
-The dimensions of the matrix or array in value of type dim_vector.
+The dimensions of the matrix or array in value of type @code{dim_vector}.
 @end deftypefn
 
 @deftypefn {Method} {int} ndims (void) const
-The number of dimensions of the matrix or array.  Matrices are 2-D,
-but arrays can be N-dimensional.
+The number of dimensions of the matrix or array.  Matrices are always 2-D, but
+arrays can be N-dimensional.
 @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.
+@deftypefn  {Method} {void} resize (const dim_vector&)
+@deftypefnx {Method} {void} resize (nrows, ncols)
+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
-array so that it can be manipulated directly, either within Octave or by
-an external library.
+This method returns a pointer to the underlying data of the matrix or 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 matrix and array 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.
+Operators such as @code{+}, @code{-}, or @code{*} can be used on the majority
+of the matrix and array 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
@@ -363,23 +358,22 @@
 @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.  If an
-error occurs when attempting to extract the value, Octave will print a
-message and throw an exception.  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.  If you need to catch errors like this and
-perform some kind of cleanup or other operation, you can catch the
-@code{octave_execution_error} exception.
+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 @code{array_value} method is called
+without using the @code{is_matrix_type} method.  If an error occurs when
+attempting to extract the value, Octave will print a message and throw an
+exception.  The reason to prefer this coding structure is that the arguments
+might be a type which is not an @code{NDArray}, but for which it would make
+sense to convert them to one.  The @code{array_value} method allows this
+conversion to be performed transparently when possible.  If you need to catch
+errors like this, and perform some kind of cleanup or other operation, you can
+catch the @code{octave_execution_error} exception.
 
-@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
+@code{A + B}, operating on two @code{NDArray} objects 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
@@ -420,8 +414,8 @@
 @node Character Strings in Oct-Files
 @subsection Character Strings in Oct-Files
 
-A character string in Octave is just a special @code{Array} class.
-Consider the example:
+A character string in Octave is just a special @code{Array} class.  Consider
+the example:
 
 @example
 @EXAMPLEFILE(stringdemo.cc)
@@ -446,10 +440,10 @@
 @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 use
-one of the predicate tests shown below.
+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 use one of the predicate tests shown
+below.
 
 @example
 @group
@@ -461,8 +455,8 @@
 @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:
+@code{charNDArray} type, and so when assigning to an @code{octave_value}, the
+type of string should be specified.  For example:
 
 @example
 @group
@@ -470,7 +464,7 @@
 charNDArray ch;
 @dots{}
 // Create single quoted string
-retval(1) = octave_value (ch);        // default constructor is sq_string
+retval(1) = octave_value (ch);   // default constructor is sq_string
            OR
 retval(1) = octave_value (ch, '\'');  // explicitly create sq_string
 
@@ -482,19 +476,18 @@
 @node Cell Arrays in Oct-Files
 @subsection Cell Arrays in Oct-Files
 
-Octave's cell type is also available from within oct-files.  A cell
-array is just an array of @code{octave_value}s, and thus each element of the
-cell array can be treated just like any other @code{octave_value}.  A simple
-example is
+Octave's cell type is also available from within oct-files.  A cell array is
+just an @code{Array} of @code{octave_value}s, and thus each element of the cell
+array can be treated like any other @code{octave_value}.  A simple example is
 
 @example
 @EXAMPLEFILE(celldemo.cc)
 @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 the
-example extracts the @code{octave_value}s one by one from the cell array and
-returns them as individual return arguments.  For 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 the example
+extracts the @code{octave_value}s one by one from the cell array and returns
+them as individual output arguments.  For example:
 
 @example
 @group
@@ -512,10 +505,9 @@
 @node Structures in Oct-Files
 @subsection Structures in Oct-Files
 
-A structure in Octave is a 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 structure in Octave is a 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
 
@@ -533,26 +525,25 @@
 @end group
 @end example
 
-The example above specifically uses the @code{octave_scalar_map} class which
-is for representing a single struct.  For structure arrays the
-@code{octave_map} class is used instead.  The commented code shows how the
-demo could be modified to handle a structure array.  In that case the
-@code{contents} method returns a @code{Cell} which may have more than one
-element.  Therefore, to obtain the underlying @code{octave_value} in
-this single-struct example we write
+The example above specifically uses the @code{octave_scalar_map} class which is
+for representing a single struct.  For structure arrays, the @code{octave_map}
+class is used instead.  The commented code shows how the demo could be modified
+to handle a structure array.  In that case, the @code{contents} method returns
+a @code{Cell} which may have more than one element.  Therefore, to obtain the
+underlying @code{octave_value} in the single struct example we would write
 
 @example
 octave_value tmp = arg0.contents (arg1)(0);
 @end example
 
 @noindent
-where the trailing (0) is the () operator on the @code{Cell} object.  If
-this were a true structure array with multiple elements we could iterate
-over the elements using the () operator.
+where the trailing @code{(0)} is the @code{()} operator on the @code{Cell}
+object.  If this were a true structure array with multiple elements we could
+iterate over the elements using the @code{()} operator.
 
-Structures are a relatively complex data container and there are more
-functions available in @file{oct-map.h} which make coding with them easier
-than relying on just @code{contents}.
+Structures are a relatively complex data container and there are more functions
+available in @file{oct-map.h} which make coding with them easier than relying
+on just @code{contents}.
 
 @node Sparse Matrices in Oct-Files
 @subsection Sparse Matrices in Oct-Files
@@ -570,20 +561,19 @@
 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's @code{Array<T>} class, and so users familiar
-with Octave's @code{Array} classes will be comfortable with the use of
-the sparse classes.
+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's @code{Array<T>} class and 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.  First, although it is fundamentally
-possible to have N-dimensional sparse objects, the Octave sparse classes do
-not allow them at this time; All instances of the sparse classes
-must be 2-dimensional.  This means that @code{SparseMatrix} is actually
-more similar to Octave's @code{Matrix} class than its @code{NDArray} class.
+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 nature of sparse objects, and these will be described.
+First, although it is fundamentally possible to have N-dimensional sparse
+objects, the Octave sparse classes do not allow them at this time; All
+instances of the sparse classes @strong{must} be 2-dimensional.  This means
+that @code{SparseMatrix} is actually more similar to Octave's @code{Matrix}
+class than it is to the @code{NDArray} class.
 
 @menu
 * Array and Sparse Class Differences::
@@ -595,35 +585,34 @@
 @subsubsection Array and Sparse Class Differences
 
 The number of elements in a sparse matrix is considered to be the number
-of nonzero elements rather than the product of the dimensions.  Therefore
+of nonzero elements, rather than the product of the dimensions.  Therefore,
 
 @example
 @group
 SparseMatrix sm;
 @dots{}
-int nel = sm.nelem ();
+int nnz = sm.nelem ();
 @end group
 @end example
 
 @noindent
-returns the number of nonzero elements.  If the user really requires the
-number of elements in the matrix, including the nonzero 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 nonzero 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 unless it is known
-that it will not overflow.
+returns the number of nonzero elements (like the interpreter function
+@code{nnz}).  If the user really requires the number of elements in the matrix,
+including the nonzero 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, @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 nonzero elements.  In this case,
+the number of rows multiplied by the number of columns is more than two hundred
+times the maximum value that can be represented by an unsigned 32-bit int.  The
+use of @code{numel} should, therefore, be avoided unless it is known that it
+will not overflow.
 
-Extreme care must be take with the elem method and the @qcode{"()"} 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
+Extreme care is also required when using the @code{elem} method or the
+@qcode{()} operator which perform essentially 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
@@ -631,20 +620,21 @@
 @dots{}
 for (int j = 0; j < nc; j++)
   for (int i = 0; i < nr; i++)
-    std::cerr << " (" << i << "," << j << "): " << sm(i,j) << std::endl;
+    std::cerr << " (" << i << "," << j << "): " << sm(i,j) << "\n";
 @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.
+is a great way of turning a sparse matrix into a dense one, and a very slow
+way at that since it reallocates the sparse object for 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
+A simple 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; This is not a costly
+operation.  The example above, re-written to prevent sparse-to-dense
+conversion, is 
 
 @example
 @group
@@ -653,31 +643,29 @@
 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;
+    std::cerr << " (" << i << "," << j << "): " << tmp(i,j) << "\n";
 @end group
 @end example
 
-Finally, as the sparse types aren't represented by 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 Octave sparse matrices are stored in.  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.
+Finally, because the sparse types aren't represented by a contiguous block of
+memory, the @nospell{@code{fortran_vec}} method of @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
+Octave sparse matrices are stored in.  These methods can be used in a manner
+similar to @code{elem} to allow the matrix to be accessed or filled.  However,
+it is up to the user to respect the sparse matrix compressed column format or
+the matrix will become corrupted.
 
 @node Creating Sparse Matrices in Oct-Files
 @subsubsection Creating Sparse Matrices in Oct-Files
 
-There are several useful alternatives for creating a sparse matrix.
-The first is to create three vectors representing the row index, column index,
-and data values, and from these create the matrix.
-The second alternative is to create a sparse matrix with the appropriate
-amount of space and then fill in the values.  Both techniques have their
-advantages and disadvantages.
+There are two useful strategies for creating a sparse matrix.  The first is to
+create three vectors representing the row index, column index, and data values,
+and from these create the matrix.  The second alternative is to create a sparse
+matrix with the appropriate amount of space, and then fill in the values.  Both
+techniques have their advantages and disadvantages.
 
-Below is an example of creating a small sparse matrix using the first
-technique
+Below is an example of creating a small sparse matrix using the first technique
 
 @example
 @group
@@ -697,24 +685,22 @@
 @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,
-but is used internally.
+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, but is used internally.
 
-As discussed in the chapter on Sparse Matrices, the values of the sparse
-matrix are stored in increasing column-major ordering.  Although the data
-passed by the user need not respect this requirement, pre-sorting the
-data will significantly speed up creation of the sparse matrix.
+As discussed in the chapter on Sparse Matrices, the values of the sparse matrix
+are stored in increasing column-major ordering.  Although the data passed by
+the user need not respect this requirement, pre-sorting the data will
+significantly speed up creation of the sparse matrix.
 
-The disadvantage of this technique for creating a sparse matrix is
-that there is a brief time when two copies of the data exist.  For
-extremely memory constrained problems this may not be the best
-technique for creating a sparse matrix.
+The disadvantage of this technique for creating a sparse matrix is that there
+is a brief time when two copies of the data exist.  For extremely memory
+constrained problems this may not be the best technique for creating a sparse
+matrix.
 
-The alternative is to first create a sparse matrix with the desired
-number of nonzero elements and then later fill those elements in.
-Sample code:
+The alternative is to first create a sparse matrix with the desired number of
+nonzero elements and then later fill those elements in.  Sample code:
 
 @example
 @group
@@ -725,16 +711,16 @@
 @end group
 @end example
 
-This creates the same matrix as previously.  Again, although not
-strictly necessary, it is significantly faster if the sparse matrix is
-created and the elements are added in column-major ordering.  The reason
-for this is that when 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.
+This creates the same matrix as previously.  Again, although not strictly
+necessary, it is significantly faster if the sparse matrix is created and the
+elements are added in column-major ordering.  The reason for this is that when
+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 indices need to be updated.
 
-There are a few further points to note about this method of creating
-a sparse matrix.  First, it is possible to create a sparse matrix
-with fewer elements than are actually inserted in the matrix.  Therefore,
+There are a few further points to note about this method of creating a sparse
+matrix.  First, it is possible to create a sparse matrix with fewer elements
+than are actually inserted in the matrix.  Therefore,
 
 @example
 @group
@@ -746,25 +732,24 @@
 @end example
 
 @noindent
-is perfectly valid.  However, it is a very bad idea because as each new
-element is added to the sparse matrix the matrix needs to request more
-space and reallocate 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} greater than 4 is also valid.  The disadvantage is that the matrix
-occupies more memory than strictly needed.
+is perfectly valid.  However, it is a very bad idea because as each new element
+is added to the sparse matrix the matrix needs to request more space and
+reallocate memory.  This is an expensive operation that will significantly slow
+this means of creating a sparse matrix.  It is possible to create a sparse
+matrix with excess storage, so having @var{nz} greater than 4 in this example
+is also valid.  The disadvantage is that the matrix occupies more memory than
+strictly needed.
 
-It is not always possible to know the number of nonzero elements prior
-to filling a matrix.  For this reason the additional unused storage of
-a sparse matrix can be removed after its creation with the
-@code{maybe_compress} function.  In addition, @code{maybe_compress} can
-deallocate the unused storage, but it can also remove zero elements
-from the matrix.  The removal of zero elements from the matrix is
-controlled by setting the argument of the @code{maybe_compress} function
-to be @code{true}.  However, the cost of removing the zeros is high because it
-implies re-sorting the elements.  If possible, it is better
-if the user does not add the unnecessary zeros in the first place.
-An example of the use of @code{maybe_compress} is
+Of course, it is not always possible to know the number of nonzero elements
+prior to filling a matrix.  For this reason the additional unused storage of a
+sparse matrix can be removed after its creation with the @code{maybe_compress}
+function.  In addition to deallocating unused storage, @code{maybe_compress}
+can also remove zero elements from the matrix.  The removal of zero elements
+from the matrix is controlled by setting the argument of the
+@code{maybe_compress} function to be @code{true}.  However, the cost of
+removing the zeros is high because it implies re-sorting the elements.  If
+possible, it is better for the user to avoid adding the unnecessary zeros in
+the first place.  An example of the use of @code{maybe_compress} is
 
 @example
 @group
@@ -773,7 +758,7 @@
 
 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
+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;
@@ -782,12 +767,11 @@
 @end group
 @end example
 
-The use of the @code{maybe_compress} function should be avoided if
-possible as it will slow the creation of the matrix.
+The use of the @code{maybe_compress} function should be avoided if possible as
+it will slow the creation of the matrix.
 
-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
+A third means of creating a sparse matrix is to work directly with the data in
+compressed row format.  An example of this advanced technique might be
 
 @example
 octave_value arg;
@@ -803,7 +787,7 @@
   @{
     for (int i = 0; i < nr; i++)
       @{
-        double tmp = foo (m(i,j));
+        double tmp = m(i,j);
         if (tmp != 0.)
           @{
             sm.data(ii) = tmp;
@@ -819,16 +803,16 @@
 @noindent
 which is probably the most efficient means of creating a 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
+Finally, it may 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, nr, nc;
-nz = 6, nr = 3, nc = 4;   // Assume we know the max # nz
+nz = 6, nr = 3, nc = 4;   // Guess the number of nz elements
 SparseMatrix sm (nr, nc, nz);
 Matrix m = arg.matrix_value ();
 
@@ -838,7 +822,7 @@
   @{
     for (int i = 0; i < nr; i++)
       @{
-        double tmp = foo (m(i,j));
+        double tmp = m(i,j);
         if (tmp != 0.)
           @{
             if (ii == nz)
@@ -853,31 +837,29 @@
       @}
     sm.cidx(j+1) = ii;
  @}
-sm.maybe_mutate ();  // If don't know a priori the final # of nz.
+sm.maybe_compress ();  // If don't know a priori the final # of nz.
 @end example
 
-Note that both increasing and decreasing the number of nonzero elements in
-a sparse matrix is expensive as it involves memory reallocation.  Also as
-parts of the matrix, though not its entirety, exist as old and new copies
-at the same time, additional memory is needed.  Therefore, if possible this
-should be avoided.
+Note that both increasing and decreasing the number of nonzero elements in a
+sparse matrix is expensive as it involves memory reallocation.  Also because
+parts of the matrix, though not its entirety, exist as old and new copies at
+the same time, additional memory is needed.  Therefore, if possible avoid
+changing capacity.
 
 @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 command line are also available within oct-files.
-The basic means of extracting a sparse matrix from an @code{octave_value}
-and returning it as an @code{octave_value}, can be seen in the
-following example.
+Most of the same operators and functions for sparse matrices that are available
+from the Octave interpeter are also available within oct-files.  The basic
+means of extracting a sparse matrix from an @code{octave_value}, and returning
+it 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 ();
+SparseComplexMatrix scm = args(1).sparse_complex_matrix_value ();
 SparseBoolMatrix sbm = args(2).sparse_bool_matrix_value ();
 @dots{}
 retval(2) = sbm;
@@ -892,13 +874,13 @@
 @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 be accessed within oct-files by 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 if no global variable of the desired name is found.
-An example of the use of these two functions is
+Global variables allow variables in the global scope to be accessed.  Global
+variables can be accessed within oct-files by using the support functions
+@w{@code{get_global_value}} and @w{@code{set_global_value}}.
+@w{@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 if no global variable of the desired name is
+found.  An example of the use of these two functions is
 
 @example
 @EXAMPLEFILE(globaldemo.cc)
@@ -922,13 +904,12 @@
 @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 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
+There are also many ways in which a function could be given as input.  It might
 be passed as one of
 
 @enumerate 1
@@ -941,36 +922,35 @@
 @item String
 @end enumerate
 
-The example below demonstrates an example that accepts all four means of
-passing a function to an oct-file.
+The code below demonstrates all four methods 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 remaining arguments are all passed to the user function.
+The first input to the demonstration code is a user-supplied function and the
+remaining arguments are all passed to the function.
 
 @example
 @group
-funcdemo (@@sin,1)
+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)
+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 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
-as demonstrated below.
+When the user function is passed as a string the treatment of the function is
+different.  In some cases it is necessary to 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 as demonstrated below.
 
 @example
 @group
@@ -987,20 +967,20 @@
 @end example
 
 There are two important things to know in this case.  First, the number of
-input arguments to the user function is fixed, and in the above example is
-a single argument.  Second, to avoid leaving the temporary function in the
-Octave symbol table it should be cleared after use.  Also, by convention
-internal function names begin and end with the character sequence @samp{__}.
+input arguments to the user function is fixed, and in the above example is a
+single argument.  Second, to avoid leaving the temporary function in the Octave
+symbol table it should be cleared after use.  Also, by convention all internal
+function names begin and end with the character sequence @samp{__}.
 
 @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
-that the declarations of the external C functions may need to be explicitly
-defined as C functions to the compiler.  If the declarations of the
-external C functions are in the header @file{foo.h}, then the tactic to
-ensure that the C++ compiler treats these declarations as C code is
+Linking external C code to Octave is relatively simple, as the C functions can
+easily be called directly from C++.  One possible issue is that the
+declarations of the external C functions may need to be explicitly defined as C
+functions to the compiler.  If the declarations of the external C functions are
+in the header @file{foo.h}, then the tactic to ensure that the C++ compiler
+treats these declarations as C code is
 
 @example
 @group
@@ -1017,30 +997,29 @@
 
 Calling Fortran code, however, can pose more difficulties.  This is due to
 differences in the manner in which compilers treat the linking of Fortran code
-with C or C++ code.  Octave supplies a number of macros that allow consistent
+with C or C++ code.  Octave supplies several 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}.
+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 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.
+If the 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 great 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.
+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
+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(fortrandemo.cc)
@@ -1053,10 +1032,10 @@
 @EXAMPLEFILE(fortransub.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.  Both the Fortran and C++ files need to be compiled
-in order for the example to work.
+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.  Both the Fortran and C++ files need to be compiled in order for the
+example to work.
 
 @example
 @group
@@ -1073,46 +1052,44 @@
 @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 great 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
+Allocating memory within an oct-file might seem easy, as the C++ new/delete
+operators can be used.  However, in that case great 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}.
+that returns a pointer @code{tmp} of type @code{double *} of length @code{len}.
 
-In this case Octave itself will worry about reference counting and variable
+In this case, Octave itself will worry about reference counting and variable
 scope and will properly free memory without programmer intervention.
 
 @node Input Parameter Checking in Oct-Files
 @subsection Input Parameter Checking in Oct-Files
 
-As oct-files are compiled functions they open up the possibility of
-crashing Octave through careless function calls or memory faults.
-It is quite important that each and every function have a sufficient level
-of parameter checking to ensure that Octave behaves well.
+Because oct-files are compiled functions they open up the possibility of
+crashing Octave through careless function calls or memory faults.  It is quite
+important that each and every function have a sufficient level of parameter
+checking 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 nonexistent
-argument.  However, in some cases 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, or if the input is complex
-and a real value was expected.  Therefore, oct-files often need additional
-input parameter checking.
+The minimum requirement, as previously discussed, is to check the number of
+input arguments before using them to avoid referencing a nonexistent argument.
+However, in some cases 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, or if the input is complex and a real value was expected.  Therefore,
+oct-files often need additional input parameter checking.
 
-There are several functions within Octave that can be useful for the
-purposes of parameter checking.  These include the methods of the
-octave_value class like @code{is_real_matrix}, @code{is_numeric_type}, etc.
-Often, with a knowledge of the Octave m-file language, you can guess at what
-the corresponding C++ routine will.  In addition there are some more
-specialized input validation functions of which a few are demonstrated below.
+There are several functions within Octave that can be useful for the purposes
+of parameter checking.  These include the methods of the @code{octave_value}
+class like @code{is_real_matrix}, @code{is_numeric_type}, etc. (See
+@file{ov.h}).  Often, with a knowledge of the Octave m-file language, you can
+guess at what the corresponding C++ routine will.  In addition there are some
+more specialized input validation functions of which a few are demonstrated
+below.
 
 @example
 @EXAMPLEFILE(paramdemo.cc)
@@ -1134,12 +1111,13 @@
 @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 @key{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 @key{Control-C},
-the @w{@code{OCTAVE_QUIT}} macro is supplied.  For example:
+Another important feature of Octave is its ability to react to the user typing
+@key{Control-C} during extended calculations.  This ability is based on the C++
+exception handler, where memory allocated by the C++ new/delete methods is
+automatically released when the exception is treated.  When writing an oct-file
+which may run for a long time the programmer must periodically use the macro
+@w{@code{OCTAVE_QUIT}}, in order to allow Octave to check and possibly respond
+to a user typing @key{Control-C}.  For example:
 
 @example
 @group
@@ -1152,18 +1130,19 @@
 @end example
 
 The presence of the @w{@code{OCTAVE_QUIT}} macro in the inner loop allows
-Octave to treat the user request with the @key{Control-C}.  Without this macro,
-the user must either wait for the function to return before the interrupt is
-processed, or press @key{Control-C} three times to force Octave to exit.
+Octave to detect and acknowledge a @key{Control-C} key sequence.  Without this
+macro, the user must either wait for the oct-file function to return before the
+interrupt is processed, or the user must press @key{Control-C} three times
+which will force Octave to exit completely.
 
-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
+The @w{@code{OCTAVE_QUIT}} macro does impose a very small performance penalty;
+For loops that are known to be small it may 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
+When creating an oct-file that uses an external library, 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 code in this case is
 
 @example
 @group
@@ -1173,17 +1152,16 @@
 @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 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{@code{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
+The Octave @code{unwind_protect} mechanism (@ref{The unwind_protect Statement})
+can also be used in oct-files.  In conjunction with the exception handling of
+Octave, it ensures that certain recovery code is always run even if an
+exception occurs.  An example of the use of this mechanism is
 
 @example
 @EXAMPLEFILE(unwinddemo.cc)
@@ -1204,19 +1182,18 @@
 The warning for division by zero (and in fact all warnings) are disabled in the
 @code{unwinddemo} function.
 
-@node Documentation and Test of Oct-Files
-@subsection Documentation and Test of Oct-Files
+@node Documentation and Testing of Oct-Files
+@subsection Documentation and Testing 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,
-however there are some issue that are particular to the formatting of
-help strings within oct-files.
+The documentation for an oct-file is contained in 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, however there are some issues
+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 needs to
-be taken into account.  There are several possible solutions, but the most
-common is illustrated in the following example,
+The major issue is that the help string will typically be longer than a single
+line of text, and so the formatting of long multi-line help strings needs to be
+taken into account.  There are several possible solutions, but the most common
+is illustrated in the following example,
 
 @example
 @group
@@ -1233,22 +1210,20 @@
 @end example
 
 @noindent
-where, as can be seen, each line of text 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.
+where each line of text is terminated by @code{\n\} which is an embedded
+newline 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 test and demonstration
-code for a function within the code itself (@pxref{Test and Demo Functions}).
-This can be used from within oct-files (or in fact any file) with
-certain provisos.  First, the test and demo functions of Octave look
-for @code{%!} as the first two characters of a line to identify test
-and demonstration code.  This is a requirement for oct-files as well.
-In addition, the test and demonstration code must be wrapped in a comment
-block to avoid it being interpreted by the compiler.  Finally, the Octave
-test and demonstration code must have access to the original 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
+Octave also includes the ability to embed test and demonstration code for a
+function within the code itself (@pxref{Test and Demo Functions}).  This can be
+used from within oct-files (or in fact any file) with certain provisos.  First,
+the test and demo functions of Octave look for @code{%!} as the first two
+characters of a line to identify test and demonstration code.  This is a
+requirement for oct-files as well.  In addition, the test and demonstration
+code must be wrapped in a comment block to avoid it being interpreted by the
+compiler.  Finally, the Octave test and demonstration code must have access to
+the original source code of the oct-file---not just the compiled code---as the
+tests are stripped from the compiled code.  An example in an oct-file might be
 
 @example
 @group
@@ -1270,16 +1245,16 @@
 @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
-@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
-variables are passed to mex functions there are a significant number of
-additional copies of memory blocks when calling or returning from a
-mex-file function.  For this reason, it is recommended that any new code
-be written with the oct-file interface previously discussed.
+Octave includes an interface to allow legacy mex-files to be compiled and used
+with Octave.  This interface can also be used to share compiled code between
+Octave and @sc{matlab} users.  However, as mex-files expose @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 variables are passed to mex
+functions there are a significant number of additional copies of memory blocks
+when invoking or returning from a mex-file function.  For this reason, it is
+recommended that any new code be written with the oct-file interface previously
+discussed.
 
 @menu
 * Getting Started with Mex-Files::
@@ -1295,11 +1270,11 @@
 @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 command can be used either 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.
-Compiled mex-files have the extension @file{.mex}.
+The basic command to build a mex-file is either @code{mkoctfile --mex} or
+@code{mex}.  The first command can be used either from within Octave or from
+the command line.  To avoid issues with @sc{matlab}'s own @code{mex} command,
+the use of the command @code{mex} is limited to within Octave.  Compiled
+mex-files have the extension @file{.mex}.
 
 @DOCSTRING(mex)
 
@@ -1334,10 +1309,10 @@
 @end enumerate
 
 Note that the function name definition is not explicitly included in
-@code{mexFunction} and so there can only be a single @code{mexFunction}
-entry point per file.  Instead, the name of the function as seen in Octave is
-determined by the name of the mex-file itself minus the extension.  Therefore,
-if the above function is in the file @file{myhello.c}, it can be compiled with
+@code{mexFunction} and so there can only be a single @code{mexFunction} entry
+point per file.  Instead, the name of the function as seen in Octave is
+determined by the name of the mex-file itself minus the extension.  If the
+above function is in the file @file{myhello.c}, it can be compiled with
 
 @example
 mkoctfile --mex myhello.c
@@ -1355,25 +1330,24 @@
 @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{myhello.m} that might
-contain the text
+It should be noted that the mex-file contains no help string.  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, there would need to be a file
+@file{myhello.m} which might contain the text
 
 @example
 %MYHELLO 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.
+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 there cannot be multiple entry points in a single mex-file,
-one 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
+Although there cannot be multiple entry points in a single mex-file, one 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
@@ -1382,7 +1356,7 @@
 @end example
 
 @noindent
-is in file @file{myfunc.c}, and it is compiled with
+is in the file @file{myfunc.c}, and is compiled with
 
 @example
 @group
@@ -1405,37 +1379,34 @@
 @end example
 
 @noindent
-the behavior of the mex-file can be altered depending on the functions
-name.
+the behavior of the mex-file can be altered depending on the function's name.
 
 Although the user should only include @file{mex.h} in their code, Octave
-declares additional functions, typedefs, etc., available to the user to
-write mex-files in the headers @file{mexproto.h} and @file{mxarray.h}.
+declares additional functions, typedefs, etc., available to the user to write
+mex-files in the headers @file{mexproto.h} and @file{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}.  Any object,
-such as a matrix, cell array, or structure is stored in this basic
-type.  As such, @code{mxArray} serves basically the same purpose as the
-octave_value class in oct-files in that it acts as a container for the
-more specialized types.
+The basic mex type of all variables is @code{mxArray}.  Any object, such as a
+matrix, cell array, or structure, is stored in this basic type.  @code{mxArray}
+serves essentially the same purpose as the @code{octave_value} class in
+oct-files in that it acts as a container for all the more specialized types.
 
-The @code{mxArray} structure contains at a minimum, the name of the
-variable it represents, its dimensions, its type, and whether the variable is
-real or complex.  It can also 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{mxCreateDoubleMatrix}, @code{mxCreateCellArray}, @code{mxCreateSparse},
-and the generic @code{mxCreateNumericArray}.
+The @code{mxArray} structure contains at a minimum, the name of the variable it
+represents, its dimensions, its type, and whether the variable is real or
+complex.  It can also 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{mxCreateDoubleMatrix},
+@code{mxCreateCellArray}, @code{mxCreateSparse}, and the generic
+@code{mxCreateNumericArray}.
 
-The basic function to access the data contained in an array is
-@code{mxGetPr}.  As the mex interface assumes that real and imaginary
-parts of a complex array are stored separately, there is an equivalent
-function @code{mxGetPi} that gets the imaginary part.  Both of these
-functions are only for use with double precision matrices.  The generic
-functions @code{mxGetData} and @code{mxGetImagData} perform the same operation
-on all matrix types.  For example:
+The basic function to access the data in an array is @code{mxGetPr}.  Because
+the mex interface assumes that real and imaginary parts of a complex array are
+stored separately, there is an equivalent function @code{mxGetPi} that gets the
+imaginary part.  Both of these functions are only for use with double precision
+matrices.  The generic functions @code{mxGetData} and @code{mxGetImagData}
+perform the same operation for all matrix types.  For example:
 
 @example
 @group
@@ -1450,26 +1421,26 @@
 @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}.
+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 also @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 dimensions
-and the maximum number or elements, while @code{mwIndex} is used to define
-indexing into arrays.
+Note the type @code{mwSize} used above, and also @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 dimensions and the maximum
+number or elements, while @code{mwIndex} is used to define indexing into
+arrays.
 
-An example that demonstrates how to work with arbitrary real or complex
-double precision arrays is given by the file @file{mypow2.c} shown below.
+An example that demonstrates how to work with arbitrary real or complex double
+precision arrays is given by the file @file{mypow2.c} shown below.
 
 @example
 @EXAMPLEFILE(mypow2.c)
 @end example
 
 @noindent
-with an example of its use
+An example of its use is
 
 @example
 @group
@@ -1480,19 +1451,19 @@
 @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 2-D matrix.
+@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
+2-D matrix (MxN 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 shown below.
+As mex-files do not make the distinction between single and double quoted
+strings that Octave does, there is perhaps less complexity in the use of
+strings and character matrices.  An example of their use that parallels the
+demo in @file{stringdemo.cc} is given in the file @file{mystring.c}, as shown
+below.
 
 @example
 @EXAMPLEFILE(mystring.c)
@@ -1511,18 +1482,17 @@
 
 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.
+@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 @code{mxArray} for the matrix is consecutive in
+any case.
 
 @node Cell Arrays with Mex-Files
 @subsection Cell Arrays with Mex-Files
 
-One can perform exactly the same operations on Cell arrays in mex-files
-as in oct-files.  An example that reduplicates the function of
-the @file{celldemo.cc} oct-file in a mex-file is given by @file{mycell.c}
-as shown below.
+One can perform exactly the same operations on Cell arrays in mex-files as in
+oct-files.  An example that duplicates the function of the @file{celldemo.cc}
+oct-file in a mex-file is given by @file{mycell.c} as shown below.
 
 @example
 @EXAMPLEFILE(mycell.c)
@@ -1544,10 +1514,10 @@
 @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}, used for
-setting Cell values, is @code{mxSetCell} and is defined as
+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}, used for setting Cell
+values, is @code{mxSetCell} and is defined as
 
 @example
 void mxSetCell (mxArray *ptr, int idx, mxArray *val);
@@ -1597,14 +1567,14 @@
 @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.
+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 a mex-file can be
-found in the file @file{mystruct.c} shown below.
+An example that demonstrates the use of structures in a mex-file can be found
+in the file @file{mystruct.c} shown below.
 
 @example
 @EXAMPLEFILE(mystruct.c)
@@ -1638,14 +1608,15 @@
 @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 Octave format for sparse matrices is identical to the mex format in that it
+is a compressed column sparse format.  Also, in both implementations sparse
+matrices are required to be two-dimensional.  The only difference of importance
+to the programmer is that the real and imaginary parts of the matrix are stored
+separately.
 
 The mex-file interface, in addition to using @code{mxGetM}, @code{mxGetN},
-@code{mxSetM}, @code{mxSetN}, @code{mxGetPr}, @code{mxGetPi},
-@code{mxSetPr}, and @code{mxSetPi}, also supplies the following functions.
+@code{mxSetM}, @code{mxSetN}, @code{mxGetPr}, @code{mxGetPi}, @code{mxSetPr},
+and @code{mxSetPi}, also supplies the following functions.
 
 @example
 @group
@@ -1660,13 +1631,12 @@
 @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 nonzero
-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 nonzero elements in each column of
-the sparse matrix.  Therefore,
+@code{mxGetNzmax} gets the maximum number of elements that can be stored in the
+sparse matrix.  This is not necessarily the number of nonzero 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 nonzero
+elements in each column of the sparse matrix.  Therefore,
 
 @example
 @group
@@ -1682,11 +1652,11 @@
 
 @noindent
 returns the actual number of nonzero elements stored in the matrix in
-@code{nz}.  As the arrays returned by @code{mxGetPr} and @code{mxGetPi}
-only contain the nonzero values of the matrix, we also need a pointer
-to the rows of the nonzero 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} shown below.
+@code{nz}.  As the arrays returned by @code{mxGetPr} and @code{mxGetPi} only
+contain the nonzero values of the matrix, we also need a pointer to the rows of
+the nonzero 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} shown below.
 
 @example
 @EXAMPLEFILE(mysparse.c)
@@ -1707,9 +1677,9 @@
 @node Calling Other Functions in Mex-Files
 @subsection Calling Other Functions in Mex-Files
 
-It is possible to 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.
+It is possible to 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)
@@ -1739,19 +1709,17 @@
 @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 of the Octave algorithms.  The
-following C++ program, uses class Matrix from @file{liboctave.a} or
-@file{liboctave.so}.
+The libraries Octave uses itself can be utilized in standalone applications.
+These applications then have access, for example, to the array and matrix
+classes, as well as to all of the Octave algorithms.  The following C++
+program, uses class Matrix from @file{liboctave.a} or @file{liboctave.so}.
 
 @example
 @EXAMPLEFILE(standalone.cc)
 @end example
 
 @noindent
-mkoctfile can be used to build a standalone application with a
-command like
+mkoctfile can be used to build a standalone application with a command like
 
 @example
 @group
@@ -1764,13 +1732,12 @@
 @end group
 @end example
 
-Note that the application @code{standalone} 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 built-in 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
+Note that the application @code{standalone} 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 built-in 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
 @EXAMPLEFILE(embedded.cc)
@@ -1788,25 +1755,24 @@
 @end group
 @end example
 
-It is worth noting that, if only built-in functions are to be called from
-a C++ standalone program, then it does not need to initialize the
-interpreter to do so.  The general rule is that, for a built-in
-function named @code{function_name} in the interpreter, there will be
-a C++ function named @code{Ffunction_name} (note the prepended capital
-@code{F}) accessible in the C++ API@.  The declarations for all built-in
-functions are collected in the header file @code{builtin-defun-decls.h}.
-This feature should be used with care as the list of built-in functions can
-change.  No guarantees can be made that a function that is currently built in
-won't be implemented as a .m file or as a dynamically linked function in the
-future.  An example of how to call built-in functions from C++ can be seen in
-the code
+It is worth re-iterating that, if only built-in functions are to be called from
+a C++ standalone program then it does not need to initialize the interpreter.
+The general rule is that for a built-in function named @code{function_name} in
+the interpreter, there will be a C++ function named @code{Ffunction_name} (note
+the prepended capital @code{F}) accessible in the C++ API@.  The declarations
+for all built-in functions are collected in the header file
+@code{builtin-defun-decls.h}.  This feature should be used with care as the
+list of built-in functions can change.  No guarantees can be made that a
+function that is currently a built-in won't be implemented as a .m file or as a
+dynamically linked function in the future.  An example of how to call built-in
+functions from C++ can be seen in the code
 
 @example
 @EXAMPLEFILE(standalonebuiltin.cc)
 @end example
 
 @noindent
-which, again, is compiled and run as a standalone application with
+which is compiled and run as a standalone application with
 
 @example
 @group
@@ -1833,10 +1799,9 @@
 @cindex Octave, calling from Java
 
 The Java Interface is designed for calling Java functions from within Octave.
-If you want to do the reverse, and call Octave from within Java, try
-a library like
-@code{javaOctave} (@url{https://kenai.com/projects/javaoctave/pages/Home}) or
-@code{joPas} (@url{http://jopas.sourceforge.net/}).
+If you want to do the reverse, and call Octave from within Java, try a library
+like @code{javaOctave} (@url{https://kenai.com/projects/javaoctave/pages/Home})
+or @code{joPas} (@url{http://jopas.sourceforge.net/}).
 
 @menu
 * Java Interface Functions::
@@ -1848,9 +1813,9 @@
 @node Java Interface Functions
 @subsection Java Interface Functions
 
-The following functions are the core of the Java Interface.  They provide
-a way to create a Java object, get and set its data fields, and call Java
-methods which return results to Octave.
+The following functions are the core of the Java Interface.  They provide a way
+to create a Java object, get and set its data fields, and call Java methods
+which return results to Octave.
 
 @cindex object, creating a Java object
 @DOCSTRING(javaObject)
@@ -1858,14 +1823,14 @@
 @cindex array, creating a Java array
 @DOCSTRING(javaArray)
 
-There are many different variable types in Octave but only ones created through
-@code{javaObject} can use Java functions.  Before using Java with an unknown
-object the type can be checked with @code{isjava}.
+There are many different variable types in Octave, but only ones created
+through @code{javaObject} can use Java functions.  Before using Java with an
+unknown object the type can be checked with @code{isjava}.
 
 @DOCSTRING(isjava)
 
 Once an object has been created it is natural to find out what fields the
-object has and to read (get) and write (set) them.
+object has, and to read (get) and write (set) them.
 
 @cindex fields, displaying available fields of a Java object
 In Octave the @code{fieldnames} function for structures has been overloaded
@@ -1892,11 +1857,11 @@
 @end example
 
 @cindex field, returning value of Java object field
-The analogy of objects with structures is carried over into reading and
-writing object fields.  To read a field the object is indexed with the
-@samp{.} operator from structures.  This is the preferred method for reading
-fields, but Octave also provides a function interface to read fields with
-@code{java_get}.  An example of both styles is shown below.
+The analogy of objects with structures is carried over into reading and writing
+object fields.  To read a field the object is indexed with the @samp{.}
+operator from structures.  This is the preferred method for reading fields, but
+Octave also provides a function interface to read fields with @code{java_get}.
+An example of both styles is shown below.
 
 @example
 @group
@@ -1914,8 +1879,8 @@
 @DOCSTRING(java_set)
 
 @cindex methods, displaying available methods of a Java object
-To see what functions can be called with an object use @code{methods}.
-For example, using the previously created @var{dobj}:
+To see what functions can be called with an object use @code{methods}.  For
+example, using the previously created @var{dobj}:
 
 @example
 @group
@@ -1929,10 +1894,10 @@
 @end group
 @end example
 
-To call a method of an object the same structure indexing operator @samp{.}
-is used.  Octave also provides a functional interface to calling the methods
-of an object through @code{javaMethod}.  An example showing both styles is
-shown below.
+To call a method of an object the same structure indexing operator @samp{.} is
+used.  Octave also provides a functional interface to calling the methods of an
+object through @code{javaMethod}.  An example showing both styles is shown
+below.
 
 @example
 @group
@@ -1947,10 +1912,9 @@
 @cindex method, invoking a method of a Java object
 @DOCSTRING(javaMethod)
 
-The following three functions are used to display and modify the
-class path used by the Java Virtual Machine.  This is entirely separate
-from Octave's PATH variable and is used by the JVM to find the correct
-code to execute.
+The following three functions are used to display and modify the class path
+used by the Java Virtual Machine.  This is entirely separate from Octave's
+@env{PATH} variable and is used by the JVM to find the correct code to execute.
 
 @cindex classpath, displaying
 @cindex classpath, dynamic
@@ -1999,9 +1963,9 @@
 @cindex classes, making available to Octave
 @c - index -
 
-Java finds classes by searching a @var{classpath}.  This is a list of Java
-archive files and/or directories containing class files.  In Octave
-the @var{classpath} is composed of two parts:
+Java finds classes by searching a @var{classpath} which is a list of Java
+archive files and/or directories containing class files.  In Octave the
+@var{classpath} is composed of two parts:
 
 @itemize
 @item the @var{static classpath} is initialized once at startup of the JVM, and
@@ -2009,46 +1973,49 @@
 @item the @var{dynamic classpath} which can be modified at runtime.
 @end itemize
 
-Octave searches the @var{static classpath} first, then the @var{dynamic
-classpath}.  Classes appearing in the @var{static} as well as in the
-@var{dynamic classpath} will therefore be found in the @var{static classpath}
-and loaded from this location.  Classes which will be used frequently or must
-be available to all users should be added to the @var{static classpath}.  The
-@var{static classpath} is populated once from the contents of a plain text file
-named @file{javaclasspath.txt} (or @file{classpath.txt} historically) when the
-Java Virtual Machine starts.  This file contains one line for each individual
-classpath to be added to the @var{static classpath}.  These lines can identify
-directories containing class files, or Java archives with complete class file
-hierarchies.  Comment lines starting with a @samp{#} or a @samp{%} character
-are ignored.
+Octave searches the @var{static classpath} first, and then the
+@var{dynamic classpath}.  Classes appearing in the @var{static classpath}, as
+well as in the @var{dynamic classpath}, will therefore be found in the
+@var{static classpath} and loaded from this location.  Classes which will be
+used frequently, or must be available to all users, should be added to the
+@var{static classpath}.  The @var{static classpath} is populated once from the
+contents of a plain text file named @file{javaclasspath.txt} (or
+@file{classpath.txt} historically) when the Java Virtual Machine starts.  This
+file contains one line for each individual classpath to be added to the
+@var{static classpath}.  These lines can identify directories containing class
+files, or Java archives with complete class file hierarchies.  Comment lines
+starting with a @samp{#} or a @samp{%} character are ignored.
 
-The search rules for the file @file{javaclasspath.txt}
-(or @file{classpath.txt}) are:
+The search rules for the file @file{javaclasspath.txt} (or
+@file{classpath.txt}) are:
 
 @itemize
-@item First, Octave tries to locate it in the current directory (where Octave
-was started from).  If such a file is found, it is read and defines the initial
+@item
+First, Octave tries to locate it in the current directory (where Octave was
+started from).  If such a file is found, it is read and defines the initial
 @var{static classpath}.  Thus, it is possible to define a static classpath on a
 'per Octave invocation' basis.
 
-@item Next, Octave searches in the user's home directory.  If a file
+@item
+Next, Octave searches in the user's home directory.  If a file
 @file{javaclasspath.txt} exists here, its contents are appended to the static
 classpath (if any).  Thus, it is possible to build an initial static classpath
 on a @nospell{'per user'} basis.
 
-@item Finally, Octave looks for a next occurrence of file
-@file{javaclasspath.txt} in the m-files directory where Octave Java functions
-live.  This is where @file{javaclasspath.m} resides, usually something like
-@file{@w{@env{OCTAVE_HOME}}/share/octave/@w{@env{OCTAVE_VERSION}}/m/java/}.  You can
-find this directory by executing the command
+@item
+Finally, Octave looks for a @file{javaclasspath.txt} in the m-file directory
+where Octave Java functions live.  This is where the function
+@file{javaclasspath.m} resides, usually something like
+@file{@w{@env{OCTAVE_HOME}}/share/octave/@w{@env{OCTAVE_VERSION}}/m/java/}.
+You can find this directory by executing the command
 
 @example
 which javaclasspath
 @end example
 
-If this file exists here, its contents are also appended to the static
-classpath.  Note that the archives and class directories defined in this last
-step will affect all users.
+If this file exists here, its contents are also appended to the
+@var{static classpath}.  Note that the archives and class directories defined
+in this last step will affect all users.
 @end itemize
 
 Classes which are used only by a specific script should be placed in the
@@ -2060,24 +2027,24 @@
 @example
 octave> base_path = "C:/Octave/java_files";
 
-octave> % add two JARchives to the dynamic classpath
+octave> # add two JAR archives to the dynamic classpath
 octave> javaaddpath ([base_path, "/someclasses.jar"]);
 octave> javaaddpath ([base_path, "/moreclasses.jar"]);
 
-octave> % check the dynamic classpath
+octave> # check the dynamic classpath
 octave> p = javaclasspath;
 octave> disp (p@{1@});
 C:/Octave/java_files/someclasses.jar
 octave> disp (p@{2@});
 C:/Octave/java_files/moreclasses.jar
 
-octave> % remove the first element from the classpath
+octave> # remove the first element from the classpath
 octave> javarmpath ([base_path, "/someclasses.jar"]);
 octave> p = javaclasspath;
 octave> disp (p@{1@});
 C:/Octave/java_files/moreclasses.jar
 
-octave> % provoke an error
+octave> # provoke an error
 octave> disp (p@{2@});
 error: A(I): Index exceeds matrix dimension.
 @end example
@@ -2091,7 +2058,7 @@
 
 @example
 @group
-% contents of .octaverc:
+# contents of .octaverc:
 addpath ("~/octave");
 javaaddpath ("~/octave/myclasses.jar");
 @end group
@@ -2120,30 +2087,31 @@
 In order to execute Java code Octave creates a Java Virtual Machine (JVM).
 Such a JVM allocates a fixed amount of initial memory and may expand this pool
 up to a fixed maximum memory limit.  The default values depend on the Java
-version (@pxref{XREFjavamem,,javamem}).  The memory pool is shared by all
-Java objects running in the JVM@.  This strict memory limit is intended mainly
-to avoid that runaway applications inside web browsers or in enterprise servers
+version (@pxref{XREFjavamem,,javamem}).  The memory pool is shared by all Java
+objects running in the JVM@.  This strict memory limit is intended mainly to
+avoid runaway applications inside web browsers or in enterprise servers which
 can consume all memory and crash the system.  When the maximum memory limit is
 hit, Java code will throw exceptions so that applications will fail or behave
 unexpectedly.
 
 You can specify options for the creation of the JVM inside a file named
-@file{java.opts}.  This is a text file where you can enter lines containing
-@option{-X} and @option{-D} options handed to the JVM during initialization.
+@file{java.opts}.  This is a text file where enter you enter lines containing
+@option{-X} and @option{-D} options that are then passed to the JVM during
+initialization.
 
 The directory where the Java options file is located is specified by the
 environment variable @w{@env{OCTAVE_JAVA_DIR}}.  If unset the directory where
 @file{javaclasspath.m} resides is used instead (typically
-@file{@w{@env{OCTAVE_HOME}}/share/octave/@w{@env{OCTAVE_VERSION}}/m/java/}).  You can
-find this directory by executing
+@file{@w{@env{OCTAVE_HOME}}/share/octave/@w{@env{OCTAVE_VERSION}}/m/java/}).
+You can find this directory by executing
 
 @example
 which javaclasspath
 @end example
 
 The @option{-X} options allow you to increase the maximum amount of memory
-available to the JVM@.  The following example allows up to 256 Megabytes to
-be used by adding the following line to the @file{java.opts} file:
+available to the JVM@.  The following example allows up to 256 Megabytes to be
+used by adding the following line to the @file{java.opts} file:
 
 @example
 -Xmx256m
@@ -2188,4 +2156,3 @@
 
 @seealso{javamem}
 
-

--- a/doc/interpreter/octave.texi	Wed Dec 28 13:58:01 2016 -0800
+++ b/doc/interpreter/octave.texi	Wed Dec 28 17:49:02 2016 -0500
@@ -857,7 +857,7 @@
 * 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::
+* Documentation and Testing of Oct-Files::
 
 Sparse Matrices in Oct-Files