<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2012 - Scilab Enterprises - Vincent COUVERT
 *
 * 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="example_run" xml:lang="en">
    <refnamediv>
        <refname>example_run</refname>
        <refpurpose>Launch the examples found in help pages.</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            example_run()
            example_run(moduleNames)
            example_run(moduleNames, functionNames)
            example_run(moduleNames, functionNames, language)
            example_run(moduleNames, functionNames, language, testrunOptions, testrunExportToFile)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>moduleNames</term>
                <listitem>
                    <para>
                        a string or a vector of strings: references of the modules to test.
                        Each reference can be either of
                        <itemizedlist>
                            <listitem>
                                the technical name of a Scilab internal module, that is the name
                                of the root directory of the module.
                            </listitem>
                            <listitem>
                                the relative or absolute path of the root directory of the module.
                                This must be used for installed ATOMS modules or other external modules.
                            </listitem>
                        </itemizedlist>
                        By default, all Scilab internal modules are considered, as returned by
                        <link linkend="getmodules">getmodules()</link>.
                    </para>
                    <para>
                        The root directory of each targeted module must have a
                        <literal>./help</literal> subdirectory containing the XML source files of
                        help pages where examples to test are provided, gathered by languages as
                        in the source package of any standard module.
                        Example of the template toolbox_skeleton module:
                        <programlisting role="example">
unix_w("dir /b /s """ + WSCI + "/contrib/toolbox_skeleton/help""")
                      </programlisting>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>functionNames</term>
                <listitem>
                    <para>
                        a string or a string vector: the name(s) of the functions to test.
                        If not given, all help pages of the module(s) will be tested.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>language</term>
                <listitem>
                    <para>a string: the language of the help pages to test. Default value is "en_US".</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>testrunOptions</term>
                <listitem>
                    <para>
                        Used as third input argument for <link linkend="test_run">test_run</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>testrunExportToFile</term>
                <listitem>
                    <para>
                        Used as forth input argument for <link linkend="test_run">test_run</link>.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            This function extracts the examples given in help pages and run them using
            <link linkend="test_run">test_run</link>.
        </para>
        <para>
           <warning>
               When testing examples of any external module, it is mandatory to autoload the module
               at Scilab startup. This can be achieved either by setting the ATOMS module as
               autoloaded, or by loading the module through the user's startup file.
           </warning>
        </para>
    </refsection>
    <refsection>
        <title>Example</title>
        <programlisting role="example"><![CDATA[
if ~isempty(ls("SCI/modules/xml/help/en_US/*.xml")) then // Help XML sources must be available for this example
    example_run("xml")
    example_run("elementary_functions", "insertion")
    example_run("elementary_functions", ["insertion"; "extraction"])
    example_run("elementary_functions", "insertion", "en_US")
end
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="test_run">test_run</link>
            </member>
            <member>
                <link linkend="bench_run">bench_run</link>
            </member>
            <member>
                <link linkend="atomsAutoloadAdd">atomsAutoloadAdd</link>
            </member>
            <member>
                <link linkend="startup">startup</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>5.4.0</revnumber>
                <revremark>Function example_run introduced.</revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
