<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA - Fabrice Leray
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<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="LineSpec">
    <refnamediv>
        <refname>LineSpec</refname>
        <refpurpose>to quickly customize the lines appearance
            in a plot
        </refpurpose>
    </refnamediv>
    <refsection>
        <title>Description</title>
        <para>
            The <literal>LineSpec</literal> is an optional argument
            that can be used inside a <function>plot</function>
            command to customize each new line aspect. It has to
            be given as a concatenated string containing information
            about color, line style or markers. It is very useful to
            quickly specify such basic line properties.
        </para>
        <para>
            To specify a red longdash-dot with diamond marker, the
            string can be <literal>'r-.diam'</literal>. As you can
            see, a full complete spelling of each property value is
            not required but the string, which is a concatenation
            (in any order) of these three types of properties, must
            remain unambiguous. Furthermore, the string specification
            is not case sensitive.
        </para>
        <para>
            Here is a complete list of the <literal>LineSpec</literal>
            types you can specify (using <link linkend="plot">plot</link>).
        </para>
        <variablelist>
            <varlistentry>
                <term>LineStyle: </term>
                <listitem>
                    <para>
                        a string defining the line style. This property is linked to the
                        object's <literal>line_style</literal> property (see
                        <link linkend="polyline_properties">polyline properties</link>).
                    </para>
                    <para/>
                    <informaltable border="1">
                        <tr>
                            <td>
                                <literal>Specifier</literal>
                            </td>
                            <td>
                                <literal>Line Style</literal>
                            </td>
                        </tr>
                        <tr>
                            <td>
                                <literal>-</literal>
                            </td>
                            <td>Solid line (default)</td>
                        </tr>
                        <tr>
                            <td>
                                <literal>--</literal>
                            </td>
                            <td>Dashed line</td>
                        </tr>
                        <tr>
                            <td>
                                <literal>:</literal>
                            </td>
                            <td>Dotted line</td>
                        </tr>
                        <tr>
                            <td>
                                <literal>-.</literal>
                            </td>
                            <td>Dash-dotted line</td>
                        </tr>
                    </informaltable>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Color: </term>
                <listitem>
                    <para>
                        a string defining the line color. This property is linked to the
                        object's <literal>foreground</literal> property (see
                        <link linkend="polyline_properties">polyline properties</link>).
                    </para>
                    <para/>
                    <informaltable border="1">
                        <tr>
                            <td>
                                <literal>Specifier</literal>
                            </td>
                            <td>
                                <literal>Color</literal>
                            </td>
                        </tr>
                        <tr>
                            <td>
                                <literal>r</literal>
                            </td>
                            <td>Red</td>
                        </tr>
                        <tr>
                            <td>
                                <literal>g</literal>
                            </td>
                            <td>Green</td>
                        </tr>
                        <tr>
                            <td>
                                <literal>b</literal>
                            </td>
                            <td>Blue</td>
                        </tr>
                        <tr>
                            <td>
                                <literal>c</literal>
                            </td>
                            <td>Cyan</td>
                        </tr>
                        <tr>
                            <td>
                                <literal>m</literal>
                            </td>
                            <td>Magenta</td>
                        </tr>
                        <tr>
                            <td>
                                <literal>y</literal>
                            </td>
                            <td>Yellow</td>
                        </tr>
                        <tr>
                            <td>
                                <literal>k</literal>
                            </td>
                            <td>Black</td>
                        </tr>
                        <tr>
                            <td>
                                <literal>w</literal>
                            </td>
                            <td>White</td>
                        </tr>
                    </informaltable>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term/>
                <listitem>
                    <para>
                        A default color table is used to color plotted curves if you do
                        not specify a color (neither with <literal>LineSpec</literal> nor with
                        <link linkend="GlobalProperty">GlobalProperty</link>). When drawing
                        multiple lines, the plot command automatically cycles through
                        this table. Here are the used colors:
                    </para>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term/>
                <listitem>
                    <informaltable border="1">
                        <tr>
                            <td>
                                <literal>R</literal>
                            </td>
                            <td>
                                <literal>G</literal>
                            </td>
                            <td>
                                <literal>B</literal>
                            </td>
                        </tr>
                        <tr>
                            <td>0.</td>
                            <td>0.</td>
                            <td>1.</td>
                        </tr>
                        <tr>
                            <td>0.</td>
                            <td>0.5</td>
                            <td>0.</td>
                        </tr>
                        <tr>
                            <td>1.</td>
                            <td>0.</td>
                            <td>0.</td>
                        </tr>
                        <tr>
                            <td>0.</td>
                            <td>0.75</td>
                            <td>0.75</td>
                        </tr>
                        <tr>
                            <td>0.75</td>
                            <td>0.</td>
                            <td>0.75</td>
                        </tr>
                        <tr>
                            <td>0.75</td>
                            <td>0.75</td>
                            <td>0.</td>
                        </tr>
                        <tr>
                            <td>0.25</td>
                            <td>0.25</td>
                            <td>0.25</td>
                        </tr>
                    </informaltable>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Marker type: </term>
                <listitem>
                    <para>
                        A string defining the marker type. Note that if you specify a
                        marker without a line style, only the marker is drawn. This property
                        is linked to the object's <literal>mark_style</literal> and
                        <literal>mark_mode</literal> properties (see
                        <link linkend="polyline_properties">polyline properties</link>).
                    </para>
                    <para/>
                    <informaltable border="1">
                        <tr>
                            <td>
                                <literal>Specifier</literal>
                            </td>
                            <td>
                                <literal>Marker Type</literal>
                            </td>
                        </tr>
                        <tr>
                            <td>
                                <literal>+</literal>
                            </td>
                            <td>Plus sign</td>
                        </tr>
                        <tr>
                            <td>
                                <literal>o</literal>
                            </td>
                            <td>Circle</td>
                        </tr>
                        <tr>
                            <td>
                                <literal>*</literal>
                            </td>
                            <td>Asterisk</td>
                        </tr>
                        <tr>
                            <td>
                                <literal>.</literal>
                            </td>
                            <td>Point</td>
                        </tr>
                        <tr>
                            <td>
                                <literal>x</literal>
                            </td>
                            <td>Cross</td>
                        </tr>
                        <tr>
                            <td>
                                <literal>'square'</literal> or
                                <literal>'s'</literal>
                            </td>
                            <td>Square</td>
                        </tr>
                        <tr>
                            <td>
                                <literal>'diamond'</literal> or
                                <literal>'d'</literal>
                            </td>
                            <td>Diamond</td>
                        </tr>
                        <tr>
                            <td>
                                <literal>^</literal>
                            </td>
                            <td>Upward-pointing triangle</td>
                        </tr>
                        <tr>
                            <td>
                                <literal>v</literal>
                            </td>
                            <td>Downward-pointing triangle</td>
                        </tr>
                        <tr>
                            <td>
                                <literal>&gt;</literal>
                            </td>
                            <td>Right-pointing triangle</td>
                        </tr>
                        <tr>
                            <td>
                                <literal>&lt;</literal>
                            </td>
                            <td>Left-pointing triangle</td>
                        </tr>
                        <tr>
                            <td>
                                <literal>'pentagram' or 'p'</literal>
                            </td>
                            <td>Five-pointed star (pentagram)</td>
                        </tr>
                        <tr>
                            <td>
                            </td>
                            <td>No marker (default)</td>
                        </tr>
                    </informaltable>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
