New modifications
Farid Belahcene [Fri, 1 Sep 2006 09:23:44 +0000 (09:23 +0000)]
scilab_doc/toolbox_guide/html/toolbox.html

index 3d4e672..a8452c5 100644 (file)
@@ -26,7 +26,7 @@
                        This article describes a standart method to create a Scilab toolbox.<br />
                        The objective is to help the contributors to build a toolbox easily, but also that the users are able to install it with just the execution of a main builder and a main loader script.<br />
                        We show in first time how to structure your toolbox (sub-directories contents, files, ...), in second time how to customize the templates to create the builder(s), the loader(s), and the Scilab help files. To finish we explain how to upload your contribution on the scilab website.<br />
-                       For this article the reference toolbox name is <b>mytoolbox</b>.
+                       For this article the reference toolbox name is <strong>mytoolbox</strong>.
                        (The standarisation below is not mandatory)
                </p>
                
                
                <a name="chap1"></a>
                <h2>1. Toolbox composition</h2>
-               <p>The root directory has the generic name of the toolbox (here <b>mytoolbox</b>), it contains 8 sub-directories:</p> 
+               <p>The root directory has the generic name of the toolbox (here <strong>mytoolbox</strong>), it contains 8 sub-directories:</p> 
                
                <ul style="list-style-type: disc">
-                       <li><b>macros</b>: Scilab macros (i.e the functions written in Scilab code with the extension .sci), buildmacros and loadmacros scripts</li>
-                       <li><b>src</b>: source code (all .c and .f  files), a buildsrc script</li>
-                       <li><b>sci_gateway</b>: interfaces programs, a buildsci_gateway</li>
-                       <li><b>help</b>: english and french help sub-directories named respectively <b>eng</b> and <b>fr</b> which contains all the .xml help files, buildhelp and loadhelp scripts</li>
-                       <li><b>etc</b>: .html, .pdf, .txt, .jpeg, ...</li>
-                       <li><b>unit tests</b>: .tst files (scripts to test your toolbox)</li>
-                       <li><b>demos</b>: different examples to illustrate your toolbox</li>
-                       <li><b>includes</b>: .h files</li>
+                       <li><strong>macros</strong>: Scilab macros (i.e the functions written in Scilab code with the extension .sci), buildmacros and loadmacros scripts</li>
+                       <li><strong>src</strong>: source code (all .c and .f  files), a buildsrc script</li>
+                       <li><strong>sci_gateway</strong>: interfaces programs, a buildsci_gateway</li>
+                       <li><strong>help</strong>: english and french help sub-directories named respectively <strong>eng</strong> and <strong>fr</strong> which contains all the .xml help files, buildhelp and loadhelp scripts</li>
+                       <li><strong>etc</strong>: .html, .pdf, .txt, .jpeg, ...</li>
+                       <li><strong>unit tests</strong>: .tst files (scripts to test your toolbox)</li>
+                       <li><strong>demos</strong>: different examples to illustrate your toolbox</li>
+                       <li><strong>includes</strong>: .h files</li>
                </ul>
                
                and 4 files:
                
                <ul style="list-style-type: disc">
-                       <li><b>readme.txt</b>: toolbox description and installation</li>
-                       <li><b>builder.sce</b>: the main builder</li>
-                       <li><b>loader.sce</b>: the main loader</li>
-                       <li><b>license.txt</b></li>
+                       <li><strong>readme.txt</strong>: toolbox description and installation</li>
+                       <li><strong>builder.sce</strong>: the main builder</li>
+                       <li><strong>loader.sce</strong>: the main loader</li>
+                       <li><strong>license.txt</strong></li>
                </ul>
                
                <a name="chap2"></a>
@@ -91,9 +91,9 @@
                <a name="chap2.1"></a>
                <h3>2.1 The macros directory</h3>
                <p>
