[doc] misc fix & improvements 62/21562/37
Samuel GOUGEON [Thu, 30 Jul 2020 21:51:08 +0000 (23:51 +0200)]
  * insertion, extraction: Main <variablelist> replaced with <refsect3>
                           No content changed (the diff is far bad)
  * gsort: rank of "" when sorting text
  * polyline_properties: image of line styles fixed
  * cumsum: + warning: sparse density => 100%: http://bugzilla.scilab.org/8100
            + completing http://bugzilla.scilab.org/14297 for cumsum
            + <latex alt=".."> added and other improvements
  * mtlb_sparse: no longer exists: http://bugzilla.scilab.org/14477
  * symbols: ** deprecated equivalent of ^:http://bugzilla.scilab.org/16568
  * xsave: remark @ http://mailinglists.scilab.org/Scilab-users-xsave-or-save-tt4041024.html
  * replot(): note added: gca() stays the same.
  * example_run: description of moduleNames improved (for external modules)
                 This documents the change https://codereview.scilab.org/8698
  * percent: wrong overload name fixed in example. See also improved.
             SCI/modules/overloading/macros/README no longer exists.
  * bode: example #3 plot: avoid extra tight x limit

Change-Id: Ia8a083ba7f80f7e91bf4f2e75ef92c0a74121486

68 files changed:
scilab/CHANGES.md
scilab/modules/cacsd/help/en_US/linear_analysis/freq_domain/bode.xml
scilab/modules/cacsd/help/ja_JP/linear_analysis/freq_domain/bode.xml
scilab/modules/core/help/en_US/1_keywords/percent.xml
scilab/modules/core/help/en_US/1_keywords/symbols.xml
scilab/modules/core/help/fr_FR/1_keywords/percent.xml
scilab/modules/core/help/fr_FR/1_keywords/symbols.xml
scilab/modules/core/help/fr_FR/configuration/getos.xml
scilab/modules/core/help/ja_JP/1_keywords/percent.xml
scilab/modules/core/help/ja_JP/1_keywords/symbols.xml
scilab/modules/core/help/pt_BR/1_keywords/percent.xml
scilab/modules/core/help/pt_BR/1_keywords/symbols.xml
scilab/modules/core/help/ru_RU/1_keywords/percent.xml
scilab/modules/core/help/ru_RU/1_keywords/symbols.xml
scilab/modules/development_tools/help/en_US/example_run.xml
scilab/modules/development_tools/help/ja_JP/example_run.xml
scilab/modules/elementary_functions/help/en_US/extraction.xml
scilab/modules/elementary_functions/help/en_US/insertion.xml
scilab/modules/elementary_functions/help/en_US/matrixoperations/cumsum.xml
scilab/modules/elementary_functions/help/en_US/searchandsort/gsort.xml
scilab/modules/elementary_functions/help/fr_FR/extraction.xml
scilab/modules/elementary_functions/help/fr_FR/insertion.xml
scilab/modules/elementary_functions/help/fr_FR/matrixoperations/cumsum.xml
scilab/modules/elementary_functions/help/ja_JP/extraction.xml
scilab/modules/elementary_functions/help/ja_JP/insertion.xml
scilab/modules/elementary_functions/help/ja_JP/matrixoperations/cumsum.xml
scilab/modules/elementary_functions/help/pt_BR/extraction.xml
scilab/modules/elementary_functions/help/pt_BR/insertion.xml
scilab/modules/elementary_functions/help/pt_BR/matrixoperations/cumsum.xml
scilab/modules/elementary_functions/help/ru_RU/extraction.xml
scilab/modules/elementary_functions/help/ru_RU/insertion.xml
scilab/modules/elementary_functions/help/ru_RU/matrixoperations/cumsum.xml
scilab/modules/elementary_functions/help/ru_RU/searchandsort/gsort.xml
scilab/modules/graphics/help/en_US/2d_plot/plot2d.xml
scilab/modules/graphics/help/en_US/axes_operations/replot.xml
scilab/modules/graphics/help/en_US/load_save/xsave.xml
scilab/modules/graphics/help/en_US/polygon/polyline_properties.xml
scilab/modules/graphics/help/en_US/property/set.xml
scilab/modules/graphics/help/fr_FR/axes_operations/replot.xml
scilab/modules/graphics/help/ja_JP/2d_plot/plot2d.xml
scilab/modules/graphics/help/ja_JP/axes_operations/replot.xml
scilab/modules/graphics/help/ja_JP/load_save/xsave.xml
scilab/modules/graphics/help/ja_JP/polygon/polyline_properties.xml
scilab/modules/graphics/help/pt_BR/axes_operations/replot.xml
scilab/modules/graphics/help/pt_BR/load_save/xsave.xml
scilab/modules/helptools/etc/images_md5.txt
scilab/modules/helptools/images/_LaTeX_cumsum.xml_1.png
scilab/modules/helptools/images/_LaTeX_cumsum.xml_2.png
scilab/modules/helptools/images/_LaTeX_cumsum.xml_3.png
scilab/modules/helptools/images/_LaTeX_cumsum.xml_4.png
scilab/modules/helptools/images/_LaTeX_cumsum.xml_5.png
scilab/modules/helptools/images/_LaTeX_cumsum.xml_6.png
scilab/modules/helptools/images/bode_en_US_3.png
scilab/modules/helptools/images/bode_fr_FR_3.png
scilab/modules/helptools/images/bode_ja_JP_3.png
scilab/modules/helptools/images/bode_pt_BR_3.png
scilab/modules/helptools/images/bode_ru_RU_3.png
scilab/modules/helptools/images/polyline_properties_1.png
scilab/modules/linear_algebra/help/en_US/eigen/bdiag.xml
scilab/modules/linear_algebra/help/fr_FR/eigen/bdiag.xml
scilab/modules/linear_algebra/help/ja_JP/eigen/bdiag.xml
scilab/modules/linear_algebra/help/pt_BR/eigen/bdiag.xml
scilab/modules/linear_algebra/help/ru_RU/eigen/bdiag.xml [new file with mode: 0644]
scilab/modules/localization/help/en_US/gettext.xml
scilab/modules/localization/help/ru_RU/gettext.xml [new file with mode: 0644]
scilab/modules/sparse/help/en_US/sparseconvert/mtlb_sparse.xml [deleted file]
scilab/modules/sparse/help/ja_JP/sparseconvert/mtlb_sparse.xml [deleted file]
scilab/modules/sparse/help/pt_BR/sparseconvert/mtlb_sparse.xml [deleted file]

