help: scilab|scilex page fixed & improved
[scilab.git] / scilab / modules / core / help / en_US / scilab.xml
index 4bf76a5..3046f7f 100644 (file)
@@ -1,33 +1,89 @@
 <?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: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="scilab" 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="scilab" xml:lang="en">
+    <refnamediv xml:id="wscilex">
+    </refnamediv>
+    <refnamediv xml:id="scilex">
+    </refnamediv>
     <refnamediv>
-        <refname>scilab</refname>
-        <refpurpose>Main script to start Scilab and miscellaneous
-            tools (GNU/Linux, Unix and Mac OS X)
+        <refname>scilex | scilab</refname>
+        <refpurpose>runs Scilab in interactive or batch mode with command line options
         </refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
-        <synopsis>scilab &lt;Options&gt;
-            scilab-adv-cli &lt;Options&gt;
-            scilab-cli &lt;Options&gt;
+        <synopsis>
+#      MS Windows          |  # Linux / Unix / Mac OS X
+wscilex     &lt;Options&gt;     |  scilab         &lt;Options&gt;
+wscilex -nw &lt;Options&gt; |  scilab-adv-cli &lt;Options&gt;
+scilex      &lt;Options&gt;      |  scilab-cli     &lt;Options&gt;
         </synopsis>
     </refsynopsisdiv>
     <refsection role="arguments">
-        <title>Arguments</title>
+        <title>Options</title>
         <variablelist>
             <varlistentry>
-                <term>-args Arguments</term>
+                <term>-args arg#1 arg#2 ..</term>
                 <listitem>
-                    <para>If this option is present, arguments are passed to Scilab.
-                        They can then be got by <link linkend="sciargs">sciargs</link>
-                        function. For multi arguments passing use a quoted, blank separated
-                        sequence of words like: <literal>scilab -args 'foo1
-                            foo2'
-                        </literal>
-                        .Without this option, unknown arguments will not
-                        be accepted.
+                    <para>
+                        This option allows to send some data to the Scilab session:
+                        <itemizedlist>
+                            <listitem>Consecutive data are separated by one or several spaces.
+                            </listitem>
+                            <listitem>An expression between double-quotes is a single data.
+                            </listitem>
+                            <listitem>To include a double-quote in a data, write <literal>\"</literal> instead of <literal>"</literal>.
+                            </listitem>
+                            <listitem>The single quote <literal>'</literal> is a regular character. It has no special meaning.
+                            </listitem>
+                        </itemizedlist>
                     </para>
