--- a/doc/interpreter/intro.txi	Tue Nov 29 16:46:35 2016 -0800
+++ b/doc/interpreter/intro.txi	Thu Dec 01 04:42:28 2016 -0800
@@ -20,15 +20,17 @@
 @chapter A Brief Introduction to Octave
 @cindex introduction
 
-GNU Octave is a high-level language, primarily intended for numerical
+GNU Octave is a high-level language primarily intended for numerical
 computations.  It is typically used for such problems as solving
 linear and nonlinear equations, numerical linear algebra, statistical
 analysis, and for performing other numerical experiments.  It may also
 be used as a batch-oriented language for automated data processing.
 
-Until recently GNU Octave provided a command-line interface only with
-graphical plots displayed in separate windows.  However, by default
-the current version runs with a graphical user interface.
+The current version of Octave executes in a graphical user interface
+(GUI).  The GUI hosts an Integrated Development Environment (IDE)
+which includes a code editor with syntax highlighting, built-in
+debugger, documentation browser, as well as the interpreter for the
+language itself.  A command-line interface for Octave is also available.
 
 GNU Octave is freely redistributable software.  You may redistribute
 it and/or modify it under the terms of the GNU General Public License
@@ -51,12 +53,13 @@
 @section Running Octave
 
 On most systems, Octave is started with the shell command @samp{octave}.
-This starts the graphical user interface (GUI).  The central window in
-the GUI is the Octave command-line interface.  In this window Octave
-displays an initial message and then a prompt indicating it is ready to
-accept input.  If you have chosen the traditional command-line interface
-then only the command prompt appears in the same window that was running
-a shell.  In any case, you can immediately begin typing Octave commands.
+This starts the graphical user interface.  The central window in the GUI
+is the Octave command-line interface.  In this window Octave displays an
+initial message and then a prompt indicating it is ready to accept
+input.  If you have chosen the traditional command-line interface then
+only the command prompt appears in the same window that was running
+a shell.  In either case, you can immediately begin typing Octave
+commands.
 
 If you get into trouble, you can usually interrupt Octave by typing
 @kbd{Control-C} (written @kbd{C-c} for short).  @kbd{C-c} gets
@@ -79,9 +82,9 @@
 capabilities.
 
 If you are new to Octave, we recommend that you try these examples to
-begin learning Octave by using it.  Lines marked like so, @samp{octave:13>},
-are lines you type, ending each with a carriage return.  Octave will
-respond with an answer, or by displaying a graph.
+begin learning Octave by using it.  Lines marked like so,
+@samp{octave:13>}, are lines you type, ending each with a carriage
+return.  Octave will respond with an answer, or by displaying a graph.
 
 @subsection Elementary Calculations
 
@@ -116,9 +119,9 @@
 
 @subsection Creating a Matrix
 
-Vectors and matrices are the basic building blocks for numerical analysis.
-To create a new matrix and store it in a variable so that you can
-refer to it later, type the command
+Vectors and matrices are the basic building blocks for numerical
+analysis.  To create a new matrix and store it in a variable so that you
+can refer to it later, type the command
 
 @example
 octave:1> A = [ 1, 1, 2; 3, 5, 8; 13, 21, 34 ]
@@ -149,9 +152,10 @@
 
 @subsection Matrix Arithmetic
 
-Octave has a convenient operator notation for performing matrix
-arithmetic.  For example, to multiply the matrix @code{A} by a scalar
-value, type the command
+Octave uses standard mathematical notation with the advantage over
+low-level languages that operators may act on scalars, vector, matrices,
+or N-dimensional arrays.  For example, to multiply the matrix @code{A}
+by a scalar value, type the command
 
 @example
 octave:4> 2 * A
@@ -348,8 +352,7 @@
 @end example
 
 @noindent
-If you are using a graphical user interface, Octave will automatically create
-a separate window to display the plot.
+Octave will automatically create a separate window to display the plot.
 
 To save a plot once it has been displayed on the screen, use the print
 command.  For example,
@@ -370,20 +373,6 @@
 explains more options for the @code{print} command and provides a list
 of additional output file formats.
 
-@subsection Editing What You Have Typed
-
-At the Octave prompt, you can recall, edit, and reissue previous
-commands using Emacs- or vi-style editing commands.  The default
-keybindings use Emacs-style commands.  For example, to recall the
-previous command, press @kbd{Control-p} (written @kbd{C-p} for
-short).  Doing this will normally bring back the previous line of input.
-@kbd{C-n} will bring up the next line of input, @kbd{C-b} will move
-the cursor backward on the line, @kbd{C-f} will move the cursor forward
-on the line, etc.
-
-A complete description of the command line editing capability is given
-in this manual, @pxref{Command Line Editing}.
-
 @subsection Help and Documentation
 
 Octave has an extensive help facility.  The same documentation that is
