changeset 17128:eaab03308c0b

doc: Rewrite docstrings for most plot functions. Emphasize clarity, use common "voice", and increase density of seealso links. * doc/interpreter/plot.txi: Add @findex entries that were in xlim.m * scripts/miscellaneous/getappdata.m scripts/miscellaneous/setappdata.m, scripts/plot/allchild.m, scripts/plot/ancestor.m, scripts/plot/area.m, scripts/plot/axes.m, scripts/plot/axis.m, scripts/plot/bar.m, scripts/plot/barh.m, scripts/plot/box.m, scripts/plot/caxis.m, scripts/plot/cla.m, scripts/plot/clabel.m, scripts/plot/clf.m, scripts/plot/close.m, scripts/plot/closereq.m, scripts/plot/colorbar.m, scripts/plot/comet.m, scripts/plot/comet3.m, scripts/plot/compass.m, scripts/plot/contour.m, scripts/plot/contour3.m, scripts/plot/contourc.m, scripts/plot/contourf.m, scripts/plot/copyobj.m, scripts/plot/cylinder.m, scripts/plot/daspect.m, scripts/plot/diffuse.m, scripts/plot/ellipsoid.m, scripts/plot/errorbar.m, scripts/plot/ezcontour.m, scripts/plot/ezcontourf.m, scripts/plot/ezmesh.m, scripts/plot/ezmeshc.m, scripts/plot/ezplot.m, scripts/plot/ezplot3.m, scripts/plot/ezpolar.m, scripts/plot/ezsurf.m, scripts/plot/ezsurfc.m, scripts/plot/feather.m, scripts/plot/figure.m, scripts/plot/fill.m, scripts/plot/findall.m, scripts/plot/findobj.m, scripts/plot/fplot.m, scripts/plot/gca.m, scripts/plot/gcbf.m, scripts/plot/gcbo.m, scripts/plot/gcf.m, scripts/plot/gco.m, scripts/plot/ginput.m, scripts/plot/graphics_toolkit.m, scripts/plot/grid.m, scripts/plot/gtext.m, scripts/plot/guidata.m, scripts/plot/guihandles.m, scripts/plot/hdl2struct.m, scripts/plot/hggroup.m, scripts/plot/hidden.m, scripts/plot/hist.m, scripts/plot/hold.m, scripts/plot/ishghandle.m, scripts/plot/ishold.m, scripts/plot/isocolors.m, scripts/plot/isprop.m, scripts/plot/legend.m, scripts/plot/line.m, scripts/plot/linkprop.m, scripts/plot/loglog.m, scripts/plot/loglogerr.m, scripts/plot/mesh.m, scripts/plot/meshc.m, scripts/plot/meshgrid.m, scripts/plot/meshz.m, scripts/plot/newplot.m, scripts/plot/orient.m, scripts/plot/pareto.m, scripts/plot/patch.m, scripts/plot/pcolor.m, scripts/plot/peaks.m, scripts/plot/pie.m, scripts/plot/pie3.m, scripts/plot/plot.m, scripts/plot/plot3.m, scripts/plot/plotmatrix.m, scripts/plot/plotyy.m, scripts/plot/polar.m, scripts/plot/print.m, scripts/plot/quiver.m, scripts/plot/quiver3.m, scripts/plot/rectangle.m, scripts/plot/refresh.m, scripts/plot/refreshdata.m, scripts/plot/ribbon.m, scripts/plot/rose.m, scripts/plot/saveas.m, scripts/plot/scatter.m, scripts/plot/scatter3.m, scripts/plot/semilogx.m, scripts/plot/semilogxerr.m, scripts/plot/semilogy.m, scripts/plot/semilogyerr.m, scripts/plot/shading.m, scripts/plot/shg.m, scripts/plot/shrinkfaces.m, scripts/plot/slice.m, scripts/plot/specular.m, scripts/plot/sphere.m, scripts/plot/stairs.m, scripts/plot/stem.m, scripts/plot/stem3.m, scripts/plot/struct2hdl.m, scripts/plot/subplot.m, scripts/plot/surf.m, scripts/plot/surface.m, scripts/plot/surfc.m, scripts/plot/surfl.m, scripts/plot/tetramesh.m, scripts/plot/text.m, scripts/plot/title.m, scripts/plot/trimesh.m, scripts/plot/triplot.m, scripts/plot/trisurf.m, scripts/plot/view.m, scripts/plot/waitbar.m, scripts/plot/waitforbuttonpress.m, scripts/plot/waterfall.m, scripts/plot/whitebg.m, scripts/plot/xlabel.m, scripts/plot/xlim.m, scripts/plot/ylabel.m, scripts/plot/ylim.m, scripts/plot/zlabel.m, scripts/plot/zlim.m: Rewrite docstrings for most plot functions. Emphasize clarity, use common "voice", and increase density of seealso links.
author Rik <rik@octave.org>
date Wed, 31 Jul 2013 13:53:30 -0700
parents d4549655b92e
children bcada0a4f8a7
files doc/interpreter/plot.txi scripts/miscellaneous/getappdata.m scripts/miscellaneous/setappdata.m scripts/plot/allchild.m scripts/plot/ancestor.m scripts/plot/area.m scripts/plot/axes.m scripts/plot/axis.m scripts/plot/bar.m scripts/plot/barh.m scripts/plot/box.m scripts/plot/caxis.m scripts/plot/cla.m scripts/plot/clabel.m scripts/plot/clf.m scripts/plot/close.m scripts/plot/closereq.m scripts/plot/colorbar.m scripts/plot/comet.m scripts/plot/comet3.m scripts/plot/compass.m scripts/plot/contour.m scripts/plot/contour3.m scripts/plot/contourc.m scripts/plot/contourf.m scripts/plot/copyobj.m scripts/plot/cylinder.m scripts/plot/daspect.m scripts/plot/diffuse.m scripts/plot/ellipsoid.m scripts/plot/errorbar.m scripts/plot/ezcontour.m scripts/plot/ezcontourf.m scripts/plot/ezmesh.m scripts/plot/ezmeshc.m scripts/plot/ezplot.m scripts/plot/ezplot3.m scripts/plot/ezpolar.m scripts/plot/ezsurf.m scripts/plot/ezsurfc.m scripts/plot/feather.m scripts/plot/figure.m scripts/plot/fill.m scripts/plot/findall.m scripts/plot/findobj.m scripts/plot/fplot.m scripts/plot/gca.m scripts/plot/gcbf.m scripts/plot/gcbo.m scripts/plot/gcf.m scripts/plot/gco.m scripts/plot/ginput.m scripts/plot/graphics_toolkit.m scripts/plot/grid.m scripts/plot/gtext.m scripts/plot/guidata.m scripts/plot/guihandles.m scripts/plot/hdl2struct.m scripts/plot/hggroup.m scripts/plot/hidden.m scripts/plot/hist.m scripts/plot/hold.m scripts/plot/ishghandle.m scripts/plot/ishold.m scripts/plot/isocolors.m scripts/plot/isprop.m scripts/plot/legend.m scripts/plot/line.m scripts/plot/linkprop.m scripts/plot/loglog.m scripts/plot/loglogerr.m scripts/plot/mesh.m scripts/plot/meshc.m scripts/plot/meshgrid.m scripts/plot/meshz.m scripts/plot/newplot.m scripts/plot/orient.m scripts/plot/pareto.m scripts/plot/patch.m scripts/plot/pcolor.m scripts/plot/peaks.m scripts/plot/pie.m scripts/plot/pie3.m scripts/plot/plot.m scripts/plot/plot3.m scripts/plot/plotmatrix.m scripts/plot/plotyy.m scripts/plot/polar.m scripts/plot/print.m scripts/plot/quiver.m scripts/plot/quiver3.m scripts/plot/rectangle.m scripts/plot/refresh.m scripts/plot/refreshdata.m scripts/plot/ribbon.m scripts/plot/rose.m scripts/plot/saveas.m scripts/plot/scatter.m scripts/plot/scatter3.m scripts/plot/semilogx.m scripts/plot/semilogxerr.m scripts/plot/semilogy.m scripts/plot/semilogyerr.m scripts/plot/shading.m scripts/plot/shg.m scripts/plot/shrinkfaces.m scripts/plot/slice.m scripts/plot/specular.m scripts/plot/sphere.m scripts/plot/stairs.m scripts/plot/stem.m scripts/plot/stem3.m scripts/plot/struct2hdl.m scripts/plot/subplot.m scripts/plot/surf.m scripts/plot/surface.m scripts/plot/surfc.m scripts/plot/surfl.m scripts/plot/tetramesh.m scripts/plot/text.m scripts/plot/title.m scripts/plot/trimesh.m scripts/plot/triplot.m scripts/plot/trisurf.m scripts/plot/view.m scripts/plot/waitbar.m scripts/plot/waitforbuttonpress.m scripts/plot/waterfall.m scripts/plot/whitebg.m scripts/plot/xlabel.m scripts/plot/xlim.m scripts/plot/ylabel.m scripts/plot/ylim.m scripts/plot/zlabel.m scripts/plot/zlim.m
diffstat 135 files changed, 1404 insertions(+), 905 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/plot.txi
+++ b/doc/interpreter/plot.txi
@@ -252,8 +252,11 @@
 The @code{xlim}, @code{ylim}, and @code{zlim} functions may be used to
 get or set individual axis limits.  Each has the same form.
 
+@c Add cross-references and function index entries for other limit functions.
 @anchor{XREFylim}
 @anchor{XREFzlim}
+@findex ylim
+@findex zlim
 @DOCSTRING(xlim)
 
 @node Two-dimensional Function Plotting
--- a/scripts/miscellaneous/getappdata.m
+++ b/scripts/miscellaneous/getappdata.m
@@ -23,6 +23,8 @@
 ## 
 ## @code{getappdata(@var{h})} returns a structure, @var{appdata}, whose fields
 ## correspond to the appdata properties.
+##
+## @seealso{setappdata, guidata, get, set, getpref, setpref}
 ## @end deftypefn
 
 ## Author: Ben Abbott <bpabbott@mac.com>
--- a/scripts/miscellaneous/setappdata.m
+++ b/scripts/miscellaneous/setappdata.m
@@ -19,6 +19,7 @@
 ## Set the named application data to @var{value} for the object(s) with
 ## handle(s) @var{h}.  If the application data with the specified name does
 ## not exist, it is created.
+## @seealso{getappdata, guidata, get, set, getpref, setpref}
 ## @end deftypefn
 
 ## Author: Ben Abbott <bpabbott@mac.com>
--- a/scripts/plot/allchild.m
+++ b/scripts/plot/allchild.m
@@ -25,7 +25,7 @@
 ## @var{h} will be a vector.  Otherwise, @var{h} will be a cell matrix
 ## of the same size as @var{handles} and each cell will contain a
 ## vector of handles.
-## @seealso{get, set, findall, findobj}
+## @seealso{findall, findobj, get, set}
 ## @end deftypefn
 
 ## Author: Bill Denney <bill@denney.ws>
--- a/scripts/plot/ancestor.m
+++ b/scripts/plot/ancestor.m
@@ -24,7 +24,7 @@
 ## cell array of strings, return the first parent whose type matches
 ## any of the given type strings.
 ##
-## If the handle object @var{h} is of type @var{type}, return @var{h}.
+## If the handle object @var{h} itself is of type @var{type}, return @var{h}.
 ##
 ## If @code{"toplevel"} is given as a third argument, return the highest
 ## parent in the object hierarchy that matches the condition, instead
--- a/scripts/plot/area.m
+++ b/scripts/plot/area.m
@@ -24,24 +24,24 @@
 ## @deftypefnx {Function File} {} area (@dots{}, @var{prop}, @var{val}, @dots{})
 ## @deftypefnx {Function File} {} area (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} area (@dots{})
-## Area plot of the columns of @var{y}.  This shows the
-## contributions of each column value to the row sum.  It is functionally
-## similar to @code{plot (@var{x}, cumsum (@var{y}, 2))}, except that the
-## area under the curve is shaded.
+## Area plot of the columns of @var{y}.
+##
+## This plot shows the contributions of each column value to the row sum.  It
+## is functionally similar to @code{plot (@var{x}, cumsum (@var{y}, 2))},
+## except that the area under the curve is shaded.
 ##
-## If the @var{x} argument is omitted it defaults to 
-## @code{1 : rows (@var{y})}.  A value @var{lvl} can be defined that determines
-## where the base level of the shading under the curve should be defined.  The
-## default level is 0.
+## If the @var{x} argument is omitted it defaults to @code{1:rows (@var{y})}.
+## A value @var{lvl} can be defined that determines where the base level of
+## the shading under the curve should be defined.  The default level is 0.
 ##
-## Additional arguments to the @code{area} function are passed directly to
-## @code{patch}.  
+## Additional property/value pairs are passed directly to the underlying patch
+## object.
 ##
-## If the first argument is an axis handle @var{hax}, then plot into these axes,
-## rather than the current axis handle returned by @code{gca}.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a graphics handle to the hggroup
-## object representing the area patch objects.  The "BaseValue" property
+## object comprising the area patch objects.  The "BaseValue" property
 ## of the hggroup can be used to adjust the level where shading begins.
 ##
 ## Example: Verify identity sin^2 + cos^2 = 1
@@ -51,7 +51,7 @@
 ## t = linspace (0, 2*pi, 100)';
 ## y = [sin(t).^2, cos(t).^2)];
 ## area (t, y);
-## legend ('sin^2', 'cos^2', 'location', 'NorthEastOutside');  
+## legend ("sin^2", "cos^2", "location", "NorthEastOutside");  
 ## @end group
 ## @end example
 ## @seealso{plot, patch}
--- a/scripts/plot/axes.m
+++ b/scripts/plot/axes.m
@@ -19,19 +19,19 @@
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} axes ()
 ## @deftypefnx {Function File} {} axes (@var{property}, @var{value}, @dots{})
-## @deftypefnx {Function File} {} axes (@var{h})
+## @deftypefnx {Function File} {} axes (@var{hax})
 ## @deftypefnx {Function File} {@var{h} =} axes (@dots{})
 ## Create an axes object and return a handle to it, or set the current
-## axes to @var{h}.
+## axes to @var{hax}.
 ##
 ## Called without any arguments, or with @var{property}/@var{value} pairs,
-## contruct a new axes.  For accepted properties and corresponding
-## values, see @code{set} function.
+## construct a new axes.  For accepted properties and corresponding
+## values, @pxref{XREFset,,set}.
 ##
-## Called with a single axes handle argument @var{h}, the function makes
-## @var{h} the current axis.  It also restacks the axes in the
-## corresponding figure so that @var{h} is the first entry in the list
-## of children.  This causes @var{h} to be displayed on top of any other
+## Called with a single axes handle argument @var{hax}, the function makes
+## @var{hax} the current axis.  It also restacks the axes in the
+## corresponding figure so that @var{hax} is the first entry in the list
+## of children.  This causes @var{hax} to be displayed on top of any other
 ## axes objects (Z-order stacking).
 ## 
 ## @seealso {gca, set, get}
--- a/scripts/plot/axis.m
+++ b/scripts/plot/axis.m
@@ -23,9 +23,9 @@
 ## @deftypefnx {Function File} {} axis ([@var{x}_lo @var{x}_hi @var{y}_lo @var{y}_hi @var{z}_lo @var{z}_hi])
 ## @deftypefnx {Function File} {} axis (@var{option})
 ## @deftypefnx {Function File} {} axis (@dots{}, @var{option})
-## @deftypefnx {Function File} {} axis (@var{h}, @dots{})
+## @deftypefnx {Function File} {} axis (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{limits} =} axis ()
-## Set axis limits for plots.
+## Set axis limits and appearance.
 ##
 ## The argument @var{limits} should be a 2-, 4-, or 6-element vector.  The
 ## first and second elements specify the lower and upper limits for the
@@ -34,7 +34,8 @@
 ##
 ## Without any arguments, @code{axis} turns autoscaling on.
 ##
-## With one output argument, @code{x = axis} returns the current axes.
+## With one output argument, @code{@var{limits} = axis} returns the current
+## axis limits.
 ##
 ## The vector argument specifying limits is optional, and additional
 ## string arguments may be used to specify various axis properties.  For
@@ -66,7 +67,7 @@
 ## Force x distance to equal y-distance.
 ##
 ## @item "normal"
-## Restore the balance.
+## Restore default aspect ratio.
 ## @end table
 ##
 ## @noindent
@@ -82,13 +83,12 @@
 ##
 ## @item "tight"
 ## Fix axes to the limits of the data.
+##
+## @item "image"
+## Equivalent to "tight" and "equal".
 ## @end table
 ##
 ## @noindent
-## The option @code{"image"} is equivalent to @code{"tight"} and
-## @code{"equal"}.
-##
-## @noindent
 ## The following options affect the appearance of tic marks.
 ##
 ## @table @asis
@@ -113,8 +113,7 @@
 ## Note, if there are no tic marks for an axis, there can be no labels.
 ##
 ## @noindent
-## The following options affect the direction of increasing values on
-## the axes.
+## The following options affect the direction of increasing values on the axes.
 ##
 ## @table @asis
 ## @item "ij"
@@ -124,8 +123,10 @@
 ## Restore y-axis, so higher values are nearer the top.
 ## @end table
 ##
-## If an axes handle is passed as the first argument, then operate on
-## this axes rather than the current axes.
+## If the first argument @var{hax} is an axes handle, then operate on
+## this axes rather than the current axes returned by @code{gca}.
+##
+## @seealso{xlim, ylim, zlim, daspect, pbaspect, box, grid}
 ## @end deftypefn
 
 ## Author: jwe
--- a/scripts/plot/bar.m
+++ b/scripts/plot/bar.m
@@ -17,18 +17,21 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {} bar (@var{x}, @var{y})
-## @deftypefnx {Function File} {} bar (@var{y})
-## @deftypefnx {Function File} {} bar (@var{x}, @var{y}, @var{w})
-## @deftypefnx {Function File} {} bar (@var{x}, @var{y}, @var{w}, @var{style})
-## @deftypefnx {Function File} {} bar (@var{h}, @dots{})
-## @deftypefnx {Function File} {@var{h} =} bar (@dots{}, @var{prop}, @var{val})
-## Produce a bar graph from two vectors of x-y data.
+## @deftypefn  {Function File} {} bar (@var{y})
+## @deftypefnx {Function File} {} bar (@var{x}, @var{y})
+## @deftypefnx {Function File} {} bar (@dots{}, @var{w})
+## @deftypefnx {Function File} {} bar (@dots{}, @var{style})
+## @deftypefnx {Function File} {} bar (@dots{}, @var{prop}, @var{val}, @dots{})
+## @deftypefnx {Function File} {} bar (@var{hax}, @dots{})
+## @deftypefnx {Function File} {@var{h} =} bar (@dots{}, @var{prop}, @var{val}, @dots{})
+## Produce a bar graph from two vectors of X-Y data.
 ##
-## If only one argument is given, @var{y}, it is taken as a vector of y-values
-## and the x coordinates are taken to be the indices of the elements.
+## If only one argument is given, @var{y}, it is taken as a vector of Y values
+## and the X coordinates are the range @code{1:numel (@var{y})}.
 ##
-## The default width of 0.8 for the bars can be changed using @var{w}.
+## The optional input @var{w} controls the width of the bars.  A value of
+## 1.0 will cause each bar to exactly touch any adjacent bars.
+## The default width is 0.8.
 ##
 ## If @var{y} is a matrix, then each column of @var{y} is taken to be a
 ## separate bar graph plotted on the same graph.  By default the columns
@@ -36,14 +39,17 @@
 ## argument, which can take the values @code{"grouped"} (the default),
 ## or @code{"stacked"}.
 ##
-## Passing the optional input handle @var{h} will draw the resulting plot
-## in the specified handle.
+## Optional property/value pairs are passed directly to the underlying patch
+## objects.
+##
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
-## The optional return value @var{h} is a handle to the created "bar series"
-## object with one handle per column of the variable @var{y}.  This
-## series allows common elements of the group of bar series objects to
-## be changed in a single bar series and the same properties are changed
-## in the other "bar series".  For example,
+## The optional return value @var{h} is a vector of handles to the created
+## "bar series" hggroups with one handle per column of the variable @var{y}.
+## This series makes it possible to change a common element in one bar series
+## object and have the change reflected in the other "bar series".
+## For example,
 ##
 ## @example
 ## @group
@@ -55,11 +61,11 @@
 ## @noindent
 ## changes the position on the base of all of the bar series.
 ##
-## The bar graph's appearance may be modified by specifying property/value
-## pairs.  The following example modifies the face and edge colors.
+## The following example modifies the face and edge colors using
+## property/value pairs.
 ##
 ## @example
-## bar (randn (1, 100), "facecolor", "r", "edgecolor", "b")
+## bar (randn (1, 100), "facecolor", "r", "edgecolor", "b");
 ## @end example
 ##
 ## @noindent
@@ -85,7 +91,7 @@
 ## @end group
 ## @end example
 ##
-## @seealso{barh, plot}
+## @seealso{barh, hist, pie, plot, patch}
 ## @end deftypefn
 
 ## Author: jwe
--- a/scripts/plot/barh.m
+++ b/scripts/plot/barh.m
@@ -17,19 +17,21 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {} barh (@var{x}, @var{y})
-## @deftypefnx {Function File} {} barh (@var{y})
-## @deftypefnx {Function File} {} barh (@var{x}, @var{y}, @var{w})
-## @deftypefnx {Function File} {} barh (@var{x}, @var{y}, @var{w}, @var{style})
-## @deftypefnx {Function File} {} barh (@dots{}, @var{prop}, @var{val})
-## @deftypefnx {Function File} {} barh (@var{h}, @dots{})
-## @deftypefnx {Function File} {@var{h} =} barh (@dots{})
-## Produce a horizontal bar graph from two vectors of x-y data.
+## @deftypefn  {Function File} {} barh (@var{y})
+## @deftypefnx {Function File} {} barh (@var{x}, @var{y})
+## @deftypefnx {Function File} {} barh (@dots{}, @var{w})
+## @deftypefnx {Function File} {} barh (@dots{}, @var{style})
+## @deftypefnx {Function File} {} barh (@dots{}, @var{prop}, @var{val}, @dots{})
+## @deftypefnx {Function File} {} barh (@var{hax}, @dots{})
+## @deftypefnx {Function File} {@var{h} =} barh (@dots{}, @var{prop}, @var{val}, @dots{})
+## Produce a horizontal bar graph from two vectors of X-Y data.
 ##
-## If only one argument is given, it is taken as a vector of y-values
-## and the x coordinates are taken to be the indices of the elements.
+## If only one argument is given, it is taken as a vector of Y values
+## and the X coordinates are the range @code{1:numel (@var{y})}.
 ##
-## The default width of 0.8 for the bars can be changed using @var{w}.
+## The optional input @var{w} controls the width of the bars.  A value of
+## 1.0 will cause each bar to exactly touch any adjacent bars.
+## The default width is 0.8.
 ##
 ## If @var{y} is a matrix, then each column of @var{y} is taken to be a
 ## separate bar graph plotted on the same graph.  By default the columns
@@ -37,16 +39,16 @@
 ## argument, which can take the values @code{"grouped"} (the default),
 ## or @code{"stacked"}.
 ##
-## Passing the optional input handle @var{h} will draw the resulting plot
-## in the specified handle.
+## Optional property/value pairs are passed directly to the underlying patch
+## objects.
+##
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ## 
-## Properties of the patch graphics object can be changed using
-## @var{prop}, @var{val} pairs.
-##
 ## The optional return value @var{h} is a graphics handle to the created
-## bar series object.  See @code{bar} for a description of the use of the
-## bar series.
-## @seealso{bar, plot}
+## bar series hggroup.  For a description of the use of the
+## bar series, @pxref{XREFbar,,bar}.
+## @seealso{bar, hist, pie, plot, patch}
 ## @end deftypefn
 
 ## Author: jwe
--- a/scripts/plot/box.m
+++ b/scripts/plot/box.m
@@ -17,18 +17,18 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {} box on
-## @deftypefnx {Function File} {} box off
-## @deftypefnx {Function File} {} box
+## @deftypefn  {Command} {} box on
+## @deftypefnx {Command} {} box off
+## @deftypefnx {Command} {} box
 ## @deftypefnx {Function File} {} box (@var{hax}, @dots{})
-## Control the display of a border around the current axis.
+## Control display of the axis border.
 ##
-## The argument may be either @code{"on"} or @code{"off"}.  If it is
-## omitted, the current box state is toggled.
+## The argument may be either "on" or "off".  If it is omitted, the current
+## box state is toggled.
 ##
-## If the first argument is an axis handle, @var{hax}, operate on the
-## specified axis object.
-## @seealso{grid}
+## If the first argument @var{hax} is an axes handle, then operate on
+## this axis rather than the current axes returned by @code{gca}.
+## @seealso{axis, grid}
 ## @end deftypefn
 
 ## Author: jwe
--- a/scripts/plot/caxis.m
+++ b/scripts/plot/caxis.m
@@ -32,10 +32,10 @@
 ## If @var{limits} is "auto", then automatic colormap scaling is applied,
 ## whereas if @var{limits} is "manual" the colormap scaling is set to manual.
 ##
-## Called without arguments the current color axis limits are returned.
+## If the first argument @var{hax} is an axes handle, then operate on
+## this axis rather than the current axes returned by @code{gca}.
 ##
-## If an axes handle @var{hax} is passed as the first argument then operate on
-## this axes rather than the current axes.
+## Called without arguments the current color axis limits are returned.
 ## @seealso{colormap}
 ## @end deftypefn
 