index dddbddd..4cf0f0c 100644 (file)
@@ -316,6 +316,7 @@ Bug Fixes
 * [#3188](https://bugzilla.scilab.org/3188): `part()` was slower than in Scilab 4.1.2.
 * [#7117](https://bugzilla.scilab.org/7117): `findobj()` could not search within given object.
 * [#8059](https://bugzilla.scilab.org/8059): A local `.wgetrc` config file could make troubles in `atomsDownload`.
+* [#8100](https://bugzilla.scilab.org/8100): `cumsum()` on sparse documented.
 * [#8378](https://bugzilla.scilab.org/8378): Datatip `ContextMenu => Delete last datatip` was useless.
 * [#9221](https://bugzilla.scilab.org/9221): There was no way in Scilab to easily access to sets of unicode symbols like greek letters, etc.
 * [#9909](https://bugzilla.scilab.org/9909): In the help browser, add a way to open the online version of the current page.
@@ -339,7 +340,9 @@ Bug Fixes
 * [#13985](https://bugzilla.scilab.org/13985): The display of lists was very loose and poor.
 * [#14033](https://bugzilla.scilab.org/14033): `x_matrix` could not edit matrices of booleans, encoded integers or text. Matrices of real or complex numbers were poorly displayed.
 * [#14098](https://bugzilla.scilab.org/14098): The `genlib` and `library` help pages were outdated with respect to Scilab 6.
+* [#14297](https://bugzilla.scilab.org/14297): Documentation of `cumsum()` improved.
 * [#14435](https://bugzilla.scilab.org/14435): Errors were not well handled in overloaded functions.
+* [#14477](https://bugzilla.scilab.org/14477): `mtlb_sparse()` removed from the documentation.
 * [#14488](https://bugzilla.scilab.org/14488): The `frameflag=9` and `strf=".9."` values of these `plot2d` options were no longer accepted. Their documentation was ambiguous.
 * [#14718](https://bugzilla.scilab.org/14718): `user` is removed for a while but was still documented.
 * [#14873](https://bugzilla.scilab.org/14873): `setfield` page: The output and the 6.0 history were documented only on the en_US version. The input was wrongly restricted to matrices, while any Scilab object is acceptable. The specific role of `setfield` for mlists was not really described nor illustrated. The example did not include any call to setfield.
@@ -411,6 +414,7 @@ Bug Fixes
 * [#16559](https://bugzilla.scilab.org/16553): `isempty(A)` was true for sparse matrix of dimension 2^16 or larger.
 * [#16565](https://bugzilla.scilab.org/16565): `edit(user_defined_function)` corrupted the original code.
 * [#16567](https://bugzilla.scilab.org/16567): `mfile2sci` did not support Matlab block-comments %{ ..%}.
+* [#16568](https://bugzilla.scilab.org/16568): The operator `**` was undocumented.
 * [#16571](https://bugzilla.scilab.org/16571): `mfile2sci` had several issues when converting the NOT ~ operator: 1) `~(1-1)` was converted into `~1-1` instead of `~(1-1)`  2) ~ applied to an integer expression yielded an error from `convert2double`  3) `~i` was converted into `~%i` instead of `~abs(%i)`.
 * [#16573](https://bugzilla.scilab.org/16573): `mfile2sci`: Some `axis` conversions were wrong or not reliable.
 * [#16586](https://bugzilla.scilab.org/16586): `mfile2sci`: The `prettyprintoutput` flag badly managed appended comments.
index 3abc465..5ce194b 100644 (file)
@@ -188,7 +188,7 @@ clf(); bode([h1; h2], 0.01, 100, ['h1'; 'h2']);
 s = %s;
 G = (10*(s+3))/(s*(s+2)*(s^2+s+2)); // A rational matrix
 sys = syslin('c', G); // A continuous-time linear system in transfer matrix representation.
-f_min = .0001; f_max = 16; // Frequencies in Hz
+f_min = .0001; f_max = 15; // Frequencies in Hz
 
 clf(); bode(sys, f_min, f_max, "rad"); // Converts Hz to rad/s
  ]]></programlisting>
@@ -197,7 +197,7 @@ clf(); bode(sys, f_min, f_max, "rad"); // Converts Hz to rad/s
                 s = %s;
                 G = (10*(s+3))/(s*(s+2)*(s^2+s+2)); // A rational matrix
                 sys = syslin('c', G); // A continuous-time linear system in transfer matrix representation.
-                f_min = .0001; f_max = 16; // Frequencies in Hz
+                f_min = .0001; f_max = 15; // Frequencies in Hz
                 clf(); bode(sys, f_min, f_max, "rad"); // Converts Hz to rad/s
             </scilab:image>
         </para>
index 14e6dc9..a0d4d79 100644 (file)
@@ -191,7 +191,7 @@ bode([h1; h2], 0.01, 100, ['h1'; 'h2']);
 s = %s;
 G = (10*(s+3)) / (s*(s+2)*(s^2+s+2)); // A rational matrix
 sys = syslin('c', G); // A continuous-time linear system in transfer matrix representation.
-f_min = .0001; f_max = 16; // Frequencies in Hz
+f_min = .0001; f_max = 15; // Frequencies in Hz
 
 clf
 bode(sys, f_min, f_max, "rad"); // Converts Hz to rad/s
@@ -201,7 +201,7 @@ bode(sys, f_min, f_max, "rad"); // Converts Hz to rad/s
                 s = %s;
                 G = (10*(s+3))/(s*(s+2)*(s^2+s+2)); // A rational matrix
                 sys = syslin('c', G); // A continuous-time linear system in transfer matrix representation.
-                f_min = .0001; f_max = 16; // Frequencies in Hz
+                f_min = .0001; f_max = 15; // Frequencies in Hz
                 clf(); bode(sys, f_min, f_max, "rad"); // Converts Hz to rad/s
             </scilab:image>
         </para>
index 86de71a..a7ee4ba 100644 (file)
@@ -1,5 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<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="percent">
+<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="percent">
     <refnamediv>
         <refname>percent</refname>
         <refpurpose>(%) special character</refpurpose>
         <title>Description</title>
         <para>
             Some predefined variables names begin with <literal>%</literal>, such as
-            <literal>%i</literal> (for <literal>sqrt(-1)</literal>), <literal>%inf</literal> (for <literal>Infinity</literal>), <literal>%pi</literal> (for <literal>3.14...</literal>),
+            <literal>%i</literal> (for <literal>sqrt(-1)</literal>), <literal>%inf</literal>
+            (for <literal>Infinity</literal>), <literal>%pi</literal> (for <literal>3.14...</literal>),
             <literal>%T</literal> (for the boolean constant <literal>"true"</literal>),...
         </para>
         <para>
             In addition, functions whose names begin with <literal>%</literal> are special :
-            they are used for primitives and operators overloading (see <literal>overloading</literal>).
+            they are used for primitives and operators overloading.
         </para>
         <para>
-            For example the function <literal>%rmr</literal> performs the multiplication (<literal>m</literal>)
-            operation <literal>x*y</literal> for <literal>x</literal> and <literal>y</literal> rational matrices (<literal>r</literal>).
-            The coding conventions are given in the <link linkend="overloading">overloading</link> help page.
+            For example the function <literal>%r_m_r</literal> performs the multiplication
+            (<literal>m</literal>) operation <literal>x*y</literal> for <literal>x</literal> and
+            <literal>y</literal> rational matrices (<literal>r</literal>).
+            The coding conventions are described in the <link linkend="overloading">overloading</link>
+            help page.
         </para>
     </refsection>
     <refsection>
         <title>Examples</title>
         <programlisting role="example"><![CDATA[
-x1=tlist('x',1,2);
-x2=tlist('x',2,3);
-deff('x=%xmx(x1,x2)','x=list(''x'',x1(2)*x2(2),x2(3)*x2(3))');
-x1*x2
+x1 = tlist('x',1,2);
+x2 = tlist('x',2,3);
+deff('x = %x_m_x(x1,x2)','x = list(''x'', x1(2)*x2(2), x2(3)*x2(3))');
+x1 * x2
  ]]></programlisting>
     </refsection>
     <refsection role="see also">
@@ -36,6 +42,15 @@ x1*x2
             <member>
                 <link linkend="overloading">overloading</link>
             </member>
+            <member>
+                <link linkend="names">names</link>
+            </member>
+            <member>
+                <link linkend="symbols">symbols</link>
+            </member>
+            <member>
+                <link linkend="printf_conversion">printf_conversion</link>
+            </member>
         </simplelist>
     </refsection>
 </refentry>
index f0f4efe..2f74f34 100644 (file)
             </tr>
         </informaltable>
         <warning>
-          <para>For historical reasons, different symbols may represent the same operator:</para>
-          <para>
-              <literal>@</literal> as the same meaning as <literal>~</literal>
+          <para>For historical reasons, different symbols may represent the same operator:
           </para>
-          <para>
-              <literal>`</literal> as the same meaning as &lt;
-          </para>
-          <para> It is highly recommended not to use these features because they will be removed in
+          <para><literal>@</literal> is equivalent to <literal>~</literal></para>
+          <para><literal>`</literal> is equivalent to <literal>&lt;</literal></para>
+          <para><literal>**</literal> is equivalent to <literal>^</literal>.</para>
+          <para> It is highly recommended not to use these features, because they will be removed in
             the future.
           </para>
         </warning>
index 1d553f4..36b23c5 100644 (file)
@@ -1,5 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<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="fr" xml:id="percent">
+<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="fr" xml:id="percent">
     <refnamediv>
         <refname>percent (%)</refname>
         <refpurpose>caractère spécial  </refpurpose>
     <refsection>
         <title>Description</title>
         <para>
-            Certains noms de variables prédéfinies commencent par le caractère <literal>%</literal>, tels que <literal>%i</literal> (pour <literal>sqrt(-1)</literal>), <literal>%inf</literal> (pour <literal>Infinity</literal>), <literal>%pi</literal> (pour <literal>3.14...</literal>),
+            Certains noms de variables prédéfinies commencent par le caractère <literal>%</literal>,
+            tels que <literal>%i</literal> (pour <literal>sqrt(-1)</literal>),
+            <literal>%inf</literal> (pour <literal>Infinity</literal>), <literal>%pi</literal>
+            (pour <literal>3.14...</literal>),
             <literal>%T</literal> (pour la constante booléenne <literal>"true"="vrai"</literal>),...
         </para>
         <para>
             De plus, les fonctions dont les noms commencent par <literal>%</literal> sont spéciales :
-            elles sont utilisées pour surcharger les primitives et opérateurs usuels (voir <literal>overloading</literal>).
+            elles sont utilisées pour surcharger les primitives et opérateurs usuels.
         </para>
         <para>
-            Par exemple la fonction <literal>%rmr</literal> calcule la multiplication (opérateur <literal>m</literal>)
-            <literal>x*y</literal> pour des matrices rationnelles <literal>x</literal> et <literal>y</literal> (type <literal>r</literal>).
-            Les conventions de codage sont précisées dans le fichier README du répertoire
-            <literal>SCI/modules/overloading/macros</literal>.
+            Par exemple la fonction <literal>%r_m_r</literal> calcule la multiplication
+            (opérateur <literal>m</literal>)  <literal>x*y</literal> pour des matrices rationnelles
+            <literal>x</literal> et <literal>y</literal> (type <literal>r</literal>).
+            Les conventions de codage sont précisées dans la page <link linkend="overloading">overloading</link>.
         </para>
     </refsection>
     <refsection>
         <title>Exemples</title>
         <programlisting role="example"><![CDATA[
-x1=tlist('x',1,2);
-x2=tlist('x',2,3);
-deff('x=%xmx(x1,x2)','x=list(''x'',x1(2)*x2(2),x2(3)*x2(3))');
-x1*x2
+x1 = tlist('x',1,2);
+x2 = tlist('x',2,3);
+deff('x = %x_m_x(x1,x2)','x = list(''x'', x1(2)*x2(2), x2(3)*x2(3))');
+x1 * x2
  ]]></programlisting>
     </refsection>
     <refsection role="see also">
@@ -36,6 +42,15 @@ x1*x2
             <member>
                 <link linkend="overloading">overloading</link>
             </member>
+            <member>
+                <link linkend="names">names</link>
+            </member>
+            <member>
+                <link linkend="symbols">symbols</link>
+            </member>
+            <member>
+                <link linkend="printf_conversion">printf_conversion</link>
+            </member>
         </simplelist>
     </refsection>
 </refentry>
index 45d93c8..a28b113 100644 (file)
               opérateur:
           </para>
           <para>
-              <literal>@</literal> a la même signification que <literal>~</literal>
+              <literal>@</literal> est équivalent à <literal>~</literal>
           </para>
           <para>
-              <literal>`</literal> a la même signification que  &lt;
+              <literal>`</literal> est équivalent à  <literal>&lt;</literal>.
+          </para>
+          <para>
+            <literal>**</literal> est équivalent à  <literal>^</literal>.
           </para>
           <para>
               Il est fortement déconseillé d'utiliser ces opérateurs alternatifs, car il seront
index 08bf228..2b90eaa 100644 (file)
@@ -1,21 +1,24 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<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="fr" xml:id="getos">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:db="http://docbook.org/ns/docbook"
+          xmlns:scilab="http://www.scilab.org" xml:lang="fr" xml:id="getos">
     <refnamediv>
         <refname>getos</refname>
-        <refpurpose>retourne le nom et la version de
-            O.S
+        <refpurpose>
+            donne le nom et la version du système d'exploitation
         </refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Séquence d'appel</title>
-        <synopsis>OS=getos()
-            [OS,Version]=getos()
+        <synopsis>
+            [OS, Version] = getos()
         </synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Description</title>
         <para>
-            <literal>getos </literal>retourne le nom et la version de O.S
+            <literal>getos</literal> donne le nom voire la version du système d'exploitation
+            depuis lequel la session Scilab courante est lancée.
         </para>
     </refsection>
     <refsection>
@@ -27,7 +30,6 @@ if (getos() == "Windows") then disp("Scilab on Windows"); end
 if (getos() == "Linux") then disp("Scilab on Linux"); end
 if (getos() == "SunOS") then disp("Scilab on Solaris"); end
 if (getos() == "Darwin") then disp("Scilab on MacOs"); end
-
- ]]></programlisting>
+     ]]></programlisting>
     </refsection>
 </refentry>
index ba56d0a..cade93f 100644 (file)
@@ -1,5 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<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="ja" xml:id="percent">
+<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="ja" xml:id="percent">
     <refnamediv>
         <refname>percent</refname>
         <refpurpose>(%) 特殊文字</refpurpose>
         <para>
             加えて, <literal>%</literal>で始まる名前を有する関数は特殊な関数です :
             これらはプリミティブおよび演算子オーバーローディングで
-            使用されます(<literal>overloading</literal>参照).
+            使用されます.
         </para>
         <para>
-            例えば,関数 <literal>%rmr</literal> は乗算(<literal>m</literal>)
+            例えば,関数 <literal>%r_m_r</literal> は乗算(<literal>m</literal>)
             処理<literal>x*y</literal>を有理行列(<literal>r</literal>)
             <literal>x</literal> および <literal>y</literal> に関して実行します.
-            コード記法は,
-            <link linkend="overloading">オーバーローディング</link>の
+            コード記法は, <link linkend="overloading">オーバーローディング</link>の
             ヘルプページに記載されています.
         </para>
     </refsection>
     <refsection>
         <title>例</title>
         <programlisting role="example"><![CDATA[
-x1=tlist('x',1,2);
-x2=tlist('x',2,3);
-deff('x=%xmx(x1,x2)','x=list(''x'',x1(2)*x2(2),x2(3)*x2(3))');
-x1*x2
+x1 = tlist('x',1,2);
+x2 = tlist('x',2,3);
+deff('x = %x_m_x(x1,x2)','x = list(''x'', x1(2)*x2(2), x2(3)*x2(3))');
+x1 * x2
  ]]></programlisting>
     </refsection>
     <refsection role="see also">
@@ -42,6 +44,15 @@ x1*x2
             <member>
                 <link linkend="overloading">overloading</link>
             </member>
+            <member>
+                <link linkend="names">names</link>
+            </member>
+            <member>
+                <link linkend="symbols">symbols</link>
+            </member>
+            <member>
+                <link linkend="printf_conversion">printf_conversion</link>
+            </member>
         </simplelist>
     </refsection>
 </refentry>
index 5588ea1..16aaf55 100644 (file)
             <para>
                 <literal>`</literal> は &lt; と同じ意味です
             </para>
+            <para><literal>**</literal> is equivalent to <literal>^</literal>.</para>
             <para> これらは将来削除される予定ですので,これらの機能を使用しないことを
                 強く推奨します.
             </para>
index d1f7478..94c4c4b 100644 (file)
@@ -1,5 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="percent" xml:lang="pt">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
+          xmlns:scilab="http://www.scilab.org" xml:id="percent" xml:lang="pt">
     <refnamediv>
         <refname>percent</refname>
         <refpurpose>caractere especial (%)</refpurpose>
             booleana<literal>"true"</literal>),...
         </para>
         <para>Ainda, funções cujo nome começa com % são especiais : elas são
-            usadas para primitivas e overloading ("sobrecarga") de operadores (ver
-            <literal>overloading</literal>).
+            usadas para primitivas e overloading ("sobrecarga") de operadores.
         </para>
         <para>
-            Por exemplo, a função <literal>%rmr</literal> realiza a operação de
+            Por exemplo, a função <literal>%r_m_r</literal> realiza a operação de
             multiplicação (<literal>m</literal>) <literal>x*y</literal> para
             <literal>x</literal> e <literal>y</literal> matrizes de razões de
-            polinômios (<literal>r</literal>). As convenções de codificação são
-            fornecidas pelo arquivo "leia-me" no diretório
-            <literal>SCI/modules/overloading/macros</literal>.
+            polinômios (<literal>r</literal>).
+            As convenções de codificação são descritas na página de ajuda <link linkend="overloading">
+            overloading</link>.
         </para>
     </refsection>
     <refsection>
         <title>Exemplos</title>
         <programlisting role="example"><![CDATA[
-x1=tlist('x',1,2);
-x2=tlist('x',2,3);
-deff('x=%xmx(x1,x2)','x=list(''x'',x1(2)*x2(2),x2(3)*x2(3))');
-x1*x2
+x1 = tlist('x',1,2);
+x2 = tlist('x',2,3);
+deff('x = %x_m_x(x1,x2)','x = list(''x'', x1(2)*x2(2), x2(3)*x2(3))');
+x1 * x2
  ]]></programlisting>
     </refsection>
     <refsection>
@@ -41,6 +43,15 @@ x1*x2
             <member>
                 <link linkend="overloading">overloading</link>
             </member>
+            <member>
+                <link linkend="names">names</link>
+            </member>
+            <member>
+                <link linkend="symbols">symbols</link>
+            </member>
+            <member>
+                <link linkend="printf_conversion">printf_conversion</link>
+            </member>
         </simplelist>
     </refsection>
 </refentry>
index 275be73..c7f58a5 100644 (file)
                 <literal>~</literal>
             </para>
             <para>
-                <literal>`</literal> tem o mesmo significado que &lt;
+                <literal>`</literal> tem o mesmo significado que <literal>&lt;</literal>.
             </para>
+            <para>
+                <literal>`</literal> tem o mesmo significado que <literal>&lt;</literal>.
+            </para>
+            <para><literal>**</literal> é equivalente a <literal>^</literal>.</para>
             <para>É altamente recomendável que não se use esses recursos, pois eles
                 serão removidos futuramente
             </para>
index e45490b..f3fddb7 100644 (file)
@@ -1,5 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<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="ru" xml:id="percent">
+<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="ru" xml:id="percent">
     <refnamediv>
         <refname>процент</refname>
         <refpurpose>(%) специальный символ</refpurpose>
         </para>
         <para>
             Кроме того, функции, чьи имена начинаются с <literal>%</literal>, являются специальными:
-            они используются для перегрузки примитивов и операторов (см. <link linkend="overloading">перегрузку</link>).
+            они используются для перегрузки примитивов и операторов.
         </para>
         <para>
-            Например, функция <literal>%rmr</literal> выполняет операцию умножения (<literal>m</literal>)
+            Например, функция <literal>%r_m_r</literal> выполняет операцию умножения (<literal>m</literal>)
             <literal>x*y</literal> для рациональных (<literal>r</literal>) матриц
             <literal>x</literal> и <literal>y</literal>.
-            Соглашения по написанию кода даны в файле readme в директории <literal>SCI/modules/overloading/macros</literal>.
+            Соглашения о кодировании описаны на странице справки <link linkend="overloading">overloading</link>.
         </para>
     </refsection>
     <refsection>
         <title>Примеры</title>
         <programlisting role="example"><![CDATA[
-x1=tlist('x',1,2);
-x2=tlist('x',2,3);
-deff('x=%xmx(x1,x2)','x=list(''x'',x1(2)*x2(2),x2(3)*x2(3))');
-x1*x2
+x1 = tlist('x',1,2);
+x2 = tlist('x',2,3);
+deff('x = %x_m_x(x1,x2)','x = list(''x'', x1(2)*x2(2), x2(3)*x2(3))');
+x1 * x2
  ]]></programlisting>
     </refsection>
     <refsection role="see also">
@@ -39,6 +42,15 @@ x1*x2
             <member>
                 <link linkend="overloading">перегрузка</link>
             </member>
+            <member>
+                <link linkend="names">names</link>
+            </member>
+            <member>
+                <link linkend="symbols">symbols</link>
+            </member>
+            <member>
+                <link linkend="printf_conversion">printf_conversion</link>
+            </member>
         </simplelist>
     </refsection>
 </refentry>
index 86df949..383b5cc 100644 (file)
             <para>
                 <literal>`</literal> то же самое, что и &lt;
             </para>
+            <para><literal>**</literal> то же самое, что и <literal>^</literal>.</para>
             <para>
                 Настоятельно рекомендуется не использовать эти символы, поскольку они будут в будущем удалены.
             </para>
index fd04e5a..7c67bdf 100644 (file)
  * along with this program.
  *
  -->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="example_run" xml:lang="en">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
+          xmlns:scilab="http://www.scilab.org" xml:id="example_run" xml:lang="en">
     <refnamediv>
         <refname>example_run</refname>
         <refpurpose>Launch the examples found in help pages.</refpurpose>
                 <term>moduleNames</term>
                 <listitem>
                     <para>
-                        a string or a string vector: the name(s) of the modules to test. Default value is the value returned by <link linkend="getmodules">getmodules()</link>.
+                        a string or a vector of strings: references of the modules to test.
+                        Each reference can be either of
+                        <itemizedlist>
+                            <listitem>
+                                the technical name of a Scilab internal module, that is the name
+                                of the root directory of the module.
+                            </listitem>
+                            <listitem>
+                                the relative or absolute path of the root directory of the module.
+                                This must be used for installed ATOMS modules or other external modules.
+                            </listitem>
+                        </itemizedlist>
+                        By default, all Scilab internal modules are considered, as returned by
+                        <link linkend="getmodules">getmodules()</link>.
+                    </para>
+                    <para>
+                        The root directory of each targeted module must have a
+                        <literal>./help</literal> subdirectory containing the XML source files of
+                        help pages where examples to test are provided, gathered by languages as
+                        in the source package of any standard module.
+                        Example of the template toolbox_skeleton module:
+                        <programlisting role="example">
+unix_w("dir /b /s """ + WSCI + "/contrib/toolbox_skeleton/help""")
+                      </programlisting>
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>functionNames</term>
                 <listitem>
-                    <para>a string or a string vector: the name(s) of the functions to test. If not given, all help pages of the module(s) will be tested.</para>
+                    <para>
+                        a string or a string vector: the name(s) of the functions to test.
+                        If not given, all help pages of the module(s) will be tested.
+                    </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
     <refsection>
         <title>Description</title>
         <para>
-            This function extracts the examples given in help pages and run them using <link linkend="test_run">test_run</link>.
+            This function extracts the examples given in help pages and run them using
+            <link linkend="test_run">test_run</link>.
+        </para>
+        <para>
+           <warning>
+               When testing examples of any external module, it is mandatory to autoload the module
+               at Scilab startup. This can be achieved either by setting the ATOMS module as
+               autoloaded, or by loading the module through the user's startup file.
+           </warning>
         </para>
     </refsection>
     <refsection>
@@ -92,6 +129,15 @@ end
             <member>
                 <link linkend="test_run">test_run</link>
             </member>
+            <member>
+                <link linkend="bench_run">bench_run</link>
+            </member>
+            <member>
+                <link linkend="atomsAutoloadAdd">atomsAutoloadAdd</link>
+            </member>
+            <member>
+                <link linkend="startup">startup</link>
+            </member>
         </simplelist>
     </refsection>
     <refsection>
index fd5ce31..fc4bb1e 100644 (file)
  * along with this program.
  *
  -->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="example_run" xml:lang="ja">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
+          xmlns:scilab="http://www.scilab.org" xml:id="example_run" xml:lang="ja">
     <refnamediv>
         <refname>example_run</refname>
         <refpurpose>ヘルプページで見つかった例を実行.</refpurpose>
                 <term>moduleNames</term>
                 <listitem>
                     <para>
-                        文字列または文字列ベクトル: テストを行うモジュールの名前.
-                        デフォルト値は
-                        <link linkend="getmodules">getmodules()</link>で返された値です.
+                        a string or a vector of strings: references of the modules to test.
+                        Each reference can be either of
+                        <itemizedlist>
+                            <listitem>
+                                the technical name of a Scilab internal module, that is the name
+                                of the root directory of the module.
+                            </listitem>
+                            <listitem>
+                                the relative or absolute path of the root directory of the module.
+                                This must be used for installed ATOMS modules or other external modules.
+                            </listitem>
+                        </itemizedlist>
+                        By default, all Scilab internal modules are considered, as returned by
+                        <link linkend="getmodules">getmodules()</link>.
+                    </para>
+                    <para>
+                        The root directory of each targeted module must have a
+                        <literal>./help</literal> subdirectory containing the XML source files of
+                        help pages where examples to test are provided, gathered by languages as
+                        in the source package of any standard module.
+                        Example of the template toolbox_skeleton module:
+                        <programlisting role="example">
+unix_w("dir /b /s """ + WSCI + "/contrib/toolbox_skeleton/help""")
+                      </programlisting>
                     </para>
                 </listitem>
             </varlistentry>
             この巻数は,ヘルプページで指定した例を展開し,
             <link linkend="test_run">test_run</link>により実行します.
         </para>
+        <para>
+           <warning>
+               When testing examples of any external module, it is mandatory to autoload the module
+               at Scilab startup. This can be achieved either by setting the ATOMS module as
+               autoloaded, or by loading the module through the user's startup file.
+           </warning>
+        </para>
     </refsection>
     <refsection>
         <title>例</title>
@@ -98,6 +129,15 @@ end
             <member>
                 <link linkend="test_run">test_run</link>
             </member>
+            <member>
+                <link linkend="bench_run">bench_run</link>
+            </member>
+            <member>
+                <link linkend="atomsAutoloadAdd">atomsAutoloadAdd</link>
+            </member>
+            <member>
+                <link linkend="startup">startup</link>
+            </member>
         </simplelist>
     </refsection>
     <refsection>
index f7d4515..51a5896 100644 (file)
@@ -1,5 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="extraction" xml:lang="en">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
+          xmlns:scilab="http://www.scilab.org" xml:id="extraction" xml:lang="en">
     <refnamediv>
         <refname>extraction</refname>
         <refpurpose>matrix and list entry extraction</refpurpose>
@@ -10,8 +13,8 @@
             x(i)
             x(i,j)
             x(i,j,k,..)
-            [...]=l(i)
-            [...]=l(k1)...(kn)(i) or [...]=l(list(k1,...,kn,i))
+            [...] = l(i)
+            [...] = l(k1)...(kn)(i) or [...] = l(list(k1,...,kn,i))
             l(k1)...(kn)(i,j) or l(list(k1,...,kn,list(i,j))
         </synopsis>
     </refsynopsisdiv>
     </refsection>
     <refsection>
         <title>Description</title>
-        <variablelist>
-            <varlistentry>
-                <term>MATRIX CASE</term>
+        <refsect3>
+            <title>Matrix case</title>
+            <para>
+              <literal>i</literal>, <literal>j</literal>,
+              <literal>k</literal>,.. can be:
+            </para>
+            <variablelist>
+              <varlistentry>
+                <term>a real scalar or a vector or a matrix with positive
+                  elements.
+                </term>
                 <listitem>
-                    <para>
-                        <literal>i</literal>, <literal>j</literal>,
-                        <literal>k</literal>,.. can be:
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>a real scalar or a vector or a matrix with positive
-                                elements.
-                            </term>
-                            <listitem>
-                                <itemizedlist>
-                                    <listitem>
-                                        <para>
-                                            <literal>r=x(i,j)</literal> builds the matrix
-                                            <literal>r</literal> such as
-                                            <literal>r(l,k)=x(int(i(l)),int(j(k)))</literal> for
-                                            <literal>l</literal> from 1 to
-                                            <literal>size(i,'*')</literal> and <literal>k</literal>
-                                            from 1 to <literal>size(j,'*')</literal>.
-                                        </para>
-                                        <para>
-                                            <literal>i</literal> (<literal>j</literal>) Maximum
-                                            value must be less or equal to
-                                            <literal>size(x,1)</literal>
-                                            (<literal>size(x,2)</literal>).
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            <literal>r=x(i)</literal> with <literal>x</literal>
-                                            a 1x1 matrix builds the matrix <literal>r</literal> such
-                                            as <literal>r(l,k)=x(int(i(l)),int(i(k)))</literal> for
-                                            <literal>l</literal> from 1 to
-                                            <literal>size(i,1)</literal> and <literal>k</literal> from
-                                            1 to <literal>size(i,2)</literal>.
-                                        </para>
-                                        <para>
-                                            Note that in this case index <literal>i</literal> is
-                                            valid only if all its entries are equal to one.
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            <literal>r=x(i)</literal> with <literal>x</literal>
-                                            a row vector builds the row vector <literal>r</literal>
-                                            such as <literal>r(l)=x(int(i(l)))</literal> for
-                                            <literal>l</literal> from 1 to
-                                            <literal>size(i,'*')</literal><literal>i</literal> Maximum
-                                            value must be less or equal to
-                                            <literal>size(x,'*')</literal>.
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            <literal>r=x(i)</literal> with <literal>x</literal>
-                                            a matrix with one or more columns builds the column vector
-                                            <literal>r</literal> such as <literal>r(l)</literal>
-                                            (<literal>l</literal> from 1 to
-                                            <literal>size(i,'*')</literal>) contains the
-                                            <literal>int(i(l))</literal> entry of the column vector
-                                            formed by the concatenation of the <literal>x</literal>'s
-                                            columns.
-                                        </para>
-                                        <para>
-                                            <literal>i</literal> Maximum value must be less or
-                                            equal to <literal>size(x,'*')</literal>.
-                                        </para>
-                                    </listitem>
-                                </itemizedlist>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>
-                                the symbol <literal>: </literal>
-                            </term>
-                            <listitem>
-                                <para><literal/>
-                                    which stands for "all elements".
-                                </para>
-                                <itemizedlist>
-                                    <listitem>
-                                        <para>
-                                            <literal>r=x(i,:)</literal> builds the matrix
-                                            <literal>r</literal> such as
-                                            <literal>r(l,k)=x(int(i(l)),k))</literal> for
-                                            <literal>l</literal> from 1 to
-                                            <literal>size(i,'*')</literal> and <literal>k</literal>
-                                            from 1 to <literal>size(x,2)</literal>
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            <literal>r=x(:,j)</literal> builds the matrix
-                                            <literal>r</literal> such as
-                                            <literal>r(l,k)=x(l,int(j(k)))</literal> for
-                                            <literal>l</literal> from 1 to
-                                            <literal>size(r,1)</literal> and <literal>k</literal> from
-                                            1 to <literal>size(j,'*')</literal>.
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            <literal>r=x(:)</literal> builds the column vector
-                                            <literal>r</literal> formed by the column concatenations
-                                            of <literal>x</literal> columns. It is equivalent to
-                                            <literal>matrix(x,size(x,'*'),1)</literal>.
-                                        </para>
-                                    </listitem>
-                                </itemizedlist>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>a vector of boolean</term>
-                            <listitem>
-                                <para>
-                                    If an index (<literal>i</literal> or
-                                    <literal>j</literal>) is a vector of booleans it is
-                                    interpreted as <literal>find(i)</literal> or respectively
-                                    <literal>find(j)</literal>
-                                </para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>a polynomial</term>
-                            <listitem>
-                                <para>
-                                    If an index (<literal>i</literal> or
-                                    <literal>j</literal>) is a vector of polynomials or implicit
-                                    polynomial vector it is interpreted as
-                                    <literal>horner(i,m)</literal> or respectively
-                                    <literal>horner(j,n)</literal> where <literal>m</literal> and
-                                    <literal>n</literal> are associated <literal>x</literal>
-                                    dimensions. Even if this feature works for all polynomials, it
-                                    is recommended to use polynomials in <literal>$</literal> for
-                                    readability.
-                                </para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                    <para>
-                        For matrices with more than 2 dimensions (see:<link linkend="hypermatrices">hypermatrices</link>) the dimensionality
-                        is automatically reduced when right-most dimensions are equal to
-                        1.
-                    </para>
+                  <itemizedlist>
+                    <listitem>
+                      <para>
+                        <literal>r=x(i,j)</literal> builds the matrix
+                        <literal>r</literal> such as
+                        <literal>r(l,k)=x(int(i(l)),int(j(k)))</literal> for
+                        <literal>l</literal> from 1 to
+                        <literal>size(i,'*')</literal> and <literal>k</literal>
+                        from 1 to <literal>size(j,'*')</literal>.
+                      </para>
+                      <para>
+                        <literal>i</literal> (<literal>j</literal>) Maximum
+                        value must be less or equal to
+                        <literal>size(x,1)</literal>
+                        (<literal>size(x,2)</literal>).
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>r=x(i)</literal> with <literal>x</literal>
+                        a 1x1 matrix builds the matrix <literal>r</literal> such
+                        as <literal>r(l,k)=x(int(i(l)),int(i(k)))</literal> for
+                        <literal>l</literal> from 1 to
+                        <literal>size(i,1)</literal> and <literal>k</literal> from
+                        1 to <literal>size(i,2)</literal>.
+                      </para>
+                      <para>
+                        Note that in this case index <literal>i</literal> is
+                        valid only if all its entries are equal to one.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>r=x(i)</literal> with <literal>x</literal>
+                        a row vector builds the row vector <literal>r</literal>
+                        such as <literal>r(l)=x(int(i(l)))</literal> for
+                        <literal>l</literal> from 1 to
+                        <literal>size(i,'*')</literal><literal>i</literal> Maximum
+                        value must be less or equal to
+                        <literal>size(x,'*')</literal>.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>r=x(i)</literal> with <literal>x</literal>
+                        a matrix with one or more columns builds the column vector
+                        <literal>r</literal> such as <literal>r(l)</literal>
+                        (<literal>l</literal> from 1 to
+                        <literal>size(i,'*')</literal>) contains the
+                        <literal>int(i(l))</literal> entry of the column vector
+                        formed by the concatenation of the <literal>x</literal>'s
+                        columns.
+                      </para>
+                      <para>
+                        <literal>i</literal> Maximum value must be less or
+                        equal to <literal>size(x,'*')</literal>.
+                      </para>
+                    </listitem>
+                  </itemizedlist>
                 </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>LIST OR TLIST CASE</term>
+              </varlistentry>
+              <varlistentry>
+                <term>
+                  the symbol <literal>: </literal>
+                </term>
                 <listitem>
-                    <para>
-                        If they are present the <literal>ki</literal> give the path to
-                        a sub-list entry of <literal>l</literal> data structure. They allow
-                        a recursive extraction without intermediate copies. The
-                        instructions
-                    </para>
-                    <para>
-                        <literal>[...]=l(k1)...(kn)(i)</literal>
-                    </para>
-                    <para>and</para>
-                    <para>
-                        <literal>[...]=l(list(k1,...,kn,i))</literal>
-                    </para>
-                    <para>are interpreted as:</para>
-                    <para>
-                        <literal>lk1 = l(k1)</literal>
-                    </para>
-                    <para>
-                        <literal>.. = .. </literal>
-                    </para>
-                    <para>
-                        <literal>lkn = lkn-1(kn)</literal>
-                    </para>
-                    <para>
-                        <literal>[...] = lkn(i)</literal>.
-                    </para>
-                    <para>
-                        And the <literal>l(k1)...(kn)(i,j)</literal> and
-                    </para>
-                    <para>
-                        <literal>l(list(k1,...,kn,list(i,j))</literal> instructions
-                        are interpreted as:
-                    </para>
-                    <para>
-                        <literal>lk1 = l(k1)</literal>
-                    </para>
-                    <para>
-                        <literal>.. = .. </literal>
-                    </para>
-                    <para>
-                        <literal>lkn = lkn-1(kn)</literal>
-                    </para>
-                    <para>
-                        <literal>
-                            lkn(i,j)
-                        </literal>
-                    </para>
-                    <para>
-                        When path points to more than one list component, the
-                        instruction must have as many left-hand side arguments as selected
-                        components. But if the extraction syntax is used as function
-                        parameters, each returned list component is added to the
-                        function parameters.
-                    </para>
-                    <para>
-                        Note that <literal>l(list())</literal> is the same as
-                        <literal>l</literal>.
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>i and j may be:</term>
-                            <listitem>
-                                <variablelist>
-                                    <varlistentry>
-                                        <term>real scalar or vector or matrix with positive
-                                            elements.
-                                        </term>
-                                        <listitem>
-                                            <para>
-                                                <literal>[r1,...rn]=l(i)</literal> extracts the
-                                                <literal>i(k)</literal> elements from the list <literal>l</literal> and store
-                                                them in <literal>rk</literal> variables for
-                                                <literal>k</literal> from 1 to
-                                                <literal>size(i,'*')</literal>
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>
-                                            the symbol <literal>: </literal>
-                                        </term>
-                                        <listitem>
-                                            <para>which stands for "all elements".</para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>a vector of booleans.</term>
-                                        <listitem>
-                                            <para>
-                                                If <literal>i</literal> is a vector of booleans it is
-                                                interpreted as <literal>find(i)</literal>.
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>a polynomial</term>
-                                        <listitem>
-                                            <para>
-                                                If <literal>i</literal> is a vector of polynomials or
-                                                implicit polynomial vector it is interpreted as
-                                                <literal>horner(i,m)</literal> where
-                                                <literal>m=size(l)</literal>. Even if this feature works for
-                                                all polynomials, it is recommended to use polynomials in
-                                                <literal>$</literal> for readability.
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                </variablelist>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>k1 ... kn may be :</term>
-                            <listitem>
-                                <variablelist>
-                                    <varlistentry>
-                                        <term>real positive scalar</term>
-                                        <listitem>
-                                            <para/>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>a polynomial</term>
-                                        <listitem>
-                                            <para>
-                                                interpreted as <literal>horner(ki,m)</literal> where
-                                                <literal>m</literal> is the corresponding sub-list
-                                                size.
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>a character string</term>
-                                        <listitem>
-                                            <para>associated with a sub-list entry name.</para>
-                                        </listitem>
-                                    </varlistentry>
-                                </variablelist>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
+                  <para><literal/>
+                    which stands for "all elements".
+                  </para>
+                  <itemizedlist>
+                    <listitem>
+                      <para>
+                        <literal>r=x(i,:)</literal> builds the matrix
+                        <literal>r</literal> such as
+                        <literal>r(l,k)=x(int(i(l)),k))</literal> for
+                        <literal>l</literal> from 1 to
+                        <literal>size(i,'*')</literal> and <literal>k</literal>
+                        from 1 to <literal>size(x,2)</literal>
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>r=x(:,j)</literal> builds the matrix
+                        <literal>r</literal> such as
+                        <literal>r(l,k)=x(l,int(j(k)))</literal> for
+                        <literal>l</literal> from 1 to
+                        <literal>size(r,1)</literal> and <literal>k</literal> from
+                        1 to <literal>size(j,'*')</literal>.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>r=x(:)</literal> builds the column vector
+                        <literal>r</literal> formed by the column concatenations
+                        of <literal>x</literal> columns. It is equivalent to
+                        <literal>matrix(x,size(x,'*'),1)</literal>.
+                      </para>
+                    </listitem>
+                  </itemizedlist>
                 </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>Remarks</title>
-        <para>For soft coded matrix types such as rational functions and state
-            space linear systems, <literal>x(i)</literal> syntax may not be used for
-            vector element extraction due to confusion with list element extraction.
-            <literal>x(1,j)</literal> or <literal>x(i,1)</literal> syntax must be
-            used.
-        </para>
+              </varlistentry>
+              <varlistentry>
+                <term>a vector of boolean</term>
+                <listitem>
+                  <para>
+                    If an index (<literal>i</literal> or
+                    <literal>j</literal>) is a vector of booleans it is
+                    interpreted as <literal>find(i)</literal> or respectively
+                    <literal>find(j)</literal>
+                  </para>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>a polynomial</term>
+                <listitem>
+                  <para>
+                    If an index (<literal>i</literal> or
+                    <literal>j</literal>) is a vector of polynomials or implicit
+                    polynomial vector it is interpreted as
+                    <literal>horner(i,m)</literal> or respectively
+                    <literal>horner(j,n)</literal> where <literal>m</literal> and
+                    <literal>n</literal> are associated <literal>x</literal>
+                    dimensions. Even if this feature works for all polynomials, it
+                    is recommended to use polynomials in <literal>$</literal> for
+                    readability.
+                  </para>
+                </listitem>
+              </varlistentry>
+            </variablelist>
+            <para>
+              For matrices with more than 2 dimensions (see:<link linkend="hypermatrices">hypermatrices</link>) the dimensionality
+              is automatically reduced when right-most dimensions are equal to
+              1.
+            </para>
+        </refsect3>
+        <refsect3>
+            <title>List or Tlist case</title>
+            <para>
+              If they are present the <literal>ki</literal> give the path to
+              a sub-list entry of <literal>l</literal> data structure. They allow
+              a recursive extraction without intermediate copies. The
+              instructions
+            </para>
+            <para>
+              <literal>[...]=l(k1)...(kn)(i)</literal>
+            </para>
+            <para>and</para>
+            <para>
+              <literal>[...]=l(list(k1,...,kn,i))</literal>
+            </para>
+            <para>are interpreted as:</para>
+            <para>
+              <literal>lk1 = l(k1)</literal>
+            </para>
+            <para>
+              <literal>.. = .. </literal>
+            </para>
+            <para>
+              <literal>lkn = lkn-1(kn)</literal>
+            </para>
+            <para>
+              <literal>[...] = lkn(i)</literal>.
+            </para>
+            <para>
+              And the <literal>l(k1)...(kn)(i,j)</literal> and
+            </para>
+            <para>
+              <literal>l(list(k1,...,kn,list(i,j))</literal> instructions
+              are interpreted as:
+            </para>
+            <para>
+              <literal>lk1 = l(k1)</literal>
+            </para>
+            <para>
+              <literal>.. = .. </literal>
+            </para>
+            <para>
+              <literal>lkn = lkn-1(kn)</literal>
+            </para>
+            <para>
+              <literal>
+                lkn(i,j)
+              </literal>
+            </para>
+            <para>
+              When path points to more than one list component, the
+              instruction must have as many left-hand side arguments as selected
+              components. But if the extraction syntax is used as function
+              parameters, each returned list component is added to the
+              function parameters.
+            </para>
+            <para>
+              Note that <literal>l(list())</literal> is the same as
+              <literal>l</literal>.
+            </para>
+            <variablelist>
+              <varlistentry>
+                <term>i and j may be:</term>
+                <listitem>
+                  <variablelist>
+                    <varlistentry>
+                      <term>real scalar or vector or matrix with positive
+                        elements.
+                      </term>
+                      <listitem>
+                        <para>
+                          <literal>[r1,...rn]=l(i)</literal> extracts the
+                          <literal>i(k)</literal> elements from the list <literal>l</literal> and store
+                          them in <literal>rk</literal> variables for
+                          <literal>k</literal> from 1 to
+                          <literal>size(i,'*')</literal>
+                        </para>
+                      </listitem>
+                    </varlistentry>
+                    <varlistentry>
+                      <term>
+                        the symbol <literal>: </literal>
+                      </term>
+                      <listitem>
+                        <para>which stands for "all elements".</para>
+                      </listitem>
+                    </varlistentry>
+                    <varlistentry>
+                      <term>a vector of booleans.</term>
+                      <listitem>
+                        <para>
+                          If <literal>i</literal> is a vector of booleans it is
+                          interpreted as <literal>find(i)</literal>.
+                        </para>
+                      </listitem>
+                    </varlistentry>
+                    <varlistentry>
+                      <term>a polynomial</term>
+                      <listitem>
+                        <para>
+                          If <literal>i</literal> is a vector of polynomials or
+                          implicit polynomial vector it is interpreted as
+                          <literal>horner(i,m)</literal> where
+                          <literal>m=size(l)</literal>. Even if this feature works for
+                          all polynomials, it is recommended to use polynomials in
+                          <literal>$</literal> for readability.
+                        </para>
+                      </listitem>
+                    </varlistentry>
+                  </variablelist>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>k1 ... kn may be :</term>
+                <listitem>
+                  <variablelist>
+                    <varlistentry>
+                      <term>real positive scalar</term>
+                      <listitem>
+                        <para/>
+                      </listitem>
+                    </varlistentry>
+                    <varlistentry>
+                      <term>a polynomial</term>
+                      <listitem>
+                        <para>
+                          interpreted as <literal>horner(ki,m)</literal> where
+                          <literal>m</literal> is the corresponding sub-list
+                          size.
+                        </para>
+                      </listitem>
+                    </varlistentry>
+                    <varlistentry>
+                      <term>a character string</term>
+                      <listitem>
+                        <para>associated with a sub-list entry name.</para>
+                      </listitem>
+                    </varlistentry>
+                  </variablelist>
+                </listitem>
+              </varlistentry>
+            </variablelist>
+        </refsect3>
+        <refsect3>
+            <title>Remarks</title>
+            <para>For soft coded matrix types such as rational functions and state
+                space linear systems, <literal>x(i)</literal> syntax may not be used for
+                vector element extraction due to confusion with list element extraction.
+                <literal>x(1,j)</literal> or <literal>x(i,1)</literal> syntax must be
+                used.
+            </para>
+        </refsect3>
     </refsection>
     <refsection>
         <title>Examples</title>
+        <para>
+            Matrix case:
+        </para>
         <programlisting role="example"><![CDATA[
-// MATRIX CASE
-a=[1 2 3;4 5 6]
+a = [1 2 3 ; 4 5 6]
 a(1,2)
-a([1 1],2)
-a(:,1)
-a(:,3:-1:1)
+a([1 1], 2)
+a(:, 1)
+a(:, 3:-1:1)
 a(1)
 a(6)
 a(:)
 a([%t %f %f %t])
-a([%t %f],[2 3])
-a(1:2,$-1)
-a($:-1:1,2)
+a([%t %f], [2 3])
+a(1:2, $-1)
+a($:-1:1, 2)
 a($)
 //
-x='test'
-x([1 1;1 1;1 1])
+x = 'test'
+x([1 1 ; 1 1 ; 1 1])
 //
-b=[1/%s,(%s+1)/(%s-1)]
+b = [1/%s, (%s+1)/(%s-1)]
 b(1,1)
 b(1,$)
 b(2) // the numerator
-// LIST OR TLIST CASE
-l=list(1,'qwerw',%s)
+     ]]></programlisting>
+        <para>
+            List ot Tlist case:
+        </para>
+        <programlisting role="example"><![CDATA[
+l = list(1,'qwerw',%s)
 l(1)
-[a,b]=l([3 2])
+[a,b] = l([3 2])
 l($)
-x=tlist(l(2:3)) //form a tlist with the last 2 components of l
+x = tlist(l(2:3)) // forms a tlist with the last 2 components of l
 //
-dts=list(1,tlist(['x';'a';'b'],10,[2 3]));
+dts = list(1, tlist(['x';'a';'b'],10,[2 3]));
 dts(2)('a')
 dts(2)('b')(1,2)
-[a,b]=dts(2)(['a','b'])
- ]]></programlisting>
+[a,b] = dts(2)(['a','b'])
+     ]]></programlisting>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
         <simplelist type="inline">
             <member>
+                <link linkend="insertion">insertion</link>
+            </member>
+            <member>
+                <link linkend="colon">colon</link>
+            </member>
+            <member>
                 <link linkend="find">find</link>
             </member>
             <member>
@@ -402,9 +411,6 @@ dts(2)('b')(1,2)
             <member>
                 <link linkend="parentheses">parentheses</link>
             </member>
-            <member>
-                <link linkend="insertion">insertion</link>
-            </member>
         </simplelist>
     </refsection>
 </refentry>
index 8464866..ebc5904 100644 (file)
@@ -1,5 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<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="insertion">
+<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="insertion">
     <refnamediv>
         <refname>insertion</refname>
         <refpurpose>partial variable assignation
     </refsection>
     <refsection>
         <title>Description</title>
-        <variablelist>
-            <varlistentry>
-                <term>MATRIX CASE</term>
+        <refsect3>
+            <title>Matrix case</title>
+            <para>
+              If <literal>x</literal> is a matrix the indices <literal>i</literal> and <literal>j</literal>, may be:
+            </para>
+            <variablelist>
+              <varlistentry>
+                <term>Real scalars or vectors or matrices</term>
                 <listitem>
-                    <para>
-                        If <literal>x</literal> is a matrix the indices <literal>i</literal> and <literal>j</literal>, may be:
-                    </para>
-                    <variablelist>
+                  <para>In this case the values given as indices should be positive and
+                    only their integer part are taken into account.
+                  </para>
+                  <itemizedlist>
+                    <listitem>
+                      <para>
+                        If <literal>a</literal> is a matrix with
+                        dimensions
+                        <literal>(size(i,'*'),size(j,'*'))</literal>,
+                        <literal>x(i,j)=a</literal> returns a new <literal>x</literal> matrix
+                        such as <literal>x(int(i(l)),int(j(k)))=a(l,k) </literal> for
+                        <literal>l</literal> from 1 to
+                        <literal>size(i,'*')</literal> and <literal>k</literal> from
+                        1 to <literal>size(j,'*')</literal>, other initial
+                        entries of <literal>x</literal> are unchanged.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        If <literal>a</literal> is a scalar
+                        <literal>x(i,j)=a</literal> returns a new <literal>x</literal> matrix
+                        such as <literal>x(int(i(l)),int(j(k)))=a</literal> for
+                        <literal>l</literal> from 1 to <literal>size(i,'*')</literal>
+                        and <literal>k</literal> from 1 to
+                        <literal>size(j,'*')</literal>, other initial entries
+                        of <literal>x</literal> are unchanged.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        If <literal>i</literal> or <literal>j</literal>
+                        maximum value exceed corresponding <literal>x</literal> matrix
+                        dimension, array <literal>x</literal> is previously extended to the
+                        required dimensions with zeros entries for standard
+                        matrices, 0 length character string for string matrices and
+                        false values for boolean matrices.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>x(i,j)=[]</literal> kills rows
+                        specified by <literal>i</literal> if <literal>j</literal> matches all
+                        columns of <literal>x</literal> or kills columns specified by
+                        <literal>j</literal> if <literal>i</literal> matches all rows of
+                        <literal>x</literal>. In other cases <literal>x(i,j)=[]</literal>
+                        produce an error.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>x(i)=a</literal> with an <literal>a</literal>
+                        vector returns a new <literal>x</literal> matrix such as
+                        <literal>x(int(i(l)))=a(l)</literal> for <literal>l</literal> from 1 to
+                        <literal>size(i,'*')</literal>, other initial entries
+                        of <literal>x</literal> are unchanged.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>x(i)=a</literal> with an <literal>a</literal>
+                        scalar returns a new <literal>x</literal> matrix such as
+                        <literal>x(int(i(l)))=a</literal> for <literal>l</literal> from 1 to
+                        <literal>size(i,'*')</literal>, other initial entries
+                        of <literal>x</literal> are unchanged.
+                      </para>
+                      <para>
+                        If <literal>i</literal> maximum value exceed
+                        <literal>size(x,1)</literal>, <literal>x</literal> is previously
+                        extended to the required dimension with zeros entries for
+                        standard matrices, 0 length character string for string
+                        matrices and false values for boolean matrices.
+                      </para>
+                      <variablelist>
                         <varlistentry>
-                            <term>Real scalars or vectors or matrices</term>
-                            <listitem>
-                                <para>In this case the values given as indices should be positive and
-                                    only their integer part are taken into account.
-                                </para>
-                                <itemizedlist>
-                                    <listitem>
-                                        <para>
-                                            If <literal>a</literal> is a matrix with
-                                            dimensions
-                                            <literal>(size(i,'*'),size(j,'*'))</literal>,
-                                            <literal>x(i,j)=a</literal> returns a new <literal>x</literal> matrix
-                                            such as <literal>x(int(i(l)),int(j(k)))=a(l,k) </literal> for
-                                            <literal>l</literal> from 1 to
-                                            <literal>size(i,'*')</literal> and <literal>k</literal> from
-                                            1 to <literal>size(j,'*')</literal>, other initial
-                                            entries of <literal>x</literal> are unchanged.
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            If <literal>a</literal> is a scalar
-                                            <literal>x(i,j)=a</literal> returns a new <literal>x</literal> matrix
-                                            such as <literal>x(int(i(l)),int(j(k)))=a</literal> for
-                                            <literal>l</literal> from 1 to <literal>size(i,'*')</literal>
-                                            and <literal>k</literal> from 1 to
-                                            <literal>size(j,'*')</literal>, other initial entries
-                                            of <literal>x</literal> are unchanged.
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            If <literal>i</literal> or <literal>j</literal>
-                                            maximum value exceed corresponding <literal>x</literal> matrix
-                                            dimension, array <literal>x</literal> is previously extended to the
-                                            required dimensions with zeros entries for standard
-                                            matrices, 0 length character string for string matrices and
-                                            false values for boolean matrices.
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            <literal>x(i,j)=[]</literal> kills rows
-                                            specified by <literal>i</literal> if <literal>j</literal> matches all
-                                            columns of <literal>x</literal> or kills columns specified by
-                                            <literal>j</literal> if <literal>i</literal> matches all rows of
-                                            <literal>x</literal>. In other cases <literal>x(i,j)=[]</literal>
-                                            produce an error.
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            <literal>x(i)=a</literal> with an <literal>a</literal>
-                                            vector returns a new <literal>x</literal> matrix such as
-                                            <literal>x(int(i(l)))=a(l)</literal> for <literal>l</literal> from 1 to
-                                            <literal>size(i,'*')</literal>, other initial entries
-                                            of <literal>x</literal> are unchanged.
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            <literal>x(i)=a</literal> with an <literal>a</literal>
-                                            scalar returns a new <literal>x</literal> matrix such as
-                                            <literal>x(int(i(l)))=a</literal> for <literal>l</literal> from 1 to
-                                            <literal>size(i,'*')</literal>, other initial entries
-                                            of <literal>x</literal> are unchanged.
-                                        </para>
-                                        <para>
-                                            If <literal>i</literal> maximum value exceed
-                                            <literal>size(x,1)</literal>, <literal>x</literal> is previously
-                                            extended to the required dimension with zeros entries for
-                                            standard matrices, 0 length character string for string
-                                            matrices and false values for boolean matrices.
-                                        </para>
-                                        <variablelist>
-                                            <varlistentry>
-                                                <term>if</term>
-                                                <listitem>
-                                                    <para>
-                                                        <literal>x</literal> is a 1x1
-                                                    </para>
-                                                    <para>
-                                                        matrix <literal>a</literal> may be a row (respectively a
-                                                        column) vector with dimension
-                                                        <literal>size(i,'*')</literal>. Resulting
-                                                        <literal>x</literal> matrix is a row (respectively a column)
-                                                        vector
-                                                    </para>
-                                                </listitem>
-                                            </varlistentry>
-                                            <varlistentry>
-                                                <term>if</term>
-                                                <listitem>
-                                                    <para>
-                                                        <literal>x</literal> is a row
-                                                    </para>
-                                                    <para>
-                                                        vector <literal>a</literal> must be a row vector with
-                                                        dimension <literal>size(i,'*')</literal>
-                                                    </para>
-                                                </listitem>
-                                            </varlistentry>
-                                            <varlistentry>
-                                                <term>if</term>
-                                                <listitem>
-                                                    <para>
-                                                        <literal>x</literal> is a column
-                                                    </para>
-                                                    <para>
-                                                        vector <literal>a</literal> must be a column vector with
-                                                        dimension <literal>size(i,'*')</literal>
-                                                    </para>
-                                                </listitem>
-                                            </varlistentry>
-                                            <varlistentry>
-                                                <term>if</term>
-                                                <listitem>
-                                                    <para>
-                                                        <literal>x</literal> is a general
-                                                    </para>
-                                                    <para>
-                                                        matrix <literal>a</literal> must be a row or column vector
-                                                        with dimension <literal>size(i,'*')</literal> and
-                                                        <literal>i</literal> maximum value cannot exceed
-                                                        <literal>size(x,'*')</literal>.
-                                                    </para>
-                                                </listitem>
-                                            </varlistentry>
-                                        </variablelist>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            <literal>x(i)=[]</literal> kills entries
-                                            specified by <literal>i</literal>.
-                                        </para>
-                                    </listitem>
-                                </itemizedlist>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>The : symbol</term>
-                            <listitem>
-                                <para>
-                                    The <literal>:</literal> symbol stands for "all elements".
-                                </para>
-                                <itemizedlist>
-                                    <listitem>
-                                        <para>
-                                            <literal>x(i,:)=a</literal> is interpreted as
-                                            <literal>x(i,1:size(x,2))=a</literal>
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            <literal>x(:,j)=a</literal> is interpreted as
-                                            <literal>x(1:size(x,1),j)=a</literal>
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            <literal>x(:)=a</literal> returns in
-                                            <literal>x</literal> the <literal>a</literal> matrix reshaped
-                                            according to <literal>x</literal>
-                                            dimensions. <literal>size(x,'*')</literal> must be
-                                            equal to <literal>size(a,'*')</literal>.
-                                        </para>
-                                    </listitem>
-                                </itemizedlist>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>Vectors of boolean</term>
-                            <listitem>
-                                <para>
-                                    If an index (<literal>i</literal> or <literal>j</literal>) is a vector
-                                    of booleans it is interpreted as <literal>find(i)</literal> or
-                                    respectively <literal>find(j)</literal>.
-                                </para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>Polynomials</term>
-                            <listitem>
-                                <para>
-                                    If an index (<literal>i</literal> or <literal>j</literal>) is a vector of
-                                    polynomials or implicit polynomial vector it is interpreted
-                                    as <literal>horner(i,m)</literal> or respectively
-                                    <literal>horner(j,n)</literal> where <literal>m</literal> and
-                                    <literal>n</literal> are associated <literal>x</literal> dimensions.
-                                    Even if this feature works for all polynomials, it is
-                                    recommended to use polynomials in <literal>$</literal> for
-                                    readability.
-                                </para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>LIST OR TLIST CASE</term>
-                <listitem>
-                    <itemizedlist>
-                        <listitem>
-                            <para>If they are present
-                                the <literal>ki</literal> give the path to a sub-list entry of
-                                <literal>l</literal> data structure. They allow a recursive insertion
-                                without intermediate copies.  The <literal>l(k1)...(kn)(i)=a</literal>
-                                and <literal>l(list(k1,...,kn,i)=a)</literal> instructions are
-                                interpreted as:
-                            </para>
-                            <para>
-                                <literal>lk1 = l(k1)</literal>
-                            </para>
-                            <para>
-                                <literal> ..  = ..  </literal>
-                            </para>
-                            <para>
-                                <literal>lkn = lkn-1(kn)</literal>
-                            </para>
-                            <para>
-                                <literal>lkn(i) = a</literal>
-                            </para>
-                            <para>
-                                <literal>lkn-1(kn) = lkn</literal>
-                            </para>
-                            <para>
-                                <literal> ..  = ..  </literal>
-                            </para>
-                            <para>
-                                <literal>l(k1) = lk1</literal>
-                            </para>
-                            <para>
-                                And the <literal>l(k1)...(kn)(i,j)=a</literal> and  <literal>l(list(k1,...,kn,list(i,j))=a</literal>
-                                instructions are interpreted as:
-                            </para>
-                            <para>
-                                <literal>lk1 = l(k1)</literal>
-                            </para>
+                          <term>if</term>
+                          <listitem>
                             <para>
-                                <literal> ..  = ..  </literal>
+                              <literal>x</literal> is a 1x1
                             </para>
                             <para>
-                                <literal>lkn = lkn-1(kn)</literal>
+                              matrix <literal>a</literal> may be a row (respectively a
+                              column) vector with dimension
+                              <literal>size(i,'*')</literal>. Resulting
+                              <literal>x</literal> matrix is a row (respectively a column)
+                              vector
                             </para>
+                          </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                          <term>if</term>
+                          <listitem>
                             <para>
-                                <literal>lkn(i,j) = a</literal>
+                              <literal>x</literal> is a row
                             </para>
                             <para>
-                                <literal>lkn-1(kn) = lkn</literal>
+                              vector <literal>a</literal> must be a row vector with
+                              dimension <literal>size(i,'*')</literal>
                             </para>
+                          </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                          <term>if</term>
+                          <listitem>
                             <para>
-                                <literal> ..  = ..  </literal>
+                              <literal>x</literal> is a column
                             </para>
                             <para>
-                                <literal>l(k1)= lk1</literal>
+                              vector <literal>a</literal> must be a column vector with
+                              dimension <literal>size(i,'*')</literal>
                             </para>
-                        </listitem>
-                        <listitem>
+                          </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                          <term>if</term>
+                          <listitem>
                             <para>
-                                <literal>i</literal> may be :
+                              <literal>x</literal> is a general
                             </para>
-                            <itemizedlist>
-                                <listitem>
-                                    <para> a real non negative scalar (only its integer part is taken into account).
-                                        <literal>l(0)=a</literal> adds an entry on the "left"
-                                        of the list. <literal>l(i)=a</literal> sets the <literal>i</literal>
-                                        entry of the list <literal>l</literal> to <literal>a</literal>. If
-                                        <literal>i&gt;size(l)</literal>, <literal>l</literal> is previously
-                                        extended with zero length entries (undefined).
-                                        <literal>l(i)=null()</literal> deletes the <literal>i</literal>th list
-                                        entry.
-                                    </para>
-                                </listitem>
-                                <listitem>
-                                    <para>
-                                        a polynomial.  If <literal>i</literal> is a
-                                        polynomial it is interpreted as <literal>horner(i,m)</literal>
-                                        where <literal>m=size(l)</literal>.  Even if this feature works
-                                        for all polynomials, it is recommended to use polynomials
-                                        in <literal>$</literal> for readability.
-                                    </para>
-                                </listitem>
-                            </itemizedlist>
-                        </listitem>
-                        <listitem>
                             <para>
-                                <literal>k1,..kn</literal> may be :
+                              matrix <literal>a</literal> must be a row or column vector
+                              with dimension <literal>size(i,'*')</literal> and
+                              <literal>i</literal> maximum value cannot exceed
+                              <literal>size(x,'*')</literal>.
                             </para>
-                            <itemizedlist>
-                                <listitem>
-                                    <para>
-                                        real positive scalar.
-                                    </para>
-                                </listitem>
-                                <listitem>
-                                    <para> a polynomial, interpreted as
-                                        <literal>horner(ki,m)</literal> where <literal>m</literal> is the
-                                        corresponding sub-list size.
-                                    </para>
-                                </listitem>
-                                <listitem>
-                                    <para> a character string associated with a
-                                        sub-list entry name.
-                                    </para>
-                                </listitem>
-                            </itemizedlist>
-                        </listitem>
-                    </itemizedlist>
+                          </listitem>
+                        </varlistentry>
+                      </variablelist>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>x(i)=[]</literal> kills entries
+                        specified by <literal>i</literal>.
+                      </para>
+                    </listitem>
+                  </itemizedlist>
                 </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>Remarks</title>
-        <para>
-            For soft coded matrix types such as rational functions and state space linear systems, <literal>x(i)</literal> syntax must not be used for vector entry insertion due to confusion with list entry insertion. <literal>x(1,j)</literal> or <literal>x(i,1)</literal> syntax must be used.
-        </para>
+              </varlistentry>
+              <varlistentry>
+                <term>The : symbol</term>
+                <listitem>
+                  <para>
+                    The <literal>:</literal> symbol stands for "all elements".
+                  </para>
+                  <itemizedlist>
+                    <listitem>
+                      <para>
+                        <literal>x(i,:)=a</literal> is interpreted as
+                        <literal>x(i,1:size(x,2))=a</literal>
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>x(:,j)=a</literal> is interpreted as
+                        <literal>x(1:size(x,1),j)=a</literal>
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>x(:)=a</literal> returns in
+                        <literal>x</literal> the <literal>a</literal> matrix reshaped
+                        according to <literal>x</literal>
+                        dimensions. <literal>size(x,'*')</literal> must be
+                        equal to <literal>size(a,'*')</literal>.
+                      </para>
+                    </listitem>
+                  </itemizedlist>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>Vectors of boolean</term>
+                <listitem>
+                  <para>
+                    If an index (<literal>i</literal> or <literal>j</literal>) is a vector
+                    of booleans it is interpreted as <literal>find(i)</literal> or
+                    respectively <literal>find(j)</literal>.
+                  </para>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>Polynomials</term>
+                <listitem>
+                  <para>
+                    If an index (<literal>i</literal> or <literal>j</literal>) is a vector of
+                    polynomials or implicit polynomial vector it is interpreted
+                    as <literal>horner(i,m)</literal> or respectively
+                    <literal>horner(j,n)</literal> where <literal>m</literal> and
+                    <literal>n</literal> are associated <literal>x</literal> dimensions.
+                    Even if this feature works for all polynomials, it is
+                    recommended to use polynomials in <literal>$</literal> for
+                    readability.
+                  </para>
+                </listitem>
+              </varlistentry>
+            </variablelist>
+        </refsect3>
+        <refsect3>
+            <title>List or Tlist case</title>
+            <itemizedlist>
+              <listitem>
+                <para>If they are present
+                  the <literal>ki</literal> give the path to a sub-list entry of
+                  <literal>l</literal> data structure. They allow a recursive insertion
+                  without intermediate copies.  The <literal>l(k1)...(kn)(i)=a</literal>
+                  and <literal>l(list(k1,...,kn,i)=a)</literal> instructions are
+                  interpreted as:
+                </para>
+                <para>
+                  <literal>lk1 = l(k1)</literal>
+                </para>
+                <para>
+                  <literal> ..  = ..  </literal>
+                </para>
+                <para>
+                  <literal>lkn = lkn-1(kn)</literal>
+                </para>
+                <para>
+                  <literal>lkn(i) = a</literal>
+                </para>
+                <para>
+                  <literal>lkn-1(kn) = lkn</literal>
+                </para>
+                <para>
+                  <literal> ..  = ..  </literal>
+                </para>
+                <para>
+                  <literal>l(k1) = lk1</literal>
+                </para>
+                <para>
+                  And the <literal>l(k1)...(kn)(i,j)=a</literal> and  <literal>l(list(k1,...,kn,list(i,j))=a</literal>
+                  instructions are interpreted as:
+                </para>
+                <para>
+                  <literal>lk1 = l(k1)</literal>
+                </para>
+                <para>
+                  <literal> ..  = ..  </literal>
+                </para>
+                <para>
+                  <literal>lkn = lkn-1(kn)</literal>
+                </para>
+                <para>
+                  <literal>lkn(i,j) = a</literal>
+                </para>
+                <para>
+                  <literal>lkn-1(kn) = lkn</literal>
+                </para>
+                <para>
+                  <literal> ..  = ..  </literal>
+                </para>
+                <para>
+                  <literal>l(k1)= lk1</literal>
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  <literal>i</literal> may be :
+                </para>
+                <itemizedlist>
+                  <listitem>
+                    <para> a real non negative scalar (only its integer part is taken into account).
+                      <literal>l(0)=a</literal> adds an entry on the "left"
+                      of the list. <literal>l(i)=a</literal> sets the <literal>i</literal>
+                      entry of the list <literal>l</literal> to <literal>a</literal>. If
+                      <literal>i&gt;size(l)</literal>, <literal>l</literal> is previously
+                      extended with zero length entries (undefined).
+                      <literal>l(i)=null()</literal> deletes the <literal>i</literal>th list
+                      entry.
+                    </para>
+                  </listitem>
+                  <listitem>
+                    <para>
+                      a polynomial.  If <literal>i</literal> is a
+                      polynomial it is interpreted as <literal>horner(i,m)</literal>
+                      where <literal>m=size(l)</literal>.  Even if this feature works
+                      for all polynomials, it is recommended to use polynomials
+                      in <literal>$</literal> for readability.
+                    </para>
+                  </listitem>
+                </itemizedlist>
+              </listitem>
+              <listitem>
+                <para>
+                  <literal>k1,..kn</literal> may be :
+                </para>
+                <itemizedlist>
+                  <listitem>
+                    <para>
+                      real positive scalar.
+                    </para>
+                  </listitem>
+                  <listitem>
+                    <para> a polynomial, interpreted as
+                      <literal>horner(ki,m)</literal> where <literal>m</literal> is the
+                      corresponding sub-list size.
+                    </para>
+                  </listitem>
+                  <listitem>
+                    <para> a character string associated with a
+                      sub-list entry name.
+                    </para>
+                  </listitem>
+                </itemizedlist>
+              </listitem>
+            </itemizedlist>
+        </refsect3>
+        <refsect3>
+            <title>Remarks</title>
+            <para>
+                For soft coded matrix types such as rational functions and state space linear
+                systems, <literal>x(i)</literal> syntax must not be used for vector entry
+                insertion due to confusion with list entry insertion. <literal>x(1,j)</literal>
+                or <literal>x(i,1)</literal> syntax must be used.
+            </para>
+        </refsect3>
     </refsection>
     <refsection>
         <title>Examples</title>
+        <para>Matrix cases:</para>
         <programlisting role="example"><![CDATA[
-// MATRIX CASE
-a=[1 2 3;4 5 6]
-a(1,2)=10
-a([1 1],2)=[-1;-2]
-a(:,1)=[8;5]
-a(1,3:-1:1)=[77 44 99]
-a(1)=%s
-a(6)=%s+1
-a(:)=1:6
-a([%t %f],1)=33
-a(1:2,$-1)=[2;4]
-a($:-1:1,1)=[8;7]
-a($)=123
-a(1,%pi)=1 //equivalent to a(1,3)=1
+a = [1 2 3;4 5 6]
+a(1,2) = 10
+a([1 1],2) = [-1;-2]
+a(:,1) = [8;5]
+a(1,3:-1:1) = [77 44 99]
+a(1) = %s
+a(6) = %s+1
+a(:) = 1:6
+a([%t %f],1) = 33
+a(1:2,$-1) = [2;4]
+a($:-1:1,1) = [8;7]
+a($) = 123
+a(1,%pi) = 1 // equivalent to a(1,3)=1
 //
-x='test'
-x([4 5])=['4','5']
+x = 'test'
+x([4 5]) = ['4','5']
 //
-b=[1/%s,(%s+1)/(%s-1)]
-b(1,1)=0
-b(1,$)=b(1,$)+1
-b(2)=[1 2] // the numerator
-// LIST OR TLIST CASE
-l=list(1,'qwerw',%s)
-l(1)='Changed'
-l(0)='Added'
-l(%pi)=1 //equivalent to l(3)=1
-l(6)=['one more';'added']
+b = [1/%s, (%s+1)/(%s-1)]
+b(1,1) = 0
+b(1,$) = b(1,$)+1
+b(2) = [1 2] // the numerator
+     ]]></programlisting>
+        <para>List or Tlist cases:</para>
+        <programlisting role="example"><![CDATA[
+l = list(1,'qwerw',%s)
+l(1) = 'Changed'
+l(0) = 'Added'
+l(%pi) = 1 // equivalent to l(3)=1
+l(6) = ['one more';'added']
 //
 //
-dts=list(1,tlist(['x';'a';'b'],10,[2 3]));
-dts(2).a=33
-dts(2)('b')(1,2)=-100
- ]]></programlisting>
+dts = list(1, tlist(['x';'a';'b'],10,[2 3]));
+dts(2).a = 33
+dts(2)('b')(1,2) = -100
+     ]]></programlisting>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
         <simplelist type="inline">
             <member>
+                <link linkend="extraction">extraction</link>
+            </member>
+            <member>
+                <link linkend="colon">colon</link>
+            </member>
+            <member>
                 <link linkend="find">find</link>
             </member>
             <member>
@@ -433,9 +441,6 @@ dts(2)('b')(1,2)=-100
             <member>
                 <link linkend="parentheses">parentheses</link>
             </member>
-            <member>
-                <link linkend="extraction">extraction</link>
-            </member>
         </simplelist>
     </refsection>
 </refentry>
index 16dc100..5c71694 100644 (file)
  * along with this program.
  *
  -->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xml:id="cumsum">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
+          xmlns:db="http://docbook.org/ns/docbook" xml:id="cumsum">
     <refnamediv>
         <refname>cumsum</refname>
-        <refpurpose>cumulative sum of array elements</refpurpose>
+        <refpurpose>partial cumulative sums of the elements of an array</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
-        <synopsis>y=cumsum(x)
-            y=cumsum(x,orientation)
-            y=cumsum(x,outtype)
-            y=cumsum(x,orientation,outtype)
+        <synopsis>
+            y = cumsum(x)
+            y = cumsum(x, outtype)
+            y = cumsum(x, orientation)
+            y = cumsum(x, orientation, outtype)
         </synopsis>
     </refsynopsisdiv>
 
             <varlistentry>
                 <term>x</term>
                 <listitem>
-                    <para>an array of reals, complex, booleans, polynomials or rational fractions.</para>
+                    <para>
+                        array of booleans, integers, real or complex numbers, polynomials, or
+                        rational fractions.
+                        Hypermatrices or sparse boolean or numerical matrices are supported as well.
+                    </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                     <itemizedlist>
                         <listitem>
                             <para>
-                                either a string with possible values <literal>"*"</literal>, <literal>"r"</literal>, <literal>"c"</literal> or <literal>"m"</literal>
+                                either a string with possible values <literal>"*"</literal>,
+                                <literal>"r"</literal>, <literal>"c"</literal> or <literal>"m"</literal>
                             </para>
                         </listitem>
                         <listitem>
-                            <para>or a number with positive integer value</para>
+                            <para>
+                              positive integer 1 ≤ orientation ≤ ndims(x): the index of the
+                              dimension along which the cumulative sum must be computed.
+                              1 and "r", and 2 and "c", are equivalent.
+                            </para>
                         </listitem>
                     </itemizedlist>
                 </listitem>
                 <term>outtype</term>
                 <listitem>
                     <para>
-                        a string with possible values <literal>"native"</literal> or <literal>"double"</literal>.
+                        Word <literal>"native"</literal> or <literal>"double"</literal>.
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>y</term>
                 <listitem>
-                    <para>scalar or array</para>
+                    <para>Array of size equal to that of <varname>x</varname>.</para>
                 </listitem>
             </varlistentry>
         </variablelist>
     <refsection role="description">
         <title>Description</title>
         <para>
-            Returns the cumulative sum of array elements.
-            For an array <term>x</term>, <literal>y=cumsum(x)</literal> a matrix <term>y</term> of the same size as <term>x</term>.
-            The value <literal>y(i)</literal> is the sum of all elements of <literal>x(1:i)</literal> <emphasis role="italic">i.e.</emphasis>:
+            <emphasis role="bold">y = cumsum(x)</emphasis> computes and provides the partial
+            cumulative sums <literal>y(i)=sum(x(1:i))</literal>, <emphasis role="italic">i.e.</emphasis>:
         </para>
         <para>
-            <latex><![CDATA[ y(i) = \sum_{k=1}^i x(k)]]></latex>
+            <latex alt="y(i) = ∑u=1→i x(u)"><![CDATA[ y(i) = \sum_{u=1}^i x(u)]]></latex>
         </para>
         <para>
-            <literal>y=cumsum(x,orientation)</literal> returns in <term>y</term> the cumulative sum of <term>x</term> along the dimension given by <term>orientation</term>:
+            <emphasis role="bold">y = cumsum(x, orientation)</emphasis> returns the partial
+            cumulative sums of <term>x</term> along the dimension given by <term>orientation</term>:
         </para>
         <itemizedlist>
             <listitem>
                     if <term>orientation</term> is equal to 1 or "r" then:
                 </para>
                 <para>
-                    <latex><![CDATA[ y(\mathbf{l},j) = \sum_{\mathbf{i}=1}^l x(\mathbf{i},j)]]></latex>
+                    <latex alt="y(i,j) = ∑u=1→i x(u,j)"><![CDATA[
+                        y(\mathbf{i},j) = \sum_{u=1}^{\mathbf{i}} x(\mathbf{u},j)   ]]>
+                    </latex>, or for a N-Dimensional array:
                 </para>
-                <para>or </para>
                 <para>
-                    <latex><![CDATA[ y(\mathbf{l},j,k,\ldots) = \sum_{\mathbf{i}=1}^l x(\mathbf{i},j,k,\ldots)]]></latex>
+                    <latex alt="y(i,j,k,…) = ∑u=1→i x(u,j,k,…)"><![CDATA[
+                        y(\mathbf{i},j,k,\ldots) = \sum_{u=1}^{\mathbf{i}} x(\mathbf{u},j,k,\ldots)  ]]>
+                    </latex>
                 </para>
             </listitem>
             <listitem>
                     if <term>orientation</term> is equal to 2 or "c" then:
                 </para>
                 <para>
-                    <latex><![CDATA[ y(i,\mathbf{l}) = \sum_{\mathbf{j}=1}^l x(i,{\mathbf{j})]]></latex>
+                    <latex alt="y(i,j) = ∑u=1→j x(i,u)"><![CDATA[
+                        y(i,\mathbf{j}) = \sum_{u=1}^{\mathbf{j}} x(i,{\mathbf{u})  ]]>
+                    </latex>, or for a N-Dimensional array:
                 </para>
-                <para> or </para>
                 <para>
-                    <latex><![CDATA[ y(i,\mathbf{l},k,\ldots) = \sum_{\mathbf{j}=1}^l x(i,\mathbf{j},k,\ldots)]]></latex>
+                    <latex alt="y(i,j,k,…) = ∑u=1→j x(i,u,k,…)"><![CDATA[
+                        y(i,\mathbf{j},k,\ldots) = \sum_{u=1}^{\mathbf{j}} x(i,\mathbf{u},k,\ldots) ]]>
+                    </latex>
                 </para>
             </listitem>
             <listitem>
                     if <term>orientation</term> is equal to n then:
                 </para>
                 <para>
-                    <latex><![CDATA[ y(i_1,\ldots,i_{n-1},\mathbf{l},i_{n+1},\ldots) = \sum_{\mathbf{i_n}=1}^l x(i_1,\ldots,i_{n-1},\mathbf{i_n},i_{n+1},\ldots)]]></latex>
+                    <latex alt="y(i₁,…,iₙ₋₁, iₙ,iₙ₊₁,…) = ∑u=1…iₙ  x(i₁,…,iₙ₋₁, u,iₙ₊₁,…)"><![CDATA[
+                        y(i_1,\ldots,i_{n-1},\mathbf{i_{n}},i_{n+1},\ldots) =
+                        \sum_{u=1}^{\mathbf{i_n}} x(i_1,\ldots,i_{n-1},\mathbf{u},i_{n+1},\ldots) ]]>
+                    </latex>
                 </para>
             </listitem>
             <listitem>
                 <para>
-                    <literal>y=cumsum(x,"*")</literal> is equivalent to <literal>y=cumsum(x)</literal>
+                    <emphasis role="bold">y = cumsum(x, "*")</emphasis> is equivalent to
+                    <literal>y = cumsum(x)</literal>
                 </para>
             </listitem>
             <listitem>
                 <para>
-                    <literal>y=cumsum(x,"m")</literal> is equivalent to <literal>y=cumsum(x,orientation)</literal> where <term>orientation</term> is the index of the first dimension of <term>x</term> that is greater than 1. This option is used for Matlab compatibility.
+                    <emphasis role="bold">y = cumsum(x, "m")</emphasis> is equivalent to
+                    <literal>y = cumsum(x, orientation)</literal> where <term>orientation</term>
+                    is the index of the first dimension of <term>x</term> that is greater than 1.
+                    This option is used for Matlab compatibility.
                 </para>
             </listitem>
         </itemizedlist>
         <para/>
         <para>
-            The <term>outtype</term> argument rules the way the summation is done:
+            The <term>outtype</term> argument rules the way the summations are done:
         </para>
         <itemizedlist>
             <listitem>
                 <para>
-                    For arrays of floats, of polynomials, of rational fractions, the evaluation is always done using floating points computations. The <literal>"double"</literal> or <literal>"native"</literal> options are equivalent.
+                    For arrays of floats, of polynomials, of rational fractions, the evaluation
+                    is always done using floating points computations. The <literal>"double"</literal>
+                    or <literal>"native"</literal> options are equivalent.
                 </para>
             </listitem>
             <listitem>
                 <para>For arrays of integers,</para>
                 <para>
-                    if <literal>outtype="native"</literal> the evaluation is done using integer computations (modulo 2^b, where b is the number of bits used),
+                    if <literal>outtype="native"</literal> the evaluation is done using integer
+                    computations (modulo 2^b, where b is the number of bits used),
                 </para>
                 <para>
-                    if <literal>outtype="double"</literal> the evaluation is done using floating point computations.
+                    if <literal>outtype="double"</literal> the evaluation is done using floating
+                    point computations.
                 </para>
                 <para>
                     The default value is <literal>outtype="native"</literal>.
             <listitem>
                 <para>For arrays of booleans,</para>
                 <para>
-                    if <literal>outtype="native"</literal> the evaluation is done using boolean computations ( + is replaced by |),
+                    if <literal>outtype="native"</literal> the evaluation is done using boolean
+                    computations ( + is replaced with |),
                 </para>
                 <para>
-                    if <literal>outtype="double"</literal> the evaluation is done using floating point computations (%t values are replaced by 1 and %f values by 0).
+                    if <literal>outtype="double"</literal> the evaluation is done using floating
+                    point computations (%t values are replaced by 1 and %f values by 0).
                 </para>
                 <para>
                     The default value is <literal>outtype="double"</literal>.
                 </para>
             </listitem>
         </itemizedlist>
-        <note>
-            This function applies, with identical rules to <link linkend="sparse">sparse matrices</link>.
-        </note>
+        <warning>
+            When the input <varname>x</varname> is sparse, please keep in mind that the density
+            of the result <varname>y</varname> will be almost always close to 100%.
+        </warning>
     </refsection>
 
     <refsection role="examples">
         <title>Examples</title>
         <programlisting role="example"><![CDATA[
-A=[1,2;3,4];
+A = [1,2;3,4];
 cumsum(A)
 cumsum(A,1)
 
-I=uint8([2 95 103;254 9 0])
-cumsum(I) //native evaluation
+I = uint8([2 95 103 ; 254 9 0])
+cumsum(I) // native evaluation
 cumsum(I,"double")
 cumsum(I,2,"double")
 
-s=poly(0,"s");
-P=[s,%i+s;s^2,1];
-cumsum(P),
-cumsum(P,2)
+s = poly(0,"s");
+P = [s, %i+s ; s^2 , 1];
+cumsum(P)
+cumsum(P, 2)
 
-B=[%t %t %f %f];
-cumsum(B) //evaluation in float
-cumsum(B,"native") //similar to or(B)
+B = [%t %t %f %f];
+cumsum(B)          // evaluation in float
+cumsum(B,"native") // similar to or(B)
  ]]></programlisting>
     </refsection>
 
index 1f64025..6d886e1 100644 (file)
@@ -19,7 +19,7 @@
           xmlns:scilab="http://www.scilab.org" xml:id="gsort" xml:lang="en">
     <refnamediv>
         <refname>gsort</refname>
-        <refpurpose>sorts boolean, numerical and text arrays</refpurpose>
+        <refpurpose>sorts boolean, numerical and string arrays</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
@@ -38,7 +38,7 @@
                 <term>A</term>
                 <listitem>
                     Scalar, vector, matrix or hypermatrix of booleans, integers, real or
-                    complex numbers, or text. Sparse matrices of real numbers,
+                    complex numbers, or strings. Sparse matrices of real numbers,
                     of complex numbers, or of booleans can also be sorted.
                     <note>
                         Overloading for unhandled types is allowed.
                             </listitem>
                             <listitem>
                                 <literal>R</literal> must be of simple sortable type: boolean,
-                                integer, real, text.
+                                integer, real, string.
                             </listitem>
                         </itemizedlist>
                     </para>
             The multilevel mode is described with details in a dedicated subsection below.
         </para>
         <para>
-            Texts are sorted in alphabetical order, in a case-sensitive way.
-            Extended UTF characters are supported.
+            Strings are sorted in alphabetical order, in a case-sensitive way.
+            Extended UTF characters are supported. The empty string "" is considered "smaller"
+            than any other string.
         </para>
         <para>
             Sorting boolean arrays is mostly useful with the "r", "c", "lr" or "lc" methods.
                         <para/>
                     </listitem>
                     <listitem>
-                        <emphasis>Sorting the columns of a matrix T of texts,
+                        <emphasis>Sorting the columns of a matrix T of strings,
                         first: by increasing length, second: in anti-alphabetical order</emphasis>:
                         <para/>
                         <literal>gsort(T, "c", ["i" "d"], list(length, :))</literal>
@@ -509,7 +510,7 @@ c = evstr(s)
 ]]></screen>
         </para>
         <para>
-            <emphasis role="bold">With some texts:</emphasis>
+            <emphasis role="bold">With some strings:</emphasis>
             Sorting rows in columns, first by increasing lengths, second by alphabetical order
         </para>
         <para>
index bbd7be7..79b532e 100644 (file)
@@ -1,5 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="extraction" xml:lang="fr">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
+          xmlns:scilab="http://www.scilab.org" xml:id="extraction" xml:lang="fr">
     <refnamediv>
         <refname>extraction</refname>
         <refpurpose>extraction à partir d'une matrice ou d'une liste</refpurpose>
@@ -10,8 +13,8 @@
             x(i)
             x(i,j)
             x(i,j,k,...)
-            [...]=l(i)
-            [...]=l(k1)...(kn)(i) ou [...]=l(list(k1,...,kn,i))
+            [...] = l(i)
+            [...] = l(k1)...(kn)(i) ou [...] = l(list(k1,...,kn,i))
             l(k1)...(kn)(i,j) ou l(list(k1,...,kn,list(i,j))
         </synopsis>
     </refsynopsisdiv>
     </refsection>
     <refsection>
         <title>Description</title>
-        <variablelist>
-            <varlistentry>
-                <term>CAS DES MATRICES</term>
+        <refsect3>
+            <title>Cas des matrices</title>
+            <para>
+              <literal>i</literal>, <literal>j</literal>,
+              <literal>k</literal>, ... peuvent être :
+            </para>
+            <variablelist>
+              <varlistentry>
+                <term>Un scalaire, un vecteur ou une matrice à éléments
+                  positifs.
+                </term>
                 <listitem>
-                    <para>
-                        <literal>i</literal>, <literal>j</literal>,
-                        <literal>k</literal>, ... peuvent être :
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>Un scalaire, un vecteur ou une matrice à éléments
-                                positifs.
-                            </term>
-                            <listitem>
-                                <itemizedlist>
-                                    <listitem>
-                                        <para>
-                                            <literal>r=x(i,j)</literal> construit la matrice
-                                            <literal>r</literal> telle que:
-                                        </para>
-                                        <para>
-                                            <literal>r(l,k)=x(int(i(l)),int(j(k)))</literal>
-                                        </para>
-                                        <para>
-                                            pour <literal>l</literal> variant de 1 à
-                                            <literal>size(i,'*')</literal>
-                                        </para>
-                                        <para>
-                                            et <literal>k</literal> variant de 1 à
-                                            <literal>size(j,'*')</literal>.
-                                        </para>
-                                        <para>
-                                            La valeur maximale de <literal>i</literal> (resp.
-                                            <literal>j</literal>) doit être inférieure ou égale à
-                                            <literal>size(x,1)</literal> (resp.
-                                            <literal>size(x,2)</literal>).
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            <literal>r=x(i)</literal> où <literal>x</literal>
-                                            est une matrice 1 x 1, construit la matrice
-                                            <literal>r</literal> telle que
-                                            <literal>r(l,k)=x(int(i(l)),int(i(k)))</literal> pour
-                                            <literal>l</literal> variant de 1 à
-                                            <literal>size(i,1)</literal> et <literal>k</literal>
-                                            variant de 1 à <literal>size(i,2)</literal>. Noter que
-                                            dans ce cas l'indice <literal>i</literal> est valable si
-                                            toutes ses composantes sont égales à 1.
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            <literal>r=x(i)</literal> avec <literal>x</literal>
-                                            un vecteur ligne, construit le vecteur ligne
-                                            <literal>r</literal> tel que
-                                            <literal>r(l)=x(int(i(l)))</literal> pour
-                                            <literal>l</literal> entre 1 et
-                                            <literal>size(i,'*')</literal> La valeur maximale de
-                                            <literal>i</literal> doit être inférieure ou égale à
-                                            <literal>size(x,'*')</literal>.
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            <literal>r=x(i)</literal> avec <literal>x</literal>
-                                            une matrice à une ou plusieurs colonnes, construit la
-                                            matrice <literal>r</literal> telle que
-                                            <literal>r(l)</literal> (<literal>l</literal> variant de 1
-                                            à <literal>size(i,'*')</literal>) contient le terme numéro
-                                            <literal>int(i(l))</literal> du vecteur colonne issu de la
-                                            concaténation des colonnes de <literal>x</literal>. La
-                                            valeur maximale de <literal>i</literal> doit être
-                                            inférieure ou égale à
-                                            <literal>size(x,'*')</literal>.
-                                        </para>
-                                    </listitem>
-                                </itemizedlist>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>Le symbole</term>
-                            <listitem>
-                                <para>
-                                    <literal> : </literal> signifiant "tous les
-                                    éléments".
-                                </para>
-                                <itemizedlist>
-                                    <listitem>
-                                        <para>
-                                            <literal>r=x(i,:)</literal> construit la matrice
-                                            <literal>r</literal> telle que
-                                            <literal>r(l,k)=x(int(i(l)),k))</literal> pour
-                                            <literal>l</literal> variant de 1 à
-                                            <literal>size(i,'*')</literal> et <literal>k</literal>
-                                            variant de 1 à <literal>size(x,2)</literal>
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            <literal>r=x(:,j)</literal> construit la matrice
-                                            <literal>r</literal> telle que
-                                            <literal>r(l,k)=x(l,int(j(k)))</literal> pour
-                                            <literal>l</literal> variant de 1 à
-                                            <literal>size(r,1)</literal> et <literal>k</literal>
-                                            variant de 1 à <literal>size(j,'*')</literal>.
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            <literal>r=x(:)</literal> construit le vecteur
-                                            colonne <literal>r</literal> obtenu par concaténation des
-                                            colonnes de <literal> x</literal>. Cette commande est
-                                            équivalente à
-                                            <literal>r=matrix(x,size(x,'*'),1)</literal>.
-                                        </para>
-                                    </listitem>
-                                </itemizedlist>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>Un vecteur de booléens</term>
-                            <listitem>
-                                <para>
-                                    Si un indice (<literal>i</literal> ou
-                                    <literal>j</literal> ) est un vecteur de booléen il est
-                                    interprété comme <literal>find(i)</literal> ou
-                                    <literal>find(j)</literal>, respectivement.
-                                </para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>Un polynôme</term>
-                            <listitem>
-                                <para>
-                                    Si un indice (<literal>i</literal> ou
-                                    <literal>j</literal> ) est un vecteur de polynômes ou de
-                                    polynômes implicites il est interprété comme
-                                    <literal>horner(i,m)</literal> ou
-                                    <literal>horner(j,n)</literal>, respectivement, où
-                                    <literal>m</literal> et <literal>n</literal> sont les
-                                    dimensions de <literal>x</literal> associées. Même si cette
-                                    fonctionnalité marche pour tous les polynômes, il est
-                                    recommandé d'utiliser des polynômes dans <literal>$</literal>
-                                    par souci de lisibilité.
-                                </para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                    <para>Dans le case des matrices ayant plus de 2 dimensions
-                        (voir:<link linkend="hypermatrices">hypermatrices</link>) la
-                        dimensionalité est automatiquement réduite si les dimensions les
-                        plus à droite sont égales à 1.
-                    </para>
+                  <itemizedlist>
+                    <listitem>
+                      <para>
+                        <literal>r=x(i,j)</literal> construit la matrice
+                        <literal>r</literal> telle que:
+                      </para>
+                      <para>
+                        <literal>r(l,k)=x(int(i(l)),int(j(k)))</literal>
+                      </para>
+                      <para>
+                        pour <literal>l</literal> variant de 1 à
+                        <literal>size(i,'*')</literal>
+                      </para>
+                      <para>
+                        et <literal>k</literal> variant de 1 à
+                        <literal>size(j,'*')</literal>.
+                      </para>
+                      <para>
+                        La valeur maximale de <literal>i</literal> (resp.
+                        <literal>j</literal>) doit être inférieure ou égale à
+                        <literal>size(x,1)</literal> (resp.
+                        <literal>size(x,2)</literal>).
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>r=x(i)</literal> où <literal>x</literal>
+                        est une matrice 1 x 1, construit la matrice
+                        <literal>r</literal> telle que
+                        <literal>r(l,k)=x(int(i(l)),int(i(k)))</literal> pour
+                        <literal>l</literal> variant de 1 à
+                        <literal>size(i,1)</literal> et <literal>k</literal>
+                        variant de 1 à <literal>size(i,2)</literal>. Noter que
+                        dans ce cas l'indice <literal>i</literal> est valable si
+                        toutes ses composantes sont égales à 1.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>r=x(i)</literal> avec <literal>x</literal>
+                        un vecteur ligne, construit le vecteur ligne
+                        <literal>r</literal> tel que
+                        <literal>r(l)=x(int(i(l)))</literal> pour
+                        <literal>l</literal> entre 1 et
+                        <literal>size(i,'*')</literal> La valeur maximale de
+                        <literal>i</literal> doit être inférieure ou égale à
+                        <literal>size(x,'*')</literal>.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>r=x(i)</literal> avec <literal>x</literal>
+                        une matrice à une ou plusieurs colonnes, construit la
+                        matrice <literal>r</literal> telle que
+                        <literal>r(l)</literal> (<literal>l</literal> variant de 1
+                        à <literal>size(i,'*')</literal>) contient le terme numéro
+                        <literal>int(i(l))</literal> du vecteur colonne issu de la
+                        concaténation des colonnes de <literal>x</literal>. La
+                        valeur maximale de <literal>i</literal> doit être
+                        inférieure ou égale à
+                        <literal>size(x,'*')</literal>.
+                      </para>
+                    </listitem>
+                  </itemizedlist>
                 </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>CAS DES LISTES</term>
+              </varlistentry>
+              <varlistentry>
+                <term>Le symbole</term>
                 <listitem>
-                    <para>
-                        S'ils sont présents, les <literal>ki</literal> donnent le
-                        chemin vers un terme d'une sous-liste de la liste
-                        <literal>l</literal>. Ils permettent de faire une extraction
-                        récursive directe sans utiliser de variable intermédiaire.
-                    </para>
-                    <para> Les instructions:</para>
-                    <para>
-                        <literal>[...]=l(k1)...(kn)(i) et
-                            [...]=l(list(k1,...,kn,i))
-                        </literal>
-                    </para>
-                    <para>sont interprétées comme :</para>
-                    <para>
-                        <literal>lk1 = l(k1)</literal>, <literal> .. = .. </literal>,
-                        <literal>lkn = lkn-1(kn)</literal>, <literal>[...] =
-                            lkn(i)
-                        </literal>
-                    </para>
-                    <para>De même, les instructions</para>
-                    <para>
-                        <literal>l(k1)...(kn)(i,j) et
-                            l(list(k1,...,kn,list(i,j))
-                        </literal>
-                    </para>
-                    <para>sont interprétées comme :</para>
-                    <para>
-                        <literal>lk1 = l(k1)</literal>, <literal> .. = .. </literal>,
-                        <literal>lkn = lkn-1(kn)</literal>,
-                        <literal>lkn(i,j)</literal>
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>
-                                <literal>i</literal> et <literal>j</literal>, peuvent être
-                                :
-                            </term>
-                            <listitem>
-                                <variablelist>
-                                    <varlistentry>
-                                        <term>un scalaire, un vecteur ou matrice à termes positifs </term>
-                                        <listitem>
-                                            <para>
-                                                <literal>[r1,...rn]=l(i)</literal> extrait les termes
-                                                <literal>i(k)</literal> de la liste l et les stocke dans les
-                                                variables <literal>rk</literal> pour <literal>k</literal>
-                                                variant de 1 à <literal>size(i,'*')</literal>
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>
-                                            le symbole <literal> : </literal>
-                                        </term>
-                                        <listitem>
-                                            <para> qui représente "tous les éléments".</para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>un vecteur de booléens</term>
-                                        <listitem>
-                                            <para>
-                                                Si <literal>i</literal> est un vecteur de booléens, il
-                                                est interprété comme <literal>find(i)</literal>.
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>un polynôme</term>
-                                        <listitem>
-                                            <para>
-                                                Si <literal>i</literal> est un vecteur de polynômes ou
-                                                de polynômes implicites il est interprété comme
-                                                <literal>horner(i,m)</literal> où
-                                                <literal>m=size(l)</literal>. Même si cette fonctionnalité
-                                                marche pour tous les polynômes, il est recommandé d'utiliser
-                                                des polynômes dans <literal>$</literal> par souci de
-                                                lisibilité.
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                </variablelist>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>
-                                <literal>k1</literal>,..<literal>kn</literal> peuvent être :
-                            </term>
-                            <listitem>
-                                <variablelist>
-                                    <varlistentry>
-                                        <term>un nombre réel positif à valeur entière</term>
-                                        <listitem>
-                                            <para/>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>un polynôme</term>
-                                        <listitem>
-                                            <para>un polynôme, interprété comme
-                                                <literal>horner(ki,m)</literal> ou <literal>m</literal> est la
-                                                taille de la sous-liste correspondante.
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>une chaîne de caractères</term>
-                                        <listitem>
-                                            <para>associée à un nom d'entrée de sous-liste</para>
-                                        </listitem>
-                                    </varlistentry>
-                                </variablelist>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                    <para>Quand le chemin désigne plusieurs termes d'une liste
-                        l'instruction doit avoir autant de termes dans la liste des
-                        arguments du membre de gauche que le nombre de termes sélectionnés.
-                        Mais si la syntaxe d'extraction est utilisée dans les arguments
-                        d'entrée d'une fonction, chaque terme renvoyé est ajouté aux
-                        arguments d'entrée.
-                    </para>
-                    <para>
-                        Notez que <literal>l(list())</literal> est identique à
-                        <literal>l</literal>.
-                    </para>
+                  <para>
+                    <literal> : </literal> signifiant "tous les
+                    éléments".
+                  </para>
+                  <itemizedlist>
+                    <listitem>
+                      <para>
+                        <literal>r=x(i,:)</literal> construit la matrice
+                        <literal>r</literal> telle que
+                        <literal>r(l,k)=x(int(i(l)),k))</literal> pour
+                        <literal>l</literal> variant de 1 à
+                        <literal>size(i,'*')</literal> et <literal>k</literal>
+                        variant de 1 à <literal>size(x,2)</literal>
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>r=x(:,j)</literal> construit la matrice
+                        <literal>r</literal> telle que
+                        <literal>r(l,k)=x(l,int(j(k)))</literal> pour
+                        <literal>l</literal> variant de 1 à
+                        <literal>size(r,1)</literal> et <literal>k</literal>
+                        variant de 1 à <literal>size(j,'*')</literal>.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>r=x(:)</literal> construit le vecteur
+                        colonne <literal>r</literal> obtenu par concaténation des
+                        colonnes de <literal> x</literal>. Cette commande est
+                        équivalente à
+                        <literal>r=matrix(x,size(x,'*'),1)</literal>.
+                      </para>
+                    </listitem>
+                  </itemizedlist>
                 </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>REMARQUES</title>
-        <para>Pour les matrices rationnelles et les systèmes dynamiques linéaires
-            stockés sous forme de représentation d'état, la syntaxe
-            <literal>x(i)</literal> ne doit pas être utilisée pour l'extraction des
-            éléments d'un vecteur, à cause de la confusion possible avec l'extraction
-            des éléments de liste. La syntaxe <literal>x(1,j)</literal> où
-            <literal>x(i,1)</literal> doit être utilisée dans ce cas.
-        </para>
+              </varlistentry>
+              <varlistentry>
+                <term>Un vecteur de booléens</term>
+                <listitem>
+                  <para>
+                    Si un indice (<literal>i</literal> ou
+                    <literal>j</literal> ) est un vecteur de booléen il est
+                    interprété comme <literal>find(i)</literal> ou
+                    <literal>find(j)</literal>, respectivement.
+                  </para>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>Un polynôme</term>
+                <listitem>
+                  <para>
+                    Si un indice (<literal>i</literal> ou
+                    <literal>j</literal> ) est un vecteur de polynômes ou de
+                    polynômes implicites il est interprété comme
+                    <literal>horner(i,m)</literal> ou
+                    <literal>horner(j,n)</literal>, respectivement, où
+                    <literal>m</literal> et <literal>n</literal> sont les
+                    dimensions de <literal>x</literal> associées. Même si cette
+                    fonctionnalité marche pour tous les polynômes, il est
+                    recommandé d'utiliser des polynômes dans <literal>$</literal>
+                    par souci de lisibilité.
+                  </para>
+                </listitem>
+              </varlistentry>
+            </variablelist>
+            <para>Dans le case des matrices ayant plus de 2 dimensions
+              (voir:<link linkend="hypermatrices">hypermatrices</link>) la
+              dimensionalité est automatiquement réduite si les dimensions les
+              plus à droite sont égales à 1.
+            </para>
+        </refsect3>
+        <refsect3>
+            <title>Cas des listes</title>
+            <para>
+              S'ils sont présents, les <literal>ki</literal> donnent le
+              chemin vers un terme d'une sous-liste de la liste
+              <literal>l</literal>. Ils permettent de faire une extraction
+              récursive directe sans utiliser de variable intermédiaire.
+            </para>
+            <para> Les instructions:</para>
+            <para>
+              <literal>[...]=l(k1)...(kn)(i) et
+                [...]=l(list(k1,...,kn,i))
+              </literal>
+            </para>
+            <para>sont interprétées comme :</para>
+            <para>
+              <literal>lk1 = l(k1)</literal>, <literal> .. = .. </literal>,
+              <literal>lkn = lkn-1(kn)</literal>, <literal>[...] =
+              lkn(i)
+              </literal>
+            </para>
+            <para>De même, les instructions</para>
+            <para>
+              <literal>l(k1)...(kn)(i,j) et
+                l(list(k1,...,kn,list(i,j))
+              </literal>
+            </para>
+            <para>sont interprétées comme :</para>
+            <para>
+              <literal>lk1 = l(k1)</literal>, <literal> .. = .. </literal>,
+              <literal>lkn = lkn-1(kn)</literal>,
+              <literal>lkn(i,j)</literal>
+            </para>
+            <variablelist>
+              <varlistentry>
+                <term>
+                  <literal>i</literal> et <literal>j</literal>, peuvent être
+                  :
+                </term>
+                <listitem>
+                  <variablelist>
+                    <varlistentry>
+                      <term>un scalaire, un vecteur ou matrice à termes positifs </term>
+                      <listitem>
+                        <para>
+                          <literal>[r1,...rn]=l(i)</literal> extrait les termes
+                          <literal>i(k)</literal> de la liste l et les stocke dans les
+                          variables <literal>rk</literal> pour <literal>k</literal>
+                          variant de 1 à <literal>size(i,'*')</literal>
+                        </para>
+                      </listitem>
+                    </varlistentry>
+                    <varlistentry>
+                      <term>
+                        le symbole <literal> : </literal>
+                      </term>
+                      <listitem>
+                        <para> qui représente "tous les éléments".</para>
+                      </listitem>
+                    </varlistentry>
+                    <varlistentry>
+                      <term>un vecteur de booléens</term>
+                      <listitem>
+                        <para>
+                          Si <literal>i</literal> est un vecteur de booléens, il
+                          est interprété comme <literal>find(i)</literal>.
+                        </para>
+                      </listitem>
+                    </varlistentry>
+                    <varlistentry>
+                      <term>un polynôme</term>
+                      <listitem>
+                        <para>
+                          Si <literal>i</literal> est un vecteur de polynômes ou
+                          de polynômes implicites il est interprété comme
+                          <literal>horner(i,m)</literal> où
+                          <literal>m=size(l)</literal>. Même si cette fonctionnalité
+                          marche pour tous les polynômes, il est recommandé d'utiliser
+                          des polynômes dans <literal>$</literal> par souci de
+                          lisibilité.
+                        </para>
+                      </listitem>
+                    </varlistentry>
+                  </variablelist>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>
+                  <literal>k1</literal>,..<literal>kn</literal> peuvent être :
+                </term>
+                <listitem>
+                  <variablelist>
+                    <varlistentry>
+                      <term>un nombre réel positif à valeur entière</term>
+                      <listitem>
+                        <para/>
+                      </listitem>
+                    </varlistentry>
+                    <varlistentry>
+                      <term>un polynôme</term>
+                      <listitem>
+                        <para>un polynôme, interprété comme
+                          <literal>horner(ki,m)</literal> ou <literal>m</literal> est la
+                          taille de la sous-liste correspondante.
+                        </para>
+                      </listitem>
+                    </varlistentry>
+                    <varlistentry>
+                      <term>une chaîne de caractères</term>
+                      <listitem>
+                        <para>associée à un nom d'entrée de sous-liste</para>
+                      </listitem>
+                    </varlistentry>
+                  </variablelist>
+                </listitem>
+              </varlistentry>
+            </variablelist>
+            <para>Quand le chemin désigne plusieurs termes d'une liste
+              l'instruction doit avoir autant de termes dans la liste des
+              arguments du membre de gauche que le nombre de termes sélectionnés.
+              Mais si la syntaxe d'extraction est utilisée dans les arguments
+              d'entrée d'une fonction, chaque terme renvoyé est ajouté aux
+              arguments d'entrée.
+            </para>
+            <para>
+              Notez que <literal>l(list())</literal> est identique à
+              <literal>l</literal>.
+            </para>
+        </refsect3>
+        <refsect3>
+            <title>Remarques</title>
+            <para>Pour les matrices rationnelles et les systèmes dynamiques linéaires
+                stockés sous forme de représentation d'état, la syntaxe
+                <literal>x(i)</literal> ne doit pas être utilisée pour l'extraction des
+                éléments d'un vecteur, à cause de la confusion possible avec l'extraction
+                des éléments de liste. La syntaxe <literal>x(1,j)</literal> où
+                <literal>x(i,1)</literal> doit être utilisée dans ce cas.
+            </para>
+        </refsect3>
     </refsection>
     <refsection>
         <title>Exemples</title>
+        <para>
+            Cas des matrices :
+        </para>
         <programlisting role="example"><![CDATA[
-// CAS DES MATRICES
-a=[1 2 3;4 5 6]
+a = [1 2 3;4 5 6]
 a(1,2)
 a([1 1],2)
 a(:,1)
-a(:,3:-1:1)
+a(:, 3:-1:1)
 a(1)
 a(6)
 a(:)
 a([%t %f %f %t])
-a([%t %f],[2 3])
-a(1:2,$-1)
+a([%t %f], [2 3])
+a(1:2, $-1)
 a($:-1:1,2)
 a($)
 //
-x='test'
+x = 'test'
 x([1 1;1 1;1 1])
 //
-b=[1/%s,(%s+1)/(%s-1)]
+b = [1/%s, (%s+1)/(%s-1)]
 b(1,1)
 b(1,$)
 b(2) // le numérateur
-// CAS des LISTES (types LIST et TLIST)
-l=list(1,'qwerw',%s)
+     ]]></programlisting>
+        <para>
+            Cas des listes simples et des listes typées tlist :
+        </para>
+        <programlisting role="example"><![CDATA[
+l = list(1,'qwerw',%s)
 l(1)
-[a,b]=l([3 2])
+[a,b] = l([3 2])
 l($)
-x=tlist(l(2:3)) // construction d'une TLIST avec les deux derniers termes de l
+x = tlist(l(2:3))  // construction d'une TLIST avec les deux derniers termes de l
 //
-dts=list(1,tlist(['x';'a';'b'],10,[2 3]));
+dts = list(1, tlist(['x';'a';'b'],10,[2 3]));
 dts(2)('a')
 dts(2)('b')(1,2)
-[a,b]=dts(2)(['a','b'])
- ]]></programlisting>
+[a,b] = dts(2)(['a','b'])
+     ]]></programlisting>
     </refsection>
     <refsection role="see also">
         <title>Voir aussi</title>
         <simplelist type="inline">
             <member>
+                <link linkend="insertion">insertion</link>
+            </member>
+            <member>
+                <link linkend="colon">colon</link>
+            </member>
+            <member>
                 <link linkend="find">find</link>
             </member>
             <member>
index b76838d..5b978d4 100644 (file)
@@ -1,5 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<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="fr" xml:id="insertion">
+<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="fr" xml:id="insertion">
     <refnamediv>
         <refname>insertion</refname>
         <refpurpose>insertion/modification dans une
     </refsection>
     <refsection>
         <title>Description</title>
-        <variablelist>
-            <varlistentry>
-                <term>CAS DES MATRICES</term>
+        <refsect3>
+            <title>Cas des matrices</title>
+            <para>
+              Si  <literal>x</literal> est un tableau <literal>i</literal> et <literal>j</literal> peuvent être :
+            </para>
+            <variablelist>
+              <varlistentry>
+                <term>Des scalaires, vecteurs ou matrices</term>
                 <listitem>
-                    <para/>
-                    <para>
-                        Si  <literal>x</literal> est un tableau <literal>i</literal> et <literal>j</literal> peuvent être :
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>Des scalaires, vecteurs ou matrices</term>
-                            <listitem>
-                                <para>Dans ce cas, les valeurs données en
-                                    indices doivent être strictement positives. Seules les parties
-                                    entières sont prises en compte.
-                                </para>
-                                <itemizedlist>
-                                    <listitem>
-                                        <para>
-                                            Si <literal>a</literal> est une matrice de dimensions
-                                            <literal>(size(i,'*'),size(j,'*'))</literal>
-                                            <literal>x(i,j)=a</literal> renvoie une nouvelle matrice
-                                            <literal>x</literal> telle que <literal>x(int(i(l)),int(j(k)))=a(l,k)
-                                            </literal>
-                                            pour <literal>l</literal> variant de 1 à
-                                            <literal>size(i,'*')</literal> et <literal>k</literal> variant de
-                                            1 à <literal>size(j,'*')</literal>, les autres composantes
+                  <para>Dans ce cas, les valeurs données en
+                    indices doivent être strictement positives. Seules les parties
+                    entières sont prises en compte.
+                  </para>
+                  <itemizedlist>
+                    <listitem>
+                      <para>
+                        Si <literal>a</literal> est une matrice de dimensions
+                        <literal>(size(i,'*'),size(j,'*'))</literal>
+                        <literal>x(i,j)=a</literal> renvoie une nouvelle matrice
+                        <literal>x</literal> telle que <literal>x(int(i(l)),int(j(k)))=a(l,k)
+                        </literal>
+                        pour <literal>l</literal> variant de 1 à
+                        <literal>size(i,'*')</literal> et <literal>k</literal> variant de
+                        1 à <literal>size(j,'*')</literal>, les autres composantes
 
-                                            initiales de <literal>x</literal> sont inchangées.
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            Si <literal>a</literal> est un scalaire
-                                            <literal>x(i,j)=a</literal> renvoie une nouvelle matrice
-                                            <literal>x</literal> telle que <literal>x(int(i(l)),int(j(k)))=a </literal>
-                                            pour <literal>l</literal> variant de 1 à
-                                            <literal>size(i,'*')</literal> et <literal>k</literal> variant de
-                                            1 à <literal>size(j,'*')</literal>, les autres composantes
-                                            initiales de <literal>x</literal> sont inchangées.
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            Si la valeur maximum de <literal>i</literal> ou
-                                            <literal>j</literal> dépasse la dimension correspondante de
-                                            <literal>x</literal>, alors <literal>x</literal> est au préalable agrandie
-                                            aux dimensions adéquates en stockant des zéros pour les matrices
-                                            standard, des chaînes vides pour les matrices de chaînes de
-                                            caractères ou la valeur %F pour les matrices booléennes.
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            <literal>x(i,j)=[]</literal> détruit les lignes
-                                            spécifiées par <literal>i</literal> si <literal>j</literal> désigne toutes
-                                            les colonnes de <literal>x</literal> ou détruit les colonnes
-                                            spécifiées par <literal>j</literal> si <literal>i</literal> désigne toutes
-                                            les lignes de <literal>x</literal>. Dans tous les autres cas
-                                            <literal>x(i,j)=[]</literal> produit une erreur.
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            <literal>x(i)=a</literal> où <literal>a</literal> est un
-                                            vecteur renvoie une nouvelle matrice <literal>x</literal> telle que
-                                            <literal>x(int(i(l)))=a(l)</literal> pour <literal>l</literal> variant de 1
-                                            à <literal>size(i,'*')</literal> , les autres composantes
-                                            initiales de <literal>x</literal> sont inchangées.
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            <literal>x(i)=a</literal> où <literal>a</literal> est un
-                                            scalaire, renvoie une nouvelle matrice <literal>x</literal> telle que
-                                            <literal>x(int(i(l)))=a</literal> pour <literal>l</literal> variant de 1 à
-                                            <literal>size(i,'*')</literal> , les autres composantes
-                                            initiales de <literal>x</literal> sont inchangées.
-                                        </para>
-                                        <para>
-                                            Si la valeur maximum de <literal>i</literal> dépasse
-                                            <literal>size(x,1)</literal>, <literal>x</literal> est au préalable agrandie
-                                            aux dimensions adéquates en stockant des zéros pour les matrices
-                                            standard, des chaînes vides pour les matrices de chaînes de
-                                            caractères ou la valeur %F pour les matrices booléennes.
-                                        </para>
-                                        <variablelist>
-                                            <varlistentry>
-                                                <term>Si</term>
-                                                <listitem>
-                                                    <para>
-                                                        <literal>x</literal> est une matrice 1 x 1 <literal>a</literal> peut
-                                                        être un vecteur ligne (resp. colonne) de dimension
-                                                        <literal>size(i,'*')</literal>. La matrice
-                                                        <literal>x</literal> obtenue est un vecteur ligne
-                                                        (resp. colonne)
-                                                    </para>
-                                                </listitem>
-                                            </varlistentry>
-                                            <varlistentry>
-                                                <term>Si</term>
-                                                <listitem>
-                                                    <para>
-                                                        <literal>x</literal> est un vecteur
-                                                        ligne (resp. colonne) <literal>a</literal> doit être un vecteur
-                                                        ligne (resp. colonne) de dimension
-                                                        <literal>size(i,'*')</literal>
-                                                    </para>
-                                                </listitem>
-                                            </varlistentry>
-                                            <varlistentry>
-                                                <term>Si</term>
-                                                <listitem>
-                                                    <para>
-                                                        <literal>x</literal> est une matrice
-                                                        en général <literal>a</literal> doit être un vecteur ligne ou
-                                                        colonne de dimension <literal>size(i,'*')</literal> et
-                                                        la valeur maximum de<literal>i</literal> ne peut dépasser
-                                                        <literal>size(x,'*')</literal>,
-                                                    </para>
-                                                </listitem>
-                                            </varlistentry>
-                                        </variablelist>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            <literal>x(i)=[]</literal> supprime les termes
-
-
-                                            spécifiés par <literal>i</literal>.
-                                        </para>
-                                    </listitem>
-                                </itemizedlist>
-                            </listitem>
-                        </varlistentry>
+                        initiales de <literal>x</literal> sont inchangées.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        Si <literal>a</literal> est un scalaire
+                        <literal>x(i,j)=a</literal> renvoie une nouvelle matrice
+                        <literal>x</literal> telle que <literal>x(int(i(l)),int(j(k)))=a </literal>
+                        pour <literal>l</literal> variant de 1 à
+                        <literal>size(i,'*')</literal> et <literal>k</literal> variant de
+                        1 à <literal>size(j,'*')</literal>, les autres composantes
+                        initiales de <literal>x</literal> sont inchangées.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        Si la valeur maximum de <literal>i</literal> ou
+                        <literal>j</literal> dépasse la dimension correspondante de
+                        <literal>x</literal>, alors <literal>x</literal> est au préalable agrandie
+                        aux dimensions adéquates en stockant des zéros pour les matrices
+                        standard, des chaînes vides pour les matrices de chaînes de
+                        caractères ou la valeur %F pour les matrices booléennes.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>x(i,j)=[]</literal> détruit les lignes
+                        spécifiées par <literal>i</literal> si <literal>j</literal> désigne toutes
+                        les colonnes de <literal>x</literal> ou détruit les colonnes
+                        spécifiées par <literal>j</literal> si <literal>i</literal> désigne toutes
+                        les lignes de <literal>x</literal>. Dans tous les autres cas
+                        <literal>x(i,j)=[]</literal> produit une erreur.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>x(i)=a</literal> où <literal>a</literal> est un
+                        vecteur renvoie une nouvelle matrice <literal>x</literal> telle que
+                        <literal>x(int(i(l)))=a(l)</literal> pour <literal>l</literal> variant de 1
+                        à <literal>size(i,'*')</literal> , les autres composantes
+                        initiales de <literal>x</literal> sont inchangées.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>x(i)=a</literal> où <literal>a</literal> est un
+                        scalaire, renvoie une nouvelle matrice <literal>x</literal> telle que
+                        <literal>x(int(i(l)))=a</literal> pour <literal>l</literal> variant de 1 à
+                        <literal>size(i,'*')</literal> , les autres composantes
+                        initiales de <literal>x</literal> sont inchangées.
+                      </para>
+                      <para>
+                        Si la valeur maximum de <literal>i</literal> dépasse
+                        <literal>size(x,1)</literal>, <literal>x</literal> est au préalable agrandie
+                        aux dimensions adéquates en stockant des zéros pour les matrices
+                        standard, des chaînes vides pour les matrices de chaînes de
+                        caractères ou la valeur %F pour les matrices booléennes.
+                      </para>
+                      <variablelist>
                         <varlistentry>
-                            <term>Le : symbole</term>
-                            <listitem>
-                                <para>
-                                    Le symbole <literal> : </literal> signifiant "tous les éléments".
-                                </para>
-                                <itemizedlist>
-                                    <listitem>
-                                        <para>
-                                            <literal>x(i,:)=a</literal> est interprété comme
-
-                                            <literal>x(i,1:size(x,2))=a</literal>
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            <literal>x(:,j)=a</literal> est interprété comme
-                                            <literal>x(1:size(x,1),j)=a</literal>
-                                        </para>
-                                    </listitem>
-                                    <listitem>
-                                        <para>
-                                            <literal>x(:)=a</literal> renvoie dans
-                                            <literal>x</literal> la matrice <literal>a</literal> remise en forme en
-                                            accord avec les dimensions de
-                                            x. <literal>size(x,'*')</literal> doit être égal
-                                            à<literal>size(a,'*')</literal>
-                                        </para>
-                                    </listitem>
-                                </itemizedlist>
-                            </listitem>
+                          <term>Si</term>
+                          <listitem>
+                            <para>
+                              <literal>x</literal> est une matrice 1 x 1 <literal>a</literal> peut
+                              être un vecteur ligne (resp. colonne) de dimension
+                              <literal>size(i,'*')</literal>. La matrice
+                              <literal>x</literal> obtenue est un vecteur ligne
+                              (resp. colonne)
+                            </para>
+                          </listitem>
                         </varlistentry>
                         <varlistentry>
-                            <term>Vecteurs de booléens</term>
-                            <listitem>
-                                <para>  Si un indice
-
-                                    (<literal>i</literal> ou <literal>j</literal> ) est un vecteur de booléens, il
-                                    est interprété comme <literal>find(i)</literal> ou <literal>find(j)</literal>,
-                                    respectivement.
-                                </para>
-                            </listitem>
+                          <term>Si</term>
+                          <listitem>
+                            <para>
+                              <literal>x</literal> est un vecteur
+                              ligne (resp. colonne) <literal>a</literal> doit être un vecteur
+                              ligne (resp. colonne) de dimension
+                              <literal>size(i,'*')</literal>
+                            </para>
+                          </listitem>
                         </varlistentry>
                         <varlistentry>
-                            <term>Polynomes</term>
-                            <listitem>
-                                <para>
-                                    Si un indice (<literal>i</literal> ou
-                                    <literal>j</literal> ) est un vecteur de polynômes ou de polynômes
-                                    implicites, il est interprété comme <literal>horner(i,m)</literal> ou
-                                    <literal>horner(j,n)</literal>, respectivement, où <literal>m</literal> et
-                                    <literal>n</literal> sont les dimensions de <literal>x</literal> associées.
-                                    Même si cette fonctionnalité marche pour tous les polynômes, il
-                                    est recommandé d'utiliser des polynômes dans <literal>$</literal>
-                                    par souci de lisibilité.
-                                </para>
-                            </listitem>
+                          <term>Si</term>
+                          <listitem>
+                            <para>
+                              <literal>x</literal> est une matrice
+                              en général <literal>a</literal> doit être un vecteur ligne ou
+                              colonne de dimension <literal>size(i,'*')</literal> et
+                              la valeur maximum de<literal>i</literal> ne peut dépasser
+                              <literal>size(x,'*')</literal>,
+                            </para>
+                          </listitem>
                         </varlistentry>
-                    </variablelist>
+                      </variablelist>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>x(i)=[]</literal> supprime les termes
+
+
+                        spécifiés par <literal>i</literal>.
+                      </para>
+                    </listitem>
+                  </itemizedlist>
                 </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>CAS DES LISTES</term>
+              </varlistentry>
+              <varlistentry>
+                <term>Le : symbole</term>
                 <listitem>
-                    <itemizedlist>
-                        <listitem>
-                            <para>
-                                S'ils sont présents les <literal>ki</literal> donnent le chemin
-                                vers un terme d'une sous-liste de la liste
-                                <literal>l</literal>. Ils permettent de faire une insertion récursive
-                                directe sans utiliser de variable intermédiaire.  Les instructions
-                                <literal>l(k1)...(kn)(i)=a</literal> et
-                                <literal>l(list(k1,...,kn,i)=a)</literal> sont interprétées comme :
-                            </para>
-                            <para>
-                                <literal>lk1 = l(k1)</literal>
-                                <literal> ..  = ..  </literal>
-                            </para>
-                            <para>
-                                <literal>lkn =   lkn-1(kn)</literal>
-                            </para>
-                            <para>
-                                <literal>lkn(i) = a</literal>
-                                <literal>lkn-1(kn) =lkn</literal>
-                                <literal> ..  = ..</literal>
-                            </para>
-                            <para>
-                                les instructions<literal>l(k1)...(kn)(i,j)=a</literal> et
-                                <literal>l(list(k1,...,kn,list(i,j))=a</literal> sont interprétées
-                                comme:
-                            </para>
-                            <para>
-                                <literal>lk1 = l(k1)</literal>
-                                <literal> ..  = ..  </literal>
-                            </para>
-                            <para>
-                                <literal>lkn =lkn-1(kn)</literal>
-                                <literal>lkn(i,j) = a</literal>
-                            </para>
-                            <para>
-                                <literal>lkn-1(kn) = lkn</literal>
-                                <literal> ..  = ..  </literal>
-                            </para>
-                            <para>
-                                <literal>l(k1) = lk1</literal>
-                            </para>
-                        </listitem>
-                        <listitem>
-                            <para>
-                                <literal>i</literal> peut être :
-                            </para>
-                            <itemizedlist>
-                                <listitem>
-                                    <para>un scalaire réel positif (seule sa partie entière est prise en compte).
-                                        <literal>l(0)=a</literal> ajoute un terme "à gauche"
-                                        de la liste <literal>l(i)=a</literal> affecte <literal>a</literal> au
-                                        terme <literal>i</literal> de la liste <literal>l</literal>. Si
-                                        <literal>i&gt;size(l)</literal>, <literal>l</literal> est
-                                        préalablement agrandie et les termes créés sont de type
-                                        non-défini.  <literal>l(i)=null()</literal> supprime le terme
-                                        <literal>i</literal>th de la liste.
-                                    </para>
-                                </listitem>
-                                <listitem>
-                                    <para>
-                                        un polynôme. Si <literal>i</literal> est un
+                  <para>
+                    Le symbole <literal> : </literal> signifiant "tous les éléments".
+                  </para>
+                  <itemizedlist>
+                    <listitem>
+                      <para>
+                        <literal>x(i,:)=a</literal> est interprété comme
 
-                                        vecteur de polynômes ou de polynômes implicites il est
-                                        interprété comme <literal>horner(i,m)</literal> où
-                                        <literal>m=size(l)</literal>. Même si cette fonctionnalité marche
-                                        pour tous les polynômes, il est recommandé d'utiliser
-                                        des polynômes dans <literal>$</literal> par souci de lisibilité.
-                                    </para>
-                                </listitem>
-                            </itemizedlist>
-                        </listitem>
-                        <listitem>
-                            <para>
-                                <literal>k1,..kn</literal> peuvent être :
-                            </para>
-                            <itemizedlist>
-                                <listitem>
-                                    <para>un polynôme, interprété comme
-                                        <literal>horner(ki,m)</literal> ou <literal>m</literal> est la taille de
-                                        la sous-liste correspondante.
-                                    </para>
-                                </listitem>
-                                <listitem>
-                                    <para>une chaîne de caractères associée à un nom
+                        <literal>x(i,1:size(x,2))=a</literal>
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>x(:,j)=a</literal> est interprété comme
+                        <literal>x(1:size(x,1),j)=a</literal>
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>x(:)=a</literal> renvoie dans
+                        <literal>x</literal> la matrice <literal>a</literal> remise en forme en
+                        accord avec les dimensions de
+                        x. <literal>size(x,'*')</literal> doit être égal
+                        à<literal>size(a,'*')</literal>
+                      </para>
+                    </listitem>
+                  </itemizedlist>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>Vecteurs de booléens</term>
+                <listitem>
+                  <para>  Si un indice
 
-                                        d'entrée de sous-liste.
-                                    </para>
-                                </listitem>
-                            </itemizedlist>
-                        </listitem>
-                    </itemizedlist>
+                    (<literal>i</literal> ou <literal>j</literal> ) est un vecteur de booléens, il
+                    est interprété comme <literal>find(i)</literal> ou <literal>find(j)</literal>,
+                    respectivement.
+                  </para>
                 </listitem>
-            </varlistentry>
-        </variablelist>
+              </varlistentry>
+              <varlistentry>
+                <term>Polynomes</term>
+                <listitem>
+                  <para>
+                    Si un indice (<literal>i</literal> ou
+                    <literal>j</literal> ) est un vecteur de polynômes ou de polynômes
+                    implicites, il est interprété comme <literal>horner(i,m)</literal> ou
+                    <literal>horner(j,n)</literal>, respectivement, où <literal>m</literal> et
+                    <literal>n</literal> sont les dimensions de <literal>x</literal> associées.
+                    Même si cette fonctionnalité marche pour tous les polynômes, il
+                    est recommandé d'utiliser des polynômes dans <literal>$</literal>
+                    par souci de lisibilité.
+                  </para>
+                </listitem>
+              </varlistentry>
+            </variablelist>
+        </refsect3>
+        <refsect3>
+            <title>Cas des listes</title>
+            <itemizedlist>
+              <listitem>
+                <para>
+                  S'ils sont présents les <literal>ki</literal> donnent le chemin
+                  vers un terme d'une sous-liste de la liste
+                  <literal>l</literal>. Ils permettent de faire une insertion récursive
+                  directe sans utiliser de variable intermédiaire.  Les instructions
+                  <literal>l(k1)...(kn)(i)=a</literal> et
+                  <literal>l(list(k1,...,kn,i)=a)</literal> sont interprétées comme :
+                </para>
+                <para>
+                  <literal>lk1 = l(k1)</literal>
+                  <literal> ..  = ..  </literal>
+                </para>
+                <para>
+                  <literal>lkn =   lkn-1(kn)</literal>
+                </para>
+                <para>
+                  <literal>lkn(i) = a</literal>
+                  <literal>lkn-1(kn) =lkn</literal>
+                  <literal> ..  = ..</literal>
+                </para>
+                <para>
+                  les instructions<literal>l(k1)...(kn)(i,j)=a</literal> et
+                  <literal>l(list(k1,...,kn,list(i,j))=a</literal> sont interprétées
+                  comme:
+                </para>
+                <para>
+                  <literal>lk1 = l(k1)</literal>
+                  <literal> ..  = ..  </literal>
+                </para>
+                <para>
+                  <literal>lkn =lkn-1(kn)</literal>
+                  <literal>lkn(i,j) = a</literal>
+                </para>
+                <para>
+                  <literal>lkn-1(kn) = lkn</literal>
+                  <literal> ..  = ..  </literal>
+                </para>
+                <para>
+                  <literal>l(k1) = lk1</literal>
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  <literal>i</literal> peut être :
+                </para>
+                <itemizedlist>
+                  <listitem>
+                    <para>un scalaire réel positif (seule sa partie entière est prise en compte).
+                      <literal>l(0)=a</literal> ajoute un terme "à gauche"
+                      de la liste <literal>l(i)=a</literal> affecte <literal>a</literal> au
+                      terme <literal>i</literal> de la liste <literal>l</literal>. Si
+                      <literal>i&gt;size(l)</literal>, <literal>l</literal> est
+                      préalablement agrandie et les termes créés sont de type
+                      non-défini.  <literal>l(i)=null()</literal> supprime le terme
+                      <literal>i</literal>th de la liste.
+                    </para>
+                  </listitem>
+                  <listitem>
+                    <para>
+                      un polynôme. Si <literal>i</literal> est un
+
+                      vecteur de polynômes ou de polynômes implicites il est
+                      interprété comme <literal>horner(i,m)</literal> où
+                      <literal>m=size(l)</literal>. Même si cette fonctionnalité marche
+                      pour tous les polynômes, il est recommandé d'utiliser
+                      des polynômes dans <literal>$</literal> par souci de lisibilité.
+                    </para>
+                  </listitem>
+                </itemizedlist>
+              </listitem>
+              <listitem>
+                <para>
+                  <literal>k1,..kn</literal> peuvent être :
+                </para>
+                <itemizedlist>
+                  <listitem>
+                    <para>un polynôme, interprété comme
+                      <literal>horner(ki,m)</literal> ou <literal>m</literal> est la taille de
+                      la sous-liste correspondante.
+                    </para>
+                  </listitem>
+                  <listitem>
+                    <para>une chaîne de caractères associée à un nom
+
+                      d'entrée de sous-liste.
+                    </para>
+                  </listitem>
+                </itemizedlist>
+              </listitem>
+            </itemizedlist>
+        </refsect3>
+        <refsect3>
+            <title>Remarque</title>
+            <para>
+                Pour les matrices rationnelles et les systèmes dynamiques
+                linéaires stockés sous forme de représentation d'état, la
+                syntaxe <literal>x(i)</literal> ne doit pas être utilisée pour
+                l'insertion des éléments d'un vecteur, à cause de la
+                confusion possible avec l'insertion des éléments de liste. La
+                syntaxe <literal>x(1,j)</literal> où <literal>x(i,1)</literal> doit être
+                utilisée dans ce cas.
+            </para>
+        </refsect3>
     </refsection>
     <refsection>
-        <title>Remarque</title>
+        <title>Exemples</title>
         <para>
-            Pour les matrices rationnelles et les systèmes dynamiques
-            linéaires stockés sous forme de représentation d'état, la
-            syntaxe <literal>x(i)</literal> ne doit pas être utilisée pour
-            l'insertion des éléments d'un vecteur, à cause de la
-            confusion possible avec l'insertion des éléments de liste. La
-            syntaxe <literal>x(1,j)</literal> où <literal>x(i,1)</literal> doit être
-            utilisée dans ce cas.
+            Cas des matrices :
         </para>
-    </refsection>
-    <refsection>
-        <title>Exemples</title>
         <programlisting role="example"><![CDATA[
-// CAS DES MATRICES
-a=[1 2 3;4 5 6]
-a(1,2)=10
-a([1 1],2)=[-1;-2]
-a(:,1)=[8;5]
-a(1,3:-1:1)=[77 44 99]
-a(1)=%s
-a(6)=%s+1
-a(:)=1:6
-a([%t %f],1)=33
-a(1:2,$-1)=[2;4]
-a($:-1:1,1)=[8;7]
-a($)=123
-a(1,%pi)=1 //équivalent à a(1,3)=1
+a = [1 2 3 ; 4 5 6]
+a(1,2) = 10
+a([1 1],2) = [-1;-2]
+a(:,1) = [8;5]
+a(1,3:-1:1) = [77 44 99]
+a(1) = %s
+a(6) = %s + 1
+a(:) = 1:6
+a([%t %f],1) = 33
+a(1:2,$-1) = [2 ; 4]
+a($:-1:1,1) = [8 ; 7]
+a($) = 123
+a(1,%pi) = 1 // équivalent à a(1,3)=1
 //
-x='test'
-x([4 5])=['4','5']
+x = 'test'
+x([4 5]) = ['4','5']
 //
-b=[1/%s,(%s+1)/(%s-1)]
-b(1,1)=0
-b(1,$)=b(1,$)+1
-b(2)=[1 2] // le numérateur
-// CAS des LISTES (types LIST et TLIST)
-l=list(1,'qwerw',%s)
-l(1)='Changed'
-l(0)='Added'
-l(%pi)=1 //équivalent à l(3)=1
-l(6)=['one more';'added']
+b = [1/%s, (%s+1)/(%s-1)]
+b(1,1) = 0
+b(1,$) = b(1,$)+1
+b(2) = [1 2] // le numérateur
+     ]]></programlisting>
+        <para>
+            Cas des listes simples ou tlist :
+        </para>
+        <programlisting role="example"><![CDATA[
+l = list(1,'qwerw',%s)
+l(1) = 'Changed'
+l(0) = 'Added'
+l(%pi) = 1  // équivalent à l(3)=1
+l(6) = ['one more';'added']
 //
 //
-dts=list(1,tlist(['x';'a';'b'],10,[2 3]));
-dts(2)('a')=33
-dts(2)('b')(1,2)=-100
- ]]></programlisting>
+dts = list(1, tlist(['x';'a';'b'],10,[2 3]));
+dts(2)('a') = 33
+dts(2)('b')(1,2) = -100
+     ]]></programlisting>
     </refsection>
     <refsection role="see also">
         <title>Voir aussi</title>
         <simplelist type="inline">
             <member>
+                <link linkend="extraction">extraction</link>
+            </member>
+            <member>
+                <link linkend="colon">colon</link>
+            </member>
+            <member>
                 <link linkend="find">find</link>
             </member>
             <member>
@@ -418,9 +426,6 @@ dts(2)('b')(1,2)=-100
             <member>
                 <link linkend="parentheses">parentheses</link>
             </member>
-            <member>
-                <link linkend="extraction">extraction</link>
-            </member>
         </simplelist>
     </refsection>
 </refentry>
index 1b3b96a..6955eeb 100644 (file)
  * along with this program.
  *
  -->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="cumsum" xml:lang="fr">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
+          xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
+          xml:id="cumsum" xml:lang="fr">
     <refnamediv>
         <refname>cumsum</refname>
-        <refpurpose>somme cumulative des éléments d'un tableau.</refpurpose>
+        <refpurpose>sommes partielles cumulatives des éléments d'un tableau.</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Séquence d'appel</title>
-        <synopsis>y=cumsum(x)
-            y=cumsum(x,orientation)
-            y=cumsum(x,outtype)
-            y=cumsum(x,orientation,outtype)
+        <synopsis>
+            y = cumsum(x)
+            y = cumsum(x, outtype)
+            y = cumsum(x, orientation)
+            y = cumsum(x, orientation, outtype)
         </synopsis>
     </refsynopsisdiv>
 
     <refsection role="parameters">
-        <title>Paramètres</title>
+        <title>Arguments</title>
         <variablelist>
             <varlistentry>
                 <term>x</term>
                 <listitem>
-                    <para>un tableau de réels, de complexes, de booléens, de
-                        polynômes ou de fractions rationnelles.
+                    <para>
+                        tableau de booléens, de nombres entiers, réels, ou complexes, de
+                        polynômes, ou de fractions rationnelles. Les hypermatrices ou les matrices
+                        booléennes ou numériques creuses sont acceptées.
                     </para>
                 </listitem>
             </varlistentry>
                 <term>orientation</term>
                 <listitem>
                     <para>
+                        direction selon laquelle les sommes partielles cumulatives sont calculées :
                         Cet argument peut être
                     </para>
                     <itemizedlist>
                         <listitem>
-                            <para>ou une chaîne de caractères pouvant avoir comme
-                                valeurs: <literal>"*"</literal>,
+                            <para>le caractère <literal>"*"</literal>,
                                 <literal>"r"</literal>, <literal>"c"</literal> ou
-                                <literal>"m"</literal>
+                                <literal>"m"</literal>.
                             </para>
                         </listitem>
                         <listitem>
-                            <para>ou bien un nombre à valeur positive entière</para>
+                            <para>
+                              un nombre entier 1 ≤ orientation ≤ ndims(x) : n° de la dimension
+                              selon laquelle les sommes partielles cumulatives directionnelles doivent
+                              être calculées. 1 et "r", ou 2 et "c", sont equivalents.
+                            </para>
                         </listitem>
                     </itemizedlist>
                 </listitem>
                 <term>outtype</term>
                 <listitem>
                     <para>
-                        une chaîne de caractères pouvant prendre les valeurs <literal>"native"</literal> ou <literal>"double"</literal>.
+                        mot <literal>"native"</literal> ou <literal>"double"</literal>.
+                        <literal>"double"</literal> convertit préalablement en nombres décimaux
+                        les booléens ou les entiers fournis.
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>y</term>
                 <listitem>
-                    <para> un scalaire ou un tableau</para>
+                    <para>tableau de tailles identiques à celles de <varname>x</varname>.</para>
                 </listitem>
             </varlistentry>
         </variablelist>
     <refsection>
         <title>Description</title>
         <para>
-            Renvoie la somme cumulée des éléments d'un tableau.
-            Pour un tableau <term>x</term>,
-            <literal>y=cumsum(x)</literal> renvoie une matrice <term>y</term>
-            de la même taille que <term>x</term>.
-            La valeur <literal>y(i)</literal> est la somme de tous les éléments de <literal>x(1:i)</literal>, <emphasis role="italic">i.e.</emphasis> :
+            <emphasis role="bold">y = cumsum(x)</emphasis> calcule et fournit les sommes partielles
+            cumulatives <literal>y(i)=sum(x(1:i))</literal>,
+            <emphasis role="italic">i.e.</emphasis> :
         </para>
         <para>
-            <latex><![CDATA[ y(i) = \sum_{k=1}^i x(k)]]></latex>
+            <latex alt="y(i) = ∑u=1→i x(u)"><![CDATA[ y(i) = \sum_{u=1}^i x(u)]]></latex>
         </para>
         <para>
-            <literal>y=cumsum(x,orientation)</literal> retourne dans
-            <term>y</term> la somme cumulée des éléments de
-            <term>x</term> le long de la dimension donnée par le
-            paramètre <term>orientation</term>:
+            <emphasis role="bold">y = cumsum(x, orientation)</emphasis> calcule et fournit dans
+            <term>y</term> les sommes partielles cumulatives des éléments de
+            <term>x</term> selon la direction spécifiée par <term>orientation</term> :
         </para>
         <itemizedlist>
             <listitem>
                     Si <term>orientation</term> est égal à 1 ou "r" alors :
                 </para>
                 <para>
-                    <latex><![CDATA[ y(\mathbf{l},j) = \sum_{\mathbf{i}=1}^l x(\mathbf{i},j)]]></latex>
+                    <latex alt="y(i,j) = ∑u=1→i x(u,j)"><![CDATA[
+                        y(\mathbf{i},j) = \sum_{u=1}^{\mathbf{i}} x(\mathbf{u},j)   ]]>
+                    </latex>, ou pour un tableau N-Dimensionnel :
                 </para>
-                <para>ou </para>
                 <para>
-                    <latex><![CDATA[ y(\mathbf{l},j,k,\ldots) = \sum_{\mathbf{i}=1}^l x(\mathbf{i},j,k,\ldots)]]></latex>
+                    <latex alt="y(i,j,k,…) = ∑u=1→i x(u,j,k,…)"><![CDATA[
+                        y(\mathbf{i},j,k,\ldots) = \sum_{u=1}^{\mathbf{i}} x(\mathbf{u},j,k,\ldots)  ]]>
+                    </latex>
                 </para>
             </listitem>
             <listitem>
                     Si <term>orientation</term> est égal à 2 ou "c" alors :
                 </para>
                 <para>
-                    <latex><![CDATA[ y(i,\mathbf{l}) = \sum_{\mathbf{j}=1}^l x(i,{\mathbf{j})]]></latex>
+                    <latex alt="y(i,j) = ∑u=1→j x(i,u)"><![CDATA[
+                        y(i,\mathbf{j}) = \sum_{u=1}^{\mathbf{j}} x(i,{\mathbf{u})  ]]>
+                    </latex>, ou pour un tableau N-Dimensionnel :
                 </para>
-                <para> ou </para>
                 <para>
-                    <latex><![CDATA[ y(i,\mathbf{l},k,\ldots) = \sum_{\mathbf{j}=1}^l x(i,\mathbf{j},k,\ldots)]]></latex>
+                    <latex alt="y(i,j,k,…) = ∑u=1→j x(i,u,k,…)"><![CDATA[
+                        y(i,\mathbf{j},k,\ldots) = \sum_{u=1}^{\mathbf{j}} x(i,\mathbf{u},k,\ldots) ]]>
+                    </latex>
                 </para>
             </listitem>
             <listitem>
                     Si <term>orientation</term> est égal à n alors :
                 </para>
                 <para>
-                    <latex><![CDATA[ y(i_1,\ldots,i_{n-1},\mathbf{l},i_{n+1},\ldots) = \sum_{\mathbf{i_n}=1}^l x(i_1,\ldots,i_{n-1},\mathbf{i_n},i_{n+1},\ldots)]]></latex>
+                    <latex alt="y(i₁,…,iₙ₋₁, iₙ,iₙ₊₁,…) = ∑u=1…iₙ  x(i₁,…,iₙ₋₁, u,iₙ₊₁,…)"><![CDATA[
+                        y(i_1,\ldots,i_{n-1},\mathbf{i_{n}},i_{n+1},\ldots) =
+                        \sum_{u=1}^{\mathbf{i_n}} x(i_1,\ldots,i_{n-1},\mathbf{u},i_{n+1},\ldots) ]]>
+                    </latex>
                 </para>
             </listitem>
             <listitem>
                 <para>
-                    <literal>y=cumsum(x,"*")</literal> est équivalent à <literal>y=cumsum(x)</literal>
+                    <emphasis role="bold">y = cumsum(x,"*")</emphasis> est équivalent à
+                    <literal>y = cumsum(x)</literal>
                 </para>
             </listitem>
             <listitem>
                 <para>
-                    <literal>y=cumsum(x,"m")</literal> est équivalent à
-                    <literal>y=cumsum(x,orientation)</literal> où
-                    <term>orientation</term> est l'index de la première
-                    dimension de <term>x</term> qui est plus grande que
-                    1. Cette option est utilisé pour la compatibilité avec Matlab.
+                    <emphasis role="bold">y = cumsum(x, "m")</emphasis> est équivalent à
+                    <literal>y = cumsum(x, orientation)</literal>, où
+                    <term>orientation</term> est le n° de la première dimension de <term>x</term>
+                    plus grande que 1. Cette option est utilisé pour compatibilité avec Matlab.
                 </para>
             </listitem>
         </itemizedlist>
         </para>
         <itemizedlist>
             <listitem>
-                <para>Pour les matrices de doubles, de polynômes, de fractions rationnelles,
-                    l'évaluation est toujours effetuée sur des nombres à virgule flottante.
-                    Les options <literal>"double"</literal> ou <literal>"native"</literal> sont équivalentes
-                    (par défaut, <literal>outtype = "double"</literal>).
+                <para>
+                    Pour les matrices de nombres décimaux ou complexes, de polynômes, ou de
+                    fractions rationnelles, les calculs sont effectués en virgule flottante.
+                    Les options <literal>"double"</literal> ou <literal>"native"</literal>
+                    sont équivalentes.
                 </para>
             </listitem>
             <listitem>
                 <para>Pour les tableaux d'entiers,</para>
                 <para>
-                    si <literal>outtype="native"</literal>, le calcul est effectué sur des nombres entiers
-                    (modulo 2^b, où b est le nombre de bits utilisés).
+                    Par défaut ou si <literal>outtype="native"</literal>, les calculs sont
+                    effectués en arithmétique entière (modulo 2^b, où b est le nombre de bits utilisés).
                 </para>
                 <para>
-                    si <literal>outtype="double"</literal>, le calcul est effectué sur
-                    des nombres à virgule flottante.
-                </para>
-                <para>
-                    La valeur par défaut est <literal>outtype="native"</literal>
+                    Si <literal>outtype="double"</literal>, les calculs sont effectués après
+                    conversion en nombres décimaux, et les résultats sont fournis en entiers
+                    décimaux.
                 </para>
             </listitem>
             <listitem>
                 </para>
             </listitem>
         </itemizedlist>
-        <note>
-            Cette fonction s'applique avec les mêmes règles aux <link linkend="sparse">matrices creuses</link> et aux hypermatrices.
-        </note>
+        <warning>
+            Lorsque <varname>x</varname> est une matrice creuse, garder à l'esprit que la densité
+            de la matrice <varname>y</varname> résultante sera presque toujours proche de 100%.
+        </warning>
     </refsection>
     <refsection>
         <title>Exemples</title>
         <programlisting role="example"><![CDATA[
-A=[1,2;3,4];
+A = [1 , 2 ; 3 , 4];
 cumsum(A)
 cumsum(A,1)
 
-I=uint8([2 95 103;254 9 0])
+I = uint8([2 95 103;254 9 0])
 cumsum(I) //native evaluation
 cumsum(I,"double")
 cumsum(I,2,"double")
 
-s=poly(0,"s");
-P=[s,%i+s;s^2,1];
+s = poly(0,"s");
+P = [s, %i+s ; s^2, 1];
 cumsum(P),
 cumsum(P,2)
 
-B=[%t %t %f %f];
+B = [%t %t %f %f];
 cumsum(B) //evaluation in float
-cumsum(B,"native") //similar to or(B)
-
+cumsum(B, "native") //similar to or(B)
  ]]></programlisting>
     </refsection>
     <refsection role="see also">
index 41a2448..eed027c 100644 (file)
 <?xml version="1.0" encoding="UTF-8"?>
-
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="extraction" xml:lang="ja">
-
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
+          xmlns:scilab="http://www.scilab.org" xml:id="extraction" xml:lang="ja">
     <refnamediv>
-
         <refname>extraction</refname>
-
         <refpurpose>行列およびリストのエントリの展開</refpurpose>
-
     </refnamediv>
-
     <refsynopsisdiv>
-
         <title>呼出し手順</title>
-
         <synopsis>
-
             x(i)
-
             x(i,j)
-
             x(i,j,k,..)
-
-            [...]=l(i)
-
-            [...]=l(k1)...(kn)(i) または [...]=l(list(k1,...,kn,i))
-
+            [...] = l(i)
+            [...] = l(k1)...(kn)(i) または [...] = l(list(k1,...,kn,i))
             l(k1)...(kn)(i,j) または l(list(k1,...,kn,list(i,j))
-
         </synopsis>
-
     </refsynopsisdiv>
-
     <refsection>
-
         <title>引数</title>
-
         <variablelist>
-
             <varlistentry>
-
                 <term>x</term>
-
                 <listitem>
-
                     <para>任意の型の行列</para>
-
                 </listitem>
-
             </varlistentry>
-
             <varlistentry>
-
                 <term>l</term>
-
                 <listitem>
-
                     <para>リスト変数</para>
-
                 </listitem>
-
             </varlistentry>
-
             <varlistentry>
-
                 <term>i,j, k</term>
-
                 <listitem>
-
                     <para>添え字</para>
-
                 </listitem>
-
             </varlistentry>
-
             <varlistentry>
-
                 <term>k1,...kn</term>
-
                 <listitem>
-
                     <para>添え字</para>
-
                 </listitem>
-
             </varlistentry>
-
         </variablelist>
-
     </refsection>
-
     <refsection>
-
         <title>説明</title>
-
-        <variablelist>
-
-            <varlistentry>
-
-                <term>行列の場合</term>
-
+        <refsect3>
+            <title>行列の場合</title>
+            <para>
+              <literal>i</literal>, <literal>j</literal>,
+              <literal>k</literal>,.. は以下のようになります:
+            </para>
+            <variablelist>
+              <varlistentry>
+                <term>
+                  正の要素を有する実数のスカラーまたはベクトルまたは行列.
+                </term>
                 <listitem>
-
-                    <para>
-
-                        <literal>i</literal>, <literal>j</literal>,
-
-                        <literal>k</literal>,.. は以下のようになります:
-
-                    </para>
-
-                    <variablelist>
-
-                        <varlistentry>
-
-                            <term>
-
-                                正の要素を有する実数のスカラーまたはベクトルまたは行列.
-
-                            </term>
-
-                            <listitem>
-
-                                <itemizedlist>
-
-                                    <listitem>
-
-                                        <para>
-
-                                            <literal>r=x(i,j)</literal> は,
-
-                                            1 から<literal>size(i,'*')</literal>の
-
-                                            <literal>l</literal>および
-
-                                            1 から <literal>size(j,'*')</literal>の
-
-                                            <literal>k</literal>について
-
-                                            <literal>r(l,k)=x(int(i(l)),int(j(k)))</literal>となるような
-
-                                            行列<literal>r</literal>を作成します.
-
-                                        </para>
-
-                                        <para>
-
-                                            <literal>i</literal> (<literal>j</literal>) の
-
-                                            最大値は<literal>size(x,1)</literal>
-
-                                            (<literal>size(x,2)</literal>)以下とする必要があります.
-
-                                        </para>
-
-                                    </listitem>
-
-                                    <listitem>
-
-                                        <para>
-
-                                            1x1行列 <literal>x</literal>を指定した
-
-                                            <literal>r=x(i)</literal>は,
-
-                                            1 から<literal>size(i,1)</literal>の<literal>l</literal>および
-
-                                            1 から <literal>size(i,2)</literal>の<literal>k</literal>
-
-                                            について, <literal>r(l,k)=x(int(i(l)),int(i(k)))</literal>
-
-                                            となるような
-
-                                            行列 <literal>r</literal> を構築します.
-
-                                        </para>
-
-                                        <para>
-
-                                            この場合,全てのエントリが1に等しい場合にのみ,
-
-                                            添え字 <literal>i</literal>が有効です.
-
-                                        </para>
-
-                                    </listitem>
-
-                                    <listitem>
-
-                                        <para>
-
-                                            <literal>x</literal>を指定した行ベクトル<literal>r=x(i)</literal>は,
-
-                                            1から<literal>size(i,'*')</literal>の<literal>l</literal>
-
-                                            について<literal>r(l)=x(int(i(l)))</literal>となるような
-
-                                            行ベクトル <literal>r</literal>を作成します.
-
-                                            <literal>i</literal>の最大値が
-
-                                            <literal>size(x,'*')</literal>以下とする必要があります.
-
-                                        </para>
-
-                                    </listitem>
-
-                                    <listitem>
-
-                                        <para>
-
-                                            1つ以上の列を有する行列<literal>x</literal>を指定した
-
-                                            <literal>r=x(i)</literal> は,
-
-                                            <literal>r(l)</literal>
-
-                                            (<literal>l</literal>は 1 から <literal>size(i,'*')</literal>)
-
-                                            が <literal>x</literal>の列の結合により作成された
-
-                                            列ベクトルの
-
-                                            エントリ<literal>int(i(l))</literal>を含むような
-
-                                            列ベクトル<literal>r</literal>を作成します.
-
-                                        </para>
-
-                                        <para>
-
-                                            <literal>i</literal> の最大値は
-
-                                            <literal>size(x,'*')</literal>以下である必要があります.
-
-                                        </para>
-
-                                    </listitem>
-
-                                </itemizedlist>
-
-                            </listitem>
-
-                        </varlistentry>
-
-                        <varlistentry>
-
-                            <term>
-
-                                記号 <literal> : </literal>
-
-                            </term>
-
-                            <listitem>
-
-                                <para><literal/>
-
-                                    は "全ての要素"を意味します.
-
-                                </para>
-
-                                <itemizedlist>
-
-                                    <listitem>
-
-                                        <para>
-
-                                            <literal>r=x(i,:)</literal> は,
-
-                                            1から<literal>size(i,'*')</literal>の<literal>l</literal>,
-
-                                            1から<literal>size(x,2)</literal>の<literal>k</literal>について,
-
-                                            <literal>r(l,k)=x(int(i(l)),k))</literal>となるような
-
-                                            行列 <literal>r</literal> を作成します.
-
-                                        </para>
-
-                                    </listitem>
-
-                                    <listitem>
-
-                                        <para>
-
-                                            <literal>r=x(:,j)</literal> は,
-
-                                            1から<literal>size(r,1)</literal>の<literal>l</literal>,
-
-                                            1から<literal>size(j,'*')</literal>の<literal>k</literal>について,
-
-                                            <literal>r(l,k)=x(l,int(j(k)))</literal>となるような
-
-                                            行列 <literal>r</literal> を作成します.
-
-                                        </para>
-
-                                    </listitem>
-
-                                    <listitem>
-
-                                        <para>
-
-                                            <literal>r=x(:)</literal> は,
-
-                                            <literal>x</literal>列の列結合により
-
-                                            列ベクトル<literal>r</literal>を作成します.
-
-                                            これは,<literal>matrix(x,size(x,'*'),1)</literal>と等価です.
-
-                                        </para>
-
-                                    </listitem>
-
-                                </itemizedlist>
-
-                            </listitem>
-
-                        </varlistentry>
-
-                        <varlistentry>
-
-                            <term>論理値のベクトル</term>
-
-                            <listitem>
-
-                                <para>
-
-                                    添え字 (<literal>i</literal> または
-
-                                    <literal>j</literal> ) が論理値のベクトルの場合,それぞれ
-
-                                    <literal>find(i)</literal>または<literal>find(j)</literal>
-
-                                    として解釈されます.
-
-                                </para>
-
-                            </listitem>
-
-                        </varlistentry>
-
-                        <varlistentry>
-
-                            <term>多項式</term>
-
-                            <listitem>
-
-                                <para>
-
-                                    添え字 (<literal>i</literal> または
-
-                                    <literal>j</literal> )が多項式のベクトルまたは
-
-                                    暗黙の多項式ベクトルの場合,それぞれ
-
-                                    <literal>horner(i,m)</literal>または
-
-                                    <literal>horner(j,n)</literal>と解釈されます.
-
-                                    ただし,<literal>m</literal> および<literal>n</literal>
-
-                                    は<literal>x</literal>の次元に関連します.
-
-                                    この機能は全ての多項式に対して動作しますが,
-
-                                    可読性を確保するために, <literal>$</literal>に
-
-                                    多項式を使用することが推奨されます.
-
-                                </para>
-
-                            </listitem>
-
-                        </varlistentry>
-
-                    </variablelist>
-
-                    <para>
-
-                        2より大きな次元の行列(参照:<link linkend="hypermatrices">ハイパー行列</link>)の場合,
-
-                        最も右の次元が1に等しくなると
-
-                        次元が自動的に縮小されます.
-
-                    </para>
-
+                  <itemizedlist>
+                    <listitem>
+                      <para>
+                        <literal>r=x(i,j)</literal> は,
+                        1 から<literal>size(i,'*')</literal>の
+                        <literal>l</literal>および
+                        1 から <literal>size(j,'*')</literal>の
+                        <literal>k</literal>について
+                        <literal>r(l,k)=x(int(i(l)),int(j(k)))</literal>となるような
+                        行列<literal>r</literal>を作成します.
+                      </para>
+                      <para>
+                        <literal>i</literal> (<literal>j</literal>) の
+                        最大値は<literal>size(x,1)</literal>
+                        (<literal>size(x,2)</literal>)以下とする必要があります.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        1x1行列 <literal>x</literal>を指定した
+                        <literal>r=x(i)</literal>は,
+                        1 から<literal>size(i,1)</literal>の<literal>l</literal>および
+                        1 から <literal>size(i,2)</literal>の<literal>k</literal>
+                        について, <literal>r(l,k)=x(int(i(l)),int(i(k)))</literal>
+                        となるような
+                        行列 <literal>r</literal> を構築します.
+                      </para>
+                      <para>
+                        この場合,全てのエントリが1に等しい場合にのみ,
+                        添え字 <literal>i</literal>が有効です.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>x</literal>を指定した行ベクトル<literal>r=x(i)</literal>は,
+                        1から<literal>size(i,'*')</literal>の<literal>l</literal>
+                        について<literal>r(l)=x(int(i(l)))</literal>となるような
+                        行ベクトル <literal>r</literal>を作成します.
+                        <literal>i</literal>の最大値が
+                        <literal>size(x,'*')</literal>以下とする必要があります.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        1つ以上の列を有する行列<literal>x</literal>を指定した
+                        <literal>r=x(i)</literal> は,
+                        <literal>r(l)</literal>
+                        (<literal>l</literal>は 1 から <literal>size(i,'*')</literal>)
+                        が <literal>x</literal>の列の結合により作成された
+                        列ベクトルの
+                        エントリ<literal>int(i(l))</literal>を含むような
+                        列ベクトル<literal>r</literal>を作成します.
+                      </para>
+                      <para>
+                        <literal>i</literal> の最大値は
+                        <literal>size(x,'*')</literal>以下である必要があります.
+                      </para>
+                    </listitem>
+                  </itemizedlist>
                 </listitem>
-
-            </varlistentry>
-
-            <varlistentry>
-
-                <term>list または tlist の場合</term>
-
+              </varlistentry>
+              <varlistentry>
+                <term>
+                  記号 <literal> : </literal>
+                </term>
                 <listitem>
-
-                    <para>
-
-                        指定された場合,
-
-                        <literal>ki</literal>は<literal>l</literal>データ構造
-
-                        のサブリストのエントリへのパスを指定します.
-
-                        これにより,中間的なコピーをすることなく再帰的な展開が
-
-                        可能になります.
-
-                        命令は以下のようになります:
-
-                    </para>
-
-                    <para>
-
-                        <literal>[...]=l(k1)...(kn)(i)</literal>
-
-                    </para>
-
-                    <para>および</para>
-
-                    <para>
-
-                        <literal>[...]=l(list(k1,...,kn,i))</literal>
-
-                    </para>
-
-                    <para>は以下のように解釈されます:</para>
-
-                    <para>
-
-                        <literal>lk1 = l(k1)</literal><literal> .. = .. </literal><literal>lkn = lkn-1(kn)</literal><literal>[...] = lkn(i)</literal>
-
-                        そして,<literal>l(k1)...(kn)(i,j)</literal> および
-
-                    </para>
-
-                    <para>
-
-                        <literal>l(list(k1,...,kn,list(i,j))</literal> 命令は
-
-                        以下のように解釈されます: <literal>lk1 = l(k1)</literal> <literal> .. = ..
-
-                        </literal>
-
-                        <literal>lkn = lkn-1(kn)</literal> <literal>
-
-                            lkn(i,j)
-
-                        </literal>
-
-                        <literal>i</literal> および <literal>j</literal>については後述します.
-
-                        パスが複数のリストの要素を指す場合,
-
-                        この命令は,選択した要素と同じ数の左辺の引数を有する必要があります.
-
-                        しかし,展開構文を関数の中で使用した場合,
-
-                        リストの要素を返す入力の呼出し手順が
-
-                        関数の呼び出し手順に追加されます.
-
-                    </para>
-
-                    <para>
-
-                        <literal> l(list())</literal> は
-
-                        <literal> l</literal>と同じであることに注意してください.
-
-                    </para>
-
-                    <variablelist>
-
-                        <varlistentry>
-
-                            <term>i および j は以下のようになります :</term>
-
-                            <listitem>
-
-                                <variablelist>
-
-                                    <varlistentry>
-
-                                        <term>正の要素を有する実数のスカラーまたはベクトルまたは行列.</term>
-
-                                        <listitem>
-
-                                            <para>
-
-                                                <literal>[r1,...rn]=l(i)</literal> は
-
-                                                リスト l から要素<literal>i(k)</literal>を展開し,これを
-
-                                                1から<literal>size(i,'*')</literal>までの <literal>k</literal>
-
-                                                について <literal>rk</literal> に保存します.
-
-                                            </para>
-
-                                        </listitem>
-
-                                    </varlistentry>
-
-                                    <varlistentry>
-
-                                        <term>
-
-                                            記号 <literal> : </literal>
-
-                                        </term>
-
-                                        <listitem>
-
-                                            <para>"全ての要素"を意味します.</para>
-
-                                        </listitem>
-
-                                    </varlistentry>
-
-                                    <varlistentry>
-
-                                        <term>論理値のベクトル.</term>
-
-                                        <listitem>
-
-                                            <para>
-
-                                                <literal>i</literal> が論理値のベクトルの場合,
-
-                                                <literal>find(i)</literal>と解釈されます.
-
-                                            </para>
-
-                                        </listitem>
-
-                                    </varlistentry>
-
-                                    <varlistentry>
-
-                                        <term>多項式.</term>
-
-                                        <listitem>
-
-                                            <para>
-
-                                                <literal>i</literal> が多項式のベクトルまたは
-
-                                                暗黙の多項式ベクトルの場合,
-
-                                                <literal>horner(i,m)</literal>として解釈されます.
-
-                                                ただし,<literal>m=size(l)</literal>です.
-
-                                                この機能は全ての多項式に関して動作しますが,
-
-                                                可読性を良くするために,多項式を<literal>$</literal>の
-
-                                                中で使用することを推奨します.
-
-                                            </para>
-
-                                        </listitem>
-
-                                    </varlistentry>
-
-                                </variablelist>
-
-                            </listitem>
-
-                        </varlistentry>
-
-                        <varlistentry>
-
-                            <term>k1,..kn は以下のようになります. :</term>
-
-                            <listitem>
-
-                                <variablelist>
-
-                                    <varlistentry>
-
-                                        <term>実数の正のスカラー,</term>
-
-                                        <listitem>
-
-                                            <para/>
-
-                                        </listitem>
-
-                                    </varlistentry>
-
-                                    <varlistentry>
-
-                                        <term>多項式,</term>
-
-                                        <listitem>
-
-                                            <para>
-
-                                                は<literal>horner(ki,m)</literal>と解釈されます.
-
-                                                ただし,<literal>m</literal>は対応するサブリストの大きさです.
-
-                                            </para>
-
-                                        </listitem>
-
-                                    </varlistentry>
-
-                                    <varlistentry>
-
-                                        <term>文字列</term>
-
-                                        <listitem>
-
-                                            <para>サブリストのエントリ名に関連します.</para>
-
-                                        </listitem>
-
-                                    </varlistentry>
-
-                                </variablelist>
-
-                            </listitem>
-
-                        </varlistentry>
-
-                    </variablelist>
-
+                  <para><literal/>
+                    は "全ての要素"を意味します.
+                  </para>
+                  <itemizedlist>
+                    <listitem>
+                      <para>
+                        <literal>r=x(i,:)</literal> は,
+                        1から<literal>size(i,'*')</literal>の<literal>l</literal>,
+                        1から<literal>size(x,2)</literal>の<literal>k</literal>について,
+                        <literal>r(l,k)=x(int(i(l)),k))</literal>となるような
+                        行列 <literal>r</literal> を作成します.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>r=x(:,j)</literal> は,
+                        1から<literal>size(r,1)</literal>の<literal>l</literal>,
+                        1から<literal>size(j,'*')</literal>の<literal>k</literal>について,
+                        <literal>r(l,k)=x(l,int(j(k)))</literal>となるような
+                        行列 <literal>r</literal> を作成します.
+                      </para>
+                    </listitem>
+                    <listitem>
+                      <para>
+                        <literal>r=x(:)</literal> は,
+                        <literal>x</literal>列の列結合により
+                        列ベクトル<literal>r</literal>を作成します.
+                        これは,<literal>matrix(x,size(x,'*'),1)</literal>と等価です.
+                      </para>
+                    </listitem>
+                  </itemizedlist>
                 </listitem>
-
-            </varlistentry>
-
-        </variablelist>
-
+              </varlistentry>
+              <varlistentry>
+                <term>論理値のベクトル</term>
+                <listitem>
+                  <para>
+                    添え字 (<literal>i</literal> または
+                    <literal>j</literal> ) が論理値のベクトルの場合,それぞれ
+                    <literal>find(i)</literal>または<literal>find(j)</literal>
+                    として解釈されます.
+                  </para>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>多項式</term>
+                <listitem>
+                  <para>
+                    添え字 (<literal>i</literal> または
+                    <literal>j</literal> )が多項式のベクトルまたは
+                    暗黙の多項式ベクトルの場合,それぞれ
+                    <literal>horner(i,m)</literal>または
+                    <literal>horner(j,n)</literal>と解釈されます.
+                    ただし,<literal>m</literal> および<literal>n</literal>
+                    は<literal>x</literal>の次元に関連します.
+                    この機能は全ての多項式に対して動作しますが,
+                    可読性を確保するために, <literal>$</literal>に
+                    多項式を使用することが推奨されます.
+                  </para>
+                </listitem>
+              </varlistentry>
+            </variablelist>
+            <para>
+              2より大きな次元の行列(参照:<link linkend="hypermatrices">ハイパー行列</link>)の場合,
+              最も右の次元が1に等しくなると
+              次元が自動的に縮小されます.
+            </para>
+        </refsect3>
+        <refsect3>
+            <title>list または tlist の場合</title>
+            <para>
+              指定された場合,
+              <literal>ki</literal>は<literal>l</literal>データ構造
+              のサブリストのエントリへのパスを指定します.
+              これにより,中間的なコピーをすることなく再帰的な展開が
+              可能になります.
+              命令は以下のようになります:
+            </para>
+            <para>
+              <literal>[...]=l(k1)...(kn)(i)</literal>
+            </para>
+            <para>および</para>
+            <para>
+              <literal>[...]=l(list(k1,...,kn,i))</literal>
+            </para>
+            <para>は以下のように解釈されます:</para>
+            <para>
+              <literal>lk1 = l(k1)</literal><literal> .. = .. </literal><literal>lkn = lkn-1(kn)</literal><literal>[...] = lkn(i)</literal>
+              そして,<literal>l(k1)...(kn)(i,j)</literal> および
+            </para>
+            <para>
+              <literal>l(l