Fix a typo
[scilab.git] / scilab / modules / graphics / help / en_US / 2d_plot / LineSpec.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) INRIA - Fabrice Leray
5  * 
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at    
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  *
12  -->
13 <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">
14     <refnamediv>
15         <refname>LineSpec</refname>
16         <refpurpose>to quickly customize the lines appearance
17             in a plot
18         </refpurpose>
19     </refnamediv>
20     <refsection>
21         <title>Description</title>
22         <para>The LineSpec is an optional argument that can be used inside a plot 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>
23         <para>To specify a red longdash-dot with diamond marker, the string can be 'r-.diam'. 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>
24         <para>
25             Here is a complete list of the <literal>LineSpec</literal> types you can
26             specify (using <link linkend="plot">plot</link>).
27         </para>
28         <variablelist>
29             <varlistentry>
30                 <term>LineStyle: </term>
31                 <listitem>
32                     <para>a string defining the line style. This property is linked to the
33                         object's <literal>line_style</literal> property (see
34                         <link linkend="polyline_properties">polyline_properties</link>).
35                     </para>
36                     <para/>
37                     <informaltable border="1">
38                         <tr>
39                             <td>
40                                 <literal>Specifier</literal>
41                             </td>
42                             <td>
43                                 <literal>Line Style</literal>
44                             </td>
45                         </tr>
46                         <tr>
47                             <td>
48                                 <literal>-</literal>
49                             </td>
50                             <td>Solid line (default)</td>
51                         </tr>
52                         <tr>
53                             <td>
54                                 <literal>--</literal>
55                             </td>
56                             <td>Dashed line</td>
57                         </tr>
58                         <tr>
59                             <td>
60                                 <literal>:</literal>
61                             </td>
62                             <td>Dotted line</td>
63                         </tr>
64                         <tr>
65                             <td>
66                                 <literal>-.</literal>
67                             </td>
68                             <td>Dash-dotted line</td>
69                         </tr>
70                     </informaltable>
71                 </listitem>
72             </varlistentry>
73             <varlistentry>
74                 <term>Color: </term>
75                 <listitem>
76                     <para>a string defining the line color. This property is linked to the
77                         object's <literal>foreground</literal> property (see
78                         <link linkend="polyline_properties">polyline_properties</link>).
79                     </para>
80                     <para/>
81                     <informaltable border="1">
82                         <tr>
83                             <td>
84                                 <literal>Specifier</literal>
85                             </td>
86                             <td>
87                                 <literal>Color</literal>
88                             </td>
89                         </tr>
90                         <tr>
91                             <td>
92                                 <literal>r</literal>
93                             </td>
94                             <td>Red</td>
95                         </tr>
96                         <tr>
97                             <td>
98                                 <literal>g</literal>
99                             </td>
100                             <td>Green</td>
101                         </tr>
102                         <tr>
103                             <td>
104                                 <literal>b</literal>
105                             </td>
106                             <td>Blue</td>
107                         </tr>
108                         <tr>
109                             <td>
110                                 <literal>c</literal>
111                             </td>
112                             <td>Cyan</td>
113                         </tr>
114                         <tr>
115                             <td>
116                                 <literal>m</literal>
117                             </td>
118                             <td>Magenta</td>
119                         </tr>
120                         <tr>
121                             <td>
122                                 <literal>y</literal>
123                             </td>
124                             <td>Yellow</td>
125                         </tr>
126                         <tr>
127                             <td>
128                                 <literal>k</literal>
129                             </td>
130                             <td>Black</td>
131                         </tr>
132                         <tr>
133                             <td>
134                                 <literal>w</literal>
135                             </td>
136                             <td>White</td>
137                         </tr>
138                     </informaltable>
139                 </listitem>
140             </varlistentry>
141             <varlistentry>
142                 <term/>
143                 <listitem>
144                     <para>A default color table is used to color plotted curves if you do
145                         not specify a color (neither with <literal>LineSpec</literal> nor with
146                         <link linkend="GlobalProperty">GlobalProperty</link>). When drawing multiple lines, the plot
147                         command automatically cycles through this table. Here are the used
148                         colors:
149                     </para>
150                     <para/>
151                 </listitem>
152             </varlistentry>
153             <varlistentry>
154                 <term/>
155                 <listitem>
156                     <informaltable border="1">
157                         <tr>
158                             <td>
159                                 <literal>R</literal>
160                             </td>
161                             <td>
162                                 <literal>G</literal>
163                             </td>
164                             <td>
165                                 <literal>B</literal>
166                             </td>
167                         </tr>
168                         <tr>
169                             <td>0.</td>
170                             <td>0.</td>
171                             <td>1.</td>
172                         </tr>
173                         <tr>
174                             <td>0.</td>
175                             <td>0.5</td>
176                             <td>0.</td>
177                         </tr>
178                         <tr>
179                             <td>1.</td>
180                             <td>0.</td>
181                             <td>0.</td>
182                         </tr>
183                         <tr>
184                             <td>0.</td>
185                             <td>0.75</td>
186                             <td>0.75</td>
187                         </tr>
188                         <tr>
189                             <td>0.75</td>
190                             <td>0.</td>
191                             <td>0.75</td>
192                         </tr>
193                         <tr>
194                             <td>0.75</td>
195                             <td>0.75</td>
196                             <td>0.</td>
197                         </tr>
198                         <tr>
199                             <td>0.25</td>
200                             <td>0.25</td>
201                             <td>0.25</td>
202                         </tr>
203                     </informaltable>
204                 </listitem>
205             </varlistentry>
206             <varlistentry>
207                 <term>Marker type: </term>
208                 <listitem>
209                     <para>A string defining the marker type. note that if you specify a
210                         marker without a line style, only the marker is drawn. This property
211                         is linked to the object's <literal>mark_style</literal> and
212                         <literal>mark_mode</literal> properties (see
213                         <link linkend="polyline_properties">polyline_properties</link>).
214                     </para>
215                     <para/>
216                     <informaltable border="1">
217                         <tr>
218                             <td>
219                                 <literal>Specifier</literal>
220                             </td>
221                             <td>
222                                 <literal>Marker Type</literal>
223                             </td>
224                         </tr>
225                         <tr>
226                             <td>
227                                 <literal>+</literal>
228                             </td>
229                             <td>Plus sign</td>
230                         </tr>
231                         <tr>
232                             <td>
233                                 <literal>o</literal>
234                             </td>
235                             <td>Circle</td>
236                         </tr>
237                         <tr>
238                             <td>
239                                 <literal>*</literal>
240                             </td>
241                             <td>Asterisk</td>
242                         </tr>
243                         <tr>
244                             <td>
245                                 <literal>.</literal>
246                             </td>
247                             <td>Point</td>
248                         </tr>
249                         <tr>
250                             <td>
251                                 <literal>x</literal>
252                             </td>
253                             <td>Cross</td>
254                         </tr>
255                         <tr>
256                             <td>
257                                 <literal>'square'</literal> or
258                                 <literal>'s'</literal>
259                             </td>
260                             <td>Square</td>
261                         </tr>
262                         <tr>
263                             <td>
264                                 <literal>'diamond'</literal> or
265                                 <literal>'d'</literal>
266                             </td>
267                             <td>Diamond</td>
268                         </tr>
269                         <tr>
270                             <td>
271                                 <literal>^</literal>
272                             </td>
273                             <td>Upward-pointing triangle</td>
274                         </tr>
275                         <tr>
276                             <td>
277                                 <literal>v</literal>
278                             </td>
279                             <td>Downward-pointing triangle</td>
280                         </tr>
281                         <tr>
282                             <td>
283                                 <literal>&gt;</literal>
284                             </td>
285                             <td>Right-pointing triangle</td>
286                         </tr>
287                         <tr>
288                             <td>
289                                 <literal>&lt;</literal>
290                             </td>
291                             <td>Left-pointing triangle</td>
292                         </tr>
293                         <tr>
294                             <td>
295                                 <literal>'pentagram'</literal>
296                             </td>
297                             <td>Five-pointed star (pentagram)</td>
298                         </tr>
299                         <tr>
300                             <td>
301                                 <literal>'none'</literal>
302                             </td>
303                             <td>No marker (default)</td>
304                         </tr>
305                     </informaltable>
306                 </listitem>
307             </varlistentry>
308         </variablelist>
309     </refsection>
310     <refsection>
311         <title>Examples</title>
312         <programlisting role="example"><![CDATA[ 
313 x=1:0.1:10; // Init.
314 plot(x,sin(x),'r.->') // plots a dash-dotted line with a right-pointing triangle centered on each points.
315  ]]></programlisting>
316         <scilab:image>
317             x=1:0.1:10;
318             plot(x,sin(x),'r.->')
319         </scilab:image>
320         <programlisting role="example"><![CDATA[
321 clf();
322 x=1:0.1:10;
323 // If you specify a marker without a line style, only the marker is drawn
324 plot(x,sin(x),'d') // plots a dash-dotted line with a right-pointing triangle centered on each points.
325  ]]></programlisting>
326         <scilab:image>
327             x=1:0.1:10;
328             plot(x,sin(x),'d')
329         </scilab:image>
330         <programlisting role="example"><![CDATA[ 
331 x=1:10; // Init.
332 // combinations' order does not matter
333 plot(x,x.*x,'*cya--') 
334  ]]></programlisting>
335         <scilab:image>
336             x=1:10;
337             plot(x,x.*x,'*cya--')
338         </scilab:image>
339         <programlisting role="example"><![CDATA[ 
340 //multiple plots with different LineSpecs
341 clf();
342 t=0:%pi/20:2*%pi;
343 plot(t,sin(t),'ro-.',t,cos(t),'cya+',t,abs(sin(t)),'--mo')
344  ]]></programlisting>
345         <scilab:image>x=1:0.1:10;
346             plot(x,sin(x),'r.-&gt;')
347             t=0:%pi/20:2*%pi;
348             plot(t,sin(t),'ro-.',t,cos(t),'cya+',t,abs(sin(t)),'--mo')
349         </scilab:image>
350     </refsection>
351     <refsection role="see also">
352         <title>See Also</title>
353         <simplelist type="inline">
354             <member>
355                 <link linkend="GlobalProperty">GlobalProperty</link>
356             </member>
357             <member>
358                 <link linkend="plot">plot</link>
359             </member>
360             <member>
361                 <link linkend="clf">clf</link>
362             </member>
363         </simplelist>
364     </refsection>
365 </refentry>