[doc] mputstr() page overhauled 29/21529/4
Samuel GOUGEON [Sun, 5 Jul 2020 21:09:18 +0000 (23:09 +0200)]
Change-Id: I1c8f56cd6922709ac86390f398c87e8d033f8036

scilab/modules/fileio/help/en_US/mputstr.xml
scilab/modules/fileio/help/ja_JP/mputstr.xml [deleted file]
scilab/modules/fileio/help/ru_RU/mputstr.xml

index 91aab13..dc74b00 100644 (file)
@@ -3,8 +3,8 @@
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) 2008 - INRIA
  * ...
- *
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2020 - Samuel GOUGEON
  *
  * This file is hereby licensed under the terms of the GNU GPL v2.0,
  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  * along with this program.
  *
  -->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="mputstr">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:db="http://docbook.org/ns/docbook"
+          xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="mputstr">
     <refnamediv>
         <refname>mputstr</refname>
-        <refpurpose>writes a character string in a file</refpurpose>
+        <refpurpose>write a single text in an open file</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
-        <synopsis>mputstr(str [, fd]);</synopsis>
+        <synopsis>
+            mputstr(str)
+            mputstr(str, fid)
+        </synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Arguments</title>
         <variablelist>
             <varlistentry>
-                <term>fd</term>
+                <term>fid</term>
                 <listitem>
                     <para>
-                        a scalar: a file descriptor returned by the function <function>mopen</function>. <literal>-1</literal> stands for last opened file. Default value is <literal>-1</literal>.
+                        integer: file identifier returned by <literal>mopen(…)</literal>.
+                        <literal>-1</literal> (default) stands for the last opened file.
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>str</term>
                 <listitem>
-                    <para>a character string.</para>
+                    <para>
+                        Single text to write in the file. Multilingual UTF-8 characters are accepted.
+                        <varname>str</varname> can include special formatting characters
+                        like ascii(9) (tab), ascii(10) (newline) and ascii(13) (carriage return).
+                        Sequences like "\t", "\n" and "\r" have no special meaning and are written as is.
+                    </para>
                 </listitem>
             </varlistentry>
         </variablelist>
     <refsection>
         <title>Description</title>
         <para>
-            The <function>mputstr</function> function allows to write a character string <varname>str</varname> in a binary file.
+            <literal>mputstr(…)</literal> writes a character string <varname>str</varname>
+            in a binary or text file. <varname>str</varname> is buffered: It is actually
+            written in the file only when closing this one.
         </para>
     </refsection>
     <refsection>
         <title>Examples</title>
         <programlisting role="example"><![CDATA[
+myFile = tempname();
+fid = mopen(myFile, "wt");
+
+mputstr("Scilab", fid);
+mgetl(myFile) // => []. "Scilab" has been buffered
+mputstr(" and Xcos", fid);
+mgetl(myFile) // => still []. " and Xcos" added to the buffer
+
+// Only one text can be sent at a once:
+mputstr(["Science" ; "Innovation"], fid);     // => error
+
+mclose(fid);
+mgetl(myFile) // => "Scilab and Xcos"
+mdelete(myFile);
+     ]]></programlisting>
+        <para/>
+        <screen><![CDATA[
+--> mputstr("Scilab", fid);
+--> mgetl(myFile) // => []. "Scilab" has been buffered
+ ans  =
+    []
+
+--> mputstr(" and Xcos", fid);
+--> mgetl(myFile) // => still []. " and Xcos" added to the buffer
+ ans  =
+    []
 
-this_file = pathconvert(TMPDIR+"/mputstr.txt", %F);
+--> // Only one text can be sent:
+--> mputstr(["Science" ; "Innovation"], fid);    // => error
+mputstr: Argument #1: Scalar (1 element) expected.
 
-fd = mopen(this_file, "wt");
-mputstr("Scilab", fd);
-mclose(fd);
+--> mclose(fid);
+--> mgetl(myFile)
+ ans  =
+  "Scilab and Xcos"
+]]></screen>
+        <para/>
+        <para>
+            Use UTF-8 and special formatting characters:
+        </para>
+        <programlisting role="example"><![CDATA[
+[tab, nl] = (ascii(9), ascii(10));
+myFile = tempname();
+fid = mopen(myFile, "wt");
 
-mgetl(this_file) // Scilab
+mputstr("Επιστήμη", fid);
+mputstr(ascii(10), fid);      // Line feed
+mputstr("Τεχνολογία" + nl, fid);
+mputstr(tab, fid);           // Heading tab
+mputstr("innovation", fid);
+mputstr(nl + "Science" + nl + tab + "technology", fid);
+mclose(fid);
+mgetl(myFile)
 
+mdelete(myFile);
  ]]></programlisting>