--- a/scripts/plot/cla.m
+++ b/scripts/plot/cla.m
@@ -17,11 +17,13 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {} cla
-## @deftypefnx {Function File} {} cla reset
+## @deftypefn  {Command} {} cla
+## @deftypefnx {Command} {} cla reset
 ## @deftypefnx {Function File} {} cla (@var{hax})
 ## @deftypefnx {Function File} {} cla (@var{hax}, "reset")
-## Clear the current axes by deleting child graphic objects with visible
+## Clear the current axes.
+##
+## @code{cla} operates by deleting child graphic objects with visible
 ## handles (HandleVisibility = "on").
 ##
 ## If the optional argument "reset" is specified, delete all child objects
@@ -29,8 +31,8 @@
 ## their defaults.  However, the following properties are not reset:
 ## Position, Units.
 ##
-## If an axes object handle @var{hax} is specified, operate on it instead of
-## the current axes.
+## If the first argument @var{hax} is an axes handle, then operate on
+## this axis rather than the current axes returned by @code{gca}.
 ## @seealso{clf}
 ## @end deftypefn
 
@@ -80,13 +82,12 @@
 %! hf = figure ("visible", "off");
 %! unwind_protect
 %!   plot (1:10);
+%!   assert (! isempty (get (gca, "children")));
 %!   cla ();
-%!   kids = get (gca, "children");
-%!   cla ();
+%!   assert (isempty (get (gca, "children")));
 %! unwind_protect_cleanup
 %!   close (hf);
 %! end_unwind_protect
-%! assert (numel (kids), 0);
 
 %!test
 %! hf = figure ("visible", "off");
--- a/scripts/plot/clabel.m
+++ b/scripts/plot/clabel.m
@@ -21,23 +21,28 @@
 ## @deftypefnx {Function File} {} clabel (@var{c}, @var{h}, @var{v})
 ## @deftypefnx {Function File} {} clabel (@var{c}, @var{h}, "manual")
 ## @deftypefnx {Function File} {} clabel (@var{c})
-## @deftypefnx {Function File} {} clabel (@var{c}, @var{h})
 ## @deftypefnx {Function File} {} clabel (@dots{}, @var{prop}, @var{val}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} clabel (@dots{})
-## Add labels to the contours of a contour plot.  The contour plot is specified
-## by the contour matrix @var{c} and optionally the contourgroup object @var{h}
-## that are returned by @code{contour}, @code{contourf} and @code{contour3}.
-## The contour labels are rotated and placed in the contour itself.
+## Add labels to the contours of a contour plot.
+##
+## The contour levels are specified by the contour matrix @var{c} which is
+## returned by @code{contour}, @code{contourc}, @code{contourf}, and
+## @code{contour3}.  Contour labels are rotated to match the local line 
+## orientation and centered on the line.  The position of labels along the
+## contour line is chosen randomly.
+##
+## If the argument @var{h} is a handle to a contour group object, then label
+## this plot rather than the one in the current axes returned by @code{gca}.
 ##
 ## By default, all contours are labeled.  However, the contours to label can be
 ## specified by the vector @var{v}.  If the "manual" argument is given then
 ## the contours to label can be selected with the mouse.
 ##
 ## Additional property/value pairs that are valid properties of text objects
-## can be given and are passed to the underlying text objects.  Additionally,
-## the property "LabelSpacing" is available allowing the spacing between labels
-## on a contour (in points) to be specified.  The default is 144 points, or 2
-## inches.
+## can be given and are passed to the underlying text objects.  Moreover,
+## the contour group property "LabelSpacing" is available which determines
+## the spacing between labels on a contour to be specified.  The default is
+## 144 points, or 2 inches.
 ##
 ## The optional return value @var{h} is a vector of graphics handles to
 ## the text objects representing each label.  
@@ -57,6 +62,7 @@
 ## @end deftypefn
 
 function retval = clabel (c, varargin)
+
   label_spacing = 2 * 72;
   have_hg = false;
   have_labelspacing = false;
--- a/scripts/plot/clf.m
+++ b/scripts/plot/clf.m
@@ -17,8 +17,8 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {} clf
-## @deftypefnx {Function File} {} clf reset
+## @deftypefn  {Command} {} clf
+## @deftypefnx {Command} {} clf reset
 ## @deftypefnx {Function File} {} clf (@var{hfig})
 ## @deftypefnx {Function File} {} clf (@var{hfig}, "reset")
 ## @deftypefnx {Function File} {@var{h} =} clf (@dots{})
--- a/scripts/plot/close.m
+++ b/scripts/plot/close.m
@@ -24,12 +24,12 @@
 ## Close figure window(s).
 ##
 ## @code{close} operates by calling the function specified by the
-## @code{"closerequestfcn"} property for each figure.  By default, the function
+## "closerequestfcn" property for each figure.  By default, the function
 ## @code{closereq} is used.
 ##
 ## When called with no arguments, close the current figure.  This is equivalent
-## to @code{close (gcf)}.  If the input is a graphic handle @var{h} or vector
-## of graphics handles then close each figure in @var{h}.
+## to @code{close (gcf)}.  If the input @var{h} is a graphic handle, or vector
+## of graphics handles, then close each figure in @var{h}.
 ##
 ## If the argument "all" is given then all figures with visible handles
 ## (HandleVisibility = "on") are closed.
@@ -39,7 +39,8 @@
 ##
 ## Implementation Note: @code{close} calls a function to dispose of the figure.
 ## It is possible that the function will delay or abort removing the figure.
-## To remove a figure without calling any callback functions use @code{delete}.
+## To remove a figure without executing any callback functions use
+## @code{delete}.
 ##
 ## @seealso{closereq, delete}
 ## @end deftypefn
--- a/scripts/plot/closereq.m
+++ b/scripts/plot/closereq.m
@@ -18,8 +18,7 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {} closereq ()
-## Close the current figure and delete all graphics objects associated
-## with it.
+## Close the current figure and delete all graphics objects associated with it.
 ## @seealso{close, delete}
 ## @end deftypefn
 
--- a/scripts/plot/colorbar.m
+++ b/scripts/plot/colorbar.m
@@ -17,7 +17,7 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {} colorbar
+## @deftypefn  {Command} {} colorbar
 ## @deftypefnx {Function File} {} colorbar (@var{loc})
 ## @deftypefnx {Function File} {} colorbar (@var{delete_option})
 ## @deftypefnx {Function File} {} colorbar (@var{hcb}, @dots{})
--- a/scripts/plot/comet.m
+++ b/scripts/plot/comet.m
@@ -29,8 +29,8 @@
 ## time each point is displayed before moving to the next one.  The default for
 ## @var{p} is 0.1 seconds.
 ##
-## If @var{hax} is specified the animation is produced in that axis rather than
-## the current axis.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ## @seealso{comet3}
 ## @end deftypefn
 
--- a/scripts/plot/comet3.m
+++ b/scripts/plot/comet3.m
@@ -29,8 +29,8 @@
 ## time each point is displayed before moving to the next one.  The default for
 ## @var{p} is 0.1 seconds.
 ##
-## If @var{hax} is specified the animation is produced in that axis rather than
-## the current axis.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ## @seealso{comet}
 ## @end deftypefn
 
--- a/scripts/plot/compass.m
+++ b/scripts/plot/compass.m
@@ -24,15 +24,17 @@
 ## @deftypefnx {Function File} {@var{h} =} compass (@dots{})
 ##
 ## Plot the @code{(@var{u}, @var{v})} components of a vector field emanating
-## from the origin of a polar plot.  If a single complex argument @var{z} is
-## given, then @code{@var{u} = real (@var{z})} and @code{@var{v} = imag
-## (@var{z})}.
+## from the origin of a polar plot.
+##
+## The arrow representing each vector has one end at the origin and the tip at
+## [@var{u}(i), @var{v}(i)].  If a single complex argument @var{z} is given,
+## then @code{@var{u} = real (@var{z})} and @code{@var{v} = imag (@var{z})}.
 ##
 ## The style to use for the plot can be defined with a line style @var{style}
-## in a similar manner to the line styles used with the @code{plot} command.
+## of the same format as the @code{plot} command.
 ##
-## If the first argument @var{hax} is an axis handle, then plot into these axes,
-## rather than the current axis handle returned by @code{gca}.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a vector of graphics handles to the
 ## line objects representing the drawn vectors.
--- a/scripts/plot/contour.m
+++ b/scripts/plot/contour.m
@@ -22,12 +22,27 @@
 ## @deftypefnx {Function File} {} contour (@var{x}, @var{y}, @var{z})
 ## @deftypefnx {Function File} {} contour (@var{x}, @var{y}, @var{z}, @var{vn})
 ## @deftypefnx {Function File} {} contour (@dots{}, @var{style})
-## @deftypefnx {Function File} {} contour (@var{h}, @dots{})
+## @deftypefnx {Function File} {} contour (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {[@var{c}, @var{h}] =} contour (@dots{})
+## Create a 2-D contour plot.
+##
 ## Plot level curves (contour lines) of the matrix @var{z}, using the
 ## contour matrix @var{c} computed by @code{contourc} from the same
-## arguments; see the latter for their interpretation.  The set of
-## contour levels, @var{c}, is only returned if requested.  For example:
+## arguments; see the latter for their interpretation.
+##
+## The appearance of contour lines can be defined with a line style @var{style}
+## in the same manner as @code{plot}.  Only line style and color are used;
+## Any markers defined by @var{style} are ignored.
+##
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
+##
+## The optional output @var{c} are the contour levels in @code{contourc} format.
+##
+## The optional return value @var{h} is a graphics handle to the hggroup
+## comprising the contour lines.
+##
+## Example:
 ##
 ## @example
 ## @group
@@ -38,14 +53,8 @@
 ## @end group
 ## @end example
 ##
-## The style to use for the plot can be defined with a line style @var{style}
-## in a similar manner to the line styles used with the @code{plot} command.
-## Any markers defined by @var{style} are ignored.
+## @seealso{ezcontour, contourc, contourf, contour3, clabel, meshc, surfc, caxis, colormap, plot}
 ##
-## The optional input and output argument @var{h} allows an axis handle to
-## be passed to @code{contour} and the handles to the contour objects to be
-## returned.
-## @seealso{contourc, contourf, contour3, patch, plot}
 ## @end deftypefn
 
 ## Author: Shai Ayal <shaiay@users.sourceforge.net>
--- a/scripts/plot/contour3.m
+++ b/scripts/plot/contour3.m
@@ -22,13 +22,32 @@
 ## @deftypefnx {Function File} {} contour3 (@var{x}, @var{y}, @var{z})
 ## @deftypefnx {Function File} {} contour3 (@var{x}, @var{y}, @var{z}, @var{vn})
 ## @deftypefnx {Function File} {} contour3 (@dots{}, @var{style})
-## @deftypefnx {Function File} {} contour3 (@var{h}, @dots{})
+## @deftypefnx {Function File} {} contour3 (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {[@var{c}, @var{h}] =} contour3 (@dots{})
-## Plot level curves (contour lines) of the matrix @var{z}, using the
-## contour matrix @var{c} computed by @code{contourc} from the same
-## arguments; see the latter for their interpretation.  The contours are
-## plotted at the Z level corresponding to their contour.  The set of
-## contour levels, @var{c}, is only returned if requested.  For example:
+## Create a 3-D contour plot.
+##
+## @code{contour3} plots level curves (contour lines) of the matrix @var{z}
+## at a Z level corresponding to each contour.  This is in contrast to
+## @code{contour} which plots all of the contour lines at the same Z level
+## and produces a 2-D plot.
+##
+## The level curves are taken from the contour matrix @var{c} computed by
+## @code{contourc} for the same arguments; see the latter for their
+## interpretation.
+##
+## The appearance of contour lines can be defined with a line style @var{style}
+## in the same manner as @code{plot}.  Only line style and color are used;
+## Any markers defined by @var{style} are ignored.
+##
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
+##
+## The optional output @var{c} are the contour levels in @code{contourc} format.
+##
+## The optional return value @var{h} is a graphics handle to the hggroup
+## comprising the contour lines.
+##
+## Example:
 ##
 ## @example
 ## @group
@@ -39,14 +58,7 @@
 ## @end group
 ## @end example
 ##
-## The style to use for the plot can be defined with a line style @var{style}
-## in a similar manner to the line styles used with the @code{plot} command.
-## Any markers defined by @var{style} are ignored.
-##
-## The optional input and output argument @var{h} allows an axis handle to
-## be passed to @code{contour} and the handles to the contour objects to be
-## returned.
-## @seealso{contourc, contour, contourf, patch, plot}
+## @seealso{contour, contourc, contourf, clabel, meshc, surfc, caxis, colormap, plot}
 ## @end deftypefn
 
 function [c, h] = contour3 (varargin)
@@ -66,7 +78,7 @@
 
   if (! ishold ())
     set (hax, "view", [-37.5, 30],
-         "xgrid", "on", "ygrid", "on", "zgrid", "on");
+              "xgrid", "on", "ygrid", "on", "zgrid", "on");
   endif
 
   if (nargout > 0)
--- a/scripts/plot/contourc.m
+++ b/scripts/plot/contourc.m
@@ -21,10 +21,20 @@
 ## @deftypefnx {Function File} {[@var{c}, @var{lev}] =} contourc (@var{z}, @var{vn})
 ## @deftypefnx {Function File} {[@var{c}, @var{lev}] =} contourc (@var{x}, @var{y}, @var{z})
 ## @deftypefnx {Function File} {[@var{c}, @var{lev}] =} contourc (@var{x}, @var{y}, @var{z}, @var{vn})
-## Compute isolines (contour lines) of the matrix @var{z}.
-## Parameters @var{x}, @var{y}, and @var{vn} are optional.
+## Compute contour lines (isolines of constant Z value).
+##
+## The matrix @var{z} contains height values above the rectangular grid
+## determined by @var{x} and @var{y}.  If only a single input @var{z} is
+## provided then @var{x} is taken to be @code{1:rows (@var{z})} and @var{y} is
+## taken to be @code{1:columns (@var{z})}.
 ##
-## The return value @var{lev} is a vector of the contour levels.
+## The optional input @var{vn} is either a scalar denoting the number of
+## contour lines to compute or a vector containing the Z values where lines
+## will be computed.  When @var{vn} is a vector the number of contour lines
+## is @code{numel (@var{vn})}.  However, to compute a single contour line
+## at a given value use @code{@var{vn} = [val, val]}.  If @var{vn} is omitted
+## it defaults to 10.
+##
 ## The return value @var{c} is a 2x@var{n} matrix containing the
 ## contour lines in the following format
 ##
@@ -39,13 +49,10 @@
 ## in which contour line @var{n} has a level (height) of @var{levn} and
 ## length of @var{lenn}.
 ##
-## If @var{x} and @var{y} are omitted they are taken as the row/column
-## indices of @var{z}.  @var{vn} is either a scalar denoting the number of
-## contour lines to compute or a vector containing the values of the lines.
-## If only one value is desired, set @code{@var{vn} = [val, val]};
-## If @var{vn} is omitted it defaults to 10.
+## The optional return value @var{lev} is a vector with the Z values of
+## of the contour levels.
 ##
-## For example:
+## Example:
 ##
 ## @example
 ## @group
@@ -57,7 +64,7 @@
 ##         2.0000   1.0000   2.0000   2.0000   2.0000   1.5000
 ## @end group
 ## @end example
-## @seealso{contour, contourf, contour3}
+## @seealso{contour, contourf, contour3, clabel}
 ## @end deftypefn
 
 ## Author: Shai Ayal <shaiay@users.sourceforge.net>
--- a/scripts/plot/contourf.m
+++ b/scripts/plot/contourf.m
@@ -18,39 +18,35 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {} contourf (@var{x}, @var{y}, @var{z}, @var{lvl})
-## @deftypefnx {Function File} {} contourf (@var{x}, @var{y}, @var{z}, @var{n})
+## @deftypefn  {Function File} {} contourf (@var{z})
+## @deftypefnx {Function File} {} contourf (@var{z}, @var{vn})
 ## @deftypefnx {Function File} {} contourf (@var{x}, @var{y}, @var{z})
-## @deftypefnx {Function File} {} contourf (@var{z}, @var{n})
-## @deftypefnx {Function File} {} contourf (@var{z}, @var{lvl})
-## @deftypefnx {Function File} {} contourf (@var{z})
-## @deftypefnx {Function File} {} contourf (@dots{}, @var{prop}, @var{val})
+## @deftypefnx {Function File} {} contourf (@var{x}, @var{y}, @var{z}, @var{vn})
+## @deftypefnx {Function File} {} contourf (@dots{}, @var{style})
 ## @deftypefnx {Function File} {} contourf (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {[@var{c}, @var{h}] =} contourf (@dots{})
-## Compute and plot filled contours of the matrix @var{z}.
-## Parameters @var{x}, @var{y} and @var{n} or @var{lvl} are optional.
+## Create a 2-D contour plot with filled intervals.
 ##
-## If @var{x} and @var{y} are omitted they are taken as the row/column
-## indices of @var{z}.  @var{n} is a scalar denoting the number of contour
-## lines to compute.  Alternatively @var{lvl} is a vector containing the
-## contour levels.  If only one value (e.g., lvl0) is desired, set
-## @var{lvl} to [lvl0, lvl0].  If both @var{n} or @var{lvl} are omitted
-## a default value of 10 contour levels is assumed.
+## Plot level curves (contour lines) of the matrix @var{z} and fill the region
+## between lines with colors from the current colormap.
+##
+## The level curves are taken from the contour matrix @var{c} computed by
+## @code{contourc} for the same arguments; see the latter for their
+## interpretation.
 ##
-## The appearance of the plot can be customized by passing
-## property/value pairs to the function. 
+## The appearance of contour lines can be defined with a line style @var{style}
+## in the same manner as @code{plot}.  Only line style and color are used;
+## Any markers defined by @var{style} are ignored.
 ##
-## If provided, the filled contours are added to the axes object
-## @var{hax} instead of the current axis.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
-## The return value @var{c} is a 2xn matrix containing the contour lines
-## as described in the documentation on the @code{contourc} function.
+## The optional output @var{c} are the contour levels in @code{contourc} format.
 ##
-## The return value @var{h} is handle-vector to the patch objects creating
-## the filled contours.
+## The optional return value @var{h} is a graphics handle to the hggroup
+## comprising the contour lines.
 ##
-## The following example plots filled contours of the @code{peaks}
-## function.
+## The following example plots filled contours of the @code{peaks} function.
 ##
 ## @example
 ## @group
@@ -58,7 +54,7 @@
 ## contourf (x, y, z, -7:9)
 ## @end group
 ## @end example
-## @seealso{contourc, contour, contour3, patch}
+## @seealso{ezcontourf, contour, contourc, contour3, clabel, meshc, surfc, caxis, colormap, plot}
 ## @end deftypefn
 
 ## Author: Kai Habel <kai.habel@gmx.de>
--- a/scripts/plot/copyobj.m
+++ b/scripts/plot/copyobj.m
@@ -17,11 +17,12 @@
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {@var{hnew} =} copyobj (@var{horig})
 ## @deftypefnx {Function File} {@var{hnew} =} copyobj (@var{horig}, @var{hparent})
-## Construct a copy of the object associated with handle @var{horig}
+## Construct a copy of the graphic object associated with handle @var{horig}
 ## and return a handle @var{hnew} to the new object.
+##
 ## If a parent handle @var{hparent} (root, figure, axes, or hggroup) is
-## specified, the copied object will be created as a child to @var{hparent}.
-## @seealso{findobj, get, set, struct2hdl, hdl2struct}
+## specified, the copied object will be created as a child of @var{hparent}.
+## @seealso{struct2hdl, hdl2struct, findobj}
 ## @end deftypefn
 
 ## Author: pdiribarne <pdiribarne@new-host.home>
--- a/scripts/plot/cylinder.m
+++ b/scripts/plot/cylinder.m
@@ -17,24 +17,28 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {} cylinder
+## @deftypefn  {Command} {} cylinder
 ## @deftypefnx {Function File} {} cylinder (@var{r})
 ## @deftypefnx {Function File} {} cylinder (@var{r}, @var{n})
+## @deftypefnx {Function File} {} cylinder (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} cylinder (@dots{})
-## @deftypefnx {Function File} {} cylinder (@var{ax}, @dots{})
-## Generate three matrices in @code{meshgrid} format, such that
-## @code{surf (@var{x}, @var{y}, @var{z})} generates a unit cylinder.
-## The matrices are of size @code{@var{n}+1}-by-@code{@var{n}+1}.
-## @var{r} is a vector containing the radius along the z-axis.
-## If @var{n} or @var{r} are omitted then default values of 20 or [1 1]
-## are assumed.
+## Plot a 3-D unit cylinder.
+##
+## The optional input @var{r} is a vector specifying the radius along the
+## unit z-axis.  The default is [1 1] indicating radius 1 at @code{Z == 0}
+## and at @code{Z == 1}.
+##
+## The optional input @var{n} determines the number of faces around the
+## the circumference of the cylinder.  The default value is 20.
 ##
-## Called with no return arguments, @code{cylinder} calls directly
-## @code{surf (@var{x}, @var{y}, @var{z})}.  If an axes handle @var{ax}
-## is passed as the first argument, the surface is plotted to this set
-## of axes.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
-## Examples:
+## If outputs are requested @code{cylinder} returns three matrices in
+## @code{meshgrid} format, such that @code{surf (@var{x}, @var{y}, @var{z})}
+## generates a unit cylinder.
+##
+## Example:
 ##
 ## @example
 ## @group
@@ -43,7 +47,7 @@
 ## title ("a cone");
 ## @end group
 ## @end example
-## @seealso{sphere}
+## @seealso{ellipsoid, rectangle, sphere}
 ## @end deftypefn
 
 function [xx, yy, zz] = cylinder (varargin)
--- a/scripts/plot/daspect.m
+++ b/scripts/plot/daspect.m
@@ -22,9 +22,10 @@
 ## @deftypefnx {Function File} {} daspect (@var{mode})
 ## @deftypefnx {Function File} {@var{data_aspect_ratio_mode} =} daspect ("mode")
 ## @deftypefnx {Function File} {} daspect (@var{hax}, @dots{})
-## Query or set the data aspect ratio of the current axes.  The aspect 
-## ratio is a normalized 3-element vector representing the span of the x, y,
-## and z-axis limits.
+## Query or set the data aspect ratio of the current axes.
+##
+## The aspect ratio is a normalized 3-element vector representing the span of
+## the x, y, and z-axis limits.
 ## 
 ## @code{(daspect (@var{mode}))}
 ##
--- a/scripts/plot/diffuse.m
+++ b/scripts/plot/diffuse.m
@@ -20,9 +20,9 @@
 ## @deftypefn {Function File} {} diffuse (@var{sx}, @var{sy}, @var{sz}, @var{lv})
 ## Calculate diffuse reflection strength of a surface defined by the normal
 ## vector elements @var{sx}, @var{sy}, @var{sz}.
-## The light vector can be specified using parameter @var{lv}.  It can be
-## given as 2-element vector [azimuth, elevation] in degrees or as 3-element
-## vector [lx, ly, lz].
+##
+## The light source location vector @var{lv} can be given as 2-element vector
+## [azimuth, elevation] in degrees or as 3-element vector [lx, ly, lz].
 ## @seealso{specular, surfl}
 ## @end deftypefn
 
--- a/scripts/plot/ellipsoid.m
+++ b/scripts/plot/ellipsoid.m
@@ -17,14 +17,25 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {[@var{x}, @var{y}, @var{z}] =} ellipsoid (@var{xc}, @var{yc}, @var{zc}, @var{xr}, @var{yr}, @var{zr}, @var{n})
-## @deftypefnx {Function File} {} ellipsoid (@var{h}, @dots{})
-## Generate three matrices in @code{meshgrid} format that define an
-## ellipsoid.  Called with no return arguments, @code{ellipsoid} calls
-## directly @code{surf (@var{x}, @var{y}, @var{z})}.  If an axes handle
-## is passed as the first argument, the surface is plotted to this
-## set of axes.
-## @seealso{sphere}
+## @deftypefn  {Function File} {} ellipsoid (@var{xc}, @var{yc}, @var{zc}, @var{xr}, @var{yr}, @var{zr}, @var{n})
+## @deftypefnx {Function File} {} ellipsoid (@dots{}, @var{n})
+## @deftypefnx {Function File} {} ellipsoid (@var{hax}, @dots{})
+## @deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} ellipsoid (@dots{})
+## Plot a 3-D ellipsoid.
+##
+## The inputs @var{xc}, @var{yc}, @var{zc} specify the center of the ellipsoid.
+## The inputs @var{xr}, @var{yr}, @var{zr} specify the semi-major axis lengths.
+##
+## The optional input @var{n} determines the number of faces around the
+## the circumference of the cylinder.  The default value is 20.
+## 
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
+##
+## If outputs are requested @code{ellipsoid} returns three matrices in
+## @code{meshgrid} format, such that @code{surf (@var{x}, @var{y}, @var{z})}
+## generates the ellipsoid.
+## @seealso{cylinder, rectangle, sphere}
 ## @end deftypefn
 
 ## Author: Sylvain Pelissier <sylvain.pelissier@gmail.com>
--- a/scripts/plot/errorbar.m
+++ b/scripts/plot/errorbar.m
@@ -18,8 +18,9 @@
 
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} errorbar (@var{args})
-## @deftypefnx {Function File} {@var{h} =} errorbar (@var{args})
-## Create a two-dimensional plot with errorbars.
+## @deftypefnx {Function File} {} errorbar (@var{hax}, @dots{})
+## @deftypefnx {Function File} {@var{h} =} errorbar (@dots{})
+## Create a 2-D with errorbars.
 ##
 ## Many different combinations of arguments are possible.  The simplest
 ## form is
