[doc] save() page updated for 6.0 (rewritten) 20/20320/10
Samuel GOUGEON [Tue, 24 Jul 2018 22:45:20 +0000 (00:45 +0200)]
 http://bugzilla.scilab.org/show_bug.cgi?id=14840

Change-Id: Iabb2a17dabeab84330bc0159feb5e35464040a9a

scilab/CHANGES.md
scilab/modules/fileio/help/en_US/save_format.xml
scilab/modules/fileio/help/ja_JP/save_format.xml
scilab/modules/fileio/help/ru_RU/save_format.xml
scilab/modules/helptools/etc/images_md5.txt
scilab/modules/helptools/images/save_1.png [new file with mode: 0644]
scilab/modules/io/help/en_US/load.xml
scilab/modules/io/help/en_US/save.xml
scilab/modules/io/help/ja_JP/save.xml [deleted file]
scilab/modules/io/help/pt_BR/save.xml [deleted file]

index 969e5bd..0004079 100644 (file)
@@ -260,7 +260,7 @@ Help pages:
  `bitor`, `bitxor`, `bitand`, `macr2tree`, `geomean`, `clf`, `getPreferencesValue`, `gcd`, `lcm`, `isglobal`,
  `whereis`, `mode`, `%onprompt`, `toeplitz`, `param3d`, `param3d1`, `argn`, `gettext`, `poly`,
  `mtlb_int8`, `mtlb_int16`, `mtlb_int32`, `mtlb_int64`, `mtlb_uint8`, `mtlb_uint16`, `mtlb_uint32`, `mtlb_uint64`, `intersect`,
- `load`, `host`, `locate`, `null`
+ `load`, `save`, `host`, `locate`, `null`
 * reorganized:
   - `else`, `elseif`, `end`, `try`, `sciargs`, `global`, `halt`, `empty`, `power`, `numderivative`
   - `pixel_drawing_mode`, `show_window`, `twinkle`, `uigetcolor`, `winsid`, `xdel`, `xgrid`, `xname`, `xnumb`
