Graphics tests: fix histrogram references
[scilab.git] / scilab / modules / graphics / help / en_US / bar_histogram / bar.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 - Farid Belahcene
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.1-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="bar">
14     <refnamediv>
15         <refname>bar</refname>
16         <refpurpose>bar histogram</refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>Calling Sequence</title>
20         <synopsis>bar(y)
21             bar(x,y)
22             bar([h],x,y [,width [,color [,style]]])
23         </synopsis>
24     </refsynopsisdiv>
25     <refsection>
26         <title>Arguments</title>
27         <variablelist>
28             <varlistentry>
29                 <term>h</term>
30                 <listitem>
31                     <para>an axes handle, (default: h=gca() ).</para>
32                 </listitem>
33             </varlistentry>
34             <varlistentry>
35                 <term>y</term>
36                 <listitem>
37                     <para>a real scalar, vector of size N, or a matrice N*M.</para>
38                 </listitem>
39             </varlistentry>
40             <varlistentry>
41                 <term>x</term>
42                 <listitem>
43                     <para>a real scalar or a vector of size N, (default: if y is a
44                         vector then x is a vector and x length equals to y length. If y is a
45                         matrix then x is a vector and x length equals to the lines number of
46                         y.
47                     </para>
48                 </listitem>
49             </varlistentry>
50             <varlistentry>
51                 <term>width</term>
52                 <listitem>
53                     <para>(optional), a real scalar, defines the width (a percentage of
54                         the available room) for the bar (default: 0.8, i.e 80%).
55                     </para>
56                 </listitem>
57             </varlistentry>
58             <varlistentry>
59                 <term>color</term>
60                 <listitem>
61                     <para>(optional), a string (default: 'blue'), specifying the inside
62                         color bar.
63                     </para>
64                 </listitem>
65             </varlistentry>
66             <varlistentry>
67                 <term>style:</term>
68                 <listitem>
69                     <para>a string, 'grouped' or 'stacked' (default: 'grouped').</para>
70                 </listitem>
71             </varlistentry>
72         </variablelist>
73     </refsection>
74     <refsection>
75         <title>Description</title>
76         <para>
77             <literal>bar(y,...) :</literal> if y is a vector then bar function draws a
78             polyline which has the <literal>polyline_style</literal> type 6. If y is a
79             vector, bar draws vector y versus vector 1:size(y,'*') . If y is a matrix
80             N*M, bar draws M polylines (type 6), each polyline corresponds to a column
81             of y versus vector x=1:size(y,1).
82         </para>
83         <para>
84             <literal>bar(x,y,...) :</literal> if y is a vector then bar function draws a
85             polyline which has the <literal>polyline_style</literal> type 6, where x length
86             = y length.If y is a matrix NxM then bar function draws M polylines which
87             have the type 6. Each polyline corresponds to a column of y versus vector
88             x.
89         </para>
90         <para>
91             <literal>bar(h,...) :</literal> defines the current axes where the drawing is
92             performed.
93         </para>
94         <para>
95             <literal>bar(...,width,...) :</literal> defines the width of the bar(s) in
96             percentage (generally: 0&lt;width&lt;=1).
97         </para>
98         <para>
99             <literal>bar(...,style,...) :</literal> defines how the bar is drawn. If y is
100             a matrix N*M (so M polylines of type 6) then there are two ways to draw
101             the M bars. the style option = 'grouped' allows to center the M polylines
102             versus each components of x, and the style option 'stacked' allows to
103             stack them.
104         </para>
105         <para>
106             <literal>bar(...,color,...) : </literal>defines the bar color. Bar functions
107             uses the same colormap than in the <literal>plot</literal> function.
108         </para>
109         <para>
110             If there are several bar calls, the <literal>barhomogenize</literal> function
111             allows to homegenize the width and style of all bars (i.e polylines of
112             type 6) included in the current working axes.
113         </para>
114     </refsection>
115     <refsection>
116         <title>Examples</title>
117         <programlisting role="example"><![CDATA[
118 // First example: draw a bar (i.e a polyline with polyline_style type =6) with
119 // width=0.5 and color='yellow' and default style='grouped', x=1:length(y).
120 scf(0);
121 y=[1 -3 5];
122 bar(y,0.5,'yellow');
123  ]]></programlisting>
124         <scilab:image>
125             y=[1 -3 5];
126             bar(y,0.5,'yellow');
127         </scilab:image>
128         <programlisting role="example"><![CDATA[
129
130 // Second example: draw 3 bars (i.e 3 polylines with polyline_style type =6),default style='grouped'
131 scf(1);
132 x=[1 2 5];
133 y=[1  -5 6;3 -2 7;4  -3 8];
134 bar(x,y);
135  ]]></programlisting>
136         <scilab:image>
137             x=[1 2 5];
138             y=[1  -5 6;3 -2 7;4  -3 8];
139             bar(x,y);
140         </scilab:image>
141         <programlisting role="example"><![CDATA[
142 // Third example : style='stacked'.
143 scf(2);
144 x=[1 2 5];
145 y=[1 4 7;2 5 8;3 6  9];
146 bar(x,y,'stacked');
147  ]]></programlisting>
148         <scilab:image>
149             x=[1 2 5];
150             y=[1 4 7;2 5 8;3 6  9];
151             bar(x,y,'stacked');
152         </scilab:image>
153         <programlisting role="example"><![CDATA[
154 // Fourth example: width=0.2;color='green'; default style='grouped'
155 scf(3);
156 x=[1 2 5];
157 y=[1 4 7;2 5 8;3 6 9];
158 bar(x,y,0.2,'green');
159  ]]></programlisting>
160         <scilab:image>
161             x=[1 2 5];
162             y=[1 4 7;2 5 8;3 6 9];
163             bar(x,y,0.2,'green');
164         </scilab:image>
165     </refsection>
166     <refsection role="see also">
167         <title>See Also</title>
168         <simplelist type="inline">
169             <member>
170                 <link linkend="barh">barh</link>
171             </member>
172             <member>
173                 <link linkend="barhomogenize">barhomogenize</link>
174             </member>
175             <member>
176                 <link linkend="plot">plot</link>
177             </member>
178             <member>
179                 <link linkend="histplot">histplot</link>
180             </member>
181             <member>
182                 <link linkend="polyline_properties">polyline_properties</link>
183             </member>
184         </simplelist>
185     </refsection>
186 </refentry>