New modifications
Farid Belahcene [Thu, 31 Aug 2006 13:54:44 +0000 (13:54 +0000)]
scilab_doc/toolbox_guide/html/toolbox.html

index dd228ce..3d4e672 100644 (file)
        </head>
        
        <body>
-               <h1 center>Guide for the toolboxes contribution (general application)<br /><hr></h1>
+               <h1 center>Guide for the toolboxes contributions (general application)<br /><hr></h1>
                <p>
                        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>toolbox_example</b>.
-                       (The above standarisation is not mandatory)
+                       For this article the reference toolbox name is <b>mytoolbox</b>.
+                       (The standarisation below is not mandatory)
                </p>
                
                <h2>Table of content</h2>
                                </ul>
                                <a href="#chap2.2">2.2. the interface and src directories</a><br />
                                <ul>
-                                       <a href="#chap2.2.1">2.2.1. interface examples</a><br />
-                                       <a href="#chap2.2.2">2.2.2. Primitives builder</a><br />
+                                       <a href="#chap2.2.1">2.2.1. Interface C/Scilab</a><br />
+                                       <a href="#chap2.2.2">2.2.2. Examples of interfaces programs</a><br />
+                                       <a href="#chap2.2.3">2.2.3. Primitives builder</a><br />
                                </ul>
-                                       <a href="#chap2.3">2.3. The man directory</a><br />
+                                       <a href="#chap2.3">2.3. The help directory</a><br />
                                <ul>
                                        <a href="#chap2.3.1">2.3.1. Creation of .xml files</a><br />
-                                       <a href="#chap2.3.2">2.3.2. The man builder</a><br />
-                                       <a href="#chap2.3.3">2.3.3. The man loader</a><br />
+                                       <a href="#chap2.3.2">2.3.2. The help builder</a><br />
+                                       <a href="#chap2.3.3">2.3.3. The help loader</a><br />
                                </ul>
                        </ul>
                        <a href="#chap3">3. The main builder and loader</a><br />
                
                <a name="chap1"></a>
                <h2>1. Toolbox composition</h2>
-               <p>The root directory has the generic name of the toolbox (here <b>toolbox_example</b>), it contains 7 sub-directories:</p> 
+               <p>The root directory has the generic name of the toolbox (here <b>mytoolbox</b>), it contains 8 sub-directories:</p> 
                
                <ul style="list-style-type: disc">
-                       <li><b>macros</b>: Scilab macros (all .sci files), the builder and loader scripts</li>
-                       <li><b>src</b>: code source (all .c and .f  files), a builder script</li>
-                       <li><b>interface</b>: interface programs, a builder</li>
-                       <li><b>man</b>: all .xml files, the builder and loader scripts</li>
-                       <li><b>doc</b>: .html, .pdf, .txt, .jpeg, ...</li>
-                       <li><b>tests</b>: scripts to test your toolbox</li>
+                       <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>
                </ul>
                
-               and 3 files:
+               and 4 files:
                
                <ul style="list-style-type: disc">
-                       <li><b>README</b>: toolbox description and installation</li>
-                       <li><b>builder.sce</b></li>
-                       <li><b>loader.sce</b></li>
+                       <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>
                </ul>
                
                <a name="chap2"></a>
                <h2>2. Sub-builders and sub-loaders</h2>
                        <p>
-                               The main builder and main loader scripts launch respectively the sub-builders and sub-loaders included in the sub-directories (macros, src, man, ...), to generate and to load the necessary libraries and the Scilab help files.
+                               The main builder and main loader scripts launch respectively the sub-builders and sub-loaders included in the sub-directories (macros, src, help, ...), to generate and to load the necessary libraries and the Scilab help files.
                        </p>
                
                <a name="chap2.1"></a>
                <h3>2.1 The macros directory</h3>
                <p>
-                       This directory included macros Scilab functions, a builder and a loader script.<br />
-                       A  macros is a function written in Scilab code (included in .sci file)<br />
-                       We consider that the macros directory of the toolbox <b>toolbox_example</b> contains just one .sci file: the function <var><strong>foo1</strong></var> (see above script). Given a matrix A, this function returns the positive components of the A diagonal.
+                       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.
                </p>
                foo1.sci<br />
                
