Revision of help pages for save_format (en_US, ru_RU). 11/11211/1
Stanislav KROTER [Wed, 3 Apr 2013 14:07:04 +0000 (20:07 +0600)]
Change-Id: I2aca082e91691b8c466115e87dee6945b162b89c

scilab/modules/fileio/help/en_US/save_format.xml
scilab/modules/fileio/help/ru_RU/save_format.xml

index 8de9de7..ec01d60 100644 (file)
@@ -22,8 +22,6 @@
         <para>The format is called SOD for Scilab Open Data.</para>
         <para>The first public release of SOD has been done with Scilab 5.4.0.</para>
     </refsection>
-    
-    
     <refsection>
         <title>Rationale</title>
         <para>Interoperability is one of the key aspects of modern software. In order to improve more and more this aspect, a standard definition of the HDF5 format is proposed in this SEP.</para>
@@ -46,7 +44,8 @@
                     <td>
                         <emphasis role="bold">double</emphasis>
                     </td>
-                    <programlisting>A=32;
+                    <programlisting>
+                        A=32;
                         b=[32,2];
                         c=[2,2;3,4];
                         d=rand(10,10);
                     <td>
                         <emphasis role="bold">string</emphasis>
                     </td>
-                    <programlisting>a=”my string”;
-                        b=[“string 1”;”my string 2”];
+                    <programlisting>
+                        a="my string";
+                        b=["string 1";"my string 2"];
                     </programlisting>
                 </tr>
                 <tr>
                     <td>
                         <emphasis role="bold">boolean</emphasis>
                     </td>
-                    <programlisting>a=%t;
+                    <programlisting>
+                        a=%t;
                         b=[%t, %f];
                     </programlisting>
                 </tr>
@@ -73,7 +74,8 @@
                         <emphasis role="bold">integer</emphasis>
                     </td>
                     <td>
-                        <programlisting>int8([1 -120 127 312])
+                        <programlisting>
+                            int8([1 -120 127 312])
                             x=int32(-200:100:400)
                         </programlisting>
                     </td>
                     </td>
                 </tr>
                 <tr>
-                    
-                    
                     <td>
                         <emphasis role="bold">sparse</emphasis>
                     </td>
                     <td align="justify">
-                        <programlisting>sp=sparse([1,2;4,5;3,10],[1,2,3])</programlisting>
+                        <programlisting>
+                            sp=sparse([1,2;4,5;3,10],[1,2,3])
+                        </programlisting>
                     </td>
                 </tr>
                 <tr>
                     <td>
                         <emphasis role="bold">boolean sparse</emphasis>
                     </td>
-                    
                     <td align="justify">
-                        <programlisting>dense=[%F, %F, %T, %F, %F
-                            %T, %F, %F, %F, %F
-                            %F, %F, %F, %F, %F
-                            %F, %F, %F, %F, %T];
+                        <programlisting>
+                            dense=[%F, %F, %T, %F, %F
+                                   %T, %F, %F, %F, %F
+                                   %F, %F, %F, %F, %F
+                                   %F, %F, %F, %F, %T];
                             sp=sparse(dense)
                         </programlisting>
                     </td>
                         <emphasis role="bold">list</emphasis>
                     </td>
                     <td align="justify">
-                        <programlisting>l = list(1,["a" "b"])</programlisting>
+                        <programlisting>
+                            l = list(1,["a" "b"])
+                        </programlisting>
                     </td>
                 </tr>
                 <tr>
                         <emphasis role="bold">tlist</emphasis>
                     </td>
                     <td align="justify">
-                        <programlisting>t = tlist(["listtype","field1","field2"], [], []);</programlisting>
+                        <programlisting>
+                            t = tlist(["listtype","field1","field2"], [], []);
+                        </programlisting>
                     </td>
                 </tr>
                 <tr>
-                    
                     <td>
                         <emphasis role="bold">mlist</emphasis>
                     </td>
                     <td align="justify">
-                        
-                        <programlisting>M=mlist(['V','name','value'],['a','b';'c' 'd'],[1 2; 3 4]);</programlisting>
+                        <programlisting>
+                            M=mlist(['V','name','value'],['a','b';'c' 'd'],[1 2; 3 4]);
+                        </programlisting>
                     </td>
                 </tr>
             </tbody>
         </informaltable>
         <para>
-            Several “types” are based on <emphasis>tlist</emphasis> or <emphasis>mlist</emphasis>. It is the case of <emphasis>rational</emphasis>, <emphasis>state-space</emphasis>, <emphasis>hypermat,cell</emphasis> and <emphasis>struct</emphasis>.They are therefor transparently saved.
+            Several "types" are based on <emphasis>tlist</emphasis> or <emphasis>mlist</emphasis>. It is the case of <emphasis>rational</emphasis>, <emphasis>state-space</emphasis>, <emphasis>hypermat</emphasis>, <emphasis>cell</emphasis> and <emphasis>struct</emphasis>. They are therefore transparently saved.
         </para>
         <para>
             <emphasis>void </emphasis>and <emphasis>undefined </emphasis>are two specific elements created to manage special cases in the list management. They are described later in this document.
             save("uint32.sod","emptyuint32matrix","uint32scalar","uint32rowvector","uint32colvector","uint32matrix");
         </programlisting>
         <para>produces:</para>
-        <para>Each root dataset has an attribute call SCILAB_Class. This attribute defines which types is the variable stored in the HDF5 file.</para>
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="../images/img001.png" width="5.95cm" depth="1.64cm"/>
+            </imageobject>
+        </mediaobject>
+        <para>Each root dataset has an attribute called <literal>SCILAB_Class</literal>. This attribute defines which types is the variable stored in the HDF5 file.</para>
         <para>If the variable is a primitive type and without complex values associated, data are stored directly into the dataset. Otherwise, the dataset contains references to the actual data.</para>
         <para>Every SOD file contains two specific variables:</para>
         <itemizedlist>
             <listitem>
-                <para>SCILAB_scilab_version – Describe which version of Scilab has been used to save the SOD file.</para>
+                <para><literal>SCILAB_scilab_version</literal> – Describe which version of Scilab has been used to save the SOD file.</para>
                 <para>For example, with Scilab 5.4.0, the data will be:</para>
                 <para>
                     <emphasis>SCILAB_scilab_version = scilab-5.4.0</emphasis>
                 </para>
             </listitem>
         </itemizedlist>
-        Types where data are stored straight into the dataset.
-        <para></para>
+        <para>
+            Types where data are stored straight into the dataset.
+        </para>
         <informaltable border="1">
             <tbody>
                 <tr>
                     <td align="left">
-                        
-                        
-                        
                         <emphasis role="bold">Scilab Type</emphasis>
                     </td>
                     <td align="left">
-                        
-                        
-                        
                         <emphasis role="bold">HDF5 Scilab type attribute</emphasis>
                     </td>
                     <td align="left">
-                        
-                        
-                        
                         <emphasis role="bold">HDF5 attributes</emphasis>
                     </td>
                     <td align="left">
-                        
                         <emphasis role="bold">HDF data types mapping</emphasis>
                     </td>
                 </tr>
                 <tr>
                     <td align="left">
-                        
-                        
                         <para>string</para>
                     </td>
                     <td align="left">
-                        
-                        
                         <para>SCILAB_Class = string</para>
                     </td>
                     <td align="left">
-                        
-                        
+
                     </td>
                     <td align="left">
-                        
-                        
-                        
                         <para>String</para>
                     </td>
                 </tr>
                 <tr>
                     <td align="left">
-                        
-                        
                         <para>boolean</para>
                     </td>
                     <td namest="c2" nameend="c3" align="left">
-                        
-                        
                         <para>SCILAB_Class = boolean</para>
                     </td>
                     <td align="left">
-                        
-                        
+
                     </td>
                     <td align="left">
-                        
-                        
-                        
                         <para>32-bit integer</para>
                     </td>
                 </tr>
                 <tr>
                     <td align="left">
-                        
-                        
                         <para>integer</para>
                     </td>
                     <td namest="c2" nameend="c3" align="left">
-                        
-                        
                         <para>SCILAB_Class = integer</para>
                     </td>
                     <td align="left">
-                        
-                        
                         <para>SCILAB_precision = {8, 16, 32, u8, u16, u32}</para>
                     </td>
                     <td namest="c1" nameend="c2" align="left">
                         <para>u8 = 8-bit unsigned character</para>
                         <para>u16 = 16-bit unsigned integer</para>
                         <para>u32 = 32-bit unsigned integer</para>
-                        
                     </td>
                 </tr>
             </tbody>
         <para>For these types, like in Scilab, the data are stored in a one dimension array. Data are stored by column wise.</para>
         <para>To reconstruct the matrix, vector or scalar, two attributes provides the number of columns and rows. </para>
         <para>
