Improve matio help pages + add examples

Change-Id: I668c8ac6df51eba06775071c992b45b7f52e52de

diff --git a/scilab/modules/matio/help/en_US/matfile_close.xml b/scilab/modules/matio/help/en_US/matfile_close.xml
index 6a54967..9742511 100644 (file)
--- a/scilab/modules/matio/help/en_US/matfile_close.xml
+++ b/scilab/modules/matio/help/en_US/matfile_close.xml
@@ -13,7 +13,7 @@
 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="matfile_close">
     <refnamediv>
         <refname>matfile_close</refname>
-        <refpurpose>Closes a Matlab V5 binary MAT-file.</refpurpose>
+        <refpurpose>Closes a Matlab binary MAT-file.</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Calling Sequence</title>
@@ -46,6 +46,24 @@
             Closes a Matlab binary MAT-file opened by <link linkend="matfile_open">matfile_open</link>.
         </para>
     </refsection>
+    <refsection>
+        <title>Examples</title>
+        <programlisting role="example"><![CDATA[
+fd = matfile_open("test_matfile.mat","w");
+matfile_varwrite(fd, "foo", "bar", %t);
+if matfile_close(fd) == %t then
+disp("close worked!");
+else
+disp("close failed!");
+end
+
+fd = matfile_open("test_matfile.mat");
+matfile_listvar(fd)
+matfile_close(fd);
+
+ ]]></programlisting>
+    </refsection>
+    
     <refsection role="see also">
         <title>See Also</title>
         <simplelist type="inline">

diff --git a/scilab/modules/matio/help/en_US/matfile_listvar.xml b/scilab/modules/matio/help/en_US/matfile_listvar.xml
index f89c21a..8c89f53 100644 (file)
--- a/scilab/modules/matio/help/en_US/matfile_listvar.xml
+++ b/scilab/modules/matio/help/en_US/matfile_listvar.xml
@@ -13,7 +13,7 @@
 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="matfile_listvar">
     <refnamediv>
         <refname>matfile_listvar</refname>
-        <refpurpose>Lists variables of a Matlab V5 binary MAT-file.</refpurpose>
+        <refpurpose>Lists variables of a Matlab binary MAT-file.</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Calling Sequence</title>
@@ -56,6 +56,24 @@
             Lists variables of a Matlab binary MAT-file opened by <link linkend="matfile_open">matfile_open</link>.
         </para>
     </refsection>
+    <refsection>
+        <title>Examples</title>
+        <programlisting role="example"><![CDATA[
+A = rand(10,10);
+B = sprand(100,100,0.1);
+C = "foo";
+D = "bar";
+savematfile('test_matfile.mat','A','B','C','D','-v6');
+clear();
+fd = matfile_open("test_matfile.mat");
+[name, classes, types]=matfile_listvar(fd);
+matfile_close(fd);
+
+for i=1:size(name,"*") do
+disp("The variable " + name(i) + " has type " + string(types(i)) + " and class " + string(classes(i)))
+end
+ ]]></programlisting>
+    </refsection>
     <refsection role="see also">
         <title>See Also</title>
         <simplelist type="inline">

diff --git a/scilab/modules/matio/help/en_US/matfile_open.xml b/scilab/modules/matio/help/en_US/matfile_open.xml
index 811af1e..68858c2 100644 (file)
--- a/scilab/modules/matio/help/en_US/matfile_open.xml
+++ b/scilab/modules/matio/help/en_US/matfile_open.xml
@@ -13,7 +13,7 @@
 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="matfile_open">
     <refnamediv>
         <refname>matfile_open</refname>
-        <refpurpose>Opens a Matlab V5 binary MAT-file.</refpurpose>
+        <refpurpose>Opens a Matlab binary MAT-file.</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Calling Sequence</title>
@@ -61,6 +61,25 @@
         <para>
             Opens a Matlab binary MAT-file for reading or writing data.
         </para>