@@ -117,64 +120,71 @@ endfunction</pre>
                <a name="chap2.1.1"></a>
                <h4>2.1.1 The macros builder</h4>
                <p>
-                       The builder (see above script) creates a library variable, (named here: toolbox_examplelib= toolbox name +'lib')
+                       The builder (see below script) creates a library variable, (named here: mytoolboxlib= toolbox name +'lib')
                        from functions .sci  include in the directory macros, and saves it in the file lib.
-                       The builder code is generic, it's done in 2 steps, the first to locate macrosbuilder.sce script 
+                       The builder code is generic, it's done in 2 steps, the first to locate buildmacros.sce script 
                        (see help <var><strong>get_absolute_file_path</strong></var> function), and the second to generate the library
                        (see help <strong><var>genlib</strong></var> function). 
                </p>
-               builder.sce
+               buildmacros.sce
                <pre class="entete">
 mode(-1)
-toolboxname='toolbox_example'
-pathB=get_absolute_file_path('builder.sce')
+toolboxname='mytoolbox'
+pathB=get_absolute_file_path('buildmacros.sce')
 disp('Building macros  in ' +pathB)
 genlib(toolboxname+'lib',pathB,%t)
 clear pathB genlib toolboxname</pre>   
                
                <br />
-               To customize this template, replace the characters string 'toolbox_example' by the name of your toolbox.
+               To customize this template, replace the characters string 'mytoolbox' by the name of your toolbox.
                
                <a name="chap2.1.2"></a>
                <h4>2.1.2 The macros loader</h4>
                <p>
-                       The loader (see above script) loads the library lib included in the directory macros. Like the builder, the code is generic, the first step to locate macrosloader.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 <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)
                </p>
                
-               loader.sce
+               loadmacros.sce
                <pre class="entete">
 mode(-1)
-pathL=get_absolute_file_path('loader.sce')
+pathL=get_absolute_file_path('loadmacros.sce')
 disp('Loading macros  in ' +pathL)
 load(pathL+'/lib')
 clear pathL</pre>      
                
                <a name="chap2.2"></a>
-               <h3>2.2 Interface and src directories</h3>
-               <p>
-                       A Scilab primitive is a Scilab function which calls a function written in C or fortran code (using an interface program)<br />
-                       Before to write the builder, its necessary to create for each primitives the corresponding interface programs which are included in the directory: interface. 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 CheckRhs and CheckLhs functions), and get the adress of the rhs arguments which are in Scilab internal stack to give this information at the interfaced function. So in the first part we explain, thanks to template, how to implement some interfaces programs (written in C code). In this article we don't describe all the possibilities of the interface programs, for more explanations see the directory SCI/examples.
-                       All interface programs are included in the directory: interface<br />  
+               <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 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 \>
+               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 \>
                </p>
                
-               <a name="chap2.2.1"></a>
-               <h4>2.2.1 Examples of interfaces programs</h4>
+               <a name="chap2.2.2"></a>
+               <h4>2.2.2 Examples of interfaces programs</h4>
                <p>
-                       Here two examples which enable to write many interfaces, so it's important to understand it, and know how to customize it for your toolbox. 
+                       These 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.
                </p>
                
                <p>
-                       <EM>Example a</EM>: <br />             
-                       We consider an C routine <var><strong>sumab</strong></var> which returns the sum of two vectors. I suppose that the name of the corresponding primitive is 
-                       <var><strong>scisum</strong></var>. We can keep the same name that the C routine (sumab) or try an other name.<br />
-                       The both following scripts represent the C code of <var><strong>sumab</strong></var> and its associated interface program when 
-                       we call the primitive <var><strong>scisum </strong></var>in a Scilab window as follows:<br />
-                       <var><strong>--> Y=scisum(A,B )</strong></var> <br /><br />
+                       <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>.
+                       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 />
+                       <var><strong>--> Y=sumab(A,B )</strong></var> <br /><br />
                </p>
                