@@ -420,6 +409,20 @@
 driven program that contains the entire Octave manual.  Help for using
 Info is provided in this manual, @pxref{Getting Help}.
 
+@subsection Editing What You Have Typed
+
+At the Octave prompt, you can recall, edit, and reissue previous
+commands using Emacs- or vi-style editing commands.  The default
+keybindings use Emacs-style commands.  For example, to recall the
+previous command, press @kbd{Control-p} (written @kbd{C-p} for
+short).  Doing this will normally bring back the previous line of input.
+@kbd{C-n} will bring up the next line of input, @kbd{C-b} will move
+the cursor backward on the line, @kbd{C-f} will move the cursor forward
+on the line, etc.
+
+A complete description of the command line editing capability is given
+in this manual, @pxref{Command Line Editing}.
+
 @node Conventions
 @section Conventions
 
@@ -438,12 +441,12 @@
 @subsection Fonts
 @cindex documentation fonts
 
-Examples of Octave code appear in this font or form: @code{svd (a)}.
-Names that represent variables or function arguments appear
-in this font or form: @var{first-number}.  Commands that you type at the
-shell prompt appear in this font or form: @samp{octave --no-init-file}.
-Commands that you type at the Octave prompt sometimes appear in this font
-or form: @kbd{foo --bar --baz}.  Specific keys on your keyboard appear
+Examples of Octave code appear in this font or form: @w{@code{svd (a)}}.
+Names that represent variables or function arguments appear in this font
+or form: @var{first-number}.  Commands that you type at the shell prompt
+appear in this font or form: @w{@samp{octave --no-init-file}}.  Commands
+that you type at the Octave prompt sometimes appear in this font or
+form: @w{@kbd{foo --bar --baz}}.  Specific keys on your keyboard appear
 in this font or form: @key{RET}.
 
 @node Evaluation Notation
@@ -489,9 +492,9 @@
 @noindent
 in order to clearly show the structure of the result.
 
-Sometimes to help describe one expression, another expression is
-shown that produces identical results.  The exact equivalence of
-expressions is indicated with @samp{@equiv{}}.  For example:
+Sometimes to help describe one expression, another expression is shown
+that produces identical results.  The exact equivalence of expressions
+is indicated with @samp{@equiv{}}.  For example:
 
 @example
 @group
@@ -507,11 +510,11 @@
 @subsection Printing Notation
 @cindex printing notation
 
-Many of the examples in this manual print text when they are
-evaluated.  In this manual the printed text resulting from an example
-is indicated by @samp{@print{}}.  The value that is returned by
-evaluating the expression is displayed with @samp{@result{}}
-(@code{1} in the next example) and follows on a separate line.
+Many of the examples in this manual print text when they are evaluated.
+In this manual the printed text resulting from an example is indicated
+by @samp{@print{}}.  The value that is returned by evaluating the
+expression is displayed with @samp{@result{}} (@code{1} in the next
+example) and follows on a separate line.
 
 @example
 @group
@@ -540,11 +543,10 @@
 @subsection Format of Descriptions
 @cindex description format
 
-Functions and commands are described in this manual in a
-uniform format.  The first line of a description contains the name of
-the item followed by its arguments, if any.
-If there are multiple ways to invoke the function then each allowable
-form is listed.
+Functions and commands are described in this manual in a uniform format.
+The first line of a description contains the name of the item followed
+by its arguments, if any.  If there are multiple ways to invoke the
+function then each allowable form is listed.
 
 The description follows on succeeding lines, sometimes with examples.
 
@@ -575,10 +577,12 @@
 @deftypefn  {} {} foo (@var{x})
 @deftypefnx {} {} foo (@var{x}, @var{y})
 @deftypefnx {} {} foo (@var{x}, @var{y}, @dots{})
-The function @code{foo} subtracts @var{x} from @var{y}, then adds the
-remaining arguments to the result.
+Subtract @var{x} from @var{y}, then add any remaining arguments to the
+result.
 
-If @var{y} is not supplied, then the number 19 is used by default.
+The input @var{x} must be a numeric scalar, vector, or array.
+
+The optional input @var{y} defaults to 19 if it is not supplied.
 
 Example:
 
