Code

fddaa85c2dd5f1dda0fe6fd949695a65e07e3ab8
[pkg-rrdtool.git] / doc / rrdgraph_graph.1
1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.08)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings.  \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 .    ds -- \(*W-
28 .    ds PI pi
29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
31 .    ds L" ""
32 .    ds R" ""
33 .    ds C` ""
34 .    ds C' ""
35 'br\}
36 .el\{\
37 .    ds -- \|\(em\|
38 .    ds PI \(*p
39 .    ds L" ``
40 .    ds R" ''
41 'br\}
42 .\"
43 .\" Escape single quotes in literal strings from groff's Unicode transform.
44 .ie \n(.g .ds Aq \(aq
45 .el       .ds Aq '
46 .\"
47 .\" If the F register is turned on, we'll generate index entries on stderr for
48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
50 .\" output yourself in some meaningful fashion.
51 .ie \nF \{\
52 .    de IX
53 .    tm Index:\\$1\t\\n%\t"\\$2"
54 ..
55 .    nr % 0
56 .    rr F
57 .\}
58 .el \{\
59 .    de IX
60 ..
61 .\}
62 .\"
63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
65 .    \" fudge factors for nroff and troff
66 .if n \{\
67 .    ds #H 0
68 .    ds #V .8m
69 .    ds #F .3m
70 .    ds #[ \f1
71 .    ds #] \fP
72 .\}
73 .if t \{\
74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75 .    ds #V .6m
76 .    ds #F 0
77 .    ds #[ \&
78 .    ds #] \&
79 .\}
80 .    \" simple accents for nroff and troff
81 .if n \{\
82 .    ds ' \&
83 .    ds ` \&
84 .    ds ^ \&
85 .    ds , \&
86 .    ds ~ ~
87 .    ds /
88 .\}
89 .if t \{\
90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
96 .\}
97 .    \" troff and (daisy-wheel) nroff accents
98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105 .ds ae a\h'-(\w'a'u*4/10)'e
106 .ds Ae A\h'-(\w'A'u*4/10)'E
107 .    \" corrections for vroff
108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110 .    \" for low resolution devices (crt and lpr)
111 .if \n(.H>23 .if \n(.V>19 \
112 \{\
113 .    ds : e
114 .    ds 8 ss
115 .    ds o a
116 .    ds d- d\h'-1'\(ga
117 .    ds D- D\h'-1'\(hy
118 .    ds th \o'bp'
119 .    ds Th \o'LP'
120 .    ds ae ae
121 .    ds Ae AE
122 .\}
123 .rm #[ #] #H #V #F C
124 .\" ========================================================================
125 .\"
126 .IX Title "RRDGRAPH_GRAPH 1"
127 .TH RRDGRAPH_GRAPH 1 "2009-05-10" "1.3.999" "rrdtool"
128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
129 .\" way too many mistakes in technical documents.
130 .if n .ad l
131 .nh
132 .SH "NAME"
133 rrdgraph_graph \- rrdtool graph command reference
134 .SH "SYNOPSIS"
135 .IX Header "SYNOPSIS"
136 \&\fB\s-1PRINT\s0\fR\fB:\fR\fIvname\fR\fB:\fR\fIformat\fR
137 .PP
138 \&\fB\s-1GPRINT\s0\fR\fB:\fR\fIvname\fR\fB:\fR\fIformat\fR
139 .PP
140 \&\fB\s-1COMMENT\s0\fR\fB:\fR\fItext\fR
141 .PP
142 \&\fB\s-1VRULE\s0\fR\fB:\fR\fItime\fR\fB#\fR\fIcolor\fR[\fB:\fR\fIlegend\fR][\fB:dashes\fR[\fB=\fR\fIon_s\fR[,\fIoff_s\fR[,\fIon_s\fR,\fIoff_s\fR]...]][\fB:dash\-offset=\fR\fIoffset\fR]]
143 .PP
144 \&\fB\s-1HRULE\s0\fR\fB:\fR\fIvalue\fR\fB#\fR\fIcolor\fR[\fB:\fR\fIlegend\fR][\fB:dashes\fR[\fB=\fR\fIon_s\fR[,\fIoff_s\fR[,\fIon_s\fR,\fIoff_s\fR]...]][\fB:dash\-offset=\fR\fIoffset\fR]]
145 .PP
146 \&\fB\s-1LINE\s0\fR[\fIwidth\fR]\fB:\fR\fIvalue\fR[\fB#\fR\fIcolor\fR][\fB:\fR[\fIlegend\fR][\fB:STACK\fR]][\fB:dashes\fR[\fB=\fR\fIon_s\fR[,\fIoff_s\fR[,\fIon_s\fR,\fIoff_s\fR]...]][\fB:dash\-offset=\fR\fIoffset\fR]]
147 .PP
148 \&\fB\s-1AREA\s0\fR\fB:\fR\fIvalue\fR[\fB#\fR\fIcolor\fR][\fB:\fR[\fIlegend\fR][\fB:STACK\fR]]
149 .PP
150 \&\fB\s-1TICK\s0\fR\fB:\fR\fIvname\fR\fB#\fR\fIrrggbb\fR[\fIaa\fR][\fB:\fR\fIfraction\fR[\fB:\fR\fIlegend\fR]]
151 .PP
152 \&\fB\s-1SHIFT\s0\fR\fB:\fR\fIvname\fR\fB:\fR\fIoffset\fR
153 .PP
154 \&\fB\s-1TEXTALIGN\s0\fR\fB:\fR{\fBleft\fR|\fBright\fR|\fBjustified\fR|\fBcenter\fR}
155 .PP
156 \&\fB\s-1PRINT\s0\fR\fB:\fR\fIvname\fR\fB:\fR\fI\s-1CF\s0\fR\fB:\fR\fIformat\fR (deprecated)
157 .PP
158 \&\fB\s-1GPRINT\s0\fR\fB:\fR\fIvname\fR\fB:\fR\fI\s-1CF\s0\fR\fB:\fR\fIformat\fR (deprecated)
159 .PP
160 \&\fB\s-1STACK\s0\fR\fB:\fR\fIvname\fR\fB#\fR\fIcolor\fR[\fB:\fR\fIlegend\fR] (deprecated)
161 .SH "DESCRIPTION"
162 .IX Header "DESCRIPTION"
163 These instructions allow you to generate your image or report.
164 If you don't use any graph elements, no graph is generated.
165 Similarly, no report is generated if you don't use print options.
166 .SS "\s-1PRINT\s0"
167 .IX Subsection "PRINT"
168 \fI\f(BI\s-1PRINT:\s0\fI\fIvname\fI\f(BI:\fI\fIformat\fI[\f(BI:strftime\fI]\fR
169 .IX Subsection "PRINT:vname:format[:strftime]"
170 .PP
171 Depending on the context, either the value component or the time
172 component of a \fB\s-1VDEF\s0\fR is printed using \fIformat\fR. It is an error
173 to specify a \fIvname\fR generated by a \fB\s-1DEF\s0\fR or \fB\s-1CDEF\s0\fR.
174 .PP
175 Any text in \fIformat\fR is printed literally with one exception:
176 The percent character introduces a formatter string. This string
177 can be:
178 .PP
179 For printing values:
180 .IP "\fB%%\fR" 4
181 .IX Item "%%"
182 just prints a literal '%' character
183 .IP "\fB%#.#le\fR" 4
184 .IX Item "%#.#le"
185 prints numbers like 1.2346e+04. The optional integers # denote field
186 width and decimal precision.
187 .IP "\fB%#.#lf\fR" 4
188 .IX Item "%#.#lf"
189 prints numbers like 12345.6789, with optional field width
190 and precision.
191 .ie n .IP "\fB\fB%s\fB\fR" 4
192 .el .IP "\fB\f(CB%s\fB\fR" 4
193 .IX Item "%s"
194 place this after \fB\f(CB%le\fB\fR, \fB\f(CB%lf\fB\fR or \fB\f(CB%lg\fB\fR. This will be replaced by the
195 appropriate \s-1SI\s0 magnitude unit and the value will be scaled
196 accordingly (123456 \-> 123.456 k).
197 .ie n .IP "\fB\fB%S\fB\fR" 4
198 .el .IP "\fB\f(CB%S\fB\fR" 4
199 .IX Item "%S"
200 is similar to \fB\f(CB%s\fB\fR. It does, however, use a previously defined
201 magnitude unit. If there is no such unit yet, it tries to define
202 one (just like \fB\f(CB%s\fB\fR) unless the value is zero, in which case the magnitude
203 unit stays undefined. Thus, formatter strings using \fB\f(CB%S\fB\fR and no \fB\f(CB%s\fB\fR
204 will all use the same magnitude unit except for zero values.
205 .PP
206 If you \s-1PRINT\s0 a \s-1VDEF\s0 value, you can also print the time associated with it by appending the string
207 \&\fB:strftime\fR to the format. Note that rrdtool uses the strftime function of your OSs C library. This means that
208 the conversion specifier may vary. Check the manual page if you are uncertain. The following is a list of
209 conversion specifiers usually supported across the board.
210 .ie n .IP "\fB\fB%a\fB\fR" 4
211 .el .IP "\fB\f(CB%a\fB\fR" 4
212 .IX Item "%a"
213 The abbreviated weekday name according to the current locale.
214 .ie n .IP "\fB\fB%A\fB\fR" 4
215 .el .IP "\fB\f(CB%A\fB\fR" 4
216 .IX Item "%A"
217 The full weekday name according to the current locale.
218 .ie n .IP "\fB\fB%b\fB\fR" 4
219 .el .IP "\fB\f(CB%b\fB\fR" 4
220 .IX Item "%b"
221 The abbreviated month name according to the current locale.
222 .ie n .IP "\fB\fB%B\fB\fR" 4
223 .el .IP "\fB\f(CB%B\fB\fR" 4
224 .IX Item "%B"
225 The full month name according to the current locale.
226 .ie n .IP "\fB\fB%c\fB\fR" 4
227 .el .IP "\fB\f(CB%c\fB\fR" 4
228 .IX Item "%c"
229 The preferred date and time representation for the current locale.
230 .ie n .IP "\fB\fB%d\fB\fR" 4
231 .el .IP "\fB\f(CB%d\fB\fR" 4
232 .IX Item "%d"
233 The day of the month as a decimal number (range 01 to 31).
234 .ie n .IP "\fB\fB%H\fB\fR" 4
235 .el .IP "\fB\f(CB%H\fB\fR" 4
236 .IX Item "%H"
237 The hour as a decimal number using a 24\-hour clock (range 00 to 23).
238 .ie n .IP "\fB\fB%I\fB\fR" 4
239 .el .IP "\fB\f(CB%I\fB\fR" 4
240 .IX Item "%I"
241 The hour as a decimal number using a 12\-hour clock (range 01 to 12).
242 .ie n .IP "\fB\fB%j\fB\fR" 4
243 .el .IP "\fB\f(CB%j\fB\fR" 4
244 .IX Item "%j"
245 The day of the year as a decimal number (range 001 to 366).
246 .ie n .IP "\fB\fB%m\fB\fR" 4
247 .el .IP "\fB\f(CB%m\fB\fR" 4
248 .IX Item "%m"
249 The month as a decimal number (range 01 to 12).
250 .ie n .IP "\fB\fB%M\fB\fR" 4
251 .el .IP "\fB\f(CB%M\fB\fR" 4
252 .IX Item "%M"
253 The minute as a decimal number (range 00 to 59).
254 .ie n .IP "\fB\fB%p\fB\fR" 4
255 .el .IP "\fB\f(CB%p\fB\fR" 4
256 .IX Item "%p"
257 Either `\s-1AM\s0' or `\s-1PM\s0' according to the given time value, or the corresponding
258 strings for the current locale.  Noon is treated as `pm' and midnight as
259 `am'.  Note that in many locales and `pm' notation is unsupported and in
260 such cases \f(CW%p\fR will return an empty string.
261 .ie n .IP "\fB\fB%s\fB\fR" 4
262 .el .IP "\fB\f(CB%s\fB\fR" 4
263 .IX Item "%s"
264 The second as a decimal number (range 00 to 61).
265 .ie n .IP "\fB\fB%S\fB\fR" 4
266 .el .IP "\fB\f(CB%S\fB\fR" 4
267 .IX Item "%S"
268 The seconds since the epoch (1.1.1970) (libc dependant non standard!)
269 .ie n .IP "\fB\fB%U\fB\fR" 4
270 .el .IP "\fB\f(CB%U\fB\fR" 4
271 .IX Item "%U"
272 The  week  number  of  the current year as a decimal number, range 00 to 53, starting with the
273 first Sunday as the first day of week 01. See also \f(CW%V\fR and \f(CW%W\fR.
274 .ie n .IP "\fB\fB%V\fB\fR" 4
275 .el .IP "\fB\f(CB%V\fB\fR" 4
276 .IX Item "%V"
277 The \s-1ISO\s0 8601:1988 week number of the current year as a decimal number, range 01 to  53,  where
278 week  1 is the first week that has at least 4 days in the current year, and with Monday as the
279 first day of the week. See also \f(CW%U\fR and \f(CW%W\fR.
280 .ie n .IP "\fB\fB%w\fB\fR" 4
281 .el .IP "\fB\f(CB%w\fB\fR" 4
282 .IX Item "%w"
283 The day of the week as a decimal, range 0 to 6, Sunday being 0.  See also \f(CW%u\fR.
284 .ie n .IP "\fB\fB%W\fB\fR" 4
285 .el .IP "\fB\f(CB%W\fB\fR" 4
286 .IX Item "%W"
287 The week number of the current year as a decimal number, range 00 to  53,  starting  with  the
288 first Monday as the first day of week 01.
289 .ie n .IP "\fB\fB%x\fB\fR" 4
290 .el .IP "\fB\f(CB%x\fB\fR" 4
291 .IX Item "%x"
292 The preferred date representation for the current locale without the time.
293 .ie n .IP "\fB\fB%X\fB\fR" 4
294 .el .IP "\fB\f(CB%X\fB\fR" 4
295 .IX Item "%X"
296 The preferred time representation for the current locale without the date.
297 .ie n .IP "\fB\fB%y\fB\fR" 4
298 .el .IP "\fB\f(CB%y\fB\fR" 4
299 .IX Item "%y"
300 The year as a decimal number without a century (range 00 to 99).
301 .ie n .IP "\fB\fB%Y\fB\fR" 4
302 .el .IP "\fB\f(CB%Y\fB\fR" 4
303 .IX Item "%Y"
304 The year as a decimal number including the century.
305 .ie n .IP "\fB\fB%Z\fB\fR" 4
306 .el .IP "\fB\f(CB%Z\fB\fR" 4
307 .IX Item "%Z"
308 The time zone or name or abbreviation.
309 .IP "\fB%%\fR" 4
310 .IX Item "%%"
311 A literal `%' character.
312 .PP
313 \fI\f(BI\s-1PRINT:\s0\fI\fIvname\fI\f(BI:\fI\fI\s-1CF\s0\fI\f(BI:\fI\fIformat\fI\fR
314 .IX Subsection "PRINT:vname:CF:format"
315 .PP
316 \&\fIDeprecated. Use the new form of this command in new scripts.\fR
317 The first form of this command is to be used with \fB\s-1CDEF\s0\fR \fIvname\fRs.
318 .SS "\s-1GRAPH\s0"
319 .IX Subsection "GRAPH"
320 \fI\f(BI\s-1GPRINT\s0\fI\f(BI:\fI\fIvname\fI\f(BI:\fI\fIformat\fI\fR
321 .IX Subsection "GPRINT:vname:format"
322 .PP
323 This is the same as \f(CW\*(C`PRINT\*(C'\fR, but printed inside the graph.
324 .PP
325 \fI\f(BI\s-1GPRINT\s0\fI\f(BI:\fI\fIvname\fI\f(BI:\fI\fI\s-1CF\s0\fI\f(BI:\fI\fIformat\fI\fR
326 .IX Subsection "GPRINT:vname:CF:format"
327 .PP
328 \&\fIDeprecated. Use the new form of this command in new scripts.\fR
329 This is the same as \f(CW\*(C`PRINT\*(C'\fR, but printed inside the graph.
330 .PP
331 \fI\f(BI\s-1COMMENT\s0\fI\f(BI:\fI\fItext\fI\fR
332 .IX Subsection "COMMENT:text"
333 .PP
334 Text is printed literally in the legend section of the graph. Note that in
335 RRDtool 1.2 you have to escape colons in \s-1COMMENT\s0 text in the same way you
336 have to escape them in \fB*PRINT\fR commands by writing \fB'\e:'\fR.
337 .PP
338 \fI\f(BI\s-1VRULE\s0\fI\f(BI:\fI\fItime\fI\f(BI#\fI\fIcolor\fI[\f(BI:\fI\fIlegend\fI][\f(BI:dashes\fI[\f(BI=\fI\fIon_s\fI[,\fIoff_s\fI[,\fIon_s\fI,\fIoff_s\fI]...]][\f(BI:dash\-offset=\fI\fIoffset\fI]]\fR
339 .IX Subsection "VRULE:time#color[:legend][:dashes[=on_s[,off_s[,on_s,off_s]...]][:dash-offset=offset]]"
340 .PP
341 Draw a vertical line at \fItime\fR.  Its color is composed from three
342 hexadecimal numbers specifying the rgb color components (00 is off, \s-1FF\s0 is
343 maximum) red, green and blue followed by an optional alpha. Optionally, a legend box and string is
344 printed in the legend section. \fItime\fR may be a number or a variable
345 from a \fB\s-1VDEF\s0\fR. It is an error to use \fIvname\fRs from \fB\s-1DEF\s0\fR or \fB\s-1CDEF\s0\fR here.
346 Dashed lines can be drawn using the \fBdashes\fR modifier. See \fB\s-1LINE\s0\fR for more
347 details.
348 .PP
349 \fI\f(BI\s-1HRULE\s0\fI\f(BI:\fI\fIvalue\fI\f(BI#\fI\fIcolor\fI[\f(BI:\fI\fIlegend\fI][\f(BI:dashes\fI[\f(BI=\fI\fIon_s\fI[,\fIoff_s\fI[,\fIon_s\fI,\fIoff_s\fI]...]][\f(BI:dash\-offset=\fI\fIoffset\fI]]\fR
350 .IX Subsection "HRULE:value#color[:legend][:dashes[=on_s[,off_s[,on_s,off_s]...]][:dash-offset=offset]]"
351 .PP
352 Draw a horizontal line at \fIvalue\fR.  \s-1HRULE\s0 acts much like \s-1LINE\s0 except that
353 will have no effect on the scale of the graph. If a \s-1HRULE\s0 is outside the
354 graphing area it will just not be visible.
355 .PP
356 \fI\f(BI\s-1LINE\s0\fI[\fIwidth\fI]\f(BI:\fI\fIvalue\fI[\f(BI#\fI\fIcolor\fI][\f(BI:\fI[\fIlegend\fI][\f(BI:STACK\fI]][\f(BI:dashes\fI[\f(BI=\fI\fIon_s\fI[,\fIoff_s\fI[,\fIon_s\fI,\fIoff_s\fI]...]][\f(BI:dash\-offset=\fI\fIoffset\fI]]\fR
357 .IX Subsection "LINE[width]:value[#color][:[legend][:STACK]][:dashes[=on_s[,off_s[,on_s,off_s]...]][:dash-offset=offset]]"
358 .PP
359 Draw a line of the specified width onto the graph. \fIwidth\fR can be a
360 floating point number. If the color is not specified, the drawing is done
361 \&'invisibly'. This is useful when stacking something else on top of this
362 line. Also optional is the legend box and string which will be printed in
363 the legend section if specified. The \fBvalue\fR can be generated by \fB\s-1DEF\s0\fR,
364 \&\fB\s-1VDEF\s0\fR, and \fB\s-1CDEF\s0\fR.  If the optional \fB\s-1STACK\s0\fR modifier is used, this line
365 is stacked on top of the previous element which can be a \fB\s-1LINE\s0\fR or an
366 \&\fB\s-1AREA\s0\fR.
367 .PP
368 The \fBdashes\fR modifier enables dashed line style. Without any further options
369 a symmetric dashed line with a segment length of 5 pixels will be drawn. The
370 dash pattern can be changed if the \fBdashes=\fR parameter is followed by either
371 one value or an even number (1, 2, 4, 6, ...) of positive values. Each value
372 provides the length of alternate \fIon_s\fR and \fIoff_s\fR portions of the
373 stroke. The \fBdash-offset\fR parameter specifies an \fIoffset\fR into the pattern
374 at which the stroke begins.
375 .PP
376 When you do not specify a color, you cannot specify a legend.  Should
377 you want to use \s-1STACK\s0, use the \*(L"LINEx:<value>::STACK\*(R" form.
378 .PP
379 \fI\f(BI\s-1AREA\s0\fI\f(BI:\fI\fIvalue\fI[\f(BI#\fI\fIcolor\fI][\f(BI:\fI[\fIlegend\fI][\f(BI:STACK\fI]]\fR
380 .IX Subsection "AREA:value[#color][:[legend][:STACK]]"
381 .PP
382 See \fB\s-1LINE\s0\fR, however the area between the x\-axis and the line will
383 be filled.
384 .PP
385 \fI\f(BI\s-1TICK\s0\fI\f(BI:\fI\fIvname\fI\f(BI#\fI\fIrrggbb\fI[\fIaa\fI][\f(BI:\fI\fIfraction\fI[\f(BI:\fI\fIlegend\fI]]\fR
386 .IX Subsection "TICK:vname#rrggbb[aa][:fraction[:legend]]"
387 .PP
388 Plot a tick mark (a vertical line) for each value of \fIvname\fR that is
389 non-zero and not *UNKNOWN*. The \fIfraction\fR argument specifies the length of
390 the tick mark as a fraction of the y\-axis; the default value is 0.1 (10% of
391 the axis). Note that the color specification is not optional. The \s-1TICK\s0 marks normally
392 start at the lower edge of the graphing area. If the fraction is negative they start
393 at the upper border of the graphing area.
394 .PP
395 \fI\f(BI\s-1SHIFT\s0\fI\f(BI:\fI\fIvname\fI\f(BI:\fI\fIoffset\fI\fR
396 .IX Subsection "SHIFT:vname:offset"
397 .PP
398 Using this command \fBRRDtool\fR will graph the following elements
399 with the specified offset.  For instance, you can specify an
400 offset of (\ 7*24*60*60\ =\ )\ 604'800\ seconds to \*(L"look back\*(R" one
401 week. Make sure to tell the viewer of your graph you did this ...
402 As with the other graphing elements, you can specify a number or
403 a variable here.
404 .PP
405 \fI\f(BI\s-1TEXTALIGN\s0\fI\f(BI:\fI{\f(BIleft\fI|\f(BIright\fI|\f(BIjustified\fI|\f(BIcenter\fI}\fR
406 .IX Subsection "TEXTALIGN:{left|right|justified|center}"
407 .PP
408 Labels are placed below the graph. When they overflow to the left, they wrap
409 to the next line. By default, lines are justified left and right. The
410 \&\fB\s-1TEXTALIGN\s0\fR function lets you change this default. This is a command and
411 not an option, so that you can change the default several times in your
412 argument list.
413 .PP
414 \fI\f(BI\s-1STACK\s0\fI\f(BI:\fI\fIvname\fI\f(BI#\fI\fIcolor\fI[\f(BI:\fI\fIlegend\fI]\fR
415 .IX Subsection "STACK:vname#color[:legend]"
416 .PP
417 \&\fIDeprecated.  Use the \f(BI\s-1STACK\s0\fI modifiers on the other commands instead!\fR
418 .PP
419 \&\fBSome notes on stacking\fR
420 .PP
421 When stacking, an element is not placed above the X\-axis but rather
422 on top of the previous element.  There must be something to stack
423 upon.
424 .PP
425 You can use an \fBinvisible\fR \s-1LINE\s0 or \s-1AREA\s0 to stacked upon.
426 .PP
427 An \fBunknown\fR value makes the entire stack unknown from that moment on.
428 You don't know where to begin (the unknown value) and therefore do
429 not know where to end.
430 .PP
431 If you want to make sure you will be displaying a certain variable,
432 make sure never to stack upon the unknown value.  Use a \s-1CDEF\s0 instruction
433 with \fB\s-1IF\s0\fR and \fB\s-1UN\s0\fR to do so.
434 .SH "NOTES on legend arguments"
435 .IX Header "NOTES on legend arguments"
436 .SS "Escaping the colon"
437 .IX Subsection "Escaping the colon"
438 A colon ':' in a \fIlegend\fR argument will mark the end of the
439 legend. To enter a ':' as part of a legend, the colon must be escaped
440 with a backslash '\e:'.  Beware that many environments process
441 backslashes themselves, so it may be necessary to write two
442 backslashes in order to one being passed onto rrd_graph.
443 .SS "String Formatting"
444 .IX Subsection "String Formatting"
445 The text printed below the actual graph can be formatted by appending special
446 escape characters at the end of a text. When ever such a character occurs,
447 all pending text is pushed onto the graph according to the character
448 specified.
449 .PP
450 Valid markers are: \fB\ej\fR for justified, \fB\el\fR for left aligned, \fB\er\fR for
451 right aligned, and \fB\ec\fR for centered. In the next section there is an
452 example showing how to use centered formatting.
453 .PP
454 \&\fB\en\fR is a valid alias for \fB\el\fR since incomplete parsing in earlier
455 versions of rrdtool lead to this behavior and a number of people has been using it.
456 .PP
457 Normally there are two space characters inserted between every two items
458 printed into the graph. The space following a string can be suppressed by
459 putting a \fB\eg\fR at the end of the string. The \fB\eg\fR also ignores any space
460 inside the string if it is at the very end of the string. This can be used
461 in connection with \fB\f(CB%s\fB\fR to suppress empty unit strings.
462 .PP
463 .Vb 1
464 \& GPRINT:a:MAX:%lf%s\eg
465 .Ve
466 .PP
467 A special case is \s-1COMMENT:\s0\fB\es\fR which inserts some additional vertical space
468 before placing the next row of legends.
469 .PP
470 If you are using the proportional font in your graph, you can use tab
471 characters or the sequence \fB\et\fR to line-up legend elements. Note that
472 the tabs inserted are relative to the start of the current legend
473 element!
474 .PP
475 Since RRDtool 1.3 is using Pango for rending text, you can use Pango markup.
476 Pango uses the xml \fBspan\fR tags for inline formatting instructions.:
477 .PP
478 A simple example of a marked-up string might be:
479 .PP
480 .Vb 1
481 \& <span foreground="blue" size="x\-large">Blue text</span> is <i>cool</i>!
482 .Ve
483 .PP
484 The complete list of attributes for the span tag (taken from the pango documentation):
485 .IP "\fBfont_desc\fR" 4
486 .IX Item "font_desc"
487 A font description string, such as \*(L"Sans Italic 12\*(R"; note that any other span attributes will override this description. So if you have \*(L"Sans Italic\*(R" and also a style=\*(L"normal\*(R" attribute, you will get Sans normal, not italic.
488 .IP "\fBfont_family\fR" 4
489 .IX Item "font_family"
490 A font family name
491 .IP "\fBface\fR" 4
492 .IX Item "face"
493 Synonym for font_family
494 .IP "\fBsize\fR" 4
495 .IX Item "size"
496 Font size in 1024ths of a point, or one of the absolute sizes 'xx\-small', 'x\-small', 'small', 'medium', 'large', 'x\-large', 'xx\-large', or one of the relative sizes 'smaller' or 'larger'. If you want to specify a absolute size, it's usually easier to take advantage of the ability to specify a partial font description using 'font_desc'; you can use font_desc='12.5' rather than size='12800'.
497 .IP "\fBstyle\fR" 4
498 .IX Item "style"
499 One of 'normal', 'oblique', 'italic'
500 .IP "\fBweight\fR" 4
501 .IX Item "weight"
502 One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight
503 .IP "\fBvariant\fR" 4
504 .IX Item "variant"
505 \&'normal' or 'smallcaps'
506 .IP "\fBstretch\fR" 4
507 .IX Item "stretch"
508 One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'
509 .IP "\fBforeground\fR" 4
510 .IX Item "foreground"
511 An \s-1RGB\s0 color specification such as '#00FF00' or a color name such as 'red'
512 .IP "\fBbackground\fR" 4
513 .IX Item "background"
514 An \s-1RGB\s0 color specification such as '#00FF00' or a color name such as 'red'
515 .IP "\fBunderline\fR" 4
516 .IX Item "underline"
517 One of 'none', 'single', 'double', 'low', 'error'
518 .IP "\fBunderline_color\fR" 4
519 .IX Item "underline_color"
520 The color of underlines; an \s-1RGB\s0 color specification such as '#00FF00' or a color name such as 'red'
521 .IP "\fBrise\fR" 4
522 .IX Item "rise"
523 Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
524 .IP "\fBstrikethrough\fR" 4
525 .IX Item "strikethrough"
526 \&'true' or 'false' whether to strike through the text
527 .IP "\fBstrikethrough_color\fR" 4
528 .IX Item "strikethrough_color"
529 The color of strikethrough lines; an \s-1RGB\s0 color specification such as '#00FF00' or a color name such as 'red'
530 .IP "\fBfallback\fR" 4
531 .IX Item "fallback"
532 \&'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
533 .IP "\fBlang\fR" 4
534 .IX Item "lang"
535 A language code, indicating the text language
536 .IP "\fBletter_spacing\fR" 4
537 .IX Item "letter_spacing"
538 Inter-letter spacing in 1024ths of a point.
539 .IP "\fBgravity\fR" 4
540 .IX Item "gravity"
541 One of 'south', 'east', 'north', 'west', 'auto'.
542 .IP "\fBgravity_hint\fR" 4
543 .IX Item "gravity_hint"
544 One of 'natural', 'strong', 'line'.
545 .PP
546 To save you some typing, there are also some shortcuts:
547 .IP "\fBb\fR" 4
548 .IX Item "b"
549 Bold
550 .IP "\fBbig\fR" 4
551 .IX Item "big"
552 Makes font relatively larger, equivalent to <span size=\*(L"larger\*(R">
553 .IP "\fBi\fR" 4
554 .IX Item "i"
555 Italic
556 .IP "\fBs\fR" 4
557 .IX Item "s"
558 Strikethrough
559 .IP "\fBsub\fR" 4
560 .IX Item "sub"
561 Subscript
562 .IP "\fBsup\fR" 4
563 .IX Item "sup"
564 Superscript
565 .IP "\fBsmall\fR" 4
566 .IX Item "small"
567 Makes font relatively smaller, equivalent to <span size=\*(L"smaller\*(R">
568 .IP "\fBtt\fR" 4
569 .IX Item "tt"
570 Monospace font
571 .IP "\fBu\fR" 4
572 .IX Item "u"
573 Underline
574 .SH "SEE ALSO"
575 .IX Header "SEE ALSO"
576 rrdgraph gives an overview of how \fBrrdtool graph\fR works.
577 rrdgraph_data describes \fB\s-1DEF\s0\fR,\fB\s-1CDEF\s0\fR and \fB\s-1VDEF\s0\fR in detail.
578 rrdgraph_rpn describes the \fB\s-1RPN\s0\fR language used in the \fB?DEF\fR statements.
579 rrdgraph_graph page describes all of the graph and print functions.
580 .PP
581 Make sure to read rrdgraph_examples for tips&tricks.
582 .SH "AUTHOR"
583 .IX Header "AUTHOR"
584 Program by Tobias Oetiker <tobi@oetiker.ch>
585 .PP
586 This manual page by Alex van den Bogaerdt <alex@vandenbogaerdt.nl>
587 with corrections and/or additions by several people