-               sumab.c 
+               vectsum.c 
                <pre class="entete">
-void sumab(int n, double * a, double * b, double * y)
+void vectsum(int n, double * a, double * b, double * y)
 {
        int k;
        for (k = 0; k < n; ++k) 
@@ -182,12 +192,12 @@ void sumab(int n, double * a, double * b, double * y)
 }</pre>        
                        
                <br />
-               intsumab.c<br />
+               sci_sumab.c<br />
                <pre class="entete">
 #include "stack-c.h"
-extern int sumab(int n, double * a, double * b, double * y); 
+extern int vectsum(int n, double * a, double * b, double * y); 
 
-void intsumab(char *fname){  
+void sci_sumab(char *fname){  
 int l1, m1, n1, l2, m2, n2, l3, n;   
                
 /* 1 - Check the number of inputs/outputs arguments  */  
@@ -195,12 +205,12 @@ int minlhs=1, maxlhs=1, minrhs=2, maxrhs=2;
 CheckRhs(minrhs,maxrhs) ; 
 CheckLhs(minlhs,maxlhs) ; 
 
-/* 2 - Check inputs arguments type, and get the size and the adress in the Scilab stack of the inputs arguments */  
+/* 2 - Check inputs arguments type, and get the size and the address in the Scilab stack of the inputs arguments */  
 GetRhsVar(1, "d", &m1, &n1, &l1);
 GetRhsVar(2, "d", &m2, &n2, &l2);
                
 /* 3 - Check that the inputs arguments have the same size */
-/* it's possible to use the chekdims and getscalar functions to do these checks*/ 
+/* it's possible to use the chekdims and getscalar functions to make these checks*/ 
 n=m2*n2; 
 if( n1!=n2 || m1!=m2) 
 {
@@ -215,23 +225,25 @@ if(n1!=0 && m1!=0)
        }
                 
                
-/* 4 - Create the output argument */ 
+/* 4 - Create a new variable corresponding to the output argument */ 
 CreateVar(3,"d",&m2,&n2,&l3);   
-sumab(n,stk(l1),stk(l2),stk(l3));  
+
+/* 5 -call vectsum routine: returns in stk(l3) the sum of a and b*/
+vectsum(n,stk(l1),stk(l2),stk(l3));  
                
-/* 5 - Specif the ouput argument */  
+/* 6 - Specif ouput argument */  
 LhsVar(1) = 3;  
 return 0;
 }</pre>                    
                
                <br />
                <p>
-                       <EM>In Step 1</EM>: call the instructions <var><strong>CheckRhsVar(minrhs,maxrhs)</strong></var> and <var><strong>
-                       CheckLhsVar(minlhs,maxlhs)</strong></var><br />
+                       <EM>Step 1</EM>: call <var><strong>CheckRhsVar(minrhs,maxrhs)</strong></var> and <var> <strong>
+                       CheckLhsVar(minlhs,maxlhs)</strong></var> instructions<br />
                        <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 />
-                       In this example the numbers of input (=2) and output (=1) arguments are constant, but for certains functions (see example2)
+                       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)
                        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  
@@ -239,49 +251,61 @@ return 0;
                        
                        <br />
                        
-                       <EM>In Step 2</EM>:  call the instruction <b><i>GetRhsVar(1,"d",&m1,&n1,&l1)</b></i><br />
-                       <b><i>GetRhsVar</b></i> function checks that the type of inputs argument is correct, and gets their size and their adress in the Scilab stack.<br />
-                       We describe above all arguments of <b><i>GetRhsVar</b></i> function:<br />
-                       <b><i>1</b></i> : corresponds to the position of the first input argument of scisum(A,B ), i.e A, (2 corresponds to B,...)<br />
-                       <b><i>m1 </b></i>: gets the rows number of A (m2 for B)<br />
-                       <b><i>n1 </b></i>: gets the columns number of  A (n2 for B)<br />
-                       <b><i>l1 </b></i>: gets the adress of A in the Scilab stack (l2 for B)<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 />
+
+                       <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>
+                       </ul>
                        <br />
                        