-                       By convention the builder and the loader included in the <b>macros</b> directory are named respectively buildmacros.sce and loadmacros.sce<br \>
-                       A <b>macros</b> is a function written in Scilab code (included in .sci file)<br \>
-                       We consider that the <b>macros</b> directory of the toolbox <b>mytoolbox</b> contains just one .sci file, the function <var><strong>foo1</strong></var> (see above script): Given a matrix A, this function returns the vector X the positive components of the A diagonal.
+                       By convention the builder and the loader included in the <strong>macros</strong> directory are named respectively buildmacros.sce and loadmacros.sce<br \>
+                       A <strong>macros</strong> is a function written in Scilab code (included in .sci file)<br \>
+                       We consider that the <strong>macros</strong> directory of the toolbox <strong>mytoolbox</strong> contains just one .sci file, the function <var><strong>foo1</strong></var> (see above script): Given a matrix <strong>A</strong>, this function returns the vector <strong>X</strong> the positives components of the <strong>A</strong> diagonal.
                </p>
                foo1.sci<br />
                
@@ -141,7 +141,7 @@ clear pathB genlib toolboxname</pre>
                <a name="chap2.1.2"></a>
                <h4>2.1.2 The macros loader</h4>
                <p>
-                       The loader (see below script) loads the library lib included in the directory <b>macros</b>. Like the builder, the code is generic, the first step to locate loadmacros.sce script, and the second to load the library (see help <strong><var>load</strong></var> function)
+                       The loader (see below script) loads the library lib included in the directory <strong>macros</strong>. Like the builder, the code is generic, the first step to locate loadmacros.sce script, and the second to load the library (see help <strong><var>load</strong></var> function)
                </p>
                
                loadmacros.sce
@@ -154,16 +154,14 @@ clear pathL</pre>
                
                <a name="chap2.2"></a>
                <h3>2.2 scr and sci_gateway directories</h3>
-               A <b>primitive</b> is a Scilab function which calls a function written in C or fortran code ,using an interface program. So for each Scilab primitive we must to create the corresponding interface program included in the <b>sci_gateway</b> directory. 
+               A <strong>primitive</strong> is a Scilab function which calls a function written in C or fortran code ,using an interface program. So for each Scilab primitive we must to create the corresponding interface program included in the <strong>sci_gateway</strong> directory. 
 
                <a name="chap2.2.1"></a>
                <h4>2.2.1 Interface C/Scilab</h4>
                <p>     
-               When a Scilab primitive is called, the interface program checks that the number, the type and the size of inputs/outputs arguments is correct (using <b>CheckRhs</b> and <b>CheckLhs</b> functions), and gets the rhs arguments address which are in Scilab internal stack to give this information at the interfaced function.<br \><br \>
+               When a Scilab primitive is called, the interface program checks that the number, the type and the size of inputs/outputs arguments is correct (using <strong>CheckRhs</strong> and <strong>CheckLhs</strong> functions), and gets the rhs arguments address which are in Scilab internal stack to give this information at the interfaced function.<br \><br \>
  
-               In this article, the interfaces programs examples(written in C code) are described step by step, they enable to write many interfaces, so it's important to understand them, and to know how to customize them for your toolboxes.<br \><br \>
-               We don't describe all the possibilities of the interface programs, for more explanations see the directory <b>SCI/examples</b>.<br \>
+               We don't describe all the possibilities of the interface programs, for more explanations see the directory <strong>SCI/examples</strong>.<br \>
                </p>
                
                <a name="chap2.2.2"></a>
@@ -174,11 +172,11 @@ clear pathL</pre>
                
                <p>
                        <EM>Example a</EM>: <br /> 
-                       We consider an C routine <b>vectsum</b> which returns the sum of two vectors. I suppose that the name of the corresponding primitive is <b>sumab</b> and the associated interface program name is <b>sci_sumab</b>.
+                       We consider an C routine <strong>vectsum</strong> which returns the sum of two vectors. I suppose that the name of the corresponding primitive is <strong>sumab</strong> and the associated interface program name is <strong>sci_sumab</strong>.
  
                        By convention all the interfaces programs names begin by the "sci_" character strings. 
  
