--- a/scripts/plot/pie3.m
+++ b/scripts/plot/pie3.m
@@ -19,50 +19,60 @@
 
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} pie3 (@var{x})
-## @deftypefnx {Function File} {} pie3 (@var{x}, @var{explode})
+## @deftypefnx {Function File} {} pie3 (@dots{}, @var{explode})
 ## @deftypefnx {Function File} {} pie3 (@dots{}, @var{labels})
-## @deftypefnx {Function File} {} pie3 (@var{h}, @dots{});
+## @deftypefnx {Function File} {} pie3 (@var{hax}, @dots{});
 ## @deftypefnx {Function File} {@var{h} =} pie3 (@dots{});
 ## Plot a 3-D pie chart.
 ##
 ## Called with a single vector argument, produces a 3-D pie chart of the
 ## elements in @var{x}.  The size of the ith slice is the percentage that the
-## element @var{x}i represents of the total sum of @var{x}.
+## element @var{x}i represents of the total sum of @var{x}:
+## @code{pct = @var{x}(i) / sum (@var{x})}. 
 ##
-## The variable @var{explode} is a vector of the same length as @var{x} that,
-## if non-zero, "explodes" the slice from the pie chart.
+## The optional input @var{explode} is a vector of the same length as @var{x}
+## that, if non-zero, "explodes" the slice from the pie chart.
 ##
 ## 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}.
+##
 ## The optional return value @var{h} is a list of graphics handles to the patch,
 ## surface, and text objects generating the plot.
 ##
-## @seealso{pie, bar, stem}
+## 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)}.
+## Furthermore, if the sum is less than 1 then there will be a missing slice
+## in the pie plot to represent the missing, unspecified percentage.
+##
+## @seealso{pie, bar, hist, rose}
 ## @end deftypefn
 
 ## Very roughly based on pie.m from octave-forge whose author was
 ## Daniel Heiserer <Daniel.heiserer@physik.tu-muenchen.de>
 
-function retval = pie3 (varargin)
+function h = pie3 (varargin)
 
-  [h, varargin] = __plt_get_axis_arg__ ("pie", varargin{:});
+  [hax, varargin, nargin] = __plt_get_axis_arg__ ("pie3", varargin{:});
 
   if (nargin < 1)
     print_usage ();
-  else
-    oldh = gca ();
-    unwind_protect
-      axes (h);
-      newplot ();
-      tmp = __pie__ ("pie3", h, varargin{:});
-    unwind_protect_cleanup
-      axes (oldh);
-    end_unwind_protect
   endif
 
+  oldfig = ifelse (isempty (hax), [], get (0, "currentfigure"));
+  unwind_protect
+    hax = newplot (hax);
+    htmp = __pie__ ("pie3", hax, varargin{:});
+  unwind_protect_cleanup
+    if (! isempty (oldfig))
+      set (0, "currentfigure", oldfig);
+    endif
+  end_unwind_protect
+
   if (nargout > 0)
-    retval = tmp;
+    h = htmp;
   endif
 
 endfunction