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