@@ -78,6 +79,12 @@
 ## Set boxxyerrorbars plot style.
 ## @end table
 ##
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
+##
+## The optional return value @var{h} is a handle to the hggroup object
+## representing the data plot and errorbars.
+##
 ## Examples:
 ##
 ## @example
@@ -112,7 +119,7 @@
 ## produces an xyerrorbar plot of @var{y} versus @var{x} in which
 ## @var{x} errorbars are drawn from @var{x}-@var{lx} to @var{x}+@var{ux}
 ## and @var{y} errorbars from @var{y}-@var{ly} to @var{y}+@var{uy}.
-## @seealso{semilogxerr, semilogyerr, loglogerr}
+## @seealso{semilogxerr, semilogyerr, loglogerr, plot}
 ## @end deftypefn
 
 ## Created: 18.7.2000
--- a/scripts/plot/ezcontour.m
+++ b/scripts/plot/ezcontour.m
@@ -35,8 +35,8 @@
 ##
 ## @var{n} is a scalar defining the number of points to use in each dimension.
 ##
-## If the first argument is an axis handle, @var{hax}, then plot into this
-## axis rather than the current axis handle returned by @code{gca}.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a graphics handle to the created plot.
 ##
--- a/scripts/plot/ezcontourf.m
+++ b/scripts/plot/ezcontourf.m
@@ -35,8 +35,8 @@
 ##
 ## @var{n} is a scalar defining the number of points to use in each dimension.
 ##
-## If the first argument is an axis handle, @var{hax}, then plot into this
-## axis rather than the current axis handle returned by @code{gca}.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a graphics handle to the created plot.
 ##
--- a/scripts/plot/ezmesh.m
+++ b/scripts/plot/ezmesh.m
@@ -44,8 +44,8 @@
 ## If the argument "circ" is given, then the function is plotted over a disk
 ## centered on the middle of the domain @var{dom}.
 ##
-## If the first argument is an axis handle, @var{hax}, then plot into this
-## axis rather than the current axis handle returned by @code{gca}.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a graphics handle to the created 
 ## surface object.
--- a/scripts/plot/ezmeshc.m
+++ b/scripts/plot/ezmeshc.m
@@ -44,6 +44,9 @@
 ## If the argument "circ" is given, then the function is plotted over a disk
 ## centered on the middle of the domain @var{dom}.
 ##
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
+##
 ## The optional return value @var{h} is a 2-element vector with a graphics
 ## handle for the created mesh plot and a second handle for the created contour
 ## plot.
--- a/scripts/plot/ezplot.m
+++ b/scripts/plot/ezplot.m
@@ -62,11 +62,11 @@
 ## @var{n} is a scalar defining the number of points to use in plotting
 ## the function.
 ##
-## If the first argument is an axis handle, @var{hax}, then plot into this
-## axis rather than the current axis handle returned by @code{gca}.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
-## The optional return value @var{h} is a list of graphics handles in the
-## created plot.
+## The optional return value @var{h} is a vector of graphics handles to
+## the created line objects.
 ##
 ## @seealso{plot, ezplot3, ezpolar, ezcontour, ezcontourf, ezmesh, ezmeshc, ezsurf, ezsurfc}
 ## @end deftypefn
--- a/scripts/plot/ezplot3.m
+++ b/scripts/plot/ezplot3.m
@@ -36,8 +36,8 @@
 ## @var{n} is a scalar defining the number of points to use in plotting the
 ## function.
 ##
-## If the first argument is an axis handle, @var{hax}, then plot into this
-## axis rather than the current axis handle returned by @code{gca}.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a graphics handle to the created plot.
 ##
--- a/scripts/plot/ezpolar.m
+++ b/scripts/plot/ezpolar.m
@@ -37,8 +37,8 @@
 ## @var{n} is a scalar defining the number of points to use in plotting
 ## the function.
 ##
-## If the first argument is an axis handle, @var{hax}, then plot into this
-## axis rather than the current axis handle returned by @code{gca}.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a graphics handle to the created plot.
 ##
--- a/scripts/plot/ezsurf.m
+++ b/scripts/plot/ezsurf.m
@@ -44,8 +44,8 @@
 ## If the argument "circ" is given, then the function is plotted over a disk
 ## centered on the middle of the domain @var{dom}.
 ##
-## If the first argument is an axis handle, @var{hax}, then plot into this
-## axis rather than the current axis handle returned by @code{gca}.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a graphics handle to the created
 ## surface object.
--- a/scripts/plot/ezsurfc.m
+++ b/scripts/plot/ezsurfc.m
@@ -44,8 +44,8 @@
 ## If the argument "circ" is given, then the function is plotted over a disk
 ## centered on the middle of the domain @var{dom}.
 ##
-## If the first argument is an axis handle, @var{hax}, then plot into this
-## axis rather than the current axis handle returned by @code{gca}.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a 2-element vector with a graphics
 ## handle for the created surface plot and a second handle for the created
--- a/scripts/plot/feather.m
+++ b/scripts/plot/feather.m
@@ -24,12 +24,13 @@
 ## @deftypefnx {Function File} {@var{h} =} feather (@dots{})
 ##
 ## Plot the @code{(@var{u}, @var{v})} components of a vector field emanating
-## from equidistant points on the x-axis.  If a single complex argument
-## @var{z} is given, then @code{@var{u} = real (@var{z})} and
-## @code{@var{v} = imag (@var{z})}.
+## from equidistant points on the x-axis.
+##
+## If a single complex argument @var{z} is given, then
+## @code{@var{u} = real (@var{z})} and @code{@var{v} = imag (@var{z})}.
 ##
 ## The style to use for the plot can be defined with a line style @var{style}
-## in a similar manner to the line styles used with the @code{plot} command.
+## of the same format as the @code{plot} command.
 ##
 ## The optional return value @var{h} is a vector of graphics handles to the
 ## line objects representing the drawn vectors.
--- a/scripts/plot/figure.m
+++ b/scripts/plot/figure.m
@@ -20,12 +20,23 @@
 ## @deftypefn  {Command} {} figure
 ## @deftypefnx {Command} {} figure @var{n}
 ## @deftypefnx {Function File} {} figure (@var{n})
-## @deftypefnx {Function File} {} figure (@var{n}, "@var{property}", @var{value}, @dots{})
-## Set the current plot window to plot window @var{n}.  If no arguments are
-## specified, the next available window number is chosen.
+## @deftypefnx {Function File} {} figure (@dots{}, "@var{property}", @var{value}, @dots{})
+## @deftypefnx {Function File} {@var{h} =} figure (@var{dots})
+## Create a new figure window for plotting.
+##
+## If no arguments are specified, a new figure with the next available number
+## is created.
 ##
-## Multiple property-value pairs may be specified for the figure, but they
-## must appear in pairs.
+## If called with an integer @var{n}, and no such numbered figure exists, then
+## a new figure with the specified number is created.  If the figure already
+## exists then it is made visible and becomes the current figure for plotting.
+## 
+## Multiple property-value pairs may be specified for the figure object, but
+## they must appear in pairs.
+##
+## The optional return value @var{h} is a graphics handle to the created figure
+## object.
+## @seealso{axes, gcf, clf, close}
 ## @end deftypefn
 
 ## Author: jwe, Bill Denney
--- a/scripts/plot/fill.m
+++ b/scripts/plot/fill.m
@@ -26,8 +26,8 @@
 ##
 ## The inputs @var{x} and @var{y} are the coordinates of the polygon vertices.
 ## If the inputs are matrices then the rows represent different vertices and
-## each column produces a different polygon.
-## @code{fill} will close any open polygons before plotting. 
+## each column produces a different polygon.  @code{fill} will close any open
+## polygons before plotting. 
 ##
 ## The input @var{c} determines the color of the polygon.  The simplest form
 ## is a single color specification such as a @code{plot} format or an
@@ -42,10 +42,10 @@
 ## Multiple property/value pairs for the underlying patch object may be
 ## specified, but they must appear in pairs.
 ##
-## If the first argument @var{hax} is an axis handle, then plot into this axis,
-## rather than the current axis handle returned by @code{gca}.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
-## The optional return value @var{h} is an array of graphics handles to
+## The optional return value @var{h} is a vector of graphics handles to
 ## the created patch objects.
 ##
 ## Example: red square
--- a/scripts/plot/findall.m
+++ b/scripts/plot/findall.m
@@ -18,15 +18,21 @@
 
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {@var{h} =} findall ()
-## @deftypefnx {Function File} {@var{h} =} findall (@var{prop_name}, @var{prop_value})
-## @deftypefnx {Function File} {@var{h} =} findall (@var{h}, @dots{})
-## @deftypefnx {Function File} {@var{h} =} findall (@var{h}, "-depth", @var{d}, @dots{})
-## Find graphics object with specified property values including hidden handles.
+## @deftypefnx {Function File} {@var{h} =} findall (@var{prop_name}, @var{prop_value}, @dots{})
+## @deftypefnx {Function File} {@var{h} =} findall (@var{prop_name}, @var{prop_value}, "-@var{logical_op}", @var{prop_name}, @var{prop_value})
+## @deftypefnx {Function File} {@var{h} =} findall ("-property", @var{prop_name})
+## @deftypefnx {Function File} {@var{h} =} findall ("-regexp", @var{prop_name}, @var{pattern})
+## @deftypefnx {Function File} {@var{h} =} findall (@var{hlist}, @dots{})
+## @deftypefnx {Function File} {@var{h} =} findall (@var{hlist}, "flat", @dots{})
+## @deftypefnx {Function File} {@var{h} =} findall (@var{hlist}, "-depth", @var{d}, @dots{})
+## Find graphics object, including hidden ones, with specified property values.
 ##
-## This function performs the same function as @code{findobj}, but it
-## includes hidden objects in its search.  For full documentation, see
-## @code{findobj}.
-## @seealso{get, set, findobj, allchild}
+## The return value @var{h} is a list of handles to the found graphic objects.
+##
+## @code{findall} performs the same search as @code{findobj}, but it
+## includes hidden objects ("HandleVisibility" = "off").  For full
+## documentation, @pxref{XREFfindobj,,findobj}.
+## @seealso{findobj, allchild, get, set}
 ## @end deftypefn
 
 ## Author: Bill Denney <bill@denney.ws>
--- a/scripts/plot/findobj.m
+++ b/scripts/plot/findobj.m
@@ -18,46 +18,57 @@
 
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {@var{h} =} findobj ()
-## @deftypefnx {Function File} {@var{h} =} findobj (@var{prop_name}, @var{prop_value})
+## @deftypefnx {Function File} {@var{h} =} findobj (@var{prop_name}, @var{prop_value}, @dots{})
+## @deftypefnx {Function File} {@var{h} =} findobj (@var{prop_name}, @var{prop_value}, "-@var{logical_op}", @var{prop_name}, @var{prop_value})
 ## @deftypefnx {Function File} {@var{h} =} findobj ("-property", @var{prop_name})
 ## @deftypefnx {Function File} {@var{h} =} findobj ("-regexp", @var{prop_name}, @var{pattern})
-## @deftypefnx {Function File} {@var{h} =} findobj ("flat", @dots{})
-## @deftypefnx {Function File} {@var{h} =} findobj (@var{h}, @dots{})
-## @deftypefnx {Function File} {@var{h} =} findobj (@var{h}, "-depth", @var{d}, @dots{})
-## Find graphics object with specified property values.  The simplest form is
+## @deftypefnx {Function File} {@var{h} =} findobj (@var{hlist}, @dots{})
+## @deftypefnx {Function File} {@var{h} =} findobj (@var{hlist}, "flat", @dots{})
+## @deftypefnx {Function File} {@var{h} =} findobj (@var{hlist}, "-depth", @var{d}, @dots{})
+## Find graphics object with specified property values.
+##
+## The simplest form is
 ##
 ## @example
 ## findobj (@var{prop_name}, @var{prop_value})
 ## @end example
 ##
 ## @noindent
-## which returns all of the handles to the objects with the name
-## @var{prop_name} and the name @var{prop_value}.  The search can be limited
-## to a particular object or set of objects and their descendants by
-## passing a handle or set of handles @var{h} as the first argument to
-## @code{findobj}.
+## which returns the handles of all objects which have a property named
+## @var{prop_name} that has the value @var{prop_value}.  If multiple
+## property/value pairs are specified then only objects meeting all of the
+## conditions are returned.
 ##
-## The depth of hierarchy of objects to which to search to can be limited
-## with the "-depth" argument.  To limit the number depth of the hierarchy
-## to search to @var{d} generations of children, and example is
+## The search can be limited to a particular set of objects and their
+## descendants, by passing a handle or set of handles @var{hlist} as the first
+## argument.
+##
+## The depth of the object hierarchy to search can be limited with the "-depth"
+## argument.  An example of searching only three generations of children is:
 ##
 ## @example
-## findobj (@var{h}, "-depth", @var{d}, @var{prop_name}, @var{prop_value})
+## findobj (@var{hlist}, "-depth", @var{d}, @var{prop_name}, @var{prop_value})
 ## @end example
 ##
-## Specifying a depth @var{d} of 0, limits the search to the set of object
-## passed in @var{h}.  A depth @var{d} of 0 is equivalent to the "-flat"
+## Specifying a depth @var{d} of 0, limits the search to the set of objects
+## passed in @var{hlist}.  A depth @var{d} of 0 is equivalent to the "flat"
 ## argument.
 ##
 ## A specified logical operator may be applied to the pairs of @var{prop_name}
-## and @var{prop_value}.  The supported logical operators are "-and", "-or",
+## and @var{prop_value}.  The supported logical operators are: "-and", "-or",
 ## "-xor", "-not".
 ##
-## The objects may also be matched by comparing a regular expression to the
-## property values, where property values that match @code{regexp
-## (@var{prop_value}, @var{pattern})} are returned.  Finally, objects may be
-## matched by property name only, using the "-property" option.
-## @seealso{get, set}
+## Objects may also be matched by comparing a regular expression to the
+## property values, where property values that match
+## @code{regexp (@var{prop_value}, @var{pattern})} are returned.
+##
+## Finally, objects may be matched by property name only by using the
+## "-property" option.
+##
+## Implementation Note: The search only includes objects with visible
+## handles ("HandleVisibility" = "on").  @xref{XREFfindall,,findall}, to
+## search for all objects including hidden ones.
+## @seealso{findall, allchild, get, set}
 ## @end deftypefn
 
 ## Author: Ben Abbott <bpabbott@mac.com>
--- a/scripts/plot/fplot.m
+++ b/scripts/plot/fplot.m
@@ -33,7 +33,7 @@
 ## given in any order.
 ## @var{tol} is the relative tolerance to use for the plot and defaults
 ## to 2e-3 (.2%).
-## @var{n} is the minimum number of of points to use.  When @var{n} is
+## @var{n} is the minimum number of points to use.  When @var{n} is
 ## specified, the maximum stepsize will be
 ## @code{@var{xhi} - @var{xlo} / @var{n}}.  More than @var{n} points may still
 ## be used in order to meet the relative tolerance requirement.
@@ -54,9 +54,9 @@
 ## @end example
 ##
 ## Note: @code{fplot} works best with continuous functions.  Functions with
-## discontinuities are unlikely to plot well.  This restriction may be
-## removed in the future.
-## @seealso{plot}
+## discontinuities are unlikely to plot well.  This restriction may be removed
+## in the future.
+## @seealso{ezplot, plot}
 ## @end deftypefn
 
 ## Author: Paul Kienzle <pkienzle@users.sf.net>
--- a/scripts/plot/gca.m
+++ b/scripts/plot/gca.m
@@ -18,9 +18,10 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {@var{h} =} gca ()
-## Return a handle to the current axis object.  If no axis object
-## exists, create one and return its handle.  The handle may then be
-## used to examine or set properties of the axes.  For example,
+## Return a handle to the current axis object.
+##
+## If no axis object exists, create one and return its handle.  The handle may
+## then be used to examine or set properties of the axes.  For example,
 ##
 ## @example
 ## @group
@@ -30,9 +31,9 @@
 ## @end example
 ##
 ## @noindent
-## creates an empty axes object, then changes its location and size in
-## the figure window.
-## @seealso{gcf, gco, get, set}
+## creates an empty axes object, then changes its location and size in the
+## figure window.
+## @seealso{gcf, gco, gcbf, gcbo, get, set}
 ## @end deftypefn
 
 ## Author: jwe
--- a/scripts/plot/gcbf.m
+++ b/scripts/plot/gcbf.m
@@ -18,13 +18,15 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {@var{fig} =} gcbf ()
-## Return a handle to the figure containing the object whose callback
-## is currently executing.  If no callback is executing, this function
-## returns the empty matrix.  The handle returned by this function is
-## the same as the second output argument of @code{gcbo}.
+## Return a handle to the figure containing the object whose callback is
+## currently executing.
 ##
-##@seealso{gcbo, gcf, gca}
-##@end deftypefn
+## If no callback is executing, this function returns the empty matrix.  The
+## handle returned by this function is the same as the second output argument
+## of @code{gcbo}.
+##
+## @seealso{gcbo, gcf, gco, gca, get, set}
+## @end deftypefn
 
 function fig = gcbf ()
 
--- a/scripts/plot/gcbo.m
+++ b/scripts/plot/gcbo.m
@@ -19,17 +19,17 @@
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {@var{h} =} gcbo ()
 ## @deftypefnx {Function File} {[@var{h}, @var{fig}] =} gcbo ()
-## Return a handle to the object whose callback is currently
-## executing.  If no callback is executing, this function returns the
-## empty matrix.  This handle is obtained from the root object property
-## "CallbackObject".
+## Return a handle to the object whose callback is currently executing.
+## 
+## If no callback is executing, this function returns the empty matrix.  This
+## handle is obtained from the root object property "CallbackObject".
 ##
 ## When called with a second output argument, return the handle of the figure
 ## containing the object whose callback is currently executing.  If no callback
 ## is executing the second output is also set to the empty matrix.
 ##
-##@seealso{gcbf, gco, gcf, gca}
-##@end deftypefn
+## @seealso{gcbf, gco, gca, gcf, get, set}
+## @end deftypefn
 
 function [h, fig] = gcbo ()
 
--- a/scripts/plot/gcf.m
+++ b/scripts/plot/gcf.m
@@ -18,9 +18,10 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {@var{h} =} gcf ()
-## Return the current figure handle.  If a figure does not exist, create
-## one and return its handle.  The handle may then be used to examine or
-## set properties of the figure.  For example,
+## Return the current figure handle.
+##
+## If a figure does not exist, create one and return its handle.  The handle
+## may then be used to examine or set properties of the figure.  For example,
 ##
 ## @example
 ## @group
@@ -34,7 +35,7 @@
 ## plots a sine wave, finds the handle of the current figure, and then
 ## makes that figure invisible.  Setting the visible property of the
 ## figure to @code{"on"} will cause it to be displayed again.
-## @seealso{gca, gco, get, set}
+## @seealso{gca, gco, gcbf, gcbo, get, set}
 ## @end deftypefn
 
 ## Author: jwe, Bill Denney
--- a/scripts/plot/gco.m
+++ b/scripts/plot/gco.m
@@ -20,23 +20,24 @@
 ## @deftypefn  {Function File} {@var{h} =} gco ()
 ## @deftypefnx {Function File} {@var{h} =} gco (@var{fig})
 ## Return a handle to the current object of the current figure, or a handle
-## to the current object of the figure with handle @var{fig}.  The current
-## object of a figure is the object that was last clicked on.  It is stored
-## in the CurrentObject property of the target figure.
+## to the current object of the figure with handle @var{fig}.
 ##
-## If the last mouse click didn't occur on any child object of the figure,
-## the current object is the figure itself.
+## The current object of a figure is the object that was last clicked on.  It
+## is stored in the "CurrentObject" property of the target figure.
+##
+## If the last mouse click did not occur on any child object of the figure,
+## then the current object is the figure itself.
 ##
 ## If no mouse click occurred in the target figure, this function returns an
 ## empty matrix.
 ##
-## Note that the value returned by this function is not necessarily the same
-## as the one returned by gcbo during callback execution.  An executing
-## callback can be interrupted by another callback and the current object
-## can be modified.
+## Programming Note: The value returned by this function is not necessarily the
+## same as the one returned by @code{gcbo} during callback execution.  An
+## executing callback can be interrupted by another callback and the current
+## object may be changed.
 ##
-##@seealso{gcbo, gcf, gca, get, set}
-##@end deftypefn
+## @seealso{gcbo, gca, gcf, gcbf, get, set}
+## @end deftypefn
 
 function h = gco ()
 
--- a/scripts/plot/ginput.m
+++ b/scripts/plot/ginput.m
@@ -17,11 +17,20 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function File} {[@var{x}, @var{y}, @var{buttons}] =} ginput (@var{n})
-## Return which mouse buttons were pressed and keys were hit on the current
-## figure.  If @var{n} is defined, then wait for @var{n} mouse clicks
-## before returning.  If @var{n} is not defined, then @code{ginput} will
-## loop until the return key @key{RET} is pressed.
+## @deftypefn  {Function File} {[@var{x}, @var{y}, @var{buttons}] =} ginput (@var{n})
+## @deftypefnx {Function File} {[@var{x}, @var{y}, @var{buttons}] =} ginput ()
+## Return the position and type of mouse button clicks and/or key strokes
+## in the current figure window.
+##
+## If @var{n} is defined, then capture @var{n} events before returning.
+## When @var{n} is not defined @code{ginput} will loop until the return key
+## @key{RET} is pressed.
+##
+## The return values @var{x}, @var{y} are the coordinates where the mouse
+## was clicked in the units of the current axes.  The return value @var{button}
+## is 1, 2, or 3 for the left, middle, or right button.  If a key is pressed
+## the ASCII value is returned in @var{button}.
+## @seealso{gtext}
 ## @end deftypefn
 
 function varargout = ginput (n)
@@ -31,14 +40,15 @@
   endif
 
   f = gcf ();
+  a = gca ();  # Create an axis, if necessary
   drawnow ();
-  toolkit = (get (f, "__graphics_toolkit__"));
+  toolkit = get (f, "__graphics_toolkit__");
 
   varargout = cell (1, nargout);
   if (nargin == 0)
-    [varargout{:}] = feval (strcat ("__", toolkit, "_ginput__"), f);
+    [varargout{:}] = feval (["__" toolkit "_ginput__"], f);
   else
-    [varargout{:}] = feval (strcat ("__", toolkit, "_ginput__"), f, n);
+    [varargout{:}] = feval (["__" toolkit "_ginput__"], f, n);
   endif
 
 endfunction
--- a/scripts/plot/graphics_toolkit.m
+++ b/scripts/plot/graphics_toolkit.m
@@ -21,23 +21,18 @@
 ## @deftypefnx {Function File} {@var{name} =} graphics_toolkit (@var{hlist})
 ## @deftypefnx {Function File} {} graphics_toolkit (@var{name})
 ## @deftypefnx {Function File} {} graphics_toolkit (@var{hlist}, @var{name})
-## Return the default graphics toolkit.  The default graphics toolkit value
-## is assigned to new figures.
-## 
-## @code{graphics_toolkit (@var{hlist})}
-## 
-## Return the graphics toolkits for the figures with handles @var{hlist}.
-## 
-## @code{graphics_toolkit (@var{name})}
+## Query or set the default graphics toolkit which is assigned to new
+## figures.
 ## 
-## Set the default graphics toolkit to @var{name}.  If the toolkit is not
-## already loaded, it is initialized by calling the function
-## @code{__init_@var{name}__}.
+## With no inputs, return the current default graphics toolkit.  If the input
+## is a list of figure graphic handles, @var{hlist}, then return the name
+## of the graphics toolkit in use for each figure.
 ## 
-## @code{graphics_toolkit (@var{hlist}, @var{name})}
-##
-## Set the graphics toolkit for the figures with handles @var{hlist} to
-## @var{name}.
+## When called with a single input @var{name} set the default graphics toolkit
+## to @var{name}.  If the toolkit is not already loaded, it is initialized by
+## calling the function @code{__init_@var{name}__}.  If the first input
+## is a list of figure handles, @var{hlist}, then the graphics toolkit is set
+## to @var{name} for these figures only.
 ## 
 ## @seealso{available_graphics_toolkits}
 ## @end deftypefn
--- a/scripts/plot/grid.m
+++ b/scripts/plot/grid.m
@@ -17,31 +17,31 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {} grid
-## @deftypefnx {Function File} {} grid on
-## @deftypefnx {Function File} {} grid off
-## @deftypefnx {Function File} {} grid minor
-## @deftypefnx {Function File} {} grid minor on
-## @deftypefnx {Function File} {} grid minor off
+## @deftypefn  {Command} {} grid
+## @deftypefnx {Command} {} grid on
+## @deftypefnx {Command} {} grid off
+## @deftypefnx {Command} {} grid minor
+## @deftypefnx {Command} {} grid minor on
+## @deftypefnx {Command} {} grid minor off
 ## @deftypefnx {Function File} {} grid (@var{hax}, @dots{})
-## Control the display of grid lines on a plot.
+## Control the display of plot grid lines.
 ##
-## The function input may be either @code{"on"}, or @code{"off"}.
+## The function state input may be either "on" or "off".
 ## If it is omitted, the current grid state is toggled.
 ##
-## If the first argument is @code{"minor"} then all further commands
+## When the first argument is "minor" all subsequent commands
 ## modify the minor grid rather than the major grid.
 ##
