help brackets: page overhauled and rewritten 74/18274/8
Samuel GOUGEON [Tue, 21 Jun 2016 01:36:18 +0000 (03:36 +0200)]
Change-Id: I610657233a4fbe86bf5b4db35ff55608a71528ed

scilab/CHANGES.md
scilab/modules/core/help/en_US/1_keywords/brackets.xml
scilab/modules/core/help/fr_FR/1_keywords/brackets.xml
scilab/modules/core/help/ja_JP/1_keywords/brackets.xml [deleted file]
scilab/modules/core/help/ru_RU/1_keywords/brackets.xml [deleted file]

index 15152fd..6a64f72 100644 (file)
@@ -146,7 +146,7 @@ Help pages:
 
 * fixed / improved:  `members`, `part`, `ode`, `ode_optional_output`, `ode_roots`, `roots`,
   `printf`, `sprintf`, `iconvert`, `stdev`, `xlabel`
-* rewriten: `consolebox`, `double`, `isoview`, `householder`, `or`, `and`, `format`, `typeof`
+* rewriten: `consolebox`, `double`, `isoview`, `householder`, `or`, `and`, `format`, `typeof`, `brackets`
 * reorganized:
   - `else`, `elseif`, `end`, `try`, `sciargs`, `global`, `halt`, `empty`, `power`
   - CACSD and Signal Processing help pages have been sorted up.
index b80def4..20455b6 100644 (file)
 <?xml version="1.0" encoding="UTF-8"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2016 - Samuel GOUGEON
+ *
+ * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ *
+ * This file is hereby licensed under the terms of the GNU GPL v2.0,
+ * pursuant to article 5.3.4 of the CeCILL v.2.1.
+ * This file was originally licensed under the terms of the CeCILL v2.1,
+ * and continues to be available under such terms.
+ * For more information, see the COPYING file which you should have received
+ * 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: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="brackets">
     <refnamediv>
-        <refname>brackets</refname>
-        <refpurpose>([,]) left and right brackets</refpurpose>
+        <refname>brackets [,;]</refname>
+        <refpurpose>Concatenation. Recipients of an assignment. Results of a function</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
-        <synopsis>[a11,a12,...;a21,a22,...;...]
-            [s1,s2,...]=func(...)
+        <synopsis>
+            Mh = [m11 m12 m13.. m1N] or [m11, m12, m13,.., m1N]
+            Mv = [m11 ; m21 ; m31..; mN1]
+            M  = [m11, m12,...; m21, m22,...;...]
+            [r1, r2,...] = func(...)
+            [r1, r2,.., rN] = (e1, e2, .., eN)
+            [r1, r2,.., rk] = (e1, e2, .., ek,.., eN)
+            [r1, r2,.., rN] = mylist(:)
+            [r1, r2,.., rN] = S.field([i1 i2.. iN])
         </synopsis>
     </refsynopsisdiv>
-    <refsection>
+    <refsection role="parameters">
         <title>Arguments</title>
         <variablelist>
             <varlistentry>
-                <term>a11,a12,...  </term>
+                <term>m11, m12,...  </term>
                 <listitem>
                     <para>
-                        any matrix (real, polynomial, rational, <literal>syslin</literal> list ...) with appropriate dimensions
+                    Set of objects to be
+                    concatenated (and merged: the former individual containers
+                    are removed).
+                    The following subsets of types of objects can be mixed
+                    in-between, but are mutually exclusive:
+                    <itemizedlist>
+                        <listitem>Matrices of booleans, reals, complex numbers,
+                            polynomials, rationals: The data type of the
+                            concatenated result is set by the rules defined below
+                            (see the <link linkend="brackets_Types_conversions">
+                            <emphasis role="italic">type conversions</emphasis>
+                            </link> rules).
+                        </listitem>
+                        <listitem>Matrices of encoded integers of any
+                            <link linkend="inttype">inttype</link>.
+                            <warning>
+                                Encoded integers of different inttypes can't
+                                be concatenated together.
+                            </warning>
+                        </listitem>
+                        <listitem>Arrays of structures with same fields.
+                            Fields may be in different orders from an array
+                            to other ones.
+                        </listitem>
+                        <listitem>
+                            Typed lists of type <link linkend="syslin">syslin</link>.
+                        </listitem>
+                    </itemizedlist>
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>s1,s2,...  </term>
+                <term>M, Mh, Mv</term>
                 <listitem>
-                    <para>any possible variable name</para>
+                    <para>
+                        Matrices with the type of all <varname>m##</varname>
+                        (if they all have the same data type)
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>e1, e2,..  </term>
+                <listitem>
+                    <para>Input objects (literals like <literal>-1.23</literal>
+                    or <literal>"abcd"</literal>, variables, or expressions
+                    like <literal>a+%pi</literal>, etc).
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>mylist</term>
+                <listitem>
+                    <para>a simple list</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>S.field</term>
+                <listitem>
+                    <para>
+                        Array of Structures with a field named <literal>field</literal>.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>i1, i2,..  </term>
+                <listitem>
+                    <para>
+                        Indices of components selected from <varname>S</varname>.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>r1, r2,...  </term>
+                <listitem>
+                    <para>Output variables</para>
                 </listitem>
             </varlistentry>
         </variablelist>
     </refsection>
