# HG changeset patch
# User Jordi Gutiérrez Hermoso <jordigh@octave.org>
# Date 1326054293 18000
# Node ID c0ca47ab764161a014a4e4cab38e8bd13ab3ec36
# Parent  7ffd2a0791ef389474bb52228e9b046a3721ab3f
doc: Better explain which complex result is chosen by .^

* expr.txi: Explain which complex root is chosen and how to choose a
  real one if preferred.
* data.cc (power): Ditto.
* help.cc (.^, .**): Ditto. (^, **): Suggest using real-valued functions.

diff -r 7ffd2a0791ef -r c0ca47ab7641 doc/interpreter/expr.txi
--- a/doc/interpreter/expr.txi	Sat Jan 07 12:44:34 2012 -0500
+++ b/doc/interpreter/expr.txi	Sun Jan 08 15:24:53 2012 -0500
@@ -603,7 +603,11 @@
 @opindex .^
 Element by element power operator. If both operands are matrices, the
 number of rows and columns must both agree, or they must be
-broadcastable to the same shape.
+broadcastable to the same shape. If several complex results are
+possible, the one with smallest nonnegative argument (angle) is taken.
+This may mean a complex root even if a real root is also possible. Use
+@code{realpow}, @code{realsqrt}, @code{cbrt}, or @code{nthroot} if a
+real result is preferred.
 
 @item -@var{x}
 @opindex -
diff -r 7ffd2a0791ef -r c0ca47ab7641 src/data.cc
--- a/src/data.cc	Sat Jan 07 12:44:34 2012 -0500
+++ b/src/data.cc	Sun Jan 08 15:24:53 2012 -0500
@@ -5599,9 +5599,13 @@
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} power (@var{x}, @var{y})\n\
 Return the element-by-element operation of @var{x} raised to the\n\
-@var{y} power.\n\
+@var{y} power. If several complex results are possible,\n\
+returns the one with smallest nonnegative argument (angle). Use\n\
+@code{realpow}, @code{realsqrt}, @code{cbrt}, or @code{nthroot} if a\n\
+real result is preferred.\n\
+\n\
 This function and @w{@xcode{x .^ y}} are equivalent.\n\
-@seealso{mpower}\n\
+@seealso{mpower, realpow, realsqrt, cbrt, nthroot}\n\
 @end deftypefn")
 {
   return binary_op_defun_body (octave_value::op_el_pow, args);
diff -r 7ffd2a0791ef -r c0ca47ab7641 src/help.cc
--- a/src/help.cc	Sat Jan 07 12:44:34 2012 -0500
+++ b/src/help.cc	Sun Jan 08 15:24:53 2012 -0500
@@ -239,15 +239,19 @@
   pair_type ("**",
     "-*- texinfo -*-\n\
 @deftypefn {Operator} {} **\n\
-Power operator.\n\
-@seealso{power, ^, .**, .^}\n\
+Power operator. This may return complex results for real inputs. Use\n\
+@code{realsqrt}, @code{cbrt}, @code{nthroot}, or @code{realroot} to obtain\n\
+real results when possible.\n\
+@seealso{power, ^, .**, .^, realpow, realsqrt, cbrt, nthroot}\n\
 @end deftypefn"),
 
   pair_type ("^",
     "-*- texinfo -*-\n\
 @deftypefn {Operator} {} ^\n\
-Power operator.\n\
-@seealso{power, **, .^, .**}\n\
+Power operator. This may return complex results for real inputs. Use\n\
+@code{realsqrt}, @code{cbrt}, @code{nthroot}, or @code{realroot} to obtain\n\
+real results when possible.\n\
+@seealso{power, **, .^, .**, realpow, realsqrt, cbrt, nthroot}\n\
 @end deftypefn"),
 
   pair_type ("+",
@@ -304,15 +308,21 @@
   pair_type (".**",
     "-*- texinfo -*-\n\
 @deftypefn {Operator} {} .*\n\
-Element by element power operator.\n\
-@seealso{**, ^, .^, power}\n\
+Element by element power operator. If several complex results are possible,\n\
+returns the one with smallest nonnegative argument (angle). Use\n\
+@code{realpow}, @code{realsqrt}, @code{cbrt}, or @code{nthroot} if a\n\
+real result is preferred.\n\
+@seealso{**, ^, .^, power, realpow, realsqrt, cbrt, nthroot}\n\
 @end deftypefn"),
 
   pair_type (".^",
     "-*- texinfo -*-\n\
 @deftypefn {Operator} {} .^\n\
-Element by element power operator.\n\
-@seealso{.**, ^, **, power}\n\
+Element by element power operator. If several complex results are possible,\n\
+returns the one with smallest nonnegative argument (angle). Use\n\
+@code{realpow}, @code{realsqrt}, @code{cbrt}, or @code{nthroot} if a\n\
+real result is preferred.\n\
+@seealso{.**, ^, **, power, realpow, realsqrt, cbrt, nthroot}\n\
 @end deftypefn"),
 
   pair_type ("./",