-## If the first argument is an axis handle, @var{hax}, operate on the
-## specified axis object.
+## If the first argument @var{hax} is an axes handle, then operate on
+## this axis rather than the current axes returned by @code{gca}.
 ##
 ## To control the grid lines for an individual axis use the @code{set}
-## function.  For example,
+## function.  For example:
 ##
 ## @example
 ## set (gca, "ygrid", "on");
 ## @end example
-## @seealso{box}
+## @seealso{axis, box}
 ## @end deftypefn
 
 ## Author: jwe
--- a/scripts/plot/gtext.m
+++ b/scripts/plot/gtext.m
@@ -20,18 +20,20 @@
 ## @deftypefn  {Function File} {} gtext (@var{s})
 ## @deftypefnx {Function File} {} gtext (@{@var{s1}, @var{s2}, @dots{}@})
 ## @deftypefnx {Function File} {} gtext (@{@var{s1}; @var{s2}; @dots{}@})
-## @deftypefnx {Function File} {} gtext (@dots{}, @var{prop}, @var{val})
+## @deftypefnx {Function File} {} gtext (@dots{}, @var{prop}, @var{val}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} gtext (@dots{})
-## Place text on the current figure using the mouse.  The text is defined
-## by the string @var{s}.  If @var{s} is a cell string organized as a row
-## vector then each string of the cell array is written to a separate line.
-## If @var{s} is organized as a column vector then one string element of the
-## cell array is placed for every mouse click.  Additional inputs besides a
-## string or cellstr are passed to the underlying text object as Property-value
-## pairs.
+## Place text on the current figure using the mouse.
+##
+## The text is defined by the string @var{s}.  If @var{s} is a cell string
+## organized as a row vector then each string of the cell array is written to a
+## separate line.  If @var{s} is organized as a column vector then one string
+## element of the cell array is placed for every mouse click.
+##
+## Optional property/value pairs are passed directly to the underlying text
+## objects.
 ##
 ## The optional return value @var{h} is a graphics handle to the created
-## text object.
+## text object(s).
 ## @seealso{ginput, text}
 ## @end deftypefn
 
--- a/scripts/plot/guidata.m
+++ b/scripts/plot/guidata.m
@@ -17,8 +17,17 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {@var{data} =} guidata (@var{handle})
-## @deftypefnx {Function File} {} guidata (@var{handle}, @var{data})
+## @deftypefn  {Function File} {@var{data} =} guidata (@var{h})
+## @deftypefnx {Function File} {} guidata (@var{h}, @var{data})
+## Query or set user-custom GUI data.
+##
+## The GUI data is stored in the figure handle @var{h}.  If @var{h} is not a
+## figure handle then it's parent figure will be used for storage.
+##
+## @var{data} must be a single object which means it is usually preferable
+## for it to be a data container such as a cell array or struct.
+##
+## @seealso{getappdata, setappdata, get, set, getpref, setpref}
 ## @end deftypefn
 
 ## Author: goffioul
--- a/scripts/plot/guihandles.m
+++ b/scripts/plot/guihandles.m
@@ -19,6 +19,8 @@
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {@var{hdata} =} guihandles (@var{handle})
 ## @deftypefnx {Function File} {@var{hdata} =} guihandles
+##   
+## @seealso{guidata, getappdata, setappdata}
 ## @end deftypefn
 
 ## Author: goffioul
--- a/scripts/plot/hdl2struct.m
+++ b/scripts/plot/hdl2struct.m
@@ -18,9 +18,10 @@
 ## @deftypefn {Function File} {@var{s} =} hdl2struct (@var{h})
 ## Return a structure, @var{s}, whose fields describe the properties
 ## of the object, and its children, associated with the handle, @var{h}.
-## The fields of the structure, @var{s}, are "type", "handle", "properties",
-## "children" and "special".
-## @seealso{findobj, get, set, struct2hdl}
+##
+## The fields of the structure @var{s} are "type", "handle", "properties",
+## "children", and "special".
+## @seealso{struct2hdl, findobj}
 ## @end deftypefn
 
 ## Author: pdiribarne <pdiribarne@new-host.home>
--- a/scripts/plot/hggroup.m
+++ b/scripts/plot/hggroup.m
@@ -18,14 +18,25 @@
 
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} hggroup ()
-## @deftypefnx {Function File} {} hggroup (@var{h})
+## @deftypefnx {Function File} {} hggroup (@var{hax})
 ## @deftypefnx {Function File} {} hggroup (@dots{}, @var{property}, @var{value}, @dots{})
-## Create group object with parent @var{h}.  If no parent is specified,
-## the group is created in the current axes.  Return the handle of the
-## group object created.
+## @deftypefnx {Function File} {@var{h} =} hggroup (@dots{})
+## Create handle graphics group object with axes parent @var{hax}.
+##
+## If no parent is specified, the group is created in the current axes.
+##
+## Multiple property-value pairs may be specified for the hggroup, but they
+## must appear in pairs.
 ##
-## Multiple property-value pairs may be specified for the group, but they
-## must appear in pairs.
+## The optional return value @var{h} is a graphics handle to the created
+## hggroup object.
+##
+## Programming Note: An hggroup is a way to group base graphics objects such
+## as line objects or patch objects into a single unit which can react
+## appropriately.  For example, the individual lines of a contour plot are
+## collected into a single hggroup so that they can be made visible/invisible
+## with a single command, @code{set (hg_handle, "visible", "off")}.
+## 
 ## @end deftypefn
 
 ## Author: goffioul
--- a/scripts/plot/hidden.m
+++ b/scripts/plot/hidden.m
@@ -17,10 +17,10 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {} hidden ()
-## @deftypefnx {Function File} {} hidden ("on")
-## @deftypefnx {Function File} {} hidden ("off")
-## @deftypefnx {Function File} {@var{state} =} hidden (@dots{})
+## @deftypefn  {Command} {} hidden
+## @deftypefnx {Command} {} hidden "on"
+## @deftypefnx {Command} {} hidden "off"
+## @deftypefnx {Function File} {@var{mode} =} hidden (@dots{})
 ## Control mesh hidden line removal.
 ##
 ## When called with no argument the hidden line removal state is toggled.
@@ -34,7 +34,7 @@
 ## objects behind the mesh can be seen through the faces (openings) of the
 ## mesh, although the mesh grid lines are still opaque.
 ##
-## @seealso{mesh, meshc, meshz, ezmesh, ezmeshc}
+## @seealso{mesh, meshc, meshz, ezmesh, ezmeshc, trimesh, waterfall}
 ## @end deftypefn
 
 function state = hidden (mode = "toggle")
--- a/scripts/plot/hist.m
+++ b/scripts/plot/hist.m
@@ -23,7 +23,6 @@
 ## @deftypefnx {Function File} {} hist (@var{y}, @var{x}, @var{norm})
 ## @deftypefnx {Function File} {[@var{nn}, @var{xx}] =} hist (@dots{})
 ## @deftypefnx {Function File} {[@dots{}] =} hist (@dots{}, @var{prop}, @var{val})
-##
 ## Produce histogram counts or plots.
 ##
 ## With one vector input argument, @var{y}, plot a histogram of the values
@@ -65,7 +64,7 @@
 ## @end group
 ## @end example
 ##
-## @seealso{bar}
+## @seealso{histc, bar, pie, rose}
 ## @end deftypefn
 
 ## Author: jwe
--- a/scripts/plot/hold.m
+++ b/scripts/plot/hold.m
@@ -44,8 +44,11 @@
 ## Toggle the current hold state.
 ## @end table
 ##
+## If the first argument @var{hax} is an axes handle, 
+## rather than the current axes returned by @code{gca}.
+##
 ## When given the additional argument @var{hax}, the hold state is modified
-## only for the given axis handle.
+## for this axis rather than the current axes returned by @code{gca}.
 ##
 ## To query the current hold state use the @code{ishold} function.
 ## @seealso{ishold, cla, clf, newplot}
--- a/scripts/plot/ishghandle.m
+++ b/scripts/plot/ishghandle.m
@@ -18,9 +18,10 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {} ishghandle (@var{h})
-## Return true if @var{h} is a graphics handle and false otherwise.  This
-## function is equivalent to @code{ishandle} and is provided for compatibility
-## with @sc{matlab}.
+## Return true if @var{h} is a graphics handle and false otherwise.
+##
+## This function is equivalent to @code{ishandle} and is provided for
+## compatibility with @sc{matlab}.
 ## @seealso{ishandle}
 ## @end deftypefn
 
--- a/scripts/plot/ishold.m
+++ b/scripts/plot/ishold.m
@@ -18,13 +18,14 @@
 
 ## -*- texinfo -*-
 ## @deftypefn  {Command} {} ishold
-## @deftypefnx {Function File} {} ishold (@var{h})
+## @deftypefnx {Function File} {} ishold (@var{hax})
+## @deftypefnx {Function File} {} ishold (@var{hfig})
 ## Return true if the next plot will be added to the current plot, or
 ## false if the plot device will be cleared before drawing the next plot.
 ##
-## Optionally, operate on the graphics handle @var{h} rather than the current
-## plot.
-## @seealso{hold}
+## If the first argument is an axes handle @var{hax} or figure handle
+## @var{hfig} then operate on this plot rather than the current one.
+## @seealso{hold, newplot}
 ## @end deftypefn
 
 function retval = ishold (h)
--- a/scripts/plot/isocolors.m
+++ b/scripts/plot/isocolors.m
@@ -93,7 +93,6 @@
 ## @end example
 ##
 ## @seealso{isosurface, isonormals}
-##
 ## @end deftypefn
 
 ## Author: Martin Helm <martin@mhelm.de>
--- a/scripts/plot/isprop.m
+++ b/scripts/plot/isprop.m
@@ -25,7 +25,7 @@
 ## Author: Ben Abbott  <bpabbott@mac.com>
 
 function res = isprop (h, prop)
-  ## Check input
+
   if (nargin < 1 || nargin > 2)
     print_usage ();
   endif
--- a/scripts/plot/legend.m
+++ b/scripts/plot/legend.m
@@ -28,13 +28,16 @@
 ## @deftypefnx {Function File} {} legend ("@var{option}")
 ## @deftypefnx {Function File} {[@var{hleg}, @var{hleg_obj}, @var{hplot}, @var{labels}] =} legend (@dots{})
 ##
-## Display a legend for the axes with handle @var{hax}, or the current axes,
-## using the specified strings as labels.  Legend entries may be specified
-## as individual character string arguments, a character array, or a cell
-## array of character strings.  If the handles, @var{hobjs}, are not specified
-## then the legend's strings will be associated with the axes' descendants.
-## @code{legend} works on line graphs, bar graphs, etc.
-## A plot must exist before legend is called.
+## Display a legend for the current axes using the specified strings as labels.
+##
+## Legend entries may be specified as individual character string arguments,
+## a character array, or a cell array of character strings.
+##
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.  If the handles,
+## @var{hobjs}, are not specified then the legend's strings will be associated
+## with the axes' descendants.  @code{legend} works on line graphs,
+## bar graphs, etc.  A plot must exist before legend is called.
 ##
 ## The optional parameter @var{pos} specifies the location of the legend
 ## as follows:
@@ -102,7 +105,7 @@
 ## @item "right"
 ##   Place label text to the right of the keys
 ##
-## @item  "off"
+## @item "off"
 ##   Delete the legend object
 ## @end table
 ##
@@ -126,6 +129,10 @@
 ## is taken from the DisplayName property of graphics objects.  If no
 ## labels or DisplayNames are available, then the label text is simply
 ## "data1", "data2", @dots{}, @nospell{"dataN"}.
+##
+## Implementation Note: A legend is implemented as an additional axes object
+## of the current figure with the "tag" set to "legend".  Properties of the
+## legend object may be manipulated directly by using @code{set}.
 ## @end deftypefn
 
 function [hlegend2, hobjects2, hplot2, text_strings2] = legend (varargin)
--- a/scripts/plot/line.m
+++ b/scripts/plot/line.m
@@ -23,6 +23,7 @@
 ## @deftypefnx {Function File} {} line (@var{x}, @var{y}, @var{z})
 ## @deftypefnx {Function File} {} line (@var{x}, @var{y}, @var{z}, @var{property}, @var{value}, @dots{})
 ## @deftypefnx {Function File} {} line (@var{property}, @var{value}, @dots{})
+## @deftypefnx {Function File} {} line (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} line (@dots{})
 ## Create line object from @var{x} and @var{y} (and possibly @var{z}) and
 ## insert in the current axes.
@@ -30,6 +31,9 @@
 ## Multiple property-value pairs may be specified for the line object, but they
 ## must appear in pairs.
 ##
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
+##
 ## The optional return value @var{h} is a graphics handle (or vector of handles)
 ## to the line objects created.
 ##
--- a/scripts/plot/linkprop.m
+++ b/scripts/plot/linkprop.m
@@ -17,13 +17,16 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function File} {@var{hlink} =} linkprop (@var{h}, @var{prop})
+## @deftypefn  {Function File} {@var{hlink} =} linkprop (@var{h}, @var{prop})
+## @deftypefnx {Function File} {@var{hlink} =} linkprop (@var{h}, @{@var{prop1}, @var{prop2}, @dots{}@})
 ## Link graphics object properties, such that a change in one is
-## propagated to the others.  The properties to link are given as a
-## string of cell string array by @var{prop} and the objects containing
-## these properties by the handle array @var{h}.
+## propagated to the others.
 ##
-## An example of the use of linkprop is
+## @var{prop} can be a string for a single property, or a cell array of strings
+## for multiple properties.  @var{h} is an array of graphics handles which
+## will have their properties linked.
+##
+## An example of the use of @code{linkprop} is
 ##
 ## @example
 ## @group
--- a/scripts/plot/loglog.m
+++ b/scripts/plot/loglog.m
@@ -19,14 +19,18 @@
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} loglog (@var{y})
 ## @deftypefnx {Function File} {} loglog (@var{x}, @var{y})
-## @deftypefnx {Function File} {} loglog (@var{x}, @var{y}, @var{property}, @var{value}, @dots{})
+## @deftypefnx {Function File} {} loglog (@var{x}, @var{y}, @var{prop}, @var{value}, @dots{})
 ## @deftypefnx {Function File} {} loglog (@var{x}, @var{y}, @var{fmt})
-## @deftypefnx {Function File} {} loglog (@var{h}, @dots{})
+## @deftypefnx {Function File} {} loglog (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} loglog (@dots{})
-## Produce a two-dimensional plot using log scales for both axes.  See
-## the documentation of @code{plot} for a description of the arguments
+## Produce a 2-D plot using logarithmic scales for both axes.
+##
+## See the documentation of @code{plot} for a description of the arguments
 ## that @code{loglog} will accept.
 ##
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
+##
 ## The optional return value @var{h} is a graphics handle to the created plot.
 ## @seealso{plot, semilogx, semilogy}
 ## @end deftypefn
--- a/scripts/plot/loglogerr.m
+++ b/scripts/plot/loglogerr.m
@@ -18,9 +18,9 @@
 
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} loglogerr (@var{args})
-## @deftypefnx {Function File} {@var{h} =} loglogerr (@var{args})
-## Produce two-dimensional plots on a double logarithm axis with
-## errorbars.
+## @deftypefnx {Function File} {} loglogerr (@var{hax}, @dots{})
+## @deftypefnx {Function File} {@var{h} =} loglogerr (@dots{})
+## Produce 2-D plots on a double logarithm axis with errorbars.
 ##
 ## Many different combinations of arguments are possible.  The most common
 ## form is
@@ -32,8 +32,8 @@
 ## @noindent
 ## which produces a double logarithm plot of @var{y} versus @var{x}
 ## with errors in the @var{y}-scale defined by @var{ey} and the plot
-## format defined by @var{fmt}.  See @code{errorbar} for available formats and
-## additional information.
+## format defined by @var{fmt}.  @xref{XREFerrorbar,,errorbar}, for available
+## formats and additional information.
 ## @seealso{errorbar, semilogxerr, semilogyerr}
 ## @end deftypefn
 
--- a/scripts/plot/mesh.m
+++ b/scripts/plot/mesh.m
@@ -20,22 +20,37 @@
 ## @deftypefn  {Function File} {} mesh (@var{x}, @var{y}, @var{z})
 ## @deftypefnx {Function File} {} mesh (@var{z})
 ## @deftypefnx {Function File} {} mesh (@dots{}, @var{c})
+## @deftypefnx {Function File} {} mesh (@dots{}, @var{prop}, @var{val}, @dots{})
 ## @deftypefnx {Function File} {} mesh (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} mesh (@dots{})
-## Plot a mesh given matrices @var{x}, and @var{y} from @code{meshgrid} and
-## a matrix @var{z} corresponding to the @var{x} and @var{y} coordinates of
-## the mesh.  If @var{x} and @var{y} are vectors, then a typical vertex
-## is (@var{x}(j), @var{y}(i), @var{z}(i,j)).  Thus, columns of @var{z}
-## correspond to different @var{x} values and rows of @var{z} correspond
-## to different @var{y} values.
+## Plot a 3-D wireframe mesh.
+##
+## The wireframe mesh is plotted using rectangles.  The vertices of the
+## rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}.
+## over a 2-D rectangular region in the x-y plane.  @var{z} determines the
+## height above the plane of each vertex.  If only a single @var{z} matrix is
+## given, then it is plotted over the meshgrid
+## @code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}.
+## Thus, columns of @var{z} correspond to different @var{x} values and rows
+## of @var{z} correspond to different @var{y} values.  
 ##
-## The color of the mesh is derived from the @code{colormap}
-## and the value of @var{z}.  Optionally the color of the mesh can be
-## specified independent of @var{z}, by adding a fourth matrix, @var{c}.
+## The color of the mesh is computed by linearly scaling the @var{Z} values
+## to fit the range of the current colormap.  Use @code{caxis} and/or
+## change the colormap to control the appearance.
+##
+## Optionally, the color of the mesh can be specified independently of @var{z}
+## by supplying a color matrix, @var{c}.
+##
+## Any property/value pairs are passed directly to the underlying surface
+## object.
+##
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a graphics handle to the created
 ## surface object.
-## @seealso{colormap, contour, meshgrid, surf}
+##
+## @seealso{ezmesh, meshc, meshz, trimesh, contour, surf, surface, meshgrid, hidden, shading, colormap, caxis}
 ## @end deftypefn
 
 ## Author: jwe
--- a/scripts/plot/meshc.m
+++ b/scripts/plot/meshc.m
@@ -17,14 +17,40 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function File} {} meshc (@var{x}, @var{y}, @var{z})
-## Plot a mesh and contour given matrices @var{x}, and @var{y} from
-## @code{meshgrid} and a matrix @var{z} corresponding to the @var{x} and
-## @var{y} coordinates of the mesh.  If @var{x} and @var{y} are vectors,
-## then a typical vertex is (@var{x}(j), @var{y}(i), @var{z}(i,j)).  Thus,
-## columns of @var{z} correspond to different @var{x} values and rows of
-## @var{z} correspond to different @var{y} values.
-## @seealso{meshgrid, mesh, contour}
+## @deftypefn  {Function File} {} meshc (@var{x}, @var{y}, @var{z})
+## @deftypefnx {Function File} {} meshc (@var{z})
+## @deftypefnx {Function File} {} meshc (@dots{}, @var{c})
+## @deftypefnx {Function File} {} meshc (@dots{}, @var{prop}, @var{val}, @dots{})
+## @deftypefnx {Function File} {} meshc (@var{hax}, @dots{})
+## @deftypefnx {Function File} {@var{h} =} meshc (@dots{})
+## Plot a 3-D wireframe mesh with underlying contour lines.
+##
+## The wireframe mesh is plotted using rectangles.  The vertices of the
+## rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}.
+## over a 2-D rectangular region in the x-y plane.  @var{z} determines the
+## height above the plane of each vertex.  If only a single @var{z} matrix is
+## given, then it is plotted over the meshgrid
+## @code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}.
+## Thus, columns of @var{z} correspond to different @var{x} values and rows
+## of @var{z} correspond to different @var{y} values.  
+## 
+## The color of the mesh is computed by linearly scaling the @var{Z} values
+## to fit the range of the current colormap.  Use @code{caxis} and/or
+## change the colormap to control the appearance.
+##
+## Optionally the color of the mesh can be specified independently of @var{z}
+## by supplying a color matrix, @var{c}.
+##
+## Any property/value pairs are passed directly to the underlying surface
+## object.
+##
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
+##
+## The optional return value @var{h} is a 2-element vector with a graphics
+## handle to the created surface object and to the created contour plot.
+##
+## @seealso{ezmeshc, mesh, meshz, contour, surfc, surface, meshgrid, hidden, shading, colormap, caxis}
 ## @end deftypefn
 
 function h = meshc (varargin)
--- a/scripts/plot/meshgrid.m
+++ b/scripts/plot/meshgrid.m
@@ -17,9 +17,10 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {[@var{xx}, @var{yy}, @var{zz}] =} meshgrid (@var{x}, @var{y}, @var{z})
-## @deftypefnx {Function File} {[@var{xx}, @var{yy}] =} meshgrid (@var{x}, @var{y})
+## @deftypefn  {Function File} {[@var{xx}, @var{yy}] =} meshgrid (@var{x}, @var{y})
+## @deftypefnx {Function File} {[@var{xx}, @var{yy}, @var{zz}] =} meshgrid (@var{x}, @var{y}, @var{z})
 ## @deftypefnx {Function File} {[@var{xx}, @var{yy}] =} meshgrid (@var{x})
+## @deftypefnx {Function File} {[@var{xx}, @var{yy}, @var{zz}] =} meshgrid (@var{x})
 ## Given vectors of @var{x} and @var{y} and @var{z} coordinates, and
 ## returning 3 arguments, return three-dimensional arrays corresponding
 ## to the @var{x}, @var{y}, and @var{z} coordinates of a mesh.  When
@@ -28,7 +29,7 @@
 ## copies of @var{x}, and the columns of @var{yy} are copies of @var{y}.
 ## If @var{y} is omitted, then it is assumed to be the same as @var{x},
 ## and @var{z} is assumed the same as @var{y}.
-## @seealso{mesh, contour}
+## @seealso{ndgrid, mesh, contour, surf}
 ## @end deftypefn
 
 ## Author: jwe
--- a/scripts/plot/meshz.m
+++ b/scripts/plot/meshz.m
@@ -17,14 +17,40 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function File} {} meshz (@var{x}, @var{y}, @var{z})
-## Plot a curtain mesh given matrices @var{x}, and @var{y} from
-## @code{meshgrid} and a matrix @var{z} corresponding to the @var{x} and
-## @var{y} coordinates of the mesh.  If @var{x} and @var{y} are vectors,
-## then a typical vertex is (@var{x}(j), @var{y}(i), @var{z}(i,j)).  Thus,
-## columns of @var{z} correspond to different @var{x} values and rows of
-## @var{z} correspond to different @var{y} values.
-## @seealso{meshgrid, mesh, contour}
+## @deftypefn  {Function File} {} meshz (@var{x}, @var{y}, @var{z})
+## @deftypefnx {Function File} {} meshz (@var{z})
+## @deftypefnx {Function File} {} meshz (@dots{}, @var{c})
+## @deftypefnx {Function File} {} meshz (@dots{}, @var{prop}, @var{val}, @dots{})
+## @deftypefnx {Function File} {} meshz (@var{hax}, @dots{})
+## @deftypefnx {Function File} {@var{h} =} meshz (@dots{})
+## Plot a 3-D wireframe mesh with a surrounding curtain.
+##
+## The wireframe mesh is plotted using rectangles.  The vertices of the
+## rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}.
+## over a 2-D rectangular region in the x-y plane.  @var{z} determines the
+## height above the plane of each vertex.  If only a single @var{z} matrix is
+## given, then it is plotted over the meshgrid
+## @code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}.
+## Thus, columns of @var{z} correspond to different @var{x} values and rows
+## of @var{z} correspond to different @var{y} values.  
+##
+## The color of the mesh is computed by linearly scaling the @var{Z} values
+## to fit the range of the current colormap.  Use @code{caxis} and/or
+## change the colormap to control the appearance.
+##
+## Optionally the color of the mesh can be specified independently of @var{z}
+## by supplying a color matrix, @var{c}.
+##
+## Any property/value pairs are passed directly to the underlying surface
+## object.
+##
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
+##
+## The optional return value @var{h} is a graphics handle to the created
+## surface object.
+##
+## @seealso{mesh, meshc, contour, surf, surface, waterfall, meshgrid, hidden, shading, colormap, caxis}
 ## @end deftypefn
 
 function h = meshz (varargin)
--- a/scripts/plot/newplot.m
+++ b/scripts/plot/newplot.m
@@ -56,9 +56,10 @@
 ## plot, but preserves special settings such as log scaling for axes.
 ## This is equivalent to @code{cla}.
 ##
-## @item "replace" (default) @tab Delete all child objects of the axis and reset all axis
-## properties to their defaults.  However, the following properties
-## are not reset: Position, Units.  This is equivalent to @code{cla reset}.
+## @item "replace" (default) @tab Delete all child objects of the axis and
+## reset all axis properties to their defaults.  However, the following
+## properties are not reset: Position, Units.  This is equivalent to
+## @code{cla reset}.
 ##
 ## @end multitable    
 ##
@@ -76,7 +77,7 @@
 ##        which are not deleted when the figure and axes are prepared.
 ##        I'm sure there is a good reason for that, but coding such
 ##        compatibility is really tricky and doesn't serve much purpose since
-##        newplot is nearly exclusively used by Octave internal plotting
+##        newplot is nearly exclusively used by Octave's internal plotting
 ##        functions.  In Octave's case the argument is almost always null,
 ##        or occasionally the axis handle to plot into.
 
