<?xml version="1.0" encoding="UTF-8"?>
<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">
    <refnamediv>
        <refname>dot</refname>
        <refpurpose>(.) symbol</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            123.33

            a.*b
            a .*. b

            %pi * (%e + ..
            %i)

            cd ..
            dir ..
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Description</title>
        <variablelist>
            <varlistentry>
                <term>.</term>
                <listitem>
                    <para>Dot is used to mark decimal point for numbers : 3.25 and
                        0.001
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>.&lt;op&gt;</term>
                <listitem>
                    <para>
                        used in conjunction with other operator symbols (<literal>*/ \ ^ '</literal>) to form other operators. Element-by-element
                        multiplicative operations are obtained using <literal> .* , .^ , ./ , .\</literal>
                        or <literal>.'</literal>. For example,  <literal>C = A ./ B</literal> is
                        the matrix with elements <literal>c(i,j) = a(i,j)/b(i,j)</literal>. Kronecker product
                        is noted <literal>.*.</literal> .
                    </para>
                    <para>
                        <note>
                            Note that when dot is used with an operation, it is not considered part of the number directly preceding the dot,
                            therefore <literal>2.*x</literal> and <literal>2 .*x</literal> are evaluated
                            as <literal>(2).*x</literal> and not as <literal>2.0*x</literal>.
                        </note>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>..</term>
                <listitem>
                    <para>Continuation mark. Two or more dots at the end of a
                        line (or followed by a comment) causes the following line to be a
                        continuation.
                    </para>
                    <para>Continuation lines are handled by a preprocessor which builds
                        a long logical line from a sequence of continuation lines. So the
                        continuation marks can be used to cut a line at any point.
                    </para>
                    <para>
                        The following function <literal>foo</literal>:
                    </para>
                    <programlisting role=""><![CDATA[
function foo()
    plot2d()
    xtitle(["General title"; "It can be multiline, so quite long"], ..
            "This is the X-axis title", "Y title")
endfunction
 ]]></programlisting>
                    <para>is equivalent to:</para>
                    <programlisting role=""><![CDATA[
function foo()
    plot2d()

    xtitle(["General title"; "It can be multiline, so quite long"], "This is the X-axis title", "Y title")
endfunction
 ]]></programlisting>
                    <para>The logical line formed by physical line 3 and physical line 4
                        is built as if it was entirely written in the physical line 4 while
                        physical line 3 would be empty. This is done this way because
                        continuation marks can be put anywhere even inside an
                        expression.
                        <note>The difference between logical and physical
                            lines is of importance when dealing with edition (scinotes, edit)
                            and within error messages
                            (whereami), when the line number is provided or displayed.
                        </note>
                    </para>
                    <para>
                        There are exceptions to this rule in a matrix environment to ease up
                        readibility of scilab scripts. The following example shows some differences
                        between the matrix and non matrix environment.
                    </para>
                    <programlisting role=""><![CDATA[
// In the matrix environment .. is a continuation of the line
// except on some cases where readibility is important

// my_matrix == [1 2 3 -4 5 6]
my_matrix = [ 1 2 3 -4 5 6] // the minus sign here is unary

// my_matrix == [1 2 -1 5 6]
my_matrix = [ 1 2 3 -... // minus separated by .. is always considered a binary operation
4 5 6]
                     ]]></programlisting>

                    <para>
                        An error is generated if the continuation mark is inside a language token, variable name, reserved word.
                    </para>
                    <programlisting role=""><![CDATA[
// this is possible is Scilab
for a_word = 1:10
    disp("test " + string(a_word))
end


// This generate an error
for a_...
word = 1:10
    disp("test " + string(a_word))
end
// Scilab cannot parse this line
                    ]]></programlisting>
                    <para>
                        An error is generated if any word except a comment is found after the continuation mark.
                    </para>

                    <programlisting role=""><![CDATA[
this_wont_work = 3 + ... 4 // Scilab cannot parse this

this_wont_work_either = 3 + ... /* a multiline comment
followed by some text */ 4

this_works = 3 + ... /* a multiline comment
followed by text and a newline */
4
                     ]]></programlisting>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>".." parameter</term>
                <listitem>
                    <para>
                        When functions are used in a console-oriented way, <literal>..</literal>
                        is not considered as a continuation mark but as a simple argument. The most
                        common usage is with <literal>cd ..</literal>, <literal>dir ..</literal>
                        or <literal>ls ..</literal> actually standing for <literal>cd("..")</literal>,
                        etc.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
//decimal point
1.345

//used as part of an operator
x = [1 2 3]; x .^2 .*x // a space is not required between 2 and dot

// When writing rows of a matrix on different lines, ".." can be used but are not mandatory.
N_row = [   ..
    63.    89.    3.   ..
    91.    56.    22.  ..
    15.    64.    40.  ..
    ]
// Without the continuation mark, the matrix is read row by row:
N_square = [
    63.    89.    3.
    91.    56.    22.
    15.    64.    40.
    ]

// Within very long instructions like when creating uicontrol where many properties must be set,
// continuation marks are almost mandatory and allow to write and set one property per line
// in a readable way. A single huge line would not comply with Scilab coding style:
fig = figure("figure_name", "FIGURE", ..
             "dockable",    "off", ..
             "axes_size",   [990,670], ..
             "infobar_visible", "off", ..
             "toolbar",     "none", ..
             "menubar_visible", "on", ..
             "menubar",     "none", ..
             "default_axes","off", ..
             "layout",      "border", ..
             "background",  color(244,244,244), ..
             "tag",         "figure_1", ..
             "visible",     "on");

// Console-oriented calls with some ".." argument
d = pwd(); cd SCI/contrib
cd ..   // stands for cd("..") and expects nothing on the next line
cd(d)   // Go back to your working directory

// This expression does not work anymore in Scilab 6
a = "here I start a very long string...  //but I'm not in the mood of continuing
     - and here I go on"
// This one is the correct expression now
a = "here I start a very long string"+...  //but I'm not in the mood of continuing
    "    - and here I go on"
// This expression is not allowed anymore in Scilab 6: scalar number must be written on one line
y = 12..
45
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="star">star</link>
            </member>
            <member>
                <link linkend="hat">hat</link>
            </member>
            <member>
                <link linkend="slash">slash</link>
            </member>
            <member>
                <link linkend="backslash">backslash</link>
            </member>
            <member>
                <link linkend="whereami">whereami</link>
            </member>
            <member>
                <link linkend="edit">edit</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>6.0.0</revnumber>
                <revremark>
                    <para>
                        It is not possible anymore to cut a scalar number.
                    </para>
                    <para>
                        To cut a single string, "+.." operators must be used.
                    </para>
                    <para>
                        In console-oriented calls, <literal>myfun ..</literal> no longer expects
                        a continuation on the next line.
                    </para>
                </revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
