Add a warning about associativity.

[scilab.git] / scilab / modules / core / help / en_US / 1_keywords / hat.xml

diff --git a/scilab/modules/core/help/en_US/1_keywords/hat.xml b/scilab/modules/core/help/en_US/1_keywords/hat.xml
index 3ff9659..3d27413 100644 (file)
--- a/scilab/modules/core/help/en_US/1_keywords/hat.xml
+++ b/scilab/modules/core/help/en_US/1_keywords/hat.xml
@@ -1,5 +1,5 @@
-        <?xml version="1.0" encoding="UTF-8"?>
-    <!--
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) INRIA
  * 
@@ -7,50 +7,55 @@
  * This source file is licensed as described in the file COPYING, which
  * you should have received as part of this distribution.  The terms
  * are also available at    
- * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
  *
  -->
-    <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="hat">
-        <refnamediv>
-            <refname>hat</refname>
-            <refpurpose>(^) exponentiation</refpurpose>
-        </refnamediv>
-        <refsynopsisdiv>
-            <title>Calling Sequence</title>
-            <synopsis>A^b</synopsis>
-        </refsynopsisdiv>
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="hat">
+    <refnamediv>
+        <refname>hat</refname>
+        <refpurpose>(^) exponentiation</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>A^b</synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Description</title>
+        <para>
+            Exponentiation of matrices or vectors by a constant vector.
+        </para>
+        <para>
+            If <literal>A</literal> is a vector or a rectangular matrix the exponentiation is done
+            element-wise, with the usual meaning.
+        </para>
+        <para>
+            For square <literal>A</literal> matrix the exponentiation is done in the matrix sense.
+        </para>
+        <para>
+            For boolean, polynomial and rational matrices, the exponent must be an
+            integer.
+        </para>
         <refsection>
-            <title>Description</title>
+            <title>Remarks </title>
             <para>
-                Exponentiation of matrices or vectors by a constant vector.
+                <literal>123.^b</literal> is interpreted as <literal>(123).^b</literal>. In such
+                cases dot is part of the operator, not of the number.
             </para>
             <para>
-                If <literal>A</literal> is a vector or a rectangular matrix the exponentiation is done
-                element-wise, with the usual meaning.
+                For two real or complex numbers <literal>x1</literal> and
+                <literal>x2</literal> the value of  <literal>x1^x2</literal> is the "principal value"
+                determined by <literal>x1^x2 = exp(x2*log(x1))</literal>.
             </para>
             <para>
-                For square <literal>A</literal> matrix the exponentiation is done in the matrix sense.
+                <warning>
+                    Exponentiation is right-associative in Scilab contrarily to Matlab&#174; and Octave. For example 2^3^4 is equal to 2^(3^4) in Scilab but is equal to (2^3)^4 in Matlab&#174; and Octave.
+                </warning>
             </para>
-            <para>
-                For boolean, polynomial and rational matrices, the exponent must be an
-                integer.
-            </para>
-            <refsection>
-                <title>Remarks </title>
-                <para>
-                    <literal>123.^b</literal> is interpreted as <literal>(123).^b</literal>. In such
-                    cases dot is part of the operator, not of the number.
-                </para>
-                <para>
-                    For two real or complex numbers <literal>x1</literal> and
-                    <literal>x2</literal> the value of  <literal>x1^x2</literal> is the "principal value"
-                    determined by <literal>x1^x2 = exp(x2*log(x1))</literal>.
-                </para>
-            </refsection>
         </refsection>
-        <refsection>
-            <title>Examples</title>
-            <programlisting role="example"><![CDATA[ 
+    </refsection>
+    <refsection>
+        <title>Examples</title>
+        <programlisting role="example"><![CDATA[ 
 2^4
 (-0.5)^(1/3)
 [1 2;2 4]^(1+%i)
@@ -58,16 +63,16 @@ s=poly(0,"s");
 [1 2 s]^4
 [s 1;1  s]^(-1)
  ]]></programlisting>
-        </refsection>
-        <refsection role="see also">
-            <title>See Also</title>
-            <simplelist type="inline">
-                <member>
-                    <link linkend="exp">exp</link>
-                </member>
-                <member>
-                    <link linkend="log">log</link>
-                </member>
-            </simplelist>
-        </refsection>
-    </refentry>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="exp">exp</link>
+            </member>
+            <member>
+                <link linkend="log">log</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>