--- a/scripts/plot/orient.m
+++ b/scripts/plot/orient.m
@@ -17,15 +17,22 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function File} {} orient (@var{orientation})
-## Set the default print orientation.  Valid values for
-## @var{orientation} include @code{"landscape"}, @code{"portrait"},
-## and @code{"tall"}.
+## @deftypefn  {Function File} {} orient (@var{orientation})
+## @deftypefnx {Function File} {} orient (@var{hfig}, @var{orientation})
+## @deftypefnx {Function File} {@var{orientation} =} orient ()
+## @deftypefnx {Function File} {@var{orientation} =} orient (@var{hfig})
+## Query or set the default print orientation.
+##
+## Valid values for @var{orientation} are "landscape", "portrait", and "tall".
 ##
-## The @code{"tall"} option sets the orientation to portait and fills
-## the page with the plot, while leaving a 0.25in border.
+## The "tall" option sets the orientation to portait and fills
+## the page with the plot, while leaving a 0.25 inch border.
 ##
-## If called with no arguments, return the default print orientation.
+## When called with no arguments, return the default print orientation.
+##
+## If the first argument @var{hfig} is a figure handle, then operate on this
+## figure rather than the current figure returned by @code{gcf}.
+## @seealso{print, saveas}
 ## @end deftypefn
 
 ## Author: Paul Kienzle
@@ -49,8 +56,8 @@
     orientation = varargin{1};
     if (strcmpi (orientation, "landscape") || strcmpi (orientation, "portrait"))
       if (! strcmpi (get (cf, "paperorientation"), orientation))
-        ## FIXME - with the proper listeners in place there won't be a need to set
-        ##         the papersize and paperpostion here.
+        ## FIXME: with the proper listeners in place there won't be a need to
+        ##        set the papersize and paperpostion here.
         papersize = get (cf, "papersize");
         paperposition = get (cf, "paperposition");
         set (cf, "paperorientation", orientation);
--- a/scripts/plot/pareto.m
+++ b/scripts/plot/pareto.m
@@ -18,29 +18,33 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {} pareto (@var{x})
-## @deftypefnx {Function File} {} pareto (@var{x}, @var{y})
-## @deftypefnx {Function File} {} pareto (@var{h}, @dots{})
+## @deftypefn  {Function File} {} pareto (@var{y})
+## @deftypefnx {Function File} {} pareto (@var{y}, @var{x})
+## @deftypefnx {Function File} {} pareto (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} pareto (@dots{})
-## Draw a Pareto chart, also called ABC chart.  A Pareto chart is a bar graph
-## used to arrange information in such a way that priorities for process
-## improvement can be established.  It organizes and displays information
-## to show the relative importance of data.  The chart is similar to the
-## histogram or bar chart, except that the bars are arranged in decreasing
-## order from left to right along the abscissa.
+## Draw a Pareto chart.
+##
+## A Pareto chart is a bar graph that arranges information in such a way
+## that priorities for process improvement can be established;  It organizes
+## and displays information to show the relative importance of data.  The chart
+## is similar to the histogram or bar chart, except that the bars are arranged
+## in decreasing magnitude from left to right along the x-axis.
 ##
 ## The fundamental idea (Pareto principle) behind the use of Pareto
 ## diagrams is that the majority of an effect is due to a small subset of the
-## causes, so for quality improvement the first few (as presented on the
-## diagram) contributing causes to a problem usually account for the majority
-## of the result.  Thus, targeting these "major causes" for elimination
-## results in the most cost-effective improvement scheme.
+## causes.  For quality improvement, the first few contributing causes 
+## (leftmost bars as presented on the diagram) to a problem usually account for
+## the majority of the result.  Thus, targeting these "major causes" for
+## elimination results in the most cost-effective improvement scheme.
 ##
-## The data are passed as @var{x} and the abscissa as @var{y}.  If @var{y} is
-## absent, then the abscissa are assumed to be @code{1 : length (@var{x})}.
-## @var{y} can be a string array, a cell array of strings, or a numerical
+## Typically only the magnitude data @var{y} is present in which case
+## @var{x} is taken to be the range @code{1 : length (@var{y})}.  If @var{x}
+## is given it may be a string array, a cell array of strings, or a numerical
 ## vector.
 ##
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
+##
 ## The optional return value @var{h} is a 2-element vector with a graphics
 ## handle for the created bar plot and a second handle for the created line
 ## plot.
@@ -55,7 +59,7 @@
 ## pareto (Sold, Cheese);
 ## @end group
 ## @end example
-## @seealso{bar, barh, pie, plot}
+## @seealso{bar, barh, hist, pie, plot}
 ## @end deftypefn
 
 function h = pareto (varargin)
--- a/scripts/plot/patch.m
+++ b/scripts/plot/patch.m
@@ -21,29 +21,58 @@
 ## @deftypefnx {Function File} {} patch (@var{x}, @var{y}, @var{c})
 ## @deftypefnx {Function File} {} patch (@var{x}, @var{y}, @var{z}, @var{c})
 ## @deftypefnx {Function File} {} patch (@var{fv})
-## @deftypefnx {Function File} {} patch ("Faces", @var{f}, "Vertices", @var{v}, @dots{})
-## @deftypefnx {Function File} {} patch (@dots{}, @var{prop}, @var{val})
-## @deftypefnx {Function File} {} patch (@var{h}, @dots{})
+## @deftypefnx {Function File} {} patch ("Faces", @var{faces}, "Vertices", @var{verts}, @dots{})
+## @deftypefnx {Function File} {} patch (@dots{}, @var{prop}, @var{val}, @dots{})
+## @deftypefnx {Function File} {} patch (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} patch (@dots{})
-## Create patch object from @var{x} and @var{y} with color @var{c} and
-## insert in the current axes object.  Return handle to patch object.
+## Create patch object in the current axes with vertices at locations
+## (@var{x}, @var{y}) and of color @var{c}.
+##
+## If the vertices are matrices of size @nospell{MxN} then each polygon patch
+## has M vertices and a total of N polygons will be created.  If some polygons
+## do not have M vertices use NaN to represent "no vertex".  If the @var{z}
+## input is present then 3-D patches will be created.
+##
+## The color argument @var{c} can take many forms.  To create polygons
+## which all share a single color use a string value (e.g., "r" for
+## red), a scalar value which is scaled by @code{caxis} and indexed into the
+## current colormap, or a 3-element RGB vector with the precise TrueColor.
 ##
-## For a uniform colored patch, @var{c} can be given as an RGB vector,
-## scalar value referring to the current colormap, or string value (for
-## example, "r" or "red").
+## If @var{c} is a vector of length N then the ith polygon will have a color
+## determined by scaling entry @var{c}(i) according to @code{caxis} and then
+## indexing into the current colormap.  More complicated coloring situations
+## require directly manipulating patch property/value pairs.
 ##
-## If passed a structure @var{fv} contain the fields "vertices", "faces"
-## and optionally "facevertexcdata", create the patch based on these
-## properties.
+## Instead of specifying polygons by matrices @var{x} and @var{y}, it is
+## possible to present a unique list of vertices and then a list of polygon
+## faces created from those vertices.  In this case the "Vertices" matrix will
+## be an @nospell{Nx2} (2-D patch) or @nospell{Nx3} (3-D path).  The
+## @nospell{MxN} "Faces" matrix describes M polygons having N vertices---each
+## row describes a single polygon and each column entry is an index into the
+## "Vertices" matrix to identify a vertex.  The patch object can be created by
+## directly passing the property/value pairs "Vertices"/@var{verts},
+## "Faces"/@var{faces} as inputs.
+##
+## A third input form is to create a structure @var{fv} with the fields
+## "vertices", "faces", and optionally "facevertexcdata".
+##
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a graphics handle to the created patch
 ## object.
-## @seealso{fill}
+##
+## Implementation Note: Patches are highly configurable objects.  To truly
+## customize them requires setting patch properties directly.  Useful patch
+## properties are: "cdata", "edgecolor", "facecolor", "faces",
+## "facevertexcdata",
+##
+## @seealso{fill, get, set}
 ## @end deftypefn
 
 ## Author: jwe
 
-function retval = patch (varargin)
+function h = patch (varargin)
 
   [hax, varargin] = __plt_get_axis_arg__ ("patch", varargin{:});
   
@@ -58,7 +87,7 @@
   endif
 
   if (nargout > 0)
-    retval = htmp;
+    h = htmp;
   endif
 
 endfunction
--- a/scripts/plot/pcolor.m
+++ b/scripts/plot/pcolor.m
@@ -21,7 +21,7 @@
 ## @deftypefnx {Function File} {} pcolor (@var{c})
 ## @deftypefnx {Function File} {} pcolor (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} pcolor (@dots{})
-## Produce a 2D density plot.
+## Produce a 2-D density plot.
 ##
 ## A @code{pcolor} plot draws rectangles with colors from the matrix @var{c}
 ## over the two-dimensional region represented by the matrices @var{x} and
@@ -45,8 +45,8 @@
 ## "faceted", which renders a single color for each cell's face with the edge
 ## visible.
 ##
-## If the first argument @var{hax} is an axis handle, then plot into this axis,
-## rather than the current axis handle returned by @code{gca}.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a graphics handle to the created
 ## surface object.
--- a/scripts/plot/peaks.m
+++ b/scripts/plot/peaks.m
@@ -22,11 +22,12 @@
 ## @deftypefnx {Function File} {} peaks (@var{x}, @var{y})
 ## @deftypefnx {Function File} {@var{z} =} peaks (@dots{})
 ## @deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} peaks (@dots{})
-## Generate a function with lots of local maxima and minima.  The function
-## has the form
+## Plot a function with lots of local maxima and minima.
+##
+## The function has the form
 ##
 ## @tex
-## $f(x,y) = 3 (1 - x) ^ 2 e ^ {\left(-x^2 - (y+1)^2\right)} - 10 \left({x \over 5} - x^3 - y^5)\right) - {1 \over 3} e^{\left(-(x+1)^2 - y^2\right)}$
+## $$f(x,y) = 3 (1 - x) ^ 2 e ^ {\left(-x^2 - (y+1)^2\right)} - 10 \left({x \over 5} - x^3 - y^5)\right) - {1 \over 3} e^{\left(-(x+1)^2 - y^2\right)}$$
 ## @end tex
 ## @ifnottex
 ## @verbatim
@@ -37,14 +38,21 @@
 ## @end ifnottex
 ##
 ## Called without a return argument, @code{peaks} plots the surface of the
-## above function using @code{mesh}.  If @var{n} is a scalar, the @code{peaks}
-## returns the values of the above function on a @var{n}-by-@var{n} mesh over
-## the range @code{[-3,3]}.  The default value for @var{n} is 49.
+## above function using @code{surf}.
+## 
+## If @var{n} is a scalar, @code{peaks} plots the value of the above
+## function on an @var{n}-by-@var{n} mesh over the range [-3,3].  The
+## default value for @var{n} is 49.
 ##
-## If @var{n} is a vector, then it represents the @var{x} and @var{y} values
-## of the grid on which to calculate the above function.  The @var{x} and
-## @var{y} values can be specified separately.
-## @seealso{surf, mesh, meshgrid}
+## If @var{n} is a vector, then it represents the grid values over which
+## to calculate the function.  If @var{x} and @var{y} are specified then
+## the function value is calculated over the specified grid of vertices.
+##
+## When called with output arguments, return the data for the function
+## evaluated over the meshgrid.  This can subsequently be plotted with
+## @code{surf (@var{x}, @var{y}, @var{z})}.
+## 
+## @seealso{sombrero, meshgrid, mesh, surf}
 ## @end deftypefn
 
 ## Expression for the peaks function was taken from the following paper:
--- a/scripts/plot/pie.m
+++ b/scripts/plot/pie.m
@@ -35,8 +35,8 @@
 ## The optional input @var{labels} is a cell array of strings of the same
 ## length as @var{x} specifying the label for each slice.
 ## 
-## If the first argument @var{hax} is an axis handle, then plot into these axes,
-## rather than the current axis handle returned by @code{gca}.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a list of handles to the patch
 ## and text objects generating the plot.
--- a/scripts/plot/pie3.m
+++ b/scripts/plot/pie3.m
@@ -36,11 +36,11 @@
 ## The optional input @var{labels} is a cell array of strings of the same
 ## length as @var{x} specifying the label for each slice.
 ##
-## If the first argument @var{hax} is an axis handle, then plot into these axes,
-## rather than the current axis handle returned by @code{gca}.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
-## The optional return value @var{h} is a list of graphics handles to the patch,
-## surface, and text objects generating the plot.
+## The optional return value @var{h} is a list of graphics handles to the
+## patch, surface, and text objects generating the plot.
 ##
 ## Note: If @code{sum (@var{x}) @leq{} 1} then the elements of @var{x} are
 ## interpreted as percentages directly and are not normalized by @code{sum (x)}.
--- a/scripts/plot/plot.m
+++ b/scripts/plot/plot.m
@@ -21,9 +21,9 @@
 ## @deftypefnx {Function File} {} plot (@var{x}, @var{y})
 ## @deftypefnx {Function File} {} plot (@var{x}, @var{y}, @var{property}, @var{value}, @dots{})
 ## @deftypefnx {Function File} {} plot (@var{x}, @var{y}, @var{fmt})
-## @deftypefnx {Function File} {} plot (@var{h}, @dots{})
+## @deftypefnx {Function File} {} plot (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} plot (@dots{})
-## Produce two-dimensional plots.
+## Produce 2-D plots.
 ##
 ## Many different combinations of arguments are possible.  The simplest
 ## form is
@@ -94,7 +94,7 @@
 ## @end itemize
 ##
 ## Multiple property-value pairs may be specified, but they must appear
-## in pairs.  These arguments are applied to the lines drawn by
+## in pairs.  These arguments are applied to the line objects drawn by
 ## @code{plot}.
 ##
 ## If the @var{fmt} argument is supplied, it is interpreted as
@@ -125,7 +125,7 @@
 ## @item ";title;"
 ## Here @code{"title"} is the label for the key.
 ##
-## @item +
+## @item  +
 ## @itemx *
 ## @itemx o
 ## @itemx x
@@ -170,13 +170,13 @@
 ## This will plot the cosine and sine functions and label them accordingly
 ## in the key.
 ##
-## If the first argument is an axis handle, then plot into these axes,
-## rather than the current axis handle returned by @code{gca}.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
-## The optional return value @var{h} is a graphics handle to the created plot.
+## The optional return value @var{h} is a vector of graphics handles to
+## the created line objects.
 ##
-## @seealso{semilogx, semilogy, loglog, polar, mesh, contour, bar,
-## stairs, errorbar, xlabel, ylabel, title, print}
+## @seealso{axis, box, grid, hold, legend, title, xlabel, ylabel, xlim, ylim, ezplot, errorbar, fplot, line, plot3, polar, loglog, semilogx, semilogy, subplot}
 ## @end deftypefn
 
 ## Author: jwe
--- a/scripts/plot/plot3.m
+++ b/scripts/plot/plot3.m
@@ -18,13 +18,13 @@
 
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} plot3 (@var{x}, @var{y}, @var{z})
-## @deftypefnx {Function File} {} plot3 (@var{x}, @var{y}, @var{z}, @var{property}, @var{value}, @dots{})
+## @deftypefnx {Function File} {} plot3 (@var{x}, @var{y}, @var{z}, @var{prop}, @var{value}, @dots{})
 ## @deftypefnx {Function File} {} plot3 (@var{x}, @var{y}, @var{z}, @var{fmt})
 ## @deftypefnx {Function File} {} plot3 (@var{x}, @var{cplx})
 ## @deftypefnx {Function File} {} plot3 (@var{cplx})
 ## @deftypefnx {Function File} {} plot3 (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} plot3 (@dots{})
-## Produce three-dimensional plots.
+## Produce 3-D plots.
 ##
 ## Many different combinations of arguments are possible.  The simplest
 ## form is
@@ -81,12 +81,12 @@
 ## objects drawn by @code{plot3}.  If the @var{fmt} argument is supplied it
 ## will format the line objects in the same manner as @code{plot}.
 ##
-## If the first argument is an axis handle @var{hax}, then plot into these axes,
-## rather than the current axis handle returned by @code{gca}.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a graphics handle to the created plot.
 ##
-## An example of the use of @code{plot3} is
+## Example:
 ##
 ## @example
 ## @group
--- a/scripts/plot/plotmatrix.m
+++ b/scripts/plot/plotmatrix.m
@@ -22,9 +22,10 @@
 ## @deftypefnx {Function File} {} plotmatrix (@dots{}, @var{style})
 ## @deftypefnx {Function File} {} plotmatrix (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {[@var{h}, @var{ax}, @var{bigax}, @var{p}, @var{pax}] =} plotmatrix (@dots{})
-## Scatter plot of the columns of one matrix against another.  Given the
-## arguments @var{x} and @var{y}, that have a matching number of rows,
-## @code{plotmatrix} plots a set of axes corresponding to
+## Scatter plot of the columns of one matrix against another.
+##
+## Given the arguments @var{x} and @var{y}, that have a matching number of
+## rows, @code{plotmatrix} plots a set of axes corresponding to
 ##
 ## @example
 ## plot (@var{x}(:, i), @var{y}(:, j))
@@ -43,15 +44,15 @@
 ## The marker to use can be changed with the @var{style} argument, that is a
 ## string defining a marker in the same manner as the @code{plot} command.
 ##
-## If the first argument is an axis handle @var{hax}, then plot into these axes,
-## rather than the current axis handle returned by @code{gca}.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} provides handles to the individual
 ## graphics objects in the scatter plots, whereas @var{ax} returns the
 ## handles to the scatter plot axis objects.  @var{bigax} is a hidden
 ## axis object that surrounds the other axes, such that the commands
 ## @code{xlabel}, @code{title}, etc., will be associated with this hidden
-## axis.  Finally @var{p} returns the graphics objects associated with
+## axis.  Finally, @var{p} returns the graphics objects associated with
 ## the histogram and @var{pax} the corresponding axes objects.
 ##
 ## Example:
@@ -60,7 +61,7 @@
 ## plotmatrix (randn (100, 3), "g+")
 ## @end example
 ##
-## @seealso{plot}
+## @seealso{scatter, plot}
 ## @end deftypefn
 
 function [h, ax, bigax, p, pax] = plotmatrix (varargin)
--- a/scripts/plot/plotyy.m
+++ b/scripts/plot/plotyy.m
@@ -20,25 +20,28 @@
 ## @deftypefn  {Function File} {} plotyy (@var{x1}, @var{y1}, @var{x2}, @var{y2})
 ## @deftypefnx {Function File} {} plotyy (@dots{}, @var{fun})
 ## @deftypefnx {Function File} {} plotyy (@dots{}, @var{fun1}, @var{fun2})
-## @deftypefnx {Function File} {} plotyy (@var{h}, @dots{})
+## @deftypefnx {Function File} {} plotyy (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {[@var{ax}, @var{h1}, @var{h2}] =} plotyy (@dots{})
-## Plot two sets of data with independent y-axes.  The arguments @var{x1} and
-## @var{y1} define the arguments for the first plot and @var{x1} and @var{y2}
-## for the second.
+## Plot two sets of data with independent y-axes.
+##
+## The arguments @var{x1} and @var{y1} define the arguments for the first plot
+## and @var{x1} and @var{y2} for the second.
 ##
 ## By default the arguments are evaluated with
 ## @code{feval (@@plot, @var{x}, @var{y})}.  However the type of plot can be
 ## modified with the @var{fun} argument, in which case the plots are
 ## generated by @code{feval (@var{fun}, @var{x}, @var{y})}.  @var{fun} can be
-## a function handle, an inline function or a string of a function name.
+## a function handle, an inline function, or a string of a function name.
 ##
 ## The function to use for each of the plots can be independently defined
 ## with @var{fun1} and @var{fun2}.
 ##
-## If given, @var{h} defines the principal axis in which to plot the @var{x1}
-## and @var{y1} data.  The return value @var{ax} is a two element vector with
-## the axis handles of the two plots.  @var{h1} and @var{h2} are handles to
-## the objects generated by the plot commands.
+## If the first argument @var{hax} is an axes handle, then it defines
+## the principal axis in which to plot the @var{x1} and @var{y1} data.
+##
+## The return value @var{ax} is a vector with the axis handles of the two
+## y axes.  @var{h1} and @var{h2} are handles to the objects generated by the
+## plot commands.
 ##
 ## @example
 ## @group
--- a/scripts/plot/polar.m
+++ b/scripts/plot/polar.m
@@ -31,8 +31,8 @@
 ## The optional argument @var{fmt} specifies the line format in the same way
 ## as @code{plot}.
 ##
-## If the first argument @var{hax} is an axis handle, then plot into this axis,
-## rather than the current axis handle returned by @code{gca}.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a graphics handle to the created plot.
 ##
--- a/scripts/plot/print.m
+++ b/scripts/plot/print.m
@@ -21,17 +21,18 @@
 ## @deftypefnx {Function File} {} print (@var{options})
 ## @deftypefnx {Function File} {} print (@var{filename}, @var{options})
 ## @deftypefnx {Function File} {} print (@var{h}, @var{filename}, @var{options})
-## Print a plot, or save it to a file.  Both output formatted for 
-## printing (PDF and PostScript), and many bitmapped and vector
-## image formats are supported.
+## Print a plot, or save it to a file.
+##
+## Both output formatted for printing (PDF and PostScript), and many bitmapped
+## and vector image formats are supported.
 ##
 ## @var{filename} defines the name of the output file.  If the
 ## file name has no suffix, one is inferred from the specified
 ## device and appended to the file name.  If no filename is
 ## specified, the output is sent to the printer.
 ##
-## @var{h} specifies the figure handle.  If no handle is specified
-## the handle for the current figure is used.
+## @var{h} specifies the handle of the figure to print.  If no handle is
+## specified the current figure is used.
 ##
 ## For output to a printer, PostScript file, or PDF file,
 ## the paper size is specified by the figure's @code{papersize}
@@ -58,23 +59,23 @@
 ##   Specify the command for calling Ghostscript.  For Unix and Windows
 ## the defaults are 'gs' and 'gswin32c', respectively.
 ##
-## @item -color
+## @item  -color
 ## @itemx -mono
-##   Monochrome or color output.
+##   Color or monochrome output.
 ##
-## @item -solid
+## @item  -solid
 ## @itemx -dashed
 ##   Force all lines to be solid or dashed, respectively.
 ##
-## @item -portrait
+## @item  -portrait
 ## @itemx -landscape
 ##   Specify the orientation of the plot for printed output.  For
 ## non-printed output the aspect ratio of the output corresponds to
 ## the plot area defined by the "paperposition" property in the
-## orientation specified.  This options is equivalent to changing
+## orientation specified.  This option is equivalent to changing
 ## the figure's "paperorientation" property.
 ##
-## @item -TextAlphaBits=@var{n}
+## @item  -TextAlphaBits=@var{n}
 ## @itemx -GraphicsAlphaBits=@var{n}
 ##   Octave is able to produce output for various printers, bitmaps, and
 ## vector formats by using Ghostscript.
@@ -88,21 +89,21 @@
 ## and is one of:
 ##
 ##   @table @code
-##   @item ps
+##   @item  ps
 ##   @itemx ps2
 ##   @itemx psc
 ##   @itemx psc2
-##     Postscript (level 1 and 2, mono and color).  The FLTK graphics
-## toolkit generates Postscript level 3.0.
+##     PostScript (level 1 and 2, mono and color).  The FLTK graphics
+## toolkit generates PostScript level 3.0.
 ##
-##   @item eps
+##   @item  eps
 ##   @itemx eps2
 ##   @itemx epsc
 ##   @itemx epsc2
-##     Encapsulated postscript (level 1 and 2, mono and color).  The FLTK
-## graphic toolkit generates Postscript level 3.0.
+##     Encapsulated PostScript (level 1 and 2, mono and color).  The FLTK
+## graphic toolkit generates PostScript level 3.0.
 ##
-##   @item tex
+##   @item  tex
 ##   @itemx epslatex
 ##   @itemx epslatexstandalone
 ##   @itemx pstex
@@ -119,18 +120,18 @@
 ##     Generate a @LaTeX{} file using PGF/TikZ@.  For the FLTK toolkit
 ## the result is PGF.
 ##
-##   @item ill
+##   @item  ill
 ##   @itemx aifm
 ##     Adobe Illustrator (Obsolete for Gnuplot versions > 4.2)
 ##
-##   @item cdr
+##   @item  cdr
 ##   @itemx @nospell{corel}
 ##     CorelDraw
 ##
 ##   @item dxf
 ##     AutoCAD
 ##
-##   @item emf
+##   @item  emf
 ##   @itemx meta
 ##     Microsoft Enhanced Metafile
 ##
@@ -149,7 +150,7 @@
 ##   @item png
 ##     Portable network graphics
 ##
-##   @item jpg
+##   @item  jpg
 ##   @itemx jpeg
 ##     JPEG image
 ##
@@ -167,7 +168,7 @@
 ##   @end table
 ##
 ##   If the device is omitted, it is inferred from the file extension,
-## or if there is no filename it is sent to the printer as postscript.
+## or if there is no filename it is sent to the printer as PostScript.
 ##
 ## @item -d@var{ghostscript_device}
 ##   Additional devices are supported by Ghostscript.
@@ -199,7 +200,7 @@
 ##     Produces pdf output from eps
 ##   @end table
 ##
-##   For a complete list, type @samp{system ("gs -h")} to see what formats
+##   For a complete list, type @code{system ("gs -h")} to see what formats
 ## and devices are available.
 ##
 ##   When Ghostscript output is sent to a printer the size is determined