-    <refsection>
+    <refsection role="description">
         <title>Description</title>
-        <para>
-            Left and right brackets are used to note vector and matrix concatenation.
-            These symbols are also used to denote a multiple left-hand-side for a function
-            call.
-        </para>
-        <para>
-            Inside concatenation brackets, blank or comma characters mean
-            "column concatenation", semicolon and carriage-return mean
-            "row concatenation".
-        </para>
-        <para>
-            Note : to avoid confusions it is safer to use commas instead of blank to
-            separate columns.
-        </para>
-        <para>
-            Within multiple lhs brackets variable names must be separated by comma.
-        </para>
+        <variablelist>
+            <varlistentry>
+                <term>[] on right-hand side: concatenators</term>
+                <listitem>
+                    <para>[..] bundle their contents of simple and compatible
+                        types into a homogeneous vector, matrix or hypermatrix.
+                    </para>
+                    <note>An horizontal or a vertical concatenation is a
+                        binary iterated operator. It is performed step-by-step
+                        from left-to-right, and from top-to-bottom. Thus,
+                        <literal>[1 3 5 7]</literal> is performed as
+                        <literal>[[[1 3] 5] 7]</literal>.
+                    </note>
+                    <para>Inside brackets,
+                        <itemizedlist>
+                            <listitem>spaces (blanks or tabs) or commas are
+                                used as columns separators.
+                                <note>Using commas instead of spaces is safer.
+                                    For instance, <literal>[2 1 +%i]</literal>
+                                    means <literal>[2, 1, %i]</literal>, while
+                                    <literal>[2 1 + %i]</literal> means
+                                    <literal>[2, 1+%i]</literal>
+                                </note>
+                            </listitem>
+                            <listitem>semi-colons or carriage-return are used
+                                as rows separators. Multiple rows do not need
+                                the continuation dots <literal>..</literal>
+                            </listitem>
+                        </itemizedlist>
+                    </para>
+                    <refsect3 id="brackets_Types_conversions">
+                        <title>Types conversions</title>
+                        <para>
+                            In some limits, brackets may be applied on a set of
+                            data having different but compatible types. In this
+                            case, some data are converted into the dominating type
+                            available in the set. The main conversion rules are the
+                            following:
+                            <orderedlist>
+                                <listitem>boolean &lt; decimal number &lt; complex
+                                </listitem>
+                                <listitem>decimal number &lt; polynomial &lt; rational
+                                    <warning>booleans and polynomials are not compatible.
+                                        <itemizedlist>
+                                            <listitem>
+                                                <literal>[%t 2. %z]</literal> is accepted:
+                                                <literal>[%t 2.]</literal> is first
+                                                converted into
+                                                <literal>[1. 2.]</literal>, and then
+                                                <literal>[[1. 2.] %z]</literal> is accepted.
+                                            </listitem>
+                                            <listitem>
+                                                <literal>[%z %t 2.]</literal> is
+                                                rejected and yields an error.
+                                                Indeed, <literal>[%z %t]</literal>
+                                                can't be converted first.
+                                            </listitem>
+                                        </itemizedlist>
+                                    </warning>
+                                </listitem>
+                                <listitem>
+                                    The result becomes complex-encoded as soon as
+                                    a complex-encoded component -- value, polynomial,
+                                    or rational -- is met in the list
+                                    (even with a null imaginary part)
+                                    <para>Similarly, the result becomes sparse-encoded
+                                    as soon as a sparse-encoded component is met
+                                    and processed.
+                                    </para>
+                                </listitem>
+                                <listitem>
+                                    It is possible to concatenate polynomials or/and
+                                    rationals having different variable names. Then,
+                                    the first polynomial or rational met in the list
+                                    sets the variable name to the concatenation result:
+                                    <literal>[%z, 1+%s, 1-%i*%s]
+                                        // => [z, 1+z, 1-iz]
+                                    </literal>.
+                                </listitem>
+                                <listitem>
+                                    Any encoded integer can be concatenated
+                                    only with integers of the same inttype.
+                                    Thus, the expressions
+                                    <literal>[%t int8(2)]</literal>,
+                                    <literal>[int8(2) uint8(7)]</literal>,
+                                    <literal>[int8(2) int16(7)]</literal>,
+                                    <literal>[int8(2) 1.]</literal> will all yield
+                                    an error.
+                                </listitem>
+                                <listitem>Text components can be concatenated
+                                    (in the set meaning, with brackets) only with other
+                                    text components or with the empty matrix.
+                                    <literal>[]</literal>.
+                                </listitem>
+                            </orderedlist>
+                        </para>
+                    </refsect3>
+                    <refsect3 id="brackets_overloading">
+                        <title>Overloading</title>
+                        <para>
+                            <itemizedlist>
+                                <listitem>[,]: horizontal concatenation:
+                                    This operator is binary and automatically
+                                    iterated from left to right. Its overloading
+                                    code is <literal>"c"</literal>.
+                                </listitem>
+                                <listitem>[;]: vertical concatenation:
+                                    This operator is binary and automatically
+                                    iterated from top to bottom. Its overloading
+                                    code is <literal>"f"</literal>.
+                                </listitem>
+                            </itemizedlist>
+                        </para>
+                    </refsect3>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>[] on left-hand side of a <literal>"="</literal> assignment</term>
+                <listitem>
+                    <para>
+                    In this case, brackets are no longer concatenators.
+                    They are used as left and right delimiters of a series of
+                    variables used as recipients.
+                    </para>
+                    <para>
+                        <itemizedlist>
+                            <listitem>Recipients must be variables.
+                                Litteral expressions are not accepted.
+                            </listitem>
+                            <listitem>Variables shall be separated with comas.
+                            </listitem>
+                            <listitem>In a distributive assignment, there must
+                                be at most as many LHS recipients
+                                as output sources, not more. If there are less
+                                recipients on the left than sources on the right,
+                                non-collected data sources are ignored. Examples :
+                                <simplelist>
+                                    <member><literal>[a,b]=(%pi,"Hi", %z)</literal>
+                                        is OK, but <literal>%z</literal> is ignored.
+                                    </member>
+                                    <member><literal>[a,b,c]=(%pi,"Hi")</literal>
+                                        yields an error because <literal>c</literal>
+                                        expects some foods.
+                                    </member>
+                                </simplelist>
+                            </listitem>
+                            <listitem>The same variable may be used several times
+                                in the list. Then, multiple assignments overwrite
+                                the previous ones, from left to right.
+                                Example :
+                                <literal>[a,b,a]=(%pi,%z,"Allo")</literal>
+                                is equivalent to <literal>a="Allo", b=%z</literal>.
+                            </listitem>
+                        </itemizedlist>
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
     </refsection>
