* Bug 11888 fixed [doc]: struct() page overhauled for struct arrays 60/21660/3
Samuel GOUGEON [Mon, 28 Dec 2020 00:46:54 +0000 (01:46 +0100)]
  http://bugzilla.scilab.org/11888

  struct() page overhaulded (en_US PDF): http://bugzilla.scilab.org/attachment.cgi?id=5205

Change-Id: Ib0231567e6184a98e2e339f0bfffa41bff580068

scilab/CHANGES.md
scilab/modules/data_structures/help/en_US/struct.xml
scilab/modules/data_structures/help/fr_FR/struct.xml [deleted file]
scilab/modules/data_structures/help/ja_JP/struct.xml [deleted file]
scilab/modules/data_structures/help/pt_BR/struct.xml [deleted file]
scilab/modules/data_structures/help/ru_RU/struct.xml

index 26eaf08..7349040 100644 (file)
@@ -322,6 +322,7 @@ Bug Fixes
 * [#10490](https://bugzilla.scilab.org/10490): The `mapsound` page was poor with a single interesting example.
 * [#11600](https://bugzilla.scilab.org/11600): `rand()` was parsing its inputs incorrectly.
 * [#11677](https://bugzilla.scilab.org/11677): The original Arnoldi functions were obsolete.
+* [#11888](https://bugzilla.scilab.org/11888): The `struct` page did not document how to build an array of structures.
 * [#12418](https://bugzilla.scilab.org/12418): Using bvode() with "continuation", i.e. `ipar(9) > 1` led to an error.
 * [#12516](https://bugzilla.scilab.org/12516): From `browsevar`, clicking on any graphical handle did not edit its figure with `ged`.
 * [#12532](https://bugzilla.scilab.org/12532): From `browsevar`, clicking on any function did not edit it with `edit`. The content of libraries could not be displayed either.
index 1e85ca3..0394c38 100644 (file)
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) 2006-2008 - INRIA
- *
+ * Copyright (C) 2006 - 2008 - INRIA
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2020 - Samuel GOUGEON
  *
  * 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.
  * 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="struct">
+<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="en" xml:id="struct">
     <refnamediv>
         <refname>struct</refname>
-        <refpurpose>create a struct</refpurpose>
+        <refpurpose>Builds a structure or an array of structures</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
-        <synopsis>st = struct(field1, value1, field2, value2, ...)</synopsis>
+        <synopsis>
+            st = struct(field1, value1, field2, value2, ...)
+        </synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Arguments</title>
             <varlistentry>
                 <term>field1, field2, ...</term>
                 <listitem>
-                    <para>strings representing the fields names.</para>
+                    strings: Case-sensitive names of the fields of the structure.
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>value1, value2, ...</term>
                 <listitem>
                     <para>
-                        all data type (<literal>double</literal>, <literal>char</literal>, <literal>int</literal>, ...), representing the fields values.
+                        Data assigned to the respective fields. All data types are supported.  
+                    </para>
+                    <para/>
+                    <para>
+                        If several values are non-scalar cells arrays, then they must have the same size.
+                        For any scalar cell, the cell's container is stripped off, and its content
+                        is considered and assigned to the field as a whole. The processing of non-scalar
+                        cells is described here-below.
                     </para>
+                    <para/>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>st</term>
+                <listitem>
+                    Scalar structure, or array of structures if at least one value is a non-scalar
+                    cells array.
+                    <para/>
                 </listitem>
             </varlistentry>
         </variablelist>
     </refsection>
     <refsection>
         <title>Description</title>
+        <refsect3>
+            <title>Scalar structure</title>
+            <para>
+                <emphasis role="bold">If none of values <literal>value1</literal>,
+                <literal>value2</literal>, ..., <literal>valueN</literal> is a non-scalar
+                cells array</emphasis>,
+                <literal>st = struct(field1, value1, field2, value2, ...)</literal> builds
+                a scalar structure <varname>st</varname> (of size 1×1) with fields and values
+                <literal>st.field1=value1</literal>, <literal>st.field2=value2</literal>, ...,
+                <literal>st.fieldN=valueN</literal>.
+            </para>
+            <para>
+                The value of any field of such a scalar structure can be a scalar or an array.
+                The sizes of values of distinct fields can be distinct. Example:
+                <literal>st = struct("u",[2 3], "v",[%t %f ; %f %t], "w","Hello")</literal> is
+                perfectly allowed and sets <literal>st.u=[2 3]</literal>,
+                <literal>st.v=[%t %f ; %f %t]</literal>, and <literal>st.w="Hello"</literal>
+            </para>
+            <para>
+                It is possible to assign a scalar or non-scalar cells array to the field of a
+                scalar structure by embedding it in a scalar cell. Examples:
+                <literal>st = struct("num",1:3, "c",{{sin}})</literal> will set
+                <literal>st.num=1:3</literal> and <literal>st.c={sin}</literal> ; while
+                <literal>st = struct("text","Hello", "test",{{1, sin ; %t %z}})</literal> will set
+                <literal>st.text="Hello"</literal> and <literal>st.test={1,sin;%t,%z}</literal>.
+            </para>
+        </refsect3>
+        <refsect3>
+            <title>Array of structures</title>
+            <para>
+                struct(..) allows to build any array -- vector, matrix or ND-array -- of structures.
+                All elements of the array have then the same set of fields <varname>field1</varname>,
+                <varname>field2</varname>, .., <varname>fieldN</varname>.
+            </para>
+            <para>
+                Indeed, <emphasis role="bold">when at least one of the given values is a non-scalar
+                cells array</emphasis>
+                <literal>C</literal>, <literal>st=struct(..,field,C,..)</literal> builds an array
+                of structures with <literal>size(st)==size(C)</literal>, and sets
+                <literal>st(i).field=C{i}</literal> for any index i.
+            </para>
+            <para>
+                In this case, any scalar values defined for some other specified fields are
+                replicated and set for all <varname>st</varname> elements.
+            </para>
+            <para>
+                Example #1: <literal>st=struct("u", {-1,%f,%z})</literal> defines a 1×3 row vector
+                of structures with a single field "u" with values <literal>st(1).u=-1</literal>,
+                <literal>st(2).u=%f</literal>, and <literal>st(3).u=%z</literal>.
+            </para>
+            <para>
+                Example #2: <literal>st=struct("u", {-1 ; %f}, "t", "Hi")</literal> defines a 2×1
+                column vector of structures with two fields "u" and "t" with values
+                <literal>st(1,1).u=-1</literal>, <literal>st(1,1).t="Hi"</literal>,
+                <literal>st(2,1).u=%f</literal>, <literal>st(2,1).t="Hi"</literal>.
+            </para>
+        </refsect3>
+        <note>
+            <literal>type(st)</literal> returns <literal>17</literal>,
+            and <literal>typeof(st)</literal> returns <literal>"st"</literal>.
+        </note>
+    </refsection>
+    <refsection>
+        <title>Examples</title>
+        <programlisting role="example"><![CDATA[
+// Create a scalar Dates structure
+Dates = struct('day',25, 'month','DEC', 'year',2006)
+Dates.month = 'AUG'         // change the month
+Dates.year  = 1973;         // change the year
+Dates.weekday = "Saturday"  // Add a new field
+
+// Create a 2nd element, to make Dates a vector of dates:
+Dates(1,2).year = 2020
+Dates(2) // Note that the default fields value is []
+
+// Building the full Dates(2) structure element for all fields.
+// The same fields can be declared in any other order:
+Dates(2) = struct('year',2000, 'day',29, 'weekday',"Tuesday", 'month', "FEB")
+Dates(2)
+Dates(2,3) = struct('weekday',"Sunday", 'day',7, 'month',"FEB", 'year',2021)
+Dates(2,3)
+size(Dates)
+length(Dates)
+     ]]></programlisting>
+        <screen><![CDATA[
+--> Dates = struct('day',25, 'month','DEC', 'year',2006)
+ Dates  =
+  day = 25
+  month = "DEC"
+  year = 2006
+
+--> Dates.month = 'AUG'         // change the month
+ Dates  =
+  day = 25
+  month = "AUG"
+  year = 2006
+
+--> Dates.year  = 1973;         // change the year
+--> Dates.weekday = "Saturday"  // Add a new field
+ Dates  =
+  day = 25
+  month = "AUG"
+  year = 1973
+  weekday = "Saturday"
+
+--> // Create a 2nd element, to make Dates a vector of dates:
+--> Dates(1,2).year = 2020
+ Dates  =
+  1x2 struct with fields:
+  ["day", "month", "year", "weekday"]
+
+--> Dates(2) // Note that the default fields value is []
+ ans  =
+  day = []
+  month = []
+  year = 2020
+  weekday = []
+
+--> // Building the full Dates(2) structure element for all fields.
+--> // The same fields can be declared in any other order:
+--> Dates(2) = struct('year',2000, 'day',29, 'weekday',"Tuesday", 'month', "FEB")
+ Dates  =
+  1x2 struct with fields:
+  ["day", "month", "year", "weekday"]
+
+--> Dates(2)
+ ans  =
+  day = 29
+  month = "FEB"
+  year = 2000
+  weekday = "Tuesday"
+
+--> Dates(2,3) = struct('weekday',"Sunday", 'day',7, 'month',"FEB", 'year',2021)
+ Dates  =
+  2x3 struct with fields:
+  ["day", "month", "year", "weekday"]
+
+--> Dates(2,3)
+ ans  =
+  day = 7
+  month = "FEB"
+  year = 2021
+  weekday = "Sunday"
+
+--> size(Dates)
+ ans  =
+   2.   3.
+
+--> length(Dates)
+ ans  =
+   6.
+]]></screen>
         <para>
-            This function returns a struct with the fields names
-            <varname>field1</varname>, <varname>field2</varname>, ..., and the fields values
-            corresponding <varname>value1</varname>, <varname>value2</varname>, ...
+            <emphasis role="bold">Array of structures built from scratch:</emphasis>
         </para>
+        <programlisting role="example"><![CDATA[
+Dates = struct("day",{10 3 ; 25 17}, "month",{"SEP" "JUN" ; "APR" "NOV"}, "year",2020)
+Dates(2,1)
+     ]]></programlisting>
+        <screen><![CDATA[
+--> Dates = struct("day",{10 3 ; 25 17}, "month",{"SEP" "JUN" ; "APR" "NOV"}, "year",2020)
+ Dates  =
+  2x2 struct with fields:
+  ["day", "month", "year"]
+
+--> Dates(2,1)
+ ans  =
+  day = 25
+  month = "APR"
+  year = 2020
+]]></screen>
         <para>
-            Note that <literal>type(st)</literal> returns <literal>17</literal>, and <literal>typeof(st)</literal> returns <literal>st</literal>.
+            <emphasis role="bold">Structure with cells as a field's value:</emphasis>
         </para>
-    </refsection>
-    <refsection>
-        <title>Examples</title>
         <programlisting role="example"><![CDATA[
-//create a struct date
-date_st=struct('day',25,'month' ,'DEC','year',2006)
-//change the month
-date_st.month='AUG';
-//change the year
-date_st.year=1973;
-//change the day
-date_st.day=19;
-//add a new field
-date_st.semaine=32
+test = struct("number", %pi, "bool",[%f %f], "myCell",{{2 "-5";(1-%z)^3,%t}})
+test.myCell
+test.myCell{2,1}
+     ]]></programlisting>
+        <screen><![CDATA[
+--> test = struct("number", %pi, "bool",[%f %f], "myCell",{{2 "-5";(1-%z)^3,%t}})
+ test  =
+  number = 3.1415927
+  bool = [%f,%f]
+  myCell: [2x2 cell]
+
+--> test.myCell
+ ans  =
+  [1x1 constant  ]  [1x1 string ]
+  [1x1 polynomial]  [1x1 boolean]
 
-//create a structure test
-test=struct('list1',list('testlist',1,2), 'matrix1', [1 2 3; 4 5 6], 'boolean1', %t);
-//add a polynom
-s=poly(0,'s')
-test.pol1=s;
-//add a state-space
-A=[0,1;0,0]; B=[1;1];C=[1,1];
-test.ss1=syslin('c',A,B,C);
-//Show the list
-test.list1
-getfield(3,test)
-//Show the type
-type(test)
- ]]></programlisting>
+--> test.myCell{2,1}
+ ans  =
+  1 -3z +3z² -z³
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
         <simplelist type="inline">
             <member>
-                <link linkend="cell">cell</link>
+                <link linkend="fieldnames">fieldnames</link>
             </member>
             <member>
-                <link linkend="mlist">mlist</link>
+                <link linkend="tree_show">tree_show</link>
             </member>
             <member>
-                <link linkend="tlist">tlist</link>
+                <link linkend="makecell">makecell</link>
             </member>
             <member>
-                <link linkend="getfield">getfield</link>
+                <link linkend="mlist">mlist</link>
             </member>
             <member>
-                <link linkend="setfield">setfield</link>
+                <link linkend="tlist">tlist</link>
             </member>
         </simplelist>
     </refsection>
diff --git a/scilab/modules/data_structures/help/fr_FR/struct.xml b/scilab/modules/data_structures/help/fr_FR/struct.xml
deleted file mode 100644 (file)
index 6415406..0000000
+++ /dev/null
@@ -1,91 +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="fr" xml:id="struct">
-    <refnamediv>
-        <refname>struct</refname>
-        <refpurpose>creer une struct</refpurpose>
-    </refnamediv>
-    <refsynopsisdiv>
-        <title>Séquence d'appel</title>
-        <synopsis>st=struct(field1,value1,field2,value2, ...)</synopsis>
-    </refsynopsisdiv>
-    <refsection>
-        <title>Paramètres</title>
-        <variablelist>
-            <varlistentry>
-                <term>field1, field2, ...</term>
-                <listitem>
-                    <para>noms des champs (chaines de caracteres)</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>value1, value2, ...</term>
-                <listitem>
-                    <para>les valeurs des champs (acceptent tous types de données
-                        (double, matrice de doubles,des cells, char, ...)
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>Description</title>
-        <para>
-            La fonction <function>struct</function> retourne une struct avec des noms de
-            champs <varname>field1</varname>, <varname>field2</varname>, .., et dont les valeurs
-            respectives sont <varname>value1</varname>, <varname>value2</varname>,
-            ...
-        </para>
-        <para>
-            Notez que <literal>type(st)</literal> retourne <literal>17</literal> et que <literal>typeof(st)</literal> retourne <literal>st</literal>.
-        </para>
-    </refsection>
-    <refsection>
-        <title>Exemples</title>
-        <programlisting role="example"><![CDATA[
-//creer une struct: date les champs sont: 'jour' (valeur: 25), 'mois' (valeur: 'DEC'), 'annee' (valeur: 2006)
-date_st=struct('jour',25,'mois','DEC','annee',2006)
-
-// changer la valeur des champs
-date_st.jour=19;
-date_st.mois='AOU';
-date_st.annee=1973;
-
-// ajouter un champ 'semaine'
-date_st.semaine=32
-
-//creation d'une structure test
-test=struct('list1',list('testlist',1,2), 'matrix1', [1 2 3; 4 5 6], 'boolean1', %t);
-//ajout d'un polynôme
-s=poly(0,'s')
-test.pol1=s;
-//ajout d'un système linéaire (représentation d'état)
-A=[0,1;0,0]; B=[1;1];C=[1,1];
-test.ss1=syslin('c',A,B,C);
-//Affichage de la liste
-test.list1
-getfield(3,test)
-//Affichage du type
-type(test)
- ]]></programlisting>
-    </refsection>
-    <refsection role="see also">
-        <title>Voir aussi</title>
-        <simplelist type="inline">
-            <member>
-                <link linkend="cell">cell</link>
-            </member>
-            <member>
-                <link linkend="mlist">mlist</link>
-            </member>
-            <member>
-                <link linkend="tlist">tlist</link>
-            </member>
-            <member>
-                <link linkend="getfield">getfield</link>
-            </member>
-            <member>
-                <link linkend="setfield">setfield</link>
-            </member>
-        </simplelist>
-    </refsection>
-</refentry>
diff --git a/scilab/modules/data_structures/help/ja_JP/struct.xml b/scilab/modules/data_structures/help/ja_JP/struct.xml
deleted file mode 100644 (file)
index f5115ce..0000000
+++ /dev/null
@@ -1,73 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) 2006-2008 - INRIA
- *
- * 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="ja" xml:id="struct">
-    <refnamediv>
-        <refname>struct</refname>
-        <refpurpose>構造体を作成する</refpurpose>
-    </refnamediv>
-    <refsynopsisdiv>
-        <title>呼び出し手順</title>
-        <synopsis>st=struct(field1,value1,field2,value2...)</synopsis>
-    </refsynopsisdiv>
-    <refsection>
-        <title>パラメータ</title>
-        <variablelist>
-            <varlistentry>
-                <term>field1, field2, ..</term>
-                <listitem>
-                    <para>フィールド名を表す文字列</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>value1, value2, ..</term>
-                <listitem>
-                    <para>フィールドの値を表すデータ型 (double, char, int, ...)</para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>説明</title>
-        <para>この関数はフィールド名
-            <literal>fields1</literal>, <literal>field2</literal>, ..., を有し,
-            その値が<literal>value1</literal>, <literal>value2</literal>, ...
-            となる構造体を返します.
-        </para>
-    </refsection>
-    <refsection>
-        <title>例</title>
-        <programlisting role="example"><![CDATA[
-// create a struct date
-date=struct('day',25,'month' ,'DEC','year',2006)
-//change the month
-date.month='AUG';
-// change the year
-date.year=1973;
-//change the day
-date.day=19;
-// add a new field
-date.semaine=32
- ]]></programlisting>
-    </refsection>
-    <refsection role="see also">
-        <title>参照</title>
-        <simplelist type="inline">
-            <member>
-                <link linkend="cell">cell</link>
-            </member>
-        </simplelist>
-    </refsection>
-</refentry>
diff --git a/scilab/modules/data_structures/help/pt_BR/struct.xml b/scilab/modules/data_structures/help/pt_BR/struct.xml
deleted file mode 100644 (file)
index 65923d8..0000000
+++ /dev/null
@@ -1,79 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) 2006-2008 - INRIA
- *
- * 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:ns4="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="struct" xml:lang="pt">
-    <refnamediv>
-        <refname>struct</refname>
-        <refpurpose>criando um struct (estrutura)</refpurpose>
-    </refnamediv>
-    <refsynopsisdiv>
-        <title>Seqüência de Chamamento</title>
-        <synopsis>st=struct(field1,value1,field2,value2...)</synopsis>
-    </refsynopsisdiv>
-    <refsection>
-        <title>Parâmetros</title>
-        <variablelist>
-            <varlistentry>
-                <term>field1, field2, ..</term>
-                <listitem>
-                    <para>strings, representam os nomes dos campos</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>value1, value2, ..</term>
-                <listitem>
-                    <para>todos os tipos de dados (double, char, int, ...), representam
-                        os valores dos campos
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>Descrição</title>
-        <para>Esta função retorna uma estrutura com campos de nomes
-            <literal>fields1</literal>, <literal>field2</literal>, ..., e valores
-            correspondentes <literal>value1</literal>, <literal>value2</literal>,
-            ...
-        </para>
-    </refsection>
-    <refsection>
-        <title>Exemplos</title>
-        <programlisting role="example"><![CDATA[
-// criando um dado struct
-date_st=struct('dia',25,'mes' ,'DEZ','ano',2006)
-
-//mudando o mes
-date_st.mes='AGO';
-
-// mudando o ano
-date_st.ano=1973;
-
-//mudando o dia
-date_st.dia=19;
-
-// adicionando um novo campo
-date_st.semana=32
- ]]></programlisting>
-    </refsection>
-    <refsection role="see also">
-        <title>Ver Também</title>
-        <simplelist type="inline">
-            <member>
-                <link linkend="cell">cell</link>
-            </member>
-        </simplelist>
-    </refsection>
-</refentry>
index 6ad5727..a76e7f6 100644 (file)
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) 2006-2008 - INRIA
- *
+ * Copyright (C) 2006 - 2008 - INRIA
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2020 - Samuel GOUGEON
  *
  * 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.
  * 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="ru" xml:id="struct">
+<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="ru" xml:id="struct">
     <refnamediv>
         <refname>struct</refname>
-        <refpurpose>создаёт структуру</refpurpose>
+        <refpurpose>строит структуру или массив структур</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Синтаксис</title>
-        <synopsis>st = struct(field1, value1, field2, value2, ...)</synopsis>
+        <synopsis>
+            st = struct(field1, value1, field2, value2, ...)
+        </synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Аргументы</title>
             <varlistentry>
                 <term>field1, field2, ...</term>
                 <listitem>
-                    <para>строки, представляющие имена полей.</para>
+                    строки: имена полей структуры с учётом регистра. Разрешены
+                    расширенные не-ascii UTF-символы.
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>value1, value2, ...</term>
                 <listitem>
-                    <para>
-                        все типы данных (<literal>double</literal>, <literal>char</literal>, <literal>int</literal>, ...), представляющие значения полей.
-                    </para>
+                    данные, присвоенные соответствующим полям. Поддерживаются все
+                    типы данных. Если несколько значений являются нескалярными
+                    cell-массивами, то они должны быть одинакового размера. Для
+                    любого cell-скаляра cell-контейнер удаляется и его содержимое
+                    рассматривается и присваивается полю как единое целое. Обработка
+                    cell-массивов описана ниже.
+                    <para/>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>st</term>
+                <listitem>
+                    скалярная структура или массив структур, если хотя бы одно
+                    значение является нескалярным cell-массивом.
+                    <para/>
                 </listitem>
             </varlistentry>
         </variablelist>
     </refsection>
     <refsection>
         <title>Описание</title>
-        <para>
-            Эта функция возвращает структуру с именами полей
-            <varname>fields1</varname>, <varname>field2</varname>, ..., и значениями полей, соответственно, <varname>value1</varname>, <varname>value2</varname>, ...
-        </para>
+        <refsect3>
+            <title>Скалярная структура</title>
+            <para>
+                <emphasis role="bold">Если ни одно из значений <literal>value1</literal>,
+                <literal>value2</literal>, ..., <literal>valueN</literal> не
+                является нескалярным cell-массивом</emphasis>, то
+                <literal>st = struct(field1, value1, field2, value2, ...)</literal> строит
+                скалярную структуру <varname>st</varname> (размером 1×1) с полями
+                и значениями <literal>st.field1=value1</literal>, 
+                <literal>st.field2=value2</literal>, ..., <literal>st.fieldN=valueN</literal>.
+            </para>
+            <para>
+                Значение любого поля такой скалярной структуры может быть скаляром
+                или массивом. Размеры значений разных полей могут быть разными.
+                Например:
+                <literal>st = struct("u",[2 3], "v",[%t %f ; %f %t], "w","Hello")</literal> 
+                совершенно допустимо и устанавливает <literal>st.u=[2 3]</literal>,
+                <literal>st.v=[%t %f ; %f %t]</literal> и <literal>st.w="Hello"</literal>.
+            </para>
+            <para>
+                Можно присвоить скалярные или нескалярные cell-массивы полю
+                скалярной структуры, встраивая её в скалярный cell-массив. Например:
+                <literal>st = struct("num",1:3, "c",{{sin}})</literal> установит
+                <literal>st.num=1:3</literal> и <literal>st.c={sin}</literal> ;
+                в то время, как
+                <literal>st = struct("text","Hello", "test",{{1, sin ; %t %z}})</literal> 
+                установит
+                <literal>st.text="Hello"</literal> и <literal>st.test={1,sin;%t,%z}</literal>.
+            </para>
+        </refsect3>
+        <refsect3>
+            <title>Массив структур</title>
+            <para>
+                struct(..) позволяет строить любой массив структур -- вектор,
+                матрицу или ND-массив. Все элементы массива имеют одинаковый набор
+                полей <varname>field1</varname>, <varname>field2</varname>, ..., 
+                <varname>fieldN</varname>.
+            </para>
+            <para>
+                Действительно, <emphasis role="bold">если хотя бы одно из указанных
+                значений является нескалярным cell-массивом</emphasis> <literal>C</literal>,
+                то <literal>st=struct(..,field,C,..)</literal> строит массив структур
+                с <literal>size(st)==size(C)</literal> и устанавливает
+                <literal>st(i).field=C{i}</literal> для любого индекса <literal>i</literal>.
+            </para>
+            <para>
+                В этом случае любые скалярные величины, определённые для других определённых
+                полей, копируются и устанавливаются для всех элементов <varname>st</varname>.
+            </para>
+            <para>
+                Пример №1: <literal>st=struct("u", {-1,%f,%z})</literal> определяет
+                вектор-строку 1×3 структур с единственным полем "u" со значениями
+                <literal>st(1).u=-1</literal>, <literal>st(2).u=%f</literal> и
+                <literal>st(3).u=%z</literal>.
+            </para>
+            <para>
+                Пример №2: <literal>st=struct("u", {-1 ; %f}, "t", "Hi")</literal> 
+                определяет вектор-столбец 2×1 структур с двумя полями "u" и "t"
+                со значениями  <literal>st(1,1).u=-1</literal>,
+                <literal>st(1,1).t="Hi"</literal>, <literal>st(2,1).u=%f</literal>,
+                <literal>st(2,1).t="Hi"</literal>.
+            </para>
+        </refsect3>
+        <note>
+            <literal>type(st)</literal> возвращает <literal>17</literal>,
+            а <literal>typeof(st)</literal> возвращает <literal>"st"</literal>.
+        </note>
     </refsection>
     <refsection>
         <title>Примеры</title>
         <programlisting role="example"><![CDATA[
-//создадим структуру данных
-date_st=struct('day',25,'month' ,'DEC','year',2006)
+// Создать скалярную структуру Dates
+Dates = struct('day',25, 'month','DEC', 'year',2006)
+Dates.month = 'AUG'         // изменить месяц
+Dates.year  = 1973;         // изменить год
+Dates.weekday = "Saturday"  // добавить новое поле
+
+// Создать второй элемент, чтобы сделать Dates вектором дат:
+Dates(1,2).year = 2020
+Dates(2) // Заметьте, что значение поля по умолчанию равно []
+
+// Построение элемента полной структуры Dates(2) для всех полей.
+// Одинаковые поля можно декларировать в любом порядке:
+Dates(2) = struct('year',2000, 'day',29, 'weekday',"Tuesday", 'month', "FEB")
+Dates(2)
+Dates(2,3) = struct('weekday',"Sunday", 'day',7, 'month',"FEB", 'year',2021)
+Dates(2,3)
+size(Dates)
+length(Dates)
+     ]]></programlisting>
+        <screen><![CDATA[
+--> Dates = struct('day',25, 'month','DEC', 'year',2006)
+ Dates  =
+  day = 25
+  month = "DEC"
+  year = 2006
 
-//изменим месяц
-date_st.month='AUG';
+--> Dates.month = 'AUG'         // change the month
+ Dates  =
+  day = 25
+  month = "AUG"
+  year = 2006
 
-//изменим год
-date_st.year=1973;
+--> Dates.year  = 1973;         // change the year
+--> Dates.weekday = "Saturday"  // Add a new field
+ Dates  =
+  day = 25
+  month = "AUG"
+  year = 1973
+  weekday = "Saturday"
 
-//изменим день
-date_st.day=19;
+--> // Create a 2nd element, to make Dates a vector of dates:
+--> Dates(1,2).year = 2020
+ Dates  =
+  1x2 struct with fields:
+  ["day", "month", "year", "weekday"]
 
-//добавим новое поле
-date_st.semaine=32
- ]]></programlisting>
+--> Dates(2) // Note that the default fields value is []
+ ans  =
+  day = []
+  month = []
+  year = 2020
+  weekday = []
+
+--> // Building the full Dates(2) structure element for all fields.
+--> // The same fields can be declared in any other order:
+--> Dates(2) = struct('year',2000, 'day',29, 'weekday',"Tuesday", 'month', "FEB")
+ Dates  =
+  1x2 struct with fields:
+  ["day", "month", "year", "weekday"]
+
+--> Dates(2)
+ ans  =
+  day = 29
+  month = "FEB"
+  year = 2000
+  weekday = "Tuesday"
+
+--> Dates(2,3) = struct('weekday',"Sunday", 'day',7, 'month',"FEB", 'year',2021)
+ Dates  =
+  2x3 struct with fields:
+  ["day", "month", "year", "weekday"]
+
+--> Dates(2,3)
+ ans  =
+  day = 7
+  month = "FEB"
+  year = 2021
+  weekday = "Sunday"
+
+--> size(Dates)
+ ans  =
+   2.   3.
+
+--> length(Dates)
+ ans  =
+   6.
+]]></screen>
+        <para>
+            <emphasis role="bold">Массив структур, построенный с нуля:</emphasis>
+        </para>
+        <programlisting role="example"><![CDATA[
+Dates = struct("day",{10 3 ; 25 17}, "month",{"SEP" "JUN" ; "APR" "NOV"}, "year",2020)
+Dates(2,1)
+     ]]></programlisting>
+        <screen><![CDATA[
+--> Dates = struct("day",{10 3 ; 25 17}, "month",{"SEP" "JUN" ; "APR" "NOV"}, "year",2020)
+ Dates  =
+  2x2 struct with fields:
+  ["day", "month", "year"]
+
+--> Dates(2,1)
+ ans  =
+  day = 25
+  month = "APR"
+  year = 2020
+]]></screen>
+        <para>
+            <emphasis role="bold">Структура с cell-массивами в качестве значения
+            полей:</emphasis>
+        </para>
+        <programlisting role="example"><![CDATA[
+test = struct("number", %pi, "bool",[%f %f], "myCell",{{2 "-5";(1-%z)^3,%t}})
+test.myCell
+test.myCell{2,1}
+     ]]></programlisting>
+        <screen><![CDATA[
+--> test = struct("number", %pi, "bool",[%f %f], "myCell",{{2 "-5";(1-%z)^3,%t}})
+ test  =
+  number = 3.1415927
+  bool = [%f,%f]
+  myCell: [2x2 cell]
+
+--> test.myCell
+ ans  =
+  [1x1 constant  ]  [1x1 string ]
+  [1x1 polynomial]  [1x1 boolean]
+
+--> test.myCell{2,1}
+ ans  =
+  1 -3z +3z² -z³
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>Смотрите также</title>
         <simplelist type="inline">
             <member>
-                <link linkend="cell">cell</link>
+                <link linkend="fieldnames">fieldnames</link>
+            </member>
+            <member>
+                <link linkend="tree_show">tree_show</link>
+            </member>
+            <member>
+                <link linkend="makecell">makecell</link>
+            </member>
+            <member>
+                <link linkend="mlist">mlist</link>
+            </member>
+            <member>
+                <link linkend="tlist">tlist</link>
             </member>
         </simplelist>
     </refsection>
 </refentry>
-