@@ -464,6 +464,7 @@ Known issues
 * [#14701](http://bugzilla.scilab.org/show_bug.cgi?id=14701): `poly(c,v,"coeff")` did not ignore null high order coefficients.
 * [#14704](http://bugzilla.scilab.org/show_bug.cgi?id=14704): In Scinotes, URL for the `https://`, `ftp://`, `ftps://`, and `file://` protocols were no longer hyperlinked.
 * [#14708](http://bugzilla.scilab.org/show_bug.cgi?id=14708): polynomial operators + - / ./ * .* no longer simplified null high orders coefficients from result
+* [#14840](http://bugzilla.scilab.org/show_bug.cgi?id=14840): load() is unable to load old data files saved with Scilab < 5.4.0 out of the SOD format.
 * [#14897](http://bugzilla.scilab.org/show_bug.cgi?id=14897): `xinfo` is poor and useless. It is declared obsolete.
 * [#14988](http://bugzilla.scilab.org/show_bug.cgi?id=14988): The example of Xcos diagram on the DERIV help page was distorted.
 * [#14989](http://bugzilla.scilab.org/show_bug.cgi?id=14989): The example of Xcos diagram on the INTEGRAL_m help page was distorted.
index 6cc9c05..3eeb224 100644 (file)
         <para>produces:</para>
         <mediaobject>
             <imageobject>
-                <imagedata fileref="../images/img001.png" width="5.95cm" depth="1.64cm"/>
+                <imagedata fileref="../images/img001.png"/>
             </imageobject>
         </mediaobject>
         <para>
         </para>
         <mediaobject>
             <imageobject>
-                <imagedata fileref="../images/img002.png" width="5.95cm" depth="1.64cm"/>
+                <imagedata fileref="../images/img002.png"/>
             </imageobject>
         </mediaobject>
         <para>in hdfview.</para>
                     </td>
                 </tr>
                 <tr>
-                    <td align="justify">
+                    <td align="center">
                         <para>0</para>
                     </td>
-                    <td align="justify">
+                    <td align="center">
                         <para>5.2.0</para>
                     </td>
                     <td align="justify">
                     </td>
                 </tr>
                 <tr>
-                    <td align="justify">
+                    <td align="center">
                         <para>1</para>
                     </td>
-                    <td align="justify">
+                    <td align="center">
                         <para>5.4.0 alpha / beta</para>
                     </td>
                     <td align="left">
                     </td>
                 </tr>
                 <tr>
-                    <td align="justify">
-
+                    <td align="center">
+                        3
                     </td>
-                    <td align="justify">
-                        <para>6.0.0 (future)</para>
+                    <td align="center">
+                        <para>6.0.0</para>
                     </td>
                     <td align="justify">
                         <para>.bin support dropped.</para>
index 84d2b6a..1c0a9bc 100644 (file)
         <para>produces:</para>
         <mediaobject>
             <imageobject>
-                <imagedata fileref="../images/img001.png" width="5.95cm" depth="1.64cm"/>
+                <imagedata fileref="../images/img001.png"/>
             </imageobject>
         </mediaobject>
         <para>
         </para>
         <mediaobject>
             <imageobject>
-                <imagedata fileref="../images/img002.png" width="5.95cm" depth="1.64cm"/>
+                <imagedata fileref="../images/img002.png"/>
             </imageobject>
         </mediaobject>
         <para>metadataは以下のようになります:</para>
                     </td>
                 </tr>
                 <tr>
-                    <td align="justify">
+                    <td align="center">
                         <para>0</para>
                     </td>
-                    <td align="justify">
+                    <td align="center">
                         <para>5.2.0</para>
                     </td>
                     <td align="justify">
                     </td>
                 </tr>
                 <tr>
-                    <td align="justify">
+                    <td align="center">
                         <para>1</para>
                     </td>
-                    <td align="justify">
+                    <td align="center">
                         <para>5.4.0 alpha / beta</para>
                     </td>
                     <td align="left">
                     </td>
                 </tr>
                 <tr>
-                    <td>
+                    <td align="center">
                         <para>2</para>
                     </td>
-                    <td>
+                    <td align="center">
                         <para>5.4.0</para>
                     </td>
                     <td>
                     </td>
                 </tr>
                 <tr>
-                    <td align="justify">
-
+                    <td align="center">
+                       3
                     </td>
-                    <td align="justify">
-                        <para>6.0.0 (将来)</para>
+                    <td align="center">
+                        <para>6.0.0</para>
                     </td>
                     <td align="justify">
                         <para>.bin サポートを廃止.</para>
index d624d4f..3685c57 100644 (file)
         <para>формирует:</para>
         <mediaobject>
             <imageobject>
-                <imagedata fileref="../images/img001.png" width="5.95cm" depth="1.64cm"/>
+                <imagedata fileref="../images/img001.png"/>
             </imageobject>
         </mediaobject>
         <para>
         </para>
         <mediaobject>
             <imageobject>
-                <imagedata fileref="../images/img002.png" width="5.95cm" depth="1.64cm"/>
+                <imagedata fileref="../images/img002.png"/>
             </imageobject>
         </mediaobject>
         <para>в hdfview.</para>
                     </td>
                 </tr>
                 <tr>
-                    <td align="justify">
+                    <td align="center">
                         <para>0</para>
                     </td>
-                    <td align="justify">
+                    <td align="center">
                         <para>5.2.0</para>
                     </td>
                     <td align="justify">
                     </td>
                 </tr>
                 <tr>
-                    <td align="justify">
+                    <td align="center">
                         <para>1</para>
                     </td>
-                    <td align="justify">
+                    <td align="center">
                         <para>5.4.0 alpha / beta</para>
                     </td>
                     <td align="left">
                     </td>
                 </tr>
                 <tr>
-                    <td align="justify">
-
+                    <td align="center">
+                        3
                     </td>
-                    <td align="justify">
-                        <para>6.0.0 (будущая)</para>
+                    <td align="center">
+                        <para>6.0.0</para>
                     </td>
                     <td align="justify">
                         <para>.bin не поддерживается.</para>
index 9036d1a..f02081c 100644 (file)
@@ -1139,6 +1139,7 @@ replot_1.png=d9ab231632d9298a6f87718df49ce8ae
 replot_2.png=2bbd8e5516bcfba00fb343eff77b4736
 rotate_1.png=df252732000d1c17d23c04e038b1b0f3
 rpem_1.png=f1f661c0f1bc866f159ff8e328971f0f
+save_1.png=3735341e3e1dc6a290055825cc900ec9
 sca_1.png=26a128db93d82d857191be51313e1d87
 scatter3_1.png=aab921f0b450aa45bfbb5664bec0041e
 scatter3_2.png=15c5d3b32f8696f4208bbb5b2bad2d71
diff --git a/scilab/modules/helptools/images/save_1.png b/scilab/modules/helptools/images/save_1.png
new file mode 100644 (file)
index 0000000..32f5b8c
Binary files /dev/null and b/scilab/modules/helptools/images/save_1.png differ
index a70870d..39d1a80 100644 (file)
                 where "/path/to/lib" is replaced with the actual pathname of the lib file.
             </para>
         </refsect3>
+        <warning>
+            <para>
+                Scilab 6 can load data saved with Scilab>=5.4 in SOD format.
+            </para>
+            <para>
+                Data saved in the old Scilab&lt;5.4 format
+                <ulink url="http://bugzilla.scilab.org/14840">can't be directly loaded</ulink>:
+                Scilab 5.5.2 must be used as an intermediate to load them from the old format
+                and save them to the SOD format, which can be loaded in Scilab 6.
+            </para>
+        </warning>
     </refsection>
     <refsection>
         <title>Examples</title>
index 433131f..3a7aa77 100644 (file)
@@ -2,8 +2,8 @@
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) XXXX-2008 - INRIA
- *
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2018 - 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: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="save" xml:lang="en">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+        xmlns:svg="http://www.w3.org/2000/svg" xmlns: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="save" xml:lang="en">
     <refnamediv>
         <refname>save</refname>
-        <refpurpose>Save a variable or a serie of variables in a binary
-            file
+        <refpurpose>Saves some chosen variables in a binary data file
         </refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
-        <synopsis>save(filename [,x1,x2,...,xn])
-            save(fd [,x1,x2,...,xn])
+        <synopsis>
+            save(filename)
+            save(filename, x1, x2,...,xn)
+            save(filename, x1, x2,...,xn, "-append")
         </synopsis>
     </refsynopsisdiv>
     <refsection>
             <varlistentry>
                 <term>filename</term>
                 <listitem>
-                    <para>Character string containing the path of the file</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>fd</term>
-                <listitem>
-                    <para>A file descriptor given by a call to mopen</para>
+                    <para>Character string containing the path of the file.</para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>xi</term>
                 <listitem>
-                    <para>Arbitrary Scilab variable(s)</para>
+                    <para>
+                        Names (as strings) of Scilab variables to be saved. Objects returned by
+                        expressions -- like gcf() -- can't be directly saved. They must be
+                        explicitly named: <literal>f = gcf(); save(filename, "f")</literal>.
+                    </para>
                 </listitem>
             </varlistentry>
         </variablelist>
     <refsection>
         <title>Description</title>
         <para>
-            The <literal>save</literal> command can be used to save Scilab
-            current variables in a binary file. If a variable is a graphic handle, the
-            <literal>save</literal> function saves all the corresponding <link linkend="graphics_entities">graphics_entities</link> definition.
-        </para>
-        <para>The file can be given either by its paths or by its descriptor
-            previously given by <literal>mopen</literal>.
+            <literal>save(filename)</literal> saves in the file defined by <literal>filename</literal>
+            <emphasis>all</emphasis> Scilab variables defined by the user, and reachable at the
+            current level.
         </para>
+        <note>
+            <itemizedlist>
+                <listitem>
+                    <para>
+                        When some global variables are defined, only their local counterparts
+                        -- if any -- can be saved. Hence, the "global status" is never saved.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        If a variable is a graphic handle, <literal>save(..)</literal> records all
+                        the corresponding <emphasis>descending</emphasis>
+                        <link linkend="graphics_entities">graphical entity</link> definition,
+                        including its existing children -- if any.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        Saving a XML pointer is possible but does not save the pointed object. If in
+                        the meantime the XML object is deleted, restoring its pointer won't restore
+                        the object. Please see the dedicated example.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        TCL variables defined from Scilab (with <link linkend="TCL_SetVar">TCL_SetVar</link>)
+                        can't be saved. Only their counterparts in Scilab -- if any -- can be considered.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        Scilab save/load functions use the Scilab Open Data (SOD) binary format,
+                        based on the HDF-5 storage format. The SOD format is described
+                        <link linkend="save_format">there</link>. Scilab binary data files can be read
+                        and handled through external HDF-5 libraries or applications.
+                    </para>
+                </listitem>
+            </itemizedlist>
+        </note>
         <para>
-            <literal>save(filename)</literal> saves all current variables in the
-            file defined by <literal>filename</literal>.
+            When only some variables chosen among all defined ones must be saved, their names must
+            be listed after the filename, as in <literal>save(filename,"x","y")</literal>. If one
+            indicated variable is not defined, the file is not created or overwritten and an error
+            is yielded.
         </para>
         <para>
-            <literal>save(fd)</literal> saves all current variables in the file
-            defined by the descriptor <literal>fd</literal>. <emphasis role="bold">This prototype is obsolete and will be removed in Scilab 6.</emphasis>
+            The <literal>"-append"</literal> keyword can be used in option at any place after
+            the <varname>filename</varname>. Then, listed variables are appended to the existing
+            file. If some listed variables already exist in the file, their stored values are updated.
         </para>
         <para>
-            <literal>save(filename,x,y)</literal> or <literal>save(fd,x,y)</literal> (with <literal>x</literal> and <literal>y</literal> variables of your environment) saves only named variables <literal>x</literal> and <literal>y</literal>. <literal>save(fd,x,y)</literal> <emphasis role="bold"> is obsolete and will be removed in Scilab 6.</emphasis>
+            Saved variables can be reloaded by the
+            <literal>
+                <link linkend="load">load</link>
+            </literal>
+            command.
         </para>
+        <note>
+            The archives files generated with save() are portable to other operating systems and
+            architectures (little and big endian automatically handled).
+        </note>
+        <warning>
+            Built-in functions can't be saved.
+        </warning>
+    </refsection>
+    <refsection>
+        <title>Examples</title>
         <para>
-            <literal>save(filename,"x","y")</literal> (with <literal>"x"</literal> and <literal>"y"</literal> names of variables of your environment) will save your data using the SOD (Scilab Open Data) format (based on HDF5), format that will be readable by Scilab 6 family.
+            With homogeneous arrays of simple data types:
         </para>
+        <programlisting role="example"><![CDATA[
+// For each created object, we make a current copy for comparison after restoring.
+b = [%t %f %f];          bc = b;  // Booleans
+i = int8([0 -17 38 ]);   ic = i;  // Encoded integers
+d = [%pi %e %inf %i];    dc = d;  // Decimal numbers (real or complex numbers)
+p = (1-%z)^[1 2];        pc = p;  // Polynomials (real or complex coefficients)
+r = %z./(1-%z)^[1 2];    rc = r;  // Rationals (real or complex coefficients)
+t = ["Sci" "‫البرمجیات‬"];    tc = t;  // Texts
+sp = sprand(4,10,0.1);  spc = sp; // Sparse matrix of numbers
+spb = sp < 0.5;        spbc = spb;// Sparse matrix of boolean numbers
+
+path = TMPDIR + "/test.dat";
+save(path, "b","i","d","p","r","t","sp","spb")
+clear b i d p r t sp spb
+isdef(["b" "i" "d" "p" "r" "t" "sp" "spb"],"l")
+listvarinfile(path);
+load(path);
+isdef(["b" "i" "d" "p" "r" "t" "sp" "spb"],"l")
+[b==bc, i==ic, d==dc, t==tc, p==pc, r==rc, and(sp==spc), and(spb==spbc)]
+    ]]></programlisting>
+        <screen><![CDATA[
+--> path = TMPDIR + "/test.dat";
+--> save(path, "b","i","d","p","r","t","sp","spb")
+--> clear b i d p r t sp spb
+--> isdef(["b" "i" "d" "p" "r" "t" "sp" "spb"],"l")
+ ans  =
+  F F F F F F F F
+
+--> listvarinfile(path);
+Name                     Type           Size            Bytes
+-------------------------------------------------------------
+b                        boolean        1 by 3          12
+d                        double         1 by 4          64
+i                        integer        1 by 3          3
+p                        polynomial     1 by 2          40
+r                        tlist          4               108
+sp                       sparse         4 by 10         76
+spb                      boolean sparse 4 by 10         160
+t                        string         1 by 2          108
+
+--> load(path);
+--> isdef(["b" "i" "d" "p" "r" "t" "sp" "spb"],"l")
+ ans  =
+  T T T T T T T T
+
+--> [b==bc, i==ic, d==dc, t==tc, p==pc, r==rc, and(sp==spc), and(spb==spbc)]
+ans  =
+  T T T T T T T T T T T T T T T T T
+]]></screen>
         <para>
-            <literal>save(filename,"-append","w", "z")</literal> (with <literal>"w"</literal> and <literal>"z"</literal> names of variables of your environment) will append your data in the existing SOD file called <literal>filename</literal>.
+            With a user-defined macro:
         </para>
+        <programlisting role="example"><![CDATA[
+path = TMPDIR + "/test.dat";
+function myTest(), disp("User-defined macros can be saved"), endfunction
+save(path, "myTest")
+clear myTest
+listvarinfile(path);
+load(path);
+myTest()
+    ]]></programlisting>
+        <screen><![CDATA[
+--> clear myTest
+--> listvarinfile(path);
+Name                     Type           Size            Bytes
+-------------------------------------------------------------
+myTest                   macro          1 by 1          0
+
+--> load(path);
+--> myTest()
+ User-defined macros can be saved
+]]></screen>
         <para>
-            The change of format between the family 5 and 6 of Scilab has been decided because the 5 format is undocumented, not specified and hard to read. SOD (Scilab 6 default format) is fully documented and easy to read through HDF5 libraries or applications.
+            With (nested) heterogeneous containers:
         </para>
+        <programlisting role="example"><![CDATA[
+// lists
+L = list(%pi,%t,%s^2,"abc",{"Scilab" 2},list(%e,%z/(1-%z))); Lc = L;
+// cells arrays
+c = {%pi, %t ; %s^2, "abc"};  cc = c;
+// array of structures
+s = struct("n",%i+1, "p",(1+%z)^3, "L",L, "c",c); sc = s;
+
+path = TMPDIR + "/test.dat";
+save(path, "L", "c", "s")
+clear L c s
+isdef(["L" "c" "s"], "l")
+listvarinfile(path);
+load(path);
+[isequal(L,Lc) isequal(c,cc) isequal(s,sc)]
+    ]]></programlisting>
+        <screen><![CDATA[
+--> isdef(["L" "c" "s"], "l")
+ ans  =
+  F F F
+
+--> listvarinfile(path);
+Name                     Type           Size            Bytes
+-------------------------------------------------------------
+L                        list           6               156
+c                        cell           2 by 2          48
+s                        struct         2 by 2          864
+
+--> load(path);
+--> [isequal(L,Lc) isequal(c,cc) isequal(s,sc)]
+ ans  =
+  F F F
+]]></screen>
         <para>
-            Saved variables can be reloaded by the
-            <literal>
-                <link linkend="load">load</link>
-            </literal>
-            command.
+            With some graphic handles:
         </para>
-        <para>Note that the written file is portable to other operating systems and architectures (little and big endian).
+        <programlisting role="example"><![CDATA[
+clf reset
+subplot(1,2,1), param3d()
+subplot(1,2,2), plot2d4(), xtitle("plot2d4()"); a = gca();
+path = TMPDIR + "/test.dat";
+save(path, "a");       // We save only the right axes (plot2d4)
+clf reset, clear a
+xload(path);           // The right axes is restored and rendered
+gcf().axes_size = [700 300];
+    ]]></programlisting>
+        <scilab:image>
+            subplot(1,2,1), param3d()
+            subplot(1,2,2), plot2d4(), xtitle("plot2d4()"); a = gca();
+            path = TMPDIR + "/test.dat";
+            save(path, "a");       // We save only the right axes (hist3d)
+            clf reset, clear a
+            xload(path);           // The right axes is restored and rendered
+            gcf().axes_size = [700 300];
+        </scilab:image>
+        <para>
+            With a global variable:
         </para>
-    </refsection>
-    <refsection>
-        <title>Examples</title>
         <programlisting role="example"><![CDATA[
-// Binary format readable up to Scilab 5 family
-a=eye(2,2);b=ones(a);
-save('val.dat',a,b);
+path = TMPDIR + "/test.dat";
 clear a
-clear b
-load('val.dat','a','b');
+global a, a = 1.234;
+isglobal a
+save(path, "a")
+clear a, clearglobal a
+load(path); a
+isglobal("a")   // The global attribute was not saved and so is not restored
+    ]]></programlisting>
+        <screen><![CDATA[
+--> isglobal a
+ ans  =
+  T
+--> save(path, "a")
+--> clear a, clearglobal a
+--> load(path); a
+ a  =
+   1.234
+--> isglobal("a")
+ ans  =
+  F
+]]></screen>
+        <para>
+            With a XML pointer:
+        </para>
+        <programlisting role="example"><![CDATA[
+path = TMPDIR + "/test.dat";
+doc = xmlReadStr("<root><b>Hello</b></root>");
+save(path, "doc")
+clear doc             // This does not delete the document
+load(path); doc       // We restore the saved pointer to the document. It is still valid.
+// Let's delete both the document and the pointer to it:
+xmlDelete(doc), clear doc
+load(path);           // We restore the saved pointer (to the unexisting document)
+isdef("doc","l")        // The pointer is restored...
+xmlIsValidObject doc  //  but not the pointed document
+    ]]></programlisting>
+        <screen><![CDATA[
+--> path = TMPDIR + "/test.dat";
+--> doc = xmlReadStr("<root><b>Hello</b></root>");
+--> save(path, "doc")
+--> clear doc
+--> load(path); doc
+ doc  =
+XML Document
+url: Undefined
+root: XML Element
 
-// sequential save into a file
-fd=mopen('TMPDIR/foo','wb')
-for k=1:4, x=k^2;save(fd,x,k),end
-mclose(fd)
-fd=mopen('TMPDIR/foo','rb')
-for i=1:4, load(fd,'x','k');x,k,end
-mclose(fd)
+--> xmlDelete(doc), clear doc
+--> load(path)
+--> isdef("doc","l")
+ ans  =
+  T
+ doc  =
+--> xmlIsValidObject doc
+ ans  =
+  F
+]]></screen>
+        <para>
+            With the "-append" option:
+        </para>
+        <programlisting role="example"><![CDATA[
+a = 1; b = %t;
+path = TMPDIR + "/test.dat";
+save(path, "a", "b");
+listvarinfile(path);
+a = [%e %pi];
+c = %i;
+save(path, "a", "c", "-append");
+listvarinfile(path);
+clear a
+load(path, "a"); a
+    ]]></programlisting>
+        <screen><![CDATA[
+--> save(path, "a", "b");
+--> listvarinfile(path);
+Name                     Type           Size            Bytes
+-------------------------------------------------------------
+a                        double         1 by 1          8
+b                        boolean        1 by 1          4
 
-// appending variables to an old save file
-fd=mopen('TMPDIR/foo','rb+')
-mseek(0,fd,'end')
-lst=list(1,2,3)
-save(fd,lst)
-mclose(fd)
+--> a = [%e %pi];
+--> c = %i;
+--> save(path, "a", "c", "-append");
+--> listvarinfile(path);
+Name                     Type           Size            Bytes
+-------------------------------------------------------------
+a                        double         1 by 2          16
+b                        boolean        1 by 1          4
+c                        double         1 by 1          16
 
-// Binary format readable by Scilab 5.4.X and Scilab 6 family
-a=eye(2,2);b=ones(a);
-save("val.sod", "a", "b");
-clear a
-clear b
-load("val.sod", "a", "b");
- ]]></programlisting>
+--> clear a
+--> load(path, "a"); a    // has been updated
+ a  =
+   2.7182818   3.1415927
+]]></screen>
+        <para>
+            save() can't save TCL variables:
+        </para>
+        <programlisting role="example"><![CDATA[
+TCL_SetVar("myPi", 3.14);   // Creates the myPi variable in the TCL session
+myPi    // => error: the variable is a TCL one, not a Scilab one => It can't be save()d
+]]></programlisting>
+        <screen><![CDATA[
+--> myPi
+Undefined variable: myPi
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
@@ -129,13 +377,22 @@ load("val.sod", "a", "b");
                 <link linkend="load">load</link>
             </member>
             <member>
-                <link linkend="write">write</link>
+                <link linkend="save_format">save_format</link>
             </member>
             <member>
-                <link linkend="save_format">save_format</link>
+                <link linkend="savematfile">savematfile</link>
+            </member>
+            <member>
+                <link linkend="xsave">xsave</link>
+            </member>
+            <member>
+                <link linkend="saveGui">saveGui</link>
             </member>
             <member>
-                <link linkend="mopen">mopen</link>
+                <link linkend="write">write</link>
+            </member>
+            <member>
+                <link linkend="TCL_SetVar">TCL_SetVar</link>
             </member>
         </simplelist>
     </refsection>
@@ -145,19 +402,41 @@ load("val.sod", "a", "b");
             <revision>
                 <revnumber>5.0.0</revnumber>
                 <revremark>
-                    All <link linkend="uimenu">uimenu</link> or <link linkend="uicontrol">uicontrol</link> handles are also saved by this function.
+                    All <link linkend="uimenu">uimenu</link> or
+                    <link linkend="uicontrol">uicontrol</link> handles are also saved by this function.
                 </revremark>
             </revision>
             <revision>
                 <revnumber>5.4.0</revnumber>
                 <revdescription>
                     <itemizedlist>
-                        <listitem>When called with variables names (character string) as input, variables are saved in SOD format, format that will be readable by Scilab 6 family.</listitem>
-                        <listitem>The Scilab 5.X format is deprecated and will be removed with Scilab 6.</listitem>
-                        <listitem>Using save with a file descriptor as first input argument is deprecated and will be removed with Scilab 6.</listitem>
+                        <listitem>
+                            When called with variables names (character string) as input, variables
+                            are saved in SOD format (HDF5-based).
+                        </listitem>
+                        <listitem>
+                            The Scilab &lt;5.4 binary data format is deprecated.
+                        </listitem>
+                        <listitem>
+                            Using save() with a file descriptor as first input argument is deprecated.
+                        </listitem>
                     </itemizedlist>
                 </revdescription>
             </revision>
+            <revision>
+                <revnumber>6.0</revnumber>
+                <revremark>
+                    <itemizedlist>
+                        <listitem>
+                            save() no longer supports the old Scilab &lt;5.4 data format.
+                        </listitem>
+                        <listitem>
+                            The syntaxes save(fid) and save(fid, x1,..) with a file id are no longer
+                            supported.
+                        </listitem>
+                    </itemizedlist>
+                </revremark>
+            </revision>
         </revhistory>
     </refsection>
 </refentry>
diff --git a/scilab/modules/io/help/ja_JP/save.xml b/scilab/modules/io/help/ja_JP/save.xml
deleted file mode 100644 (file)
index fad2f37..0000000
+++ /dev/null
@@ -1,177 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) XXXX-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="save" xml:lang="ja">
-    <refnamediv>
-        <refname>save</refname>
-        <refpurpose>バイナリファイルに1個または複数の変数を保存する</refpurpose>
-    </refnamediv>
-    <refsynopsisdiv>
-        <title>呼び出し手順</title>
-        <synopsis>save(filename [,x1,x2,...,xn])
-            save(fd [,x1,x2,...,xn])
-        </synopsis>
-    </refsynopsisdiv>
-    <refsection>
-        <title>引数</title>
-        <variablelist>
-            <varlistentry>
-                <term>filename</term>
-                <listitem>
-                    <para>ファイルのパスを含む文字列</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>fd</term>
-                <listitem>
-                    <para>mopenをコールすることにより得られたファイル記述子</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xi</term>
-                <listitem>
-                    <para>任意のScilab変数</para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>説明</title>
-        <para>
-            <literal>save</literal>コマンドはカレントのScilab変数を
-            バイナリファイルに保存する際に使用されます.
-            変数がグラフィックハンドルの場合,
-            <literal>save</literal>関数は対応する<link linkend="graphics_entities">graphics_entities</link>の定義を全て保存します.
-        </para>
-        <para>
-            ファイルはパスまたは<literal>mopen</literal>により得られたファイル記述子の
-            どちらかで指定できます.
-        </para>
-        <para>
-            <literal>save(filename)</literal> は<literal>filename</literal>で指定したファイルに
-            カレントの全ての変数を保存します.
-        </para>
-        <para>
-            <literal>save(fd)</literal>は記述子<literal>fd</literal>で指定したファイルに
-            カレントの全ての変数を保存します.
-            <emphasis role="bold">このプロトタイプは廃止予定であり、
-                Scilab 6では削除されます.
-            </emphasis>
-        </para>
-        <para>
-            (実行環境の変数<literal>x</literal> および <literal>y</literal> を指定した)
-            <literal>save(filename,x,y)</literal> または <literal>save(fd,x,y)</literal> は
-            <literal>x</literal> および <literal>y</literal>という名前の変数のみを保存します.
-            <literal>save(fd,x,y)</literal> <emphasis role="bold"> は廃止予定であり,
-                Scilab 6では削除されます.
-            </emphasis>
-        </para>
-        <para>
-            (実行環境の変数名 <literal>"x"</literal> および <literal>"y"</literal> を指定した)
-            <literal>save(filename,"x","y")</literal> は(HDF5に基づく)SOD (Scilab Open Data)形式で
-            データを保存します.このフォーマットは Scilab 6シリーズで読むことができます.
-        </para>
-        <para>
-            Scilab 5シリーズと6シリーズの間でフォーマットの変更が決められました.
-            これは,5形式は文書化されておらず,仕様が既定されておらず,読み込むことが困難であったためです.
-            SOD (Scilab 6 のデフォルト形式)は完全に文書化され,HDF5ライブラリまたはアプリケーションにより
-            容易に読み込むことができます.
-        </para>
-        <para>
-            保存された変数は
-            <literal>
-                <link linkend="load">load</link>
-            </literal>
-            コマンドにより再度読み込むことができます.
-        </para>
-        <para>書き込まれたファイルは他のオペレーティングシステムやアーキテクチャ(リトルおよびビッグインディアン)に
-            対する可搬性があります.
-        </para>
-    </refsection>
-    <refsection>
-        <title>例</title>
-        <programlisting role="example"><![CDATA[
-// Scilab 5 ファミリーまでで可読なバイナリ形式
-a=eye(2,2);b=ones(a);
-save('val.dat',a,b);
-clear a
-clear b
-load('val.dat','a','b');
-// ファイルにシーケンシャルに保存
-fd=mopen('TMPDIR/foo','wb')
-for k=1:4, x=k^2;save(fd,x,k),end
-mclose(fd)
-fd=mopen('TMPDIR/foo','rb')
-for i=1:4, load(fd,'x','k');x,k,end
-mclose(fd)
-// 変数を既存のファイルに追加
-fd=mopen('TMPDIR/foo','rb+')
-mseek(0,fd,'end')
-lst=list(1,2,3)
-save(fd,lst)
-mclose(fd)
-// Scilab 5.4.X および Scilab 6 ファミリーで可読なバイナリ形式
-a=eye(2,2);b=ones(a);
-save("val.sod", "a", "b");
-clear a
-clear b
-load("val.sod", "a", "b");
- ]]></programlisting>
-    </refsection>
-    <refsection role="see also">
-        <title>参照</title>
-        <simplelist type="inline">
-            <member>
-                <link linkend="load">load</link>
-            </member>
-            <member>
-                <link linkend="write">write</link>
-            </member>
-            <member>
-                <link linkend="save_format">save_format</link>
-            </member>
-            <member>
-                <link linkend="mopen">mopen</link>
-            </member>
-        </simplelist>
-    </refsection>
-    <refsection>
-        <title>履歴</title>
-        <revhistory>
-            <revision>
-                <revnumber>5.0.0</revnumber>
-                <revremark>
-                    <link linkend="uimenu">uimenu</link> または
-                    <link linkend="uicontrol">uicontrol</link> ハンドルもこの関数で保存されます.
-                </revremark>
-            </revision>
-            <revision>
-                <revnumber>5.4.0</revnumber>
-                <revdescription>
-                    <itemizedlist>
-                        <listitem>
-                            変数名(文字列)を入力とする場合,変数はScilab 6ファミリーで可読な
-                            SOD形式で保存されます.
-                        </listitem>
-                        <listitem>Scilab 5.X形式は廃止予定であり,Scilab 6で削除されます.</listitem>
-                        <listitem>
-                            ファイル記述子を入力引数とするsaveは廃止予定であり,Scilab 6で削除されます.
-                        </listitem>
-                    </itemizedlist>
-                </revdescription>
-            </revision>
-        </revhistory>
-    </refsection>
-</refentry>
diff --git a/scilab/modules/io/help/pt_BR/save.xml b/scilab/modules/io/help/pt_BR/save.xml
deleted file mode 100644 (file)
index 4431e29..0000000
+++ /dev/null
@@ -1,122 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) XXXX-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="save" xml:lang="pt">
-    <refnamediv>
-        <refname>save</refname>
-        <refpurpose>salvando variáveis em arquivos binários</refpurpose>
-    </refnamediv>
-    <refsynopsisdiv>
-        <title>Seqüência de Chamamento</title>
-        <synopsis>save(filename [,x1,x2,...,xn])
-            save(fd [,x1,x2,...,xn])
-        </synopsis>
-    </refsynopsisdiv>
-    <refsection>
-        <title>Parâmetros</title>
-        <variablelist>
-            <varlistentry>
-                <term>filename</term>
-                <listitem>
-                    <para>string contendo o endereço do arquivo</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>fd</term>
-                <listitem>
-                    <para>descritor do arquivo fornecido por uma chamada a mopen</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>xi</term>
-                <listitem>
-                    <para>variável(is) Scilab arbitrárias</para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>Descrição</title>
-        <para>
-            O comando <literal>save</literal> pode ser usado para salvar as
-            variáveis Scilab correntes em um arquivo. Se uma variável é um manipulador
-            gráfico, a função <literal>save</literal> salva todas as definições de
-            <link linkend="graphics_entities">graphics_entities</link> (entidades
-            gráficas) correspondentes.
-        </para>
-        <para>
-            Desde o Scilab 5.0, todos os manipuladores de <link linkend="uimenu">uimenu</link> ou <link linkend="uicontrol">uicontrol</link> também são gravados por esta
-            função.
-        </para>
-        <para>O arquivo pode ser fornecido tanto pelo seu endereço quanto por seu
-            descritor dado previamente por <literal>mopen</literal>.
-        </para>
-        <para>
-            <literal>save(filename)</literal> salva todas as variáveis correntes
-            definidas por <literal>filename</literal>.
-        </para>
-        <para>
-            <literal>save(fd)</literal> salva todas as variáveis correntes
-            definidas pelo descritor <literal>fd</literal>.
-        </para>
-        <para>
-            <literal>save(filename,x,y)</literal> ou
-            <literal>save(fd,x,y)</literal> salva apenas as variáveis chamadas
-            <literal>x</literal> e <literal>y</literal>.
-        </para>
-        <para>Variáveis salvas podem ser recarregadas através do comando
-            <literal>load</literal>.
-        </para>
-    </refsection>
-    <refsection>
-        <title>Exemplos</title>
-        <programlisting role="example"><![CDATA[
-a=eye(2,2);b=ones(a);
-save('val.dat',a,b);
-clear a
-clear b
-load('val.dat','a','b');
-
-// gravação seqüêncial em um arquivo
-fd=mopen('TMPDIR/foo','wb')
-for k=1:4, x=k^2;save(fd,x,k),end
-mclose(fd)
-fd=mopen('TMPDIR/foo','rb')
-for i=1:4, load(fd,'x','k');x,k,end
-mclose(fd)
-
-// anexando variáveis a um arquivo gravado antigo
-fd=mopen('TMPDIR/foo','rb+')
-mseek(0,fd,'end')
-lst=list(1,2,3)
-save(fd,lst)
-mclose(fd)
- ]]></programlisting>
-    </refsection>
-    <refsection>
-        <title>Ver Também</title>
-        <simplelist type="inline">
-            <member>
-                <link linkend="load">load</link>
-            </member>
-            <member>
-                <link linkend="save_format">save_format</link>
-            </member>
-            <member>
-                <link linkend="mopen">mopen</link>
-            </member>
-        </simplelist>
-    </refsection>
-</refentry>