4da5d01308ecad5cc47c793c1efc7506d15edc9c
[scilab.git] / scilab / modules / m2sci / help / en_US / m2scideclare.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" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="m2scideclare">
17     <refnamediv>
18         <refname>m2scideclare</refname>
19         <refpurpose>Giving tips to help M2SCI...</refpurpose>
20     </refnamediv>
21     <refsection>
22         <title>Description</title>
23         <para>
24             The main difficulty for M2SCI (<literal>mfile2sci</literal>) is to find what variables are: dimensions, type...
25         </para>
26         <para>
27             To help this tool, just add comments beginning with <literal>%m2scideclare</literal> in the M-file to convert,
28             (<literal>%m2sciassume</literal> was used in previous Scilab versions and is now obsolete).
29         </para>
30         <para>
31             The syntax of this command is:
32         </para>
33         <para>
34             <literal>%m2scideclare variable_name|dimensions|data_type|property</literal>
35         </para>
36         <para>
37             with :
38         </para>
39         <itemizedlist>
40             <listitem>
41                 <itemizedlist>
42                     <listitem>
43                         <para>
44                             variable_name: name of the variable declared. It can be a Struct field (e.g. <literal>x(1,2).name</literal>)
45                             or describe the contents of a Cell using syntax
46                             <literal>x(1,2).entries</literal>. NOTE that for Cells and Structs,
47                             <literal>*</literal> can be used as an index (see examples below).
48                         </para>
49                     </listitem>
50                     <listitem>
51                         <para>
52                             dimensions: dimensions of the variable declared separated by blanks, if a dimension is unknown,
53                             replace it by <literal>?</literal>. NOTE that String dimensions must be similar to Matlab ones
54                             e.g. <literal>1 6</literal> for character string 'string'.
55                         </para>
56                     </listitem>
57                     <listitem>
58                         <para>
59                             data_type: data type of the variable which can be:
60                         </para>
61                         <informaltable border="1">
62                             <tr>
63                                 <td>m2scideclare data type</td>
64                                 <td>Scilab "equivalent" type</td>
65                             </tr>
66                             <tr>
67                                 <td>Double</td>
68                                 <td>1</td>
69                             </tr>
70                             <tr>
71                                 <td>Boolean</td>
72                                 <td>4</td>
73                             </tr>
74                             <tr>
75                                 <td>Sparse</td>
76                                 <td>5</td>
77                             </tr>
78                             <tr>
79                                 <td>Int</td>
80                                 <td>8</td>
81                             </tr>
82                             <tr>
83                                 <td>Handle</td>
84                                 <td>9</td>
85                             </tr>
86                             <tr>
87                                 <td>String</td>
88                                 <td>10</td>
89                             </tr>
90                             <tr>
91                                 <td>Struct</td>
92                                 <td>Matlab struct (16)</td>
93                             </tr>
94                             <tr>
95                                 <td>Cell</td>
96                                 <td>Matlab cell (17)</td>
97                             </tr>
98                             <tr>
99                                 <td>Void</td>
100                                 <td>No type (0)</td>
101                             </tr>
102                             <tr>
103                                 <td>?</td>
104                                 <td>Unknown type</td>
105                             </tr>
106                         </informaltable>
107                     </listitem>
108                     <listitem>
109                         <para>
110                             property: property of the variable which can be:
111                         </para>
112                         <informaltable border="1">
113                             <tr>
114                                 <td>m2scideclare property</td>
115                                 <td>Scilab "equivalent"</td>
116                             </tr>
117                             <tr>
118                                 <td>Real</td>
119                                 <td>Real data</td>
120                             </tr>
121                             <tr>
122                                 <td>Complex</td>
123                                 <td>Complex data</td>
124                             </tr>
125                             <tr>
126                                 <td>?</td>
127                                 <td>Unknown property</td>
128                             </tr>
129                         </informaltable>
130                         <para>
131                             This field is ignored for following datatypes: <literal>Cell</literal>,
132                             <literal>Struct</literal>, <literal>String</literal> and <literal>Boolean</literal>.
133                         </para>
134                     </listitem>
135                 </itemizedlist>
136             </listitem>
137         </itemizedlist>
138         <para>
139             All data given by <literal>m2scideclare</literal> are compared with infered data,
140             in case of conflict, infered data are kept and a warning message is displayed.
141             If you are sure about your data, report a bug.
142         </para>
143         <para>Some examples are given below:</para>
144         <itemizedlist>
145             <listitem>
146                 <itemizedlist>
147                     <listitem>
148                         <para>
149                             <literal>%m2scideclare var1|2 3|Double|Real</literal>var1 is declared as a 2x3 Double matrix containing real data
150                         </para>
151                     </listitem>
152                     <listitem>
153                         <para>
154                             <literal>%m2scideclare var2|2 3 10|Double|Complex</literal>var2 is declared as a 2x3x10 Double hypermatrix containing complex data
155                         </para>
156                     </listitem>
157                     <listitem>
158                         <para>
159                             <literal>%m2scideclare var3(1,2).name|1 10|String|?</literal>var3 is declared as a Struct array containing a 1x10 character string
160                             in field 'name' of struct at index (1,2)
161                         </para>
162                     </listitem>
163                     <listitem>
164                         <para>
165                             <literal>%m2scideclare var4(1,5).entries|1 ?|Boolean|?</literal>var4 is declared as a Cell containing a row boolean vector at index (1,5)
166                         </para>
167                     </listitem>
168                     <listitem>
169                         <para>
170                             <literal>%m2scideclare var4(1,6).entries|? ?|Int|?</literal>var4 is declared as a Cell containing a row boolean vector at index (1,5)
171                             and integer data at index (1,6)
172                         </para>
173                     </listitem>
174                     <listitem>
175                         <para>
176                             <literal>%m2scideclare var5(*,*).name|1 ?|String|?</literal>var5 is declared as a Struct array containing a 1xn character string
177                             in all fields 'name'
178                         </para>
179                     </listitem>
180                     <listitem>
181                         <para>
182                             <literal>%m2scideclare var6(2,*).entries|1 3|Double|Real</literal>var6 is declared as a Cell array containing a 1x3 double vector
183                             in each element of its second row
184                         </para>
185                     </listitem>
186                 </itemizedlist>
187             </listitem>
188         </itemizedlist>
189     </refsection>
190 </refentry>