+    <screen><![CDATA[
+--> mputstr("Επιστήμη", fid);
+--> mputstr(ascii(10), fid);      // Line feed
+--> mputstr("Τεχνολογία" + nl, fid);
+--> mputstr(tab, fid);           // Heading tab
+--> mputstr("innovation", fid);
+--> mputstr(nl + "Science" + nl + tab + "technology", fid);
+--> mclose(fid);
+--> mgetl(myFile)
+ ans  =
+  "Επιστήμη"
+  "Τεχνολογία"
+  "        innovation"
+  "Science"    
+  "        technology"
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
         <simplelist type="inline">
             <member>
-                <link linkend="mclose">mclose</link>
-            </member>
-            <member>
-                <link linkend="meof">meof</link>
-            </member>
-            <member>
-                <link linkend="mfprintf">mfprintf</link>
-            </member>
-            <member>
-                <link linkend="fprintfMat">fprintfMat</link>
-            </member>
-            <member>
-                <link linkend="mfscanf">mfscanf</link>
-            </member>
-            <member>
-                <link linkend="fscanfMat">fscanfMat</link>
-            </member>
-            <member>
-                <link linkend="mget">mget</link>
-            </member>
-            <member>
                 <link linkend="mgetstr">mgetstr</link>
             </member>
             <member>
-                <link linkend="mopen">mopen</link>
+                <link linkend="mputl">mputl</link>
             </member>
             <member>
-                <link linkend="mprintf">mprintf</link>
+                <link linkend="mgetl">mgetl</link>
             </member>
             <member>
                 <link linkend="mput">mput</link>
             </member>
             <member>
-                <link linkend="mseek">mseek</link>
+                <link linkend="mfprintf">mfprintf</link>
+            </member>
+            <member>
+                <link linkend="save">save</link>
             </member>
             <member>
-                <link linkend="mtell">mtell</link>
+                <link linkend="write">write</link>
             </member>
             <member>
-                <link linkend="mdelete">mdelete</link>
+                <link linkend="csvWrite">csvWrite</link>
             </member>
         </simplelist>
     </refsection>
diff --git a/scilab/modules/fileio/help/ja_JP/mputstr.xml b/scilab/modules/fileio/help/ja_JP/mputstr.xml
deleted file mode 100644 (file)
index 3378a4e..0000000
+++ /dev/null
@@ -1,218 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-
-<!--
- * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) 2008 - INRIA
- * ...
- *
- * Copyright (C) 2012 - 2016 - Scilab Enterprises
- *
- * This file is hereby licensed under the terms of the GNU GPL v2.0,
- * pursuant to article 5.3.4 of the CeCILL v.2.1.
- * This file was originally licensed under the terms of the CeCILL v2.1,
- * and continues to be available under such terms.
- * For more information, see the COPYING file which you should have received
- * along with this program.
- *
- -->
-
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="ja" xml:id="mputstr">
-
-    <refnamediv>
-
-        <refname>mputstr</refname>
-
-        <refpurpose>ファイルに文字列を書き込む</refpurpose>
-
-    </refnamediv>
-
-    <refsynopsisdiv>
-
-        <title>呼び出し手順</title>
-
-        <synopsis>mputstr(str [, fd]);</synopsis>
-
-    </refsynopsisdiv>
-
-    <refsection>
-
-        <title>引数</title>
-
-        <variablelist>
-
-            <varlistentry>
-
-                <term>fd</term>
-
-                <listitem>
-
-                    <para>
-
-                        スカラー:  <function>mopen</function>関数により返されたファイル記述子.
-
-                        <literal>-1</literal>は直近にオープンされたファイルを意味します.
-
-                        デフォルト値は<literal>-1</literal>です.
-
-                    </para>
-
-                </listitem>
-
-            </varlistentry>
-
-            <varlistentry>
-
-                <term>str</term>
-
-                <listitem>
-
-                    <para>文字列.</para>
-
-                </listitem>
-
-            </varlistentry>
-
-        </variablelist>
-
-    </refsection>
-
-    <refsection>
-
-        <title>説明</title>
-
-        <para>
-
-            <function>mputstr</function> 関数により文字列<varname>str</varname>を
-
-            バイナリファイルに書き込むことが可能です.
-
-        </para>
-
-    </refsection>
-
-    <refsection>
-
-        <title>例</title>
-
-        <programlisting role="example"><![CDATA[
-
-this_file = pathconvert(TMPDIR+"/mputstr.txt", %F);
-
-fd = mopen(this_file, "wt");
-mputstr("Scilab", fd);
-mclose(fd);
-
-mgetl(this_file) // Scilab
-
- ]]></programlisting>
-
-    </refsection>
-
-    <refsection role="see also">
-
-        <title>参照</title>
-
-        <simplelist type="inline">
-
-            <member>
-
-                <link linkend="mclose">mclose</link>
-
-            </member>
-
-            <member>
-
-                <link linkend="meof">meof</link>
-
-            </member>
-
-            <member>
-
-                <link linkend="mfprintf">mfprintf</link>
-
-            </member>
-
-            <member>
-
-                <link linkend="fprintfMat">fprintfMat</link>
-
-            </member>
-
-            <member>
-
-                <link linkend="mfscanf">mfscanf</link>
-
-            </member>
-
-            <member>
-
-                <link linkend="fscanfMat">fscanfMat</link>
-
-            </member>
-
-            <member>
-
-                <link linkend="mget">mget</link>
-
-            </member>
-
-            <member>
-
-                <link linkend="mgetstr">mgetstr</link>
-
-            </member>
-
-            <member>
-
-                <link linkend="mopen">mopen</link>
-
-            </member>
-
-            <member>
-
-                <link linkend="mprintf">mprintf</link>
-
-            </member>
-
-            <member>
-
-                <link linkend="mput">mput</link>
-
-            </member>
-
-            <member>
-
-                <link linkend="mputstr">mputstr</link>
-
-            </member>
-
-            <member>
-
-                <link linkend="mscanf">mscanf</link>
-
-            </member>
-
-            <member>
-
-                <link linkend="mseek">mseek</link>
-
-            </member>
-
-            <member>
-
-                <link linkend="mtell">mtell</link>
-
-            </member>
-
-            <member>
-
-                <link linkend="mdelete">mdelete</link>
-
-            </member>
-
-        </simplelist>
-
-    </refsection>
-
-</refentry>
-
index 7ac4334..8b614bf 100644 (file)
@@ -3,8 +3,8 @@
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) 2008 - INRIA
  * ...