@@ -612,35 +616,6 @@
 features common to parameters of several functions are described at the
 beginning.
 
-Functions in Octave may be defined in several different ways:
-
-@table @asis
-@item Function File
-@cindex function file
-The function described is defined using Octave commands stored in a text
-file.  @xref{Function Files}.
-
-@item Built-in Function
-@cindex built-in function
-The function described is written in a language like C++, C, or Fortran,
-and is part of the compiled Octave binary.
-
-@item Loadable Function
-@cindex loadable function
-The function described is written in a language like C++, C, or Fortran.
-On systems that support dynamic linking of user-supplied functions, it
-may be automatically linked while Octave is running, but only if it is
-needed.  @xref{External Code Interface}.
-
-@item Mapping Function
-@cindex mapping function
-The function described works element-by-element for matrix and vector
-arguments.
-@end table
-
-Use @code{which} or @code{exist} to determine the category of a function
-and where it resides.
-
 @node A Sample Command Description
 @subsubsection A Sample Command Description
 @cindex command descriptions
@@ -673,5 +648,6 @@
 @end table
 
 With no arguments, @code{diary} toggles the current diary state.
-@seealso{history}
+@seealso{history, evalc}
 @end deftypefn
+

--- a/libinterp/corefcn/data.cc	Tue Nov 29 16:46:35 2016 -0800
+++ b/libinterp/corefcn/data.cc	Thu Dec 01 04:42:28 2016 -0800
@@ -2639,7 +2639,7 @@
 
 @example
 @group
