* rewriten: `consolebox`, `double`, `isoview`, `householder`, `or`, `and`, `format`. 75/18275/5
Samuel GOUGEON [Tue, 21 Jun 2016 02:01:35 +0000 (04:01 +0200)]
* Functionnalities based on former Scilab stack have been removed:
* [Bug #13597](http://bugzilla.scilab.org/show_bug.cgi?id=13597) fixed - `help format` claimed setting a number of digits instead of characters
* Bug #13597 fixed: help format overhauled

  * http://bugzilla.scilab.org/13597
  * (en) mostly rewritten
  * (fr) translation to come after the (en) approval

Change-Id: I33c92e92ae0df8e701f4eabde783dc1cba86a644

scilab/CHANGES.md
scilab/modules/elementary_functions/help/en_US/floating_point/format.xml
scilab/modules/elementary_functions/help/ja_JP/floating_point/format.xml [deleted file]
scilab/modules/elementary_functions/help/pt_BR/floating_point/format.xml [deleted file]

index a6592ae..2e63eba 100644 (file)
@@ -145,7 +145,7 @@ Help pages:
 
 * CACSD and Signal Processing help pages have been sorted up.
 * fixed / improved:  `members`, `part`, `ode`, `ode_optional_output`, `ode_roots`, `roots`, `printf`, `sprintf`, `iconvert`, `stdev`, `xlabel`
-* rewriten: `consolebox`, `double`, `isoview`, `householder`, `or`, `and`.
+* rewriten: `consolebox`, `double`, `isoview`, `householder`, `or`, `and`, `format`.
 * resorted: `else`, `elseif`, `end`, `try`, `sciargs`, `global`, `halt`, `empty`, `power`
 * added: support to `valign=".."` and `style="white-space:nowrap"` attributes for `<td>` and `<th>` tags
 
@@ -205,7 +205,7 @@ Removed Functions
 * `lex_sort` has been removed. Please use `gsort(..,"lr")` instead
 
 * Symbolic module functions have been removed: `addf`, `cmb_lin`, `ldivf`, `mulf`, `rdivf`, `solve`, `subf`, `trianfml`, `trisolve` and `block2exp`.
-* Functionnalities based on former Scilab stack have been removed: 
+* Functionnalities based on former Scilab stack have been removed:
   - `comp`, `errcatch`, `iserror`, `fun2string`, `getvariablesonstack`, `gstacksize`, `macr2lst`, `stacksize`, `code2str` and `str2code`.
   - `-mem` launching option (used to set `stacksize` at startup).
 
@@ -222,10 +222,9 @@ Bug Fixes
 
 ### In 6.0.0:
 
+* [Bug #13597](http://bugzilla.scilab.org/show_bug.cgi?id=13597) fixed - `help format` claimed setting a number of digits instead of characters
 * [Bug #14557](http://bugzilla.scilab.org/show_bug.cgi?id=14557) fixed - csim failed when the system has no state.
-
 * [Bug #14587](http://bugzilla.scilab.org/show_bug.cgi?id=14587) fixed - Datatip textbox wrong clipping when loaded from *.scg file.
 
 ### In 6.0.0 beta-2 and earlier:
 
index fd3fbd7..aa3cd27 100644 (file)
 <?xml version="1.0" encoding="UTF-8"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2016 - Samuel GOUGEON
+ * 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="format" xml:lang="en">
     <refnamediv>
         <refname>format</refname>
-        <refpurpose>number printing and display format</refpurpose>
+        <refpurpose>set the default output format of decimal numbers</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
         <synopsis>
-            format([type],[long])
+            format(mode)
+            format(width)
+            format(mode, width)
+            format(wm)
             v = format()
-            format(m)
         </synopsis>
     </refsynopsisdiv>
-    <refsection>
+    <refsection role="parameters">
         <title>Arguments</title>
         <variablelist>
             <varlistentry>
-                <term>type</term>
+                <term>mode</term>
                 <listitem>
-                    <para>character string</para>
+                    <para>formatting mode:
+                        <itemizedlist>
+                          <listitem>1 or "v": <emphasis role="bold">v</emphasis>ariable adaptative
+                            formatting. Scilab chooses either the direct representation
+                            (e.g. -143.8757) or
+                            the exponential/engineering/scientific notation (e.g. -1.438E+02),
+                            in order to cope with each processed value as well as with the
+                            required width, with a maximal number of output digits.
+                          </listitem>
+                          <listitem>0 or "e": The <emphasis role="bold">e</emphasis>xponential
+                            /<emphasis role="bold">e</emphasis>ngineering notation is forced
+                            and used for all numbers.
+                          </listitem>
+                      </itemizedlist>
+                  </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>long</term>
+                <term>width</term>
                 <listitem>
-                    <para>integer (max number of digits (default 10))</para>
+                    <para>width of numbers = number of output characters used, all included: sign of
+                      the mantissa, its digits, decimal separator, exponent symbol, sign and digits
+                      of the exponent. (default width = 10)</para>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>v</term>
+                <term>wm</term>
                 <listitem>
-                    <para>a vector for the current format.</para>
-                    <para>
-                        <literal>v(1)</literal> is a type of format : 0 for 'e' 
-                        and 1 for 'v'
-                    </para>
-                    <para>
-                        <literal>v(2)</literal> is a number of digits 
+                    <para>a vector to set new format </para>
+                    <para><literal>wm(1)</literal> is the width</para>
+                    <para><literal>wm(2)</literal> is the formatting mode: 0 for
+                      <literal>'e'</literal> and 1 for <literal>'v'</literal>
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>m</term>
+                <term>v</term>
                 <listitem>
-                    <para>a vector to set new format </para>
-                    <para>m(1) is a number of digits </para>
-                    <para>m(2) is a type of format : 0 for 'e' and 1 for 'v'</para>
-                </listitem>
+                    <para>vector returning the current formatting parameters:
+                        <itemizedlist>
+                          <listitem><literal>v(1)</literal> is the formatting mode:
+                            0 for <literal>'e'</literal> and 1 for <literal>'v'</literal>
+                          </listitem>
+                          <listitem><literal>v(2)</literal> is the width: Number of characters used
+                            to output each number.
+                          </listitem>
+                         </itemizedlist>
+                     </para>
+                 </listitem>
             </varlistentry>
         </variablelist>
     </refsection>
-    <refsection>
+    <refsection role="description">
         <title>Description</title>
-        <para>Sets the current printing format with the parameter
-            <literal>type</literal>; it is one of the following :
-        </para>
-        <variablelist>
-            <varlistentry>
-                <term>"v"</term>
-                <listitem>
-                    <para>for a variable format (default)</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>"e"</term>
-                <listitem>
-                    <para>for the e-format.</para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-        <para>
-            <literal>long</literal> defines the max number of digits (default
-            10). <literal>format()</literal> returns a vector for the current format:
-            first component is the type of format (1 if 'v' ; 0 if
-            'e'); second component is the number of digits.
-        </para>
+            <note>For complex numbers, each real and imaginary decimal part is output according to
+             format(..). The total width of a complex number is therefore roughly twice greater (+ 1
+              character for "i" symbol).
+            </note>
+            <note>Encoded integers are never output according to the "e"xponential mode, even when
+                this formatting is the default mode set for decimal numbers. For them, the decimal
+                separator "." is skipped. This allows to distinguish them from decimal integers
+                that have a dot.
+            </note>
+            <note>For wide format(), digits that may be displayed beyond the
+                relative accuracy <literal>%eps</literal> are set to 0.
+            </note>
+            <warning>The default decimal format set with
+                <function>format(..)</function> is a global parameter:
+                Wherever you set it, it then applies everywhere in Scilab and Xcos.
+            </warning>
         <para>In the old Scilab versions, in "variable format" mode, vector
-            entries which are less than %eps times the maximum absolute value of the
+            entries which are less than <literal>%eps</literal> times the maximum absolute value of the
             entries were displayed as "0". It is no more the case, the clean function
             can be used to set negligible entries to zeros.
         </para>
     </refsection>
-    <refsection>
+    <refsection role="examples">
         <title>Examples</title>
-        <programlisting role="example"><![CDATA[ 
-x=rand(1,5);
-format('v',10);x
-format(20);x
-format('e',10);x
-format(20);x
+        <programlisting role="example"><![CDATA[
+// format() is not taken into account for encoded integers
+// -------------------------------------------------------
+format("e",6)
+int32(2.^grand(3,5,"uin",0,30))
+
+// format() impacts console's output, disp(), string(), sci2exp(),...
+// --------------------------------------------------------------
+a = %pi; p = %pi + %z - %e*%z^2;
+format("v",10);
+a, p
+disp(a,p)
+string(a), string(p)
+[sci2exp(a) sci2exp(p)]
+
+format("e",15);
+a, p
+disp(a,p)
+string(a), string(p)
+[sci2exp(a) sci2exp(p)]
+format("v",10); // reset
+
+// format() set the width, not a fixed number of digits:
+// ----------------------------------------------------
+format("v",10)
+%pi*1e-217, s = string(%pi*1e-217)
+length(s) // the missing char is the implicit "+" sign
 
-x=[100 %eps];
-format('e',10);x
-format('v',10);x
+// This is usefull to get aligned and fully informative display of matrices
+[ -1.234 %pi*1e-10 %nan ; %e*1e137 -%inf 54312]
 
-format("v")
+// Since Scilab 6.0, unrelevant digits displayed with wide format() are set to 0:
+format(22)
+%pi
+
+// format() has a global impact
+// ----------------------------
+function myfun()
+    format("e",20)
+endfunction
+format("v", 10)
+disp(%pi)
+myfun()
+// it remains everywhere, wherever it has been set:
+disp(%pi)
+format("v",10) // reset
  ]]></programlisting>
     </refsection>
     <refsection role="see also">
         <title>See Also</title>
         <simplelist type="inline">
             <member>
-                <link linkend="write">write</link>
+                <link linkend="number_properties">numbers properties</link>
+            </member>
+            <member>
+                <link linkend="string">string</link>
+            </member>
+            <member>
+                <link linkend="sci2exp">sci2exp</link>
             </member>
             <member>
                 <link linkend="disp">disp</link>
@@ -110,8 +178,28 @@ format("v")
                 <link linkend="print">print</link>
             </member>
             <member>
-                <link linkend="clean">clean</link>
+                <link linkend="printf_conversion">C-like format</link>
+            </member>
+            <member>
+                <link linkend="mprintf">mprintf</link>
+            </member>
+            <member>
+                <link linkend="msprintf">msprintf</link>
+            </member>
+            <member>
+                <link linkend="mfprintf">mfprintf</link>
             </member>
-        </simplelist>
+      </simplelist>
+    </refsection>
+    <refsection role="history">
+        <title>History</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.0</revnumber>
+                <revdescription>For wide format(), digits that may be displayed
+                    beyond the relative accuracy %eps are now set to 0.
+                </revdescription>
+            </revision>
+        </revhistory>
     </refsection>
 </refentry>
diff --git a/scilab/modules/elementary_functions/help/ja_JP/floating_point/format.xml b/scilab/modules/elementary_functions/help/ja_JP/floating_point/format.xml
deleted file mode 100644 (file)
index e622e5a..0000000
+++ /dev/null
@@ -1,240 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-
-<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="format" xml:lang="ja">
-    
-    <refnamediv>
-        
-        <refname>format</refname>
-        
-        <refpurpose>数値の印字および表示形式</refpurpose>
-        
-    </refnamediv>
-    
-    <refsynopsisdiv>
-        
-        <title>呼出し手順</title>
-        
-        <synopsis>
-            
-            format([type],[long])
-            
-            v = format()
-            
-            format(m)
-            
-        </synopsis>
-        
-    </refsynopsisdiv>
-    
-    <refsection>
-        
-        <title>引数</title>
-        
-        <variablelist>
-            
-            <varlistentry>
-                
-                <term>type</term>
-                
-                <listitem>
-                    
-                    <para>文字列</para>
-                    
-                </listitem>
-                
-            </varlistentry>
-            
-            <varlistentry>
-                
-                <term>long</term>
-                
-                <listitem>
-                    
-                    <para>整数 (最大桁数 (デフォルト 10))</para>
-                    
-                </listitem>
-                
-            </varlistentry>
-            
-            <varlistentry>
-                
-                <term>v</term>
-                
-                <listitem>
-                    
-                    <para>
-                        
-                        カレントのフォーマットに関するベクトル. 
-                        
-                    </para>
-                    
-                    <para>
-                        
-                        <literal>v(1)</literal> は形式の型: 'e' の場合は 0,
-                        
-                        'v' の場合は 1.
-                        
-                    </para>
-                    
-                    <para>
-                        
-                        <literal>v(2)</literal> は桁数です.
-                        
-                    </para>
-                    
-                </listitem>
-                
-            </varlistentry>
-            
-            <varlistentry>
-                
-                <term>m</term>
-                
-                <listitem>
-                    
-                    <para>新しい形式を設定するためのベクトル</para>
-                    
-                    <para>m(1) は桁数です</para>
-                    
-                    <para>m(2) は形式の型です : 'e' の場合は 0, 'v' の場合は 1</para>
-                    
-                </listitem>
-                
-            </varlistentry>
-            
-        </variablelist>
-        
-    </refsection>
-    
-    <refsection>
-        
-        <title>説明</title>
-        
-        <para>
-            
-            カレントの出力形式を<literal>type</literal>
-            
-            で指定します.
-            
-            この指定は以下のどれかとなります :
-            
-        </para>
-        
-        <variablelist>
-            
-            <varlistentry>
-                
-                <term>"v"</term>
-                
-                <listitem>
-                    
-                    <para>変数形式の場合 (デフォルト)</para>
-                    
-                </listitem>
-                
-            </varlistentry>
-            
-            <varlistentry>
-                
-                <term>"e"</term>
-                
-                <listitem>
-                    
-                    <para>指数形式の場合.</para>
-                    
-                </listitem>
-                
-            </varlistentry>
-            
-        </variablelist>
-        
-        <para>
-            
-            <literal>long</literal>は桁数の最大値(デフォルト:10)を
-            
-            定義します.
-            
-            <literal>format()</literal> はカレントの形式のベクトルを
-            
-            返します: 
-            
-            最初の要素は format の型
-            
-            (<literal>v</literal> の場合は 1; <literal>e</literal>の場合は 0);
-            
-            2番目の要素は桁数です.
-            
-        </para>
-        
-        <para>
-            
-            古いバージョンのScilabでは,
-            
-            "変数形式"モードにおいて,
-            
-            %eps にそのエントリの絶対値の最大値を乗じたものより
-            
-            小さいベクトルのエントリは "0" と表示されていました.
-            
-            現在のバージョンではそのようなことはなく,
-            
-            無視できるエントリをゼロにするには clear 関数が使用されます.
-            
-        </para>
-        
-    </refsection>
-    
-    <refsection>
-        
-        <title>例</title>
-        
-        <programlisting role="example"><![CDATA[ 
-x=rand(1,5);
-format('v',10);x
-format(20);x
-format('e',10);x
-format(20);x
-x=[100 %eps];
-format('e',10);x
-format('v',10);x
-format("v")
- ]]></programlisting>
-        
-    </refsection>
-    
-    <refsection role="see also">
-        
-        <title>参照</title>
-        
-        <simplelist type="inline">
-            
-            <member>
-                
-                <link linkend="write">write</link>
-                
-            </member>
-            
-            <member>
-                
-                <link linkend="disp">disp</link>
-                
-            </member>
-            
-            <member>
-                
-                <link linkend="print">print</link>
-                
-            </member>
-            
-            <member>
-                
-                <link linkend="clean">clean</link>
-                
-            </member>
-            
-        </simplelist>
-        
-    </refsection>
-    
-</refentry>
-
diff --git a/scilab/modules/elementary_functions/help/pt_BR/floating_point/format.xml b/scilab/modules/elementary_functions/help/pt_BR/floating_point/format.xml
deleted file mode 100644 (file)
index 78d6398..0000000
+++ /dev/null
@@ -1,115 +0,0 @@
-<?xml version="1.0" encoding="windows-1251"?>
-<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="format" xml:lang="en">
-    <refnamediv>
-        <refname>format</refname>
-        <refpurpose>impress&#227;o de n&#250;meros e formato de
-            exibi&#231;&#227;o
-        </refpurpose>
-    </refnamediv>
-    <refsynopsisdiv>
-        <title>Seq&#252;&#234;ncia de Chamamento</title>
-        <synopsis>format([type],[long])
-            v = format()
-            format(m)
-        </synopsis>
-    </refsynopsisdiv>
-    <refsection>
-        <title>Par&#226;metros</title>
-        <variablelist>
-            <varlistentry>
-                <term>type</term>
-                <listitem>
-                    <para>string</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>long</term>
-                <listitem>
-                    <para>inteiro ( n&#250;mero m&#225;ximo de digitos (padr&#227;o
-                        10))
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>v</term>
-                <listitem>
-                    <para>um vetor para o formato corrente onde v(1) &#233; o de tipo de
-                        formato : 0 para 'e' e 1 para 'v' v(2) n&#250;mero de
-                        d&#237;gitos
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>m</term>
-                <listitem>
-                    <para>um vetor para ajuste de novo formato</para>
-                    <para>m(1) n&#250;mero de digitos</para>
-                    <para>m(2) tipo de formato : 0 para 'e' e 1 para 'v'</para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>Descri&#231;&#227;o</title>
-        <para>Ajusta o formato de impress&#227;o corrente atrav&#233;s do
-            par&#226;metro <literal>type</literal> ; &#233; um dos seguintes :
-        </para>
-        <variablelist>
-            <varlistentry>
-                <term>"v"</term>
-                <listitem>
-                    <para>para um formato vari&#225;vel (default) </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>"e"</term>
-                <listitem>
-                    <para>para o formato "e" (nota&#231;&#227;o cient&#237;fica) </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-        <para>
-            <literal>long</literal> define o n&#250;mero m&#225;ximo de
-            d&#237;gitos (padr&#227;o 10). <literal>format()</literal> retorna o vetor
-            que indica o fomato corrente: primeiro componente &#233; o tipo do formato
-            (1 se <literal>v</literal> ; 0 se <literal>e</literal> ); o segundo
-            componente &#233; o n&#250;mero de digitos.
-        </para>
-        <para>No "formato vari&#225;vel", entradas de vetores que s&#227;o menores
-            que %eps vezes o valor absoluto m&#225;ximo das entradas era exibido como
-            "0" em vers&#245;es anteriores do Scilab. N&#227;o &#233; mais o caso, a
-            fun&#231;&#227;o de clean pode ser usada para ajustar as entradas
-            negligenci&#225;veis para zeros.
-        </para>
-    </refsection>
-    <refsection>
-        <title>Exemplos</title>
-        <programlisting role="example"><![CDATA[ 
-x=rand(1,5);
-format('v',10);x
-format(20);x
-format('e',10);x
-format(20);x
-
-x=[100 %eps];
-format('e',10);x
-format('v',10);x
-
-format("v")
- ]]></programlisting>
-    </refsection>
-    <refsection>
-        <title>Ver Tamb&#233;m</title>
-        <simplelist type="inline">
-            <member>
-                <link linkend="write">write</link>
-            </member>
-            <member>
-                <link linkend="disp">disp</link>
-            </member>
-            <member>
-                <link linkend="print">print</link>
-            </member>
-        </simplelist>
-    </refsection>
-</refentry>