[doc] misc. fix & improvements
[scilab.git] / scilab / modules / m2sci / help / en_US / mfile2sci.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) ???? - INRIA - Serge STEER
5  * Copyright (C) 2002-2004 - INRIA - Vincent COUVERT
6  * Copyright (C) 2018 - Samuel GOUGEON
7  *
8  * Copyright (C) 2012 - 2016 - Scilab Enterprises
9  *
10  * This file is hereby licensed under the terms of the GNU GPL v2.0,
11  * pursuant to article 5.3.4 of the CeCILL v.2.1.
12  * This file was originally licensed under the terms of the CeCILL v2.1,
13  * and continues to be available under such terms.
14  * For more information, see the COPYING file which you should have received
15  * along with this program.
16     *
17     -->
18 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
19         xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
20         xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
21         xml:lang="en" xml:id="mfile2sci">
22     <refnamediv>
23         <refname>mfile2sci</refname>
24         <refpurpose>Matlab M-file to Scilab conversion function</refpurpose>
25     </refnamediv>
26     <refsynopsisdiv>
27         <title>Syntax</title>
28         <synopsis>
29             mfile2sci()  // interactive GUI
30             mfile2sci(M_file_path)
31             mfile2sci(M_file_path, result_path )
32             mfile2sci(M_file_path, result_path, Recmode)
33             mfile2sci(M_file_path, result_path, Recmode, only_double)
34             mfile2sci(M_file_path, result_path, Recmode, only_double, verbose_mode)
35             mfile2sci(M_file_path, result_path, Recmode, only_double, verbose_mode, prettyprintoutput)
36         </synopsis>
37     </refsynopsisdiv>
38     <refsection>
39         <title>Arguments</title>
40         <variablelist>
41             <varlistentry>
42                 <term>M_file_path</term>
43                 <listitem>
44                     <para>a character string which gives the path of Matlab M-file to convert</para>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>result_path</term>
49                 <listitem>
50                     <para>
51                         a character string which gives the directory where the result has to be
52                         written. Default value is current directory.
53                     </para>
54                 </listitem>
55             </varlistentry>
56             <varlistentry>
57                 <term>Recmode</term>
58                 <listitem>
59                     <para>
60                         Boolean flag, used by <literal>translatepaths()</literal> function for
61                         recursive conversion. Must be %F to convert a single mfile. Default value: %F
62                     </para>
63                 </listitem>
64             </varlistentry>
65             <varlistentry>
66                 <term>only_double</term>
67                 <listitem>
68                     <para>
69                         Boolean: If %T, mfile2sci() considers that numerical functions and operators
70                         (like "+") are used only with numerical data. This excludes for instance
71                         instructions like <literal>"ab" + "cd"</literal> (that then will be
72                         kept as is instead of being converted into
73                         <literal>asciimat("ab") + asciimat("cd")</literal>).
74                     </para>
75                     <para>
76                         Default value: %F: All possible conversions are done.
77                     </para>
78                 </listitem>
79             </varlistentry>
80             <varlistentry>
81                 <term>verbose_mode</term>
82                 <listitem>
83                     <para> display information mode</para>
84                     <table border="0">
85                         <tr valign="top">
86                             <th>0 : </th>
87                             <td>no information displayed</td>
88                         </tr>
89                         <tr valign="top">
90                             <th>1 : </th>
91                             <td>
92                                 information is written as comments in resulting SCI-file.
93                             </td>
94                         </tr>
95                         <tr valign="top">
96                             <th>2 : </th>
97                             <td>
98                                 information is written as comments in resulting SCI-file
99                                 and in logfile.
100                             </td>
101                         </tr>
102                         <tr valign="top">
103                             <th>[3] : </th>
104                             <td>
105                                 information is written as comments in resulting SCI-file,
106                                 in logfile and displayed in Scilab window. (Default value)
107                             </td>
108                         </tr>
109                     </table>
110                 </listitem>
111             </varlistentry>
112             <varlistentry>
113                 <term>prettyprintoutput</term>
114                 <listitem>
115                     <para>Boolean flag, if %T generated code is beautified. Default value: %F</para>
116                 </listitem>
117             </varlistentry>
118         </variablelist>
119     </refsection>
120     <refsection>
121         <title>Description</title>
122         <para>
123             M2SCI (and particularly mfile2sci) is Matlab M-file to Scilab function conversion tools.
124             It tries whenever possible to replace call to Matlab functions by the equivalent
125             Scilab primitives and functions.
126         </para>
127         <para>
128             To convert a Matlab M-file just enter the Scilab instruction:
129             <literal>mfile2sci(file)</literal>
130         </para>
131         <para>
132             where file is a character string giving the path name of the M-file.
133         </para>
134         <para>
135             <literal>mfile2sci(..)</literal> will then generate three files in the same directory:
136         </para>
137         <para>
138             <table border="0">
139                 <tr valign="top">
140                     <td><emphasis role="bold">&lt;function-name>.sci</emphasis></td>
141                     <td>The result of the translation of the M-file in Scilab language.</td>
142                 </tr>
143                 <tr valign="top">
144                     <td><emphasis role="bold">&lt;function-name>.cat</emphasis></td>
145                     <td>the Scilab help file associated to the function</td>
146                 </tr>
147                 <tr valign="top">
148                     <td><emphasis role="bold">sci_&lt;function-name>.sci</emphasis></td>
149                     <td>
150                         The Scilab function required to convert the calls to this Matlab M-file
151                         in other Matlab M-files. This function may be improved "by hand".
152                         This function is only useful for conversion not for use of translated
153                         functions.
154                     </td>
155                 </tr>
156             </table>
157         </para>
158         <para>
159             Some functions like eye, ones, size, sum,... behave differently according to the
160             dimension of their arguments. When mfile2sci cannot infer dimensions it replaces
161             these function call by a call to an emulation function named mtlb_&lt;function_name>.
162             For efficiency, these functions may be replaced by the proper scilab equivalent
163             instructions.
164             To get information about replacement, enter:
165             <literal>help mtlb_&lt;function_name></literal> in Scilab command window
166         </para>
167         <para>
168             Some other functions like plot, has no straightforward equivalent in scilab.
169             They are also replaced by an emulation function named
170             <literal>mtlb_&lt;function_name></literal>.
171         </para>
172         <para>
173             When translation may be incorrect or may be improved mfile2sci adds a
174             comment which begins by "//!" (according to verbose_mode)
175         </para>
176         <note>
177             <literal>mfile2sci()</literal> without input argument launches a GUI allowing to
178             select a file/directory, and to configure and run the converter:
179             <programlisting role="example"><![CDATA[
180 mfile2sci()
181             ]]></programlisting>
182         </note>
183     </refsection>
184     <refsection>
185         <title>Examples</title>
186         <programlisting role="example"><![CDATA[
187 // Create a simple M-file
188 rot90m = ["function B = rot90(A,k)"
189     "if ~isa(A, ''double'')"
190     "    error(''rot90: Wrong type for input argument #1: Real or complex matrix expected.'');"
191     "    return"
192     "end"
193     "[m,n] = size(A);"
194     "if nargin == 1"
195     "    k = 1;"
196     "else"
197     "    if ~isa(k, ''double'')"
198     "        error(''rot90: Wrong type for input argument #2: A real expected.'');"
199     "        return"
200     "    end"
201     "    k = rem(k,4);"
202     "    if k < 0"
203     "        k = k + 4;"
204     "    end"
205     "end"
206     "if k == 1"
207     "    A = A.'';"
208     "    B = A(n:-1:1,:);"
209     "elseif k == 2"
210     "    B = A(m:-1:1,n:-1:1);"
211     "elseif k == 3"
212     "    B = A(m:-1:1,:);"
213     "    B = B.'';"
214     "else"
215     "    B = A;"
216     "end"];
217 mputl(rot90m, TMPDIR + "/rot90.m")
218
219 // Convert it to scilab language
220 mfile2sci(TMPDIR + "/rot90.m",TMPDIR)
221
222 // Show the new code
223 editor(TMPDIR + "/rot90.sci")
224
225 // Compile it in scilab
226 exec(TMPDIR+'/rot90.sci')
227
228 // Call & use it
229 m = rand(4,2);
230 rot90(m,1)
231  ]]></programlisting>
232     </refsection>
233     <refsection role="see also">
234         <title>See also</title>
235         <simplelist type="inline">
236             <member>
237                 <link linkend="translatepaths">translatepaths</link>
238             </member>
239         </simplelist>
240     </refsection>
241     <refsection role="history">
242         <title>History</title>
243         <revhistory>
244             <revision>
245                 <revnumber>6.0.2</revnumber>
246                 <revdescription>
247                     The <varname>only_double</varname> option is now %F by default.
248                 </revdescription>
249             </revision>
250         </revhistory>
251     </refsection>
252 </refentry>