@@ -208,7 +209,7 @@
 ## the figure's "paperposition" property.
 ##
 ## @item -append
-##   Append Postscript or PDF output to a pre-existing file of the same type.
+##   Append PostScript or PDF output to a pre-existing file of the same type.
 ##
 ## @item -r@var{NUM}
 ##   Resolution of bitmaps in pixels per inch.  For both metafiles and
@@ -243,7 +244,7 @@
 ## of the print function you must quote the @var{xsize},@var{ysize}
 ## option.  For example, by writing @w{"-S640,480"}.
 ##
-## @item -F@var{fontname}
+## @item  -F@var{fontname}
 ## @itemx -F@var{fontname}:@var{size}
 ## @itemx -F:@var{size}
 ##   Use @var{fontname} and/or @var{fontsize} for all text.
@@ -267,14 +268,13 @@
 ##
 ## @example
 ## @group
-## figure (1);
 ## clf ();
 ## surf (peaks);
 ## print -dcdj550
 ## @end group
 ## @end example
 ##
-## @seealso{figure, orient, saveas}
+## @seealso{saveas, orient, figure}
 ## @end deftypefn
 
 function print (varargin)
--- a/scripts/plot/quiver.m
+++ b/scripts/plot/quiver.m
@@ -25,23 +25,23 @@
 ## @deftypefnx {Function File} {} quiver (@var{h}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} quiver (@dots{})
 ##
-## Plot the @code{(@var{u}, @var{v})} components of a vector field in
-## an @code{(@var{x}, @var{y})} meshgrid.  If the grid is uniform, you can
+## Plot the (@var{u}, @var{v}) components of a vector field in
+## an (@var{x}, @var{y}) meshgrid.  If the grid is uniform, you can
 ## specify @var{x} and @var{y} as vectors.
 ##
 ## If @var{x} and @var{y} are undefined they are assumed to be
-## @code{(1:@var{m}, 1:@var{n})} where @code{[@var{m}, @var{n}] =
-## size (@var{u})}.
+## @code{(1:@var{m}, 1:@var{n})} where
+## @code{[@var{m}, @var{n}] = size (@var{u})}.
 ##
 ## The variable @var{s} is a scalar defining a scaling factor to use for
 ## the arrows of the field relative to the mesh spacing.  A value of 0
 ## disables all scaling.  The default value is 1.
 ##
 ## The style to use for the plot can be defined with a line style @var{style}
-## in a similar manner to the line styles used with the @code{plot} command.
+## of the same format as the @code{plot} command.
 ## If a marker is specified then markers at the grid points of the vectors are
-## printed rather than arrows.  If the argument "filled" is given then the
-## markers are drawn filled.
+## drawn rather than arrows.  If the argument "filled" is given then the
+## markers are filled.
 ##
 ## The optional return value @var{h} is a graphics handle to a quiver object.
 ## A quiver object regroups the components of the quiver plot (body, arrow,
@@ -55,7 +55,7 @@
 ## @end group
 ## @end example
 ##
-## @seealso{quiver3, feather, plot}
+## @seealso{quiver3, compass, feather, plot}
 ## @end deftypefn
 
 function retval = quiver (varargin)
--- a/scripts/plot/quiver3.m
+++ b/scripts/plot/quiver3.m
@@ -22,26 +22,26 @@
 ## @deftypefnx {Function File} {} quiver3 (@dots{}, @var{s})
 ## @deftypefnx {Function File} {} quiver3 (@dots{}, @var{style})
 ## @deftypefnx {Function File} {} quiver3 (@dots{}, "filled")
-## @deftypefnx {Function File} {} quiver3 (@var{h}, @dots{})
+## @deftypefnx {Function File} {} quiver3 (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} quiver3 (@dots{})
 ##
-## Plot the @code{(@var{u}, @var{v}, @var{w})} components of a vector field in
-## an @code{(@var{x}, @var{y}), @var{z}} meshgrid.  If the grid is uniform, you
-## can specify @var{x}, @var{y} @var{z} as vectors.
+## Plot the (@var{u}, @var{v}, @var{w}) components of a vector field in
+## an (@var{x}, @var{y}, @var{z}) meshgrid.  If the grid is uniform, you
+## can specify @var{x}, @var{y}, and @var{z} as vectors.
 ##
-## If @var{x}, @var{y} and @var{z} are undefined they are assumed to be
+## If @var{x}, @var{y}, and @var{z} are undefined they are assumed to be
 ## @code{(1:@var{m}, 1:@var{n}, 1:@var{p})} where @code{[@var{m}, @var{n}] =
 ## size (@var{u})} and @code{@var{p} = max (size (@var{w}))}.
 ##
 ## The variable @var{s} is a scalar defining a scaling factor to use for
-##  the arrows of the field relative to the mesh spacing.  A value of 0
+## the arrows of the field relative to the mesh spacing.  A value of 0
 ## disables all scaling.  The default value is 1.
 ##
 ## The style to use for the plot can be defined with a line style @var{style}
-## in a similar manner to the line styles used with the @code{plot} command.
+## of the same format as the @code{plot} command.
 ## If a marker is specified then markers at the grid points of the vectors are
-## printed rather than arrows.  If the argument "filled" is given then the
-## markers as filled.
+## drawn rather than arrows.  If the argument "filled" is given then the
+## markers are filled.
 ##
 ## The optional return value @var{h} is a graphics handle to a quiver object.
 ## A quiver object regroups the components of the quiver plot (body, arrow,
@@ -58,7 +58,7 @@
 ## @end group
 ## @end example
 ##
-## @seealso{quiver, plot}
+## @seealso{quiver, compass, feather, plot}
 ## @end deftypefn
 
 function retval = quiver3 (varargin)
--- a/scripts/plot/rectangle.m
+++ b/scripts/plot/rectangle.m
@@ -22,12 +22,14 @@
 ## @deftypefnx {Function File} {} rectangle (@dots{}, "Curvature", @var{curv})
 ## @deftypefnx {Function File} {} rectangle (@dots{}, "EdgeColor", @var{ec})
 ## @deftypefnx {Function File} {} rectangle (@dots{}, "FaceColor", @var{fc})
+## @deftypefnx {Function File} {} rectangle (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} rectangle (@dots{})
 ##
-## Draw rectangular patch defined by @var{pos} and @var{curv}.  The variable
-## @code{@var{pos}(1:2)} defines the lower left-hand corner of the patch
-## and @code{@var{pos}(3:4)} defines its width and height.  By default, the
-## value of @var{pos} is @code{[0, 0, 1, 1]}.
+## Draw a rectangular patch defined by @var{pos} and @var{curv}.
+## 
+## The variable @code{@var{pos}(1:2)} defines the lower left-hand corner of
+## the patch and @code{@var{pos}(3:4)} defines its width and height.  By
+## default, the value of @var{pos} is @code{[0, 0, 1, 1]}.
 ##
 ## The variable @var{curv} defines the curvature of the sides of the rectangle
 ## and may be a scalar or two-element vector with values between 0 and 1.
@@ -44,12 +46,15 @@
 ## min (pos (1:2)) / max (pos (1:2)) * curv
 ## @end example
 ##
-## Other properties are passed to the underlying patch command. 
+## Additional property/value pairs are passed to the underlying patch command. 
 ## 
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
+##
 ## The optional return value @var{h} is a graphics handle to the created
 ## rectangle object.
 ## @end deftypefn
-## @seealso{patch}
+## @seealso{patch, line, cylinder, ellipsoid, sphere}
 
 function h = rectangle (varargin)
 
--- a/scripts/plot/refresh.m
+++ b/scripts/plot/refresh.m
@@ -19,9 +19,10 @@
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} refresh ()
 ## @deftypefnx {Function File} {} refresh (@var{h})
-## Refresh a figure, forcing it to be redrawn.  When called without an
-## argument the current figure is redrawn.  Otherwise, the figure pointed
-## to by @var{h} is redrawn.
+## Refresh a figure, forcing it to be redrawn.
+##
+## When called without an argument the current figure is redrawn.  Otherwise,
+## the figure with graphic handle @var{h} is redrawn.
 ## @seealso{drawnow}
 ## @end deftypefn
 
--- a/scripts/plot/refreshdata.m
+++ b/scripts/plot/refreshdata.m
@@ -21,9 +21,12 @@
 ## @deftypefnx {Function File} {} refreshdata (@var{h})
 ## @deftypefnx {Function File} {} refreshdata (@var{h}, @var{workspace})
 ## Evaluate any @samp{datasource} properties of the current figure and update
-## the plot if the corresponding data has changed.  If called with one or more
-## arguments @var{h} is a scalar or array of figure handles to refresh.  The
-## optional second argument @var{workspace} can take the following values.
+## the plot if the corresponding data has changed.
+##
+## If the first argument @var{h} is a list of graphic handles, then operate
+## on these objects rather than the current figure returned by @code{gcf}.
+##
+## The optional second argument @var{workspace} can take the following values:
 ##
 ## @table @asis
 ## @item "base"
--- a/scripts/plot/ribbon.m
+++ b/scripts/plot/ribbon.m
@@ -28,11 +28,12 @@
 ## (default is 0.75).  If @var{x} is omitted, a vector containing the
 ## row numbers is assumed (@code{1:rows (Y)}).
 ##
-## If the first argument @var{hax} is an axis handle, then plot into this axis,
-## rather than the current axis handle returned by @code{gca}.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a vector of graphics handles to
 ## the surface objects representing each ribbon.
+## @seealso{surface, waterfall}
 ## @end deftypefn
 
 ## Author: Kai Habel <kai.habel at gmx.de>
--- a/scripts/plot/rose.m
+++ b/scripts/plot/rose.m
@@ -23,7 +23,6 @@
 ## @deftypefnx {Function File} {} rose (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} rose (@dots{})
 ## @deftypefnx {Function File} {[@var{thout} @var{rout}] =} rose (@dots{})
-##
 ## Plot an angular histogram.
 ##
 ## With one vector argument, @var{th}, plot the histogram with 20 angular bins.
@@ -32,9 +31,12 @@
 ##
 ## If @var{nbins} is given and is a scalar, then the histogram is produced with
 ## @var{nbin} bins.  If @var{bins} is a vector, then the center of each bin is
-## defined defined by the values of @var{bins} and the number of bins is
+## defined by the values of @var{bins} and the number of bins is
 ## given by the number of elements in @var{bins}.
 ##
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
+##
 ## The optional return value @var{h} is a vector of graphics handles to the
 ## line objects representing each histogram.
 ##
@@ -48,7 +50,7 @@
 ## @end group
 ## @end example
 ##
-## @seealso{polar, compass, hist}
+## @seealso{hist, polar}
 ## @end deftypefn
 
 function [thout, rout] = rose (varargin)
--- a/scripts/plot/saveas.m
+++ b/scripts/plot/saveas.m
@@ -26,10 +26,10 @@
 ##
 ## @table @code
 ##   @item ps
-##     Postscript
+##     PostScript
 ##
 ##   @item eps
-##     Encapsulated Postscript
+##     Encapsulated PostScript
 ##
 ##   @item jpg
 ##     JPEG Image
@@ -46,7 +46,7 @@
 ##
 ## All device formats specified in @code{print} may also be used.  If
 ## @var{fmt} is omitted it is extracted from the extension of @var{filename}.
-## The default format is @code{"pdf"}.
+## The default format is "pdf".
 ##
 ## @example
 ## @group
@@ -56,7 +56,7 @@
 ## @end group
 ## @end example
 ##
-## @seealso{print}
+## @seealso{print, orient}
 ## @end deftypefn
 
 ## Author: Kai Habel
--- a/scripts/plot/scatter.m
+++ b/scripts/plot/scatter.m
@@ -20,28 +20,37 @@
 ## @deftypefn  {Function File} {} scatter (@var{x}, @var{y})
 ## @deftypefnx {Function File} {} scatter (@var{x}, @var{y}, @var{s})
 ## @deftypefnx {Function File} {} scatter (@var{x}, @var{y}, @var{s}, @var{c})
-## @deftypefnx {Function File} {} scatter (@var{x}, @var{y}, @var{s}, @var{c}, @var{style})
-## @deftypefnx {Function File} {} scatter (@var{x}, @var{y}, @var{s}, @var{c}, @var{prop}, @var{val})
+## @deftypefnx {Function File} {} scatter (@dots{}, @var{style})
 ## @deftypefnx {Function File} {} scatter (@dots{}, "filled")
-## @deftypefnx {Function File} {} scatter (@var{h}, @dots{})
+## @deftypefnx {Function File} {} scatter (@dots{}, @var{prop}, @var{val}, @dots{})
+## @deftypefnx {Function File} {} scatter (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} scatter (@dots{})
+## Draw a 2-D scatter plot.
 ##
-## Draw a scatter plot of the data.  A marker is plotted at each point
-## defined by the points in the vectors @var{x} and @var{y}.  The size of
-## the markers used is determined by the @var{s}, which can be a scalar or
-## a vector of the same length as @var{x} and @var{y}.  If @var{s} is not
-## given or is an empty matrix, then the default value of 8 points is used.
+## A marker is plotted at each point defined by the coordinates in the vectors
+## @var{x} and  @var{y}.
+##
+## The size of the markers is determined by @var{s}, which can be a scalar
+## or a vector of the same length as @var{x} and @var{y}.  If @var{s}
+## is not given, or is an empty matrix, then a default value of 8 points is
+## used.
 ##
 ## The color of the markers is determined by @var{c}, which can be a string
-## defining a fixed color; a 3-element vector giving the red, green,and blue
+## defining a fixed color; a 3-element vector giving the red, green, and blue
 ## components of the color; a vector of the same length as @var{x} that gives
-## a scaled index into the current colormap; or an @var{n}-by-3 matrix defining
-## the colors of each of the markers individually.
+## a scaled index into the current colormap; or an @nospell{Nx3} matrix defining
+## the RGB color of each marker individually.
 ##
 ## The marker to use can be changed with the @var{style} argument, that is a
 ## string defining a marker in the same manner as the @code{plot} command.
-## If the argument @code{"filled"} is given then the markers as filled.  All
-## additional arguments are passed to the underlying patch command.
+## If no marker is specified it defaults to 'o' or circles.
+## If the argument "filled" is given then the markers are filled.
+##
+## Additional property/value pairs are passed directly to the underlying
+## patch object.
+##
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a graphics handle to the created patch
 ## object.
@@ -56,7 +65,7 @@
 ## @end group
 ## @end example
 ##
-## @seealso{plot, patch, scatter3}
+## @seealso{scatter3, patch, plot}
 ## @end deftypefn
 
 function retval = scatter (varargin)
--- a/scripts/plot/scatter3.m
+++ b/scripts/plot/scatter3.m
@@ -17,29 +17,40 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {} scatter3 (@var{x}, @var{y}, @var{z}, @var{s}, @var{c})
-## @deftypefnx {Function File} {} scatter3 (@dots{}, "filled")
+## @deftypefn  {Function File} {} scatter3 (@var{x}, @var{y}, @var{z})
+## @deftypefnx {Function File} {} scatter3 (@var{x}, @var{y}, @var{z}, @var{s})
+## @deftypefnx {Function File} {} scatter3 (@var{x}, @var{y}, @var{z}, @var{s}, @var{c})
 ## @deftypefnx {Function File} {} scatter3 (@dots{}, @var{style})
+## @deftypefnx {Function File} {} scatter3 (@dots{}, "filled")
 ## @deftypefnx {Function File} {} scatter3 (@dots{}, @var{prop}, @var{val})
-## @deftypefnx {Function File} {} scatter3 (@var{h}, @dots{})
+## @deftypefnx {Function File} {} scatter3 (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} scatter3 (@dots{})
+## Draw a 3-D scatter plot.
 ##
-## Plot a scatter plot of the data in 3D@.  A marker is plotted at each point
-## defined by the points in the vectors @var{x}, @var{y} and @var{z}.  The size
-## of the markers used is determined by @var{s}, which can be a scalar or
-## a vector of the same length of @var{x}, @var{y} and @var{z}.  If @var{s} is
-## not given or is an empty matrix, then the default value of 8 points is used.
+## A marker is plotted at each point defined by the coordinates in the vectors
+## @var{x}, @var{y}, and @var{z}.
+##
+## The size of the markers is determined by @var{s}, which can be a scalar
+## or a vector of the same length as @var{x}, @var{y}, and @var{z}.  If @var{s}
+## is not given, or is an empty matrix, then a default value of 8 points is
+## used.
 ##
 ## The color of the markers is determined by @var{c}, which can be a string
 ## defining a fixed color; a 3-element vector giving the red, green, and blue
 ## components of the color; a vector of the same length as @var{x} that gives
-## a scaled index into the current colormap; or a @var{n}-by-3 matrix defining
-## the colors of each of the markers individually.
+## a scaled index into the current colormap; or an @nospell{Nx3} matrix defining
+## the RGB color of each marker individually.
 ##
 ## The marker to use can be changed with the @var{style} argument, that is a
 ## string defining a marker in the same manner as the @code{plot} command.
-## If the argument "filled" is given then the markers as filled.  All
-## additional arguments are passed to the underlying patch command.
+## If no marker is specified it defaults to 'o' or circles.
+## If the argument "filled" is given then the markers are filled.
+##
+## Additional property/value pairs are passed directly to the underlying
+## patch object.
+##
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a graphics handle to the hggroup
 ## object representing the points.
@@ -51,7 +62,7 @@
 ## @end group
 ## @end example
 ##
-## @seealso{plot, patch, scatter}
+## @seealso{scatter, patch, plot}
 ## @end deftypefn
 
 function retval = scatter3 (varargin)
--- a/scripts/plot/semilogx.m
+++ b/scripts/plot/semilogx.m
@@ -21,12 +21,16 @@
 ## @deftypefnx {Function File} {} semilogx (@var{x}, @var{y})
 ## @deftypefnx {Function File} {} semilogx (@var{x}, @var{y}, @var{property}, @var{value}, @dots{})
 ## @deftypefnx {Function File} {} semilogx (@var{x}, @var{y}, @var{fmt})
-## @deftypefnx {Function File} {} semilogx (@var{h}, @dots{})
+## @deftypefnx {Function File} {} semilogx (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} semilogx (@dots{})
-## Produce a two-dimensional plot using a logarithmic scale for the @var{x}
-## axis.  See the documentation of @code{plot} for a description of the
+## Produce a 2-D plot using a logarithmic scale for the x-axis.
+##
+## See the documentation of @code{plot} for a description of the
 ## arguments that @code{semilogx} will accept.
 ## 
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
+##
 ## The optional return value @var{h} is a graphics handle to the created plot.
 ## @seealso{plot, semilogy, loglog}
 ## @end deftypefn
--- a/scripts/plot/semilogxerr.m
+++ b/scripts/plot/semilogxerr.m
@@ -18,9 +18,10 @@
 
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} semilogxerr (@var{args})
+## @deftypefnx {Function File} {} semilogxerr (@var{hax}, @var{args})
 ## @deftypefnx {Function File} {@var{h} =} semilogxerr (@var{args})
-## Produce two-dimensional plots using a logarithmic scale for the @var{x}
-## axis and errorbars at each data point.
+## Produce 2-D plots using a logarithmic scale for the x-axis and
+## errorbars at each data point.
 ##
 ## Many different combinations of arguments are possible.  The most common
 ## form is
@@ -32,8 +33,8 @@
 ## @noindent
 ## which produces a semi-logarithmic plot of @var{y} versus @var{x}
 ## with errors in the @var{y}-scale defined by @var{ey} and the plot
-## format defined by @var{fmt}.  See @code{errorbar} for available formats and
-## additional information.
+## format defined by @var{fmt}.  @xref{XREFerrorbar,,errorbar}, for available
+## formats and additional information.
 ## @seealso{errorbar, semilogyerr, loglogerr}
 ## @end deftypefn
 
--- a/scripts/plot/semilogy.m
+++ b/scripts/plot/semilogy.m
@@ -23,10 +23,14 @@
 ## @deftypefnx {Function File} {} semilogy (@var{x}, @var{y}, @var{fmt})
 ## @deftypefnx {Function File} {} semilogy (@var{h}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} semilogy (@dots{})
-## Produce a two-dimensional plot using a logarithmic scale for the @var{y}
-## axis.  See the documentation of @code{plot} for a description of the
+## Produce a 2-D plot using a logarithmic scale for the y-axis.
+##
+## See the documentation of @code{plot} for a description of the
 ## arguments that @code{semilogy} will accept.
 ##
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
+##
 ## The optional return value @var{h} is a graphics handle to the created plot.
 ## @seealso{plot, semilogx, loglog}
 ## @end deftypefn
--- a/scripts/plot/semilogyerr.m
+++ b/scripts/plot/semilogyerr.m
@@ -18,9 +18,10 @@
 
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} semilogyerr (@var{args})
+## @deftypefnx {Function File} {} semilogyerr (@var{hax}, @var{args})
 ## @deftypefnx {Function File} {@var{h} =} semilogyerr (@var{args})
-## Produce two-dimensional plots using a logarithmic scale for the @var{y}
-## axis and errorbars at each data point.
+## Produce 2-D plots using a logarithmic scale for the y-axis and
+## errorbars at each data point.
 ##
 ## Many different combinations of arguments are possible.  The most common
 ## form is
@@ -32,8 +33,8 @@
 ## @noindent
 ## which produces a semi-logarithmic plot of @var{y} versus @var{x}
 ## with errors in the @var{y}-scale defined by @var{ey} and the plot
-## format defined by @var{fmt}.  See @code{errorbar} for available formats and
-## additional information.
+## format defined by @var{fmt}.  @xref{XREFerrorbar,,errorbar}, for available
+## formats and additional information.
 ## @seealso{errorbar, semilogxerr, loglogerr}
 ## @end deftypefn
 
--- a/scripts/plot/shading.m
+++ b/scripts/plot/shading.m
@@ -19,7 +19,7 @@
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} shading (@var{type})
 ## @deftypefnx {Function File} {} shading (@var{hax}, @var{type})
-## Set the shading of surface or patch graphic objects.
+## Set the shading of patch or surface graphic objects.
 ##
 ## Valid arguments for @var{type} are
 ##
@@ -37,8 +37,7 @@
 ##
 ## If the first argument @var{hax} is an axes handle, then plot into this axis,
 ## rather than the current axes returned by @code{gca}.
-## If the first argument @var{hax} is an axes handle, then operate on
-## this axis rather than the current axes returned by @code{gca}.
+## @seealso{fill, mesh, patch, pcolor, surf, surface, hidden}
 ## @end deftypefn
 
 ## Author: Kai Habel <kai.habel@gmx.de>
--- a/scripts/plot/shg.m
+++ b/scripts/plot/shg.m
@@ -18,8 +18,9 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {Command} {} shg
-## Show the graph window.  Currently, this is the same as executing
-## @code{drawnow}.
+## Show the graph window.
+##
+## Currently, this is the same as executing @code{drawnow}.
 ## @seealso{drawnow, figure}
 ## @end deftypefn
 
--- a/scripts/plot/shrinkfaces.m
+++ b/scripts/plot/shrinkfaces.m
@@ -106,7 +106,7 @@
 
   n = columns (vertices);
   if (n < 2 || n > 3)
-    error ("shrinkfaces: only 2D and 3D patches are supported");
+    error ("shrinkfaces: only 2-D and 3-D patches are supported");
   endif
 
   m = columns (faces);
--- a/scripts/plot/slice.m
+++ b/scripts/plot/slice.m
@@ -26,15 +26,14 @@
 ## @deftypefnx {Function File} {@var{h} =} slice (@dots{})
 ## Plot slices of 3-D data/scalar fields.
 ##
-## Each element of the 3-dimensional
-## array @var{v} represents a scalar value at a location given by the
-## parameters @var{x}, @var{y}, and @var{z}.  The parameters @var{x},
-## @var{x}, and @var{z} are either 3-dimensional arrays of the same size
-## as the array @var{v} in the "meshgrid" format or vectors.  The
-## parameters @var{xi}, etc. respect a similar format to @var{x}, etc.,
-## and they represent the points at which the array @var{vi} is
-## interpolated using interp3.  The vectors @var{sx}, @var{sy}, and
-## @var{sz} contain points of orthogonal slices of the respective axes.
+## Each element of the 3-dimensional array @var{v} represents a scalar value at
+## a location given by the parameters @var{x}, @var{y}, and @var{z}.  The
+## parameters @var{x}, @var{x}, and @var{z} are either 3-dimensional arrays of
+## the same size as the array @var{v} in the "meshgrid" format or vectors.  The
+## parameters @var{xi}, etc. respect a similar format to @var{x}, etc., and
+## they represent the points at which the array @var{vi} is interpolated using
+## interp3.  The vectors @var{sx}, @var{sy}, and @var{sz} contain points of
+## orthogonal slices of the respective axes.
 ##
 ## If @var{x}, @var{y}, @var{z} are omitted, they are assumed to be
 ## @code{x = 1:size (@var{v}, 2)}, @code{y = 1:size (@var{v}, 1)} and
@@ -59,8 +58,8 @@
 ##
 ## The default method is "linear".
 ##
-## If the first argument @var{hax} is an axis handle, then plot into this axis,
-## rather than the current axis handle returned by @code{gca}.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a graphics handle to the created
 ## surface object.
--- a/scripts/plot/specular.m
+++ b/scripts/plot/specular.m
@@ -21,13 +21,14 @@
 ## @deftypefnx {Function File} {} specular (@var{sx}, @var{sy}, @var{sz}, @var{lv}, @var{vv}, @var{se})
 ## Calculate specular reflection strength of a surface defined by the normal
 ## vector elements @var{sx}, @var{sy}, @var{sz} using Phong's approximation.
