* Bug #14361 fixed - Parser did not manage linebreak + blockcomment "... /* a comment */"
[scilab.git] / scilab / modules / core / help / en_US / 1_keywords / dot.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="dot" xml:lang="en">
3     <refnamediv>
4         <refname>dot</refname>
5         <refpurpose>(.) symbol</refpurpose>
6     </refnamediv>
7     <refsynopsisdiv>
8         <title>Syntax</title>
9         <synopsis>
10             123.33
11             
12             a.*b
13             a .*. b
14             
15             %pi * (%e + ..
16             %i)
17             
18             cd ..
19             dir ..
20         </synopsis>
21     </refsynopsisdiv>
22     <refsection>
23         <title>Description</title>
24         <variablelist>
25             <varlistentry>
26                 <term>.</term>
27                 <listitem>
28                     <para>Dot is used to mark decimal point for numbers : 3.25 and
29                         0.001
30                     </para>
31                 </listitem>
32             </varlistentry>
33             <varlistentry>
34                 <term>.&lt;op&gt;</term>
35                 <listitem>
36                     <para>
37                         used in conjunction with other operator symbols (<literal>*/ \ ^ '</literal>) to form other operators. Element-by-element
38                         multiplicative operations are obtained using <literal> .* , .^ , ./ , .\</literal>
39                         or <literal>.'</literal>. For example,  <literal>C = A ./ B</literal> is
40                         the matrix with elements <literal>c(i,j) = a(i,j)/b(i,j)</literal>. Kronecker product
41                         is noted <literal>.*.</literal> .
42                     </para>
43                     <para>
44                         <note>
45                             Note that when dot is used with an operation, it is not considered part of the number directly preceding the dot,
46                             therefore <literal>2.*x</literal> and <literal>2 .*x</literal> are evaluated
47                             as <literal>(2).*x</literal> and not as <literal>2.0*x</literal>.
48                         </note>
49                     </para>
50                 </listitem>
51             </varlistentry>
52             <varlistentry>
53                 <term>..</term>
54                 <listitem>
55                     <para>Continuation mark. Two or more dots at the end of a
56                         line (or followed by a comment) causes the following line to be a
57                         continuation.
58                     </para>
59                     <para>Continuation lines are handled by a preprocessor which builds
60                         a long logical line from a sequence of continuation lines. So the
61                         continuation marks can be used to cut a line at any point.
62                     </para>
63                     <para>
64                         The following function <literal>foo</literal>:
65                     </para>
66                     <programlisting role=""><![CDATA[
67 function foo()
68     plot2d()
69     xtitle(["General title"; "It can be multiline, so quite long"], ..
70             "This is the X-axis title", "Y title")
71 endfunction
72  ]]></programlisting>
73                     <para>is equivalent to:</para>
74                     <programlisting role=""><![CDATA[
75 function foo()
76     plot2d()
77
78     xtitle(["General title"; "It can be multiline, so quite long"], "This is the X-axis title", "Y title")
79 endfunction
80  ]]></programlisting>
81                     <para>The logical line formed by physical line 3 and physical line 4
82                         is built as if it was entirely written in the physical line 4 while
83                         physical line 3 would be empty. This is done this way because
84                         continuation marks can be put anywhere even inside an
85                         expression.
86                         <note>The difference between logical and physical
87                             lines is of importance when dealing with edition (scinotes, edit)
88                             and within error messages
89                             (whereami), when the line number is provided or displayed.
90                         </note>
91                     </para>
92                     <para>
93                         There are exceptions to this rule in a matrix environment to ease up
94                         readibility of scilab scripts. The following example shows some differences
95                         between the matrix and non matrix environment.
96                     </para>
97                     <programlisting role=""><![CDATA[
98 // In the matrix environment .. is a continuation of the line
99 // except on some cases where readibility is important
100
101 // my_matrix == [1 2 3 -4 5 6]
102 my_matrix = [ 1 2 3 -4 5 6] // the minus sign here is unary
103
104 // my_matrix == [1 2 -1 5 6]
105 my_matrix = [ 1 2 3 -... // minus separated by .. is always considered a binary operation
106 4 5 6]
107                      ]]></programlisting>
108
109                     <para>
110                         An error is generated if the continuation mark is inside a language token, variable name, reserved word.
111                     </para>
112                     <programlisting role=""><![CDATA[
113 // this is possible is Scilab
114 for a_word = 1:10
115     disp("test " + string(a_word))
116 end
117
118
119 // This generate an error
120 for a_...
121 word = 1:10
122     disp("test " + string(a_word))
123 end
124 // Scilab cannot parse this line
125                     ]]></programlisting>
126                     <para>
127                         An error is generated if any word except a comment is found after the continuation mark.
128                     </para>
129
130                     <programlisting role=""><![CDATA[
131 this_wont_work = 3 + ... 4 // Scilab cannot parse this
132
133 this_wont_work_either = 3 + ... /* a multiline comment
134 followed by some text */ 4
135
136 this_works = 3 + ... /* a multiline comment
137 followed by text and a newline */
138 4
139                      ]]></programlisting>
140                 </listitem>
141             </varlistentry>
142             <varlistentry>
143                 <term>".." parameter</term>
144                 <listitem>
145                     <para>
146                         When functions are used in a console-oriented way, <literal>..</literal>
147                         is not considered as a continuation mark but as a simple argument. The most
148                         common usage is with <literal>cd ..</literal>, <literal>dir ..</literal>
149                         or <literal>ls ..</literal> actually standing for <literal>cd("..")</literal>,
150                         etc.
151                     </para>
152                 </listitem>
153             </varlistentry>
154         </variablelist>
155     </refsection>
156     <refsection>
157         <title>Examples</title>
158         <programlisting role="example"><![CDATA[
159 //decimal point
160 1.345
161
162 //used as part of an operator
163 x = [1 2 3]; x .^2 .*x // a space is not required between 2 and dot
164
165 // When writing rows of a matrix on different lines, ".." can be used but are not mandatory.
166 N_row = [   ..
167     63.    89.    3.   ..
168     91.    56.    22.  ..
169     15.    64.    40.  ..
170     ]
171 // Without the continuation mark, the matrix is read row by row:
172 N_square = [
173     63.    89.    3.
174     91.    56.    22.
175     15.    64.    40.
176     ]
177
178 // Within very long instructions like when creating uicontrol where many properties must be set,
179 // continuation marks are almost mandatory and allow to write and set one property per line
180 // in a readable way. A single huge line would not comply with Scilab coding style:
181 fig = figure("figure_name", "FIGURE", ..
182              "dockable",    "off", ..
183              "axes_size",   [990,670], ..
184              "infobar_visible", "off", ..
185              "toolbar",     "none", ..
186              "menubar_visible", "on", ..
187              "menubar",     "none", ..
188              "default_axes","off", ..
189              "layout",      "border", ..
190              "background",  color(244,244,244), ..
191              "tag",         "figure_1", ..
192              "visible",     "on");
193
194 // Console-oriented calls with some ".." argument
195 d = pwd(); cd SCI/contrib
196 cd ..   // stands for cd("..") and expects nothing on the next line
197 cd(d)   // Go back to your working directory
198
199 // This expression does not work anymore in Scilab 6
200 a = "here I start a very long string...  //but I'm not in the mood of continuing
201      - and here I go on"
202 // This one is the correct expression now
203 a = "here I start a very long string"+...  //but I'm not in the mood of continuing
204     "    - and here I go on"
205 // This expression is not allowed anymore in Scilab 6: scalar number must be written on one line
206 y = 12..
207 45
208  ]]></programlisting>
209     </refsection>
210     <refsection role="see also">
211         <title>See Also</title>
212         <simplelist type="inline">
213             <member>
214                 <link linkend="star">star</link>
215             </member>
216             <member>
217                 <link linkend="hat">hat</link>
218             </member>
219             <member>
220                 <link linkend="slash">slash</link>
221             </member>
222             <member>
223                 <link linkend="backslash">backslash</link>
224             </member>
225             <member>
226                 <link linkend="whereami">whereami</link>
227             </member>
228             <member>
229                 <link linkend="edit">edit</link>
230             </member>
231         </simplelist>
232     </refsection>
233     <refsection>
234         <title>History</title>
235         <revhistory>
236             <revision>
237                 <revnumber>6.0.0</revnumber>
238                 <revremark>
239                     <para>
240                         It is not possible anymore to cut a scalar number.
241                     </para>
242                     <para>
243                         To cut a single string, "+.." operators must be used.
244                     </para>
245                     <para>
246                         In console-oriented calls, <literal>myfun ..</literal> no longer expects
247                         a continuation on the next line.
248                     </para>
249                 </revremark>
250             </revision>
251         </revhistory>
252     </refsection>
253 </refentry>