-            Since the 5.4.0 release of Scilab and SOD v2, <emphasis>SCILAB_cols</emphasis> and SCILAB_rows are no longer used for matrices of double, integer, polynomial and string. SOD uses the native multi dimensional HDF5 feature.
+            Since the 5.4.0 release of Scilab and SOD v2, <literal>SCILAB_cols</literal> and <literal>SCILAB_rows</literal> are no longer used for matrices of double, integer, polynomial and string. SOD uses the native multidimensional HDF5 feature.
         </para>
-        <para></para>
-        <emphasis role="bold">Example</emphasis>
+        <para><emphasis role="bold">Example</emphasis></para>
         <para>
-            The saving of the declaration: <emphasis>int32([1 -4 7;-9 6 -3])</emphasis> will be displayed as:
+            The saving of the declaration: <code>int32([1 -4 7;-9 6 -3])</code> will be displayed as:
         </para>
         <mediaobject>
             <imageobject>
             <para>SCILAB_Class = integer</para>
             <para>SCILAB_precision = 32</para>
         </emphasis>
-        <para>Note: Scalar value are stored as a matrix of size 1 by 1.</para>
-        <para>An empty variable ([]) will have the attribute SCILAB_empty set to true.</para>
-        <para></para>
-        <emphasis role="bold">Types where data are stored in a dedicated group</emphasis>
+        <para>
+            <note>
+                Scalar value are stored as a matrix of size 1 by 1.
+            </note>
+        </para>
+        <para>An empty variable (<literal>[]</literal>) will have the attribute <literal>SCILAB_empty</literal> set to true.</para>
+        <para><emphasis role="bold">Types where data are stored in a dedicated group</emphasis></para>
         <para>Many of Scilab datatypes are stored using groups. This allows a clear separations of the value but also an easy access.</para>
         <para>
-            Groups are named from the variables enclosed by “#”. For example, for a matrix of double called matrixofdouble, the name of the root dataset will be matrixofdouble, the name of the associated group will be #matrixofdouble<emphasis role="strong">#.</emphasis>
+            Groups are named from the variables enclosed by "#". For example, for a matrix of double called matrixofdouble, the name of the root dataset will be matrixofdouble, the name of the associated group will be <emphasis role="strong">#matrixofdouble#</emphasis>.
         </para>
         <para>For recursive data type (list, mlist, tlist, etc), names of subgroup are constructed the following way:</para>
         <para>
-            The # allow the creation of an unique identifier. The number of initial # shows the level of depth. Therefor, the sub list <emphasis>###listnested#_#2##_#1## </emphasis>will indicate that it is located at the second level.
+            The <literal>#</literal> allows the creation of an unique identifier. The number of initial <literal>#</literal> shows the level of depth. Therefore, the sublist <emphasis>###listnested#_#2##_#1##</emphasis> will indicate that it is located at the second level.
         </para>
-        <para>The underscore “_” is a way to represent the depth. Usually, the “/” character is used in such case but it is a reserver keyword in the HDF5 specification.</para>
+        <para>The underscore "_" is a way to represent the depth. Usually, the "/" character is used in such case but it is a reserved keyword in the HDF5 specification.</para>
         <para>
-            The integers used in the naming shows the position in the data structure, both in term of position in the current structure but also regarding the parent element. In the example, <emphasis>###listnested#_#2##_#1##,</emphasis> the 1 shows that it is dealing with the second element of the third structure of the main element (elements are indexed from 0).
+            The integers used in the naming shows the position in the data structure, both in term of position in the current structure but also regarding the parent element. In the example, <emphasis>###listnested#_#2##_#1##</emphasis>, the 1 shows that it is dealing with the second element of the third structure of the main element (elements are indexed from 0).
         </para>
         <para>
             For example, the group named <emphasis>###listnested#_#2##_#1##</emphasis>, will point to the value [32, 42] from the example:
         </para>
-        <programlisting>listnested=list(2,%i,'f',ones(3,3))
-            listnested(3) = list( %t, [32,42]); 
+        <programlisting>
+            listnested=list(2,%i,'f',ones(3,3))
+            listnested(3) = list( %t, [32,42]);
         </programlisting>
-        <para></para>
-        <emphasis role="bold">Sparse</emphasis>
+        <para><emphasis role="bold">Sparse</emphasis></para>
         <para>
             <emphasis role="strong">Scilab type:</emphasis> sparse
         </para>
         </para>
         <para>SCILAB_rows = &lt;int&gt;</para>
         <para>Number of rows</para>
-        <para>SCILAB_cols = &lt;int&gt;</para>
+        <para><emphasis>SCILAB_cols = &lt;int&gt;</emphasis></para>
         <para>Number of columns</para>
         <para>
             <emphasis>SCILAB_items = &lt;int&gt;</emphasis>
         </para>
         <para>Define the number of elements in the sparse matrix</para>
         <para>