-                       The both following scripts represent the C code of <b>vectsum</b> and <b>sci_sumab</b> when we call the primitive <b>sumab</b> in a Scilab window as follows:<br /><br />
+                       The both following scripts represent the C code of <strong>vectsum</strong> and <strong>sci_sumab</strong> when we call the primitive <strong>sumab</strong> in a Scilab window as follows:<br /><br />
                        <var><strong>--> Y=sumab(A,B )</strong></var> <br /><br />
                </p>
                
@@ -243,7 +241,7 @@ return 0;
                        <var><strong>CheckRhsVar</strong></var> function uses the arguments <strong><var>minrhs</strong></var> 
                        and <var><strong>maxrhs</strong></var> to check that:<br />
                        <var><strong>minrhs <= number of  input arguments <= maxrhs</strong></var><br />
-                       The number of inputs and outputs arguments (respectively 2 and 1) of <b>vectsum</b> are constant, so minrhs=maxrhs=2 and minlhs=maxlhs=1, but for certains functions (see example2)
+                       The number of inputs and outputs arguments (respectively 2 and 1) of <strong>vectsum</strong> are constant, so minrhs=maxrhs=2 and minlhs=maxlhs=1, but for certains functions (see example2)
                        they can be variable, in this case the variables <var><strong>minrhs/minlhs</strong></var> and <var><strong>maxrhs/maxlhs</strong>
                        </var> are different.<br /> We can use directly the defined variables <var><strong>Rhs</strong></var>(=number of inputs) and 
                        <var><strong>Lhs</strong></var>(=number of outputs) instead of the functions <var><strong>CheckRhsVar</strong></var>  and  
@@ -251,61 +249,62 @@ return 0;
                        
                        <br />
                        
-                       <EM>Step 2</EM>:  call <b><i>GetRhsVar(1,"d",&m1,&n1,&l1)</b></i> instruction<br />
-                       <b><i>GetRhsVar</b></i> function checks that the type of inputs arguments of <b>sumab</b> are correct, and gets their size and their address in the Scilab stack.<br />
-                       We describe below all arguments of <b><i>GetRhsVar</b></i> function:<br />
+                       <EM>Step 2</EM>:  call <strong><i>GetRhsVar(1,"d",&m1,&n1,&l1)</strong></i> instruction<br />
+                       <strong><i>GetRhsVar</strong></i> function checks that the type of inputs arguments of <strong>sumab</strong> are correct, and gets their size and their address in the Scilab stack.<br />
+                       We describe below all arguments of <strong><i>GetRhsVar</strong></i> function:<br />
 
                        <ul style="list-style-type: disc">
-                       <li><b><i>1</b></i> : corresponds to the position of the first input argument of sumab, i.e A, (2 corresponds to B,...)</li>
-                       <li><b><i>m1 </b></i>: gets the rows number of A (m2 for B)</li>
-                       <li><b><i>n1 </b></i>: gets the columns number of A (n2 for B)</li>
-                       <li><b><i>l1 </b></i>: gets the address of A in the Scilab stack (l2 for B)</li>
+                       <li><strong><i>1</strong></i> : corresponds to the position on the stack of the first input argument of <strong>sumab</strong>, i.e A, (2 corresponds to B,...)</li>
+                       <li><strong><i>m1 </strong></i>: gets the rows number of A (m2 for B)</li>
+                       <li><strong><i>n1 </strong></i>: gets the columns number of A (n2 for B)</li>
+                       <li><strong><i>l1 </strong></i>: gets the address of A in the Scilab stack (l2 for B)</li>
                        </ul>
                        <br />
                        
-                       <EM>Step 4</EM>: call <b><i>CreateVar(3,"d",&m2,&n2,&l3)</b></i> instruction<br /> 
-                       <b><i>CreateVar</b></i> function creates in the Stack at the 3th position a variable which corresponds to the output argument of <b>vectsum</b> (here Y)<br />
+                       <EM>Step 4</EM>: call <strong><i>CreateVar(3,"d",&m2,&n2,&l3)</strong></i> instruction<br /> 
+                       <strong><i>CreateVar</strong></i> function creates in the Stack at the 3th position a variable which corresponds to the output argument of <strong>vectsum</strong> (here Y)
+                       <br />
                        <ul style="list-style-type: disc">