- *
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2020 - Samuel GOUGEON
  *
  * This file is hereby licensed under the terms of the GNU GPL v2.0,
  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  * along with this program.
  *
  -->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="ru" xml:id="mputstr">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:db="http://docbook.org/ns/docbook"
+          xmlns:scilab="http://www.scilab.org" xml:lang="ru" xml:id="mputstr">
     <refnamediv>
         <refname>mputstr</refname>
-        <refpurpose>записывает символьную строку в файл</refpurpose>
+        <refpurpose>запись отдельного текста в открытый файл</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Синтаксис</title>
-        <synopsis>mputstr(str [, fd]);</synopsis>
+        <synopsis>
+            mputstr(str)
+            mputstr(str, fid)
+        </synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Аргументы</title>
         <variablelist>
             <varlistentry>
-                <term>fd</term>
+                <term>fid</term>
                 <listitem>
                     <para>
-                        скаляр: дескриптор файла, возвращённый функцией <function>mopen</function>. Для последнего открытого файла ставится <literal>-1</literal>. Значение по умолчанию <literal>-1</literal>.
+                        целое число: идентификатор файла, возвращённый
+                        <literal>mopen(…)</literal>. <literal>-1</literal>
+                        (по умолчанию) стоит для последнего открытого файла.
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>str</term>
                 <listitem>
-                    <para>символьная строка.</para>
+                    <para>
+                        Отдельный текст для записи в файл. Принимаются мультиязыковые
+                        символы UTF-8. <varname>str</varname> может включать в
+                        себя специальные символы форматирования, такие как ascii(9)
+                        (табулятор), ascii(10) (новая строка) and ascii(13)
+                        (возврат каретки). Такие последовательности, как "\t",
+                        "\n" и "\r" не имеют специального значения и записываются
+                        как есть.
+                    </para>
                 </listitem>
             </varlistentry>
         </variablelist>
     <refsection>
         <title>Описание</title>
         <para>
-            Функция <function>mputstr</function> позволяет записать символьную строку <varname>str</varname> в двоичный файл.
+            <literal>mputstr(…)</literal> записывает символьную строку
+            <varname>str</varname> в двоичный или текстовый файл. <varname>str</varname>
+            буферизуется: фактически она записывается в файл только при его
+            закрытии.
         </para>
     </refsection>
     <refsection>