-                       <EM>In Step 3</EM>: instruction <b><i>CreateVar(3,"d",&m2,&n2,&l3)</b></i><br />
-                       <b><i>CreateVar</b></i>  function creates the ouput argument (here Y) at the 3th position<br />
-                       <b><i>3 </b></i>: corresponds to the position of the first output argument Y. We should take the number which follows 
-                       immediatly the last position of  the input arguments (which is 2)<br />
-                       <b><i>"d"</b></i>: sets the type of the output argument, a double <br />
-                       <b><i>m2</b></i>: sets the rows number of the output argument (here equal to the rows number of the second input argument B: m2)<br />
-                       <b><i>n2</b></i>: sets the columns number of the first output argument (here equal to the columns number of the second input argument B: n2)<br />
-                       <b><i>l3</b></i>: gets the adress of the lhs in the Scilab stack <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 />
+                       <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>
+                       </ul>
                        
                        <br />
                        
-                       <EM>In Step 4</EM>: instruction <b><i>LhsVar(1) = 3</b></i><br />
-                       The instruction <b><i>LhsVar(1) = 3</b></i> means the first output argument takes the value of the variable placed in the 3th position (i.e Y)<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 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 />
                        <br />
                        <br />
                        
                        <EM>Example b</EM>:<br />
-                               In the second example we describe the interface program (see above script) of the primitive <b><i>scifun1</b></i> which uses the C functions <b><i>fun1</b></i> and <b><i>fun2</b></i> (see above script). This primitive has two syntaxes:<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:
+                       <br />
                        <br />
                        the first syntax is:</b></i><br />
-                       <b><i>--> [X, Y ]=scifun1(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 positive components in a scalar <b><i>Y</b></i>. In this case the number of output arguments (=Lhs) is 2.<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 />
                        
                        <br />
                        the second syntax is:<br />
-                       <b><i>--> [X ]=scifun1(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>. In this case <b><i>Lhs=1</b></i>.<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 />
+               </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 />
                </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 memory place)
+               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)
                <pre class="entete">
 extern void  fun2(double *, int, int *);
 