-                       <li><b><i>3 </b></i>: position of the created variable in the stack. This position (here 3) must follows the position of the last input argument (here2) of <b>vectsum</b> </li>
-                       <li><b><i>"d"</b></i>: sets the type of the created variable, here double </li>
-                       <li><b><i>m2</b></i>: sets the rows number of the created variable(here equal to the rows number of the second input argument B: m2)</li>
-                       <li><b><i>n2</b></i>: sets the columns number of the first created variable (here equal to the columns number of the second input argument B: n2)</li>
-                       <li><b><i>l3</b></i>: gets the address of the created variable in the Scilab stack </li>
+                       <li><strong><i>3 </strong></i>: position of the created variable in the stack. This position (here 3) must follows the position of the last input argument (here2) of <strong>sumab</strong> </li>
+                       <li><strong><i>"d"</strong></i>: sets the type of the created variable, here double </li>
+                       <li><strong><i>m2</strong></i>: sets the rows number of the created variable(here equal to the rows number of the second input argument B: m2)</li>
+                       <li><strong><i>n2</strong></i>: sets the columns number of the first created variable (here equal to the columns number of the second input argument B: n2)</li>
+                       <li><strong><i>l3</strong></i>: gets the address of the created variable in the Scilab stack </li>
                        </ul>
-                       
                        <br />
                        
-                       <EM>Step 5</EM>: call <b>vectsum(n,stk(l1),stk(l2),stk(l3))</b> instruction<br /> 
-                       The C function <b>vectsum</b> returns in stk(l3) the sum of stk(l1) and stk(l2) (i.e a and b)<br />
-                       
+                       <EM>Step 5</EM>: call <strong>vectsum(n,stk(l1),stk(l2),stk(l3))</strong> instruction<br /> 
+                       The C function <strong>vectsum</strong> returns in stk(l3) the sum of stk(l1) and stk(l2) (i.e a and b)
+                       <br />
+                       <br />
                        
-                       <EM>Step 6</EM>: call <b><i>LhsVar(1) = 3</b></i> instruction<br />
-                       The first output argument (here Y) of sumab takes the value of the variable placed in the 3th position (i.e stk(l3))<br />
+                       <EM>Step 6</EM>: call <strong><i>LhsVar(1) = 3</strong></i> instruction<br />
+                       The first output argument (here Y) of sumab takes the value of the variable placed in the 3th position on the stack (i.e stk(l3))<br />
                        <br />
                        <br />
                        
                        <EM>Example b</EM>:<br />
-                               In the second example we describe the interface program named <b>sci_fun</b> of the Scilab primitive named <b><i>fun</b></i>.<br />
-                               This function call the C routines <b>fun1</b> and <b>fun2</b> and has 2 syntaxes which are:
+                               In the second example we describe the interface program named <strong>sci_fun</strong> of the Scilab primitive named <strong><i>fun</strong></i>.<br />
+                               This function call the C routines <strong>fun1</strong> and <strong>fun2</strong> and has 2 syntaxes which are:
                        <br />
                        <br />
-                       the first syntax is:</b></i><br />
-                       <b><i>--> [X, Y ]=fun(A);</b></i><br />
-                       Given a vector <b><i>A</b></i>, this function returns the positive components of <b><i>A</b></i> in a vector <b><i>X</b></i> and the sum of its positives components in a scalar <b><i>Y</b></i>.<br />
+                       First syntax:</strong></i><br />
+                       <strong><i>--> [X, Y ]=fun(A);</strong></i><br />
+                       Given a vector <strong><i>A</strong></i>, this function returns the positives components of <strong><i>A</strong></i> in a vector <strong><i>X</strong></i> and the sum of its positives components in a scalar <strong><i>Y</strong></i>.<br />
                        
                        <br />