-        <title>Examples</title>
+        <title>Примеры</title>
         <programlisting role="example"><![CDATA[
+myFile = tempname();
+fid = mopen(myFile, "wt");
+
+mputstr("Scilab", fid);
+mgetl(myFile) // => []. "Scilab" буферизован
+mputstr(" and Xcos", fid);
+mgetl(myFile) // => still []. " and Xcos" добавляется в буфер
 
-this_file = pathconvert(TMPDIR+"/mputstr.txt", %F);
+// Только один текст может быть послан за раз:
+mputstr(["Science" ; "Innovation"], fid);     // => error
 
-fd = mopen(this_file, "wt");
-mputstr("Scilab", fd);
-mclose(fd);
+mclose(fid);
+mgetl(myFile) // => "Scilab and Xcos"
+mdelete(myFile);
+     ]]></programlisting>
+        <para/>
+        <screen><![CDATA[
+--> mputstr("Scilab", fid);
+--> mgetl(myFile) // => []. "Scilab"  буферизован
+ ans  =
+    []
 
-mgetl(this_file) // Scilab
+--> mputstr(" and Xcos", fid);
+--> mgetl(myFile) // => still []. " and Xcos" добавляется в буфер
+ ans  =
+    []
 
+--> // Только один текст может быть послан за раз:
+--> mputstr(["Science" ; "Innovation"], fid);    // => error
+mputstr: Argument #1: Scalar (1 element) expected.
+
+--> mclose(fid);
+--> mgetl(myFile)
+ ans  =
+  "Scilab and Xcos"
+]]></screen>
+        <para/>
+        <para>
+            Использование UTF-8 и специальные символы форматирования:
+        </para>
+        <programlisting role="example"><![CDATA[
+[tab, nl] = (ascii(9), ascii(10));
+myFile = tempname();
+fid = mopen(myFile, "wt");
+
+mputstr("Επιστήμη", fid);
+mputstr(ascii(10), fid);      // перевод строки
+mputstr("Τεχνολογία" + nl, fid);
+mputstr(tab, fid);           // табуляция в начале строки
+mputstr("innovation", fid);
+mputstr(nl + "Science" + nl + tab + "technology", fid);
+mclose(fid);
+mgetl(myFile)
+
+mdelete(myFile);
  ]]></programlisting>
+    <screen><![CDATA[
+--> mputstr("Επιστήμη", fid);
+--> mputstr(ascii(10), fid);      // перевод строки
+--> mputstr("Τεχνολογία" + nl, fid);
+--> mputstr(tab, fid);           // табуляция в начале строки
+--> mputstr("innovation", fid);
+--> mputstr(nl + "Science" + nl + tab + "technology", fid);
+--> mclose(fid);
+--> mgetl(myFile)
+ ans  =
+  "Επιστήμη"
+  "Τεχνολογία"
+  "        innovation"
+  "Science"    
+  "        technology"
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>Смотрите также</title>
         <simplelist type="inline">
             <member>
-                <link linkend="mclose">mclose</link>
-            </member>
-            <member>
-                <link linkend="meof">meof</link>
-            </member>
-            <member>
-                <link linkend="mfprintf">mfprintf</link>
-            </member>
-            <member>
-                <link linkend="fprintfMat">fprintfMat</link>
-            </member>
-            <member>
-                <link linkend="mfscanf">mfscanf</link>
-            </member>
-            <member>
-                <link linkend="fscanfMat">fscanfMat</link>
-            </member>
-            <member>
-                <link linkend="mget">mget</link>
-            </member>
-            <member>
                 <link linkend="mgetstr">mgetstr</link>
             </member>
             <member>
-                <link linkend="mopen">mopen</link>
+                <link linkend="mputl">mputl</link>
             </member>
             <member>
-                <link linkend="mprintf">mprintf</link>
+                <link linkend="mgetl">mgetl</link>
             </member>
             <member>
                 <link linkend="mput">mput</link>
             </member>
             <member>
-                <link linkend="mseek">mseek</link>
+                <link linkend="mfprintf">mfprintf</link>
             </member>
             <member>
-                <link linkend="mtell">mtell</link>
+                <link linkend="save">save</link>
             </member>
             <member>
-                <link linkend="mdelete">mdelete</link>
+                <link linkend="write">write</link>
+            </member>
+            <member>
+                <link linkend="csvWrite">csvWrite</link>
             </member>
         </simplelist>
     </refsection>
 </refentry>
-