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