-                       the second syntax is:<br />
-                       <b><i>--> [X ]=fun(A);</b></i><br />
-                       Given a vector <b><i>A</b></i>, this function returns the positives components of <b><i>A</b></i> in a vector <b><i>X</b></i>.<br />
+                       Second syntax:<br />
+                       <strong><i>--> [X ]=fun(A);</strong></i><br />
+                       Given a vector <strong><i>A</strong></i>, this function returns the positives components of <strong><i>A</strong></i> in a vector <strong><i>X</strong></i>.<br />
                </p>
                <p> 
                 The number of outputs arguments (i.e Lhs value) is variable: for the first syntax Lhs=1, for the second syntax Lhs=2. The number of intputs arguments (i.e Rhs value) is constant: Rhs=1 (first and second syntax).<br />
-                So the interface program must check that: <b>1<=Lhs<=2</b> (set <b>minlhs=1</b>, <b>maxlhs=2</b>)  and <b>Rhs=1</b> (set <b>minrhs=maxrhs=1</b>)<br />
+                So the interface program must check that: <strong>1<=Lhs<=2</strong> (set <strong>minlhs=1</strong>, <strong>maxlhs=2</strong>)  and <strong>Rhs=1</strong> (set <strong>minrhs=maxrhs=1</strong>)<br />
                </p>
                
                                
                <br />
-               fun1.c (the C function <b><i>fun1</b></i> creates the vector <b><i>X</b></i> and the scalar <b><i>Y</b></i>. It calls the C function <b><i>fun2</b></i> to get the needed size of <b><i>X</b></i> in order to allocate the corresponding memory place)
+               fun1.c (the C function <strong><i>fun1</strong></i> creates the vector <strong><i>X</strong></i> and the scalar <strong><i>Y</strong></i>. It calls the C function <strong><i>fun2</strong></i> to get the needed size of <strong><i>X</strong></i> in order to allocate the corresponding memory place)
                <pre class="entete">
 extern void  fun2(double *, int, int *);
 
@@ -399,12 +398,12 @@ int sci_fun(char *fname)
                
                <a name="chap2.2.3"></a>
                <h4>2.2.3 Primitives builder</h4>
-               <p>Now the <b>src</b> and the <b>sci_gateway</b> directories contain all the necessary files (<b><i>fun1.c</b></i>, <b><i>fun2.c</b></i>, <b><i>sci_fun.c</b></i>, <b><i>vectsum.c</b></i>, <b><i>sci_sumab.c</b></i>) to create the builder (see below template) for the primitives <i><b>fun</i></b> and <i><b>sumab</i></b>.
+               <p>Now the <strong>src</strong> and the <strong>sci_gateway</strong> directories contain all the necessary files (<strong><i>fun1.c</strong></i>, <strong><i>fun2.c</strong></i>, <strong><i>sci_fun.c</strong></i>, <strong><i>vectsum.c</strong></i>, <strong><i>sci_sumab.c</strong></i>) to create the builder (see below template) for the primitives <i><strong>fun</i></strong> and <i><strong>sumab</i></strong>.
                <br />
                We need to write two builders:<br /> 
-               One the hand, in the <b>src</b> directory, this builder (named <b>buildersrc</b>) creates a shared libraries (see help <i><b>ilib_for_link</b></i> function) corresponding to the C functions.<br />
-                And the other hand, in the <b>interface</b> directory, this builder (named <b>buildsci_gateway</b>) creates the new shared libraries to link the compiled C or Fortran new Scilab interface routines (thanks to src libraries), and generates a loader (see help <i><b>ilib_build</b></i> function). 
-               This loader file calls the addinter function to load dynamically the shared library (see help <i><b>addinter</b></i> function)</p>
+               One the hand, in the <strong>src</strong> directory, this builder (named <strong>buildersrc</strong>) creates a shared libraries (see help <i><strong>ilib_for_link</strong></i> function) corresponding to the C functions.<br />
+                And the other hand, in the <strong>interface</strong> directory, this builder (named <strong>buildsci_gateway</strong>) creates the new shared libraries to link the compiled C or Fortran new Scilab interface routines (thanks to src libraries), and generates a loader (see help <i><strong>ilib_build</strong></i> function). 
+               This loader file calls the addinter function to load dynamically the shared library (see help <i><strong>addinter</strong></i> function)</p>
                
                buildsrc.sce
                <pre class="entete">