-## The light and view vectors can be specified using parameter @var{lv} and
-## @var{vv} respectively.
-## Both can be given as 2-element vectors [azimuth, elevation] in degrees or as
-## 3-element
-## vector [x, y, z].  An optional 6th argument describes the specular exponent
-## (spread) @var{se}.
-## @seealso{surfl, diffuse}
+##
+## The light source location and viewer location vectors can be specified using
+## parameter @var{lv} and  @var{vv} respectively.  The location vectors can
+## given as 2-element vectors [azimuth, elevation] in degrees or as 3-element
+## vectors [x, y, z].
+##
+## An optional sixth argument describes the specular exponent (spread) @var{se}.
+## @seealso{diffuse, surfl}
 ## @end deftypefn
 
 ## Author: Kai Habel <kai.habel@gmx.de>
--- a/scripts/plot/sphere.m
+++ b/scripts/plot/sphere.m
@@ -17,17 +17,33 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {[@var{x}, @var{y}, @var{z}] =} sphere (@var{n})
-## @deftypefnx {Function File} {} sphere (@var{h}, @dots{})
-## Generate three matrices in @code{meshgrid} format, such that
-## @code{surf (@var{x}, @var{y}, @var{z})} generates a unit sphere.
-## The matrices of @code{@var{n}+1}-by-@code{@var{n}+1}.  If @var{n} is
-## omitted then a default value of 20 is assumed.
+## @deftypefn  {Function File} {} sphere ()
+## @deftypefnx {Function File} {} sphere (@var{n})
+## @deftypefnx {Function File} {} sphere (@var{hax}, @dots{})
+## @deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} sphere (@dots{})
+## Plot a 3-D unit sphere.
+##
+## The optional input @var{n} determines the number of faces around the
+## the circumference of the sphere.  The default value is 20.
+##
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
-## Called with no return arguments, @code{sphere} call directly
-## @code{surf (@var{x}, @var{y}, @var{z})}.  If an axes handle is passed
-## as the first argument, the surface is plotted to this set of axes.
-## @seealso{peaks}
+## If outputs are requested @code{sphere} returns three matrices in
+## @code{meshgrid} format such that @code{surf (@var{x}, @var{y}, @var{z})}
+## generates a unit sphere.
+##
+## Example:
+##
+## @example
+## @group
+## [x, y, z] = sphere (40);
+## surf (3*x, 3*y, 3*z);
+## axis equal;
+## title ("sphere of radius 3");
+## @end group
+## @end example
+## @seealso{cylinder, ellipsoid, rectangle}
 ## @end deftypefn
 
 function [xx, yy, zz] = sphere (varargin)
--- a/scripts/plot/stairs.m
+++ b/scripts/plot/stairs.m
@@ -20,7 +20,7 @@
 ## @deftypefn  {Function File} {} stairs (@var{y})
 ## @deftypefnx {Function File} {} stairs (@var{x}, @var{y})
 ## @deftypefnx {Function File} {} stairs (@dots{}, @var{style})
-## @deftypefnx {Function File} {} stairs (@dots{}, @var{prop}, @var{val})
+## @deftypefnx {Function File} {} stairs (@dots{}, @var{prop}, @var{val}, @dots{})
 ## @deftypefnx {Function File} {} stairs (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} stairs (@dots{})
 ## @deftypefnx {Function File} {[@var{xstep}, @var{ystep}] =} stairs (@dots{})
@@ -31,7 +31,7 @@
 ## and the X coordinates are taken to be the indices of the elements.
 ## 
 ## The style to use for the plot can be defined with a line style @var{style}
-## in the same way as the @code{plot} command.
+## of the same format as the @code{plot} command.
 ##
 ## Multiple property/value pairs may be specified, but they must appear in
 ## pairs.
@@ -59,7 +59,7 @@
 ##
 ## @noindent
 ## are equivalent.
-## @seealso{plot}
+## @seealso{bar, hist, plot, stem}
 ## @end deftypefn
 
 ## Author: jwe
--- a/scripts/plot/stem.m
+++ b/scripts/plot/stem.m
@@ -21,10 +21,10 @@
 ## @deftypefnx {Function File} {} stem (@var{x}, @var{y})
 ## @deftypefnx {Function File} {} stem (@dots{}, @var{linespec})
 ## @deftypefnx {Function File} {} stem (@dots{}, "filled")
-## @deftypefnx {Function File} {} stem (@dots{}, "@var{prop}", "@var{val}", @dots{})
+## @deftypefnx {Function File} {} stem (@dots{}, @var{prop}, @var{val}, @dots{})
 ## @deftypefnx {Function File} {} stem (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} stem (@dots{})
-## Plot a stem graph from two vectors of x-y data.
+## Plot a 2-D stem graph.
 ##
 ## If only one argument is given, it is taken as the y-values and the
 ## x-coordinates are taken from the indices of the elements.
@@ -37,7 +37,8 @@
 ## The default color is @code{"b"} (blue), the default line style is
 ## @code{"-"}, and the default marker is @code{"o"}.  The line style can
 ## be altered by the @code{linespec} argument in the same manner as the
-## @code{plot} command.  For example,
+## @code{plot} command.  If the "filled" argument is present the markers at
+## the top of the stems will be filled in.  For example,
 ##
 ## @example
 ## @group
@@ -50,11 +51,11 @@
 ## @noindent
 ## plots 10 stems with heights from 2 to 20 in red;
 ##
-## Multiple property/value pairs may be specified, but they must appear in
-## pairs.
+## Optional property/value pairs may be specified to control the appearance
+## of the plot.
 ##
-## If the first argument @var{hax} is an axis handle, then plot into these axes,
-## rather than the current axis handle returned by @code{gca}.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a vector of "stem series" graphics
 ## handles with one handle per column of the variable @var{y}.  The
@@ -75,7 +76,7 @@
 ## @noindent
 ## changes the color of the second "stem series" and moves the base line
 ## of the first.
-## @seealso{stem3, bar, hist, plot}
+## @seealso{stem3, bar, hist, plot, stairs}
 ## @end deftypefn
 
 ## Author: Michel D. Schmid <michaelschmid@users.sourceforge.net>
--- a/scripts/plot/stem3.m
+++ b/scripts/plot/stem3.m
@@ -18,33 +18,36 @@
 
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} stem3 (@var{x}, @var{y}, @var{z})
-## @deftypefnx {Function File} {} stem3 (@var{x}, @var{y}, @var{z}, @var{linespec})
+## @deftypefnx {Function File} {} stem3 (@dots{}, @var{linespec})
 ## @deftypefnx {Function File} {} stem3 (@dots{}, "filled")
-## @deftypefnx {Function File} {} stem3 (@dots{}, "@var{prop}", "@var{val}", @dots{})
+## @deftypefnx {Function File} {} stem3 (@dots{}, @var{prop}, @var{val}, @dots{})
 ## @deftypefnx {Function File} {} stem3 (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} stem3 (@dots{})
 ## Plot a 3-D stem graph.
 ##
-## The default color is @code{"r"} (red), the default line style is
-## @code{"-"}, and the default marker is @code{"o"}.  The line style can
-## be altered by the @code{linespec} argument in the same manner as the
-## @code{plot} command.
+## Stems are drawn from the height @var{z} to the location in the x-y plane
+## determined by @var{x} and @var{y}.  The default color is @code{"b"} (blue),
+## the default line style is @code{"-"}, and the default marker is @code{"o"}.
 ##
-## Multiple property/value pairs may be specified, but they must appear in
-## pairs.
+## The line style can be altered by the @code{linespec} argument in the same
+## manner as the @code{plot} command.  If the "filled" argument is present
+## the markers at the top of the stems will be filled in.
 ##
-## If the first argument @var{hax} is an axis handle, then plot into these axes,
-## rather than the current axis handle returned by @code{gca}.
+## Optional property/value pairs may be specified to control the appearance
+## of the plot.
+##
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a vector with the handles of the line
-## and marker objects used to draw the stems as "stem series" object.
+## and marker objects used to draw the stems as a "stem series" object.
 ##
 ## Example:
 ##
 ## @example
 ## @group
 ## theta = 0:0.2:6;
-## stem3 (cos (theta), sin (theta), theta)
+## stem3 (cos (theta), sin (theta), theta);
 ## @end group
 ## @end example
 ##
@@ -52,7 +55,6 @@
 ## plots 31 stems with heights from 0 to 6 lying on a circle.
 ##
 ## Implementation Note: Color definitions with RGB-triples are not valid.
-##
 ## @seealso{stem, bar, hist, plot}
 ## @end deftypefn
 
--- a/scripts/plot/struct2hdl.m
+++ b/scripts/plot/struct2hdl.m
@@ -18,18 +18,18 @@
 ## @deftypefn  {Function File} {@var{h} =} struct2hdl (@var{s})
 ## @deftypefnx {Function File} {@var{h} =} struct2hdl (@var{s}, @var{p})
 ## @deftypefnx {Function File} {@var{h} =} struct2hdl (@var{s}, @var{p}, @var{hilev})
-## Construct a handle object @var{h} from the structure @var{s}.  The structure
-## must contain the fields "handle", "type", "children", "properties", and
-## "special".  If the handle of an existing figure or axes is specified,
-## @var{p}, the new object will be created as a child of that object.
-## If no object handle is provided then a new figure and the necessary
-## children will be constructed using the default object values from
-## the root figure.
+## Construct a graphics handle object @var{h} from the structure @var{s}.
+##
+## The structure must contain the fields "handle", "type", "children",
+## "properties", and "special".  If the handle of an existing figure or axes
+## is specified, @var{p}, the new object will be created as a child of that
+## object.  If no parent handle is provided then a new figure and the necessary
+## children will be constructed using the default values from the root figure.
 ##
 ## A third boolean argument @var{hilev} can be passed to specify whether
-## the function should try to preserve listeners/callbacks, e.g., for
-## legends or hggroups.  The default is false.
-## @seealso{hdl2struct, findobj, get, set}
+## the function should preserve listeners/callbacks, e.g., for legends or
+## hggroups.  The default is false.
+## @seealso{hdl2struct, findobj}
 ## @end deftypefn
 
 ## Author: pdiribarne <pdiribarne@new-host.home>
--- a/scripts/plot/subplot.m
+++ b/scripts/plot/subplot.m
@@ -19,18 +19,17 @@
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} subplot (@var{rows}, @var{cols}, @var{index})
 ## @deftypefnx {Function File} {} subplot (@var{rcn})
+## @deftypefnx {Function File} {} subplot (@dots{}, "align")
 ## @deftypefnx {Function File} {@var{hax} =} subplot (@dots{})
-## Set up a plot grid with @var{rows} by @var{cols} subwindows and plot
-## in location given by @var{index}.
+## @deftypefnx {Function File} {@var{hax} =} subplot (@dots{})
+## Set up a plot grid with @var{rows} by @var{cols} subwindows and set the
+## current axes for plotting to the location given by @var{index}.
 ##
-## If @var{hax} is provided, subplot returns the axis handle for the subplot.
-## This is usuful for modifying the properties of a subplot.
+## If only one numeric argument is supplied, then it must be a three digit
+## value specifying the location in digits 1 (rows) and 2 (columns) and the
+## plot index in digit 3.
 ##
-## If only one argument is supplied, then it must be a three digit value
-## specifying the location in digits 1 (rows) and 2 (columns) and the plot
-## index in digit 3.
-##
-## The plot index runs row-wise.  First all the columns in a row are filled
+## The plot index runs row-wise.  First all the columns in a row are numbered
 ## and then the next row is filled.
 ##
 ## For example, a plot with 2 by 3 grid will have plot indices running as
@@ -56,14 +55,20 @@
 ## @end group
 ## @end example
 ##
-## @var{index} may be a vector.  In which case, the new axis will enclose
+## @end ifnottex
+##
+## @var{index} may also be a vector.  In this case, the new axis will enclose
 ## the grid locations specified.  The first demo illustrates an example:
 ##
 ## @example
 ## demo ("subplot", 1)
 ## @end example
 ##
-## @end ifnottex
+## If the option "align" is given then the plot boxes of the subwindows
+## will align, but this may leave no room for axis tick marks or labels.
+##
+## If the output @var{hax} is requested, subplot returns the axis handle for
+## the subplot.  This is useful for modifying the properties of a subplot.
 ## @seealso{axes, plot}
 ## @end deftypefn
 
--- a/scripts/plot/surf.m
+++ b/scripts/plot/surf.m
@@ -20,22 +20,40 @@
 ## @deftypefn  {Function File} {} surf (@var{x}, @var{y}, @var{z})
 ## @deftypefnx {Function File} {} surf (@var{z})
 ## @deftypefnx {Function File} {} surf (@dots{}, @var{c})
+## @deftypefnx {Function File} {} surf (@dots{}, @var{prop}, @var{val}, @dots{})
 ## @deftypefnx {Function File} {} surf (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} surf (@dots{})
-## Plot a surface given matrices @var{x}, and @var{y} from @code{meshgrid} and
-## a matrix @var{z} corresponding to the @var{x} and @var{y} coordinates of
-## the mesh.  If @var{x} and @var{y} are vectors, then a typical vertex
-## is (@var{x}(j), @var{y}(i), @var{z}(i,j)).  Thus, columns of @var{z}
-## correspond to different @var{x} values and rows of @var{z} correspond
-## to different @var{y} values.
+## Plot a 3-D surface mesh.
+##
+## The surface mesh is plotted using shaded rectangles.  The vertices of the
+## rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}.
+## over a 2-D rectangular region in the x-y plane.  @var{z} determines the
+## height above the plane of each vertex.  If only a single @var{z} matrix is
+## given, then it is plotted over the meshgrid
+## @code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}.
+## Thus, columns of @var{z} correspond to different @var{x} values and rows
+## of @var{z} correspond to different @var{y} values.  
 ##
-## The color of the surface is derived from the @code{colormap} and
-## the value of @var{z}.  Optionally the color of the surface can be
-## specified independent of @var{z}, by adding a fourth matrix, @var{c}.
+## The color of the surface is computed by linearly scaling the @var{Z} values
+## to fit the range of the current colormap.  Use @code{caxis} and/or
+## change the colormap to control the appearance.
+##
+## Optionally, the color of the surface can be specified independently of
+## @var{z} by supplying a color matrix, @var{c}.
+##
+## Any property/value pairs are passed directly to the underlying surface
+## object.
+##
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a graphics handle to the created
 ## surface object.
-## @seealso{colormap, contour, meshgrid, mesh}
+##
+## Note: The exact appearance of the surface can be controlled with the
+## @code{shading} command or by using @code{set} to control surface object
+## properties.
+## @seealso{ezsurf, surfc, surfl, surfnorm, trisurf, contour, mesh, surface, meshgrid, hidden, shading, colormap, caxis}
 ## @end deftypefn
 
 ## Author: Kai Habel <kai.habel@gmx.de>
--- a/scripts/plot/surface.m
+++ b/scripts/plot/surface.m
@@ -21,19 +21,25 @@
 ## @deftypefnx {Function File} {} surface (@var{x}, @var{y}, @var{z})
 ## @deftypefnx {Function File} {} surface (@var{z}, @var{c})
 ## @deftypefnx {Function File} {} surface (@var{z})
-## @deftypefnx {Function File} {} surface (@dots{}, @var{prop}, @var{val})
-## @deftypefnx {Function File} {} surface (@var{h}, @dots{})
+## @deftypefnx {Function File} {} surface (@dots{}, @var{prop}, @var{val}, @dots{})
+## @deftypefnx {Function File} {} surface (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} surface (@dots{})
-## Plot a surface graphic object given matrices @var{x}, and @var{y} from
-## @code{meshgrid} and a matrix @var{z} corresponding to the @var{x} and
-## @var{y} coordinates of the surface.  If @var{x} and @var{y} are vectors,
-## then a typical vertex is (@var{x}(j), @var{y}(i), @var{z}(i,j)).  Thus,
-## columns of @var{z} correspond to different @var{x} values and rows of
-## @var{z} correspond to different @var{y} values.  If @var{x} and @var{y}
-## are missing, they are constructed from size of the matrix @var{z}.
+## Create a surface graphic object given matrices @var{x} and @var{y} from
+## @code{meshgrid} and a matrix of values @var{z} corresponding to the
+## @var{x} and @var{y} coordinates of the surface.
 ##
-## Any additional properties passed are assigned to the surface.
+## If @var{x} and @var{y} are vectors, then a typical vertex is
+## (@var{x}(j), @var{y}(i), @var{z}(i,j)).  Thus, columns of @var{z} correspond
+## to different @var{x} values and rows of @var{z} correspond to different
+## @var{y} values.  If only a single input @var{z} is given then @var{x} is
+## taken to be @code{1:rows (@var{z})} and @var{y} is
+## @code{1:columns (@var{z})}.
+##
+## Any property/value input pairs are assigned to the surface object.
 ## 
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
+##
 ## The optional return value @var{h} is a graphics handle to the created
 ## surface object.
 ## @seealso{surf, mesh, patch, line}
--- a/scripts/plot/surfc.m
+++ b/scripts/plot/surfc.m
@@ -17,14 +17,43 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function File} {} surfc (@var{x}, @var{y}, @var{z})
-## Plot a surface and contour given matrices @var{x}, and @var{y} from
-## @code{meshgrid} and a matrix @var{z} corresponding to the @var{x} and
-## @var{y} coordinates of the mesh.  If @var{x} and @var{y} are vectors,
-## then a typical vertex is (@var{x}(j), @var{y}(i), @var{z}(i,j)).  Thus,
-## columns of @var{z} correspond to different @var{x} values and rows of
-## @var{z} correspond to different @var{y} values.
-## @seealso{ezsurfc, meshgrid, surf, contour}
+## @deftypefn  {Function File} {} surfc (@var{x}, @var{y}, @var{z})
+## @deftypefnx {Function File} {} surfc (@var{z})
+## @deftypefnx {Function File} {} surfc (@dots{}, @var{c})
+## @deftypefnx {Function File} {} surfc (@dots{}, @var{prop}, @var{val}, @dots{})
+## @deftypefnx {Function File} {} surfc (@var{hax}, @dots{})
+## @deftypefnx {Function File} {@var{h} =} surfc (@dots{})
+## Plot a 3-D surface mesh with underlying contour lines.
+##
+## The surface mesh is plotted using shaded rectangles.  The vertices of the
+## rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}.
+## over a 2-D rectangular region in the x-y plane.  @var{z} determines the
+## height above the plane of each vertex.  If only a single @var{z} matrix is
+## given, then it is plotted over the meshgrid
+## @code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}.
+## Thus, columns of @var{z} correspond to different @var{x} values and rows
+## of @var{z} correspond to different @var{y} values.  
+##
+## The color of the surface is computed by linearly scaling the @var{Z} values
+## to fit the range of the current colormap.  Use @code{caxis} and/or
+## change the colormap to control the appearance.
+##
+## Optionally, the color of the surface can be specified independently of
+## @var{z} by supplying a color matrix, @var{c}.
+##
+## Any property/value pairs are passed directly to the underlying surface
+## object.
+##
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
+##
+## The optional return value @var{h} is a graphics handle to the created
+## surface object.
+##
+## Note: The exact appearance of the surface can be controlled with the
+## @code{shading} command or by using @code{set} to control surface object
+## properties.
+## @seealso{ezsurfc, surf, surfl, surfnorm, trisurf, contour, mesh, surface, meshgrid, hidden, shading, colormap, caxis}
 ## @end deftypefn
 
 function h = surfc (varargin)
--- a/scripts/plot/surfl.m
+++ b/scripts/plot/surfl.m
@@ -22,20 +22,32 @@
 ## @deftypefnx {Function File} {} surfl (@var{x}, @var{y}, @var{z}, @var{L})
 ## @deftypefnx {Function File} {} surfl (@var{x}, @var{y}, @var{z}, @var{L}, @var{P})
 ## @deftypefnx {Function File} {} surfl (@dots{}, "light")
-## Plot a lighted surface given matrices @var{x}, and @var{y} from
-## @code{meshgrid} and a matrix @var{z} corresponding to the @var{x} and
-## @var{y} coordinates of the mesh.  If @var{x} and @var{y} are vectors, then
-## a typical vertex is (@var{x}(j), @var{y}(i), @var{z}(i,j)).  Thus, columns
-## of @var{z} correspond to different @var{x} values and rows of @var{z}
-## correspond to different @var{y} values.
+## @deftypefnx {Function File} {} surfl (@var{hax}, @dots{})
+## @deftypefnx {Function File} {@var{h} =} surfl (@dots{})
+##
+## Plot a 3-D surface using shading based on various lighting models.
 ##
-## The light direction can be specified using @var{L}.  It can be given as a
-## 2-element vector [azimuth, elevation] in degrees or as a 3-element vector
-## [lx, ly, lz].  The default value is rotated 45 degrees counterclockwise
-## from the current view.
+## The surface mesh is plotted using shaded rectangles.  The vertices of the
+## rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}.
+## over a 2-D rectangular region in the x-y plane.  @var{z} determines the
+## height above the plane of each vertex.  If only a single @var{z} matrix is
+## given, then it is plotted over the meshgrid
+## @code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}.
+## Thus, columns of @var{z} correspond to different @var{x} values and rows
+## of @var{z} correspond to different @var{y} values.  
 ##
-## The material properties of the surface can specified using a 4-element vector
-## @var{P} = [@var{AM} @var{D} @var{SP} @var{exp}] which defaults to
+## The default lighting mode "cdata", changes the cdata property of the
+## surface object to give the impression of a lighted surface.
+## @strong{Warning:} The alternative mode "light" mode which creates a light
+## object to illuminate the surface is not implemented (yet).
+##
+## The light source location can be specified using @var{L}.  It can be given
+## as a 2-element vector [azimuth, elevation] in degrees, or as a 3-element
+## vector [lx, ly, lz].  The default value is rotated 45 degrees
+## counterclockwise to the current view.
+##
+## The material properties of the surface can specified using a 4-element
+## vector @var{P} = [@var{AM} @var{D} @var{SP} @var{exp}] which defaults to
 ## @var{p} = [0.55 0.6 0.4 10].
 ##
 ## @table @asis
@@ -48,10 +60,11 @@
 ## @item "EXP" specular exponent
 ## @end table
 ##
-## The default lighting mode "cdata", changes the cdata property to give the
-## impression of a lighted surface.  Please note: the alternative "light"
-## mode, which creates a light object to illuminate the surface is not
-## implemented (yet).
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
+##
+## The optional return value @var{h} is a graphics handle to the created
+## surface object.
 ##
 ## Example:
 ##
@@ -62,7 +75,7 @@
 ## shading interp;
 ## @end group
 ## @end example
-## @seealso{surf, diffuse, specular, surface}
+## @seealso{diffuse, specular, surf, shading, colormap, caxis}
 ## @end deftypefn
 
 ## Author: Kai Habel <kai.habel@gmx.de>
--- a/scripts/plot/tetramesh.m
+++ b/scripts/plot/tetramesh.m
@@ -21,9 +21,9 @@
 ## @deftypefnx {Function File} {} tetramesh (@var{T}, @var{X}, @var{C})
 ## @deftypefnx {Function File} {} tetramesh (@dots{}, @var{property}, @var{val}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} tetramesh (@dots{})
+## Display the tetrahedrons defined in the m-by-4 matrix @var{T} as 3-D patches.
 ##
-## Display the tetrahedrons defined in the m-by-4 matrix @var{T}
-## as 3-D patches.  @var{T} is typically the output of a Delaunay triangulation
+## @var{T} is typically the output of a Delaunay triangulation
 ## of a 3-D set of points.  Every row of @var{T} contains four indices into
 ## the n-by-3 matrix @var{X} of the vertices of a tetrahedron.  Every row in
 ## @var{X} represents one point in 3-D space. 
@@ -43,7 +43,7 @@
 ## property "on" or "off".
 ##
 ## Type @code{demo tetramesh} to see examples on using @code{tetramesh}.
-## @seealso{delaunay3, delaunayn, trimesh, patch}
+## @seealso{trimesh, delaunay3, delaunayn, patch}
 ## @end deftypefn
 
 ## Author: Martin Helm <martin@mhelm.de>
--- a/scripts/plot/text.m
+++ b/scripts/plot/text.m
@@ -17,17 +17,19 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {} text (@var{x}, @var{y}, @var{label})
-## @deftypefnx {Function File} {} text (@var{x}, @var{y}, @var{z}, @var{label})
-## @deftypefnx {Function File} {} text (@var{x}, @var{y}, @var{label}, @var{p1}, @var{v1}, @dots{})
-## @deftypefnx {Function File} {} text (@var{x}, @var{y}, @var{z}, @var{label}, @var{p1}, @var{v1}, @dots{})
+## @deftypefn  {Function File} {} text (@var{x}, @var{y}, @var{string})
+## @deftypefnx {Function File} {} text (@var{x}, @var{y}, @var{z}, @var{string})
+## @deftypefnx {Function File} {} text (@dots{}, @var{prop}, @var{val}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} text (@dots{})
-## Create a text object with text @var{label} at position @var{x},
-## @var{y}, @var{z} on the current axes.  Property-value pairs following
-## @var{label} may be used to specify the appearance of the text.
+## Create a text object with text @var{string} at position @var{x},
+## @var{y}, @var{z} on the current axes.
+##
+## Optional property/value pairs following may be used to specify the
+## appearance of the text.
 ##
 ## The optional return value @var{h} is a graphics handle to the created text
 ## object.
+## @seealso{gtext, title, xlabel, ylabel, zlabel}
 ## @end deftypefn
 
 ## Author: jwe
