[doc] gettext printf_conversion mprintf msprintf mfprintf pages updated & fixed 28/21728/3
Samuel GOUGEON [Mon, 12 Apr 2021 13:01:32 +0000 (15:01 +0200)]
  * update for numbered placeholders "%n$"
  * update for boolean input
  * printf_conversion fixed for many issues (see changes), and a lot improved.
    I think that when processing the bug http://bugzilla.scilab.org/5511 10 years ago,
    the uploaded XML were not the right ones: there were so many issues left...
    (or i was more lazy :-/ )

    Bundled PDF: http://bugzilla.scilab.org/attachment.cgi?id=5260

Change-Id: I755f6fa53140e3a357a55188d16ff36288c1fc8f

13 files changed:
scilab/CHANGES.md
scilab/modules/fileio/help/en_US/mfprintf.xml
scilab/modules/fileio/help/ja_JP/mfprintf.xml [deleted file]
scilab/modules/fileio/help/ru_RU/mfprintf.xml
scilab/modules/localization/help/en_US/gettext.xml
scilab/modules/localization/help/ru_RU/gettext.xml
scilab/modules/output_stream/help/en_US/mprintf.xml
scilab/modules/output_stream/help/en_US/msprintf.xml
scilab/modules/output_stream/help/en_US/printf_conversion.xml
scilab/modules/output_stream/help/ja_JP/mprintf.xml
scilab/modules/output_stream/help/ja_JP/msprintf.xml [deleted file]
scilab/modules/output_stream/help/ja_JP/printf_conversion.xml
scilab/modules/output_stream/help/pt_BR/printf_conversion.xml