clf();
x=1:0.1:10; // Init.
plot(x,sin(x),'r-.>') // plots a dash-dotted line with a right-pointing triangle centered on each points.
 ]]></programlisting>
        <scilab:image>x=1:0.1:10; // Init.
            plot(x,sin(x),'r.-&gt;')
            t=0:%pi/20:2*%pi;
            plot(t,sin(t),'ro-.',t,cos(t),'cya+',t,abs(sin(t)),'--mo')
        </scilab:image>
        <programlisting role="example"><![CDATA[
clf();
x=1:0.1:10;
// If you specify a marker without a line style, only the marker is drawn
plot(x,sin(x),'d')
 ]]></programlisting>
        <scilab:image>
            x=1:0.1:10;
            plot(x,sin(x),'d')
        </scilab:image>
        <programlisting role="example"><![CDATA[
clf();
x = 1:0.5:10; // Init.
// The order of information about color, line style or markers does not matter
// BUT the information must be unambiguous
subplot(311);plot(x,sin(x),'.b-');
subplot(312);plot(x,sin(x),'b.-');
subplot(313);plot(x,sin(x),'b-.');// The point belongs to information about line style (not marker!)

 ]]></programlisting>
        <scilab:image>
            x = 1:0.5:10;
            subplot(311);plot(x,sin(x),'.b-');
            subplot(312);plot(x,sin(x),'b.-');
            subplot(313);plot(x,sin(x),'b-.');
        </scilab:image>
        <programlisting role="example"><![CDATA[
//multiple plots with different LineSpecs
clf();
t=0:%pi/20:2*%pi;
plot(t,sin(t),'ro-.',t,cos(t),'cya+',t,abs(sin(t)),'--mo')
 ]]></programlisting>
        <scilab:image>
            t=0:%pi/20:2*%pi;
            plot(t,sin(t),'ro-.',t,cos(t),'cya+',t,abs(sin(t)),'--mo')
        </scilab:image>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="color">color</link>
            </member>
            <member>
                <link linkend="GlobalProperty">GlobalProperty</link>
            </member>
            <member>
                <link linkend="plot">plot</link>
            </member>
            <member>
                <link linkend="clf">clf</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