--- a/scripts/plot/title.m
+++ b/scripts/plot/title.m
@@ -18,16 +18,16 @@
 
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} title (@var{string})
-## @deftypefnx {Function File} {} title (@var{string}, @var{property}, @var{val}, @dots{})
-## @deftypefnx {Function File} {} title (@var{hax}, @var{string})
-## @deftypefnx {Function File} {} title (@var{hax}, @var{string}, @var{property}, @var{val}, @dots{})
+## @deftypefnx {Function File} {} title (@var{string}, @var{prop}, @var{val}, @dots{})
+## @deftypefnx {Function File} {} title (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} title (@dots{})
 ## Specify the string used as a title for the current axis.
 ##
-## If @var{hax} is specified then title the axis defined by @var{hax}.
+## An optional list of @var{property}/@var{value} pairs can be used to change
+## the appearance of the created title text object.
 ##
-## An optional list of @var{property}/@var{value} pairs can be used to change
-## the properties of the created title text.
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a graphics handle to the created text
 ## object.
--- a/scripts/plot/trimesh.m
+++ b/scripts/plot/trimesh.m
@@ -17,15 +17,35 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {} trimesh (@var{tri}, @var{x}, @var{y}, @var{z})
+## @deftypefn  {Function File} {} trimesh (@var{tri}, @var{x}, @var{y}, @var{z}, @var{c})
+## @deftypefnx {Function File} {} trimesh (@var{tri}, @var{x}, @var{y}, @var{z})
+## @deftypefnx {Function File} {} trimesh (@var{tri}, @var{x}, @var{y})
+## @deftypefnx {Function File} {} trimesh (@dots{}, @var{prop}, @var{val}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} trimesh (@dots{})
-## Plot a triangular mesh in 3D@.  The variable @var{tri} is the triangular
-## meshing of the points @code{(@var{x}, @var{y})} which is returned
-## from @code{delaunay}.  The variable @var{z} is value at the point
-## @code{(@var{x}, @var{y})}.
+## Plot a 3-D triangular wireframe mesh.
+## 
+## In contrast to @code{mesh}, which plots a mesh using rectangles,
+## @code{trimesh} plots the mesh using triangles.
 ##
-## The optional return value @var{h} is a graphics handle to the created plot.
-## @seealso{triplot, trisurf, delaunay3}
+## @var{tri} is typically the output of a Delaunay triangulation over the
+## grid of @var{x}, @var{y}.  Every row of @var{tri} represents one triangle
+## and contains three indices into [@var{x}, @var{y}] which are the
+## vertices of the triangles in the x-y plane.  @var{z} determines the
+## height above the plane of each vertex.  If no @var{z} input is given then
+## the triangles are plotted as a 2-D figure.
+## 
+## The color of the trimesh is computed by linearly scaling the @var{z} values
+## to fit the range of the current colormap.  Use @code{caxis} and/or
+## change the colormap to control the appearance.
+##
+## Optionally, the color of the mesh can be specified independently of @var{z}
+## by supplying a color matrix, @var{c}.
+##
+## Any property/value pairs are passed directly to the underlying patch object.
+##
+## The optional return value @var{h} is a graphics handle to the created patch
+## object.
+## @seealso{mesh, tetramesh, triplot, trisurf, delaunay, patch, hidden}
 ## @end deftypefn
 
 function h = trimesh (tri, x, y, z, varargin)
--- a/scripts/plot/triplot.m
+++ b/scripts/plot/triplot.m
@@ -20,12 +20,18 @@
 ## @deftypefn  {Function File} {} triplot (@var{tri}, @var{x}, @var{y})
 ## @deftypefnx {Function File} {} triplot (@var{tri}, @var{x}, @var{y}, @var{linespec})
 ## @deftypefnx {Function File} {@var{h} =} triplot (@dots{})
-## Plot a triangular mesh in 2D@.  The variable @var{tri} is the triangular
-## meshing of the points @code{(@var{x}, @var{y})} which is returned from
-## @code{delaunay}.  If given, @var{linespec} determines the properties
-## to use for the lines. 
+## Plot a 2-D triangular mesh.
+## 
+## @var{tri} is typically the output of a Delaunay triangulation over the
+## grid of @var{x}, @var{y}.  Every row of @var{tri} represents one triangle
+## and contains three indices into [@var{x}, @var{y}] which are the
+## vertices of the triangles in the x-y plane.
 ##
-## The optional return value @var{h} is a graphics handle to the created plot.
+## The linestyle to use for the plot can be defined with the argument
+## @var{linespec} of the same format as the @code{plot} command.
+##
+## The optional return value @var{h} is a graphics handle to the created
+## patch object.
 ## @seealso{plot, trimesh, trisurf, delaunay}
 ## @end deftypefn
 
--- a/scripts/plot/trisurf.m
+++ b/scripts/plot/trisurf.m
@@ -17,15 +17,33 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {} trisurf (@var{tri}, @var{x}, @var{y}, @var{z})
+## @deftypefn  {Function File} {} trisurf (@var{tri}, @var{x}, @var{y}, @var{z}, @var{c})
+## @deftypefnx {Function File} {} trisurf (@var{tri}, @var{x}, @var{y}, @var{z})
+## @deftypefnx {Function File} {} trisurf (@dots{}, @var{prop}, @var{val}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} trisurf (@dots{})
-## Plot a triangular surface in 3D@.  The variable @var{tri} is the triangular
-## meshing of the points @code{(@var{x}, @var{y})} which is returned
-## from @code{delaunay}.  The variable @var{z} is value at the point
-## @code{(@var{x}, @var{y})}.
+## Plot a 3-D triangular surface.
+## 
+## In contrast to @code{surf}, which plots a surface mesh using rectangles,
+## @code{trisurf} plots the mesh using triangles.
 ##
-## The optional return value @var{h} is a graphics handle to the created plot.
-## @seealso{triplot, trimesh, delaunay3}
+## @var{tri} is typically the output of a Delaunay triangulation over the
+## grid of @var{x}, @var{y}.  Every row of @var{tri} represents one triangle
+## and contains three indices into [@var{x}, @var{y}] which are the
+## vertices of the triangles in the x-y plane.  @var{z} determines the
+## height above the plane of each vertex.
+## 
+## The color of the trimesh is computed by linearly scaling the @var{z} values
+## to fit the range of the current colormap.  Use @code{caxis} and/or
+## change the colormap to control the appearance.
+##
+## Optionally, the color of the mesh can be specified independently of @var{z}
+## by supplying a color matrix, @var{c}.
+##
+## Any property/value pairs are passed directly to the underlying patch object.
+##
+## The optional return value @var{h} is a graphics handle to the created patch
+## object.
+## @seealso{surf, triplot, trimesh, delaunay, patch, shading}
 ## @end deftypefn
 
 function h = trisurf (tri, x, y, z, varargin)
--- a/scripts/plot/view.m
+++ b/scripts/plot/view.m
@@ -17,24 +17,29 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {[@var{azimuth}, @var{elevation}] =} view ()
-## @deftypefnx {Function File} {} view (@var{azimuth}, @var{elevation})
+## @deftypefn  {Function File} {} view (@var{azimuth}, @var{elevation})
 ## @deftypefnx {Function File} {} view ([@var{azimuth} @var{elevation}])
 ## @deftypefnx {Function File} {} view ([@var{x} @var{y} @var{z}])
 ## @deftypefnx {Function File} {} view (2)
 ## @deftypefnx {Function File} {} view (3)
-## @deftypefnx {Function File} {} view (@var{ax}, @dots{})
-## Query or set the viewpoint for the current axes.  The parameters
-## @var{azimuth} and @var{elevation} can be given as two arguments or as
-## 2-element vector.
-## The viewpoint can also be given with Cartesian coordinates @var{x},
-## @var{y}, and @var{z}.
+## @deftypefnx {Function File} {} view (@var{hax}, @dots{})
+## @deftypefnx {Function File} {[@var{azimuth}, @var{elevation}] =} view ()
+## Query or set the viewpoint for the current axes.
+##
+## The parameters @var{azimuth} and @var{elevation} can be given as two
+## arguments or as 2-element vector.  The viewpoint can also be specified with
+## Cartesian coordinates @var{x}, @var{y}, and @var{z}.
+##
 ## The call @code{view (2)} sets the viewpoint to @var{azimuth} = 0
 ## and @var{elevation} = 90, which is the default for 2-D graphs.
+##
 ## The call @code{view (3)} sets the viewpoint to @var{azimuth} = -37.5
 ## and @var{elevation} = 30, which is the default for 3-D graphs.
-## If @var{ax} is given, the viewpoint is set for this axes, otherwise
-## it is set for the current axes.
+##
+## If the first argument @var{hax} is an axes handle, then operate on
+## this axis rather than the current axes returned by @code{gca}.
+##
+## If no inputs are given, return the current @var{azimuth} and @var{elevation}.
 ## @end deftypefn
 
 ## Author: jwe
--- a/scripts/plot/waitbar.m
+++ b/scripts/plot/waitbar.m
@@ -23,11 +23,12 @@
 ## @deftypefnx {Function File} {} waitbar (@var{frac})
 ## @deftypefnx {Function File} {} waitbar (@var{frac}, @var{hwbar})
 ## @deftypefnx {Function File} {} waitbar (@var{frac}, @var{hwbar}, @var{msg})
-## Return a handle @var{h} to a new waitbar object.  The waitbar is
-## filled to fraction @var{frac} which must be in the range [0, 1].  The
-## optional message @var{msg} is centered and displayed above the waitbar.
-## The appearance of the waitbar figure window can be configured by passing
-## property/value pairs to the function.
+## Return a handle @var{h} to a new waitbar object.
+##
+## The waitbar is filled to fraction @var{frac} which must be in the range
+## [0, 1].  The optional message @var{msg} is centered and displayed above the
+## waitbar.  The appearance of the waitbar figure window can be configured by
+## passing property/value pairs to the function.
 ## 
 ## When called with a single input the current waitbar, if it exists, is
 ## updated to the new value @var{frac}.  If there are multiple outstanding
--- a/scripts/plot/waitforbuttonpress.m
+++ b/scripts/plot/waitforbuttonpress.m
@@ -17,11 +17,13 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function File} {@var{b} =} waitforbuttonpress ()
-## Wait for button or mouse press.over a figure window.  The value of
-## @var{b} returns 0 if a mouse button was pressed or 1 is a key was
-## pressed.
-## @seealso{ginput}
+## @deftypefn  {Function File} {} waitforbuttonpress ()
+## @deftypefnx {Function File} {@var{b} =} waitforbuttonpress ()
+## Wait for mouse click or key press over the current figure window.
+##
+## The return value of @var{b} is 0 if a mouse button was pressed or 1 if a
+## key was pressed.
+## @seealso{waitfor, ginput}
 ## @end deftypefn
 
 ## The original version of this code bore the copyright
--- a/scripts/plot/waterfall.m
+++ b/scripts/plot/waterfall.m
@@ -19,35 +19,59 @@
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} waterfall (@var{x}, @var{y}, @var{z})
 ## @deftypefnx {Function File} {} waterfall (@var{z})
+## @deftypefnx {Function File} {} waterfall (@dots{}, @var{c})
+## @deftypefnx {Function File} {} waterfall (@dots{}, @var{prop}, @var{val}, @dots{})
+## @deftypefnx {Function File} {} waterfall (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} waterfall (@dots{})
-## Plot a waterfall plot given matrices @var{x}, and @var{y} from
-## @code{meshgrid} and a matrix @var{z} corresponding to the @var{x} and
-## @var{y} coordinates of the mesh.  If @var{x} and @var{y} are vectors,
-## then a typical vertex is (@var{x}(j), @var{y}(i), @var{z}(i,j)).  Thus,
-## columns of @var{z} correspond to different @var{x} values and rows of
-## @var{z} correspond to different @var{y} values.
+## Plot a 3-D waterfall plot.
+##
+## A waterfall plot is similar to a @code{meshz} plot except only
+## mesh lines for the rows of @var{z} (x-values) are shown.
+##
+## The wireframe mesh is plotted using rectangles.  The vertices of the
+## rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}.
+## over a 2-D rectangular region in the x-y plane.  @var{z} determines the
+## height above the plane of each vertex.  If only a single @var{z} matrix is
+## given, then it is plotted over the meshgrid
+## @code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}.
+## Thus, columns of @var{z} correspond to different @var{x} values and rows
+## of @var{z} correspond to different @var{y} values.  
+##
+## The color of the mesh is computed by linearly scaling the @var{Z} values
+## to fit the range of the current colormap.  Use @code{caxis} and/or
+## change the colormap to control the appearance.
+##
+## Optionally the color of the mesh can be specified independently of @var{z}
+## by supplying a color matrix, @var{c}.
+##
+## Any property/value pairs are passed directly to the underlying surface
+## object.
+##
+## If the first argument @var{hax} is an axes handle, then plot into this axis,
+## rather than the current axes returned by @code{gca}.
 ##
 ## The optional return value @var{h} is a graphics handle to the created
 ## surface object.
-## @seealso{meshgrid, meshz, surf}
+##
+## @seealso{meshz, mesh, meshc, contour, surf, surface, ribbon, meshgrid, hidden, shading, colormap, caxis}
 ## @end deftypefn
 
 ## Author: Mike Miller <mtmiller@ieee.org>
 
 function h = waterfall (varargin)
 
-  tmp = meshz (varargin{:});
+  htmp = meshz (varargin{:});
 
-  set (tmp, "meshstyle", "row");
+  set (htmp, "meshstyle", "row");
 
   ## The gnuplot toolkit does nothing with the meshstyle property currently.
-  toolkit = get (ancestor (tmp, "figure"), "__graphics_toolkit__");
+  toolkit = get (ancestor (htmp, "figure"), "__graphics_toolkit__");
   if (strcmp (toolkit, "gnuplot"))
     warning ("waterfall: may not render correctly using toolkit '%s'", toolkit);
   endif
 
   if (nargout > 0)
-    h = tmp;
+    h = htmp;
   endif
 
 endfunction
--- a/scripts/plot/whitebg.m
+++ b/scripts/plot/whitebg.m
@@ -20,20 +20,21 @@
 ## @deftypefn  {Function File} {} whitebg ()
 ## @deftypefnx {Function File} {} whitebg (@var{color})
 ## @deftypefnx {Function File} {} whitebg ("none")
-## @deftypefnx {Function File} {} whitebg (@var{fig})
-## @deftypefnx {Function File} {} whitebg (@var{fig}, @var{color})
-## @deftypefnx {Function File} {} whitebg (@var{fig}, "none")
-## Invert the colors in the current color scheme.  The root properties are
-## also inverted such that all subsequent plot use the new color scheme.
+## @deftypefnx {Function File} {} whitebg (@var{hfig}, @dots{})
+## Invert the colors in the current color scheme.
 ##
-## If defined, @var{fig} is the handle to the figure to be inverted.  In
-## this case only the specified figure has its color properties changed.
+## The root properties are also inverted such that all subsequent plot use the
+## new color scheme.
 ##
 ## If the optional argument @var{color} is present then the background color
 ## is set to @var{color} rather than inverted.  @var{color} may be a string
 ## representing one of the eight known colors or an RGB triplet.  The special
 ## string argument "none" restores the plot to the default colors.
-## @seealso{reset}
+##
+## If the first argument @var{hfig} is a figure handle, then operate on
+## this figure rather than the current figure returned by @code{gcf}.  The
+## root properties will not be changed.
+## @seealso{reset, get, set}
 ## @end deftypefn
 
 function whitebg (varargin)
--- a/scripts/plot/xlabel.m
+++ b/scripts/plot/xlabel.m
@@ -19,19 +19,19 @@
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} xlabel (@var{string})
 ## @deftypefnx {Function File} {} xlabel (@var{string}, @var{property}, @var{val}, @dots{})
-## @deftypefnx {Function File} {} xlabel (@var{hax}, @var{string})
-## @deftypefnx {Function File} {} xlabel (@var{hax}, @var{string}, @var{property}, @var{val}, @dots{})
+## @deftypefnx {Function File} {} xlabel (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} xlabel (@dots{})
 ## Specify the string used to label the x-axis of the current axis.
 ##
-## If @var{hax} is specified then label the axis defined by @var{hax}.
-##
 ## An optional list of @var{property}/@var{value} pairs can be used to change
 ## the properties of the created text label.
 ##
+## If the first argument @var{hax} is an axes handle, then operate on
+## this axis rather than the current axes returned by @code{gca}.
+##
 ## The optional return value @var{h} is a graphics handle to the created text
 ## object.
-## @seealso{ylabel, zlabel, title, text}
+## @seealso{ylabel, zlabel, datetick, title, text}
 ## @end deftypefn
 
 ## Author: jwe
--- a/scripts/plot/xlim.m
+++ b/scripts/plot/xlim.m
@@ -17,28 +17,27 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @c List other forms of function in documentation index
-## @findex ylim
-## @findex zlim
+## @deftypefn  {Function File} {@var{xlimits} =} xlim ()
+## @deftypefnx {Function File} {@var{xmode} =} xlim ("mode")
+## @deftypefnx {Function File} {} xlim ([@var{x_lo} @var{x_hi}])
+## @deftypefnx {Function File} {} xlim ("auto")
+## @deftypefnx {Function File} {} xlim ("manual")
+## @deftypefnx {Function File} {} xlim (@var{hax}, @dots{})
+## Query or set the limits of the x-axis of the current plot.
 ##
-## @deftypefn  {Function File} {@var{xl} =} xlim ()
-## @deftypefnx {Function File} {} xlim (@var{xl})
-## @deftypefnx {Function File} {@var{m} =} xlim ("mode")
-## @deftypefnx {Function File} {} xlim (@var{m})
-## @deftypefnx {Function File} {} xlim (@var{h}, @dots{})
-## Get or set the limits of the x-axis of the current plot.  Called without
-## arguments @code{xlim} returns the x-axis limits of the current plot.
-## If passed a two element vector @var{xl}, the limits of the x-axis are set
-## to this value.
+## Called without arguments @code{xlim} returns the x-axis limits of the
+## current plot.  With the input query "mode", return the current x-limit
+## calculation mode which is either "auto" or "manual".
+##
+## If passed a 2-element vector [@var{x_lo} @var{x_hi}], the limits of the
+## x-axis are set to these values.
 ##
-## The current mode for calculation of the x-axis can be returned with a
-## call @code{xlim ("mode")}, and can be either "auto" or "manual".  The
-## current plotting mode can be set by passing either "auto" or "manual"
-## as the argument.
+## The current plotting mode can be set by passing either "auto" or "manual" as
+## the argument.
 ##
-## If passed a handle as the first argument, then operate on this handle
-## rather than the current axes handle.
-## @seealso{ylim, zlim, set, get, gca}
+## If the first argument @var{hax} is an axes handle, then operate on
+## this axis rather than the current axes returned by @code{gca}.
+## @seealso{ylim, zlim, axis, set, get, gca}
 ## @end deftypefn
 
 function retval = xlim (varargin)
--- a/scripts/plot/ylabel.m
+++ b/scripts/plot/ylabel.m
@@ -19,8 +19,7 @@
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} ylabel (@var{string})
 ## @deftypefnx {Function File} {} ylabel (@var{string}, @var{property}, @var{val}, @dots{})
-## @deftypefnx {Function File} {} ylabel (@var{hax}, @var{string})
-## @deftypefnx {Function File} {} ylabel (@var{hax}, @var{string}, @var{property}, @var{val}, @dots{})
+## @deftypefnx {Function File} {} ylabel (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} ylabel (@dots{})
 ## Specify the string used to label the y-axis of the current axis.
 ##
@@ -29,9 +28,12 @@
 ## An optional list of @var{property}/@var{value} pairs can be used to change
 ## the properties of the created text label.
 ##
+## If the first argument @var{hax} is an axes handle, then operate on
+## this axis rather than the current axes returned by @code{gca}.
+##
 ## The optional return value @var{h} is a graphics handle to the created text
 ## object.
-## @seealso{xlabel, zlabel, title, text}
+## @seealso{xlabel, zlabel, datetick, title, text}
 ## @end deftypefn
 
 ## Author: jwe
--- a/scripts/plot/ylim.m
+++ b/scripts/plot/ylim.m
@@ -17,24 +17,27 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {@var{yl} =} ylim ()
-## @deftypefnx {Function File} {} ylim (@var{yl})
-## @deftypefnx {Function File} {@var{m} =} ylim ("mode")
-## @deftypefnx {Function File} {} ylim (@var{m})
-## @deftypefnx {Function File} {} ylim (@var{h}, @dots{})
-## Get or set the limits of the y-axis of the current plot.  Called without
-## arguments @code{ylim} returns the y-axis limits of the current plot.
-## If passed a two element vector @var{yl}, the limits of the y-axis are set
-## to this value.
+## @deftypefn  {Function File} {@var{ylimits} =} ylim ()
+## @deftypefnx {Function File} {@var{xmode} =} ylim ("mode")
+## @deftypefnx {Function File} {} ylim ([@var{y_lo} @var{y_hi}])
+## @deftypefnx {Function File} {} ylim ("auto")
+## @deftypefnx {Function File} {} ylim ("manual")
+## @deftypefnx {Function File} {} ylim (@var{hax}, @dots{})
+## Query or set the limits of the y-axis of the current plot.
 ##
-## The current mode for calculation of the y-axis can be returned with a
-## call @code{ylim ("mode")}, and can be either "auto" or "manual".  The
-## current plotting mode can be set by passing either "auto" or "manual"
-## as the argument.
+## Called without arguments @code{ylim} returns the y-axis limits of the
+## current plot.  With the input query "mode", return the current y-limit
+## calculation mode which is either "auto" or "manual".
+##
+## If passed a 2-element vector [@var{y_lo} @var{y_hi}], the limits of the
+## y-axis are set to these values.
 ##
-## If passed a handle as the first argument, then operate on this handle
-## rather than the current axes handle.
-## @seealso{xlim, zlim, set, get, gca}
+## The current plotting mode can be set by passing either "auto" or "manual" as
+## the argument.
+##
+## If the first argument @var{hax} is an axes handle, then operate on
+## this axis rather than the current axes returned by @code{gca}.
+## @seealso{xlim, zlim, axis, set, get, gca}
 ## @end deftypefn
 
 function retval = ylim (varargin)
--- a/scripts/plot/zlabel.m
+++ b/scripts/plot/zlabel.m
@@ -19,19 +19,19 @@
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} zlabel (@var{string})
 ## @deftypefnx {Function File} {} zlabel (@var{string}, @var{property}, @var{val}, @dots{})
-## @deftypefnx {Function File} {} zlabel (@var{hax}, @var{string})
-## @deftypefnx {Function File} {} zlabel (@var{hax}, @var{string}, @var{property}, @var{val}, @dots{})
+## @deftypefnx {Function File} {} zlabel (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} zlabel (@dots{})
 ## Specify the string used to label the z-axis of the current axis.
 ##
-## If @var{hax} is specified then label the axis defined by @var{hax}.
-##
 ## An optional list of @var{property}/@var{value} pairs can be used to change
 ## the properties of the created text label.
 ##
+## If the first argument @var{hax} is an axes handle, then operate on
+## this axis rather than the current axes returned by @code{gca}.
+##
 ## The optional return value @var{h} is a graphics handle to the created text
 ## object.
-## @seealso{xlabel, ylabel, title, text}
+## @seealso{xlabel, ylabel, datetick, title, text}
 ## @end deftypefn
 ## Author: jwe
 
--- a/scripts/plot/zlim.m
+++ b/scripts/plot/zlim.m
@@ -17,24 +17,27 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {@var{zl} =} zlim ()
-## @deftypefnx {Function File} {} zlim (@var{zl})
-## @deftypefnx {Function File} {@var{m} =} zlim ("mode")
-## @deftypefnx {Function File} {} zlim (@var{m})
-## @deftypefnx {Function File} {} zlim (@var{h}, @dots{})
-## Get or set the limits of the z-axis of the current plot.  Called without
-## arguments @code{zlim} returns the z-axis limits of the current plot.
-## If passed a two element vector @var{zl}, the limits of the z-axis are set
-## to this value.
+## @deftypefn  {Function File} {@var{zlimits} =} zlim ()
+## @deftypefnx {Function File} {@var{xmode} =} zlim ("mode")
+## @deftypefnx {Function File} {} zlim ([@var{z_lo} @var{z_hi}])
+## @deftypefnx {Function File} {} zlim ("auto")
+## @deftypefnx {Function File} {} zlim ("manual")
+## @deftypefnx {Function File} {} zlim (@var{hax}, @dots{})
+## Query or set the limits of the z-axis of the current plot.
 ##
-## The current mode for calculation of the z-axis can be returned with a
-## call @code{zlim ("mode")}, and can be either "auto" or "manual".  The
-## current plotting mode can be set by passing either "auto" or "manual"
-## as the argument.
+## Called without arguments @code{zlim} returns the z-axis limits of the
+## current plot.  With the input query "mode", return the current z-limit
+## calculation mode which is either "auto" or "manual".
+##
+## If passed a 2-element vector [@var{z_lo} @var{z_hi}], the limits of the
+## z-axis are set to these values.
 ##
-## If passed a handle as the first argument, then operate on this handle
-## rather than the current axes handle.
-## @seealso{xlim, ylim, set, get, gca}
+## The current plotting mode can be set by passing either "auto" or "manual" as
+## the argument.
+##
+## If the first argument @var{hax} is an axes handle, then operate on
+## this axis rather than the current axes returned by @code{gca}.
+## @seealso{xlim, ylim, axis, set, get, gca}
 ## @end deftypefn
 
 function retval = zlim (varargin)