+        <para>
+            <warning>
+                If <varname>mode</varname> is set to <literal>w</literal>, the content of <varname>filename</varname> will be reseted.
+            </warning>
+        </para>
+    </refsection>
+    <refsection>
+        <title>Examples</title>
+        <programlisting role="example"><![CDATA[
+A = rand(10,10);
+B = sprand(100,100,0.1);
+savematfile('test_matfile.mat','A','B','-v6');
+clear();
+fd = matfile_open("test_matfile.mat");
+matfile_listvar(fd)
+matfile_close(fd);
+
+//fd = matfile_open("test_matfile.mat","w"); // Empty test_matfile.mat
+ ]]></programlisting>
     </refsection>
     <refsection role="see also">
         <title>See Also</title>

diff --git a/scilab/modules/matio/help/en_US/matfile_varreadnext.xml b/scilab/modules/matio/help/en_US/matfile_varreadnext.xml
index bb15ff4..b8b5f27 100644 (file)
--- a/scilab/modules/matio/help/en_US/matfile_varreadnext.xml
+++ b/scilab/modules/matio/help/en_US/matfile_varreadnext.xml
@@ -13,7 +13,7 @@
 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="matfile_varreadnext">
     <refnamediv>
         <refname>matfile_varreadnext</refname>
-        <refpurpose>Reads next variable in a Matlab V5 binary MAT-file.</refpurpose>
+        <refpurpose>Reads next variable in a Matlab binary MAT-file.</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Calling Sequence</title>
@@ -70,6 +70,30 @@
             Reads next variable in a Matlab binary MAT-file opened by <link linkend="matfile_open">matfile_open</link>.
         </para>
     </refsection>
+    <refsection>
+        <title>Examples</title>
+        <programlisting role="example"><![CDATA[
+A = rand(10,10);
+B = sprand(10,10,0.1);
+C = "foo";
+D = "bar";
+savematfile('test_matfile.mat','A','B','C','D','-v6');
+clear();
+fd = matfile_open("test_matfile.mat");
+//-- Loop on the stored variables
+while %t
+   [Name, Value, Type] = matfile_varreadnext(fd);
+   if Name == "" then
+      break;
+   else
+      disp("The variable " + Name + " has type " + string(Type) + " and contains:");
+      disp(Value);
+   end
+end
+matfile_close(fd);
+
+ ]]></programlisting>
+    </refsection>
     <refsection role="see also">
         <title>See Also</title>
         <simplelist type="inline">

diff --git a/scilab/modules/matio/help/en_US/matfile_varwrite.xml b/scilab/modules/matio/help/en_US/matfile_varwrite.xml
index 30bda6e..95b3383 100644 (file)
--- a/scilab/modules/matio/help/en_US/matfile_varwrite.xml
+++ b/scilab/modules/matio/help/en_US/matfile_varwrite.xml
@@ -13,11 +13,11 @@
 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="matfile_varwrite">
     <refnamediv>
         <refname>matfile_varwrite</refname>
-        <refpurpose>Write a variable in a Matlab V5 binary MAT-file.</refpurpose>
+        <refpurpose>Write a variable in a Matlab binary MAT-file.</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Calling Sequence</title>
-        <synopsis>status = matfile_varreadnext(fd, name, value, compressionflag)</synopsis>
+        <synopsis>status = matfile_varwrite(fd, name, value, compressionflag)</synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Arguments</title>
@@ -65,6 +65,24 @@
         <para>
             Writes a variable in a Matlab binary MAT-file opened by <link linkend="matfile_open">matfile_open</link>.
         </para>
+        <para>
+            <warning>
+                <function>matfile_varwrite</function> will fail if the MAT-file is not open with the "w" mode and will override any variable stored in the file.
+            </warning>
+        </para>
+    </refsection>
+    <refsection>
+        <title>Examples</title>
+        <programlisting role="example"><![CDATA[
+fd = matfile_open("test_matfile.mat","w");
+matfile_varwrite(fd, "foo", "bar", %t);
+matfile_close(fd);
+
+fd = matfile_open("test_matfile.mat");
+matfile_listvar(fd)
+matfile_close(fd);
+
+ ]]></programlisting>
     </refsection>
     <refsection role="see also">
         <title>See Also</title>