-    <refsection>
+    <refsection role="examples">
         <title>Examples</title>
         <programlisting role="example"><![CDATA[
-[6.9,9.64; sqrt(-1) 0]
-[1 +%i  2 -%i  3]
-[]
-['this is';'a string';'vector']
-s=poly(0,'s');[1/s,2/s]
+// Horizontal concatenations
+a = [ %pi 4 -1 ]
+b1 = grand(3,4,"uin",0,10)
+b2 = grand(3,2,"uin",0,10)
+b = [b1 b2]  // they must have the same number of rows
+
+// Vertical concatenations
+a = [-2 ; 10 ; 7]
+
+b1 = grand(2,4,"uin",0,10)
+b2 = grand(3,4,"uin",0,10)
+b = [b1 ; b2] // they must have the same number of columns
+
+// Mixed horizontal and vertical concatenations
+a = [ 3 7 ; 6, 5 ]
+b = [ 1:3 ; 7:3:13]
+c = [ a b ; a b]
+
+d = [ 3 5
+      1 4
+    ]
+e = [ d d d
+      d d d
+    ]
+// Concatenation of various types of data:
+['this is' ; 'a column' ; 'of texts']
+
+s = poly(0,'s');[1/s,2/s]
 [tf2ss(1/s),tf2ss(2/s)]
 
-[u,s]=schur(rand(3,3))
+[%t %f %f %T %F]
+
+// Heterogeneous concatenations with automatical types conversions
+[%T %pi %f 2]
+[%pi, 2+%i, %F]
+v = [%pi+0*%i, %F, %z, (1-%z)^2 ]; typeof(v), isreal(v)
+v = [10 1/%z], typeof(v)
+
+// Incompatible heterogeneous concatenations => ERRORS
+[%F %z]
+[%F int8(5)]
+[int8(%pi) uint8(%e)]
+[int8(%pi) int16(%e)]
  ]]></programlisting>