-            <emphasis role="strong">Root dataset values:</emphasis> First value (#0#): Each element of this data structure shows the number of non-null element per line.Therefor, the first element shows the number of element in the first line of the sparse matrix.
+            <emphasis role="strong">Root dataset values:</emphasis>
+        </para>
+        <para>
+            First value (<literal>#0#</literal>): Each element of this data structure shows the number of non-null element per line. Therefore, the first element shows the number of element in the first line of the sparse matrix.
         </para>
-        <para>Second value (#1#): Provides the position of the column of each elements of the sparse matrix.</para>
-        <para>Third value (#2#): Store the reference to the actual values of the element in the sparse matrix (which will be stored in a specific group).</para>
+        <para>Second value (<literal>#1#</literal>): Provides the position of the column of each elements of the sparse matrix.</para>
+        <para>Third value (<literal>#2#</literal>): Stores the reference to the actual values of the element in the sparse matrix (which will be stored in a specific group).</para>
         <para>Example, taking this matrix:</para>
         <programlisting role="no-scilab-exec">
             0. 1. 0. 0. 0. 0. 0. 0. 0. 0.
             0. 0. 0. 0. 2. 0. 0. 0. 0. 0.
         </programlisting>
         <para>which is generated by the function:</para>
+        <programlisting role="scilab_code">
+        sparse([1,2;4,5;3,10],[1,2,3])
+        </programlisting>
         <para>
-            <emphasis>sparse([1,2;4,5;3,10],[1,2,3])</emphasis>will have:
+            will have:
         </para>
         <para>
             <emphasis>#0#</emphasis> contains <emphasis>1;0;1;1</emphasis>
         </para>
         <para>
-            <emphasis>#1#</emphasis> contains 2<emphasis>;10;5</emphasis><emphasis>#2# </emphasis>reference a matrix of double (not complex in this example) which contains 1.0; 3.0; 2.0
+            <emphasis>#1#</emphasis> contains <emphasis>2;10;5</emphasis>
+        </para>
+        <para>
+            <emphasis>#2#</emphasis> references a matrix of double (not complex in this example) which contains <emphasis>1.0; 3.0; 2.0</emphasis>
+        </para>
+        <para>
+            <emphasis role="bold">Boolean sparse</emphasis>
         </para>
-        <para></para>
-        <emphasis role="bold">Boolean sparse</emphasis>
         <para>
             <emphasis role="strong">Scilab type:</emphasis> boolean sparse
         </para>
         <para>
-            <emphasis role="strong">HDF5 Scilab type attribute: </emphasis>SCILAB_Class = boolean sparse
+            <emphasis role="strong">HDF5 Scilab type attribute:</emphasis> SCILAB_Class = boolean sparse
         </para>
         <para>
             <emphasis>HDF5 attributes:</emphasis>
         </para>
-        <para>SCILAB_rows = &lt;int&gt;</para>
+        <para>
+            <emphasis>SCILAB_rows = &lt;int&gt;</emphasis>
+        </para>
         <para>Number of rows</para>
         <para>
             <emphasis>SCILAB_cols = &lt;int&gt;</emphasis>
             <emphasis>SCILAB_items = &lt;int&gt;</emphasis>
         </para>
         <para>Define the number of elements in the sparse matrix</para>
-        <para>Root dataset values:While a sparse has 3 datasets, the boolean sparse has only 2 because defined values are automatically considered as true.</para>
-        <para>First value (#0#): Each element of this data structure shows the number of non-null element per line.</para>
-        <para>Therefor, the first element shows the number of element in the first line of the sparse matrix.</para>
-        <para>Second value (#1#): Provides the position of the column of each elements of the sparse matrix.</para>
+        <para><emphasis role="strong">Root dataset values:</emphasis> While a sparse has 3 datasets, the boolean sparse has only 2 because defined values are automatically considered as true.</para>
+        <para>First value (<literal>#0#</literal>): Each element of this data structure shows the number of non-null element per line.</para>
+        <para>Therefore, the first element shows the number of element in the first line of the sparse matrix.</para>
+        <para>Second value (<literal>#1#</literal>): Provides the position of the column of each elements of the sparse matrix.</para>
         <para>With the boolean sparse matrix:</para>
-        <programlisting>dense=[%F, %F, %T, %F, %F
-            %T, %F, %F, %F, %F
-            %F, %F, %F, %F, %F
-            %F, %F, %F, %F, %T];
+        <programlisting>
+        dense=[%F, %F, %T, %F, %F
+               %T, %F, %F, %F, %F
+               %F, %F, %F, %F, %F
+               %F, %F, %F, %F, %T];
         </programlisting>
         <para>
-            <emphasis>#0#</emphasis> contains <emphasis>1;1;0;1</emphasis><emphasis>#1#</emphasis> contains <emphasis>3;1;5</emphasis>
+            <emphasis>#0#</emphasis> contains <emphasis>1;1;0;1</emphasis>.
+        </para>
+        <para>
+            <emphasis>#1#</emphasis> contains <emphasis>3;1;5</emphasis>.
         </para>
         <para>Only the two information are necessary to recreate the boolean sparse.</para>
         <para>HDF data types mapping:</para>
         <para>32-bit integer</para>
-        <para></para>
-        <emphasis role="bold">Double </emphasis>
+        <para><emphasis role="bold">Double</emphasis></para>
         <para>
             <emphasis role="strong">Scilab type:</emphasis> double
         </para>
             <emphasis role="strong">HDF5 Scilab type attribute:</emphasis> SCILAB_Class = double
         </para>
         <para>
-            <emphasis role="strong">Root dataset values:</emphasis> Both real and complex values are stored in a group called #&lt;variable name&gt;#. First value: Reference to the real values. Named #0#.If the matrix is complex, the second value will reference the complex values. Named #1#
+            <emphasis role="strong">Root dataset values:</emphasis> Both real and complex values are stored in a group called <literal>#&lt;variable name&gt;#</literal>.
+        </para>
+        <para>
+            First value: Reference to the real values. Named <literal>#0#</literal>.
+        </para>
+        <para>
+            If the matrix is complex, the second value will reference the complex values. Named <literal>#1#</literal>.
         </para>
         <para>
             <emphasis role="strong">HDF data types mapping:</emphasis> 64-bit floating-point
         </para>
-        <para></para>
-        <emphasis role="bold">Polynomial</emphasis>
+        <para><emphasis role="bold">Polynomial</emphasis></para>
         <para>
             <emphasis role="strong">Scilab type:</emphasis> polynomial
         </para>
         </para>
         <para>If the polynomial is complex (not set if false)</para>
         <para>
-            <emphasis role="strong">Root dataset values:</emphasis> 
+            <emphasis role="strong">Root dataset values:</emphasis>
         </para>
-        <para>Coefficients are stored under the form of a matrix of double (cf the relative section to double storage). It is interesting to note that coefficients can be complex and, therefor, be stored as a matrix of complex. Rules of naming of the (sub-)groups and dataset are described at the beginning of the chapter.</para>
+        <para>Coefficients are stored under the form of a matrix of double (cf the relative section to double storage). It is interesting to note that coefficients can be complex and, therefore, be stored as a matrix of complex. Rules of naming of the (sub-)groups and dataset are described at the beginning of the chapter.</para>
         <para>
             <emphasis role="strong">HDF data types mapping:</emphasis> Object reference
         </para>
-        <para></para>
-        <emphasis role="bold">list</emphasis>
+        <para><emphasis role="bold">list</emphasis></para>
         <para>
             <emphasis role="strong">Scilab type:</emphasis> list
         </para>
             <emphasis role="strong">HDF5 attributes:</emphasis> SCILAB_items = &lt;number of items in the list&gt;
         </para>
         <para>
-            <emphasis role="strong">Root dataset values:</emphasis> Associated to the root dataset, values stored in this dataset are the references to the values stored in the list. The values are stored in the group called #&lt;variable name&gt;#. In the #&lt;variable name&gt;# group, data can be any type. They are included straight into the group. Their representations are the same as in other cases, based in recursive structure (meaning that list of list of list of various types can stored and loaded).
+            <emphasis role="strong">Root dataset values:</emphasis>
+        </para>
+        <para>
+            Associated to the root dataset, values stored in this dataset are the references to the values stored in the list. The values are stored in the group called <literal>#&lt;variable name&gt;#</literal>. In the <literal>#&lt;variable name&gt;#</literal> group, data can be any type. They are included straight into the group. Their representations are the same as in other cases, based in recursive structure (meaning that list of list of list of various types can stored and loaded).
         </para>
         <para>Rules of naming of the (sub-)groups and dataset are described at the beginning of the chapter.</para>
         <para>
             <emphasis role="strong">HDF data types mapping:</emphasis> Object reference
         </para>
-        <para></para>
-        <emphasis role="bold">tlist </emphasis>
+        <para><emphasis role="bold">tlist </emphasis></para>
         <para>
             <emphasis role="strong">Scilab type:</emphasis> tlist
         </para>
         <para>
             <emphasis role="strong">HDF5 attributes:</emphasis> cf list
         </para>
-        <para></para>
-        <emphasis role="bold">mlist </emphasis>
+        <para><emphasis role="bold">mlist </emphasis></para>
         <para>
             <emphasis role="strong">Scilab type:</emphasis> mlist
         </para>
         <para>
-            <emphasis role="strong">HDF5 Scilab type attribute:</emphasis> 
+            <emphasis role="strong">HDF5 Scilab type attribute:</emphasis>
         </para>
         <para>SCILAB_Class = mlist</para>
         <para>
             <emphasis role="strong">HDF5 attributes:</emphasis> cf list
         </para>
-        <para></para>
-        <emphasis role="bold">void </emphasis>
+        <para><emphasis role="bold">void </emphasis></para>
         <para>
             <emphasis role="strong">Scilab type:</emphasis> void
         </para>
         <para>
             <emphasis role="strong">HDF5 Scilab type attribute:</emphasis>
         </para>
-        <para> SCILAB_Class = void</para>
+        <para>SCILAB_Class = void</para>
         <para>A void value can only be found in very special usages of list, tlist and mlist. It can be created with the following syntax:</para>
         <programlisting>voidelement_ref=list(1,,3);</programlisting>
-        <para></para>
-        <emphasis role="bold">undefined </emphasis>
+        <para><emphasis role="bold">undefined </emphasis></para>
         <para>
             <emphasis role="strong">Scilab type:</emphasis> undefined
         </para>
         </para>
         <para> SCILAB_Class = undefined</para>
         <para>
-            An undefined value is generated when the size of a list is increased and some elements not defined. They will be generated with the syntax:<programlisting>undefinedelement_ref=list(2,%i,'f',ones(3,3));undefinedelement_ref(6)="toto"</programlisting>
+            An undefined value is generated when the size of a list is increased and some elements not defined. They will be generated with the syntax:
         </para>
-        
+        <programlisting>
+        undefinedelement_ref=list(2,%i,'f',ones(3,3));
+        undefinedelement_ref(6)="toto"
+        </programlisting>
     </refsection>
     <refsection>
         <title>Real life examples</title>
             <tbody>
                 <tr>
                     <td align="justify">
-                        
-                        
-                        
                         <emphasis role="bold">SOD version</emphasis>
                     </td>
                     <td align="justify">
-                        
-                        
-                        
                         <emphasis role="bold">Scilab version</emphasis>
                     </td>
                     <td align="justify">
-                        
                         <emphasis role="bold">Description</emphasis>
                     </td>
                 </tr>
                 <tr>
                     <td align="justify">
-                        
-                        
                         <para>0</para>
                     </td>
                     <td align="justify">
-                        
-                        
                         <para>5.2.0</para>
                     </td>
                     <td align="justify">
-                        
-                        
-                        
                         <para>Initial version of the Scilab/HDF5 format</para>
                     </td>
                 </tr>
                 <tr>
                     <td align="justify">
-                        
-                        
                         <para>1</para>
                     </td>
                     <td align="justify">
-                        
-                        
                         <para>5.4.0 alpha / beta</para>
                     </td>
                     <td align="left">
-                        
-                        
-                        
                         <para>Default format for load and save</para>
                         <para>Previous format (.bin) still supported</para>
                     </td>
                 </tr>
                 <tr>
                     <td>
-                        
-                        
                         <para>2</para>
                     </td>
                     <td>
-                        
-                        
                         <para>5.4.0</para>
                     </td>
                     <td>
-                        
-                        
-                        
                         <para>
-                            For matrices of double, integer, polynomial and string <emphasis>SCILAB_cols</emphasis> / <emphasis>SCILAB_rows</emphasis> have been removed to use multi dimensional HDF5 
+                            For matrices of double, integer, polynomial and string <emphasis>SCILAB_cols</emphasis> / <emphasis>SCILAB_rows</emphasis> have been removed to use multidimensional HDF5
                         </para>
                     </td>
                 </tr>
                 <tr>
                     <td align="justify">
-                        
-                        
+
                     </td>
                     <td align="justify">
-                        
-                        
                         <para>6.0.0 (future)</para>
                     </td>
                     <td align="justify">
-                        
-                        
-                        
                         <para>.bin support dropped.</para>
                     </td>
                 </tr>
             </tbody>
         </informaltable>
     </refsection>
-    
-    
-    
-    
-    
-    
-    
-    
-    
-    
-    
-    
-    
-    
-    
-    
-    
-    
-    
     <refsection role="see also">
         <title>See Also</title>
         <simplelist type="inline">
index 4fdabd0..aae1f11 100644 (file)
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
- * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) 2008 - INRIA
- * ...
- * 
- * This file must be used under the terms of the CeCILL.
- * This source file is licensed as described in the file COPYING, which
- * you should have received as part of this distribution.  The terms
- * are also available at    
- * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
- *
- -->
+    * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+    * Copyright (C) 2008 - INRIA
+    * ...
+    *
+    * This file must be used under the terms of the CeCILL.
+    * This source file is licensed as described in the file COPYING, which
+    * you should have received as part of this distribution.  The terms
+    * are also available at
+    * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+    *
+-->
 <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="save_format" xml:lang="ru">
     <refnamediv>
-        <refname>save_format</refname>
-        <refpurpose>формат файлов, созданных функцией "save"</refpurpose>
+        <refname>save format</refname>
+        <refpurpose>формат файлов, полученных с помощью функции "save"</refpurpose>
     </refnamediv>
     <refsection>
-        <title>Описание</title>
-        <para>
-            Переменные сохраняются Scilab'ом с помощью функции <link linkend="save">save</link> в следующем формате:
-        </para>
-        <para>
-            каждая запись переменной добавляется в файл последовательно. Запись переменной начинается с 6-ти чисел типа длинное целое, хранящих имя переменной в кодированном формате (см. раздел Примечания ниже), после чего следует тип переменной (длинное целое), затем, в зависимости от него, следует:
-        </para>
-        <variablelist>
-            <varlistentry>
-                <term>Матрицы значений с плавающей запятой (тип 1)</term>
-                <listitem>
-                    <para>
-                        <varname>row_size</varname> <varname>m</varname> (размер строки, число типа long integer),
-                    </para>
-                    <para>
-                        <varname>column_size</varname> <varname>n</varname> (размер столбца, число типа long integer),
-                    </para>
-                    <para>
-                        признак вещественности/комплекснозначности <varname>it</varname> (целое число типа long integer на интервале <literal>{0,1}</literal>),
-                    </para>
-                    <para>
-                        данные (<literal>n*m*(it+1)</literal> чисел типа double)
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-        <variablelist>
-            <varlistentry>
-                <term>Полиномы (тип 2) и Неявный полином размера, используемый для (тип 129)</term>
-                <listitem>
-                    <para>
-                        <varname>row_size</varname> <varname>m</varname> (размер строки, число типа long integer),
-                    </para>
-                    <para>
-                        <varname>column_size</varname> <varname>n</varname> (размер столбца, число типа long integer),
-                    </para>
-                    <para>
-                        признак вещественности/комплекснозначности <varname>it</varname> (целое число типа long integer в интервале <literal>{0,1}</literal>),
-                    </para>
-                    <para>
-                        формальное имя переменной (16 байт),
-                    </para>
-                    <para>
-                        <varname>index_table</varname> (таблица индексов, <literal>m*n+1</literal> целых чисел типа long integer),
-                    </para>
-                    <para>
-                        данные (<literal>(N-1)*(it+1)</literal> чисел типа double), где <varname>N</varname> -- это значение последнего элемента таблицы индексов <varname>index_table</varname>.
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-        <variablelist>
-            <varlistentry>
-                <term>Booleans (тип 4)</term>
-                <listitem>
-                    <para>
-                        <varname>row_size</varname> <varname>m</varname> (размер строки, число типа long integer),
-                    </para>
-                    <para>
-                        <varname>column_size</varname> <varname>n</varname> (размер столбца, число типа long integer),
-                    </para>
-                    <para>
-                        данные (<literal>n*m</literal> целых чисел типа long integer).
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-        <variablelist>
-            <varlistentry>
-                <term>Разрежённые матрицы чисел с плавающей запятой (тип 5)</term>
-                <listitem>
-                    <para>
-                        <varname>row_size</varname> <varname>m</varname> (размер строки, число типа long integer),
-                    </para>
-                    <para>
-                        <varname>column_size</varname> <varname>n</varname> (размер столбца, число типа long integer),
-                    </para>
-                    <para>
-                        real/complex_flag <varname>it</varname> (целое число типа long integer на интервале <literal>{0,1}</literal>),
-                    </para>
-                    <para>
-                        <varname>total_number_of_non_zero_elements</varname> <varname>nel</varname> (общее количество ненулевых элементов, число типа long integer),
-                    </para>
-                    <para>
-                        <varname>number_of_non_zero_elements_per_row</varname> (число количество ненулевых элементов на строку, <literal>m</literal> целых чисел типа long integer),
-                    </para>
-                    <para>
-                        <varname>column_index_non_zero_elements</varname> (индексы столбцов ненулевых элементов, <literal>nel</literal> целых чисел типа long integer),
-                    </para>
-                    <para>
-                        <varname>non_zero_values</varname> (ненулевые значения, <literal>nel*(it+1)</literal> чисел типа double).
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-        <variablelist>
-            <varlistentry>
-                <term>Разрежённые матрицы логических значений (тип 6)</term>
-                <listitem>
-                    <para>
-                        <varname>row_size</varname> <varname>m</varname> (размер строки, число типа long integer),
-                    </para>
-                    <para>
-                        <varname>column_size</varname> <varname>n</varname> (размер столбца, число типа long integer),
-                    </para>
-                    <para>
-                        неиспользуемое <varname>it</varname> (целое число типа long integer),
-                    </para>
-                    <para>
-                        <varname>total_number_of_non_zero_elements</varname> <varname>nel</varname> (общее количество ненулевых элементов, число типа long integer),
-                    </para>
-                    <para>
-                        <varname>number_of_non_zero_elements_per_row</varname> (число количество ненулевых элементов на строку, <literal>m</literal> целых чисел типа long integer),
-                    </para>
-                    <para>
-                        <varname>column_index_non_zero_elements</varname> (индексы столбцов ненулевых элементов, <literal>nel</literal> целых чисел типа long integer).
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-        <variablelist>
-            <varlistentry>
-                <term>Разрежённая матрица Matlab'а (тип 7)</term>
-                <listitem>
-                    <para>
-                        <varname>row_size</varname> <varname>m</varname> (размер строки, число типа long integer),
-                    </para>
-                    <para>
-                        <varname>column_size</varname> <varname>n</varname> (размер столбца, число типа long integer),
-                    </para>
-                    <para>
-                        real/complex_flag <varname>it</varname> (целое число типа long integer на интервале <literal>{0,1}</literal>),
-                    </para>
-                    <para>
-                        <varname>total_number_of_non_zero_elements</varname> <varname>nel</varname> (общее количество ненулевых элементов, число типа long integer),
-                    </para>
-                    <para>
-                        <varname>number_of_non_zero_elements_per_column</varname> (количество ненулевых элементов на столбец, <literal>n</literal> целых чисел типа long integer),
-                    </para>
-                    <para>
-                        <varname>row_index_non_zero_elements</varname> (индекс строки ненулевых элементов, <literal>nel</literal> целых чисел типа long integer),
-                    </para>
-                    <para>
-                        <varname>non_zero_values</varname> (ненулевые значения, <literal>nel*(it+1)</literal> чисел типа double).
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-        <variablelist>
-            <varlistentry>
-                <term>матрицы целых чисел (тип 8)</term>
-                <listitem>
-                    <para>
-                        <varname>row_size</varname> <varname>m</varname> (размер строки, число типа long integer),
-                    </para>
-                    <para>
-                        <varname>column_size</varname> <varname>n</varname> (размер столбца, число типа long integer),
-                    </para>
-                    <para>
-                        <varname>integer_type</varname> (тип целого числа, число типа long integer): 1, 2, 4, или 11, 12, 14 для знаковых и беззнаковых 1-, 2-, 4-байтных целых чисел,
-                    </para>
-                    <para>
-                        данные (<literal>n*m</literal> байт для  <varname>integer_type</varname> 1 или 11, <literal>n*m</literal> чисел типа short integer для <varname>integer_type</varname> 2 или 12, <literal>n*m</literal> целых чисел типа long integer для <varname>integer_type</varname> 4 или 14).
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-        <variablelist>
-            <varlistentry>
-                <term>handles (тип 9)</term>
-                <listitem>
-                    <para>version (4 bytes)</para>
-                    <para>
-                        <varname>row_size</varname> <varname>m</varname> (размер строки, байт),
-                    </para>
-                    <para>
-                        <varname>column_size</varname> <varname>n</varname> (размер столбца, байт),
-                    </para>
-                    <para>
-                        данные (<literal>m*n</literal> записей в последовательной форме <varname>serialization_record</varname>)
-                    </para>
-                    <para>
-                        Запись в последовательной форме <varname>serialization_record</varname> -- это представление в плоском виде C-структуры данных, связанной с соответствующим графическим объектом. Каждый графический объект определяется (рекурсивным) набором свойств (см. справку по функции <link linkend="get">get</link>).
-                    </para>
-                    <para>
-                        Сохранённая запись <varname>serialization_record</varname> графического объекта структурирована в следующем виде:
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>serialization_record</term>
-                            <listitem>
-                                <para>
-                                    длина типа <varname>type_length</varname> <varname>n</varname> (байт),
-                                </para>
-                                <para>
-                                    тип <varname>type</varname> (<literal>n</literal> байт, ascii-коды имени типа),
-                                </para>
-                                <para>
-                                    запись <varname>property_values</varname> (переменная длина).
-                                </para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-        <variablelist>
-            <varlistentry>
-                <term>Строки (тип 10)</term>
-                <listitem>
-                    <para>
-                        <varname>row_size</varname> <varname>m</varname> (размер строки, число типа long integer),
-                    </para>
-                    <para>
-                        <varname>column_size</varname> <varname>n</varname> (размер столбца, число типа long integer),
-                    </para>
-                    <para>
-                        <varname>index_table</varname> (<literal>n*m+1</literal> целых чисел типа long integer),
-                    </para>
-                    <para>
-                        данные (<literal>N</literal> целых чисел типа long integer, Scilab-кодировка символов (см. <link linkend="code2str">code2str</link>), где <literal>N</literal> -- это значение последнего элемента таблицы индексов <varname>index_table</varname>.
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-        <variablelist>
-            <varlistentry>
-                <term>Некомпилированные функции (тип 11)</term>
-                <listitem>
-                    <para>
-                        <varname>nout</varname> (целое число типа long integer),
-                    </para>
-                    <para>
-                        <varname>lhs_names</varname> (<literal>6*nout</literal> целых чисел типа long integer, см. раздел "Примечания" ниже),
-                    </para>
-                    <para>
-                        <varname>nin</varname> (целое число типа long integer),
-                    </para>
-                    <para>
-                        <varname>rhs_names</varname> (<literal>6*nin</literal> целых чисел типа long integer, см. раздел "Примечания" ниже),
-                    </para>
-                    <para>
-                        <varname>code_length</varname> <varname>N</varname> (целое число типа long integer),
-                    </para>
-                    <para>
-                        <varname>code</varname> (<literal>N</literal> целых чисел типа long integer).
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-        <variablelist>
-            <varlistentry>
-                <term>Компилированные функции (тип 13)</term>
-                <listitem>
-                    <para>
-                        <varname>nout</varname> (целое число типа long integer),
-                    </para>
-                    <para>
-                        <varname>lhs_names</varname> (<literal>6*nout</literal> целых чисел типа long integer, см. раздел "Примечания" ниже),
-                    </para>
-                    <para>
-                        <varname>nin</varname> (целое число типа long integer),
-                    </para>
-                    <para>
-                        <varname>rhs_names</varname> (<literal>6*nin</literal> целых чисел типа long integer, см. раздел "Примечания" ниже),
-                    </para>
-                    <para>
-                        <varname>pseudo_code_length</varname> <varname>N</varname> (целое число типа long integer),
-                    </para>
-                    <para>
-                        <varname>pseudo_code</varname> (<literal>N</literal> целых чисел типа long integer).
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-        <variablelist>
-            <varlistentry>
-                <term>Библиотеки (тип 14)</term>
-                <listitem>
-                    <para>
-                        <varname>path_length</varname> <varname>np</varname> (длина пути, целое число типа long integer),
-                    </para>
-                    <para>
-                        <varname>path_name</varname> (имя пути, <literal>np</literal> целых чисел типа long integer: последовательность кодов символов пути, (см. <link linkend="code2str">code2str</link>)),
-                    </para>
-                    <para>
-                        количество имён <varname>nn</varname> (целое число типа long integer),
-                    </para>
-                    <para>
-                        имена (<literal>6*nn</literal> целых чисел типа long integer, см. раздел "Примечания" ниже).
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-        <variablelist>
-            <varlistentry>
-                <term>списки (тип 15), типизированные списки (тип 16), матричноориентированные списки (тип 17)</term>
-                <listitem>
-                    <para>
-                        количество полей <varname>n</varname> (целое число типа long integer),
-                    </para>
-                    <para>
-                        индекс (<literal>n+1</literal> целых чисел типа long integer),
-                    </para>
-                    <para>
-                        последовательность переменных <varname>variables_sequence</varname> (<literal>n</literal> переменных, каждое из которых записано в своём формате).
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-        <variablelist>
-            <varlistentry>
-                <term>Указатели (тип 128)</term>
-                <listitem>
-                    <para>Не обрабатываются</para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-        <variablelist>
-            <varlistentry>
-                <term>Указатели на функцию (тип 130)</term>
-                <listitem>
-                    <para>
-                        <varname>function_ptr</varname> (указатель на функцию, целое число типа long integer, (see <link linkend="funptr">funptr</link>)),
-                    </para>
-                    <para>
-                        <varname>function_name_code</varname> (код имени функции, 6 целых чисел типа long integer, см. раздел "Примечания" ниже).
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
+        <title>Аннотация</title>
+        <para>
+            Целью данного документа является определения формата HDF5,
+            используемого Scilab'ом для хранения своих данных.
+        </para>
+        <para>
+            Этот формат называется SOD от английского Scilab Open Data
+            ("открытые данные Scilab'а").
+        </para>
+        <para>
+            Первый публичный релиз SOD был сделан в Scilab 5.4.0.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Основная причина</title>
+        <para>
+            Интероперабельность является одним из ключевых аспектов
+            современного программного обеспечения. Для того, чтобы
+            больше и больше улучшать этот аспект был предложено
+            стандартное определение формата HDF5.
+        </para>
+        <para>
+            Со времён Scilab 5.2.0 была разработана возможность
+            экспорта/импорта, которая используется для обмена данными.
+            Это уже один из основных компонентов Xcos для хранения и
+            обмена данными.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Поддерживаемые типы данных</title>
+        <para>
+            Поддерживаются все типы данных Scilab'а. Например:
+        </para>
+        <informaltable border="1">
+            <tbody>
+                <tr>
+                    <td>
+                        <emphasis role="bold">Имя</emphasis>
+                    </td>
+                    <td>
+                        <emphasis role="bold">Пример в Scilab'е</emphasis>
+                    </td>
+                </tr>
+                <tr>
+                    <td>
+                        <emphasis role="bold">double</emphasis>
+                    </td>
+                    <programlisting>
+                        A=32;
+                        b=[32,2];
+                        c=[2,2;3,4];
+                        d=rand(10,10);
+                    </programlisting>
+                </tr>
+                <tr>
+                    <td>
+                        <emphasis role="bold">string</emphasis>
+                    </td>
+                    <programlisting>
+                        a="my string";
+                        b=["string 1";"my string 2"];
+                    </programlisting>
+                </tr>
+                <tr>
+                    <td>
+                        <emphasis role="bold">boolean</emphasis>
+                    </td>
+                    <programlisting>
+                        a=%t;
+                        b=[%t, %f];
+                    </programlisting>
+                </tr>
+                <tr>
+                    <td>
+                        <emphasis role="bold">integer</emphasis>
+                    </td>
+                    <td>
+                        <programlisting>
+                            int8([1 -120 127 312])
+                            x=int32(-200:100:400)
+                        </programlisting>
+                    </td>
+                </tr>
+                <tr>
+                    <td>
+                        <emphasis role="bold">polynomial</emphasis>
+                    </td>
+                    <td>
+                        <programlisting>
+                            s=poly([2 3],"s")
+                            poly(1:4,'s','c')
+                        </programlisting>
+                    </td>
+                </tr>
+                <tr>
+                    <td>
+                        <emphasis role="bold">sparse</emphasis>
+                    </td>
+                    <td align="justify">
+                        <programlisting>
+                            sp=sparse([1,2;4,5;3,10],[1,2,3])
+                        </programlisting>
+                    </td>
+                </tr>
+                <tr>
+                    <td>
+                        <emphasis role="bold">boolean sparse</emphasis>
+                    </td>
+                    <td align="justify">
+                        <programlisting>
+                            dense=[%F, %F, %T, %F, %F
+                                   %T, %F, %F, %F, %F
+                                   %F, %F, %F, %F, %F
+                                   %F, %F, %F, %F, %T];
+                            sp=sparse(dense)
+                        </programlisting>
+                    </td>
+                </tr>
+                <tr>
+                    <td>
+                        <emphasis role="bold">list</emphasis>
+                    </td>
+                    <td align="justify">
+                        <programlisting>
+                            l = list(1,["a" "b"])
+                        </programlisting>
+                    </td>
+                </tr>
+                <tr>
+                    <td>
+                        <emphasis role="bold">tlist</emphasis>
+                    </td>
+                    <td align="justify">
+                        <programlisting>
+                            t = tlist(["listtype","field1","field2"], [], []);
+                        </programlisting>
+                    </td>
+                </tr>
+                <tr>
+                    <td>
+                        <emphasis role="bold">mlist</emphasis>
+                    </td>
+                    <td align="justify">
+                        <programlisting>
+                            M=mlist(['V','name','value'],['a','b';'c' 'd'],[1 2; 3 4]);
+                        </programlisting>
+                    </td>
+                </tr>
+            </tbody>
+        </informaltable>
+        <para>
+            Несколько "типов" основаны на <emphasis>tlist</emphasis> или
+            <emphasis>mlist</emphasis>. Это <emphasis>rational</emphasis>,
+            <emphasis>state-space</emphasis>, <emphasis>hypermat</emphasis>,
+            <emphasis>cell</emphasis> и <emphasis>struct</emphasis>.
+            Следовательно, они явно сохраняются.
+        </para>
+        <para>
+            <emphasis>void</emphasis> и <emphasis>undefined</emphasis> -
+            это два особых элемента, созданных для управления особыми
+            случаями в управлении списками. Они описаны ниже.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Структура файла HDF5</title>
+        <para>
+            Архитектура HDF5 Scilab'а довольно проста.
+        </para>
+        <emphasis role="bold">Основные сведения</emphasis>
+        <para>
+            Для каждой переменной Scilab'а декларируется набор данных в
+            корне. Имя набора данных - это имя переменной Scilab'а.
+        </para>
+        <para>
+            Например, следующий код:
+        </para>
+        <programlisting>
+            emptyuint32matrix = uint32([]);
+            uint32scalar = uint32(1);
+            uint32rowvector = uint32([1 4 7]);
+            uint32colvector = uint32([1;4;7]);
+            uint32matrix = uint32([1 4 7;9 6 3]);
+            save("uint32.sod","emptyuint32matrix","uint32scalar","uint32rowvector","uint32colvector","uint32matrix");
+        </programlisting>
+        <para>формирует:</para>
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="../images/img001.png" width="5.95cm" depth="1.64cm"/>
+            </imageobject>
+        </mediaobject>
+        <para>
+            Каждый корневой набор данных имеет атрибут, именуемый
+            <literal>SCILAB_Class</literal>. Этот атрибут определяет
+            какие типы переменных хранятся в HDF5-файле.
+        </para>
+        <para>
+            Если переменная является основным типом и без связанных с
+            ним комплексных значений, то данные сохраняются
+            непосредственно в набор данных. В противном случае, набор
+            данных содержит ссылки на фактические данные.
+        </para>
+        <para>
+            Каждый SOD-файл содержит две особые переменные:
+        </para>
+        <itemizedlist>
+            <listitem>
+                <para>
+                    <literal>SCILAB_scilab_version</literal> - описывает
+                    какая версия Scilab'а использовалась для сохранения
+                    SOD-файла.
+                </para>
+                <para>
+                    Например, для Scilab 5.4.0 эти данные будут иметь вид:
+                </para>
+                <para>
+                    <emphasis>SCILAB_scilab_version = scilab-5.4.0</emphasis>
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    <literal>SCILAB_sod_version</literal> - описывает
+                    какая версия спецификации SOD использовалась для
+                    сохранения файла.
+                </para>
+                <para>
+                    Например, для Scilab 5.4.0 эти данные будут иметь вид:
+                </para>
+                <para>
+                    <emphasis>SCILAB_sod_version = 2</emphasis>
+                </para>
+            </listitem>
+        </itemizedlist>
+        <para>
+            Типы, данные которых сохраняются непосредственно в набор
+            данных.
+        </para>
+        <informaltable border="1">
+            <tbody>
+                <tr>
+                    <td align="left">
+                        <emphasis role="bold">Тип Scilab'а</emphasis>
+                    </td>
+                    <td align="left">
+                        <emphasis role="bold">Атрибут HDF5 типа Scilab'а</emphasis>
+                    </td>
+                    <td align="left">
+                        <emphasis role="bold">Атрибуты HDF5</emphasis>
+                    </td>
+                    <td align="left">
+                        <emphasis role="bold">Расположение типов данных HDF</emphasis>
+                    </td>
+                </tr>
+                <tr>
+                    <td align="left">
+                        <para>string</para>
+                    </td>
+                    <td align="left">
+                        <para>SCILAB_Class = string</para>
+                    </td>
+                    <td align="left">
+
+                    </td>
+                    <td align="left">
+                        <para>строковое значение</para>
+                    </td>
+                </tr>
+                <tr>
+                    <td align="left">
+                        <para>boolean</para>
+                    </td>
+                    <td namest="c2" nameend="c3" align="left">
+                        <para>SCILAB_Class = boolean</para>
+                    </td>
+                    <td align="left">
+
+                    </td>
+                    <td align="left">
+                        <para>32-битное целое число</para>
+                    </td>
+                </tr>
+                <tr>
+                    <td align="left">
+                        <para>integer</para>
+                    </td>
+                    <td namest="c2" nameend="c3" align="left">
+                        <para>SCILAB_Class = integer</para>
+                    </td>
+                    <td align="left">
+                        <para>SCILAB_precision = {8, 16, 32, u8, u16, u32}</para>
+                    </td>
+                    <td namest="c1" nameend="c2" align="left">
+                        <para>8 = 8-битный символ</para>
+                        <para>16 = 16-битное целое число</para>
+                        <para>32 = 32-битное целое число</para>
+                        <para>u8 = 8-битное целое беззнаковое число</para>
+                        <para>u16 = 16-битное целое беззнаковое число</para>
+                        <para>u32 = 32-битное целое беззнаковое число</para>
+                    </td>
+                </tr>
+            </tbody>
+        </informaltable>
+        <para>
+            Для этих типов, как в Scilab'е, данные хранятся в одномерном
+            массиве. Данные сохраняются столбец на столбцом.
+        </para>
+        <para>
+            Для восстановления матрицы, вектора или скаляра, два
+            атрибута дают количество столбцов и строк.
+        </para>
+        <para>
+            Начиная с релиза 5.4.0 Scilab'а и SOD v2, <literal>SCILAB_cols</literal> и
+            <literal>SCILAB_rows</literal> больше не используются для
+            матриц типа double, integer, polynomial и string. SOD
+            использует родную многомерную возможность HDF5.
+        </para>
+        <para>
+            <emphasis role="bold">Пример</emphasis>
+        </para>
+        <para>
+            Сохранение декларации: <code>int32([1 -4 7;-9 6 -3])</code>
+            будет отображено как:
+        </para>
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="../images/img002.png" width="5.95cm" depth="1.64cm"/>
+            </imageobject>
+        </mediaobject>
+        <para>в hdfview.</para>
+        <para>А метаданные будут отображены как:</para>
+        <emphasis role="italic">
+            <para>int32matrix (800, 2)</para>
+            <para>32-bit integer, 3 x 2 =&gt; размер переменной</para>
+            <para>Number of attributes = 2</para>
+            <para>SCILAB_Class = integer</para>
+            <para>SCILAB_precision = 32</para>
+        </emphasis>
+        <para>
+            <note>
+                Скалярное значение хранится в виде матрицы размером 1 на 1.
+            </note>
+        </para>
+        <para>
+            Пустая переменная (<literal>[]</literal>) будет иметь
+            атрибут <literal>SCILAB_empty</literal>, установленный в
+            значение ИСТИНА.
+        </para>
+        <para>
+            <emphasis role="bold">Типы, в которых данные хранятся в
+            соответствующей группе</emphasis>
+        </para>
+        <para>
+            Многие типы данных Scilab'а хранятся с помощью групп. Это
+            позволяет не только явно разделять значения, но и иметь
+            лёгкий доступ к ним.
+        </para>
+        <para>
+            Группы именуются по переменным, заключённым в знак "#".
+            Например, для матрицы значений типа double, названной
+            matrixofdouble, имя корневого набора данных будет
+            matrixofdouble, имя связанной с ней группы будет <emphasis
+            role="strong">#matrixofdouble#</emphasis>.
+        </para>
+        <para>
+            Для рекурсивного типа данных (list, mlist, tlist и т. д.)
+            имена подгрупп построены следующим образом:
+        </para>
+        <para>
+            Знак <literal>#</literal> позволяет создавать уникальный
+            идентификатор. Количество начальных знаков
+            <literal>#</literal> показывает уровень глубины.
+            Следовательно подсписок
+            <emphasis>###listnested#_#2##_#1##</emphasis> будет
+            указывать, что он помещён на второй уровень.
+        </para>
+        <para>
+            Символ подчёркивания "_" является способом представить
+            глубину. Обычно в таких случаях используется символ "/", но
+            это зарезервированное ключевое слово в спецификации HDF5.
+        </para>
+        <para>
+            Целые числа, используемые в названии, показывают положение в
+            структуре данных, оба в терминах положения в текущей
+            структуре, но также относительно родительского элемента. В
+            примере <emphasis>###listnested#_#2##_#1##</emphasis>, 1
+            показывает, что мы имеем дело со вторым элементом третьей
+            структуры главного элемента (элементы индексируются начиная
+            с 0).
+        </para>
+        <para>
+            В следующем примере, группа, названная
+            <emphasis>###listnested#_#2##_#1##</emphasis>,
+            будет указывать на значение [32, 42]:
+        </para>
+        <programlisting>
+            listnested=list(2,%i,'f',ones(3,3))
+            listnested(3) = list( %t, [32,42]);
+        </programlisting>
+        <para>
+            <emphasis role="bold">Разрежённая матрица</emphasis>
+        </para>
+        <para>
+            <emphasis role="strong">Тип Scilab'а:</emphasis> sparse
+        </para>
+        <para>
+            <emphasis role="strong">атрибут HDF5 типа
+                Scilab'а:</emphasis> SCILAB_Class = sparse
+        </para>
+        <para>
+            <emphasis role="strong">атрибуты HDF5: </emphasis>
+        </para>
+        <para>SCILAB_rows = &lt;int&gt;</para>
+        <para>Количество строк</para>
+        <para><emphasis>SCILAB_cols = &lt;int&gt;</emphasis></para>
+        <para>Количество столбцов</para>
+        <para>
+            <emphasis>SCILAB_items = &lt;int&gt;</emphasis>
+        </para>
+        <para>
+            Определение количества элементов разрежённой матрице
+        </para>
+        <para>
+            <emphasis role="strong">Значения корневого набора данных:</emphasis>
+        </para>
+        <para>
+            Первое значение (<literal>#0#</literal>): каждый элемент из
+            этой структуры данных показывает количество ненулевых
+            элементов на строку. Следовательно, первый элемент
+            показывает количество элементов в первой строке разрежённой
+            матрицы.
+        </para>
+        <para>
+            Второе значение (<literal>#1#</literal>): указывает
+            положение столбца каждого элемента разрежённой матрицы.
+        </para>
+        <para>
+            Третье значение (<literal>#2#</literal>): хранит ссылку на
+            фактические значения элементов в разрежённой матрице (каждое
+            будет сохранено в особой группе).
+        </para>
+        <para>Например, взяв такую матрицу:</para>
+        <programlisting role="no-scilab-exec">
+            0. 1. 0. 0. 0. 0. 0. 0. 0. 0.
+            0. 0. 0. 0. 0. 0. 0. 0. 0. 0.
+            0. 0. 0. 0. 0. 0. 0. 0. 0. 3.
+            0. 0. 0. 0. 2. 0. 0. 0. 0. 0.
+        </programlisting>
+        <para>которая формируется функцией:</para>
+        <programlisting role="scilab_code">
+        sparse([1,2;4,5;3,10],[1,2,3])
+        </programlisting>
+        <para>
+            будем иметь:
+        </para>
+        <para>
+            <emphasis>#0#</emphasis> содержит <emphasis>1;0;1;1</emphasis>
+        </para>
+        <para>
+            <emphasis>#1#</emphasis> содержит <emphasis>2;10;5</emphasis>
+        </para>
+        <para>
+            <emphasis>#2#</emphasis> обращается к матрице чисел типа
+            double (в этом примере они не комплексные), которая содержит
+            <emphasis>1.0; 3.0; 2.0</emphasis>.
+        </para>
+        <para>
+            <emphasis role="bold">Разрежённая матрица логических значений</emphasis>
+        </para>
+        <para>
+            <emphasis role="strong">Тип Scilab'а:</emphasis> boolean sparse
+        </para>
+        <para>
+            <emphasis role="strong">атрибут HDF5 типа Scilab'а:</emphasis> SCILAB_Class = boolean sparse
+        </para>
+        <para>
+            <emphasis>атрибуты HDF5:</emphasis>
+        </para>
+        <para>
+            <emphasis>SCILAB_rows = &lt;int&gt;</emphasis>
+        </para>
+        <para>Количество строк</para>
+        <para>
+            <emphasis>SCILAB_cols = &lt;int&gt;</emphasis>
+        </para>
+        <para>Количество столбцов</para>
+        <para>
+            <emphasis>SCILAB_items = &lt;int&gt;</emphasis>
+        </para>
+        <para>
+            Определение количества элементов в разрежённой матрице
+        </para>
+        <para>
+            <emphasis role="strong">Значения корневого набора
+            данных:</emphasis> в то время как разрежённая матрица имеет
+            3 набора данных, разрежённая матрица логических значений
+            имеет только 2, поскольку определяемые значения
+            автоматически рассматриваются как истинные.
+        </para>
+        <para>
+            Первое значение (<literal>#0#</literal>): каждый элемент
+            этой структуры данных показывает количество ненулевых
+            элементов в строке.
+        </para>
+        <para>
+            Следовательно, первый элемент показывает количество
+            элементов в первой строке разрежённой матрицы.
+        </para>
+        <para>
+            Второе значение (<literal>#1#</literal>): указывает
+            положение столбца каждого из элементов разрежённой матрицы.
+        </para>
+        <para>В разрежённой матрице логических значений:</para>
+        <programlisting>
+        dense=[%F, %F, %T, %F, %F
+               %T, %F, %F, %F, %F
+               %F, %F, %F, %F, %F
+               %F, %F, %F, %F, %T];
+        </programlisting>
+        <para>
+            <emphasis>#0#</emphasis> содержит <emphasis>1;1;0;1</emphasis>.
+        </para>
+        <para>
+            <emphasis>#1#</emphasis> содержит <emphasis>3;1;5</emphasis>.
+        </para>
+        <para>
+            Для восстановления разрежённой матрицы логических значений
+            требуется только два значения.
+        </para>
+        <para>
+            <emphasis role="bold">Расположение типов данных
+            HDF</emphasis>: 32-битное целое
+        </para>
+        <para>
+            <emphasis role="bold">Числа удвоенной точности</emphasis>
+        </para>
+        <para>
+            <emphasis role="strong">Тип Scilab'а:</emphasis> double
+        </para>
+        <para>
+            <emphasis role="strong">атрибут HDF5 типа Scilab'а:</emphasis> SCILAB_Class = double
+        </para>
+        <para>
+            <emphasis role="strong">Значения корневого набора данных:</emphasis>
+        </para>
+        <para>
+            Как вещественные так и комплексные значения хранятся в
+            группе, именуемой <literal>#&lt;имя переменной&gt;#</literal>.
+        </para>
+        <para>
+            Первое значение: ссылка на вещественные значения. Названо
+            <literal>#0#</literal>.
+        </para>
+        <para>
+            Если матрица комплексная, то второе значение будет ссылаться
+            на комплексные значения. Названо <literal>#1#</literal>.
+        </para>
+        <para>
+            <emphasis role="bold">Расположение типов данных
+            HDF</emphasis> 64-битное с плавающей запятой
+        </para>
+        <para>
+            <emphasis role="bold">Полином</emphasis>
+        </para>
+        <para>
+            <emphasis role="strong">Тип Scilab'а:</emphasis> polynomial
+        </para>
+        <para>
+            <emphasis role="strong">атрибут HDF5 типа
+                Scilab'а:</emphasis> SCILAB_Class = polynomial
+        </para>
+        <para>
+            <emphasis role="strong">атрибуты HDF5: </emphasis>
+        </para>
+        <para>SCILAB_Class = polynomial</para>
+        <para>SCILAB_varname = &lt;string&gt;</para>
+        <para>Имя символьной переменной</para>
+        <para>
+            <emphasis>SCILAB_Complex = &lt;boolean&gt;</emphasis>
+        </para>
+        <para>
+            Если полином комплексный (не устанавливается, если ложь).
+        </para>
+        <para>
+            <emphasis role="strong">Значения корневого набора
+            данных:</emphasis>
+        </para>
+        <para>
+            Коэффициенты хранятся в виде матрицы чисел удвоенной
+            точности (сравни соответствующий раздел, посвящённый
+            хранению чисел удвоенной точности). Интересно отметить, что
+            коэффициенты могут быть комплексными и, следовательно, могут
+            храниться в виде матрицы комплексных значений. Правила
+            наименования (под-)групп и набора данных описаны в начале
+            этого раздела.
+        </para>
+        <para>
+            <emphasis role="bold">Расположение типов данных HDF</emphasis> ссылка на объект
+        </para>
+        <para>
+            <emphasis role="bold">Список</emphasis>
+        </para>
+        <para>
+            <emphasis role="strong">Тип Scilab'а:</emphasis> list
+        </para>
+        <para>
+            <emphasis role="strong">атрибут HDF5 типа Scilab'а:</emphasis>
+        </para>
+        <para>SCILAB_Class = list</para>
+        <para>
+            <emphasis role="strong">атрибуты HDF5:</emphasis>
+            SCILAB_items = &lt;количество пунктов в списке&gt;
+        </para>
+        <para>
+            <emphasis role="strong">Значения корневого набора данных:</emphasis>
+        </para>
+        <para>
+            Привязанные к корневому набору данных значения хранятся в
+            этом наборе и являются ссылками на значения, хранимые в
+            списке. Значения хранятся в группе, названной
+            <literal>#&lt;имя переменной&gt;#</literal>. В группе
+            <literal>#&lt;имя переменной&gt;#</literal> данные могут
+            быть любого типа. Они прямо включены в группу. Их
+            представления те же самые, что и в других случаях,
+            основанных на рекурсивной структуре (имеется в виду, что
+            можно сохранить и загрузить список списка списка различных
+            типов).
+        </para>
+        <para>
+            Правила наименования (под-)групп и набора данных описаны в
+            начале этого раздела.
+        </para>
+        <para>
+            <emphasis role="bold">Расположение типов данных HDF</emphasis> ссылка на объект
+        </para>
+        <para>
+            <emphasis role="bold">Типизированный список</emphasis>
+        </para>
+        <para>
+            <emphasis role="strong">Тип Scilab'а:</emphasis> tlist
+        </para>
+        <para>
+            <emphasis role="strong">атрибут HDF5 типа Scilab'а:</emphasis>
+        </para>
+        <para> SCILAB_Class = tlist</para>
+        <para>
+            <emphasis role="strong">атрибуты HDF5:</emphasis> см. список
+        </para>
+        <para>
+            <emphasis role="bold">матричноориентированный список</emphasis>
+        </para>
+        <para>
+            <emphasis role="strong">Тип Scilab'а:</emphasis> mlist
+        </para>
+        <para>
+            <emphasis role="strong">атрибут HDF5 типа Scilab'а:</emphasis>
+        </para>
+        <para>SCILAB_Class = mlist</para>
+        <para>
+            <emphasis role="strong">атрибуты HDF5:</emphasis> см. список
+        </para>
+        <para>
+            <emphasis role="bold">Пустое значение</emphasis>
+        </para>
+        <para>
+            <emphasis role="strong">Тип Scilab'а:</emphasis> void
+        </para>
+        <para>
+            <emphasis role="strong">атрибут HDF5 типа Scilab'а:</emphasis>
+        </para>
+        <para>SCILAB_Class = void</para>
+        <para>
+            Пустое значение можно найти только в очень особых случаях
+            использования списков, типизированных списков и
+            матричноориентированных списков. Оно может быть создано с
+            помощью следующего синтаксиса:
+        </para>
+        <programlisting>voidelement_ref=list(1,,3);</programlisting>
+        <para>
+            <emphasis role="bold">Неопределённое значение</emphasis>
+        </para>
+        <para>
+            <emphasis role="strong">Тип Scilab'а:</emphasis> undefined
+        </para>
+        <para>
+            <emphasis role="strong">атрибут HDF5 типа Scilab'а:</emphasis>
+        </para>
+        <para> SCILAB_Class = undefined</para>
+        <para>
+            Неопределённое значение формируется, когда размер списка
+            увеличивается, а некоторые элементы не определены. Они будут
+            сформированы с помощью следующего синтаксиса:
+        </para>
+        <programlisting>
+        undefinedelement_ref=list(2,%i,'f',ones(3,3));
+        undefinedelement_ref(6)="toto"
+        </programlisting>
     </refsection>
     <refsection>
-        <title>Примечания</title>
+        <title>Примеры из жизни</title>
         <para>
-            Числа (типа long interger, short integer, double) хранятся в прямом порядке байтов.
+            Файлы с образцами всех этих переменных прилагаются к
+            дистрибутиву Scilab'а. Они лежат в директории:
+            <emphasis>SCI/modules/hdf5/tests/sample_scilab_data/</emphasis>
         </para>
         <para>
-            Имена переменных хранятся в виде последовательности из 6 целых чисел типа long integer с особой кодировкой. См. подробности в файле <literal>cvname.f</literal>.
+            На момент редактирования этого документа были приложены
+            следующие файлы:
         </para>
+        <emphasis role="italic">
+            <para>
+                booleanmatrix.sod
+            </para>
+            <para>booleanscalar.sod
+            </para>
+            <para>booleansparse.sod
+            </para>
+            <para>emptymatrix.sod
+            </para>
+            <para>emptysparse.sod
+            </para>
+            <para>hypermatrixcomplex.sod
+            </para>
+            <para>hypermatrix.sod
+            </para>
+            <para>int16.sod
+            </para>
+            <para>int32.sod
+            </para>
+            <para>int8.sod
+            </para>
+            <para>listnested.sod
+            </para>
+            <para>list.sod
+            </para>
+            <para>matricedoublecomplexscalar.sod
+            </para>
+            <para>matricedoublecomplex.sod
+            </para>
+            <para>matricedoublescalar.sod
+            </para>
+            <para>matricedouble.sod
+            </para>
+            <para>matricestringscalar.sod
+            </para>
+            <para>matricestring.sod
+            </para>
+            <para>mlist.sod
+            </para>
+            <para>polynomialscoef.sod
+            </para>
+            <para>polynomials.sod
+            </para>
+            <para>sparsematrix.sod
+            </para>
+            <para>tlist.sod
+            </para>
+            <para>uint16.sod
+            </para>
+            <para>uint32.sod
+            </para>
+            <para>uint8.sod
+            </para>
+            <para>undefinedelement.sod
+            </para>
+            <para>voidelement.sod
+            </para>
+        </emphasis>
+    </refsection>
+    <refsection>
+        <title>История развития формата</title>
+        <informaltable border="1">
+            <tbody>
+                <tr>
+                    <td align="justify">
+                        <emphasis role="bold">Версия SOD</emphasis>
+                    </td>
+                    <td align="justify">
+                        <emphasis role="bold">Версия Scilab'а</emphasis>
+                    </td>
+                    <td align="justify">
+                        <emphasis role="bold">Описание</emphasis>
+                    </td>
+                </tr>
+                <tr>
+                    <td align="justify">
+                        <para>0</para>
+                    </td>
+                    <td align="justify">
+                        <para>5.2.0</para>
+                    </td>
+                    <td align="justify">
+                        <para>Начальная версия формата Scilab/HDF5</para>
+                    </td>
+                </tr>
+                <tr>
+                    <td align="justify">
+                        <para>1</para>
+                    </td>
+                    <td align="justify">
+                        <para>5.4.0 alpha / beta</para>
+                    </td>
+                    <td align="left">
+                        <para>
+                            Формат по умолчанию для загрузки и сохранения.
+                        </para>
+                        <para>
+                            Предыдущий формат (.bin) по-прежнему поддерживается.
+                        </para>
+                    </td>
+                </tr>
+                <tr>
+                    <td>
+                        <para>2</para>
+                    </td>
+                    <td>
+                        <para>5.4.0</para>
+                    </td>
+                    <td>
+                        <para>
+                            Для матриц значений тип double, integer, polynomial и string
+                            <emphasis>SCILAB_cols</emphasis> / <emphasis>SCILAB_rows</emphasis> были
+                            удалены, чтобы использовать многомерные HDF5.
+                        </para>
+                    </td>
+                </tr>
+                <tr>
+                    <td align="justify">
+
+                    </td>
+                    <td align="justify">
+                        <para>6.0.0 (будущая)</para>
+                    </td>
+                    <td align="justify">
+                        <para>.bin не поддерживается.</para>
+                    </td>
+                </tr>
+            </tbody>
+        </informaltable>
     </refsection>
     <refsection role="see also">
         <title>Смотрите также</title>
         </simplelist>
     </refsection>
 </refentry>
-