[doc] misc. patchs & small improvements
[scilab.git] / scilab / modules / gui / help / en_US / getvalue.xml
index 4b84e6f..f9c185a 100644 (file)
@@ -1,12 +1,15 @@
 <?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:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="getvalue">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
+          xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
+          xml:lang="en" xml:id="getvalue">
     <refnamediv>
         <refname>getvalue</refname>
         <refpurpose>xwindow dialog for data acquisition</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
-        <synopsis>[ok,x1,..,x14]=getvalue(desc,labels,typ,ini)</synopsis>
+        <synopsis>[ok, x1,..,x14] = getvalue(desc, labels, typ, ini)</synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Arguments</title>
             <varlistentry>
                 <term>desc</term>
                 <listitem>
-                    <para>column vector of strings, dialog general comment</para>
+                    <para>
+                       column vector of strings, dialog general comment. Any "&lt;" character
+                       must be replaced with "&amp;lt;".
+                    </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>labels</term>
                 <listitem>
                     <para>
-                        n column vector of strings, <literal>labels(i)</literal> is the label of  the ith required value
+                        n column vector of strings, <literal>labels(i)</literal> is the label of
+                        the ith required value.
                     </para>
                 </listitem>
             </varlistentry>
                         <varlistentry>
                             <term>typ_i</term>
                             <listitem>
-                                <para>defines the type of the ith value, may have the following values:</para>
-                                <variablelist>
-                                    <varlistentry>
-                                        <term>"mat"  </term>
-                                        <listitem>
-                                            <para>for constant matrix</para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>"col"  </term>
-                                        <listitem>
-                                            <para>for constant column vector</para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>"row"  </term>
-                                        <listitem>
-                                            <para>for constant row vector</para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>"vec"  </term>
-                                        <listitem>
-                                            <para>for  constant vector</para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>"intvec"  </term>
-                                        <listitem>
-                                            <para>for  constant vector with integer values i.e int(x) == x</para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>"str"  </term>
-                                        <listitem>
-                                            <para>for string</para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>"lis"  </term>
-                                        <listitem>
-                                            <para>for list</para>
-                                        </listitem>
-                                    </varlistentry>
-                                </variablelist>
+                                <para>defines the type of the ith value. By default, inputs are
+                                  interpreted as decimal numbers. Columns of (rows of) values must
+                                  be separated with ";". typ_i may have the following values:</para>
+                                <table>
+                                  <tr><th>"mat"</th><td>matrix</td></tr>
+                                  <tr><th>"col"</th><td>column vector</td></tr>
+                                  <tr><th>"row"</th><td>row vector</td></tr>
+                                  <tr><th>"vec"</th><td>vector (free orientation)</td></tr>
+                                  <tr><th>"intvec"</th><td>scalar, vector or matrix of integers.</td></tr>
+                                  <tr><th>"str"</th><td>scalar, vector or matrix of texts, delimited with ".."</td></tr>
+                                  <tr><th>"lis"</th><td>list: not implemented.</td></tr>
+                                </table>
                             </listitem>
                         </varlistentry>
                         <varlistentry>
                             <term>dim_i</term>
                             <listitem>
-                                <para>defines the size of the ith value it must be an integer or a 2-vector of integer, -1 stands for undefined dimension</para>
+                                <para>
+                                    defines the size of the ith value it must be an integer or
+                                    a 2-vector of integer, -1 stands for undefined dimension.
+                                </para>
                             </listitem>
                         </varlistentry>
                     </variablelist>
@@ -95,7 +72,8 @@
                 <term>ini</term>
                 <listitem>
                     <para>
-                        n column vector of strings, <literal>ini(i)</literal> gives the suggested response for the ith required value
+                        n column vector of strings, <literal>ini(i)</literal> gives the suggested
+                        response for the ith required value
                     </para>
                 </listitem>
             </varlistentry>
                 <term>xi</term>
                 <listitem>
                     <para>
-                        contains the ith value if ok=%t. If left hand side has one more <literal>xi</literal> than required values the last  <literal>xi</literal> contains the vector of answered strings.
+                        contains the ith value if ok=%t. If left hand side has one more
+                        <literal>xi</literal> than required values the last  <literal>xi</literal>
+                        contains the vector of answered strings.
                     </para>
                 </listitem>
             </varlistentry>
             This function encapsulate <literal>x_mdialog</literal> function with error checking,
             evaluation of numerical response, ...
         </para>
-    </refsection>
-    <refsection>
-        <title>Remarks</title>
-        <para>
-            All valid expressions can be used as answers; for matrices  and vectors <literal>getvalues</literal> automatically adds [ ] around the given answer before numeric evaluation.
-        </para>
+        <note>
+          <para>
+              All valid expressions can be used as inputs. For matrices and vectors,
+              <literal>getvalues()</literal> automatically adds [ ] around each group of input
+              before their evaluation.
+          </para>
+        </note>
     </refsection>
     <refsection>
         <title>Examples</title>
         <programlisting role="example"><![CDATA[
-labels=["magnitude";"frequency";"phase    "];
-[ok,mag,Freq,ph]=getvalue("define sine signal",labels,...
-     list("vec",1,"vec",1,"vec",1),["0.85";"10^2";"%pi/3"])
+labels=["magnitude" ; "frequency" ; "phase    "];
+[ok,mag,Freq,ph] = getvalue("define sine signal",labels,...
+     list("vec",1,"vec",1,"vec",1), ["0.85";"10^2";"%pi/3"])
  ]]></programlisting>
     </refsection>
     <refsection role="see also">