index d4fd155..29c6df9 100644 (file)
@@ -328,7 +328,7 @@ Bug Fixes
 ### Bugs fixed in 6.1.1:
 * [#3188](https://bugzilla.scilab.org/3188): `part()` was slower than in Scilab 4.1.2.
 * [#4648](https://bugzilla.scilab.org/4648): Scilab missed more secure hashing functions (md5 is now broken)
-* [#7117](https://bugzilla.scilab.org/7117): `findobj()` could not search within given object.
+* [#5511](https://bugzilla.scilab.org/5511): printf_conversion page was poorly presented and had many issues: The described types of accepted value and printed result were often switched; nothing was told about the processing of complex numbers; special escaped sequences \n \r \t \\ were not described; possible numbering of placeholders was not described; in the pt_BR version, the itemized lists were wrongly unnested and characters typing placeholders (d,u,o,x,f,e,g..) were missing.
 * [#8059](https://bugzilla.scilab.org/8059): A local `.wgetrc` config file could make troubles in `atomsDownload`.
 * [#8100](https://bugzilla.scilab.org/8100): `cumsum()` on sparse documented.
 * [#8378](https://bugzilla.scilab.org/8378): Datatip `ContextMenu => Delete last datatip` was useless.
index 3c10edc..6187b63 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) 2021 - 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: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="mfprintf" 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: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="mfprintf" xml:lang="en">
     <refnamediv>
         <refname>mfprintf</refname>
         <refpurpose>converts, formats, and writes data to a file</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
-        <synopsis>mfprintf(fd, format, a1, ..., an);</synopsis>
+        <synopsis>mfprintf(fd, format, a1, ..., an)</synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Arguments</title>
                 <term>fd</term>
                 <listitem>
                     <para>
-                        a scalar, file descriptor given by <function>mopen</function>
-                        (it's a positive integer).
+                        scalar positive index identifying the file, as provided by <literal>mopen</literal>.
                     </para>
                     <para>
-                        If <varname>fd</varname> equals 0 redirection in stderr.
+                        If <varname>fd</varname> equals 0: redirection to stderr.
                     </para>
                     <para>
-                        If <varname>fd</varname> equals 6 redirection in stdout.
+                        If <varname>fd</varname> equals 6: redirection to stdout (console).
                     </para>
                     <para>
                         OBSOLETE: The value <literal>-1</literal> refers to the
                 <term>format</term>
                 <listitem>
                     <para>
-                        a Scilab string describing the format to use to write the
-                        remaining operands. The
-                        <varname>
-                            format
-                        </varname>
-                        operand follows,
-                        as close as possible, the C
-                        <function>
-                            printf
-                        </function>
-                        format
-                        operand syntax.
+                        a string providing the format to use to write all next arguments.
+                        The <varname>format</varname> follows -- as close as possible -- the C printf
+                        format operand syntax, as described in the
+                        <link linkend="printf_conversion">printf_conversion</link> page.
+                        UTF-8 extended characters are supported.
+                        <warning>
+                            Numbered placeholders "%n$.." are not supported.
+                        </warning>
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>str</term>
-                <listitem>
-                    <para>a character string: a string to be scanned.</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
                 <term>a1, ..., an</term>
                 <listitem>
                     <para>
-                        the data to be converted and printed according to
-                        the format parameter.
+                        Data to be converted and written according to the <varname>format</varname>
+                        argument. Supported types: all numbers, booleans, strings. Only the real part
+                        of complex numbers is considered (current Scilab limitation).
                     </para>
                 </listitem>
             </varlistentry>
     <refsection>
         <title>Description</title>
         <para>
-            The <function>mfprintf</function> function is a interface for C-coded
-            version of <function>fprintf</function> function.
+            <literal>mfprintf(fd, format, a1, a2, ..)</literal> replaces placeholders provided
+            in the <varname>format</varname> string with values of <varname>a1</varname>,
+            <varname>a2</varname>, .. converted according to each respective placeholder directive,
+            and writes the result to the file specified by its index <varname>fd</varname>.
         </para>
         <para>
-            The <function>mfprintf</function> function writes formatted operands
-            to the file specified by the file descriptor <varname>fd</varname>. The
-            argument operands are formatted under control of the
-            <varname>format</varname> operand.
+            If <varname>a1</varname>, <varname>a2</varname>, .. are arrays with multiple rows,
+            they feed the format row by row: the format is used iteratively for every row of the
+            (horizontally "concatenated") arrays, until the bottom
+            of the least tall array is reached. Remaining rows of taller arrays (if any) are ignored.
+            See examples.
         </para>
         <para>
-            This function may be used to output column vectors of numbers
-            and string vectors without an explicit loop on the elements. In that
-            case this function iterates on the rows. The shortest vector gives the
-            number of time the format has to be iterated.
+            If the total number of columns of <varname>a1</varname>, <varname>a2</varname>, ..
+            is bigger than the number of placeholders in the <varname>format</varname>,
+            then extra columns are ignored. If it is smaller, an error is yielded.
         </para>
         <para>
-            An homogeneous sequence of identical type parameters can be replaced
-            by a matrix.
+            The <literal>mfprintf</literal> function is a interface for C-coded
+            <literal>fprintf</literal> function.
         </para>
     </refsection>
     <refsection>
         <title>Examples</title>
         <programlisting role="example"><![CDATA[
-
 fd = mopen(TMPDIR+'/text.txt','wt');
 mfprintf(fd,'hello %s %d.\n','world',1);
 mfprintf(fd,'hello %s %d.\n','scilab',2);
@@ -116,61 +110,99 @@ mfprintf(fd,'This line is built with a row vector (26:28) %d.\n',[26:28]);
 A = rand(3,6);
 mfprintf(fd,'This line is built with a matrix %.3f.\n',A);
 mclose(fd);
-if (isdef('editor') | (funptr('editor')<>0)) then
-  editor(TMPDIR+'/text.txt')
-end
+editor(TMPDIR+'/text.txt')
+
 mfprintf(0,'stderr output.\n');
 mfprintf(6,'stdout output.\n');
- ]]></programlisting>
+     ]]></programlisting>
+        <para/>
+        <programlisting role="example"><![CDATA[
+I = (1:4)';
+A = [26.93 ; 63.25 ; 40.51 ; 91.84];
+B = [ 3.62 ; 15.04 ; 25.3  ; 48.19];
+C = [ 4.37   28.06
+     48.18   %inf
+     41.48   %nan
+     26.39   77.83];
+Status = ["NOK" "NOK" "NOK" "OK"]';
+Format = "Iteration %d: Results: A= %f   B= %2d%%  Status= %3s   C(1)= %g  C(2)= %e\n";
+File = TMPDIR + "/mfprintf.txt";
+fd = mopen(File, 'wt');
+mfprintf(fd, Format, I, A, B, Status, C);
+mclose
+editor(File)
+     ]]></programlisting>
+        <screen><![CDATA[
+Iteration 1: Results: A= 26.930000   B=  3%  Status= NOK   C(1)= 4.37  C(2)= 2.806000e+01
+Iteration 2: Results: A= 63.250000   B= 15%  Status= NOK   C(1)= 48.18  C(2)= Inf
+Iteration 3: Results: A= 40.510000   B= 25%  Status= NOK   C(1)= 41.48  C(2)= Nan
+Iteration 4: Results: A= 91.840000   B= 48%  Status=  OK   C(1)= 26.39  C(2)= 7.783000e+01
+]]></screen>
+        <para/>
+        <para>
+            Supernumerary columns or rows are ignored:
+        </para>
+        <programlisting role="example"><![CDATA[
+A = [%T  %F  %T  %T  %F]';
+B = [ 4.37   28.06
+     48.18   %inf
+     41.48   %nan ];
+File = TMPDIR + "/mfprintf.txt";
+fd = mopen(File, 'wt');
+mfprintf(fd, "OK? %s  Value: %4.1f\n", A, B)
+mclose
+editor(File)
+     ]]></programlisting>
+        <screen><![CDATA[
+OK? T  Value:  4.4
+OK? F  Value: 48.2
+OK? T  Value: 41.5
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
         <simplelist type="inline">
             <member>
-                <link linkend="mclose">mclose</link>
+                <link linkend="printf_conversion">printf_conversion</link>
             </member>
             <member>
-                <link linkend="meof">meof</link>
+                <link linkend="csvWrite">csvWrite</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="write">write</link>
             </member>
             <member>
-                <link linkend="mprintf">mprintf</link>
-            </member>
-            <member>
-                <link linkend="mput">mput</link>
+                <link linkend="mputl">mputl</link>
             </member>
             <member>
                 <link linkend="mputstr">mputstr</link>
             </member>
             <member>
-                <link linkend="mseek">mseek</link>
+                <link linkend="mopen">mopen</link>
             </member>
             <member>
-                <link linkend="mtell">mtell</link>
+                <link linkend="mclose">mclose</link>
             </member>
             <member>
-                <link linkend="mdelete">mdelete</link>
+                <link linkend="mprintf">msprintf</link>
             </member>
             <member>
-                <link linkend="printf_conversion">printf_conversion</link>
+                <link linkend="mfscanf">mfscanf</link>
             </member>
         </simplelist>
     </refsection>
+    <refsection role="history">
+        <title>History</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.1.1</revnumber>
+                <revdescription>
+                    Input data can be boolean.
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>
diff --git a/scilab/modules/fileio/help/ja_JP/mfprintf.xml b/scilab/modules/fileio/help/ja_JP/mfprintf.xml
deleted file mode 100644 (file)
index 8ac9de2..0000000
+++ /dev/null
@@ -1,308 +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: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="mfprintf" xml:lang="ja">
-
-    <refnamediv>
-
-        <refname>mfprintf</refname>
-
-        <refpurpose>変換,整形し,ファイルにデータを書き込む</refpurpose>
-
-    </refnamediv>
-
-    <refsynopsisdiv>
-
-        <title>呼び出し手順</title>
-
-        <synopsis>mfprintf(fd, format, a1, ..., an);</synopsis>
-
-    </refsynopsisdiv>
-
-    <refsection>
-
-        <title>引数</title>
-
-        <variablelist>
-
-            <varlistentry>
-
-                <term>fd</term>
-
-                <listitem>
-
-                    <para>
-
-                        スカラー, <function>mopen</function>で指定したファイル記述子
-
-                        (正の整数).
-
-                    </para>
-
-                    <para>
-
-                        <varname>fd</varname> が 0 の場合, stderr へのリダイレクション.
-
-                    </para>
-
-                    <para>
-
-                        <varname>fd</varname>が 6 の場合, stdout へのリダイレクション.
-
-                    </para>
-
-                    <para>
-
-                        古い仕様 :値 <literal>-1</literal> はデフォルトのファイル
-
-                        ( すなわち直近にオープンされたファイル)を指します.
-
-                    </para>
-
-                </listitem>
-
-            </varlistentry>
-
-            <varlistentry>
-
-                <term>format</term>
-
-                <listitem>
-
-                    <para>
-
-                        残りのオペランドを書き込む際に使用されるフォーマットを指定する
-
-                        Scilab 文字列.
-
-                        <varname>format</varname>オペランドはCの<function>printf</function>
-
-                        のフォーマットオペランドの構文に可能な限り似せられています.
-
-                    </para>
-
-                </listitem>
-
-            </varlistentry>
-
-            <varlistentry>
-
-                <term>str</term>
-
-                <listitem>
-
-                    <para>文字列: スキャンされる文字列.</para>
-
-                </listitem>
-
-            </varlistentry>
-
-            <varlistentry>
-
-                <term>a1, ..., an</term>
-
-                <listitem>
-
-                    <para>
-
-                        formatパラメータに基づき変換,出力されるデータ.
-
-                    </para>
-
-                </listitem>
-
-            </varlistentry>
-
-        </variablelist>
-
-    </refsection>
-
-    <refsection>
-
-        <title>説明</title>
-
-        <para>
-
-            <function>mfprintf</function> 関数は, C言語の<function>fprintf</function>関数への
-
-            インターフェイスです.
-
-        </para>
-
-        <para>
-
-            <function>mfprintf</function>関数は,整形されたオペランドを
-
-            ファイル記述子<varname>fd</varname>で指定したファイルに書き込みます.
-
-            引数のオペランドは,<varname>format</varname>オペランドの制御のもとで整形されます.
-
-        </para>
-
-        <para>
-
-            この関数は数値の列ベクトルおよび文字列ベクトルを要素に関する
-
-            明示的なループ処理を行うことなく出力する際に使用することができます.
-
-            この場合,この関数は行に関する反復処理を行ないます.
-
-            最も短いベクトルはフォーマットの反復回数を指定します.
-
-        </para>
-
-        <para>
-
-            同じ型パラメータの一様なシーケンスは
-
-            行列で置換することができます.
-
-        </para>
-
-    </refsection>
-
-    <refsection>
-
-        <title>例</title>
-
-        <programlisting role="example"><![CDATA[
-fd = mopen(TMPDIR+'/text.txt','wt');
-mfprintf(fd,'hello %s %d.\n','world',1);
-mfprintf(fd,'hello %s %d.\n','scilab',2);
-mfprintf(fd,'This line is built with a column vector (26:28) %d.\n',[26:28].');
-mfprintf(fd,'This line is built with a row vector (26:28) %d.\n',[26:28]);
-A = rand(3,6);
-mfprintf(fd,'This line is built with a matrix %.3f.\n',A);
-mclose(fd);
-if (isdef('editor') | (funptr('editor')<>0)) then
-  editor(TMPDIR+'/text.txt')
-end
-mfprintf(0,'stderr output.\n');
-mfprintf(6,'stdout output.\n');
- ]]></programlisting>
-
-    </refsection>
-
-    <refsection>
-
-        <title>参照</title>
-
-        <simplelist type="inline">
-
-            <member>
-
-                <link linkend="mclose">mclose</link>
-
-            </member>
-
-            <member>
-
-                <link linkend="meof">meof</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>
-
-            <member>
-
-                <link linkend="printf_conversion">printf_conversion</link>
-
-            </member>
-
-        </simplelist>
-
-    </refsection>
-
-</refentry>
-
index 6d9ed77..a6a844d 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) 2021 - 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: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="mfprintf" xml:lang="ru">
+<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="mfprintf" xml:lang="ru">
     <refnamediv>
         <refname>mfprintf</refname>
         <refpurpose>преобразует, форматирует и записывает данные в файл</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Синтаксис</title>
-        <synopsis>mfprintf(fd, format, a1, ..., an);</synopsis>
+        <synopsis>mfprintf(fd, format, a1, ..., an)</synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Аргументы</title>
@@ -31,7 +34,7 @@
                 <listitem>
                     <para>
                         скаляр, файловый дескриптор, предоставленный с помощью
-                        <function>mopen</function> (это положительное число).
+                        <literal>mopen</literal> (это положительное число).
                     </para>
                     <para>
                         Если <varname>fd</varname> равен 0, то перенаправление в
                 <term>format</term>
                 <listitem>
                     <para>
-                        Scilab-строка, описывающая формат, который нужно использовать для
-                        записи оставшихся операндов. Операнд <varname>format</varname>
-                        следует как можно ближе к синтаксису операндов формата
-                        <function>printf</function> в языке C.
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>str</term>
-                <listitem>
-                    <para>
-                        символьная строка: строка, которую нужно отсканировать.
+                        a string providing the format to use to write all next arguments.
+                        The <varname>format</varname> follows -- as close as possible -- the C printf
+                        format operand syntax, as described in the
+                        <link linkend="printf_conversion">printf_conversion</link> page.
+                        UTF-8 extended characters are supported.
+                        <warning>
+                            Numbered placeholders "%n$.." are not supported.
+                        </warning>
                     </para>
                 </listitem>
             </varlistentry>
@@ -70,7 +69,9 @@
                 <term>a1, ..., an</term>
                 <listitem>
                     <para>
-                        данные, которые преобразуются и распечатываются в соответствии с параметром формата.
+                        Data to be converted and written according to the <varname>format</varname>
+                        argument. Supported types: all numbers, booleans, strings. Only the real part
+                        of complex numbers is considered (current Scilab limitation).
                     </para>
                 </listitem>
             </varlistentry>
     <refsection>
         <title>Описание</title>
         <para>
-            Функция <function>mfprintf</function> является интерфейсом для версии функции <function>fprintf</function> на языке C.
+            <literal>mfprintf(fd, format, a1, a2, ..)</literal> replaces placeholders provided
+            in the <varname>format</varname> string with values of <varname>a1</varname>,
+            <varname>a2</varname>, .. converted according to each respective placeholder directive,
+            and writes the result to the file specified by its index <varname>fd</varname>.
         </para>
         <para>
-            Функция <function>mfprintf</function> записывает форматированные
-            операнды в файл, указанный файловым дескриптором <varname>fd</varname>.
-            Операнды аргумента форматируются по управлением операнда
-            <varname>format</varname>.
+            If <varname>a1</varname>, <varname>a2</varname>, .. are arrays with multiple rows,
+            they feed the format row by row: the format is used iteratively for every row of the
+            (horizontally "concatenated") arrays, until the bottom
+            of the least tall array is reached. Remaining rows of taller arrays (if any) are ignored.
+            See examples.
         </para>
         <para>
-            Эта функция может быть использована для вывода векторов-столбцов чисел и
-            строковых векторов без явных циклов по элементам. В этом случае функция
-            проводит итерации по строкам. Наиболее короткий вектор даёт количество раз, сколько формат будет повторён.
+            If the total number of columns of <varname>a1</varname>, <varname>a2</varname>, ..
+            is bigger than the number of placeholders in the <varname>format</varname>,
+            then extra columns are ignored. If it is smaller, an error is yielded.
         </para>
         <para>
-            Однородная последовательность параметров одинакового типа может быть
-            заменена матрицей.
+            Функция <literal>mfprintf</literal> является интерфейсом для версии функции <literal>fprintf</literal> на языке C.
         </para>
     </refsection>
     <refsection>
         <title>Примеры</title>
         <programlisting role="example"><![CDATA[
-
 fd = mopen(TMPDIR+'/text.txt','wt');
 mfprintf(fd,'Привет, %s %d.\n','мир!',1);
 mfprintf(fd,'Привет, %s %d.\n','Scilab',2);
@@ -109,62 +112,99 @@ mfprintf(fd,'Эта строка построена с помощью векто
 A = rand(3,6);
 mfprintf(fd,'Эта строка построена с помощью матрицы %.3f.\n',A);
 mclose(fd);
-if (isdef('editor') | (funptr('editor')<>0)) then
-  editor(TMPDIR+'/text.txt')
-end
+editor(TMPDIR+'/text.txt')
+
 mfprintf(0,'stderr output.\n');
 mfprintf(6,'stdout output.\n');
- ]]></programlisting>
+     ]]></programlisting>
+        <para/>
+        <programlisting role="example"><![CDATA[
+I = (1:4)';
+A = [26.93 ; 63.25 ; 40.51 ; 91.84];
+B = [ 3.62 ; 15.04 ; 25.3  ; 48.19];
+C = [ 4.37   28.06
+     48.18   %inf
+     41.48   %nan
+     26.39   77.83];
+Status = ["NOK" "NOK" "NOK" "OK"]';
+Format = "Iteration %d: Results: A= %f   B= %2d%%  Status= %3s   C(1)= %g  C(2)= %e\n";
+File = TMPDIR + "/mfprintf.txt";
+fd = mopen(File, 'wt');
+mfprintf(fd, Format, I, A, B, Status, C);
+mclose
+editor(File)
+     ]]></programlisting>
+        <screen><![CDATA[
+Iteration 1: Results: A= 26.930000   B=  3%  Status= NOK   C(1)= 4.37  C(2)= 2.806000e+01
+Iteration 2: Results: A= 63.250000   B= 15%  Status= NOK   C(1)= 48.18  C(2)= Inf
+Iteration 3: Results: A= 40.510000   B= 25%  Status= NOK   C(1)= 41.48  C(2)= Nan
+Iteration 4: Results: A= 91.840000   B= 48%  Status=  OK   C(1)= 26.39  C(2)= 7.783000e+01
+]]></screen>
+        <para/>
+        <para>
+            Supernumerary columns or rows are ignored:
+        </para>
+        <programlisting role="example"><![CDATA[
+A = [%T  %F  %T  %T  %F]';
+B = [ 4.37   28.06
+     48.18   %inf
+     41.48   %nan ];
+File = TMPDIR + "/mfprintf.txt";
+fd = mopen(File, 'wt');
+mfprintf(fd, "OK? %s  Value: %4.1f\n", A, B)
+mclose
+editor(File)
+     ]]></programlisting>
+        <screen><![CDATA[
+OK? T  Value:  4.4
+OK? F  Value: 48.2
+OK? T  Value: 41.5
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>Смотрите также</title>
         <simplelist type="inline">
             <member>
-                <link linkend="mclose">mclose</link>
+                <link linkend="printf_conversion">printf_conversion</link>
             </member>
             <member>
-                <link linkend="meof">meof</link>
+                <link linkend="csvWrite">csvWrite</link>
             </member>
             <member>
                 <link linkend="fprintfMat">fprintfMat</link>
             </member>
             <member>
-                <link linkend="mfscanf">mfscanf</link>
+                <link linkend="write">write</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>
+                <link linkend="mputl">mputl</link>
             </member>
             <member>
                 <link linkend="mputstr">mputstr</link>
             </member>
             <member>
-                <link linkend="mseek">mseek</link>
+                <link linkend="mopen">mopen</link>
             </member>
             <member>
-                <link linkend="mtell">mtell</link>
+                <link linkend="mclose">mclose</link>
             </member>
             <member>
-                <link linkend="mdelete">mdelete</link>
+                <link linkend="mprintf">msprintf</link>
             </member>
             <member>
-                <link linkend="printf_conversion">преобразование в printf</link>
+                <link linkend="mfscanf">mfscanf</link>
             </member>
         </simplelist>
     </refsection>
+    <refsection role="history">
+        <title>История</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.1.1</revnumber>
+                <revdescription>
+                    Input data can be boolean.
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>
-
index 1c005f7..77e6a81 100644 (file)
@@ -4,7 +4,7 @@
  * Copyright (C) 2007 - INRIA - Allan CORNET
  * Copyright (C) 2007 - INRIA - Sylvestre LEDRU
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
- * Copyright (C) 2018 - Samuel GOUGEON
+ * Copyright (C) 2018 - 2021 - 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.
                 <term>"The literal reference message"</term>
                 <listitem>
                     <para>
-                        Single literal text of an english message to be indexed or/and
+                        Single case-sensitive literal text of an english message to be indexed or/and
                         translated. A column of literal texts explicitly separated with
-                        semi-colons may also be specified.
+                        semi-colons may also be specified. Messages can include some
+                        <link linkend="printf_conversion">C-like placeholders</link> starting with "%".
                     </para>
                     <warning>
                         Only standard ASCII characters can be used. Any other extended ASCII or
@@ -61,8 +62,8 @@
                 <term>msgid</term>
                 <listitem>
                     <para>
-                        single or array of messages identifiers (in english) to be translated,
-                        in a variable.
+                        single or array of case-sensitive messages identifiers (in english) to be
+                        translated, in a variable.
                     </para>
                     <warning>
                         Only standard ASCII characters can be used.
@@ -80,8 +81,8 @@
                         the same sizes.
                     </para>
                     <note>
-                        These messages are defined in the ./locales/*.po files. They can include
-                        extended ASCII or UTF-8 characters.
+                        These messages are labelled <literal>msgstr</literal> and defined in
+                        the ./locales/*.po files. They can include extended ASCII or UTF-8 characters.
                     </note>
                     <para/>
                 </listitem>
@@ -337,17 +338,12 @@ gettext(["item#1" ;
         </refsect3>
         <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
         <refsect3>
-            <title>Messages</title>
+            <title>msgid messages</title>
             <para>
                 To be correctly processed, english messages must comply with a few rules:
                 <itemizedlist>
                     <listitem>
                         <para>
-                            Messages identifiers are case-sensitive.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
                             Literal harvestable messages may be indifferently delimited with single
                             or double quotes.
                         </para>
@@ -383,26 +379,71 @@ gettext(["item#1" ;
                     </listitem>
                     <listitem>
                         <para>
-                            Some template messages may often include some "%" C-like directives
+                            msgid messages often include some "%" C-like placeholders
                             aiming to be replaced with some custom input data through
                             <literal>msprintf()</literal> at run time.
                             For instance,
                             <literal>msprintf("Hi %s, could you come at %s today?", "John", "12:30")</literal>
                             will return <literal>"Hi John, could you come at 12:30 today?"</literal>.
                         </para>
-                        <warning>
+                    </listitem>
+                </itemizedlist>
+            </para>
+        </refsect3>
+        <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+        <refsect3>
+            <title>msgstr translated messages</title>
+            <para>
+                This section will be more useful for translaters than for actual users.
+            </para>
+            <para>
+                When an english msgid message includes some C-like placeholders,
+                this always means that in the code the <varname>translated</varname> message
+                is processed with msprintf() to replace placeholders with actual values.
+                Hence, <emphasis>the order and type of placeholders indicate the order and
+                types of actual input values when calling msprintf</emphasis>.
+                </para>
+                <para>
+                This is of first importance for translaters, when writing the corresponding
+                <varname>translated</varname> message:
+                <itemizedlist>
+                    <listitem>
+                        If placeholders are not numbered: they must be in the same order and
+                        types in the <varname>translated</varname> <literal>msgstr</literal>
+                        message than in the <varname>msgid</varname> message. Example (english to french):
+                        <screen>
+msgid  "%s is %d year old.\n"
+msgstr "%s a %d ans.\n"
+// first %s (a string), second %d (a decimal number), in both strings.
+
+Then, from a Scilab session set to french, we will get
+gettext("%s is %d year old.\n") // => "%s a %d ans.\n"
+// and                                     first v      v second
+t = msprintf(gettext("%s is %d year old.\n"), "Peter", 18)
+// => "Peter a 18 ans."
+</screen>
+                    </listitem>
+                    <listitem>
                         <para>
-                            Now, let's assume that you wish to make the template message translatable:
-                            <literal>msg = _("Hi %s, could you come at %s today?")</literal>
-                            and <literal>msprintf(msg, "John", "12:30")</literal>
-                            will be used. However, the author or/and translaters must be aware that,
-                            in the translated versions, the input data must appear in the same order:
-                            "%s" for "John" before "%s" for "12:30", to comply with the order
-                            imposed by the <literal>msprintf()</literal> input list of values.
-                            This is not always possible, noticeably for languages far from
-                            latin like right-to-left languages.
+                            Otherwise,
+                            <emphasis>All</emphasis> placeholders must be numbered in the
+                            <varname>translated</varname> message. Each numbered placeholder can
+                                                       be used only once in the format (Scilab limitation).
+                            Example (english to japanese):
+                            <screen>
+msgid "%s: Wrong number of input argument: %d to %d expected.\n"
+msgstr "%1$s: 入力引数で不正な数: %3$d への %2$d を想定します。\n"
+
+Then,
+msprintf(gettext("%s: Wrong number of input argument: %d to %d expected.\n"), "myFun", 2, 5)
+
+will return in a Scilab session set to english
+"myFun: Wrong number of input argument: 2 to 5 expected."
+
+while, in a Scilab session set to japanese
+"myFun: 入力引数で不正な数: 5 への 2 を想定します。"
+</screen>
                         </para>
-                        </warning>
                     </listitem>
                 </itemizedlist>
             </para>
@@ -491,6 +532,43 @@ msg = "%s: No more memory.\n";
 !%s : Plus de mémoire disponible.\n    !
 !%s : Overwrite Scilab translation.\n  !
 ]]></screen>
+    <para/>
+    <para>
+        Messages with numbered C-like placeholders:
+    </para>
+        <programlisting role="example"><![CDATA[
+in = getlanguage();
+msg = "%s: Unknown value %s for %s option"; // has already some translations
+setlanguage("en");
+t = gettext(msg)
+msprintf(t, "setdiff", "''f''", "''direction''")
+
+setlanguage("ja");
+t = gettext(msg)
+msprintf(t, "setdiff", "''f''", "''direction''")
+
+setlanguage(in);
+ ]]></programlisting>
+    <screen><![CDATA[
+--> setlanguage("en");
+--> t = gettext(msg)
+ t  =
+  "%s: Unknown value %s for %s option"
+
+--> msprintf(t, "setdiff", "''f''", "''direction''")
+ ans  =
+  "setdiff: Unknown value 'f' for 'direction' option"
+
+
+--> setlanguage("ja");
+--> t = gettext(msg)
+ t  =
+  "%1$s: %3$s オプション の未知の値 %2$s"
+
+--> msprintf(t, "setdiff", "''f''", "''direction''")
+ ans  =
+  "setdiff: 'direction' オプション の未知の値 'f'"
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
@@ -525,6 +603,12 @@ msg = "%s: No more memory.\n";
                 <revnumber>5.5.0</revnumber>
                 <revdescription>Domain management added.</revdescription>
             </revision>
+            <revision>
+                <revnumber>6.1.0</revnumber>
+                <revdescription>
+                    C-like placeholders in messages can now be numbered.
+                </revdescription>
+            </revision>
         </revhistory>
     </refsection>
 </refentry>
index 2b6cc8c..d226d72 100644 (file)
@@ -4,7 +4,7 @@
  * Copyright (C) 2007 - INRIA - Allan CORNET
  * Copyright (C) 2007 - INRIA - Sylvestre LEDRU
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
- * Copyright (C) 2018 - Samuel GOUGEON
+ * Copyright (C) 2018 - 2021 - 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.
                 <term>"The literal reference message"</term>
                 <listitem>
                     <para>
-                        Единый символьный текст сообщения на английском языке, которое
+                        Единый с учетом регистра символьный текст сообщения на английском языке, которое
                         требуется индексировать или/и перевести. Может быть также
                         указан столбец символьных текстов явно разделённых точкой с запятой.
+                        Messages can include some
+                        <link linkend="printf_conversion">C-like placeholders</link> starting with "%".
                     </para>
                     <warning>
                         Могут использоваться только стандартные символы ASCII.
@@ -62,8 +64,8 @@
                 <term>msgid</term>
                 <listitem>
                     <para>
-                        один или массив идентификаторов сообщений (на английском) для
-                        перевода, в переменной.
+                        один или массив идентификаторов сообщений с учетом регистра (на английском)
+                        для перевода, в переменной.
                     </para>
                     <warning>
                         Могут использоваться только стандартные символы ASCII.
@@ -339,7 +341,7 @@ gettext(["item#1" ;
         </refsect3>
         <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
         <refsect3>
-            <title>Сообщения</title>
+            <title>msgid сообщения</title>
             <para>
                 Для корректной обработки сообщения на английском должны соответствовать
                 нескольким правилам:
@@ -394,20 +396,63 @@ gettext(["item#1" ;
                             <literal>msprintf("Hi %s, could you come at %s today?", "John", "12:30")</literal>
                             вернёт <literal>"Hi John, could you come at 12:30 today?"</literal>.
                         </para>
-                        <warning>
+                    </listitem>
+                </itemizedlist>
+            </para>
+        </refsect3>
+        <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+        <refsect3>
+            <title>msgstr translated messages</title>
+            <para>
+                This section will be more useful for translaters than for actual users.
+            </para>
+            <para>
+                When an english msgid message includes some C-like placeholders,
+                this always means that in the code the <varname>translated</varname> message
+                is processed with msprintf() to replace placeholders with actual values.
+                Hence, <emphasis>the order and type of placeholders indicate the order and
+                types of actual input values when calling msprintf</emphasis>.
+                </para>
+                <para>
+                This is of first importance for translaters, when writing the corresponding
+                <varname>translated</varname> message:
+                <itemizedlist>
+                    <listitem>
+                        If placeholders are not numbered: they must be in the same order and
+                        types in the <varname>translated</varname> <literal>msgstr</literal>
+                        message than in the <varname>msgid</varname> message. Example (english to french):
+                        <screen>
+msgid  "%s is %d year old.\n"
+msgstr "%s a %d ans.\n"
+// first %s (a string), second %d (a decimal number), in both strings.
+
+Then, from a Scilab session set to french, we will get
+gettext("%s is %d year old.\n") // => "%s a %d ans.\n"
+// and                                     first v      v second
+t = msprintf(gettext("%s is %d year old.\n"), "Peter", 18)
+// => "Peter a 18 ans."
+</screen>
+                    </listitem>
+                    <listitem>
                         <para>
-                            Теперь, предположим, что вы хотите сделать шаблонное сообщение для
-                            перевода:
-                            <literal>msg = _("Hi %s, could you come at %s today?")</literal>
-                            и будет использоваться <literal>msprintf(msg, "John", "12:30")</literal>.
-                            Однако, автор и/или переводчики должны знать об этом, в переведённых
-                            версиях, входные данные должны появляться в том же порядке:
-                            "%s" для "John" перед "%s" для "12:30", чтобы составить в
-                            порядке, указанном списком входных значений <literal>msprintf()</literal>.
-                            Это не всегда возможно, особенно для языков, отличных латыни,
-                            например, для языков, пишущих справа налево.
+                            Otherwise, <emphasis>All</emphasis> placeholders must be numbered in the
+                            <varname>translated</varname> message. Each numbered placeholder can
+                                                       be used only once in the format (Scilab limitation).
+                            Example (english to japanese):
+                            <screen>
+msgid "%s: Wrong number of input argument: %d to %d expected.\n"
+msgstr "%1$s: 入力引数で不正な数: %3$d への %2$d を想定します。\n"
+
+Then,
+msprintf(gettext("%s: Wrong number of input argument: %d to %d expected.\n"), "myFun", 2, 5)
+
+will return in a Scilab session set to english
+"myFun: Wrong number of input argument: 2 to 5 expected."
+
+while, in a Scilab session set to japanese
+"myFun: 入力引数で不正な数: 5 への 2 を想定します。"
+</screen>
                         </para>
-                        </warning>
                     </listitem>
                 </itemizedlist>
             </para>
@@ -497,6 +542,43 @@ msg = "%s: No more memory.\n";
 !%s : Plus de mémoire disponible.\n    !
 !%s : Overwrite Scilab translation.\n  !
 ]]></screen>
+    <para/>
+    <para>
+        Messages with numbered C-like placeholders:
+    </para>
+        <programlisting role="example"><![CDATA[
+in = getlanguage();
+msg = "%s: Unknown value %s for %s option"; // has already some translations
+setlanguage("en");
+t = gettext(msg)
+msprintf(t, "setdiff", "''f''", "''direction''")
+
+setlanguage("ja");
+t = gettext(msg)
+msprintf(t, "setdiff", "''f''", "''direction''")
+
+setlanguage(in);
+ ]]></programlisting>
+    <screen><![CDATA[
+--> setlanguage("en");
+--> t = gettext(msg)
+ t  =
+  "%s: Unknown value %s for %s option"
+
+--> msprintf(t, "setdiff", "''f''", "''direction''")
+ ans  =
+  "setdiff: Unknown value 'f' for 'direction' option"
+
+
+--> setlanguage("ja");
+--> t = gettext(msg)
+ t  =
+  "%1$s: %3$s オプション の未知の値 %2$s"
+
+--> msprintf(t, "setdiff", "''f''", "''direction''")
+ ans  =
+  "setdiff: 'direction' オプション の未知の値 'f'"
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>Смотрите также</title>
@@ -531,6 +613,12 @@ msg = "%s: No more memory.\n";
                 <revnumber>5.5.0</revnumber>
                 <revdescription>Добавлено управление доменом.</revdescription>
             </revision>
+            <revision>
+                <revnumber>6.1.0</revnumber>
+                <revdescription>
+                    C-like placeholders in messages can now be numbered.
+                </revdescription>
+            </revision>
         </revhistory>
     </refsection>
 </refentry>
index 716bfff..f3ee5b2 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) 2021 - 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.
             <varlistentry>
                 <term>format</term>
                 <listitem>
-                    <para>a Scilab string describing the format to use to write the
-                        remaining operands. The format operand follows, as close as
-                        possible, the C printf format operand syntax, as described
-                        in the <link linkend="printf_conversion">printf_conversion</link>
-                        page.
+                    <para>a string providing the format to use to write all next arguments.
+                        The <varname>format</varname> follows -- as close as possible -- the C printf
+                        format operand syntax, as described in the
+                        <link linkend="printf_conversion">printf_conversion</link> page.
+                        UTF-8 extended characters and numbered placeholders "%n$.." are supported.
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>a1,...,an</term>
                 <listitem>
-                    <para>Specifies the data to be converted and printed according to
-                        the format parameter.
+                    <para>
+                        Data to be converted and printed according to the <varname>format</varname>
+                        argument. Supported types: all numbers, booleans, strings. Only the real part
+                        of complex numbers is considered (current Scilab limitation).
                     </para>
                 </listitem>
             </varlistentry>
     <refsection>
         <title>Description</title>
         <para>
-            The <literal>mprintf</literal> function is a interface for C-coded version of
-            <literal>printf</literal> function.
+            <literal>mprintf(format, a1, a2, ..)</literal> replaces placeholders provided inside the
+            <varname>format</varname> string with values of <varname>a1</varname>, <varname>a2</varname>, ..
+            converted according to each respective placeholder directive, and writes the result to
+            the Scilab console.
+        </para>
+        <para>
+            If <varname>a1</varname>, <varname>a2</varname>, .. are arrays with multiple rows,
+            they feed the format row by row: the format is used iteratively for every row of the
+            (horizontally "concatenated") arrays, until the bottom
+            of the least tall array is reached. Remaining rows of taller arrays (if any) are ignored.
+            See examples.
+        </para>
+        <para>
+            If the total number of columns of <varname>a1</varname>, <varname>a2</varname>, ..
+            is bigger than the number of placeholders in the <varname>format</varname>,
+            then extra columns are ignored. If it is smaller, an error is yielded.
         </para>
         <para>
-            The <literal>mprintf</literal> function writes formatted operands to
-            the standard Scilab output (i.e the Scilab window). The argument operands
-            are formatted under control of the format operand.
+            The <literal>mprintf</literal> function is an extended interface for C-coded
+            <literal>printf</literal>.
         </para>
     </refsection>
     <refsection>
         <title>Examples</title>
         <programlisting role="example"><![CDATA[
-mprintf('At iteration %i, Result is:\nalpha=%f',33,0.535)
-mprintf('%e ', [1; 2; 3])
-mprintf('%d %d\n', [1, 2; 3, 4])
- ]]></programlisting>
+I = (1:4)';
+A = [26.93 ; 63.25 ; 40.51 ; 91.84];
+B = [ 3.62 ; 15.04 ; 25.3  ; 48.19];
+C = [ 4.37   28.06
+     48.18   %inf
+     41.48   %nan
+     26.39   77.83];
+Status = ["NOK" "NOK" "NOK" "OK"]';
+Format = "Iteration %d: Results: A= %f   B= %2d%%  Status= %3s   C(1)= %g  C(2)= %e\n";
+mprintf(Format, I, A, B, Status, C);
+     ]]></programlisting>
+        <screen><![CDATA[
+--> mprintf(Format, I, A, B, Status, C);
+Iteration 1: Results: A= 26.930000   B=  3%  Status= NOK   C(1)= 4.37  C(2)= 2.806000e+01
+Iteration 2: Results: A= 63.250000   B= 15%  Status= NOK   C(1)= 48.18  C(2)= Inf
+Iteration 3: Results: A= 40.510000   B= 25%  Status= NOK   C(1)= 41.48  C(2)= Nan
+Iteration 4: Results: A= 91.840000   B= 48%  Status=  OK   C(1)= 26.39  C(2)= 7.783000e+01
+]]></screen>
+        <para/>
+        <para>
+            Supernumerary columns or rows are ignored:
+        </para>
+        <programlisting role="example"><![CDATA[
+A = [%T  %F  %T  %T  %F]';
+B = [ 4.37   28.06
+     48.18   %inf
+     41.48   %nan ];
+mprintf("OK? %s  Value: %4.1f\n", A, B);
+     ]]></programlisting>
+        <screen><![CDATA[
+--> mprintf("OK? %s  Value: %4.1f\n", A, B);
+OK? T  Value:  4.4
+OK? F  Value: 48.2
+OK? T  Value: 41.5
+]]></screen>
+        <para/>
+        <para>
+            Numbered placeholders "%n$.." allow reordering printed data with the format:
+        </para>
+        <programlisting role="example"><![CDATA[
+names = ["Peter", "Martha" "John"]';
+ages  = [32 25 8]';
+mprintf("%2$6s is %1$d-year old.\n", ages, names);
+     ]]></programlisting>
+        <screen><![CDATA[
+--> mprintf("%2$6s is %1$d-year old.\n", ages, names);
+ Peter is 32-year old.
+Martha is 25-year old.
+  John is 8-year old.
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
         <simplelist type="inline">
             <member>
+                <link linkend="printf_conversion">printf_conversion</link>
+            </member>
+            <member>
                 <link linkend="disp">disp</link>
             </member>
             <member>
-                <link linkend="printf_conversion">printf_conversion</link>
+                <link linkend="write">write</link>
+            </member>
+            <member>
+                <link linkend="percentio">percentio</link>
+            </member>
+            <member>
+                <link linkend="percentchars">percentchars</link>
             </member>
         </simplelist>
     </refsection>
+    <refsection role="history">
+        <title>History</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.1.0</revnumber>
+                <revdescription>
+                    Numbered placeholders "%n$.." are supported in the format.
+                </revdescription>
+            </revision>
+            <revision>
+                <revnumber>6.1.1</revnumber>
+                <revdescription>
+                    Input data can be boolean.
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>
index 1633f14..6f03a58 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) 2021 - 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: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="msprintf" 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: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="msprintf" xml:lang="en">
     <refnamediv>
         <refname>msprintf</refname>
         <refpurpose>converts, formats, and writes data in a string</refpurpose>
@@ -25,7 +28,7 @@
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
-        <synopsis>str = msprintf(format,a1,...,an);</synopsis>
+        <synopsis>str = msprintf(format, a1,...,an)</synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Arguments</title>
             <varlistentry>
                 <term>format</term>
                 <listitem>
-                    <para>a Scilab string describing the format to use to write the
-                        remaining operands.
+                    <para>
+                        a string providing the format to use to write all next arguments.
+                        The <varname>format</varname> follows -- as close as possible -- the C printf
+                        format operand syntax, as described in the
+                        <link linkend="printf_conversion">printf_conversion</link> page.
+                        UTF-8 extended characters and numbered placeholders "%n$.." are supported.
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>str</term>
+                <term>a1,...,an</term>
                 <listitem>
-                    <para>a character string.</para>
+                    <para>
+                        Data to be converted and written according to the <varname>format</varname>
+                        argument. Supported types: all numbers, booleans, strings. Only the real part
+                        of complex numbers is considered (current Scilab limitation).
+                    </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>a1,...,an</term>
+                <term>str</term>
                 <listitem>
-                    <para>Specifies the data to be converted and printed according to
-                        the format parameter.
-                    </para>
+                    <para>a string, or a column of strings.</para>
                 </listitem>
             </varlistentry>
         </variablelist>
     <refsection>
         <title>Description</title>
         <para>
-            The <literal>msprintf</literal> writes formatted operands in its
-            returned value (a Scilab string). The argument operands are formatted
-            under control of the format operand.
+            <literal>str=msprintf(format, a1, a2, ..)</literal> replaces placeholders provided
+            inside the <varname>format</varname> string with values of <varname>a1</varname>,
+            <varname>a2</varname>, .. converted according to each respective placeholder directive,
+            and set the result to the <varname>str</varname> string.
+        </para>
+        <para>
+            If <varname>a1</varname>, <varname>a2</varname>, .. are arrays with multiple rows,
+            they feed the format row by row: the format is used iteratively for every row of the
+            (horizontally "concatenated") arrays, until the bottom
+            of the least tall array is reached. Remaining rows of taller arrays (if any) are ignored.
+            See examples.
+        </para>
+        <para>
+            If the total number of columns of <varname>a1</varname>, <varname>a2</varname>, ..
+            is bigger than the number of placeholders in the <varname>format</varname>,
+            then extra columns are ignored. If it is smaller, an error is yielded.
         </para>
         <para>
             <note>
-                Note that, in this case, the escape sequences (<literal>"\n"</literal>) (in format)
-                split string to a matrix of string (see example).
+                If either the <varname>format</varname> includes some Next_line "\n" sequence,
+                or if all arrays <varname>a1</varname>, <varname>a2</varname>.. have at least 2 rows,
+                the result <varname>str</varname> is a column of strings. See examples.
             </note>
         </para>
     </refsection>
@@ -76,17 +99,92 @@ msprintf('%5.3f\n%5.3f',123,0.732)
 msprintf('--%s-\n-%d--',"hello",3)
 msprintf('%e ', [1;2;3])
 msprintf('%d %d\n', [1, 2; 3, 4])
- ]]></programlisting>
+     ]]></programlisting>
+        <para/>
+        <programlisting role="example"><![CDATA[
+I = (1:4)';
+A = [26.93 ; 63.25 ; 40.51 ; 91.84];
+B = [ 3.62 ; 15.04 ; 25.3  ; 48.19];
+C = [ 4.37   28.06
+     48.18   %inf
+     41.48   %nan
+     26.39   77.83];
+Status = ["NOK" "NOK" "NOK" "OK"]';
+Format = "Iteration %d: Results: A= %f   B= %2d%%  Status= %3s   C(1)= %g  C(2)= %e\n";
+msprintf(Format, I, A, B, Status, C)
+     ]]></programlisting>
+        <screen><![CDATA[
+--> msprintf(Format, I, A, B, Status, C)
+ ans  =
+  "Iteration 1: Results: A= 26.930000   B=  3%  Status= NOK   C(1)= 4.37  C(2)= 2.806000e+01"
+  "Iteration 2: Results: A= 63.250000   B= 15%  Status= NOK   C(1)= 48.18  C(2)= Inf"
+  "Iteration 3: Results: A= 40.510000   B= 25%  Status= NOK   C(1)= 41.48  C(2)= Nan"
+  "Iteration 4: Results: A= 91.840000   B= 48%  Status=  OK   C(1)= 26.39  C(2)= 7.783000e+01"
+]]></screen>
+        <para/>
+        <para>
+            Supernumerary columns or rows are ignored:
+        </para>
+        <programlisting role="example"><![CDATA[
+A = [%T  %F  %T  %T  %F]';
+B = [ 4.37   28.06
+     48.18   %inf
+     41.48   %nan ];
+msprintf("OK? %s  Value: %4.1f\n", A, B)
+     ]]></programlisting>
+        <screen><![CDATA[
+--> msprintf("OK? %s  Value: %4.1f\n", A, B)
+ ans  =
+  "OK? T  Value:  4.4"
+  "OK? F  Value: 48.2"
+  "OK? T  Value: 41.5"
+]]></screen>
+        <para/>
+        <para>
+            Numbered placeholders "%n$.." allow reordering printed data with the format:
+        </para>
+        <programlisting role="example"><![CDATA[
+names = ["Peter", "Martha" "John"]';
+ages  = [32 25 8]';
+msprintf("%2$6s is %1$d-year old.\n", ages, names)
+     ]]></programlisting>
+        <screen><![CDATA[
+--> msprintf("%2$6s is %1$d-year old.\n", ages, names)
+ ans  =
+  " Peter is 32-year old."
+  "Martha is 25-year old."
+  "  John is 8-year old."
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
         <simplelist type="inline">
             <member>
+                <link linkend="printf_conversion">printf_conversion</link>
+            </member>
+            <member>
                 <link linkend="mprintf">mprintf</link>
             </member>
             <member>
-                <link linkend="printf_conversion">printf_conversion</link>
+                <link linkend="percentchars">percentchars</link>
             </member>
         </simplelist>
     </refsection>
+    <refsection role="history">
+        <title>History</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.1.0</revnumber>
+                <revdescription>
+                    Numbered placeholders "%n$.." are supported in the format.
+                </revdescription>
+            </revision>
+            <revision>
+                <revnumber>6.1.1</revnumber>
+                <revdescription>
+                    Input data can be boolean.
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>
index f693e7f..b87ad2c 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) 2021 - 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="printf_conversion" 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="printf_conversion" xml:lang="en">
     <refnamediv>
         <refname>printf_conversion</refname>
-        <refpurpose>mprintf, msprintf, mfprintf conversion
-            specifications
+        <refpurpose>mprintf, msprintf, mfprintf C-format specifications
         </refpurpose>
     </refnamediv>
     <refsection>
@@ -25,7 +27,7 @@
         <para>
             Each conversion specification in the <literal>mprintf</literal> ,
             <literal>msprintf</literal> , <literal>mfprintf</literal>
-            <literal>format</literal> parameter has the following syntax:
+            <literal>format</literal> string has the following syntax:
         </para>
         <itemizedlist>
             <listitem>
             </listitem>
             <listitem>
                 <para>
+                    An optional integer n ≥ 1 followed by "$". n is the index of the input data
+                    to substitute to the placeholder, in the msprintf, mprintf .. list of input data.
+                    In a format string, placeholders are either all numbered or all non-numbered.
+                    A given numbered placeholder can be used only once in its C-format string
+                    (Scilab limitation).
+                </para>
+            </listitem>
+            <listitem>
+                <para>
                     Zero or more <literal>options</literal>, which modify the
                     meaning of the conversion specification. The following list contains
                     the <literal>option</literal> characters and their meanings:
                 </para>
-                <itemizedlist>
-                    <listitem>
-                        <para>- : Left align, within the field, the result of the
-                            conversion.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>+ : Begin the result of a signed conversion with a sign (+
-                            or -).
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>'space' : Prefix a space character to the result if the
+                <table>
+                    <tr>
+                        <th>- :</th>
+                        <td>
+                            Left align, within the field, the result of the conversion.
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>+ :</th>
+                        <td>
+                            Begin the result of a signed conversion with a sign (+ or -).
+                        </td>
+                    </tr>
+                    <tr>
+                        <td style="white-space:nowrap"><emphasis role="bold">' ' :</emphasis></td>
+                        <td>(space) Prefix a space character to the result if the
                             first character of a signed conversion is not a sign. If both the
-                            (space) and + options appear, the (space) option is ignored
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para># : Convert the value to an alternate form. For
+                            (space) and + options appear, the (space) option is ignored.
+                        </td>
+                    </tr>
+                    <tr>
+                        <th># :</th>
+                        <td>
+                            Convert the value to an alternate form. For
                             <literal>c</literal>, <literal>d</literal>, <literal>i</literal>,
                             <literal>s</literal>, and <literal>u</literal> conversions, the
                             <literal>#</literal> option has no effect. For
                             no digits follow it. For <literal>g</literal> and
                             <literal>G</literal> conversions, trailing zeros are not removed
                             from the result.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>0 : Pad to the field width, using leading zeros (following
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>0 :</th>
+                        <td>
+                            Pad to the field width, using leading zeros (following
                             any indication of sign or base) for <literal>d</literal>,
                             <literal>i</literal>, <literal>o</literal>, <literal>u</literal>,
                             <literal>x</literal>, <literal>X</literal>, <literal>e</literal>,
                             <literal>o</literal> <literal>u</literal>, <literal>x</literal>,
                             and <literal>X</literal> conversions, if a precision is specified,
                             the <literal>0</literal> flag is also ignored.
-                        </para>
-                    </listitem>
-                </itemizedlist>
+                        </td>
+                    </tr>
+                </table>
             </listitem>
             <listitem>
-                <para>An optional decimal digit string that specifies the minimum field
+                <para>
+                    An optional decimal digit string that specifies the minimum field
                     width. If the converted value has fewer characters than the field width,
                     the field is padded on the left to the length specified by the field
                     width. If the left-adjustment option is specified, the field is padded on
                 </para>
                 <itemizedlist>
                     <listitem>
-                        <para>
-                            The minimum number of digits to appear for <literal>d</literal>,
-                            <literal>u</literal>, <literal>o</literal>, <literal>x</literal>, or
-                            <literal>X</literal> conversions
-                        </para>
+                        The minimum number of digits to appear for <literal>d</literal>,
+                        <literal>u</literal>, <literal>o</literal>, <literal>x</literal>, or
+                        <literal>X</literal> conversions.
                     </listitem>
                     <listitem>
-                        <para>The number of digits to appear after the decimal point for
-                            <literal>e</literal>, <literal>E</literal>, and <literal>f</literal>
-                            conversions
-                        </para>
+                        The number of digits to appear after the decimal point for
+                        <literal>e</literal>, <literal>E</literal>, and <literal>f</literal>
+                        conversions.
                     </listitem>
                     <listitem>
-                        <para>The maximum number of significant digits for
-                            <literal>g</literal> and <literal>G</literal> conversions
-                        </para>
+                        The maximum number of significant digits for
+                        <literal>g</literal> and <literal>G</literal> conversions.
                     </listitem>
                     <listitem>
-                        <para>The maximum number of characters to be printed from a string in
-                            an <literal>s</literal> conversion
-                        </para>
+                        The maximum number of characters to be printed from a string in
+                        an <literal>s</literal> conversion.
                     </listitem>
                 </itemizedlist>
             </listitem>
             <listitem>
-                <para>A character that indicates the type of conversion to be
-                    applied:
+                <para>A character that indicates the type of conversion to be applied:
                 </para>
-                <itemizedlist>
-                    <listitem>
-                        <para>% : Performs no conversion. Displays %.</para>
-                    </listitem>
-                    <listitem>
-                        <para>
-                            d,i: Accepts an integer <literal>value</literal> and
-                            converts it to signed decimal notation. The precision specifies
+                <table>
+                    <tr>
+                        <th>% :</th>
+                        <td>
+                            Performs no conversion. Prints %.
+                            <note>
+                                This may be useful for instance to print percentages, or
+                                to process some LaTeX expression including LaTeX comments
+                                starting with "%", etc.
+                            </note>
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>s :</th>
+                        <td>
+                            Accepts a string or boolean <literal>value</literal> and displays
+                            characters from the string to the end or the number of characters
+                            indicated by the precision is reached. If no precision is
+                            specified, all characters up to the end are displayed.
+                            UTF-8 extended characters are supported in input strings.
+                            Booleans are converted into 'T' or 'F'.
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>c :</th>
+                        <td>
+                            Not supported.
+                        </td>
+                    </tr>
+                    <tr>
+                        <td colspan="2">
+                            All following conversions accept any decimal numerical or boolean
+                            input <literal>value</literal>. Only the real part of any input
+                            complex number is considered. Booleans are implicitly converted
+                            into 0 and 1.
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>d,i :</th>
+                        <td>
+                            Converts the input <literal>value</literal> to a signed integer int32
+                            notation. Conversions for input |Numbers| ≥ 2^31 are not reliable.
+                            The precision specifies
                             the minimum number of digits to appear. If the value being
                             converted can be represented in fewer digits, it is expanded with
                             leading zeros. The default precision is 1. The result of
                             converting a zero value with a precision of zero is a null string.
                             Specifying a field width with a zero as a leading character causes
                             the field width value to be padded with leading zeros.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-                            u : Accepts an integer <literal>value</literal> and converts
-                            it to unsigned decimal notation. The precision specifies the
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>u :</th>
+                        <td>
+                            Converts the input <literal>value</literal> to an unsigned integer
+                            uint32 notation. Conversions for input |Numbers| ≥ 2^32 are not reliable.
+                            The precision specifies the
                             minimum number of digits to appear. If the value being converted
                             can be represented in fewer digits, it is expanded with leading
                             zeros. The default precision is 1. The result of converting a zero
                             value with a precision of zero is a null string. Specifying a
                             field width with a zero as the leading character causes the field
                             width value to be padded with leading zeros.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-                            o : Accepts an integer <literal>value</literal> and converts
-                            it to unsigned octal notation. The precision specifies the minimum
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>o :</th>
+                        <td>
+                            Converts the input <literal>value</literal> to an unsigned octal notation.
+                            Conversions for input |Numbers| ≥ 2^32 are not reliable.
+                            The precision specifies the minimum
                             number of digits to appear. If the value being converted can be
                             represented in fewer digits, it is expanded with leading zeros.
                             The default precision is 1. The result of converting a zero value
                             width with a zero as the leading character causes the field width
                             value to be padded with leading zeros. An octal value for field
                             width is not implied.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-                            x, X : Accepts an integer <literal>value</literal> and
-                            converts it to unsigned hexadecimal notation. The letters
-                            ``abcdef'' are used for the <literal>x</literal> conversion; the
-                            letters ``ABCDEF'' are used for the <literal>X</literal>
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>x, X :</th>
+                        <td>
+                            Converts the input <literal>value</literal> to an unsigned hexadecimal
+                            notation. Conversions for input |Numbers| ≥ 2^32 are not reliable.
+                            The letters ``abcdef'' are used for the <literal>x</literal> conversion;
+                            the letters ``ABCDEF'' are used for the <literal>X</literal>
                             conversion. The precision specifies the minimum number of digits
                             to appear. If the value being converted can be represented in
                             fewer digits, it is expanded with leading zeros. The default
                             precision of zero is a null string. Specifying a field width with
                             a zero as the leading character causes the field width value to be
                             padded with leading zeros.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-                            f : Accepts a float or double <literal>value</literal> and
-                            converts it to decimal notation in the format
-                            %[\-]<literal>ddd.ddd</literal>. The number of digits after the
-                            decimal point is equal to the precision specification.
-                        </para>
-                        <itemizedlist>
-                            <listitem>
-                                <para>If no precision is specified, six digits are
-                                    output.
-                                </para>
-                            </listitem>
-                            <listitem>
-                                <para>If the precision is zero, no decimal point appears and
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>f :</th>
+                        <td>
+                            Converts the input <literal>value</literal> to a decimal notation in
+                            the format %[\-]<literal>ddd.ddd</literal>.
+                            The number of digits after the decimal point is equal to the precision
+                            specification.
+                            <itemizedlist>
+                                <listitem>
+                                    If no precision is specified, six digits are output.
+                                </listitem>
+                                <listitem>
+                                    If the precision is zero, no decimal point appears and
                                     the system outputs a number rounded to the integer nearest to
                                     <literal>value</literal>.
-                                </para>
-                            </listitem>
-                            <listitem>
-                                <para>If a decimal point is output, at least one digit is
-                                    output before it.
-                                </para>
-                            </listitem>
-                        </itemizedlist>
-                    </listitem>
-                    <listitem>
-                        <para>e, E : Accepts a real and converts it to the exponential
+                                </listitem>
+                                <listitem>
+                                    If a decimal point is output, at least one digit is output before it.
+                                </listitem>
+                            </itemizedlist>
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>e, E :</th>
+                        <td>
+                            Converts the input <literal>value</literal> to the exponential
                             form %[\-]<literal>d.ddde</literal>+/\-<literal>dd</literal>.
                             There is one digit before the decimal point, and the number of
                             digits after the decimal point is equal to the precision
                             specification.
-                        </para>
-                        <itemizedlist>
-                            <listitem>
-                                <para>If no precision is specified, six digits are
-                                    output.
-                                </para>
-                            </listitem>
-                            <listitem>
-                                <para>If the precision is zero, , no decimal point
-                                    appears.
-                                </para>
-                            </listitem>
-                            <listitem>
-                                <para>
+                            <itemizedlist>
+                                <listitem>
+                                    If no precision is specified, six digits are output.
+                                </listitem>
+                                <listitem>
+                                    If the precision is zero, no decimal point appears.
+                                </listitem>
+                                <listitem>
                                     The <literal>E</literal> conversion character produces a
                                     number with E instead of e before the exponent. The exponent
                                     always contains at least two digits. If the value is zero, the
                                     exponent is zero.
-                                </para>
-                            </listitem>
-                        </itemizedlist>
-                    </listitem>
-                    <listitem>
-                        <para>g, G : Accepts a real and converts it in the style of the
+                                </listitem>
+                            </itemizedlist>
+                        </td>
+                    </tr>
+                    <tr>
+                        <td style="white-space:nowrap"><emphasis role="bold">g, G :</emphasis></td>
+                        <td>
+                            Converts the input <literal>value</literal> in the style of the
                             <literal>e</literal>, <literal>E</literal>, or
                             <literal>f</literal> conversion characters, with the precision
-                            specifying the number of significant digits. Trailing zeros are
-                            removed from the result. A decimal point appears only if it is
-                            followed by a digit. The style used depends on the value
+                            specifying the number of significant digits.
+                            Trailing zeros are removed from the result.
+                            A decimal point appears only if it is followed by a digit.
+                            The style used depends on the value
                             converted. Style <literal>e</literal> (<literal>E</literal>, if
                             <literal>G</literal> is the flag used) results only if the
                             exponent resulting from the conversion is less than -4, or if it
                             is greater or equal to the precision.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>c : Accepts and displays an integer value converted to a
-                            character.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-                            s : Accepts a string <literal>value</literal> and displays
-                            characters from the string to the end or the number of characters
-                            indicated by the precision is reached. If no precision is
-                            specified, all characters up to the end are displayed.
-                        </para>
-                    </listitem>
-                </itemizedlist>
+                        </td>
+                    </tr>
+                </table>
             </listitem>
         </itemizedlist>
         <para>A field width or precision can be indicated by an
         <para>The representation of the plus sign depends on whether the
             <literal>+</literal> or (space) formatting option is specified.
         </para>
-        <para>display of exponential form %e is platform dependent with a different number of digits in exponent.</para>
-        <informaltable border="1">
-            <tr>
-                <td>Platform</td>
-                <td>Example: msprintf("%e",1.23e4)</td>
-            </tr>
-            <tr>
-                <td>Windows</td>
-                <td>1.23000e+004</td>
-            </tr>
-            <tr>
-                <td>Linux/Mac OS</td>
-                <td>1.23000e+04</td>
-            </tr>
-        </informaltable>
+        <para>
+            The display of exponential form %e is platform dependent with a different
+            number of digits in exponent.
+            <informaltable border="1">
+                <tr>
+                    <td>Platform</td>
+                    <td>Example: msprintf("%e",1.23e4)</td>
+                </tr>
+                <tr>
+                    <td>Windows</td>
+                    <td>1.23000e+004</td>
+                </tr>
+                <tr>
+                    <td>Linux/Mac OS</td>
+                    <td>1.23000e+04</td>
+                </tr>
+            </informaltable>
+        </para>
+        <para>
+            <emphasis role="bold">Special escaped sequences</emphasis> are supported in Scilab
+            C-format strings:
+            <table>
+                <tr>
+                    <th>\n :</th>
+                    <td>Go to Next line (line feed)</td>
+                </tr>
+                <tr>
+                    <th>\r :</th>
+                    <td>Return: go to the head of current line (for overprinting)</td>
+                </tr>
+                <tr>
+                    <th>\t :</th>
+                    <td>horizontal Tab</td>
+                </tr>
+                <tr>
+                    <th>\\ :</th>
+                    <td>print a backslash \</td>
+                </tr>
+            </table>
+        </para>
     </refsection>
     <refsection>
         <title>Examples</title>
@@ -320,7 +380,45 @@ mprintf('a float (exponential form): %3.2e\n', %pi);
 mprintf('a float (exponential form): %3.2g\n', %pi);
 mprintf('a character: %c\n', 'a');
 mprintf('a character: %c\n', 'aaa');
- ]]></programlisting>
+     ]]></programlisting>
+        <para/>
+        <para>
+            With input booleans:
+        </para>
+        <programlisting role="example"><![CDATA[
+mprintf("\n%%d: %d,  %%u: %u,  %%o: %o,  %%f: %f,  %%e: %e,  %%s: %s\n" + ..
+          "%%d: %d,  %%u: %u,  %%o: %o,  %%f: %f,  %%e: %e,  %%s: %s\n", ..
+        %T, %T, %T, %T, %T, %T, %F, %F, %F, %F, %F, %F);
+     ]]></programlisting>
+        <screen><![CDATA[
+%d: 1,  %u: 1,  %o: 1,  %f: 1.000000,  %e: 1.000000e+00,  %s: T
+%d: 0,  %u: 0,  %o: 0,  %f: 0.000000,  %e: 0.000000e+00,  %s: F
+]]></screen>
+        <para/>
+        <para>
+            With numbered placeholders:
+        </para>
+        <programlisting role="example"><![CDATA[
+mprintf("%2$s is %1$d-year old.\n", 32, "Peter");
+     ]]></programlisting>
+        <screen><![CDATA[
+Peter is 32-year old.
+]]></screen>
+        <para/>
+        <para>
+            With escaped sequences and UTF-8 extended characters:
+        </para>
+        <programlisting role="example"><![CDATA[
+mprintf("The path T:\\abc does not exist.\n");
+mprintf("abcdefghijk\tαβδ\tεϵ\tζηθικλ\rABCDE\n");
+     ]]></programlisting>
+        <screen><![CDATA[
+--> mprintf("The path T:\\abc does not exist.\n");
+The path T:\abc does not exist
+
+--> mprintf("abcdefghijk\tαβδ\tεϵ\tζηθικλ\rABCDE\n");
+ABCDEfghijk αβδ εϵ  ζηθικλ
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
@@ -336,4 +434,21 @@ mprintf('a character: %c\n', 'aaa');
             </member>
         </simplelist>
     </refsection>
+    <refsection role="history">
+        <title>History</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.1.0</revnumber>
+                <revdescription>
+                    Numbered placeholders "%n$.." are supported.
+                </revdescription>
+            </revision>
+            <revision>
+                <revnumber>6.1.1</revnumber>
+                <revdescription>
+                    Input boolean data can be converted.
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>
index 6dd7113..874572d 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) 2021 - 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.
                         formatオペランドは,C言語のprintfのformatオペランドと
                         構文にできるだけ近くなるよう作成されています, as described in the
                         <link linkend="printf_conversion">printf_conversion</link> page.
+                        UTF-8 extended characters and numbered placeholders "%n$.." are supported.
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>a1,...,an</term>
                 <listitem>
-                    <para>formatパラメータに基づき変換,出力されるデータを定義します.</para>
+                    <para>
+                        formatパラメータに基づき変換,出力されるデータを定義します.
+                        Supported types: all numbers, booleans, strings. Only the real part
+                        of complex numbers is considered (current Scilab limitation).
+                    </para>
                 </listitem>
             </varlistentry>
         </variablelist>
     <refsection>
         <title>説明</title>
         <para>
-            <literal>mprintf</literal>関数はC言語の<literal>printf</literal>へ
-            のインターフェイスです.
+            <literal>mprintf(format, a1, a2, ..)</literal> replaces placeholders provided inside the
+            <varname>format</varname> string with values of <varname>a1</varname>, <varname>a2</varname>, ..
+            converted according to each respective placeholder directive, and writes the result to
+            the Scilab console.
         </para>
         <para>
-            <literal>mprintf</literal>関数は整形されたオペランドを
-            Scilab標準出力(すなわち,Scilabウインドウ)に書き込みます.
-            argumentオペランドはformatオペランドの制御の下で整形されます.
+            If <varname>a1</varname>, <varname>a2</varname>, .. are arrays with multiple rows,
+            they are processed row by row: the format is used iteratively for every row of the
+            arrays (horizontally "concatenated"), until the bottom
+            of the least tall array is reached. Remaining rows of taller arrays (if any) are ignored.
+            See examples.
+        </para>
+        <para>
+            If the total number of columns of <varname>a1</varname>, <varname>a2</varname>, ..
+            is bigger than the number of placeholders in the <varname>format</varname>,
+            then extra columns are ignored.
+        </para>
+        <para>
+            The <literal>mprintf</literal> function is an extended interface for C-coded
+            <literal>printf</literal>.
         </para>
     </refsection>
     <refsection>
         <title>例</title>
         <programlisting role="example"><![CDATA[
-mprintf('At iteration %i, Result is:\nalpha=%f',33,0.535)
- ]]></programlisting>
+I = (1:4)';
+A = [26.93 ; 63.25 ; 40.51 ; 91.84];
+B = [ 3.62 ; 15.04 ; 25.3  ; 48.19];
+C = [ 4.37   28.06
+     48.18   %inf
+     41.48   %nan
+     26.39   77.83];
+Status = ["NOK" "NOK" "NOK" "OK"]';
+Format = "Iteration %d: Results: A= %f   B= %2d%%  Status= %3s   C(1)= %g  C(2)= %e\n";
+mprintf(Format, I, A, B, Status, C);
+     ]]></programlisting>
+        <screen><![CDATA[
+--> mprintf(Format, I, A, B, Status, C);
+Iteration 1: Results: A= 26.930000   B=  3%  Status= NOK   C(1)= 4.37  C(2)= 2.806000e+01
+Iteration 2: Results: A= 63.250000   B= 15%  Status= NOK   C(1)= 48.18  C(2)= Inf
+Iteration 3: Results: A= 40.510000   B= 25%  Status= NOK   C(1)= 41.48  C(2)= Nan
+Iteration 4: Results: A= 91.840000   B= 48%  Status=  OK   C(1)= 26.39  C(2)= 7.783000e+01
+]]></screen>
+        <para/>
+        <para>
+            Supernumerary columns or rows are ignored:
+        </para>
+        <programlisting role="example"><![CDATA[
+A = [%T  %F  %T  %T  %F]';
+B = [ 4.37   28.06
+     48.18   %inf
+     41.48   %nan ];
+mprintf("OK? %s  Value: %4.1f\n", A, B);
+     ]]></programlisting>
+        <screen><![CDATA[
+--> mprintf("OK? %s  Value: %4.1f\n", A, B);
+OK? T  Value:  4.4
+OK? F  Value: 48.2
+OK? T  Value: 41.5
+]]></screen>
+        <para/>
+        <para>
+            Numbered placeholders "%n$.." allow reordering printed data with the format:
+        </para>
+        <programlisting role="example"><![CDATA[
+names = ["Peter", "Martha" "John"]';
+ages  = [32 25 8]';
+mprintf("%2$6s is %1$d-year old.\n", ages, names);
+     ]]></programlisting>
+        <screen><![CDATA[
+--> mprintf("%2$6s is %1$d-year old.\n", ages, names);
+ Peter is 32-year old.
+Martha is 25-year old.
+  John is 8-year old.
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>参照</title>
         <simplelist type="inline">
             <member>
+                <link linkend="printf_conversion">printf_conversion</link>
+            </member>
+            <member>
                 <link linkend="disp">disp</link>
             </member>
             <member>
-                <link linkend="printf_conversion">printf_conversion</link>
+                <link linkend="write">write</link>
+            </member>
+            <member>
+                <link linkend="percentio">percentio</link>
+            </member>
+            <member>
+                <link linkend="percentchars">percentchars</link>
             </member>
         </simplelist>
     </refsection>
+    <refsection role="history">
+        <title>履歴</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.1.0</revnumber>
+                <revdescription>
+                    Numbered placeholders "%n$.." are supported in the format.
+                </revdescription>
+            </revision>
+            <revision>
+                <revnumber>6.1.1</revnumber>
+                <revdescription>
+                    Input data can be boolean.
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>
diff --git a/scilab/modules/output_stream/help/ja_JP/msprintf.xml b/scilab/modules/output_stream/help/ja_JP/msprintf.xml
deleted file mode 100644 (file)
index 252b653..0000000
+++ /dev/null
@@ -1,90 +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: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="msprintf" xml:lang="ja">
-    <refnamediv>
-        <refname>msprintf</refname>
-        <refpurpose>データを変換,整形し,文字列に書き込む</refpurpose>
-    </refnamediv>
-    <refnamediv xml:id="sprintf">
-        <refname>sprintf</refname>
-        <refpurpose>データを変換,整形し,文字列に書き込む (廃止)</refpurpose>
-    </refnamediv>
-    <refsynopsisdiv>
-        <title>呼び出し手順</title>
-        <synopsis>str = msprintf(format,a1,...,an);</synopsis>
-    </refsynopsisdiv>
-    <refsection>
-        <title>パラメータ</title>
-        <variablelist>
-            <varlistentry>
-                <term>format</term>
-                <listitem>
-                    <para>
-                        残りのオペランドを書き込む際に使用される
-                        フォーマット定義するSclab文字列.
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>str</term>
-                <listitem>
-                    <para>文字列.</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>a1,...,an</term>
-                <listitem>
-                    <para>S
-                        formatパラメータに基づき変換,出力されるデータを定義します.
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>説明</title>
-        <para>
-            <literal>msprintf</literal>は,整形されたオペランドを
-            その戻り値(Scilab文字列)に書き込みます.
-            argumentオペランドはformatオペランドの制御の下で
-            整形されます.
-        </para>
-        <para>
-            この場合,エスケープシーケンス(<literal>"\n"</literal>) は
-            文字列を文字列の行列に分割することに注意してください (例を参照)
-        </para>
-    </refsection>
-    <refsection>
-        <title>例</title>
-        <programlisting role="example"><![CDATA[
-msprintf('%5.3f %5.3f',123,0.732)
-msprintf('%5.3f\n%5.3f',123,0.732)
-msprintf('--%s-\n-%d--',"hello",3)
- ]]></programlisting>
-    </refsection>
-    <refsection role="see also">
-        <title>参照</title>
-        <simplelist type="inline">
-            <member>
-                <link linkend="mprintf">mprintf</link>
-            </member>
-            <member>
-                <link linkend="printf_conversion">printf_conversion</link>
-            </member>
-        </simplelist>
-    </refsection>
-</refentry>
index f98ca0e..1d6bd31 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) 2021 - 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="printf_conversion" xml:lang="ja">
+<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="printf_conversion" xml:lang="ja">
     <refnamediv>
         <refname>printf_conversion</refname>
         <refpurpose>mprintf, msprintf, mfprintf 変換仕様</refpurpose>
             </listitem>
             <listitem>
                 <para>
+                    An optional integer n ≥ 1 followed by "$". n is the index of the input data
+                    to substitute to the placeholder, in the msprintf, mprintf .. list of input data.
+                    In a format string, placeholders are either all numbered or all non-numbered.
+                    A given numbered placeholder can be used only once in its C-format string
+                    (Scilab limitation).
+                </para>
+            </listitem>
+            <listitem>
+                <para>
                     0個以上の <literal>options</literal>で,
                     変換仕様の意味を修正します.
                     以下のリストに<literal>option</literal>文字とその意味を示します:
                 </para>
-                <itemizedlist>
-                    <listitem>
-                        <para>- : 左揃え, フィールド内では, 変換の結果.</para>
-                    </listitem>
-                    <listitem>
-                        <para>+ : (+または -)を指定する符号変換の結果を開始.</para>
-                    </listitem>
-                    <listitem>
-                        <para>'空白' :
-                            符号変換後の最初の文字が符号ではない場合に結果の
+                <table>
+                    <tr>
+                        <th>- :</th>
+                        <td>
+                            左揃え, フィールド内では, 変換の結果.
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>+ :</th>
+                        <td>
+                            (+または -)を指定する符号変換の結果を開始.
+                        </td>
+                    </tr>
+                    <tr>
+                        <td style="white-space:nowrap"><emphasis role="bold">' ' :</emphasis></td>
+                        <td>
+                            (空白) 符号変換後の最初の文字が符号ではない場合に結果の
                             前に空白文字を付加します.
                             (空白) および +オプションが共に指定された場合,
                             (空白) オプションは無視されます.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para># : 別の形式に値を変換.
+                        </td>
+                    </tr>
+                    <tr>
+                        <th># :</th>
+                        <td>
+                            別の形式に値を変換.
                             <literal>c</literal>, <literal>d</literal>, <literal>i</literal>,
                             <literal>s</literal>, および <literal>u</literal> 変換の場合,
                             <literal>#</literal>オプションの効果はありません.
                             <literal>g</literal> および
                             <literal>G</literal> 変換の場合,
                             末尾の0は結果から除かれません.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>0 :
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>0 :</th>
+                        <td>
                             <literal>d</literal>,
                             <literal>i</literal>, <literal>o</literal>, <literal>u</literal>,
                             <literal>x</literal>, <literal>X</literal>, <literal>e</literal>,
                             <literal>o</literal> <literal>u</literal>, <literal>x</literal>,
                             および <literal>X</literal> 変換の場合, 精度が指定されると,
                             <literal>0</literal> フラグも無視されます.
-                        </para>
-                    </listitem>
-                </itemizedlist>
+                        </td>
+                    </tr>
+                </table>
             </listitem>
         </itemizedlist>
         <para>
             このパラメータは 0 (ゼロ)と扱われます.
             精度指定子:
         </para>
+        <para>
         <itemizedlist>
             <listitem>
-                <para>
-                    <literal>d</literal>,
-                    <literal>u</literal>, <literal>o</literal>, <literal>x</literal>, または
-                    <literal>X</literal>変換に関する最小表示桁数
-                </para>
+                <literal>d</literal>,
+                <literal>u</literal>, <literal>o</literal>, <literal>x</literal>, または
+                <literal>X</literal>変換に関する最小表示桁数
             </listitem>
             <listitem>
-                <para>
-                    <literal>e</literal>, <literal>E</literal>, および <literal>f</literal>
-                    における小数点の後に表示する桁数
-                </para>
+                <literal>e</literal>, <literal>E</literal>, および <literal>f</literal>
+                における小数点の後に表示する桁数
             </listitem>
             <listitem>
-                <para>
-                    <literal>g</literal> および<literal>G</literal>変換における
-                    有効桁の最大値
-                </para>
+                <literal>g</literal> および<literal>G</literal>変換における
+                有効桁の最大値
             </listitem>
             <listitem>
-                <para>
-                    <literal>s</literal>変換において文字列から出力される
-                    最大文字数
-                </para>
+                <literal>s</literal>変換において文字列から出力される
+                最大文字数
             </listitem>
             <listitem>
-                <para>適用される変換の種類を示す文字:</para>
-                <itemizedlist>
-                    <listitem>
-                        <para>% : 変換しません.  %を表示.</para>
-                    </listitem>
-                    <listitem>
-                        <para>
-                            d,i: 整数 <literal>value</literal> を受け取り,
-                            符号付き10進数表記に変換します.
+                適用される変換の種類を示す文字:
+                <table>
+                    <tr>
+                        <th>% :</th>
+                        <td>
+                            変換しません.  %を表示.
+                            <note>
+                                This may be useful for instance to print percentages, or
+                                to process some LaTeX expression including LaTeX comments
+                                starting with "%", etc.
+                            </note>
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>s :</th>
+                        <td>
+                            Accepts a string or boolean <literal>value</literal>,
+                            文字列から末尾または精度に示された文字数に達するまで,
+                            文字に変換します.精度が指定されない場合,末尾までの全ての文字が
+                            表示されます.
+                            Input strings including some UTF-8 extended characters are supported.
+                            Booleans are converted into 'T' or 'F'.
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>c :</th>
+                        <td>
+                            Not supported.
+                        </td>
+                    </tr>
+                    <tr>
+                        <td colspan="2">
+                            All following conversions accept any decimal numerical or boolean
+                            input <literal>value</literal>. Only the real part of any input
+                            complex number is considered. Booleans are implicitly converted
+                            into 0 and 1.
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>d, i :</th>
+                        <td>
+                            Converts the input <literal>value</literal> to a signed integer int32
+                            notation. Conversions for input |Numbers| ≥ 2^31 are not reliable.
                             精度は表示される最小の桁数を指定します.
                             変換される値がより少ない桁数で表せる場合,
                             前にゼロを付加して拡張されます.
                             前に付加する文字をゼロとしてフィールド幅を指定すると,
                             フィールド幅までの値では前にゼロを付加するパディングが
                             行われます.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-                            u : 整数 <literal>value</literal> を受け取り,
-                            符号なし10進数表記に変換します.
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>u :</th>
+                        <td>
+                            Converts the input <literal>value</literal> to an unsigned integer
+                            uint32 notation. Conversions for input |Numbers| ≥ 2^32 are not reliable.
                             精度は表示される最小の桁数を指定します.
                             変換される値がより少ない桁数で表せる場合,
                             前にゼロを付加して拡張されます.
                             前に付加する文字をゼロとしてフィールド幅を指定すると,
                             フィールド幅までの値では前にゼロを付加するパディングが
                             行われます.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-                            o : 整数 <literal>value</literal> を受け取り,
-                            符号なし8進数表記に変換します.
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>o :</th>
+                        <td>
+                            Converts the input <literal>value</literal> to an unsigned octal notation.
+                            Conversions for input |Numbers| ≥ 2^32 are not reliable.
                             精度は表示される最小の桁数を指定します.
                             変換される値がより少ない桁数で表せる場合,
                             前にゼロを付加して拡張されます.
                             前に付加する文字をゼロとしてフィールド幅を指定すると,
                             フィールド幅までの値では前にゼロを付加するパディングが
                             行われます. フィールド幅に8進数を使用することはできません.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-                            x, X : 整数 <literal>value</literal> を受け取り,
-                            符号なし16進数表記に変換します.<literal>x</literal>変換では,
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>x, X :</th>
+                        <td>
+                            Converts the input <literal>value</literal> to an unsigned hexadecimal
+                            notation. Conversions for input |Numbers| ≥ 2^32 are not reliable.
+                            <literal>x</literal>変換では,
                             文字``abcdef''が使用されます;<literal>X</literal>変換では,
                             文字``ABCDEF''が使用されます.
                             精度はは表示される最小の桁数を指定します.
                             前に付加する文字をゼロとしてフィールド幅を指定すると,
                             フィールド幅までの値では前にゼロを付加するパディングが
                             行われます.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>
-                            f : float または double の<literal>value</literal> を受け取り,
-                            %[\-]<literal>ddd.ddd</literal>形式の10進数表記に変換します.
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>f :</th>
+                        <td>
+                            Converts the input <literal>value</literal> to a decimal notation in
+                            the format %[\-]<literal>ddd.ddd</literal>.
                             小数点以下の桁数は,精度指定子に等しくなります.
-                        </para>
-                        <itemizedlist>
-                            <listitem>
-                                <para>精度が指定されない場合, 6桁が出力されます.</para>
-                            </listitem>
-                            <listitem>
-                                <para>精度がゼロの場合, 小数点は表示されず,
+                            <itemizedlist>
+                                <listitem>
+                                    精度が指定されない場合, 6桁が出力されます.
+                                </listitem>
+                                <listitem>
+                                    精度がゼロの場合, 小数点は表示されず,
                                     システムは<literal>value</literal>に最も近い整数に丸めた数を
                                     出力します.
-                                </para>
-                            </listitem>
-                            <listitem>
-                                <para>小数点が出力される場合,最低でも1桁がその前に出力されます.</para>
-                            </listitem>
-                        </itemizedlist>
-                    </listitem>
-                    <listitem>
-                        <para>
-                            e, E : 実数を受け取り,指数形式%[\-]<literal>d.ddde</literal>+/\-<literal>dd</literal>
-                            に変換します.
+                                </listitem>
+                                <listitem>
+                                    小数点が出力される場合,最低でも1桁がその前に出力されます.
+                                </listitem>
+                            </itemizedlist>
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>e, E :</th>
+                        <td>
+                            Converts the input <literal>value</literal> to the exponential
+                            form %[\-]<literal>d.ddde</literal>+/\-<literal>dd</literal>.
                             小数点の前に1桁があり,小数点の後の桁数は精度指定子に等しくなります.
-                        </para>
-                        <itemizedlist>
-                            <listitem>
-                                <para>精度が指定されない場合, 6桁が出力されます.</para>
-                            </listitem>
-                            <listitem>
-                                <para>精度がゼロの場合, 小数点は表示されません.
-                                </para>
-                            </listitem>
-                            <listitem>
-                                <para>
+                            <itemizedlist>
+                                <listitem>
+                                    精度が指定されない場合, 6桁が出力されます.
+                                </listitem>
+                                <listitem>
+                                    精度がゼロの場合, 小数点は表示されません.
+                                </listitem>
+                                <listitem>
                                     <literal>E</literal> 変換文字の場合,
                                     指数の前の e の代わりに E を付けた数値を出力します.
                                     指数には常に2桁以上が含まれます.
                                     値が 0 の場合, 指数は 0 となります.
-                                </para>
-                            </listitem>
-                        </itemizedlist>
-                    </listitem>
-                    <listitem>
-                        <para>g, G : 実数を受け取り,有効桁数を指定する精度を付けた
+                                </listitem>
+                            </itemizedlist>
+                        </td>
+                    </tr>
+                    <tr>
+                        <td style="white-space:nowrap"><emphasis role="bold">g, G :</emphasis></td>
+                        <td>
+                            有効桁数を指定する精度を付けた
                             <literal>e</literal>, <literal>E</literal>, または
                             <literal>f</literal>変換文字の形式に変換します.
+                            Booleans are converted into 0 and 1. Only the real part of complex
+                            numbers is considered.
                             末尾のゼロは結果から削除されます.
                             小数点は数字が続く場合にのみ表示されます.
                             使用される形式は変換される値に依存します.
                             精度より大きいか等しい場合に,
                             <literal>e</literal> (使用されるフラグが<literal>G</literal>の場合は
                             <literal>E</literal>)形式が使用されます.
-                        </para>
-                    </listitem>
-                    <listitem>
-                        <para>c : 整数値を受け取り,文字に変換します.</para>
-                    </listitem>
-                    <listitem>
-                        <para>
-                            s : 文字列 <literal>value</literal> を受け取り,
-                            文字列から末尾または精度に示された文字数に達するまで,
-                            文字に変換します.精度が指定されない場合,末尾までの全ての文字が
-                            表示されます.
-                        </para>
-                    </listitem>
-                </itemizedlist>
+                        </td>
+                    </tr>
+                </table>
             </listitem>
         </itemizedlist>
-        <para>フィールド幅または精度は,
-            桁文字の代わりに<literal>*</literal> (アスタリスク)で
+        </para>
+        <para>
+            フィールド幅または精度は, 桁文字の代わりに<literal>*</literal> (アスタリスク)で
             示すことができます.
             この場合,整数 <literal>value</literal>パラメータは
             フィールド幅または精度を指定します.
         </para>
         <para>指数形式 %e の表示はプレットフォームに依存し,
             指数の桁数は異なります.
+            <informaltable border="1">
+                <tr>
+                    <td>プラットフォーム</td>
+                    <td>例: msprintf("%e",1.23e4)</td>
+                </tr>
+                <tr>
+                    <td>Windows</td>
+                    <td>1.23000e+004</td>
+                </tr>
+                <tr>
+                    <td>Linux/Mac OS</td>
+                    <td>1.23000e+04</td>
+                </tr>
+            </informaltable>
+        </para>
+        <para>
+            <emphasis role="bold">Special escaped sequenced</emphasis> are supported in C-format
+            strings:
+            <table>
+                <tr>
+                    <th>\n :</th>
+                    <td>Go to Next line (line feed)</td>
+                </tr>
+                <tr>
+                    <th>\r :</th>
+                    <td>Return: go to the head of current line (for overprinting)</td>
+                </tr>
+                <tr>
+                    <th>\t :</th>
+                    <td>horizontal Tab</td>
+                </tr>
+                <tr>
+                    <th>\\ :</th>
+                    <td>print a backslash \</td>
+                </tr>
+            </table>
         </para>
-        <informaltable border="1">
-            <tr>
-                <td>プラットフォーム</td>
-                <td>例: msprintf("%e",1.23e4)</td>
-            </tr>
-            <tr>
-                <td>Windows</td>
-                <td>1.23000e+004</td>
-            </tr>
-            <tr>
-                <td>Linux/Mac OS</td>
-                <td>1.23000e+04</td>
-            </tr>
-        </informaltable>
     </refsection>
     <refsection>
         <title>例</title>
@@ -320,7 +387,45 @@ mprintf('a float (exponential form): %3.2e\n', %pi);
 mprintf('a float (exponential form): %3.2g\n', %pi);
 mprintf('a character: %c\n', 'a');
 mprintf('a character: %c\n', 'aaa');
- ]]></programlisting>
+     ]]></programlisting>
+        <para/>
+        <para>
+            With input booleans:
+        </para>
+        <programlisting role="example"><![CDATA[
+mprintf("\n%%d: %d,  %%u: %u,  %%o: %o,  %%f: %f,  %%e: %e,  %%s: %s\n" + ..
+          "%%d: %d,  %%u: %u,  %%o: %o,  %%f: %f,  %%e: %e,  %%s: %s\n", ..
+        %T, %T, %T, %T, %T, %T, %F, %F, %F, %F, %F, %F);
+     ]]></programlisting>
+        <screen><![CDATA[
+%d: 1,  %u: 1,  %o: 1,  %f: 1.000000,  %e: 1.000000e+00,  %s: T
+%d: 0,  %u: 0,  %o: 0,  %f: 0.000000,  %e: 0.000000e+00,  %s: F
+]]></screen>
+        <para/>
+        <para>
+            With numbered placeholders:
+        </para>
+        <programlisting role="example"><![CDATA[
+mprintf("%2$s is %1$d-year old.\n", 32, "Peter");
+     ]]></programlisting>
+        <screen><![CDATA[
+Peter is 32-year old.
+]]></screen>
+        <para/>
+        <para>
+            With escaped sequences and UTF-8 extended characters:
+        </para>
+        <programlisting role="example"><![CDATA[
+mprintf("The path T:\\abc does not exist.\n");
+mprintf("abcdefghijk\tαβδ\tεϵ\tζηθικλ\rABCDE\n");
+     ]]></programlisting>
+        <screen><![CDATA[
+--> mprintf("The path T:\\abc does not exist.\n");
+The path T:\abc does not exist
+
+--> mprintf("abcdefghijk\tαβδ\tεϵ\tζηθικλ\rABCDE\n");
+ABCDEfghijk αβδ εϵ  ζηθικλ
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>参照</title>
@@ -336,4 +441,21 @@ mprintf('a character: %c\n', 'aaa');
             </member>
         </simplelist>
     </refsection>
+    <refsection role="history">
+        <title>履歴</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.1.0</revnumber>
+                <revdescription>
+                    Numbered placeholders "%n$.." are supported.
+                </revdescription>
+            </revision>
+            <revision>
+                <revnumber>6.1.1</revnumber>
+                <revdescription>
+                    Input boolean data can be converted.
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>
index ec8f2e1..4ec5be5 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) 2021 - 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="printf_conversion" xml:lang="pt">
+<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="printf_conversion" xml:lang="pt">
     <refnamediv>
         <refname>printf_conversion</refname>
         <refpurpose>Especificações de conversão de mprintf, msprintf,
             </listitem>
             <listitem>
                 <para>
-                    Zero ou mais <literal>options</literal> (opções), que modificam
-                    o significado da especificação de conversão. A lista seguinte contem
-                    os caracteres <literal>option</literal> e seus significados:
-                </para>
-            </listitem>
-            <listitem>
-                <para>Alinhe à esquerda, dentro do campo, o resultado da
-                    conversão.
-                </para>
-            </listitem>
-            <listitem>
-                <para>Comece o resultado de uma conversão com sinal com um sinal (+ ou
-                    -).
+                    An optional integer n ≥ 1 followed by "$". n is the index of the input data
+                    to substitute to the placeholder, in the msprintf, mprintf .. list of input data.
+                    In a format string, placeholders are either all numbered or all non-numbered.
+                    A given numbered placeholder can be used only once in its C-format string
+                    (Scilab limitation).
                 </para>
             </listitem>
             <listitem>
-                <para>Prefixe um caractere de espaço ao resultado se o primeiro
-                    caractere de uma conversão com sinal não for um sinal. Se ambas as
-                    opções (espaço) e + aparecerem, a opção (space) é ignorada.
-                </para>
-            </listitem>
-            <listitem>
-                <para>Converta o valor para uma forma alternativa. Para as conversões
-                    <literal>c</literal>, <literal>d</literal>, <literal>i</literal>,
-                    <literal>s</literal>, e <literal>u</literal>, a opção
-                    <literal>#</literal> não possui efeito. Para a conversão
-                    <literal>o</literal>, <literal>#</literal> aumenta a precisão para
-                    forçar o primeiro dígito do resultado a ser 0 (zero). Para as
-                    conversões <literal>x</literal> e <literal>X</literal>, um valor
-                    não-nulo possui 0x ou 0X prefixado a ele. Para as conversões
-                    <literal>e, E, f, g,</literal> e <literal>G</literal>, o resultado
-                    sempre contém ponto decimal, Mesmo que nenhum dígito o siga. Para as
-                    conversões <literal>g</literal> e <literal>G</literal>, zeros por
-                    último não são removidos.
-                </para>
-            </listitem>
-            <listitem>
-                <para>Aumente a largura do campo utilizando zeros à esquerda (seguindo
-                    qualquer indicação de sinal ou base) para as conversões
-                    <literal>d</literal>, <literal>i</literal>, <literal>o</literal>,
-                    <literal>u</literal>, <literal>x</literal>, <literal>X</literal>,
-                    <literal>e</literal>, <literal>E</literal>, <literal>f</literal>,
-                    <literal>g</literal>, e <literal>G</literal>; nenhum aumento de espaço
-                    é realizado. Se ambos os indicadores <literal>0</literal> e
-                    <literal>\-</literal> (barra) aparecerem, o indicador
-                    <literal>0</literal> é ignorado. Para as conversões
-                    <literal>d</literal>, <literal>i</literal>, <literal>o</literal>
-                    <literal>u</literal>, <literal>x</literal>, e <literal>X</literal>, se
-                    uma precisão for especificada, o indicador <literal>0</literal> também
-                    é ignorado.
+                <para>
+                    Zero ou mais <literal>options</literal> (opções), que modificam
+                    o significado da especificação de conversão. A lista seguinte contem
+                    os caracteres <literal>option</literal> e seus significados:
                 </para>
+                <table>
+                    <tr>
+                        <th>- :</th>
+                        <td>
+                            Alinhe à esquerda, dentro do campo, o resultado da conversão.
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>+ :</th>
+                        <td>
+                            Comece o resultado de uma conversão com sinal com um sinal (+ ou -).
+                        </td>
+                    </tr>
+                    <tr>
+                        <td style="white-space:nowrap"><emphasis role="bold">' ' :</emphasis></td>
+                        <td>
+                            (space) Prefixe um caractere de espaço ao resultado se o primeiro
+                            caractere de uma conversão com sinal não for um sinal. Se ambas as
+                            opções (espaço) e + aparecerem, a opção (space) é ignorada.
+                        </td>
+                    </tr>
+                    <tr>
+                        <th># :</th>
+                        <td>
+                            Converta o valor para uma forma alternativa. Para as conversões
+                            <literal>c</literal>, <literal>d</literal>, <literal>i</literal>,
+                            <literal>s</literal>, e <literal>u</literal>, a opção
+                            <literal>#</literal> não possui efeito. Para a conversão
+                            <literal>o</literal>, <literal>#</literal> aumenta a precisão para
+                            forçar o primeiro dígito do resultado a ser 0 (zero). Para as
+                            conversões <literal>x</literal> e <literal>X</literal>, um valor
+                            não-nulo possui 0x ou 0X prefixado a ele. Para as conversões
+                            <literal>e, E, f, g,</literal> e <literal>G</literal>, o resultado
+                            sempre contém ponto decimal, Mesmo que nenhum dígito o siga. Para as
+                            conversões <literal>g</literal> e <literal>G</literal>, zeros por
+                            último não são removidos.
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>0 :</th>
+                        <td>
+                            Aumente a largura do campo utilizando zeros à esquerda (seguindo
+                            qualquer indicação de sinal ou base) para as conversões
+                            <literal>d</literal>, <literal>i</literal>, <literal>o</literal>,
+                            <literal>u</literal>, <literal>x</literal>, <literal>X</literal>,
+                            <literal>e</literal>, <literal>E</literal>, <literal>f</literal>,
+                            <literal>g</literal>, e <literal>G</literal>; nenhum aumento de espaço
+                            é realizado. Se ambos os indicadores <literal>0</literal> e
+                            <literal>\-</literal> (barra) aparecerem, o indicador
+                            <literal>0</literal> é ignorado. Para as conversões
+                            <literal>d</literal>, <literal>i</literal>, <literal>o</literal>
+                            <literal>u</literal>, <literal>x</literal>, e <literal>X</literal>, se
+                            uma precisão for especificada, o indicador <literal>0</literal> também
+                            é ignorado.
+                        </td>
+                    </tr>
+                </table>
             </listitem>
             <listitem>
                 <para>Um string de dígitos decimais opcional que especifica a largura
                 </para>
                 <itemizedlist>
                     <listitem>
-                        <para>O número mínimo de dígitos a aparecerem nas conversões
-                            <literal>d</literal>, <literal>u</literal>, <literal>o</literal>,
-                            <literal>x</literal>, ou <literal>X</literal>
-                        </para>
+                        O número mínimo de dígitos a aparecerem nas conversões
+                        <literal>d</literal>, <literal>u</literal>, <literal>o</literal>,
+                        <literal>x</literal>, ou <literal>X</literal>.
                     </listitem>
                     <listitem>
-                        <para>O número de dígitos a aparecerem após o ponto decimal nas
-                            conversões <literal>e</literal>, <literal>E</literal>, e
-                            <literal>f</literal>
-                        </para>
+                        O número de dígitos a aparecerem após o ponto decimal nas
+                        conversões <literal>e</literal>, <literal>E</literal>, e
+                        <literal>f</literal>.
                     </listitem>
                     <listitem>
-                        <para>O número máximo de dígitos significativos para as conversões
-                            <literal>g</literal> e <literal>G</literal>
-                        </para>
+                        O número máximo de dígitos significativos para as conversões
+                        <literal>g</literal> e <literal>G</literal>.
                     </listitem>
                     <listitem>
-                        <para>O número máximo de caracteres a serem impressos a partir de um
-                            string em uma convesão <literal>s</literal>
-                        </para>
+                        O número máximo de caracteres a serem impressos a partir de um
+                        string em uma convesão <literal>s</literal>.
                     </listitem>
                 </itemizedlist>
             </listitem>
                 <para>O caractere que indica o tipo de conversão a ser
                     aplicada:
                 </para>
-            </listitem>
-            <listitem>
-                <para>Não realiza conversão. Exibe %.</para>
-            </listitem>
-            <listitem>
-                <para>Aceita um valor inteiro e o converte para notação decimal com
-                    sinal. A precisão especifica o número mínimo de dígitos a aparecer. Se
-                    o valor sendo convertido puder ser representado em menos dígitos, ele
-                    é expandido com zeros à esquerda. A precisão padrão é 1. O resultado
-                    de se converter um valor zero com uma precisão de zero é um string
-                    nulo. A especificação de uma largura de campo com zero como caractere
-                    mais à esquerda faz com que o valor da largura do campo seja
-                    preenchido com zeros à esquerda.
-                </para>
-            </listitem>
-            <listitem>
-                <para>Aceita um valor inteiro e o converte para a notação decimal sem
-                    sinal. A precisão especifica o número mínimo de dígitos a aparecer. Se
-                    o valor sendo convertido puder ser representado em menos dígitos, ele
-                    é expandido com zeros à esquerda. A precisão padrão é 1. O resultado
-                    de se converter um valor zero com uma precisão de zero é um string
-                    nulo. A especificação de uma largura de campo com zero como caractere
-                    mais à esquerda faz com que o valor da largura do campo seja
-                    preenchido com zeros à esquerda.
-                </para>
-            </listitem>
-            <listitem>
-                <para>Aceita um valor inteiro e o converte para a sua notação octal
-                    sem sinal. A precisão especifica o número mínimo de dígitos a
-                    aparecer. Se o valor sendo convertido puder ser representado em menos
-                    dígitos, ele é expandido com zeros à esquerda. A precisão padrão é 1.
-                    O resultado de se converter um valor zero com uma precisão de zero é
-                    um string nulo. A especificação de uma largura de campo com zero como
-                    caractere mais à esquerda faz com que o valor da largura do campo seja
-                    preenchido com zeros à esquerda. Não é implicado um valor octal para a
-                    largura do campo.
-                </para>
-            </listitem>
-            <listitem>
-                <para>Aceita um valor inteiro e o converte para a sua notação
-                    hexadecimal sem sinal. As letras ``abcdef'' são utilizadas para a
-                    conversão <literal>x</literal>; as letras ``ABCDEF'' são utilizadas
-                    para a conversão <literal>X</literal>. A precisão especifica o número
-                    mínimo de dígitos a aparecer. Se o valor sendo convertido puder ser
-                    representado em menos dígitos, ele é expandido com zeros à esquerda. A
-                    precisão padrão é 1. O resultado de se converter um valor zero com uma
-                    precisão de zero é um string nulo. A especificação de uma largura de
-                    campo com zero como caractere mais à esquerda faz com que o valor da
-                    largura do campo seja preenchido com zeros à esquerda.
-                </para>
-            </listitem>
-            <listitem>
-                <para>Aceita um valor float ou double e o converte para a sua notação
-                    decimal no formato %[\-]<literal>ddd.ddd</literal>. O número de
-                    dígitos após o ponto decimal é igual à especificação de
-                    precisão.
-                </para>
-            </listitem>
-            <listitem>
-                <para>Se nenhuma precisão for especificada, a saída possui seis
-                    dígitos
-                </para>
-            </listitem>
-            <listitem>
-                <para>Se a precisão for zero, nenhum ponto decimal aparece e o sistema
-                    imprime na saída o valor inteiro mais próximo de
-                    <literal>value</literal>.
-                </para>
-            </listitem>
-            <listitem>
-                <para>Se a saída possui um ponto decimal, pelo menos um dígito é posto
-                    antes dele.
-                </para>
-            </listitem>
-            <listitem>
-                <para>Aceita um real e o converte para a sua forma exponencial
-                    %[\-]<literal>d.ddde</literal>+/\-<literal>dd</literal>. Há um dígito
-                    antes do ponto decimal, e o número de dígitos após o ponto decimal é
-                    igual à especificação de precisão.
-                </para>
-            </listitem>
-            <listitem>
-                <para>Se nenhuma precisão for especificada, a saída são seis
-                    dígitos
-                </para>
-            </listitem>
-            <listitem>
-                <para>Se a precisão for zero, nenhum ponto decimal aparece.</para>
-            </listitem>
-            <listitem>
-                <para>
-                    A caractere de conversão <literal>E</literal> produz um número
-                    com o caractere 'E', ao invés de 'e' antes do expoente. O expoente
-                    sempre contém pelo menos dois dígitos. Se o valor for zero, o expoente
-                    é zero.
-                </para>
-            </listitem>
-            <listitem>
-                <para>Aceita um real e o converte no estilo dos caracteres de
-                    conversão <literal>e</literal>, <literal>E</literal>, ou
-                    <literal>f</literal>, com a precisão especificando o número de dígitos
-                    significativos. Zeros por último são removidos. Um ponto decimal
-                    aparece apenas se for seguido de um dígito. O estilo depende do valor
-                    convertido. O resultado é o estilo <literal>e</literal>
-                    (<literal>E</literal>, se <literal>G</literal> é o indicador
-                    utilizado) apenas se o expoente resultante da conversão for menor do
-                    que -4, ou se for maior do que ou igual à precisão.
-                </para>
-            </listitem>
-            <listitem>
-                <para>Aceita e exibe um valor inteiro convertido em um
-                    caractere.
-                </para>
-            </listitem>
-            <listitem>
-                <para>Aceita um valor string e exibe caracteres do string até o fim
-                    ou até que o número de caracteres indicados pela precisão seja
-                    alcançado. Se nenhuma precisão for especificada, todos os caracteres
-                    até o fim são exibidos.
-                </para>
+                <table>
+                    <tr>
+                        <th>% :</th>
+                        <td>
+                            Não realiza conversão. Exibe %..
+                            <note>
+                                This may be useful for instance to print percentages, or
+                                to process some LaTeX expression including LaTeX comments
+                                starting with "%", etc.
+                            </note>
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>s :</th>
+                        <td>
+                            Accepts a string or boolean <literal>value</literal> e exibe caracteres
+                            do string até o fim ou até que o número de caracteres indicados pela
+                            precisão seja alcançado. Se nenhuma precisão for especificada, todos os
+                            caracteres até o fim são exibidos.
+                            UTF-8 extended characters are supported in input strings.
+                            Booleans are converted into 'T' or 'F'.
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>c :</th>
+                        <td>Not supported.
+                        </td>
+                    </tr>
+                    <tr>
+                        <td colspan="2">
+                            All following conversions accept any decimal numerical or boolean
+                            input <literal>value</literal>. Only the real part of any input
+                            complex number is considered. Booleans are implicitly converted
+                            into 0 and 1.
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>d,i :</th>
+                        <td>
+                            Converts the input <literal>value</literal> to a signed integer int32
+                            notation. Conversions for input |Numbers| ≥ 2^31 are not reliable.
+                            A precisão especifica o número mínimo de dígitos a aparecer. Se
+                            o valor sendo convertido puder ser representado em menos dígitos, ele
+                            é expandido com zeros à esquerda. A precisão padrão é 1. O resultado
+                            de se converter um valor zero com uma precisão de zero é um string
+                            nulo. A especificação de uma largura de campo com zero como caractere
+                            mais à esquerda faz com que o valor da largura do campo seja
+                            preenchido com zeros à esquerda.
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>u :</th>
+                        <td>
+                            Converts the input <literal>value</literal> to an unsigned integer
+                            uint32 notation. Conversions for input |Numbers| ≥ 2^32 are not reliable.
+                            A precisão especifica o número mínimo de dígitos a aparecer. Se
+                            o valor sendo convertido puder ser representado em menos dígitos, ele
+                            é expandido com zeros à esquerda. A precisão padrão é 1. O resultado
+                            de se converter um valor zero com uma precisão de zero é um string
+                            nulo. A especificação de uma largura de campo com zero como caractere
+                            mais à esquerda faz com que o valor da largura do campo seja
+                            preenchido com zeros à esquerda.
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>o :</th>
+                        <td>
+                            Converts the input <literal>value</literal> to an unsigned octal notation.
+                            Conversions for input |Numbers| ≥ 2^32 are not reliable.
+                            A precisão especifica o número mínimo de dígitos a
+                            aparecer. Se o valor sendo convertido puder ser representado em menos
+                            dígitos, ele é expandido com zeros à esquerda. A precisão padrão é 1.
+                            O resultado de se converter um valor zero com uma precisão de zero é
+                            um string nulo. A especificação de uma largura de campo com zero como
+                            caractere mais à esquerda faz com que o valor da largura do campo seja
+                            preenchido com zeros à esquerda. Não é implicado um valor octal para a
+                            largura do campo.
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>x, X :</th>
+                        <td>
+                            Converts the input <literal>value</literal> to an unsigned hexadecimal
+                            notation. Conversions for input |Numbers| ≥ 2^32 are not reliable.
+                            As letras ``abcdef'' são utilizadas para a
+                            conversão <literal>x</literal>; as letras ``ABCDEF'' são utilizadas
+                            para a conversão <literal>X</literal>. A precisão especifica o número
+                            mínimo de dígitos a aparecer. Se o valor sendo convertido puder ser
+                            representado em menos dígitos, ele é expandido com zeros à esquerda. A
+                            precisão padrão é 1. O resultado de se converter um valor zero com uma
+                            precisão de zero é um string nulo. A especificação de uma largura de
+                            campo com zero como caractere mais à esquerda faz com que o valor da
+                            largura do campo seja preenchido com zeros à esquerda.
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>f :</th>
+                        <td>
+                            Converte o <literal>value</literal> de entrada para a sua notação decimal
+                            no formato% [\-]<literal>ddd.ddd</literal>.
+                            O número de dígitos após o ponto decimal é igual à especificação de
+                            precisão.
+                            <itemizedlist>
+                                <listitem>
+                                    Se nenhuma precisão for especificada, a saída possui seis dígitos
+                                </listitem>
+                                <listitem>
+                                    Se a precisão for zero, nenhum ponto decimal aparece e o sistema
+                                    imprime na saída o valor inteiro mais próximo de
+                                    <literal>value</literal>.
+                                </listitem>
+                                <listitem>
+                                    Se a saída possui um ponto decimal, pelo menos um dígito é posto
+                                    antes dele.
+                                </listitem>
+                            </itemizedlist>
+                        </td>
+                    </tr>
+                    <tr>
+                        <th>e, E :</th>
+                        <td>
+                            Converte o <literal>value</literal> de entrada para a sua forma exponencial
+                            %[\-]<literal>d.ddde</literal>+/\-<literal>dd</literal>.
+                            Há um dígito antes do ponto decimal, e o número de dígitos após o
+                            ponto decimal é igual à especificação de precisão.
+                            <itemizedlist>
+                                <listitem>
+                                    Se nenhuma precisão for especificada, a saída são seis dígitos.
+                                </listitem>
+                                <listitem>
+                                    Se a precisão for zero, nenhum ponto decimal aparece.
+                                </listitem>
+                                <listitem>
+                                    A caractere de conversão <literal>E</literal> produz um
+                                    número com o caractere 'E', ao invés de 'e' antes do expoente.
+                                    O expoente sempre contém pelo menos dois dígitos. Se o valor
+                                    for zero, o expoente é zero.
+                                </listitem>
+                            </itemizedlist>
+                        </td>
+                    </tr>
+                    <tr>
+                        <td style="white-space:nowrap"><emphasis role="bold">g, G :</emphasis></td>
+                        <td>
+                            Converte o <literal>value</literal> de entrada no estilo dos caracteres
+                            de conversão <literal>e</literal>, <literal>E</literal>, ou
+                            <literal>f</literal>, com a precisão especificando o número de dígitos
+                            significativos.
+                            Zeros por último são removidos. Um ponto decimal
+                            aparece apenas se for seguido de um dígito. O estilo depende do valor
+                            convertido. O resultado é o estilo <literal>e</literal>
+                            (<literal>E</literal>, se <literal>G</literal> é o indicador
+                            utilizado) apenas se o expoente resultante da conversão for menor do
+                            que -4, ou se for maior do que ou igual à precisão.
+                        </td>
+                    </tr>
+                </table>
             </listitem>
         </itemizedlist>
         <para>Uma largura de campo ou uma precisão podem ser indicadas por
         <para>A representação do sinal de mais depende da opção de formatação
             especificada, se <literal>+</literal> ou (espaço).
         </para>
+        <para>
+            Display of exponential form %e is platform dependent with a different number of digits
+            in exponent.
+            <informaltable border="1">
+                <tr>
+                    <td>Platform</td>
+                    <td>Example: msprintf("%e",1.23e4)</td>
+                </tr>
+                <tr>
+                    <td>Windows</td>
+                    <td>1.23000e+004</td>
+                </tr>
+                <tr>
+                    <td>Linux/Mac OS</td>
+                    <td>1.23000e+04</td>
+                </tr>
+            </informaltable>
+        </para>
+        <para>
+            <emphasis role="bold">Special escaped sequences</emphasis> are supported in Scilab
+            C-format strings:
+            <table>
+                <tr>
+                    <th>\n :</th>
+                    <td>Go to Next line (line feed)</td>
+                </tr>
+                <tr>
+                    <th>\r :</th>
+                    <td>Return: go to the head of current line (for overprinting)</td>
+                </tr>
+                <tr>
+                    <th>\t :</th>
+                    <td>horizontal Tab</td>
+                </tr>
+                <tr>
+                    <th>\\ :</th>
+                    <td>print a backslash \</td>
+                </tr>
+            </table>
+        </para>
+    </refsection>
+    <refsection>
+        <title>Exemplos</title>
+        <programlisting role="example"><![CDATA[
+mprintf('a string: %s\n', 'Scilab');
+mprintf('an integer: %d\n', 10);
+mprintf('an integer: %4d\n', 10);
+mprintf('a left justified integer: %-4d\n', 10);
+mprintf('an integer converted to float: %#fd\n',10);
+mprintf('an integer with a sign: %+4d\n', 10);
+mprintf('an integer with a sign: %+4d\n', -10);
+mprintf('an integer padded with zeros: %04d\n', 10);
+mprintf('an unsigned integer: %u\n', 10);
+mprintf('an unsigned integer: %4u\n', -10);
+mprintf('an integer converted to hexadecimal: %x\n', 10);
+mprintf('a float: %d\n', %pi);
+mprintf('a float: %3.2d\n', %pi);
+mprintf('a float (exponential form): %3.2e\n', %pi);
+mprintf('a float (exponential form): %3.2g\n', %pi);
+mprintf('a character: %c\n', 'a');
+mprintf('a character: %c\n', 'aaa');
+ ]]></programlisting>
+        <para/>
+        <para>
+            With input booleans:
+        </para>
+        <programlisting role="example"><![CDATA[
+mprintf("\n%%d: %d,  %%u: %u,  %%o: %o,  %%f: %f,  %%e: %e,  %%s: %s\n" + ..
+          "%%d: %d,  %%u: %u,  %%o: %o,  %%f: %f,  %%e: %e,  %%s: %s\n", ..
+        %T, %T, %T, %T, %T, %T, %F, %F, %F, %F, %F, %F);
+     ]]></programlisting>
+        <screen><![CDATA[
+%d: 1,  %u: 1,  %o: 1,  %f: 1.000000,  %e: 1.000000e+00,  %s: T
+%d: 0,  %u: 0,  %o: 0,  %f: 0.000000,  %e: 0.000000e+00,  %s: F
+]]></screen>
+        <para/>
+        <para>
+            With numbered placeholders:
+        </para>
+        <programlisting role="example"><![CDATA[
+mprintf("%2$s is %1$d-year old.\n", 32, "Peter");
+     ]]></programlisting>
+        <screen><![CDATA[
+Peter is 32-year old.
+]]></screen>
+        <para/>
+        <para>
+            With escaped sequences and UTF-8 extended characters:
+        </para>
+        <programlisting role="example"><![CDATA[
+mprintf("The path T:\\abc does not exist.\n");
+mprintf("abcdefghijk\tαβδ\tεϵ\tζηθικλ\rABCDE\n");
+     ]]></programlisting>
+        <screen><![CDATA[
+--> mprintf("The path T:\\abc does not exist.\n");
+The path T:\abc does not exist
+
+--> mprintf("abcdefghijk\tαβδ\tεϵ\tζηθικλ\rABCDE\n");
+ABCDEfghijk αβδ εϵ  ζηθικλ
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>Ver Também</title>
             </member>
         </simplelist>
     </refsection>
+    <refsection role="history">
+        <title>Histórico</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.1.0</revnumber>
+                <revdescription>
+                    Numbered placeholders "%n$.." are supported.
+                </revdescription>
+            </revision>
+            <revision>
+                <revnumber>6.1.1</revnumber>
+                <revdescription>
+                    Input boolean data can be converted.
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>