@@ -291,7 +315,7 @@ void fun1(double * a,  int na, int * nx,  double ** x , double * y){
        fun2(a, na, nx);
        *x=(double *)malloc((*nx)*sizeof(double));
        *y=0;
-       for(i=0;i<na;i++)
+       for(i=0;i&lt;na;i++)
        if(a[i]>0) {
                *(*x+k1)=a[i];
                *y += a[i];
@@ -307,20 +331,20 @@ void  fun2(double * a, int na, int * nx)
 {
        int i;
        *nx=0;
-       for(i=0;i<na;i++)
+       for(i=0;i&lt;na;i++)
        if (a[i]>0)  
                (*nx)++;
 }</pre>        
                
                <br />
                
-               intfun1.c
+               sci_fun.c
                <pre class="entete">
 #include "stack-c.h"
 
 extern void fun1(double * ,  int, int *, double **, double *);
 
-int intfun1(char *fname)
+int sci_fun(char *fname)
 {
        int la, ma, na, m=1, nx, i, lx, ls;
        double * x, s;
@@ -331,7 +355,7 @@ int intfun1(char *fname)
        CheckRhs(minrhs,maxrhs) ;
        CheckLhs(minlhs,maxlhs) ;
 
-       /* 2 - Check the rhs type, get the rows number (ma) and the columns number (na) of rhs, and its adress (la) in the Scilab stack (first position) */
+       /* 2 - Check the rhs type, get the rows number (ma) and the columns number (na) of rhs, and its address (la) in the Scilab stack (first position) */
        GetRhsVar(1, "d", &ma, &na, &la); 
 
        /* 3 - Check rhs is a vector */
@@ -346,10 +370,10 @@ int intfun1(char *fname)
 
        fun1(stk(la), na*ma, &nx, &x, &s);
 
-       /* 4 - Create the place for the first output argument x ( a vector of doubles, size: 1*nx ) to the adress lx in the Scilab stack (second position) */
+       /* 4 - Create the place for the first output argument x ( a vector of doubles, size: 1*nx ) to the address lx in the Scilab stack (second position) */
        CreateVar(2, "d", &m, &nx, &lx);
 
-       /* if there are two outputs variables then: Create the place for the second output s ( a double, size 1*1) to the adress ls in the Scilab stack (third position) */ 
+       /* if there are two outputs variables then: Create the place for the second output s ( a double, size 1*1) to the address ls in the Scilab stack (third position) */ 
        /* get the value of s, and put it in the Scilab stack */
        if(Lhs==2)
        {
@@ -358,7 +382,7 @@ int intfun1(char *fname)
        }
 
        /* get the components of x, and put them in the Scilab stack */
-       for(i=0;i&gt;nx;i++) 
+       for(i=0;i&lt;nx;i++) 
                stk(lx)[i]=x[i];
 
        /* free memory */
@@ -373,46 +397,49 @@ int intfun1(char *fname)
                
                <br />
                
-               <a name="chap2.2.2"></a>
-               <h4>2.2.2 Primitives builder</h4>
-               <p>Now the src and the interface directories contain all the necessary files (<b><i>fun1.c</b></i>, <b><i>fun2.c</b></i>, <b><i>intfun1.c</b></i>, <b><i>sumab.c</b></i>, <b><i>intsumab.c</b></i>) to create the builder (see above template) for the primitives <i><b>scifun1</i></b> and <i><b>scisum</i></b>.
+               <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>.
                <br />
-               We need to write two builders:<br /> One the hand, in the src directory, this builder creates a shared libraries (see help <i><b>ilib_for_link</b></i> function) corresponding to the C functions.And the other hand, in the interface directory, this builder 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 dynamically load the shared library (see help <i><b>addinter</b></i> function)</p>
+               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>
                
-               the src builder
+               buildsrc.sce
                <pre class="entete">
-ilib_for_link('toolbox_examplesrc',['fun1.o' 'fun2.o','sumab.o'],[],"c")</pre> 
-               
+ilib_for_link('mytoolboxsrc',['fun1.o' 'fun2.o','vectsum.o'],[],"c")</pre>     
+
                <br />
-               the interface builder<br />
+               buildsci_gateway.sce<br />
                
                <pre class="entete">
-// must be run from this directory
-ilib_name  = 'libtoolbox_example'     // interface library name
-files = ['intfun1.o', 'intsumab.o'];  // objects files
-libs  = ["../src/libtoolbox_examplesrc"]                 // other libs needed for linking
-table = [ 'scifun1', 'intfun1';
-       'scisum','intsumab'];        // table of (scilab_name,interface-name)
-// do not modify below
-ilib_build(ilib_name,table,files,libs)</pre>   
+               // must be run from this directory
+               ilib_name  = 'libmytoolbox'     // interface library name
+               files = ['sci_fun.o', 'sci_sumab.o'];  // objects files
+               libs  = ["../src/libmytoolboxsrc"]                 // other libs needed for linking
+               table = [ 'fun', 'sci_fun';
+               'sumab','sci_sumab'];        // table of (scilab_name,interface-name)
+               // do not modify below
+               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 interface program names (second column)
+               the variable <i><b>table</b></i> contains the primitives names (first column) and the corresponding interfaces programs names (second column)
                
                <a name="chap2.3"></a>
-               <h3>2.3 The  man directory</h3>
-               <p>This directory included .xml files, a manbuilder and a manloader scripts
+               <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 />
                                On Unix/Linux systems: to create the manual pages you need 'sabcmd', an XML parser which is part of the Sablotron package.<br /> 
-                               (see the link to download it:<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 />
+                               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 />
                </p>
                
                <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>scifun1.xml</i></b>, <b><i>scisum.xml</i></b>) and put them in the man 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 <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.
                </p>
                
                <pre class="entete">
@@ -420,7 +447,7 @@ ilib_build(ilib_name,table,files,libs)</pre>
 &lt;!DOCTYPE MAN SYSTEM &quot;/home/scilab/scilab-3.0/man/manrev.dtd&quot;&gt;
 &lt;MAN&gt;
 &lt;LANGUAGE&gt;eng&lt;/LANGUAGE&gt;
-&lt;TITLE&gt;scisum&lt;/TITLE&gt;
+&lt;TITLE&gt;sumab&lt;/TITLE&gt;
 &lt;TYPE&gt;Scilab Function  &lt;/TYPE&gt;
 &lt;DATE&gt;20-Mar-2006&lt;/DATE&gt;
 &lt;SHORT_DESCRIPTION name=&quot;add function name&quot;&gt;  add short decription here&lt;/SHORT_DESCRIPTION&gt;
@@ -490,30 +517,30 @@ Add here the used function name and  references
 &lt;/MAN&gt;</pre>     
                
                <a name="chap2.3.2"></a>
-               <h4>2.3.2 The man builder</h4>
-               <p>The manbuilder (see above) creates a whatis.htm file which is a short description of the functions, and translates the xml files to html (see help <b><i>xmltohtml</b></i> function)
+               <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>
                
                <br />
                
-               builder.sce
+               buildhelp.sce
                <pre class="entete">
 mode(-1) //force silent execution
-path=get_absolute_file_path('builder.sce');//get the absolute path of this file
+path=get_absolute_file_path('builhelp.sce');//get the absolute path of this file
 add_help_chapter("Title1",path);//add help chapter
 xmltohtml(path,"Title1")
 //clear the variable stack
 clear path add_help_chapter get_absolute_file_path </pre>      
                
                <a name="chap2.3.3"></a>
-               <h4>2.3.3 The man loader</h4>
-               <p>The loader(see above script) add your help functions files in the help Scilab browser 
+               <h4>2.3.3 The help loader</h4>
+               <p>The loader (named loadhelp) adds your help functions files in the help Scilab browser 
                </p>
                
-               loader.sce
+               loadhelp.sce
                <pre class="entete">
 mode(-1) //force silent execution
-path=get_absolute_file_path('loader.sce');//get the absolute path of this file
+path=get_absolute_file_path('loadhelp.sce');//get the absolute path of this file
 add_help_chapter("Title1",path);//add help chapter
 clear path add_help_chapter get_absolute_file_</pre>   
                
@@ -528,22 +555,22 @@ mainpathB=get_absolute_file_path('builder.sce');
 chdir(mainpathB);
 if isdir('src') then
 chdir('src');
-exec('builder.sce');
+exec('buildsrc.sce');
 chdir('..');
 end
-if isdir('interface') then
-chdir('interface');
-exec('builder.sce');
+if isdir('sci_gateway') then
+chdir('sci_gateway');
+exec('buildsci_gateway.sce');
 chdir('..');
 end
 if isdir('macros') then
 chdir('macros');
-exec('builder.sce');
+exec('buildmacros.sce');
 chdir('..');
 end
-if isdir('man') then
-chdir('man');
-exec('builder.sce');
+if isdir('help') then
+chdir('help');
+exec('buildhelp.sce');
 chdir('..');
 end
 clear mainpathB</pre>  
@@ -555,19 +582,19 @@ clear mainpathB</pre>
 mode(-1);
 mainpathL=get_absolute_file_path('loader.sce');
 chdir(mainpathL);
-if isdir('interface') then
-chdir('interface');
+if isdir('sci_gateway') then
+chdir('sci_gateway');
 exec('loader.sce');
 chdir('..');
 end
 if isdir('macros') then
 chdir('macros');
-exec('loader.sce');
+exec('loadmacros.sce');
 chdir('..');
 end
-if isdir('man') then
-chdir('man');
-exec('loader.sce');
+if isdir('help') then
+chdir('help');
+exec('loadhelp.sce');
 chdir('..');
 end
 clear mainpathL</pre>  
@@ -578,7 +605,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>toolbox_example.tar.gz</b> and <b>toolbox_example.zip</b>), 
+                               <li>Complete the submission form document and add your package (here <b>mytoolbox.tar.gz</b> and <b>mytoolbox.zip</b>), 
                                        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>