[doc] misc. fix & improvements
[scilab.git] / scilab / modules / m2sci / help / en_US / About_M2SCI_tools.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3     * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4     * Copyright (C) 2002-2004 - INRIA - Vincent COUVERT
5     *
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14     *
15     -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
18           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
19           xml:lang="en" xml:id="About_M2SCI_tools">
20     <refnamediv>
21         <refname>About M2SCI tools</refname>
22         <refpurpose>Generally speaking about tools to convert Matlab files to Scilab</refpurpose>
23     </refnamediv>
24     <refsection>
25         <title>Description</title>
26         <para>Scilab includes useful tools to convert Matlab M-files to Scilab.</para>
27         <para>
28             Taking a Matlab M-file, <literal>mfile2sci</literal> modifies this files so that it can be
29             compiled by Scilab. Then, this compiled code is converted to a "tree" of instructions
30             by <literal>macr2tree</literal>. This "tree" is an imbrication of Scilab lists and tlists and
31             is the basis for conversion. Each instruction of this "tree" is converted to Scilab and
32             inference is done to known what are the variables. Once this "tree" is converted to Scilab,
33             code is generated using <literal>tree2code</literal>.
34         </para>
35         <para>
36             All tlists used for coding this tree (and we call "MSCI tlists") are listed below:
37         </para>
38         <itemizedlist>
39             <listitem>
40                 <variablelist>
41                     <varlistentry>
42                         <term>funcall</term>
43                         <listitem>
44                             <para>
45                                 tlist representing a function call created by <literal>Funcall</literal>
46                             </para>
47                         </listitem>
48                     </varlistentry>
49                     <varlistentry>
50                         <term>operation</term>
51                         <listitem>
52                             <para>
53                                 tlist representing an operation created by <literal>Operation</literal>
54                             </para>
55                         </listitem>
56                     </varlistentry>
57                     <varlistentry>
58                         <term>variable</term>
59                         <listitem>
60                             <para>
61                                 tlist representing a variable created by <literal>Variable</literal>
62                             </para>
63                         </listitem>
64                     </varlistentry>
65                     <varlistentry>
66                         <term>cste</term>
67                         <listitem>
68                             <para>
69                                 tlist representing a constant created by <literal>Cste</literal>
70                             </para>
71                         </listitem>
72                     </varlistentry>
73                     <varlistentry>
74                         <term>equal</term>
75                         <listitem>
76                             <para>
77                                 tlist representing an instruction created by <literal>Equal</literal>
78                             </para>
79                         </listitem>
80                     </varlistentry>
81                     <varlistentry>
82                         <term>ifthenelse</term>
83                         <listitem>
84                             <para>tlist representing an IF/THEN/ELSE control instruction created inside M2SCI kernel functions</para>
85                         </listitem>
86                     </varlistentry>
87                     <varlistentry>
88                         <term>while</term>
89                         <listitem>
90                             <para>tlist representing a WHILE control instruction created inside M2SCI kernel functions</para>
91                         </listitem>
92                     </varlistentry>
93                     <varlistentry>
94                         <term>selectcase</term>
95                         <listitem>
96                             <para>tlist representing a SELECT/CASE control instruction created inside M2SCI kernel functions</para>
97                         </listitem>
98                     </varlistentry>
99                     <varlistentry>
100                         <term>for</term>
101                         <listitem>
102                             <para>tlist representing a FOR control instruction created inside M2SCI kernel functions</para>
103                         </listitem>
104                     </varlistentry>
105                 </variablelist>
106             </listitem>
107         </itemizedlist>
108         <para>
109             The contents of these tlists is described in corresponding help pages.
110         </para>
111         <para>
112             Operations are converted using a function named <literal>%&lt;opcode&gt;2sci</literal> with opcode
113             the Scilab code for this operator. See help page for overloading to have these codes. All
114             these functions are already written and are in directory SCI/modules/m2sci/macros/percent/.
115         </para>
116         <para>
117             Function calls are converted using a function called <literal>sci_&lt;Matlab_function_name&gt;</literal>.
118             Some of these functions have been written and are in directory SCI/modules/m2sci/macros/sci_files/.
119             We are working on increasing the set of Matlab functions converted. However, everybody can
120             write such functions using help page sci_files.
121         </para>
122         <para>
123             Inference is done using tlists of type "infer" containing fields:
124         </para>
125         <variablelist>
126           <varlistentry>
127             <term>dims</term>
128             <listitem>
129               <para>list of dimensions</para>
130             </listitem>
131           </varlistentry>
132           <varlistentry>
133             <term>type</term>
134             <listitem>
135               <para>"type" tlist</para>
136             </listitem>
137           </varlistentry>
138           <varlistentry>
139             <term>contents</term>
140             <listitem>
141               <para>"contents" tlist if a Cell or a Struct</para>
142             </listitem>
143           </varlistentry>
144         </variablelist>
145         <para>
146             Type is a tlist of type "type" containing fields:
147         </para>
148         <variablelist>
149           <varlistentry>
150             <term>vtype</term>
151             <listitem>
152               <para>data type</para>
153             </listitem>
154           </varlistentry>
155           <varlistentry>
156             <term>property</term>
157             <listitem>
158               <para>property</para>
159             </listitem>
160           </varlistentry>
161         </variablelist>
162         <para>To have more details about inference see help page for m2scideclare.</para>
163     </refsection>
164     <refsection role="see also">
165         <title>See also</title>
166         <simplelist type="inline">
167             <member>
168                 <link linkend="mfile2sci">mfile2sci</link>
169             </member>
170             <member>
171                 <link linkend="translatepaths">translatepaths</link>
172             </member>
173             <member>
174                 <link linkend="overloading">overloading</link>
175             </member>
176             <member>
177                 <link linkend="sci_files">sci_files</link>
178             </member>
179             <member>
180                 <link linkend="Funcall">Funcall</link>
181             </member>
182             <member>
183                 <link linkend="Operation">Operation</link>
184             </member>
185             <member>
186                 <link linkend="Variable">Variable</link>
187             </member>
188             <member>
189                 <link linkend="Cste">Cste</link>
190             </member>
191             <member>
192                 <link linkend="Infer">Infer</link>
193             </member>
194             <member>
195                 <link linkend="Type">Type</link>
196             </member>
197             <member>
198                 <link linkend="Equal">Equal</link>
199             </member>
200             <member>
201                 <link linkend="m2scideclare">m2scideclare</link>
202             </member>
203         </simplelist>
204     </refsection>
205 </refentry>