-[nr, remainder] = size (ones (2, 3, 4, 5)
+[nr, remainder] = size (ones (2, 3, 4, 5))
     @result{} nr = 2
     @result{} remainder = 60
 @end group

--- a/libinterp/corefcn/sub2ind.cc	Tue Nov 29 16:46:35 2016 -0800
+++ b/libinterp/corefcn/sub2ind.cc	Thu Dec 01 04:42:28 2016 -0800
@@ -64,11 +64,20 @@
 @deftypefnx {} {@var{ind} =} sub2ind (@var{dims}, @var{s1}, @var{s2}, @dots{}, @var{sN})
 Convert subscripts to linear indices.
 
-Assume the following 3-by-3 matrices.  The left matrix contains the
-subscript tuples for each matrix element.  Those are converted to
-linear indices shown in the right matrix.  The matrices are linearly
-indexed moving from one column to next, filling up all rows in each
-column.
+The input @var{dims} is a dimension vector where each element is the size of
+the array in the respective dimension (@pxref{XREFsize,,size}).  The remaining
+inputs are scalars or vectors of subscripts to be converted.
+
+The output vector @var{ind} contains the converted linear indices.
+
+Background: Array elements can be specified either by a linear index which
+starts at 1 and runs through the number of elements in the array, or they may
+be specified with subscripts for the row, column, page, etc.  The functions
+@code{ind2sub} and @code{sub2ind} interconvert between the two forms.
+
+The linear index traverses dimension 1 (rows), then dimension 2 (columns), then
+dimension 3 (pages), etc. until it has numbered all of the elements.  Consider
+the following 3-by-3 matrices:
 
 @example
 @group
@@ -78,18 +87,23 @@
 @end group
 @end example
 
+@noindent
+The left matrix contains the subscript tuples for each matrix element.  The
+right matrix shows the linear indices for the same matrix.
+
 The following example shows how to convert the two-dimensional indices
-@code{(2,1)} and @code{(2,3)} of a 3-by-3 matrix to a linear index.
+@code{(2,1)} and @code{(2,3)} of a 3-by-3 matrix to linear indices with a
+single call to @code{sub2ind}.
 
 @example
 @group
 s1 = [2, 2];
 s2 = [1, 3];
 ind = sub2ind ([3, 3], s1, s2)
-@result{} ind =  2   8
+    @result{} ind =  2   8
 @end group
 @end example
-@seealso{ind2sub}
+@seealso{ind2sub, size}
 @end deftypefn */)
 {
   int nargin = args.length ();
@@ -174,11 +188,20 @@
 @deftypefn {} {[@var{s1}, @var{s2}, @dots{}, @var{sN}] =} ind2sub (@var{dims}, @var{ind})
 Convert linear indices to subscripts.
 
-Assume the following 3-by-3 matrices.  The left matrix contains
-the linear indices @var{ind} for each matrix element.  Those are
-converted to subscript tuples shown in the right matrix.  The
-matrices are linearly indexed moving from one column to next,
-filling up all rows in each column.
+The input @var{dims} is a dimension vector where each element is the size of
+the array in the respective dimension (@pxref{XREFsize,,size}).  The second
+input @var{ind} contains linear indies to be converted.
+
+The outputs @var{s1}, @dots{}, @var{sN} contain the converted subscripts.
+
+Background: Array elements can be specified either by a linear index which
+starts at 1 and runs through the number of elements in the array, or they may
+be specified with subscripts for the row, column, page, etc.  The functions
+@code{ind2sub} and @code{sub2ind} interconvert between the two forms.
+
+The linear index traverses dimension 1 (rows), then dimension 2 (columns), then
+dimension 3 (pages), etc. until it has numbered all of the elements.  Consider
+the following 3-by-3 matrices:
 
 @example
 @group
@@ -188,8 +211,16 @@
 @end group
 @end example
 
-The following example shows how to convert the linear indices
-@code{2} and @code{8} in a 3-by-3 matrix into a subscripts.
+@noindent
+The left matrix contains the linear indices for each matrix element.  The right
+matrix shows the subscript tuples for the same matrix.
+
+The following example shows how to convert the two-dimensional indices
+@code{(2,1)} and @code{(2,3)} of a 3-by-3 matrix to linear indices with a
+single call to @code{sub2ind}.
+
+The following example shows how to convert the linear indices @code{2} and
+@code{8} in a 3-by-3 matrix into subscripts.
 
 @example
 @group
@@ -200,26 +231,27 @@
 @end group
 @end example
 
-If the number of subscripts exceeds the number of dimensions, the
-exceeded dimensions are treated as @code{1}.  On the other hand,
-if less subscripts than dimensions are provided, the exceeding
-dimensions are merged.  For clarity see the following examples:
+If the number of output subscripts exceeds the number of dimensions, the
+exceeded dimensions are set to @code{1}.  On the other hand, if fewer
+subscripts than dimensions are provided, the exceeding dimensions are merged
+into the final requested dimension.  For clarity, consider the following
+examples:
 
-@example
+@example%
 @group
-ind = [2, 8];
+ind  = [2, 8];
 dims = [3, 3];
-% same as dims = [3, 3, 1]
+## same as dims = [3, 3, 1]
 [r, c, s] = ind2sub (dims, ind)
     @result{} r =  2   2
     @result{} c =  1   3
     @result{} s =  1   1
-% same as dims = 9
+## same as dims = [9]
 r = ind2sub (dims, ind)
     @result{} r =  2   8
 @end group
 @end example
-@seealso{sub2ind}
+@seealso{ind2sub, size}
 @end deftypefn */)
 {
   if (args.length () != 2)

--- a/libinterp/octave-value/ov-usr-fcn.cc	Tue Nov 29 16:46:35 2016 -0800
+++ b/libinterp/octave-value/ov-usr-fcn.cc	Thu Dec 01 04:42:28 2016 -0800
@@ -915,7 +915,7 @@
 In the second usage,
 
 @example
-nargout (@@histc) \% or nargout ("histc")
+nargout (@@histc)   # or nargout ("histc") using a string input
 @end example
 
 @noindent

--- a/scripts/miscellaneous/open.m	Tue Nov 29 16:46:35 2016 -0800
+++ b/scripts/miscellaneous/open.m	Thu Dec 01 04:42:28 2016 -0800
@@ -17,7 +17,7 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {} {@var{output} =} open @var{file}
+## @deftypefn  {} {} open @var{file}
 ## @deftypefnx {} {@var{output} =} open (@var{file})
 ## Open the file @var{file} in Octave or in an external application based on
 ## the file type as determined by the filename extension.

--- a/scripts/prefs/setpref.m	Tue Nov 29 16:46:35 2016 -0800
+++ b/scripts/prefs/setpref.m	Thu Dec 01 04:42:28 2016 -0800
@@ -18,7 +18,7 @@
 
 ## -*- texinfo -*-
 ## @deftypefn  {} {} setpref ("@var{group}", "@var{pref}", @var{val})
-## @deftypefnx {} {} addpref ("@var{group}", @{"@var{pref1}", "@var{pref2}", @dots{}@}, @{@var{val1}, @var{val2}, @dots{}@})
+## @deftypefnx {} {} setpref ("@var{group}", @{"@var{pref1}", "@var{pref2}", @dots{}@}, @{@var{val1}, @var{val2}, @dots{}@})
 ## Set the preference @var{pref} to the given @var{val} in the named preference
 ## group @var{group}.
 ##