Update dot help pages
[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>Calling Sequence</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 follows a number it is always a part
46                             of the number so <literal>2.*x</literal> is evaluated as <literal>2.0*x</literal> and <literal>2 .*x</literal> is evaluated
47                             as <literal>(2).*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), with
88                         profiling (profile, showprofile, plotprofile), and within error messages
89                         (whereami), when the line number is provided or displayed.
90                         </note>
91                     </para>
92                 </listitem>
93             </varlistentry>
94             <varlistentry>
95                 <term>".." parameter</term>
96                 <listitem>
97                     <para>When functions are used in a console-oriented way, <literal>..</literal>
98                         is not considered as a continuation mark but as a simple argument. The most
99                         common usage is with <literal>cd ..</literal>, <literal>dir ..</literal>
100                         or <literal>ls ..</literal> actually standing for <literal>cd("..")</literal>,
101                         etc.
102                     </para>
103                 </listitem>
104             </varlistentry>
105         </variablelist>
106     </refsection>
107     <refsection>
108         <title>Examples</title>
109         <programlisting role="example"><![CDATA[ 
110 //decimal point
111 1.345
112
113 //used as part of an operator
114 x = [1 2 3];x.^2 .*x // a space is required between 2 and dot
115
116 // When writing rows of a matrix on different lines, ".." can be used but are not mandatory.
117 N = [   ..
118     63.    89.    3.   ..
119     91.    56.    22.  ..
120     15.    64.    40.  ..
121     ]
122 // It can be more simply entered as (or copied/pasted from/to console or script), without appending ".."
123 N = [
124     63.    89.    3.
125     91.    56.    22.
126     15.    64.    40.
127     ]
128
129 // Within very long instructions like when creating uicontrol where many properties must be set,
130 // continuation marks are almost mandatory and allow to write and set one property per line
131 // in a readable way. A single huge line would not comply with Scilab coding style:
132 fig = figure("figure_name", "FIGURE", ..
133              "dockable",    "off", ..
134              "axes_size",   [990,670], ..
135              "infobar_visible", "off", ..
136              "toolbar",     "none", ..
137              "menubar_visible", "on", ..
138              "menubar",     "none", ..
139              "default_axes","off", ..
140              "layout",      "border", ..
141              "background",  color(244,244,244), ..
142              "tag",         "figure_1", ..
143              "visible",     "on");
144
145 // Console-oriented calls with some ".." argument
146 d = pwd(); cd SCI/contrib
147 cd ..   // stands for cd("..") and expects nothing on the next line
148 cd(d)   // Go back to your working directory
149
150 // This expression does not work anymore in Scilab 6
151 a = "here I start a very long string...  //but I'm not in the mood of continuing
152      - and here I go on"
153 // This one is the correct expression now
154 a = "here I start a very long string"+...  //but I'm not in the mood of continuing
155     "    - and here I go on"
156 // This expression is not allowed anymore in Scilab 6: scalar number must be written on one line
157 y = 12..
158 45
159  ]]></programlisting>
160     </refsection>
161     <refsection role="see also">
162         <title>See Also</title>
163         <simplelist type="inline">
164             <member>
165                 <link linkend="star">star</link>
166             </member>
167             <member>
168                 <link linkend="hat">hat</link>
169             </member>
170             <member>
171                 <link linkend="slash">slash</link>
172             </member>
173             <member>
174                 <link linkend="backslash">backslash</link>
175             </member>
176             <member>
177                 <link linkend="whereami">whereami</link>
178             </member>
179             <member>
180                 <link linkend="showprofile">showprofile</link>
181             </member>
182             <member>
183                 <link linkend="edit">edit</link>
184             </member>
185         </simplelist>
186     </refsection>
187     <refsection>
188         <title>History</title>
189         <revhistory>
190             <revision>
191                 <revnumber>6.0.0</revnumber>
192                 <revremark>
193                     <para>
194                         It is not possible anymore to cut a scalar number.
195                     </para>
196                     <para>
197                         To cut a single string, "+.." operators must be used.
198                     </para>
199                     <para>In console-oriented calls, <literal>myfun ..</literal> no longer expects
200                         a continuation on the next line.
201                     </para>
202                 </revremark>
203             </revision>
204         </revhistory>
205     </refsection>
206 </refentry>