+
+        <para>
+            <emphasis role="bold">Distributive assignments:</emphasis>
+        </para>
+        <programlisting role="example"><![CDATA[
+// Output from a function. Most often, output results are serially optional:
+M = rand(3,3);
+[u, s] = schur(M) // we expect and use both results u and s
+u = schur(M)      // we expect and store only the first result u
+
+// Direct RHS list
+[a, b, c] = (%pi, %t, "test")
+[a, b] = (%e, %f, "Hello")
+[a, b, a] = (%pi, %t, "test");
+
+// Explicit RHS list
+L = list(%z, %i, %t, %pi, "Text");
+[a, b, c] = L(:)
+
+// RHS structure
+s(2,3).r = %pi; s(2,1).r = %i; s(2,2) = %e;
+s(2,:).r
+s.r([2 4 6])
+[a, b, c] = s.r([2 4 6])
+
+// Forbidden / Rejected LHS expressions (=> error)
+[m, n, m+n] = myfun(a,b)   // Symbolic expressions like "m+n" are forbidden
+[p, 4.5, q] = myfun(a,b)   // Literal LHS values or expressions like "4.5" are forbidden
+[r, s+3 ] = myfun(a,b)   // Expressions mixing literals and symbols like "s+3" can't be LHS recipients
+]]></programlisting>
+        <screen><![CDATA[--> [a, b, c] = (%pi, %t, "test")
+ c  =
+ test
+
+ b  =
+  T
+
+ a  =
+   3.1415927
+
+--> [a, b] = (%e, %f, "Hello")
+ b  =
+  F
+
+ a  =
+   2.7182818
+
+--> [a, b, a] = (%pi, %t, "test"); a
+ a  =
+   3.1415927
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
         <simplelist type="inline">
             <member>
+                <link linkend="empty">empty</link>
+            </member>
+            <member>
                 <link linkend="parentheses">parentheses</link>
             </member>
             <member>
+                <link linkend="lstcat">lstcat</link>
+            </member>
+            <member>
                 <link linkend="comma">comma</link>
             </member>
             <member>
                 <link linkend="semicolon">semicolon</link>
             </member>
+            <member>
+                <link linkend="overloading">overloading</link>
+            </member>
         </simplelist>
     </refsection>
+    <refsection role="history">
+        <title>History</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.0</revnumber>
+                <revdescription>
+                    Brackets <literal>[..]</literal> and braces
+                    <literal>{..}</literal> are no longer equivalent
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>
index 8d8f0c1..a55538f 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: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="brackets">
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2016 - Samuel GOUGEON
+ * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ *
+ * This file is hereby licensed under the terms of the GNU GPL v2.0,
+ * pursuant to article 5.3.4 of the CeCILL v.2.1.
+ * This file was originally licensed under the terms of the CeCILL v2.1,
+ * and continues to be available under such terms.
+ * For more information, see the COPYING file which you should have received
+ * 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: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="brackets">
     <refnamediv>
-        <refname>brackets ([,])</refname>
-        <refpurpose>([,]) crochets à droite et à gauche  </refpurpose>
+        <refname>brackets [,;]</refname>
+        <refpurpose>Concatenation. Récipients d'une affectation. Résultats d'une function</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
-        <title>Séquence d'appel</title>
-        <synopsis>[a11,a12,...;a21,a22,...;...]
-            [s1,s2,...]=func(...)
+        <title>Syntaxe</title>
+        <synopsis>
+            Mh = [m11 m12 m13.. m1N] or [m11, m12, m13,.., m1N]
+            Mv = [m11 ; m21 ; m31..; mN1]
+            M  = [m11, m12,...; m21, m22,...;...]
+            [r1, r2,...] = func(...)
+            [r1, r2,.., rN] = (e1, e2, .., eN)
+            [r1, r2,.., rk] = (e1, e2, .., ek,.., eN)
+            [r1, r2,.., rN] = mylist(:)
+            [r1, r2,.., rN] = S.field([i1 i2.. iN])
         </synopsis>
     </refsynopsisdiv>
-    <refsection>
-        <title>Paramètres</title>
+    <refsection role="parameters">
+        <title>Arguments</title>
         <variablelist>
             <varlistentry>
-                <term>a11,a12,...  </term>
+                <term>m11, m12,...  </term>
                 <listitem>
                     <para>
-                        toute matrice (réelle, complexe, polynomiale, rationnelle, liste de type <literal>syslin</literal> ...) de dimensions adéquates
+                    Ensemble d'objets à concaténer (rassembler) et à fusionner :
+                    les conteneurs individuels initiaux des objets sont supprimés.
+                    Les types d'objets des familles suivantes peuvent
+                    être mélangés entre eux dans une même famille, mais pas
+                    entre familles :
+                    <itemizedlist>
+                        <listitem>
+                            Matrices de booléens, nombres décimaux,
+                            nombres complexes, polynômes, fractions rationnelles :
+                            le type de l'objet résultant est le type de l'élément le
+                            plus complexe, des booléens (le moins complexe) aux fractions
+                            rationelles à coefficients complexes
+                            (voir les règles de
+                            <link linkend="brackets_Types_conversions">
+                            <emphasis role="italic">transtypages</emphasis></link>).
+                        </listitem>
+                        <listitem>Matrices d'entiers encodés de type entier
+                            <link linkend="inttype">inttype</link> quelconque.
+                            <warning>Des entiers de types différents ne peuvent
+                            pas être concaténés entre eux.
+                            </warning>
+                        </listitem>
+                        <listitem>Tableaux de structures ayant les mêmes champs.
+                            Les champs peuvent être dans des ordres différents
+                            d'un tableau à l'autre.
+                        </listitem>
+                        <listitem>
+                            Listes de type <link linkend="syslin">syslin</link>
+                        </listitem>
+                    </itemizedlist>
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>s1,s2,...  </term>
+                <term>M, Mh, Mv</term>
                 <listitem>
-                    <para>noms de variables
+                    <para>
+                        Matrices ayant le type des éléments <varname>m##</varname>
+                        (s'ils ont tous le même type).
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>e1, e2,..  </term>
+                <listitem>
+                    <para>Objets d'entrée (litéraux tels que <literal>-1.23</literal>
+                    ou <literal>"abcd"</literal>, variables, ou expressions telles
+                    que <literal>a+%pi</literal>)
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>mylist</term>
+                <listitem>
+                    <para>Liste simple du type list(..)</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>S.field</term>
+                <listitem>
+                    <para>
+                        Tableau de structures ayant un champ nommé <literal>field</literal>.
                     </para>
                 </listitem>
             </varlistentry>
+            <varlistentry>
+                <term>i1, i2, ..</term>
+                <listitem>
+                    <para>
+                        Indices des éléments de <varname>S</varname> sélectionnés.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>r1, r2,...  </term>
+                <listitem>
+                    <para>Récipients = variables de sortie</para>
+                </listitem>
+            </varlistentry>
         </variablelist>
     </refsection>
-    <refsection>
+    <refsection role="description">
         <title>Description</title>
-        <para>
-            Les crochets droit et gauche sont utilisés pour effectuer une concaténation de matrices. Ces symboles sont aussi utilisés quand on effectue un appel à une fonction renvoyant plusieurs arguments.
-        </para>
-        <para>
-            A l'intérieur d'une paire de crochets spécifiant une concaténation, un espace ou une virgule signifient une concaténation de colonnes, alors qu'un point-virgule ou un passage à la ligne signifient une concaténation de lignes.
-        </para>
-        <para>
-            Note : pour éviter les confusions il est plus sûr d'utiliser des virgules pour concaténer des colonnes.
-        </para>
-        <para>
-            Pour des crochets entourant une liste d'arguments de sortie d'une fonction,
-            les noms de variables doivent être séparés par des virgules.
-        </para>
+        <variablelist>
+            <varlistentry>
+                <term>[] (figurant à droite) : crochets concaténateurs</term>
+                <listitem>
+                    <para>[..] assemble les objets de types simples et compatibles
+                        pour former un vecteur, une matrice ou une hypermatrice
+                        homogène.
+                    </para>
+                    <note>La concaténation horizontale ou verticale de N éléments
+                        est un opérateur binaire itératif : la concaténation
+                        est réalisée de proche en proche entre 2 élements consécutifs,
+                        de la gauche vers la droite, et de haut en bas. Ainsi,
+                        <literal>[1 3 5 7]</literal> est effectuée par
+                        <literal>[[[1 3] 5] 7]</literal>.
+                    </note>
+                    <para>Dans les crochets,
+                        <itemizedlist>
+                            <listitem>les espaces (blancs ou tabulations) ou
+                                les virgules servent de séparateurs.
+                                <note>Il est préférable d'utiliser des virgules,
+                                en particulier lorsque des nombres complexes
+                                ou des polynômes sont fournis en expressions
+                                litérales. Par exemple, <literal>[2 1 +%i]</literal>
+                                sera interprété comme <literal>[2, 1, %i]</literal>,
+                                alors que <literal>[2 1 + %i]</literal> sera
+                                compris comme <literal>[2, 1+%i]</literal>.
+                                </note>
+                            </listitem>
+                            <listitem>les points-virgules ou les changements de
+                            lignes sont utilisés comme séparateurs de lignes.
+                            Pour peu que la ligne courante soit complète, le
+                            passage à la ligne ne pré-requiert pas les points de
+                            poursuite-à-la-ligne <literal>..</literal>.
+                            </listitem>
+                        </itemizedlist>
+                    </para>
+                    <refsect3 id="brackets_Types_conversions">
+                        <title>Transtypages</title>
+                        <para>
+                            Avec quelques restrictions, les crochets peuvent être
+                            utilisés sur une série de valeurs ayant des types distincts
+                            mais compatibles. Des valeurs sont alors converties
+                            de proche en proche dans le type de données dominant.
+                            Les principales règles de conversion implicite sont
+                            les suivantes :
+                            <orderedlist>
+                                <listitem>booléen &lt; nombre décimal &lt; nombre complexe
+                                </listitem>
+                                <listitem>décimal &lt; polynôme &lt; fraction rationelle
+                                    <warning>Les booléens et les polynômes ne sont pas
+                                        compatibles entre eux :
+                                        <itemizedlist>
+                                            <listitem>
+                                                <literal>[%t 2. %z]</literal> est accepté, car :
+                                                <literal>[%t 2.]</literal> est d'abord
+                                                converti en
+                                                <literal>[1. 2.]</literal>, puis
+                                                <literal>[[1. 2.] %z]</literal> est
+                                                accepté.
+                                            </listitem>
+                                            <listitem>
+                                                <literal>[%z %t 2.]</literal> est
+                                                refusé et produit une erreur.
+                                                En effet, <literal>[%z %t]</literal>
+                                                n'est pas permis et bloque la suite.
+                                            </listitem>
+                                        </itemizedlist>
+                                    </warning>
+                                </listitem>
+                                <listitem>
+                                    Le résultat est encodé en valeurs complexes (avec
+                                    parties imaginaires éventuellement nulles) dés qu'un
+                                    élément -- valeur, polynôme, ou fraction rationnelle --
+                                    à valeur complexe est rencontré.
+                                    <para>De même, le résultat est encodé sous forme
+                                    creuse
+                                    dés qu'un élément encodé creux est rencontré.
+                                    </para>
+                                </listitem>
+                                <listitem>
+                                    Des polynômes ou des fractions rationnelles
+                                    de différentes variables peuvent
+                                    être concaténés entre eux. Le premier polynôme
+                                    ou fraction rationnelle listé donne alors le
+                                    nom de sa variable au résultat de la concaténation :
+                                    <literal>[%z, 1+%s, 1-%i*%s]
+                                        // => [z, 1+z, 1-iz]
+                                    </literal>.
+                                </listitem>
+                                <listitem>
+                                    Tout entier encodé peut être concaténé uniquement
+                                    avec d'autres entiers du même type entier
+                                    (<link linkend="inttype">inttype</link>). Ainsi,
+                                    les expressions
+                                    <literal>[%t int8(2)]</literal>,
+                                    <literal>[int8(2) uint8(7)]</literal>,
+                                    <literal>[int8(2) int16(7)]</literal>,
+                                    <literal>[int8(2) 1.]</literal> produiront
+                                    toutes une erreur.
+                                </listitem>
+                                <listitem>Les éléments de texte (type "string") peuvent
+                                être concaténés (au sens ensembliste, avec les crochets)
+                                uniquement entre eux ou avec la matrice vide
+                                <literal>[]</literal>.
+                                </listitem>
+                            </orderedlist>
+                        </para>
+                    </refsect3>
+                    <refsect3 id="brackets_overloading">
+                        <title>Surcharge</title>
+                        <para>
+                            <itemizedlist>
+                                <listitem>[,]: concaténation horizontale :
+                                    cet opérateur n-aire (pouvant être appliqué à un
+                                    nombre arbitraire n de données) est en fait un
+                                    opérateur binaire automatiquement itéré de la
+                                    gauche vers la droite. Son code de surcharge est
+                                    <literal>"c"</literal>.
+                                </listitem>
+                                <listitem>[;]: la concaténation verticale est
+                                    également un opérateur binaire, itéré du haut
+                                    vers le bas. Son code de surcharge est
+                                    <literal>"f"</literal>.
+                                </listitem>
+                            </itemizedlist>
+                        </para>
+                    </refsect3>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>[] figurant à gauche d'une affectation <literal>"="</literal></term>
+                <listitem>
+                    <para>
+                    Dans ce cas, les crochets ne désignent en rien une concaténation.
+                    Ils délimitent une série de variables servant de récipients.
+                    </para>
+                    <para>
+                        <itemizedlist>
+                            <listitem>Les termes entre crochets doivent alors
+                                impérativement être des variables. Les expressions
+                                litérales ou symboliques sont rejetées.
+                            </listitem>
+                            <listitem>Les variables sont séparées par des virgules
+                              ou des espaces. Lorsqu'il s'agit de la liste des
+                              arguments de sortie d'une function, les virgules
+                              sont obligatoires.
+                            </listitem>
+                            <listitem>Dans une affectation distributive, il doit
+                                y avoir <emphasis role="italic">au plus</emphasis>
+                                autant de récipients que de sources de données
+                                provenant du terme de droite, pas plus. S'il y
+                                moins de récipients à gauche que de sources à droite,
+                                les sources non collectées sont ignorées. Exemples :
+                                <simplelist>
+                                    <member><literal>[a,b] = (%pi,"Hi", %z)</literal>
+                                        est correct, mais <literal>%z</literal>
+                                        sera ignoré.
+                                    </member>
+                                    <member><literal>[a,b,c] = (%pi,"Hi")</literal>
+                                        produit une erreur, car <literal>c</literal>
+                                        attend du contenu.
+                                    </member>
+                                </simplelist>                            </listitem>
+                            <listitem>La même variable peut être utilisée plusieurs
+                                fois dans la liste de gauche entre crochets.
+                                Le cas échéant, les affectations successives réalisées
+                                de gauche à droite dans la liste écrasent les contenus
+                                pré-existants. Exemple :
+                                <literal>[a,b,a]=(%pi,%z,"Allo")</literal>
+                                est équivalent à <literal>a="Allo", b=%z</literal>.
+                            </listitem>
+                        </itemizedlist>
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
     </refsection>
-    <refsection>
+    <refsection role="examples">
         <title>Exemples</title>
         <programlisting role="example"><![CDATA[
-[6.9,9.64; sqrt(-1) 0]
-[1 +%i  2 -%i  3]
-[]
-['ceci est';'un vecteur';'de chaines de caracteres']
-s=poly(0,'s');[1/s,2/s]
+// Concaténation horizontale
+a = [ %pi 4 -1 ]
+b1 = grand(3,4,"uin",0,10)
+b2 = grand(3,2,"uin",0,10)
+b = [b1 b2]  // b1, b2.. doivent avoir le même nombre de lignes
+
+// Concaténation verticale
+a = [-2 ; 10 ; 7]
+
+b1 = grand(2,4,"uin",0,10)
+b2 = grand(3,4,"uin",0,10)
+b = [b1 ; b2] // // b1, b2.. doivent avoir le même nombre de colonnes
+
+// Double concaténation horizontale et verticale
+a = [ 3 7 ; 6, 5 ]
+b = [ 1:3 ; 7:3:13]
+c = [ a b ; a b]
+
+d = [ 3 5
+      1 4
+    ]
+e = [ d d d
+      d d d
+    ]
+// Concaténation de types d'objets variés :
+['this is' ; 'a column' ; 'of texts']
+
+s = poly(0,'s');[1/s,2/s]
 [tf2ss(1/s),tf2ss(2/s)]
 
-[u,s]=schur(rand(3,3))
+[%t %f %f %T %F]
+
+// Concaténation d'objets de types compatibles différents, avec transtypages automatiques
+[%T %pi %f 2]
+[%pi, 2+%i, %F]
+v = [%pi+0*%i, %F, %z, (1-%z)^2 ]; typeof(v), isreal(v)
+v = [10 1/%z], typeof(v)
+
+// Concaténations hétérogènes d'objets de types incompatibles => ERREURS
+[%F %z]
+[%F int8(5)]
+[int8(%pi) uint8(%e)]
+[int8(%pi) int16(%e)]
  ]]></programlisting>
+
+        <para>
+            <emphasis role="bold">Affectations distributives :</emphasis>
+        </para>
+        <programlisting role="example"><![CDATA[
+// Variables des réponses d'une function.
+// Elles sont le plus souvent optionnelles, l'une après l'autre
+M = rand(3,3);
+[u, s] = schur(M) // Nous attendons et utilisons à la fois u et s
+u = schur(M)      // Nous attendons et stockons uniquement u
+
+// Liste directe (implicite) d'objets à affecter
+[a, b, c] = (%pi, %t, "test")
+[a, b] = (%e, %f, "Hello")
+[a, b, a] = (%pi, %t, "test");
+
+// Liste explicite d'objets à affecter
+L = list(%z, %i, %t, %pi, "Text");
+[a, b, c] = L(:)
+
+// Tableau de structures :
+// Sélection de certaines cellules et affectation de leurs contenus
+s(2,3).r = %pi; s(2,1).r = %i; s(2,2) = %e;
+s(2,:).r
+s.r([2 4 6])
+[a, b, c] = s.r([2 4 6])
+
+// Expressions gauches interdites et rejetées (=> erreur)
+[m, n, m+n] = myfun(a,b) // "m+n" est une expression, non un nom de variable.
+[p, 4.5, q] = myfun(a,b) // "4.5 est une valeur littérale, non un nom de variable.
+[r, s+3 ] = myfun(a,b)   // "s+3" est une expression mixte, non un nom de variable
+ ]]></programlisting>
+        <screen><![CDATA[--> [a, b, c] = (%pi, %t, "test")
+ c  =
+ test
+
+ b  =
+  T
+
+ a  =
+   3.1415927
+
+--> [a, b] = (%e, %f, "Hello")
+ b  =
+  F
+
+ a  =
+   2.7182818
+
+--> [a, b, a] = (%pi, %t, "test"); a
+ a  =
+   3.1415927
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>Voir aussi</title>
         <simplelist type="inline">
             <member>
+                <link linkend="empty">empty</link>
+            </member>
+            <member>
                 <link linkend="parentheses">parentheses</link>
             </member>
             <member>
+                <link linkend="lstcat">lstcat</link>
+            </member>
+            <member>
                 <link linkend="comma">comma</link>
             </member>
             <member>
                 <link linkend="semicolon">semicolon</link>
             </member>
+            <member>
+                <link linkend="overloading">overloading</link>
+            </member>
         </simplelist>
     </refsection>
+    <refsection role="history">
+        <title>Historique</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.0</revnumber>
+                <revdescription>
+                    Crochets <literal>[..]</literal> et accolades
+                    <literal>{..}</literal> ont désormais des fonctions distinctes.
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>
diff --git a/scilab/modules/core/help/ja_JP/1_keywords/brackets.xml b/scilab/modules/core/help/ja_JP/1_keywords/brackets.xml
deleted file mode 100644 (file)
index fc57956..0000000
+++ /dev/null
@@ -1,147 +0,0 @@
-<?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="brackets">
-    
-    <refnamediv>
-        
-        <refname>brackets</refname>
-        
-        <refpurpose>([,]) 左および右括弧</refpurpose>
-        
-    </refnamediv>
-    
-    <refsynopsisdiv>
-        
-        <title>呼び出し手順</title>
-        
-        <synopsis>[a11,a12,...;a21,a22,...;...]
-            
-            [s1,s2,...]=func(...)
-            
-        </synopsis>
-        
-    </refsynopsisdiv>
-    
-    <refsection>
-        
-        <title>引数</title>
-        
-        <variablelist>
-            
-            <varlistentry>
-                
-                <term>a11,a12,...  </term>
-                
-                <listitem>
-                    
-                    <para>
-                        
-                        適当な次元の行列 (実数, 多項式, 有理,<literal>syslin</literal>
-                        
-                        リスト...) 
-                        
-                    </para>
-                    
-                </listitem>
-                
-            </varlistentry>
-            
-            <varlistentry>
-                
-                <term>s1,s2,...  </term>
-                
-                <listitem>
-                    
-                    <para>任意の変数名</para>
-                    
-                </listitem>
-                
-            </varlistentry>
-            
-        </variablelist>
-        
-    </refsection>
-    
-    <refsection>
-        
-        <title>説明</title>
-        
-        <para>
-            
-            左および右括弧はベクトルおよび行列を結合する
-            
-            する際に使用されます.
-            
-            これらの記号は関数コールにおいて複数の左辺値を定義する際に
-            
-            使用されます.
-            
-        </para>
-        
-        <para>
-            
-            括弧の組の内部では,空白またはカンマ文字は
-            
-            "列結合"を意味し,セミコロンおよびキャレッジリターンは
-            
-            "行結合"を意味します.
-            
-        </para>
-        
-        <para>
-            
-            注意 : 混乱を避けるため,列を区切るために空白ではなくカンマを使用する
-            
-            方がより安全です.
-            
-        </para>
-        
-        <para>
-            
-            複数の lhs 括弧の中の変数名はカンマで区切る必要があります.
-            
-        </para>
-        
-    </refsection>
-    
-    <refsection>
-        
-        <title>例</title>
-        
-        <programlisting role="example"><![CDATA[ 
-[6.9,9.64; sqrt(-1) 0]
-[1 +%i  2 -%i  3]
-[]
-['this is';'a string';'vector']
-s=poly(0,'s');[1/s,2/s]
-[tf2ss(1/s),tf2ss(2/s)]
-
-[u,s]=schur(rand(3,3))
- ]]></programlisting>
-        
-    </refsection>
-    
-    <refsection role="see also">
-        
-        <title>参照</title>
-        
-        <simplelist type="inline">
-            
-            <member>
-                
-                <link linkend="comma">comma</link>
-                
-            </member>
-            
-            <member>
-                
-                <link linkend="semicolon">semicolon</link>
-                
-            </member>
-            
-        </simplelist>
-        
-    </refsection>
-    
-</refentry>
-
diff --git a/scilab/modules/core/help/ru_RU/1_keywords/brackets.xml b/scilab/modules/core/help/ru_RU/1_keywords/brackets.xml
deleted file mode 100644 (file)
index 1af6036..0000000
+++ /dev/null
@@ -1,76 +0,0 @@
-<?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="brackets">
-    <refnamediv>
-        <refname>квадратные скобки</refname>
-        <refpurpose>([, ]) левые и правые квадратные скобки</refpurpose>
-    </refnamediv>
-    <refsynopsisdiv>
-        <title>Синтаксис</title>
-        <synopsis>[a11,a12,...;a21,a22,...;...]
-            [s1,s2,...]=func(...)
-        </synopsis>
-    </refsynopsisdiv>
-    <refsection>
-        <title>Аргументы</title>
-        <variablelist>
-            <varlistentry>
-                <term>a11,a12,...  </term>
-                <listitem>
-                    <para>
-                        любая матрица (вещественная, полиномиальная, рациональная, список <literal>syslin</literal> ...) соответствующих размеров
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>s1,s2,...  </term>
-                <listitem>
-                    <para>любое возможное имя переменной</para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>Описание</title>
-        <para>
-            Левая и правая скобки используются для обозначения конкатенации векторов и матриц. Эти символы также используются для обозначения
-            множественных выходных данных вызова функции.
-        </para>
-        <para>
-            Внутри скобок конкатенации символы пробела или запятой означают "конкатенацию столбцов", точка с запятой и возврат каретки означают
-            "конкатенацию строк".
-        </para>
-        <para>
-            Примечание: чтобы избежать проблем, для разделения столбцов безопаснее использовать запятые вместо пробелов.
-        </para>
-        <para>
-            Внутри скобок, объединяющих выходные переменные функции, имена переменных должны быть разделены запятыми.
-        </para>
-    </refsection>
-    <refsection>
-        <title>Примеры</title>
-        <programlisting role="example"><![CDATA[
-[6.9,9.64; sqrt(-1) 0]
-[1 +%i  2 -%i  3]
-[]
-['this is';'a string';'vector']
-s=poly(0,'s');[1/s,2/s]
-[tf2ss(1/s),tf2ss(2/s)]
-
-[u,s]=schur(rand(3,3))
- ]]></programlisting>
-    </refsection>
-    <refsection role="see also">
-        <title>Смотрите также</title>
-        <simplelist type="inline">
-            <member>
-                <link linkend="parentheses">круглые скобки</link>
-            </member>
-            <member>
-                <link linkend="comma">запятая</link>
-            </member>
-            <member>
-                <link linkend="semicolon">точка с запятой</link>
-            </member>
-        </simplelist>
-    </refsection>
-</refentry>