--- a/scripts/plot/hold.m	Tue Jul 23 14:31:58 2013 +0200
+++ b/scripts/plot/hold.m	Tue Jul 23 15:10:57 2013 +0200
@@ -18,7 +18,9 @@
 
 ## -*- texinfo -*-
 ## @deftypefn  {Command} {} hold
-## @deftypefnx {Command} {} hold @var{state}
+## @deftypefnx {Command} {} hold on
+## @deftypefnx {Command} {} hold off
+## @deftypefnx {Command} {} hold all
 ## @deftypefnx {Function File} {} hold (@var{hax}, @dots{})
 ## Toggle or set the "hold" state of the plotting engine which determines
 ## whether new graphic objects are added to the plot or replace the existing
@@ -30,13 +32,13 @@
 ## on a single graph.
 ##
 ## @item hold all
-## Retain plot line color, line style, data and settings so that subsequent
+## Retain plot line color, line style, data, and settings so that subsequent
 ## plot commands are displayed on a single graph with the next line color and
 ## style.
 ##
 ## @item hold off
-## Clear plot and restore default graphics settings before each new plot
-## command.  (default).
+## Restore default graphics settings which clear the graph and reset axis
+## properties before each new plot command.  (default).
 ##
 ## @item hold
 ## Toggle the current hold state.
@@ -46,26 +48,30 @@
 ## only for the given axis handle.
 ##
 ## To query the current hold state use the @code{ishold} function.
-## @seealso{ishold, cla, newplot, clf}
+## @seealso{ishold, cla, clf, newplot}
 ## @end deftypefn
 
 function hold (varargin)
 
-  if (nargin > 0 && numel (varargin{1}) == 1 && ishandle (varargin{1})
+  if (nargin > 0 && isscalar (varargin{1}) && ishandle (varargin{1})
       && strcmp (get (varargin{1}, "type"), "axes"))
-    [ax, varargin, nargs] = __plt_get_axis_arg__ ("hold", varargin{:});
-    fig = get (ax, "parent");
+    [hax, varargin, nargs] = __plt_get_axis_arg__ ("hold", varargin{:});
+    if (isempty (hax))
+      hax = gca ();
+    endif
+    ## FIXME: Should this be ancestor (hax, "parent")?
+    hfig = get (hax, "parent");
   elseif (nargin > 0 && numel (varargin{1}) > 1 && ishandle (varargin{1}))
     print_usage ();
   else
-    ax = gca ();
-    fig = gcf ();
+    hax = gca ();
+    hfig = gcf ();
     nargs = numel (varargin);
   endif
 
   hold_all = false;
   if (nargs == 0)
-    turn_hold_off = ishold (ax);
+    turn_hold_off = ishold (hax);
   elseif (nargs == 1)
     state = varargin{1};
     if (ischar (state))
@@ -85,18 +91,36 @@
   endif
 
   if (turn_hold_off)
-    set (ax, "nextplot", "replace");
+    set (hax, "nextplot", "replace");
   else
-    set (ax, "nextplot", "add");
-    set (fig, "nextplot", "add");
+    set (hax, "nextplot", "add");
+    set (hfig, "nextplot", "add");
   endif
-  set (ax, "__hold_all__", hold_all);
+  set (hax, "__hold_all__", hold_all);
 
 endfunction
 
 
 %!demo
 %! clf;
+%! t = linspace (0, 2*pi, 100);
+%! plot (t, sin (t));
+%! hold on;
+%! plot (t, cos (t));
+%! title ({'hold on', '2 plots shown on same graph'});
+%! hold off;
+
+%!demo
+%! clf;
+%! t = linspace (0, 2*pi, 100);
+%! plot (t, sin (t));
+%! hold all;
+%! plot (t, cos (t));
+%! title ({'hold all', '2 plots shown on same graph with linestyle also preserved'});
+%! hold off;
+
+%!demo
+%! clf;
 %! A = rand (100);
 %! [X, Y] = find (A > 0.9);
 %! imshow (A);
@@ -143,7 +167,7 @@
 %! colorbar ('SouthOutside');
 %! title ('Test script for some plot functions');
 
-##hold on
+## hold on test
 %!test
 %! hf = figure ("visible", "off");
 %! unwind_protect
@@ -159,7 +183,7 @@
 %!   close (hf);
 %! end_unwind_protect
 
-##hold off
+## hold off test
 %!test
 %! hf = figure ("visible", "off");
 %! unwind_protect