+                    <para>
+                      Inside the opened session, these data can be retrieved as separated strings with <link linkend="sciargs">sciargs()</link>.
+                     </para>
+                     <para>
+                      Example:
+                        <screen><![CDATA[C:\Users\Me> scilex -nb -args "Hello \"%USERNAME%\"" 1.2345 \"%cd%\"]]></screen>
+                        <programlisting><![CDATA[
+// Inside the opened session:
+a = sciargs()
+i = find(a=="-args")
+a(i+1)
+evstr(a(i+2))*2
+"This session has been launched from " + a(i+3)
+                        ]]>
+                        </programlisting>
+                        <screen><![CDATA[
+--> // Inside the opened session:
+--> a = sciargs()
+ a  =
+!c:\SCIdir\bin\scilex  -nw  -nb  -noatomsautoload  -args  Hello "John"  1.2345  "C:\Users\Me" !
+
+--> i = find(a=="-args")
+ i  =
+    5.
+
+--> a(i+1)
+ ans  =
+ Hello "John"
+
+--> evstr(a(i+2))*2
+ ans  =
+    2.469
+
+--> "This session has been launched from " + a(i+3)
+ ans  =
+ This session has been launched from "C:\Users\Me"
+
+-->
+]]></screen>
+                     </para>
+                     <para>
+                     <note>Using <literal>-args</literal> as the <emphasis role="italic">last</emphasis> command line option is safer.
+                     </note>
+                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>-debug</term>
+                <term>-e Instructions</term>
                 <listitem>
-                    <para>Start Scilab under the debugger gdb (Unix/Linux/Mac OS X only).</para>
                     <para>
-                        Define the variable <literal>SCILAB_GDB_OPT</literal> to add custom options to
-                        gdb.
-                    </para>
-                    <para>Advice: use this option on a Scilab source tree.</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>-debug-kdbg</term>
-                <listitem>
-                    <para>Start Scilab under kdbg (Unix/Linux/Mac OS X only).</para>
-                    <para>Advice: use this option on a Scilab source tree.</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>-profiling</term>
-                <listitem>
-                    <para>Start Scilab under valgrind (Unix/Linux/Mac OS X only).</para>
-                    <para>Define the variable SCILAB_VALGRIND_OPT to add custom options
-                        to valgrind (and override the existing valgrind options).
-                    </para>
-                    <para>Advice: use this option on a Scilab source tree.</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>-profiling-visu</term>
-                <listitem>
-                    <para>Start Scilab under callgrind (Unix/Linux/Mac OS X only).</para>
-                    <para>Define the variable SCILAB_VALGRIND_OPT to add custom options
-                        to callgrind (and override the existing callgrind options).
+                        At the end of the whole session startup, this option
+                        <itemizedlist>
+                            <listitem>
+                                <para>sets the current working directory to the shell directory from which Scilab has been launched. Please see the example given here-below for the <literal>-f</literal> option. Then,
+                                </para>
+                            </listitem>
+                            <listitem>
+                                <para>executes Scilab <literal>Instructions</literal> provided in a string. Example:
+                                    <screen><![CDATA[ scilab-cli -e  "disp(\"Hello\"); a=%pi+%i; disp(exp(a)); exit;" -nb]]></screen>
+                                </para>
+                            </listitem>
+                        </itemizedlist>
                     </para>
-                    <para>Advice: use this option on a Scilab source tree.</para>
+                    <warning>
+                        <literal>-e</literal> and <literal>-f</literal> options can't be used together.
+                    </warning>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>-electric-fence</term>
-                <listitem>
-                    <para>Start Scilab with the Electric Fence (Unix/Linux/Mac OS X only).</para>
-                    <para>Advice: use this option on a Scilab source tree.</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>-e Instruction</term>
+                <term>-f file</term>
                 <listitem>
-                    <para>If this option is present then Scilab instruction
-                        <literal>Instruction</literal> is executed first (just after startup
-                        file execution) into Scilab. <literal>-e</literal> and
-                        <literal>-f</literal> options are mutually exclusive.
-                    </para>
                     <para>
-                        Note that several instructions can be used in with <literal>-e</literal>.
+                        If this option is used, then at the beginning of the Scilab session, after the execution of the scilab and user startup files, and after the setting of user Preferences -- including the working directory ones --,
+                        <itemizedlist>
+                            <listitem>
+                                <para>
+                                    the current Scilab working directory is set to the shell directory from which Scilab has been launched. For instance,
+                                    <screen><![CDATA[ D:\users\me\scilab\dev> C:\scilab-5.5.2\bin\scilex -f ..\test.sce]]></screen>
+                                    will do a <literal>cd("D:\users\me\scilab\dev")</literal>.
+                                </para>
+                            </listitem>
+                            <listitem>
+                                <para>
+                                    the Scilab script <literal>file</literal> is executed. If a relative path is used (default <literal>.\</literal>, or like <literal>..\</literal> in the sample here-above), it refers to the new Scilab working directory.
+                                </para>
+                            </listitem>
+                        </itemizedlist>
                     </para>
-                    <programlisting role="no-scilab-exec">scilab-cli -e  "a=1+%i; aPlusPi=a+%pi; disp(aPlusPi);exit;" -nb</programlisting>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>-f file</term>
-                <listitem>
-                    <para>If this option is present then Scilab script
-                        <literal>file</literal> is executed first (just after startup file
-                        execution) into Scilab. <literal>-e</literal> and
-                        <literal>-f</literal> options are mutually exclusive.
+                    <para>
+                        A file with .xcos extension will be opened by Xcos.
                     </para>
-                    <para>A file with .xcos extension will be opened by Xcos.</para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                     <para>If this option is present it fixes the user language.
                         <emphasis>lang</emphasis> can be: <emphasis>ca_ES de_DE en_US es_ES
                             fr_FR ja_JP pt_BR ru_RU zh_CN zh_TW
-                        </emphasis>
-                        (from Scilab
-                        5.2).
+                        </emphasis> (from Scilab 5.2).
                     </para>
                     <para>
                         Other possible <literal>lang</literal> values are
                         <literal>'fr'</literal> for french and <literal>'en'</literal> for
                         English for compatibility reasons. The default language is English.
-                        This default value is fixed the <literal>scilab.start</literal>
-                        file.
+                        This default value is fixed the <literal>scilab.start</literal> file.
                     </para>
                     <para>On some systems, locales must be compiled to render correctly
                         UTF-8 fonts.
                     </para>
                     <para>Scilab can be also called the following way:</para>
-                    <programlisting role="no-scilab-exec">LANG=ja_JP scilab
-                        # equivalent to
-                        scilab -l ja_JP
-                    </programlisting>
+                    <screen><![CDATA[ LANG=ja_JP scilab
+ # equivalent to
+ scilab -l ja_JP
+]]></screen>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>-nb</term>
                 <listitem>
-                    <para>If this option is present then the Scilab loading message not displayed.
+                    <para>"no banner": Cancels the display of the Scilab's loading message.
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>-ns</term>
                 <listitem>
-                    <para>If this option is present the startup file
-                        <literal>SCI/etc/scilab.start</literal> and the user startup files
+                    <para>"No Startup files": Cancels the execution of the main startup file
+                        <literal>SCI/etc/scilab.start</literal> and of the user startup files
                         <literal>SCIHOME/.scilab</literal>,
-                        <literal>SCIHOME/scilab.ini</literal> are not executed.
+                        <literal>SCIHOME/scilab.ini</literal>.
                     </para>
                     <para>This option will disable many features in Scilab (Only use if
                         you know what you are doing).
             <varlistentry>
                 <term>-nouserstartup</term>
                 <listitem>
-                    <para>If this option is present the user startup files
-                        <literal>SCIHOME/.scilab</literal>,
-                        <literal>SCIHOME/scilab.ini</literal> are not executed.
+                    <para>Cancels the execution of the user startup files
+                        <literal>SCIHOME/.scilab</literal> and
+                        <literal>SCIHOME/scilab.ini</literal>.
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>-noatomsautoload</term>
                 <listitem>
-                    <para>If this option is present the ATOMS modules previously installed are not loaded for this session.</para>
+                    <para>Cancels the autoloading of installed ATOMS modules at startup.</para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                     <para>If this option is present, Scilab is started as command line
                         with advanced features still available (graphics, export, xcos, scinotes, help browser, ...).
                     </para>
-                    <para>
-                        This option may be used with <literal>-f</literal> or <literal>-e</literal> options.
-                    </para>
                     <para>From Scilab 5.2:</para>
                     <itemizedlist>
                         <listitem>
-                            <para>Scilab distribution also provides a dedicated binary which
-                                is doing the same as <literal>-nw</literal>: <literal>scilab-adv-cli</literal> (Scilab Advanced
-                                Command Line Interpreter).
+                            <para>pipes are enabled for all operating systems (see the
+                                examples for further details).
                             </para>
                         </listitem>
                         <listitem>
-                            <para>pipes are enabled for all operating systems (see the
-                                examples for further details).
+                            <para>Scilab distribution also provides a dedicated binary which
+                                is doing the same as <literal>-nw</literal>:
+                                <literal>scilab-adv-cli</literal> (Scilab Advanced Command Line Interpreter).
                             </para>
                         </listitem>
                     </itemizedlist>
             <varlistentry>
                 <term>-nwni / -nogui</term>
                 <listitem>
+                    <important>
+                        This mode prevents loading the Java Virtual Machine.
+                        It starts faster and uses less memory.
+                    </important>
                     <para>If this option is present, Scilab is started as command line
-                        without advanced features (graphics, export, xcos, scinotes, help browser, ...).
-                    </para>
-                    <para>
-                        This option may be used with <literal>-f</literal> or <literal>-e</literal> options.
+                        without advanced features (graphics, export, xcos, scinotes,
+                        help browser, Java module,...).
                     </para>
-                    <para>From Scilab 5.2:</para>
+                    <para>Since Scilab 5.2:</para>
                     <itemizedlist>
                         <listitem>
-                            <para>Scilab distribution also provides a dedicated binary which
-                                is doing the same as <literal>-nwni</literal>: <literal>scilab-cli</literal> (Scilab Command Line Interpreter).
+                            <para>pipes are enabled for all operating systems (see the
+                                examples for further details).
                             </para>
                         </listitem>
                     </itemizedlist>
                     <itemizedlist>
                         <listitem>
-                            <para>pipes are enabled for all operating systems (see the
-                                examples for further details).
+                            <para>Scilab distribution also provides a dedicated binary which
+                                is doing the same as <literal>-nwni</literal>:
+                                <literal>scilab-cli</literal> (Scilab Command Line Interpreter).
                             </para>
                         </listitem>
                     </itemizedlist>
-                    <para>This mode does not load the Java Virtual Machine (faster to
-                        start and uses less memory).
-                    </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>--texmacs</term>
                 <listitem>
-                    <para>This option is reserved for TeXMacs.</para>
-                    <para>
-                        Please install ATOMS module: <programlisting role="">atomsInstall('texmacs')</programlisting>
+                    <para>This option is reserved for the external TeXMacs module.
+                        This one can be priorly installed with <code>atomsInstall('texmacs')</code>.
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>-version</term>
                 <listitem>
-                    <para>This option prints product version and exits.</para>
+                    <para>displays the Scilab's version (before the main Scilab's startup).</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection role="arguments">
+        <title>Additional options for Unix/Linux and Mac OS X</title>
+        <para>Advice: use theses options on a Scilab source tree.</para>
+        <variablelist>
+            <varlistentry>
+                <term>-debug</term>
+                <listitem>
+                    <para>Start Scilab under the debugger gdb.</para>
+                    <para>
+                        The variable <literal>SCILAB_GDB_OPT</literal> may be set to add custom options to gdb.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-debug-kdbg</term>
+                <listitem>
+                    <para>Start Scilab under kdbg.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-profiling</term>
+                <listitem>
+                    <para>Start Scilab under valgrind.</para>
+                    <para>The variable SCILAB_VALGRIND_OPT may be set to add custom options
+                        to valgrind (and override the existing valgrind options).
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-profiling-visu</term>
+                <listitem>
+                    <para>Start Scilab under callgrind.</para>
+                    <para>The variable SCILAB_VALGRIND_OPT may be set to add custom options
+                        to callgrind (and override the existing callgrind options).
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-electric-fence</term>
+                <listitem>
+                    <para>Start Scilab with the Electric Fence.</para>
                 </listitem>
             </varlistentry>
         </variablelist>
     </refsection>
     <refsection role="description">
-        <title>Description of environment variables</title>
+        <title>Environment variables</title>
         <variablelist>
             <varlistentry>
                 <term>SCIVERBOSE</term>
     </refsection>
     <refsection role="description">
         <title>Java Virtual Machine options</title>
+        <warning>
+            The options described here-below are useless and are cancelled if the option <literal>-nwni</literal> is used.
+        </warning>
         <para>Starting from Scilab 5.0, the graphical user interface (GUI) and the
             build documentation are based on Java features. In some cases, it can be
             important to edit the JVM options (Java Virtual Machine).
     </refsection>
     <refsection role="examples">
         <title>Examples</title>
-        <programlisting role="no-scilab-exec"><![CDATA[
+        <screen><![CDATA[
 # Let's start Scilab in profiling mode without attaching a gdb once a SIGSEGV is met.
 # We are under Bash shell
 export SCILAB_VALGRIND_OPT="--db-attach=no --log-file=myfile.txt"
@@ -367,8 +441,9 @@ echo "handle SIGSEGV nostop" &> debug.txt
 # We are under Bash shell
 export SCILAB_GDB_OPT="--command=debug.txt"
 # Start Scilab in debug mode
-scilab -debug]]></programlisting>
-        <programlisting role="no-scilab-exec"><![CDATA[
+scilab -debug ]]></screen>
+        <para></para>
+        <screen><![CDATA[
 # Under GNU/Linux, Mac OS X or Unix:
 $ echo "disp(%pi)"|scilab-cli
 or
@@ -382,16 +457,31 @@ $ scilab -nw -e "help()"
 
 # Scilab can be used for scripting aspects:
 echo "if 1<>2 then exit(99) end"|scilab-cli
-echo $? ]]></programlisting>
+echo $? ]]></screen>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
         <simplelist type="inline">
             <member>
-                <link linkend="exit">exit</link>
+                <link linkend="startup">startup</link>
             </member>
             <member>
-                <link linkend="startup">startup</link>
+                <link linkend="sciargs">sciargs</link>
+            </member>
+            <member>
+                <link linkend="getpid">getpid</link>
+            </member>
+            <member>
+                <link linkend="getenv">getenv</link>
+            </member>
+            <member>
+                <link linkend="getenv">getversion</link>
+            </member>
+            <member>
+                <link linkend="consolebox">consolebox</link>
+            </member>
+            <member>
+                <link linkend="exit">exit</link>
             </member>
         </simplelist>
     </refsection>