@@ -424,13 +423,13 @@ ilib_for_link('mytoolboxsrc',['fun1.o' 'fun2.o','vectsum.o'],[],"c")</pre>
                ilib_build(ilib_name,table,files,libs)</pre>    
                
                <br />
-               The <i><b>ilib_name</b></i> value is the interface library name, the vector <i><b>files</b></i> contains all the object interface files,  
-               the vector <i><b>libs</b></i> contains the libraries needed for linking (here the library included in the src directory), 
-               the variable <i><b>table</b></i> contains the primitives names (first column) and the corresponding interfaces programs names (second column)
+               The <i><strong>ilib_name</strong></i> value is the interface library name, the vector <i><strong>files</strong></i> contains all the object interface files,  
+               the vector <i><strong>libs</strong></i> contains the libraries needed for linking (here the library included in the src directory), 
+               the variable <i><strong>table</strong></i> contains the primitives names (first column) and the corresponding interfaces programs names (second column)
                
                <a name="chap2.3"></a>
                <h3>2.3 The  help directory</h3>
-               <p>This directory included <b>.xml</b> files, a <b>buildhelp</b> and a <b>loadhelp</b> scripts.<br />
+               <p>This directory included <strong>.xml</strong> files, a <strong>buildhelp</strong> and a <strong>loadhelp</strong> scripts.<br />
                                On Unix/Linux systems: to create the manual pages you need 'sabcmd', an XML parser which is part of the Sablotron package.<br /> 
                                here the link to download it:<br />
                                <A href="http://www.scilab.org/download/index_download.php?page=related_tool.html">  http://www.scilab.org/download/index_download.php?page=related_tool.html</A><br />
@@ -439,7 +438,7 @@ ilib_for_link('mytoolboxsrc',['fun1.o' 'fun2.o','vectsum.o'],[],"c")</pre>
                <a name="chap2.3.1"></a>
                <h4>2.3.1 Creation of .xml files</h4>
                <p> 
-               Here a template which shows you how to write the .xml help files. You should just fill the different items(Langage, title, type, date, short description, ...) for the .xml files of your functions (here <b><i>foo1.xml</i></b>, <b><i>fun.xml</i></b>, <b><i>sumab.xml</i></b>) and put them in the <b>help</b> directory.
+               Here a template which shows you how to write the .xml help files. You should just fill the different items(Langage, title, type, date, short description, ...) for the .xml files of your functions (here <strong><i>foo1.xml</i></strong>, <strong><i>fun.xml</i></strong>, <strong><i>sumab.xml</i></strong>) and put them in the <strong>help</strong> directory.
                </p>
                
                <pre class="entete">
@@ -518,7 +517,7 @@ Add here the used function name and  references
                
                <a name="chap2.3.2"></a>
                <h4>2.3.2 The help builder</h4>
-               <p>The builder (named buildhelp) creates a <b>whatis.htm</b> file which is a short description of the functions, and translates the xml files to html (see help <b><i>xmltohtml</b></i> function)
+               <p>The builder (named buildhelp) creates a <strong>whatis.htm</strong> file which is a short description of the functions, and translates the xml files to html (see help <strong><i>xmltohtml</strong></i> function)
                </p>
                
                <br />
@@ -605,7 +604,7 @@ clear mainpathL</pre>
                        <li>Read the instructions about how to contribute , see the link: 
                                <A href="http://www.scilab.org/contrib/index_contrib.php?page=howto.html">http://www.scilab.org/contrib/index_contrib.php?page=howto.html </A></li>
                                <li>Archive and Compress your toolbox: </li>
-                               <li>Complete the submission form document and add your package (here <b>mytoolbox.tar.gz</b> and <b>mytoolbox.zip</b>), 
+                               <li>Complete the submission form document and add your package (here <strong>mytoolbox.tar.gz</strong> and <strong>mytoolbox.zip</strong>), 
                                        see the link: <A href="http://www.scilab.org/contrib/index_contrib.php?page=upload.html">http://www.scilab.fr/contrib/index_contrib.php?page=upload.html </A></li>
                </ul>
        </body>