complete rewrite of rrdgraph documentation. This also includs info

on upcomming/planned changes to the rrdgraph interface and functionality
-- Alex van den Bogaerdt <alex@slot.hollandcasino.nl>

git-svn-id: svn://svn.oetiker.ch/rrdtool/trunk/program@30 a5681a0c-68f1-0310-ab6d-d61299d08faa

diff --git a/NEWS b/NEWS
index 85f8ae7c46c90d0db99e829d61782d9f3a5cdcee..7adfad05e002551d2586d4a971a9ea5968662beb 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -1,10 +1,17 @@
 RRDTOOL NEWS
 ============
 
+x
+
 In this file I am noting the Major changes to rrdtool
 for details check the cvs ChangeLog
 
-2001/03/21 Tobias Oetiker <oetiker@ee.ethz.ch>
+2001/03/07 Tobias Oetiker <oetiker@ee.ethz.ch>
+  Integrated complete rewrite of rrdgraph documentation by
+  Alex van den Bogaerdt <alex@slot.hollandcasino.nl>. THis also contains
+  info on his planned changes to the rrdgraph module
+
+2001/03/02 Tobias Oetiker <oetiker@ee.ethz.ch>
   Added Aberrant Patch from Jake Brutlag <jakeb@microsoft.com>
   From now one, new rrd files use version tag 0002. They can
   NOT be read by the old 1.0.x rrdtools

diff --git a/doc/.cvsignore b/doc/.cvsignore
index 622a97eca686a770702b0fd0096e684822aed2b8..41446808a7fee0b9dc800e84b0874878f492830a 100644 (file)
--- a/doc/.cvsignore
+++ b/doc/.cvsignore
@@ -1,3 +1,7 @@
+rrdgraph_examples.pod
+rrdgraph_rpn.pod
+rrdgraph_data.pod
+rrdgraph_graph.pod
 Makefile
 Makefile.in
 *.txt

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 64a33ee6b3b0a8dbe2630a26eecdaa9f30e0185d..1515f1817442512632a63a37198c65725a784178 100644 (file)
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,6 +1,6 @@
 ## Process this file with automake to produce Makefile.in
 
-SUFFIXES = .pod .1 .man .html .txt .pm .pdf
+SUFFIXES = .pod .1 .man .html .txt .pm .pdf .src .inc
 
 #AUTOMAKE_OPTIONS        =  foreign
 
@@ -8,10 +8,13 @@ SUFFIXES = .pod .1 .man .html .txt .pm .pdf
 
 CLEANFILES = *.1 *.html *.txt *-dircache *.pm *.pdf *~ core *itemcache *.rej *.orig
 
+SRC = rrdgraph.src rrdgraph_examples.src  rrdgraph_rpn.src \
+      rrdgraph_data.src rrdgraph_graph.src    
+
 POD = rrdtool.pod rrdlast.pod rrdcreate.pod rrdupdate.pod  rrdtutorial.es.pod \
-       cdeftutorial.pod rpntutorial.pod rrdgraph.pod  bin_dec_hex.pod \
+       cdeftutorial.pod rpntutorial.pod rrdgraph-old.pod  bin_dec_hex.pod \
        rrdfetch.pod rrdrestore.pod rrddump.pod rrdtune.pod rrdresize.pod \
-       rrdcgi.pod rrdtutorial.pod rrdinfo.pod
+       rrdcgi.pod rrdtutorial.pod rrdinfo.pod $(SRC:.src=.pod)
 
 PMP = RRDs.pm RRDp.pm
 
@@ -33,6 +36,9 @@ iman_DATA = $(MAN)
 
 all-local: link txt man html
 
+.src.pod:
+       perl -n -e 'if (/^=include\s+(\S+)/){open F,"$$1.inc" || die $$?;print <F>; close F} else {print}'  $<  > $@ 
+
 .pod.1 .pm.1 .pl.1:
        pod2man --release=$(VERSION) --center=rrdtool $<  > $@
 

diff --git a/doc/name.inc b/doc/name.inc
new file mode 100644 (file)
index 0000000..97754e0
--- /dev/null
+++ b/doc/name.inc
@@ -0,0 +1,12 @@
+=head1 NAME
+
+rrdtool graph - Round Robin Database tool grapher functions
+
+WARNING: This is for version 1.1.x which is B<I<BETA>> software.
+The software may contain serious bugs. Some of the items
+described in here may not yet exist (although this should
+be mentioned) or still be in the alpha stage.  As with every
+other RRDtool release: use at your own risk.  In contrast with
+the stable version of RRDtool, this release may contain bugs
+known to the authors.  It is highly recommended that you subscribe
+to the mailing list.

diff --git a/doc/rrdgraph-old.pod b/doc/rrdgraph-old.pod
new file mode 100644 (file)
index 0000000..8e8038e
--- /dev/null
+++ b/doc/rrdgraph-old.pod
@@ -0,0 +1,660 @@
+=head1 NAME
+
+rrdtool graph - Create a graph based on data from one or several RRD
+
+=for html <div align="right"><a href="rrdgraph.pdf">PDF</a> version.</div> 
+
+=head1 SYNOPSIS
+
+B<rrdtool> B<graph> I<filename> 
+S<[B<-s>|B<--start> I<seconds>]> 
+S<[B<-e>|B<--end> I<seconds>]>
+S<[B<-x>|B<--x-grid> I<x-axis grid and label>]>
+S<[B<-y>|B<--y-grid> I<y-axis grid and label>]>
+S<[B<--alt-y-grid>]>
+S<[B<--alt-autoscale>]>
+S<[B<--alt-autoscale-max>]>
+S<[B<--units-exponent>]> I<value>]>
+S<[B<-v>|B<--vertical-label> I<text>]>
+S<[B<-w>|B<--width> I<pixels>]>
+S<[B<-h>|B<--height> I<pixels>]> 
+S<[B<-i>|B<--interlaced>]> 
+S<[B<-f>|B<--imginfo> I<formatstring>]> 
+S<[B<-a>|B<--imgformat> B<GIF>|B<PNG>]> 
+S<[B<-z>|B<--lazy>]> 
+S<[B<-o>|B<--logarithmic>]>
+S<[B<-u>|B<--upper-limit> I<value>]> 
+S<[B<-l>|B<--lower-limit> I<value>]>
+S<[B<-g>|B<--no-legend>]>
+S<[B<-r>|B<--rigid>]>
+S<[B<--step> I<value>]>
+S<[B<-b>|B<--base> I<value>]>
+S<[B<-c>|B<--color> I<COLORTAG>B<#>I<rrggbb>]>
+S<[B<-t>|B<--title> I<title>]>
+S<[B<DEF:>I<vname>B<=>I<rrd>B<:>I<ds-name>B<:>I<CF>]>
+S<[B<CDEF:>I<vname>B<=>I<rpn-expression>]>
+S<[B<PRINT:>I<vname>B<:>I<CF>B<:>I<format>]>
+S<[B<GPRINT:>I<vname>B<:>I<CF>B<:>I<format>]>
+S<[B<COMMENT:>I<text>]>
+S<[B<HRULE:>I<value>B<#>I<rrggbb>[B<:>I<legend>]]>
+S<[B<VRULE:>I<time>B<#>I<rrggbb>[B<:>I<legend>]]>
+S<[B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]]>
+S<[B<AREA:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]]>
+S<[B<STACK:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]]>
+S<[B<TICK:>I<vname>B<#>I<rrggbb>[B<:>I<axis-fraction>[B<:>I<legend>]]]>
+
+=head1 DESCRIPTION
+
+The B<graph> functions main purpose is to create graphical
+representations of the data stored in one or several B<RRD>s. Apart
+from generating graphs, it can also extract numerical reports.
+
+=over
+
+=item I<filename> 
+
+The name of the graph to generate. Since B<rrdtool> outputs
+GIFs and PNGs, it's recommended that the filename end in either
+F<.gif> or F<.png>.  B<rrdtool> does not enforce this, however.
+If the  I<filename> is set to '-' the image file will be written
+to standard out.  All other output will get suppressed.
+
+PNG output is recommended, since it takes up to 40% less disk space
+and 20-30% less time to generate than a GIF file.
+
+If no graph functions are called, the graph will not be created.
+
+=item B<-s>|B<--start> I<seconds> (default end-1day)
+
+The time when the graph should begin. Time in seconds since
+epoch (1970-01-01) is required. Negative numbers are relative to the
+current time. By default one day worth of data will be graphed.
+See also AT-STYLE TIME SPECIFICATION section in the I<rrdfetch>
+documentation for a detailed explanation on how to specify time.
+
+=item B<-e>|B<--end> I<seconds> (default now)
+
+The time when the graph should end. Time in seconds since epoch.
+See also AT-STYLE TIME SPECIFICATION section in the I<rrdfetch>
+documentation for a detailed explanation of ways to specify time.
+
+=item B<-x>|B<--x-grid> I<x-axis grid and label> (default autoconfigure)
+
+The x-axis label is quite complex to configure. So if you don't have
+very special needs, you can rely on the autoconfiguration to get this
+right.
+
+If you want no x-grid at all, use the magic setting B<none>.
+
+The x-axis label and grid can be configured, using the following format:
+
+I<GTM>B<:>I<GST>B<:>I<MTM>B<:>I<MST>B<:>I<LTM>:I<LST>B<:>I<LPR>B<:>I<LFM>
+
+You have to configure three elements making up the x-axis labels and
+grid. The base grid (I<G??>), the major grid (I<M??>) and the labels
+(I<L??>). The configuration is based on the idea that you first
+specify a well known amount of time (I<?TM>) and then say how many
+times it has to pass between each grid line or label (I<?ST>). For the
+label you have to define two additional items: The precision of the
+label in seconds (I<LPR>) and the strftime format used to generate the
+text of the label (I<LFM>).
+
+The I<?TM> elements must be one of the following keywords: B<SECOND>,
+B<MINUTE>, B<HOUR>, B<DAY>, B<WEEK>, B<MONTH> or B<YEAR>.
+
+If you wanted a graph with a base grid every 10 minutes and a major
+one every hour, with labels every hour you would use the following
+x-axis definition.
+
+C<MINUTE:10:HOUR:1:HOUR:1:0:%X>
+
+The precision in this example is 0 because the %X format is exact. If
+the label was the name of the day, we would have had a precision of 24
+hours, because when you say something like 'Monday' you mean the whole
+day and not Monday morning 00:00. Thus the label should be positioned
+at noon. By defining a precision of 24 hours or rather 86400 seconds,
+you make sure that this happens.
+
+=item B<-y>|B<--y-grid> I<grid step>:I<label factor> (default autoconfigure)
+
+Makes vertical grid lines appear at I<grid step> interval. Every
+I<label factor> gridstep, a major grid line is printed, along with
+label showing the value of the grid line.
+
+If you want no y-grid at all set specify the magic word B<none>.
+
+=item B<--alt-y-grid>
+
+Place Y grid dynamically based on graph Y range. Algorithm ensures
+that you always have grid, that there are enough but not too many
+grid lines and the grid is metric. That is grid lines are placed 
+every 1, 2, 5 or 10 units.  (contributed by Sasha Mikheev)
+
+
+=item B<--alt-autoscale>
+
+Compute Y range  based on function absolute minimum and 
+maximum values. Default algorithm uses predefined set of ranges.  
+This is good in many cases but it fails miserably when you need
+to graph something like 260 + 0.001 * sin(x). Default algorithm 
+will use Y range from 250 to 300 and on the graph you will see
+almost straight line. With --alt-autoscale Y range will be
+from slightly less the 260 - 0.001 to slightly more then 260 + 0.001
+and periodic behavior will be seen.   (contributed by Sasha Mikheev)
+
+=item B<--alt-autoscale-max>
+
+Where --alt-autoscale will modify both the absolute maximum AND minimum
+values, this option will only affect the maximum value. The minimum 
+value, if not defined on the command line, will be 0. This option can
+be useful when graphing router traffic when the WAN line uses compression,
+and thus the throughput may be higher than the WAN line speed.
+
+=item B<--units-exponent> I<value> (default autoconfigure)
+
+This sets the 10**exponent scaling of the y-axis values.  Normally
+values will be scaled to the appropriate units (k, M, etc.).  However
+you may wish to display units always in k (Kilo, 10e3) even if the data
+is in the M (Mega, 10e6) range for instance.  Value should be an
+integer which is a multiple of 3 between -18 and 18 inclusive.  It is
+the exponent on the units you which to use.  For example, use 3 to
+display the y-axis values in k (Kilo, 10e3, thousands), use -6 to
+display the y-axis values in u (Micro, 10e-6, millionths).  Use a value
+of 0 to prevent any scaling of the y-axis values.
+
+=item B<-v>|B<--vertical-label> I<text>
+
+vertical label on the left side of the graph. This is normally used to
+specify the units used.
+
+=item B<-w>|B<--width> I<pixels> (default 400 pixel)
+
+Width of the drawing area within the graph. This affects the size of the
+gif.
+
+=item B<-h>|B<--height> I<pixels> (default 100 pixel)
+
+Width of the drawing area within the graph. This affects the size of the
+gif.
+
+=item B<-i>|B<--interlaced> (default: false)
+
+If you set this option, then the resulting GIF will be interlaced.
+Most web browsers display these incrementally as they load. If
+you do not use this option, the GIFs default to being progressive
+scanned. The only effect of this option is to control the format
+of the GIF on disk. It makes no changes to the layout or contents
+of the graph.
+
+=item B<-f>|B<--imginfo> I<formatstring>
+
+After the image has been created, the graph function uses printf
+together with this format string to create output similar to the PRINT
+function, only that the printf is supplied with the parameters
+I<filename>, I<xsize> and I<ysize>. In order to generate an B<IMG> tag
+suitable for including the graph into a web page, the command line
+would look like this:
+
+ --imginfo '<IMG SRC="/img/%s" WIDTH="%lu" HEIGHT="%lu" ALT="Demo">'
+
+=item B<-a>|B<--imgformat> B<GIF>|B<PNG> (default: GIF)
+
+Allows you to produce PNG output from rrdtool. 
+
+=item B<-z>|B<--lazy> (default: false)
+
+Only generate the graph, if the current gif is out of date or not
+existent.
+
+=item B<-u>|B<--upper-limit> I<value> (default autoconfigure)
+
+Defines the value normally located at the upper border of the
+graph. If the graph contains higher values, the upper border will
+move upwards to accomodate these values as well.
+
+If you want to define an upper-limit which will not move in any
+event you have to set the B<--rigid> option as well.
+
+=item B<-l>|B<--lower-limit> I<value> (default autoconfigure)
+
+This is not the lower limit of a graph.  But rather, this is the
+maximum lower bound of a graph.  For example, the value -100 will
+result in a graph that has a lower limit of -100 or less.  Use this
+keyword to expand graphs down.
+
+=item B<-r>|B<--rigid>
+
+rigid boundaries mode.  Normally rrdgraph will automatically expand the
+lower and upper limit if the graph contains a value outside the valid
+range. With the r option you can disable this behavior
+
+=item B<-b>|B<--base> I<value>
+
+if you are graphing memory (and NOT network traffic) this switch
+should be set to 1024 so that one Kb is 1024 byte. For traffic
+measurement, 1 kb/s is 1000 b/s.
+
+=item B<-o>|B<--logarithmic>
+
+logarithmic y-axis scaling
+
+=item B<-c>|B<--color> I<COLORTAG>B<#>I<rrggbb> (default colors)
+
+override the colors for the standard elements of the graph. The I<COLORTAG>
+must be one of the following symbolic names: B<BACK> ground, B<CANVAS>,
+B<SHADEA> left/top border, B<SHADEB> right/bottom border, B<GRID>, B<MGRID>
+major grid, B<FONT>, B<FRAME> and axis of the graph or B<ARROW>. This option
+can be called multiple times to set several colors.
+
+=item B<-g>|B<--no-legend>
+
+Suppress generation of legend; only render the graph.
+
+=item B<-t>|B<--title> I<text> (default no title)
+
+Define a title to be written into the graph
+
+=item B<--step> I<value> (default automatic)
+
+By default rrdgraph calculates the width of one pixle in the time domain and
+tries to get data at that resolution from the RRD. With this switch you can
+override this behaviour. If you want rrdgraph to get data at 1 hour
+resolution from the RRD, then you can set the step to 3600 seconds. Note,
+that a step smaller than 1 pixle will be silently ignored.
+
+=item B<DEF:>I<vname>B<=>I<rrd>B<:>I<ds-name>B<:>I<CF>
+
+Define virtual name for a data source. This name can then be used
+in the functions explained below. The
+DEF call automatically chooses an B<RRA> which contains I<CF> consolidated data in a
+resolution appropriate for the size of the graph to be drawn.  Ideally
+this means that one data point from the B<RRA> should be represented
+by one pixel in the graph.  If the resolution of the B<RRA> is higher
+than the resolution of the graph, the data in the RRA will be further
+consolidated according to the consolidation function (I<CF>) chosen.
+
+=item B<CDEF:>I<vname>B<=>I<rpn-expression>
+
+Create a new virtual data source by evaluating a mathematical expression,
+specified in Reverse Polish Notation (RPN). If you have ever used a traditional
+HP calculator you already know RPN. The idea behind RPN notation is, 
+that you have a stack and push your data onto this stack. When ever
+you execute an operation, it takes as many data values from the stack
+as needed. The pushing of data is implicit, so when ever you specify a number
+or a variable, it gets pushed automatically. 
+
+If this is all a big load of incomprehensible words for you, maybe an
+example helps (a more complete explanation is given in [1]): The
+expression I<vname+3/2> becomes C<vname,3,2,/,+> in RPN. First the three
+values get pushed onto the stack (which now contains (the current
+value of) vname, a 3 and a 2).  Then the / operator pops two values
+from the stack (3 and 2), divides the first argument by the second
+(3/2) and pushes the result (1.5) back onto the stack. Then the +
+operator pops two values (vname and 1.5) from the stack; both values
+are added up and the result gets pushes back onto the stack. In the
+end there is only one value left on the stack: The result of the
+expression.
+
+The I<rpn-expression> in the B<CDEF> function takes both, constant values
+as well as I<vname> variables. The following operators can be used on these
+values: 
+
+=over
+
+=item +, -, *, /, %
+
+pops two values from the stack applies the selected operator and pushes 
+the result back onto the stack. The % operator stands for the modulo
+operation.
+
+=item SIN, COS, LOG, EXP, FLOOR, CEIL
+
+pops one value from the stack, applies the selected function and pushes
+the result back onto the stack.
+
+=item LT, LE, GT, GE, EQ
+
+pops two values from the stack, compares them according to the selected
+condition and pushes either 1 back onto the stack if the condition is true
+and 0 if the condition was not true.
+
+=item IF
+
+pops three values from the stack. If the last value is not 0, the
+second value will be pushed back onto the stack, otherwise the
+first value is pushed back.
+
+If the stack contains the values A, B, C, D, E are presently on the
+stack, the IF operator will pop the values E D and C of the stack. It will
+look at C and if it is not 0 it will push D back onto the stack, otherwise
+E will be sent back to the stack.
+
+=item MIN, MAX
+
+selects the lesser or larger of the two top stack values respectively
+
+=item LIMIT
+
+replaces the value with I<*UNKNOWN*> if it is outside the limits specified
+by the two values above it on the stack.
+
+ CDEF:a=alpha,0,100,LIMIT
+
+=item DUP, EXC, POP
+
+These manipulate the stack directly.  DUP will duplicate the top of the
+stack, pushing the result back onto the stack.  EXC will exchange the top
+two elements of the stack, and POP will pop off the top element of the
+stack.  Having insufficient elements on the stack for these operations is
+an error.
+
+=item UN
+
+Pops one value off the stack, if it is I<*UNKNOWN*>, 1 will be pushed
+back otherwise 0.
+
+=item UNKN
+
+Push an I<*UNKNOWN*> value onto the stack.
+
+=item PREV
+
+Push I<*UNKNOWN*> if its at the first value of a data set or otherwise
+the value of this CDEF at the previous time step. This allows you to
+perform calculations across the data.
+
+=item INF, NEGINF
+
+Push a positive or negative infinite (oo) value onto the stack. When
+drawing an infinite number it appears right at the top or bottom edge of the
+graph, depending whether you have a positive or negative infinite number.
+
+=item NOW
+
+Push the current (real world) time onto the stack.
+
+=item TIME
+
+Push the time the current sample was taken onto the stack. This is the
+number of non-skip seconds since 0:00:00 January 1, 1970.
+
+=item LTIME
+
+This is like TIME B<+ current timezone offset in seconds>. The current
+offset takes daylight saving time into account, given your OS supports
+this. If you were looking at a sample, in Zurich, in summer, the
+offset would be 2*3600 seconds, as Zurich at that time of year is 2
+hours ahead of UTC.
+
+Note that the timezone offset is always calculated for the time the
+current sample was taken at. It has nuthing todo with the time you are
+doing the calculation.
+
+=back
+
+Please note that you may only use I<vname> variables that you
+previously defined by either B<DEF> or B<CDEF>. Furthermore, as of
+this writing (version 0.99.25), you must use at least one I<vname>
+per expression, that is "CDEF:fourtytwo=2,40,+" will yield an error
+message but not a I<vname> fourtytwo that's always equal to 42.
+
+=item B<PRINT:>I<vname>B<:>I<CF>B<:>I<format>
+
+Calculate the chosen consolidation function I<CF> over the data-source
+variable I<vname> and C<printf> the result to stdout using I<format>.
+In the I<format> string there should be a '%lf' or '%le' marker in the
+place where the number should be printed.
+
+If an additional '%s' is found AFTER the marker, the value will be scaled
+and an appropriate SI magnitude unit will be printed in place of the '%s'
+marker. The scaling will take the '--base' argument into consideration!
+
+If a '%S' is used instead of a '%s', then instead of calculating the
+appropriate SI magnitude unit for this value, the previously calculated
+SI magnitude unit will be used.  This is useful if you want all the values
+in a PRINT statement to have the same SI magnitude unit.  If there was
+no previous SI magnitude calculation made, then '%S' behaves like a '%s',
+unless the value is 0, in which case it does not remember a SI magnitude
+unit and a SI magnitude unit will only be calculated when the next '%s' is
+seen or the next '%S' for a non-zero value.
+
+If you want to put a '%' into your PRINT string, use '%%' instead.
+
+=item B<GPRINT:>I<vname>B<:>I<CF>B<:>I<format>
+
+Same as B<PRINT> but the result is printed into the graph below the legend.
+
+=back
+
+B<Caveat:> When using the B<PRINT> and B<GRPRINT> functions to
+calculate data summaries over time periods bounded by the current
+time, it is important to note that the last sample will almost always
+yield a value of UNKNOWN as it lies after the last update time.  This
+can result in slight data skewing, particularly with the B<AVERAGE>
+function.  In order to avoid this, make sure that your end time is at
+least one heartbeat prior to the current time.
+
+=over
+
+
+=item B<COMMENT:>I<text>
+
+Like B<GPRINT> but the I<text> is simply printed into the graph.
+
+=item B<HRULE:>I<value>B<#>I<rrggbb>[B<:>I<legend>]
+
+Draw a horizontal rule into the graph and optionally add a legend
+
+=item B<VRULE:>I<time>B<#>I<rrggbb>[B<:>I<legend>]
+
+Draw a vertical rule into the graph and optionally add a legend
+
+=item B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]
+
+Plot for the requested data, using the color specified. Write a legend
+into the graph. The 3 possible keywords B<LINE1>, B<LINE2>, and B<LINE3> 
+generate increasingly wide lines. If no color is defined, 
+the drawing is done 'blind' this is useful in connection with the 
+B<STACK> function when you want to ADD the values of two 
+data-sources without showing it in the graph.
+
+=item B<AREA>:I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]
+
+Does the same as B<LINE?>, but the area between 0 and 
+the graph will be filled with the color specified.
+
+=item B<STACK>:I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]
+
+Does the same as B<LINE?>, but the graph gets stacked on top of the previous
+B<LINE?>, B<AREA> or B<STACK> graph. Depending on the type of the
+previous graph, the B<STACK> will be either a B<LINE?> or an B<AREA>.
+This obviously implies that the first B<STACK> must be preceded by an
+B<AREA> or B<LINE?> -- you need something to stack something onto in
+the first place ;) 
+
+Note, that when you STACK onto *UNKNOWN* data, rrdtool will not draw
+any graphics ... *UNKNOWN* is not zero ... if you want it to be zero
+then you might want to use a CDEF argument with IF and UN functions to
+turn *UNKNOWN* into zero ...
+
+=item B<TICK:>I<vname>B<#>I<rrggbb>[B<:>I<axis-fraction>[B<:>I<legend>]]
+
+Plot a tick mark (a vertical line) for each value of I<vname> that is
+non-zero and not *UNKNOWN*. The I<axis-fraction> argument specifies the
+length of the tick mark as a fraction of the y-axis; the default value
+is 0.1 (10% of the axis). Note that the color specification is not
+optional.
+
+=back
+
+=head1 NOTES on legend arguments
+
+=head2 Escaping the colon
+
+In a ':' in a I<legend> argument will mark the end of the legend. To
+enter a ':' into a legend, the colon must be escaped with a backslash '\:'.
+Beware, that many environments look for backslashes themselves, so it may
+be necessary to write two backslashes so that one is passed onto rrd_graph.
+
+=head2 String Formatting
+
+The text printed below the actual graph can be formated by appending special
+escaped characters at the end of a text. When ever such a character occurs,
+all pending text is pushed onto the graph according to the character
+specified.
+
+Valid markers are: B<\j> for justified, B<\l> for left aligned, B<\r> for
+right aligned and B<\c> for centered. In the next section there is an
+example showing how to use centered formating.
+
+Normally there are two space characters inserted between every two items
+printed into the graph. The space following a string can be suppressed by
+putting a B<\g> at the end of the string. The B<\g> also squshes any space
+inside the string if it is at the very end of the string. This can be used
+in connection with B<%s> to supress empty unit strings.
+
+ GPRINT:a:MAX:%lf%s\g
+
+A special case is COMMENT:B<\s> this inserts some additional vertical space
+before placing the next row of legends.
+
+=head1 NOTE on Return Values
+
+Whenever rrd_graph gets called, it prints a line telling the size of
+the gif it has just created to STDOUT. This line looks like this: XSIZExYSIZE.
+
+=head1 EXAMPLE 1
+
+  rrdtool graph demo.gif --title="Demo Graph" \
+          DEF:cel=demo.rrd:exhaust:AVERAGE \
+          "CDEF:far=cel,1.8,*,32,+"" \
+          LINE2:cel#00a000:"D. Celsius" \
+          LINE2:far#ff0000:"D. Fahrenheit\c"
+
+=head1 EXAMPLE 2
+
+This example demonstrates the syntax for using IF and UN to set
+I<*UNKNOWN*> values to 0.  This technique is useful if you are
+aggregating interface data where the start dates of the data sets
+doesn't match.
+
+  rrdtool graph demo.gif --title="Demo Graph" \
+         DEF:idat1=interface1.rrd:ds0:AVERAGE \
+         DEF:idat2=interface2.rrd:ds0:AVERAGE \
+         DEF:odat1=interface1.rrd:ds1:AVERAGE \
+         DEF:odat2=interface2.rrd:ds1:AVERAGE \
+         CDEF:agginput=idat1,UN,0,idat1,IF,idat2,UN,0,idat2,IF,+,8,* \
+         CDEF:aggoutput=odat1,UN,0,odat1,IF,odat2,UN,0,odat2,IF,+,8,* \
+         AREA:agginput#00cc00:Input Aggregate \
+         LINE1:agginput#0000FF:Output Aggregate
+         
+Assuming that idat1 has a data value of I<*UNKNOWN*>, the CDEF expression 
+
+ idat1,UN,0,idat1,IF 
+
+leaves us with a stack with contents of 1,0,NaN and the IF function
+will pop off the 3 values and replace them with 0.  If idat1 had a
+real value like 7942099, then the stack would have 0,0,7942099 and the
+real value would be the replacement.  
+
+=head1 EXAMPLE 3
+
+This example shows two ways to use the INF function. First it makes
+the background change color during half of the hours. Then, it uses
+AREA and STACK to draw a picture. If one of the inputs was UNKNOWN,
+all inputs are overlaid with another AREA.
+
+  rrdtool graph example.png --title="INF demo" \
+         DEF:val1=some.rrd:ds0:AVERAGE \
+         DEF:val2=some.rrd:ds1:AVERAGE \
+         DEF:val3=some.rrd:ds2:AVERAGE \
+         DEF:val4=other.rrd:ds0:AVERAGE \
+         CDEF:background=val4,POP,TIME,7200,%,3600,LE,INF,UNKN,IF \
+         CDEF:wipeout=val1,val2,val3,val4,+,+,+,UN,INF,UNKN,IF \
+         AREA:background#F0F0F0 \
+         AREA:val1#0000FF:Value1 \
+         STACK:val2#00C000:Value2 \
+         STACK:val3#FFFF00:Value3 \
+         STACK:val4#FFC000:Value4 \
+         AREA:wipeout#FF0000:Unknown
+
+The first CDEF uses val4 as a dummy value. It's value is removed immediately
+from the stack. Then a decision is made based on the time that a sample was
+taken. If it is an even hour (UTC time !) then the area will be filled. If
+it is not, the value is set to UNKN and is not plotted.
+
+The second CDEF looks if any of val1,val2,val3,val4 is unknown. It does so by
+checking the outcome of sum(val1,val2,val3,val4). Again, INF is returned when
+the condition is true, UNKN is used to not plot the data.
+
+The different items are plotted in a particular order. First do the background, then use a
+normal area to overlay it with data. Stack the other data until they are all plotted. Last but
+not least, overlay everything with eye-hurting red
+to signal any unknown data.
+
+Note that this example assumes that your data is in the positive half of the y-axis
+otherwhise you would would have to add NEGINF in order to extend the coverage
+of the rea to whole graph.
+
+=head1 EXAMPLE 4
+
+If the specialized function B<RRAs> exist for aberrant behavior detection, they
+can be used to generate the graph of a time series with confidence bands and
+failures.
+
+   rrdtool graph example.gif \
+          DEF:obs=monitor.rrd:ifOutOctets:AVERAGE \
+          DEF:pred=monitor.rrd:ifOutOctets:HWPREDICT \
+          DEF:dev=monitor.rrd:ifOutOctets:DEVPREDICT \
+          DEF:fail=monitor.rrd:ifOutOctets:FAILURES \
+          TICK:fail#ffffa0:1.0:"Failures\: Average bits out" \
+          CDEF:scaledobs=obs,8,* \
+          CDEF:upper=pred,dev,2,*,+ \
+          CDEF:lower=pred,dev,2,*,- \
+          CDEF:scaledupper=upper,8,* \
+          CDEF:scaledlower=lower,8,* \
+          LINE2:scaledobs#0000ff:"Average bits out" \
+          LINE1:scaledupper#ff0000:"Upper Confidence Bound: Average bits out" \
+          LINE1:scaledlower#ff0000:"Lower Confidence Bound: Average bits out"
+
+This example generates a graph of the data series in blue (LINE2 with the scaledobs
+virtual data source), confidence bounds in red (scaledupper and scaledlower virtual
+data sources), and potential failures (i.e. potential aberrant aberrant behavior)
+marked by vertical yellow lines (the fail data source).
+
+The raw data comes from an AVERAGE B<RRA>, the finest resolution of the observed
+time series (one consolidated data point per primary data point). The predicted
+(or smoothed) values are stored in the HWPREDICT B<RRA>. The predicted deviations
+(think standard deviation) values are stored in the DEVPREDICT B<RRA>. Finally,
+the FAILURES B<RRA> contains indicators, with 1 denoting a potential failure.
+
+All of the data is rescaled to bits (instead of Octets) by multiplying by 8.
+The confidence bounds are computed by an offset of 2 deviations both above
+and below the predicted values (the CDEFs upper and lower). Vertical lines
+indicated potential failures are graphed via the TICK graph element, which
+converts non-zero values in an B<RRA> into tick marks. Here an axis-fraction
+argument of 1.0 means the tick marks span the entire y-axis, and hence become
+vertical lines on the graph.
+
+The choice of 2 deviations (a scaling factor) matches the default used internally
+by the FAILURES B<RRA>. If the internal value is changed (see L<rrdtune>), this
+graphing command should be changed to be consistent.
+
+=head2 A note on data reduction:
+
+The B<rrdtool> I<graph> command is designed to plot data at a specified temporal
+resolution, regardless of the actually resolution of the data in the RRD file.
+This can present a problem for the specialized consolidation functions which
+maintain a one-to-one mapping between primary data points and consolidated
+data points. If a graph insists on viewing the contents of these B<RRAs> on a
+coarser temporal scale, the I<graph> command tries to do something intelligent,
+but the confidence bands and failures no longer have the same meaning and may
+be misleading.
+
+=head1 AUTHOR
+
+Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt>
+
+=head1 REFERENCES
+
+[1] http://www.dotpoint.com/xnumber/rpn_or_adl.htm

diff --git a/doc/rrdgraph.pod b/doc/rrdgraph.pod
index 8e8038e98c1b56e1253d73907fd3a8b629fc1678..eeab6bbc6c42a1bc0f4cfd87a69018a6381443af 100644 (file)
--- a/doc/rrdgraph.pod
+++ b/doc/rrdgraph.pod
@@ -1,660 +1,349 @@
 =head1 NAME
 
-rrdtool graph - Create a graph based on data from one or several RRD
-
-=for html <div align="right"><a href="rrdgraph.pdf">PDF</a> version.</div> 
-
-=head1 SYNOPSIS
-
-B<rrdtool> B<graph> I<filename> 
-S<[B<-s>|B<--start> I<seconds>]> 
-S<[B<-e>|B<--end> I<seconds>]>
-S<[B<-x>|B<--x-grid> I<x-axis grid and label>]>
-S<[B<-y>|B<--y-grid> I<y-axis grid and label>]>
-S<[B<--alt-y-grid>]>
-S<[B<--alt-autoscale>]>
-S<[B<--alt-autoscale-max>]>
-S<[B<--units-exponent>]> I<value>]>
-S<[B<-v>|B<--vertical-label> I<text>]>
-S<[B<-w>|B<--width> I<pixels>]>
-S<[B<-h>|B<--height> I<pixels>]> 
-S<[B<-i>|B<--interlaced>]> 
-S<[B<-f>|B<--imginfo> I<formatstring>]> 
-S<[B<-a>|B<--imgformat> B<GIF>|B<PNG>]> 
-S<[B<-z>|B<--lazy>]> 
-S<[B<-o>|B<--logarithmic>]>
-S<[B<-u>|B<--upper-limit> I<value>]> 
-S<[B<-l>|B<--lower-limit> I<value>]>
-S<[B<-g>|B<--no-legend>]>
-S<[B<-r>|B<--rigid>]>
-S<[B<--step> I<value>]>
-S<[B<-b>|B<--base> I<value>]>
-S<[B<-c>|B<--color> I<COLORTAG>B<#>I<rrggbb>]>
-S<[B<-t>|B<--title> I<title>]>
-S<[B<DEF:>I<vname>B<=>I<rrd>B<:>I<ds-name>B<:>I<CF>]>
-S<[B<CDEF:>I<vname>B<=>I<rpn-expression>]>
-S<[B<PRINT:>I<vname>B<:>I<CF>B<:>I<format>]>
-S<[B<GPRINT:>I<vname>B<:>I<CF>B<:>I<format>]>
-S<[B<COMMENT:>I<text>]>
-S<[B<HRULE:>I<value>B<#>I<rrggbb>[B<:>I<legend>]]>
-S<[B<VRULE:>I<time>B<#>I<rrggbb>[B<:>I<legend>]]>
-S<[B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]]>
-S<[B<AREA:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]]>
-S<[B<STACK:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]]>
-S<[B<TICK:>I<vname>B<#>I<rrggbb>[B<:>I<axis-fraction>[B<:>I<legend>]]]>
+rrdtool graph - Round Robin Database tool grapher functions
+
+WARNING: This is for version 1.1.x which is B<I<BETA>> software.
+The software may contain serious bugs. Some of the items
+described in here may not yet exist (although this should
+be mentioned) or still be in the alpha stage.  As with every
+other RRDtool release: use at your own risk.  In contrast with
+the stable version of RRDtool, this release may contain bugs
+known to the authors.  It is highly recommended that you subscribe
+to the mailing list.
+
+=head1 SYNOPSYS
+
+B<rrdtool graph> I<filename>
+[E<lt>B<L<option|rrdgraph/OPTIONS>>E<gt> ...]
+E<lt>B<L<data definition|rrdgraph_data/DEF>>E<gt>
+[E<lt>B<L<data definition|rrdgraph_data/DEF>>E<gt> ...]
+[E<lt>B<L<data calculation|rrdgraph_data/CDEF>>E<gt> ...]
+[E<lt>B<L<variable definition|rrdgraph_data/VDEF>>E<gt> ...]
+[E<lt>B<L<graph element|rrdgraph_graph/GRAPH>>E<gt> ...]
+[E<lt>B<L<print element|rrdgraph_graph/PRINT>>E<gt> ...]
 
 =head1 DESCRIPTION
 
-The B<graph> functions main purpose is to create graphical
-representations of the data stored in one or several B<RRD>s. Apart
-from generating graphs, it can also extract numerical reports.
+The B<graph> function of B<RRDtool> is used to represent the
+data from an B<RRD> to a human viewer.  Its main purpose is to
+create a nice graphical representation but it can also generate
+a numerical report.
 
-=over
+=head1 OVERVIEW
 
-=item I<filename> 
+B<rrdtool graph> needs data to work with, use one or more
+B<L<data definition|rrdgraph_data/DEF>> statements to collect this
+data.  You are not limited to one database, it's perfectly legal to
+collect data from two or more databases (one per statement though).
 
-The name of the graph to generate. Since B<rrdtool> outputs
-GIFs and PNGs, it's recommended that the filename end in either
-F<.gif> or F<.png>.  B<rrdtool> does not enforce this, however.
-If the  I<filename> is set to '-' the image file will be written
-to standard out.  All other output will get suppressed.
+If you want to display averages, maxima, percentiles etcetera
+it is best to collect them now using the
+B<L<variable definition|rrdgraph_data/VDEF>> statement.  At this
+stage, this command works at the unprocessed data from the B<RRD>.
+I<(Note: this is not yet true; it works on consolidated information
+right now)>
 
-PNG output is recommended, since it takes up to 40% less disk space
-and 20-30% less time to generate than a GIF file.
+The data fetched from the B<RRA> is then B<consolidated> so that
+there is exactly one datapoint per pixel in the graph. If you do
+not take care yourself, B<RRDtool> will expand the range slightly
+if necessary (in that case the first pixel may very well become
+unknown!).
 
-If no graph functions are called, the graph will not be created.
+Sometimes data is not exactly as you would like to display it. For
+instance, you might be collecting B<bytes> per second but want to
+display B<bits> per second. This is where the
+B<L<data calculation|rrdgraph_data/CDEF>> command is designed for.
+After B<consolidating> the data, a copy is made and this copy is
+modified using a rather flexible B<L<RPN|rrdgraph_rpn/>> command
+set.  If you use B<L<variable definition|rrdgraph_data/VDEF>>
+statements after this, they work on the consolidated data and may
+return other values for maximum, minimum etcetera!
+
+When you are done fetching and processing the data, it is time to
+graph it (or print it).  This ends the B<rrdtool graph> sequence.
 
-=item B<-s>|B<--start> I<seconds> (default end-1day)
+=head1 OPTIONS
 
-The time when the graph should begin. Time in seconds since
-epoch (1970-01-01) is required. Negative numbers are relative to the
-current time. By default one day worth of data will be graphed.
-See also AT-STYLE TIME SPECIFICATION section in the I<rrdfetch>
-documentation for a detailed explanation on how to specify time.
+It is expected that most options will move to the graph definition
+statements (after all, most of them do define graph elements...).
 
-=item B<-e>|B<--end> I<seconds> (default now)
+=over 4
 
-The time when the graph should end. Time in seconds since epoch.
-See also AT-STYLE TIME SPECIFICATION section in the I<rrdfetch>
-documentation for a detailed explanation of ways to specify time.
+=item filename
 
-=item B<-x>|B<--x-grid> I<x-axis grid and label> (default autoconfigure)
+The name and path of the graph to generate. It is recommended to
+end this in C<.png> or C<.gif> but B<rrdtool> does not enforce this.
 
-The x-axis label is quite complex to configure. So if you don't have
-very special needs, you can rely on the autoconfiguration to get this
-right.
+I<filename> can be 'C<->' to send the image to C<stdout>. In
+that case, no other output is generated.  
 
-If you want no x-grid at all, use the magic setting B<none>.
+Z<>
 
-The x-axis label and grid can be configured, using the following format:
+=item Time range
 
-I<GTM>B<:>I<GST>B<:>I<MTM>B<:>I<MST>B<:>I<LTM>:I<LST>B<:>I<LPR>B<:>I<LFM>
+B<[-s|--start E<lt>timeE<gt>]>
+B<[-e|--end E<lt>timeE<gt>]>
+B<[--step E<lt>secondsE<gt>]>
 
-You have to configure three elements making up the x-axis labels and
-grid. The base grid (I<G??>), the major grid (I<M??>) and the labels
-(I<L??>). The configuration is based on the idea that you first
-specify a well known amount of time (I<?TM>) and then say how many
-times it has to pass between each grid line or label (I<?ST>). For the
-label you have to define two additional items: The precision of the
-label in seconds (I<LPR>) and the strftime format used to generate the
-text of the label (I<LFM>).
+The start and end of what you would like to display, and which
+B<RRA> the data should come from.  Defaults are: 1 day ago until
+now, with the best possible resolution. B<Start> and B<end> can 
+be specified in several formats, see
+L<AT-STYLE TIME SPECIFICATION|rrdfetch/> and L<rrdgraph_examples>.
+By default, B<rrdtool graph> calculates the width of one pixel in
+the time domain and tries to get data from an B<RRA> with that
+resolution.  With the B<step> option you can alter this behaviour.
+If you want B<rrdtool graph> to get data at a one-hour resolution
+from the B<RRD>, set B<step> to 3600.  Note: a step smaller than
+one pixel will silently be ignored.
 
-The I<?TM> elements must be one of the following keywords: B<SECOND>,
-B<MINUTE>, B<HOUR>, B<DAY>, B<WEEK>, B<MONTH> or B<YEAR>.
+Z<>
 
-If you wanted a graph with a base grid every 10 minutes and a major
-one every hour, with labels every hour you would use the following
-x-axis definition.
+=item Labels
 
-C<MINUTE:10:HOUR:1:HOUR:1:0:%X>
+B<[-t|--title E<lt>stringE<gt>]>
+B<[-v|--vertical-label E<lt>stringE<gt>]>
 
-The precision in this example is 0 because the %X format is exact. If
-the label was the name of the day, we would have had a precision of 24
-hours, because when you say something like 'Monday' you mean the whole
-day and not Monday morning 00:00. Thus the label should be positioned
-at noon. By defining a precision of 24 hours or rather 86400 seconds,
-you make sure that this happens.
+A horizontal string at the top of the graph and/or a vertically
+placed string at the left hand side of the graph. I<New: (not
+yet implemented)> The string can contain formatter options that
+are used to include variables (from B<VDEF>s) and newlines.
 
-=item B<-y>|B<--y-grid> I<grid step>:I<label factor> (default autoconfigure)
+Z<>
 
-Makes vertical grid lines appear at I<grid step> interval. Every
-I<label factor> gridstep, a major grid line is printed, along with
-label showing the value of the grid line.
+=item Size
 
-If you want no y-grid at all set specify the magic word B<none>.
+B<[-w|--width E<lt>pixelsE<gt>]>
+B<[-h|--heigth E<lt>pixelsE<gt>]>
 
-=item B<--alt-y-grid>
+The width and height of the B<canvas> (the part of the graph with
+the actual lines and such). Defaults are 400 pixels by 100 pixels.
 
-Place Y grid dynamically based on graph Y range. Algorithm ensures
-that you always have grid, that there are enough but not too many
-grid lines and the grid is metric. That is grid lines are placed 
-every 1, 2, 5 or 10 units.  (contributed by Sasha Mikheev)
-
-
-=item B<--alt-autoscale>
-
-Compute Y range  based on function absolute minimum and 
-maximum values. Default algorithm uses predefined set of ranges.  
-This is good in many cases but it fails miserably when you need
-to graph something like 260 + 0.001 * sin(x). Default algorithm 
-will use Y range from 250 to 300 and on the graph you will see
-almost straight line. With --alt-autoscale Y range will be
-from slightly less the 260 - 0.001 to slightly more then 260 + 0.001
-and periodic behavior will be seen.   (contributed by Sasha Mikheev)
-
-=item B<--alt-autoscale-max>
-
-Where --alt-autoscale will modify both the absolute maximum AND minimum
-values, this option will only affect the maximum value. The minimum 
-value, if not defined on the command line, will be 0. This option can
-be useful when graphing router traffic when the WAN line uses compression,
-and thus the throughput may be higher than the WAN line speed.
-
-=item B<--units-exponent> I<value> (default autoconfigure)
-
-This sets the 10**exponent scaling of the y-axis values.  Normally
-values will be scaled to the appropriate units (k, M, etc.).  However
-you may wish to display units always in k (Kilo, 10e3) even if the data
-is in the M (Mega, 10e6) range for instance.  Value should be an
-integer which is a multiple of 3 between -18 and 18 inclusive.  It is
-the exponent on the units you which to use.  For example, use 3 to
-display the y-axis values in k (Kilo, 10e3, thousands), use -6 to
-display the y-axis values in u (Micro, 10e-6, millionths).  Use a value
-of 0 to prevent any scaling of the y-axis values.
-
-=item B<-v>|B<--vertical-label> I<text>
-
-vertical label on the left side of the graph. This is normally used to
-specify the units used.
-
-=item B<-w>|B<--width> I<pixels> (default 400 pixel)
-
-Width of the drawing area within the graph. This affects the size of the
-gif.
-
-=item B<-h>|B<--height> I<pixels> (default 100 pixel)
-
-Width of the drawing area within the graph. This affects the size of the
-gif.
-
-=item B<-i>|B<--interlaced> (default: false)
-
-If you set this option, then the resulting GIF will be interlaced.
-Most web browsers display these incrementally as they load. If
-you do not use this option, the GIFs default to being progressive
-scanned. The only effect of this option is to control the format
-of the GIF on disk. It makes no changes to the layout or contents
-of the graph.
-
-=item B<-f>|B<--imginfo> I<formatstring>
-
-After the image has been created, the graph function uses printf
-together with this format string to create output similar to the PRINT
-function, only that the printf is supplied with the parameters
-I<filename>, I<xsize> and I<ysize>. In order to generate an B<IMG> tag
-suitable for including the graph into a web page, the command line
-would look like this:
-
- --imginfo '<IMG SRC="/img/%s" WIDTH="%lu" HEIGHT="%lu" ALT="Demo">'
-
-=item B<-a>|B<--imgformat> B<GIF>|B<PNG> (default: GIF)
-
-Allows you to produce PNG output from rrdtool. 
-
-=item B<-z>|B<--lazy> (default: false)
-
-Only generate the graph, if the current gif is out of date or not
-existent.
-
-=item B<-u>|B<--upper-limit> I<value> (default autoconfigure)
-
-Defines the value normally located at the upper border of the
-graph. If the graph contains higher values, the upper border will
-move upwards to accomodate these values as well.
-
-If you want to define an upper-limit which will not move in any
-event you have to set the B<--rigid> option as well.
-
-=item B<-l>|B<--lower-limit> I<value> (default autoconfigure)
-
-This is not the lower limit of a graph.  But rather, this is the
-maximum lower bound of a graph.  For example, the value -100 will
-result in a graph that has a lower limit of -100 or less.  Use this
-keyword to expand graphs down.
+Z<>
 
-=item B<-r>|B<--rigid>
+=item Limits
 
-rigid boundaries mode.  Normally rrdgraph will automatically expand the
-lower and upper limit if the graph contains a value outside the valid
-range. With the r option you can disable this behavior
+I<Old behaviour, until the new options are implemented>
+B<[-u|--upper-limit E<lt>valueE<gt>]>
+B<[-l|--lower-limit E<lt>valueE<gt>]>
+B<[-r|--rigid]>
 
-=item B<-b>|B<--base> I<value>
+By default the graph will be autoscaling so that it displays the
+portion of the y-axis that is actually used. You can change this
+behaviour by setting the limits.  The displayed y-axis will show
+at least from B<lower-limit> to B<upper-limit>.  Autoscaling will
+still permit those boundaries to be stretched unless the B<rigid>
+option is set.
 
-if you are graphing memory (and NOT network traffic) this switch
-should be set to 1024 so that one Kb is 1024 byte. For traffic
-measurement, 1 kb/s is 1000 b/s.
-
-=item B<-o>|B<--logarithmic>
-
-logarithmic y-axis scaling
-
-=item B<-c>|B<--color> I<COLORTAG>B<#>I<rrggbb> (default colors)
-
-override the colors for the standard elements of the graph. The I<COLORTAG>
-must be one of the following symbolic names: B<BACK> ground, B<CANVAS>,
-B<SHADEA> left/top border, B<SHADEB> right/bottom border, B<GRID>, B<MGRID>
-major grid, B<FONT>, B<FRAME> and axis of the graph or B<ARROW>. This option
-can be called multiple times to set several colors.
-
-=item B<-g>|B<--no-legend>
-
-Suppress generation of legend; only render the graph.
-
-=item B<-t>|B<--title> I<text> (default no title)
-
-Define a title to be written into the graph
-
-=item B<--step> I<value> (default automatic)
-
-By default rrdgraph calculates the width of one pixle in the time domain and
-tries to get data at that resolution from the RRD. With this switch you can
-override this behaviour. If you want rrdgraph to get data at 1 hour
-resolution from the RRD, then you can set the step to 3600 seconds. Note,
-that a step smaller than 1 pixle will be silently ignored.
+I<New behaviour, after the new options are implemented>
+B<[--maximum-upper-limit E<lt>valueE<gt>]>
+B<[--minimum-upper-limit E<lt>valueE<gt>]>
+B<[--maximum-lower-limit E<lt>valueE<gt>]>
+B<[--minimum-lower-limit E<lt>valueE<gt>]>
 
-=item B<DEF:>I<vname>B<=>I<rrd>B<:>I<ds-name>B<:>I<CF>
+By default the graph will be autoscaling so that it displays the
+portion of the y-axis that is actually used. You can change this
+behaviour by setting the limits.  The displayed y-axis will show
+at most B<maximum-upper-limit> and at least B<minimum-upper-limit>
+at the top, and similarily at least B<maximum-lower-limit> and
+at most B<minimum-lower-limit> at the bottom.  The default is to
+display at most B<infinity> (so: no limit) and at least
+B<negative infinity> (no minimal value) at the top. The bottom of
+the graph has similar defaults. Note that the minimum lower limit
+is the lowest one so you should compare this with maximum upper
+limit when you try to figure out what you should set.
 
-Define virtual name for a data source. This name can then be used
-in the functions explained below. The
-DEF call automatically chooses an B<RRA> which contains I<CF> consolidated data in a
-resolution appropriate for the size of the graph to be drawn.  Ideally
-this means that one data point from the B<RRA> should be represented
-by one pixel in the graph.  If the resolution of the B<RRA> is higher
-than the resolution of the graph, the data in the RRA will be further
-consolidated according to the consolidation function (I<CF>) chosen.
+To make sure the graph shows the range of I<-1000> to I<2000>,
+optionally expanding to no more than I<-3000> to I<4000>,
+set the following options:
 
-=item B<CDEF:>I<vname>B<=>I<rpn-expression>
+--maximum-upper-limit 4000 --minimum-upper-limit 2000
+--maximum-lower-limit -1000 --minimum-lower-limit -3000
 
-Create a new virtual data source by evaluating a mathematical expression,
-specified in Reverse Polish Notation (RPN). If you have ever used a traditional
-HP calculator you already know RPN. The idea behind RPN notation is, 
-that you have a stack and push your data onto this stack. When ever
-you execute an operation, it takes as many data values from the stack
-as needed. The pushing of data is implicit, so when ever you specify a number
-or a variable, it gets pushed automatically. 
+To mimic the old B<rigid> option, you can do:
 
-If this is all a big load of incomprehensible words for you, maybe an
-example helps (a more complete explanation is given in [1]): The
-expression I<vname+3/2> becomes C<vname,3,2,/,+> in RPN. First the three
-values get pushed onto the stack (which now contains (the current
-value of) vname, a 3 and a 2).  Then the / operator pops two values
-from the stack (3 and 2), divides the first argument by the second
-(3/2) and pushes the result (1.5) back onto the stack. Then the +
-operator pops two values (vname and 1.5) from the stack; both values
-are added up and the result gets pushes back onto the stack. In the
-end there is only one value left on the stack: The result of the
-expression.
+--maximum-upper-limit 4000 --minimum-upper-limit 4000
+--maximum-lower-limit -3000 --minimum-lower-limit -3000
 
-The I<rpn-expression> in the B<CDEF> function takes both, constant values
-as well as I<vname> variables. The following operators can be used on these
-values: 
+B<[--alt-autoscale]>
 
-=over
+Sometimes the default algorithm for selecting the y-axis scale is not
+performing very well.  Normally the scale is selected from a predefined
+set of ranges and this fails miserably when you need to graph something
+like C<260 + 0.001 * sin(x)>. This option calculates the minimum and
+maximum y-axis from the actual minimum and maximum values. Our example
+would display slightly less than C<260-0.001> to slightly more than
+C<260+0.001> (Contributed by Sasha Mikheev).
 
-=item +, -, *, /, %
+B<[--alt-autoscale-max]>
 
-pops two values from the stack applies the selected operator and pushes 
-the result back onto the stack. The % operator stands for the modulo
-operation.
-
-=item SIN, COS, LOG, EXP, FLOOR, CEIL
-
-pops one value from the stack, applies the selected function and pushes
-the result back onto the stack.
-
-=item LT, LE, GT, GE, EQ
-
-pops two values from the stack, compares them according to the selected
-condition and pushes either 1 back onto the stack if the condition is true
-and 0 if the condition was not true.
-
-=item IF
-
-pops three values from the stack. If the last value is not 0, the
-second value will be pushed back onto the stack, otherwise the
-first value is pushed back.
-
-If the stack contains the values A, B, C, D, E are presently on the
-stack, the IF operator will pop the values E D and C of the stack. It will
-look at C and if it is not 0 it will push D back onto the stack, otherwise
-E will be sent back to the stack.
+Where C<--alt-autoscale> will modify both the absolute maximum AND minimum
+values, this option will only affect the maximum value. The minimum
+value, if not defined on the command line, will be 0. This option can
+be useful when graphing router traffic when the WAN line uses compression,
+and thus the throughput may be higher than the WAN line speed.
 
-=item MIN, MAX
+Z<>
 
-selects the lesser or larger of the two top stack values respectively
+=item Grid
 
-=item LIMIT
+=over 4
 
-replaces the value with I<*UNKNOWN*> if it is outside the limits specified
-by the two values above it on the stack.
+=item X-Axis
 
- CDEF:a=alpha,0,100,LIMIT
+B<[-x|--x-grid E<lt>I<GTMC<:>GSTC<:>MTMC<:>MSTC<:>LTMC<:>LSTC<:>LPRC<:>LFM>E<gt>|C<none>]>
 
-=item DUP, EXC, POP
+The x-axis label is quite complex to configure, if you don't have
+very special needs it is probably best to rely on the autoconfiguration
+to get this right.  You can specify the string C<none> to skip the grid
+and labels altogether.
 
-These manipulate the stack directly.  DUP will duplicate the top of the
-stack, pushing the result back onto the stack.  EXC will exchange the top
-two elements of the stack, and POP will pop off the top element of the
-stack.  Having insufficient elements on the stack for these operations is
-an error.
+The grid is defined by specifying a certain amount of time in the I<?TM>
+positions. You can choose from C<SECOND>, C<MINUTE>, C<HOUR>, C<DAY>,
+C<WEEK>, C<MONTH> or C<YEAR>. Then you define how many of these should
+pass between each line or label.  This pair (I<?TM:?ST>) needs to be
+specified for the base grid (I<G??>), the major grid (I<M??>) and the
+labels (I<L??>). For the labels you also need to define a precision
+in I<LPR> and a I<strftime> format string in I<LFM>.  I<LPR> defines
+where each label will be placed. If it is zero, the label will be
+placed right under the corresponding line (useful for hours, dates
+etcetera).  If you specify a number of seconds here the label is
+centered in this interval (useful for monday, januari etcetera).
 
-=item UN
+Example: C<--x-grid MINUTE:10:HOUR:1:HOUR:4:0:%X>
 
-Pops one value off the stack, if it is I<*UNKNOWN*>, 1 will be pushed
-back otherwise 0.
+This places grid lines every 10 minutes, major grid lines every hour
+and labels every 4 hours. The labels are placed under the major grid
+lines as they specify exactly that time.
 
-=item UNKN
+Example: C<--x-grid HOUR:8:DAY:1:DAY:1:0:%A>
 
-Push an I<*UNKNOWN*> value onto the stack.
+This places grid lines every 8 hours, major grid lines and labels
+each day. The labels are placed exactly between two major grid lines
+as they specify the complete day and not just midnight.
 
-=item PREV
+Z<>
 
-Push I<*UNKNOWN*> if its at the first value of a data set or otherwise
-the value of this CDEF at the previous time step. This allows you to
-perform calculations across the data.
+=item Y-Axis
 
-=item INF, NEGINF
+B<[-y|--y-grid I<E<lt>grid stepE<gt>:E<lt>label factorE<gt>>|C<none>]>
 
-Push a positive or negative infinite (oo) value onto the stack. When
-drawing an infinite number it appears right at the top or bottom edge of the
-graph, depending whether you have a positive or negative infinite number.
+Y-axis grid lines appear at each I<grid step> interval.  Labels are
+placed every I<label factor> lines.  You can specify C<-y none> to
+skip the grid and labels altogether.  The default for this option is
+to automatically select sensible values.
 
-=item NOW
+B<[--alt-y-grid]>
 
-Push the current (real world) time onto the stack.
+Place Y grid dynamically based on graph Y range. Algorithm ensures
+that you always have grid, that there are enough but not too many
+grid lines and the grid is metric. That is grid lines are placed
+every 1, 2, 5 or 10 units.  (contributed by Sasha Mikheev)
 
-=item TIME
+B<[-o|--logarithmic]>
 
-Push the time the current sample was taken onto the stack. This is the
-number of non-skip seconds since 0:00:00 January 1, 1970.
+Logarithmic y-axis scaling.
 
-=item LTIME
+B<[--units-exponent E<lt>valueE<gt>]>
 
-This is like TIME B<+ current timezone offset in seconds>. The current
-offset takes daylight saving time into account, given your OS supports
-this. If you were looking at a sample, in Zurich, in summer, the
-offset would be 2*3600 seconds, as Zurich at that time of year is 2
-hours ahead of UTC.
+This sets the 10**exponent scaling of the y-axis values.  Normally
+values will be scaled to the appropriate units (k, M, etc.).  However
+you may wish to display units always in k (Kilo, 10e3) even if the data
+is in the M (Mega, 10e6) range for instance.  Value should be an
+integer which is a multiple of 3 between -18 and 18 inclusive.  It is
+the exponent on the units you which to use.  For example, use 3 to
+display the y-axis values in k (Kilo, 10e3, thousands), use -6 to
+display the y-axis values in u (Micro, 10e-6, millionths).  Use a value
+of 0 to prevent any scaling of the y-axis values.
 
-Note that the timezone offset is always calculated for the time the
-current sample was taken at. It has nuthing todo with the time you are
-doing the calculation.
+Z<>
 
 =back
 
-Please note that you may only use I<vname> variables that you
-previously defined by either B<DEF> or B<CDEF>. Furthermore, as of
-this writing (version 0.99.25), you must use at least one I<vname>
-per expression, that is "CDEF:fourtytwo=2,40,+" will yield an error
-message but not a I<vname> fourtytwo that's always equal to 42.
+Z<>
 
-=item B<PRINT:>I<vname>B<:>I<CF>B<:>I<format>
+=item Miscellaneous
 
-Calculate the chosen consolidation function I<CF> over the data-source
-variable I<vname> and C<printf> the result to stdout using I<format>.
-In the I<format> string there should be a '%lf' or '%le' marker in the
-place where the number should be printed.
+B<[-z|--lazy]>
 
-If an additional '%s' is found AFTER the marker, the value will be scaled
-and an appropriate SI magnitude unit will be printed in place of the '%s'
-marker. The scaling will take the '--base' argument into consideration!
+Only generate the graph, if the current graph is out of date or not
+existent.
 
-If a '%S' is used instead of a '%s', then instead of calculating the
-appropriate SI magnitude unit for this value, the previously calculated
-SI magnitude unit will be used.  This is useful if you want all the values
-in a PRINT statement to have the same SI magnitude unit.  If there was
-no previous SI magnitude calculation made, then '%S' behaves like a '%s',
-unless the value is 0, in which case it does not remember a SI magnitude
-unit and a SI magnitude unit will only be calculated when the next '%s' is
-seen or the next '%S' for a non-zero value.
+B<[-f|--imginfo E<lt>printfstrE<gt>]>
 
-If you want to put a '%' into your PRINT string, use '%%' instead.
+After the image has been created, the graph function uses printf
+together with this format string to create output similar to the PRINT
+function, only that the printf is supplied with the parameters
+I<filename>, I<xsize> and I<ysize>. In order to generate an B<IMG> tag
+suitable for including the graph into a web page, the command line
+would look like this:
 
-=item B<GPRINT:>I<vname>B<:>I<CF>B<:>I<format>
+    --imginfo '<IMG SRC="/img/%s" WIDTH="%lu" HEIGHT="%lu" ALT="Demo">'
 
-Same as B<PRINT> but the result is printed into the graph below the legend.
+B<[-c|--color I<COLORTAG#rrggbb>]>
 
-=back
+Override the default colors for the standard elements of the graph.
+The I<COLORTAG> is one of C<BACK> ground, C<CANVAS>, C<SHADEA> for the
+left and top border, C<SHADEB> for the right and bottom border, C<GRID>,
+C<MGRID> for the major grid, C<FONT>, C<FRAME> and axis, C<ARROW>.
+Each color is composed out of three hexadecimal numbers specifying
+its color component (00 is off, FF is maximum) of red, green and blue.
+You may set this option several times to alter multiple defaults.
 
-B<Caveat:> When using the B<PRINT> and B<GRPRINT> functions to
-calculate data summaries over time periods bounded by the current
-time, it is important to note that the last sample will almost always
-yield a value of UNKNOWN as it lies after the last update time.  This
-can result in slight data skewing, particularly with the B<AVERAGE>
-function.  In order to avoid this, make sure that your end time is at
-least one heartbeat prior to the current time.
+A green arrow is made by: C<--color ARROW:00FF00>
 
-=over
+B<[-a|--imgformat C<GIF>|C<PNG>]>
+B<[-i|--interlaced]>
 
+The default is to generate a non-interlaced GIF image. It is recommended
+to generate PNG graphics as they take up to 40% less disk space and
+20-30% less time to generate.
 
-=item B<COMMENT:>I<text>
+B<[-g|--no-legend]>
 
-Like B<GPRINT> but the I<text> is simply printed into the graph.
+Suppress generation of legend; only render the graph.
 
-=item B<HRULE:>I<value>B<#>I<rrggbb>[B<:>I<legend>]
+B<[-b|--base E<lt>valueE<gt>]>
 
-Draw a horizontal rule into the graph and optionally add a legend
+If you are graphing memory (and NOT network traffic) this switch
+should be set to 1024 so that one Kb is 1024 byte. For traffic
+measurement, 1 kb/s is 1000 b/s.
 
-=item B<VRULE:>I<time>B<#>I<rrggbb>[B<:>I<legend>]
+Z<>
 
-Draw a vertical rule into the graph and optionally add a legend
+=item Data and variables
 
-=item B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]
+B<DEF:>I<E<lt>vnameE<gt>>=I<E<lt>rrdfileE<gt>>:I<E<lt>ds-nameE<gt>>:I<E<lt>CFE<gt>>[:[I<E<lt>time rangeE<gt>>][:I<E<lt>step timeE<gt>>]]
 
-Plot for the requested data, using the color specified. Write a legend
-into the graph. The 3 possible keywords B<LINE1>, B<LINE2>, and B<LINE3> 
-generate increasingly wide lines. If no color is defined, 
-the drawing is done 'blind' this is useful in connection with the 
-B<STACK> function when you want to ADD the values of two 
-data-sources without showing it in the graph.
+B<CDEF:>I<E<lt>vnameE<gt>>=I<E<lt>RPN expressionE<gt>>
 
-=item B<AREA>:I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]
+B<VDEF:>I<E<lt>vnameE<gt>>=I<E<lt>RPN expressionE<gt>>
 
-Does the same as B<LINE?>, but the area between 0 and 
-the graph will be filled with the color specified.
+You need at least one B<DEF> statement to generate anything. The
+other statements are useful but optional.
+See L<rrdgraph_data> and L<rrdgraph_rpn> for exact format.
 
-=item B<STACK>:I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]
+Z<>
 
-Does the same as B<LINE?>, but the graph gets stacked on top of the previous
-B<LINE?>, B<AREA> or B<STACK> graph. Depending on the type of the
-previous graph, the B<STACK> will be either a B<LINE?> or an B<AREA>.
-This obviously implies that the first B<STACK> must be preceded by an
-B<AREA> or B<LINE?> -- you need something to stack something onto in
-the first place ;) 
+=item Graph and print elements
 
-Note, that when you STACK onto *UNKNOWN* data, rrdtool will not draw
-any graphics ... *UNKNOWN* is not zero ... if you want it to be zero
-then you might want to use a CDEF argument with IF and UN functions to
-turn *UNKNOWN* into zero ...
+You need at least one graph element to generate an image and/or
+at least one print statement to generate a report.
+See L<rrdgraph_graph> for exact format.
 
-=item B<TICK:>I<vname>B<#>I<rrggbb>[B<:>I<axis-fraction>[B<:>I<legend>]]
+=back
 
-Plot a tick mark (a vertical line) for each value of I<vname> that is
-non-zero and not *UNKNOWN*. The I<axis-fraction> argument specifies the
-length of the tick mark as a fraction of the y-axis; the default value
-is 0.1 (10% of the axis). Note that the color specification is not
-optional.
+=head1 SEE ALSO
 
-=back
+L<rrdgraph> gives an overview of how B<rrdtool graph> works.
+L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail,
+L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements,
+L<rrdgraph_graph> page describes all of the graph and print functions.
 
-=head1 NOTES on legend arguments
-
-=head2 Escaping the colon
-
-In a ':' in a I<legend> argument will mark the end of the legend. To
-enter a ':' into a legend, the colon must be escaped with a backslash '\:'.
-Beware, that many environments look for backslashes themselves, so it may
-be necessary to write two backslashes so that one is passed onto rrd_graph.
-
-=head2 String Formatting
-
-The text printed below the actual graph can be formated by appending special
-escaped characters at the end of a text. When ever such a character occurs,
-all pending text is pushed onto the graph according to the character
-specified.
-
-Valid markers are: B<\j> for justified, B<\l> for left aligned, B<\r> for
-right aligned and B<\c> for centered. In the next section there is an
-example showing how to use centered formating.
-
-Normally there are two space characters inserted between every two items
-printed into the graph. The space following a string can be suppressed by
-putting a B<\g> at the end of the string. The B<\g> also squshes any space
-inside the string if it is at the very end of the string. This can be used
-in connection with B<%s> to supress empty unit strings.
-
- GPRINT:a:MAX:%lf%s\g
-
-A special case is COMMENT:B<\s> this inserts some additional vertical space
-before placing the next row of legends.
-
-=head1 NOTE on Return Values
-
-Whenever rrd_graph gets called, it prints a line telling the size of
-the gif it has just created to STDOUT. This line looks like this: XSIZExYSIZE.
-
-=head1 EXAMPLE 1
-
-  rrdtool graph demo.gif --title="Demo Graph" \
-          DEF:cel=demo.rrd:exhaust:AVERAGE \
-          "CDEF:far=cel,1.8,*,32,+"" \
-          LINE2:cel#00a000:"D. Celsius" \
-          LINE2:far#ff0000:"D. Fahrenheit\c"
-
-=head1 EXAMPLE 2
-
-This example demonstrates the syntax for using IF and UN to set
-I<*UNKNOWN*> values to 0.  This technique is useful if you are
-aggregating interface data where the start dates of the data sets
-doesn't match.
-
-  rrdtool graph demo.gif --title="Demo Graph" \
-         DEF:idat1=interface1.rrd:ds0:AVERAGE \
-         DEF:idat2=interface2.rrd:ds0:AVERAGE \
-         DEF:odat1=interface1.rrd:ds1:AVERAGE \
-         DEF:odat2=interface2.rrd:ds1:AVERAGE \
-         CDEF:agginput=idat1,UN,0,idat1,IF,idat2,UN,0,idat2,IF,+,8,* \
-         CDEF:aggoutput=odat1,UN,0,odat1,IF,odat2,UN,0,odat2,IF,+,8,* \
-         AREA:agginput#00cc00:Input Aggregate \
-         LINE1:agginput#0000FF:Output Aggregate
-         
-Assuming that idat1 has a data value of I<*UNKNOWN*>, the CDEF expression 
-
- idat1,UN,0,idat1,IF 
-
-leaves us with a stack with contents of 1,0,NaN and the IF function
-will pop off the 3 values and replace them with 0.  If idat1 had a
-real value like 7942099, then the stack would have 0,0,7942099 and the
-real value would be the replacement.  
-
-=head1 EXAMPLE 3
-
-This example shows two ways to use the INF function. First it makes
-the background change color during half of the hours. Then, it uses
-AREA and STACK to draw a picture. If one of the inputs was UNKNOWN,
-all inputs are overlaid with another AREA.
-
-  rrdtool graph example.png --title="INF demo" \
-         DEF:val1=some.rrd:ds0:AVERAGE \
-         DEF:val2=some.rrd:ds1:AVERAGE \
-         DEF:val3=some.rrd:ds2:AVERAGE \
-         DEF:val4=other.rrd:ds0:AVERAGE \
-         CDEF:background=val4,POP,TIME,7200,%,3600,LE,INF,UNKN,IF \
-         CDEF:wipeout=val1,val2,val3,val4,+,+,+,UN,INF,UNKN,IF \
-         AREA:background#F0F0F0 \
-         AREA:val1#0000FF:Value1 \
-         STACK:val2#00C000:Value2 \
-         STACK:val3#FFFF00:Value3 \
-         STACK:val4#FFC000:Value4 \
-         AREA:wipeout#FF0000:Unknown
-
-The first CDEF uses val4 as a dummy value. It's value is removed immediately
-from the stack. Then a decision is made based on the time that a sample was
-taken. If it is an even hour (UTC time !) then the area will be filled. If
-it is not, the value is set to UNKN and is not plotted.
-
-The second CDEF looks if any of val1,val2,val3,val4 is unknown. It does so by
-checking the outcome of sum(val1,val2,val3,val4). Again, INF is returned when
-the condition is true, UNKN is used to not plot the data.
-
-The different items are plotted in a particular order. First do the background, then use a
-normal area to overlay it with data. Stack the other data until they are all plotted. Last but
-not least, overlay everything with eye-hurting red
-to signal any unknown data.
-
-Note that this example assumes that your data is in the positive half of the y-axis
-otherwhise you would would have to add NEGINF in order to extend the coverage
-of the rea to whole graph.
-
-=head1 EXAMPLE 4
-
-If the specialized function B<RRAs> exist for aberrant behavior detection, they
-can be used to generate the graph of a time series with confidence bands and
-failures.
-
-   rrdtool graph example.gif \
-          DEF:obs=monitor.rrd:ifOutOctets:AVERAGE \
-          DEF:pred=monitor.rrd:ifOutOctets:HWPREDICT \
-          DEF:dev=monitor.rrd:ifOutOctets:DEVPREDICT \
-          DEF:fail=monitor.rrd:ifOutOctets:FAILURES \
-          TICK:fail#ffffa0:1.0:"Failures\: Average bits out" \
-          CDEF:scaledobs=obs,8,* \
-          CDEF:upper=pred,dev,2,*,+ \
-          CDEF:lower=pred,dev,2,*,- \
-          CDEF:scaledupper=upper,8,* \
-          CDEF:scaledlower=lower,8,* \
-          LINE2:scaledobs#0000ff:"Average bits out" \
-          LINE1:scaledupper#ff0000:"Upper Confidence Bound: Average bits out" \
-          LINE1:scaledlower#ff0000:"Lower Confidence Bound: Average bits out"
-
-This example generates a graph of the data series in blue (LINE2 with the scaledobs
-virtual data source), confidence bounds in red (scaledupper and scaledlower virtual
-data sources), and potential failures (i.e. potential aberrant aberrant behavior)
-marked by vertical yellow lines (the fail data source).
-
-The raw data comes from an AVERAGE B<RRA>, the finest resolution of the observed
-time series (one consolidated data point per primary data point). The predicted
-(or smoothed) values are stored in the HWPREDICT B<RRA>. The predicted deviations
-(think standard deviation) values are stored in the DEVPREDICT B<RRA>. Finally,
-the FAILURES B<RRA> contains indicators, with 1 denoting a potential failure.
-
-All of the data is rescaled to bits (instead of Octets) by multiplying by 8.
-The confidence bounds are computed by an offset of 2 deviations both above
-and below the predicted values (the CDEFs upper and lower). Vertical lines
-indicated potential failures are graphed via the TICK graph element, which
-converts non-zero values in an B<RRA> into tick marks. Here an axis-fraction
-argument of 1.0 means the tick marks span the entire y-axis, and hence become
-vertical lines on the graph.
-
-The choice of 2 deviations (a scaling factor) matches the default used internally
-by the FAILURES B<RRA>. If the internal value is changed (see L<rrdtune>), this
-graphing command should be changed to be consistent.
-
-=head2 A note on data reduction:
-
-The B<rrdtool> I<graph> command is designed to plot data at a specified temporal
-resolution, regardless of the actually resolution of the data in the RRD file.
-This can present a problem for the specialized consolidation functions which
-maintain a one-to-one mapping between primary data points and consolidated
-data points. If a graph insists on viewing the contents of these B<RRAs> on a
-coarser temporal scale, the I<graph> command tries to do something intelligent,
-but the confidence bands and failures no longer have the same meaning and may
-be misleading.
+Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
 
 =head1 AUTHOR
 
-Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt>
-
-=head1 REFERENCES
+Program by Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt>
 
-[1] http://www.dotpoint.com/xnumber/rpn_or_adl.htm
+This manual page by Alex van den Bogaerdt E<lt>alex@ergens.op.het.netE<gt>

diff --git a/doc/rrdgraph.src b/doc/rrdgraph.src
new file mode 100644 (file)
index 0000000..3f9bda8
--- /dev/null
+++ b/doc/rrdgraph.src
@@ -0,0 +1,325 @@
+=include name
+
+=head1 SYNOPSYS
+
+B<rrdtool graph> I<filename>
+[E<lt>B<L<option|rrdgraph/OPTIONS>>E<gt> ...]
+E<lt>B<L<data definition|rrdgraph_data/DEF>>E<gt>
+[E<lt>B<L<data definition|rrdgraph_data/DEF>>E<gt> ...]
+[E<lt>B<L<data calculation|rrdgraph_data/CDEF>>E<gt> ...]
+[E<lt>B<L<variable definition|rrdgraph_data/VDEF>>E<gt> ...]
+[E<lt>B<L<graph element|rrdgraph_graph/GRAPH>>E<gt> ...]
+[E<lt>B<L<print element|rrdgraph_graph/PRINT>>E<gt> ...]
+
+=head1 DESCRIPTION
+
+The B<graph> function of B<RRDtool> is used to represent the
+data from an B<RRD> to a human viewer.  Its main purpose is to
+create a nice graphical representation but it can also generate
+a numerical report.
+
+=head1 OVERVIEW
+
+B<rrdtool graph> needs data to work with, use one or more
+B<L<data definition|rrdgraph_data/DEF>> statements to collect this
+data.  You are not limited to one database, it's perfectly legal to
+collect data from two or more databases (one per statement though).
+
+If you want to display averages, maxima, percentiles etcetera
+it is best to collect them now using the
+B<L<variable definition|rrdgraph_data/VDEF>> statement.  At this
+stage, this command works at the unprocessed data from the B<RRD>.
+I<(Note: this is not yet true; it works on consolidated information
+right now)>
+
+The data fetched from the B<RRA> is then B<consolidated> so that
+there is exactly one datapoint per pixel in the graph. If you do
+not take care yourself, B<RRDtool> will expand the range slightly
+if necessary (in that case the first pixel may very well become
+unknown!).
+
+Sometimes data is not exactly as you would like to display it. For
+instance, you might be collecting B<bytes> per second but want to
+display B<bits> per second. This is where the
+B<L<data calculation|rrdgraph_data/CDEF>> command is designed for.
+After B<consolidating> the data, a copy is made and this copy is
+modified using a rather flexible B<L<RPN|rrdgraph_rpn/>> command
+set.  If you use B<L<variable definition|rrdgraph_data/VDEF>>
+statements after this, they work on the consolidated data and may
+return other values for maximum, minimum etcetera!
+
+When you are done fetching and processing the data, it is time to
+graph it (or print it).  This ends the B<rrdtool graph> sequence.
+
+=head1 OPTIONS
+
+It is expected that most options will move to the graph definition
+statements (after all, most of them do define graph elements...).
+
+=over 4
+
+=item filename
+
+The name and path of the graph to generate. It is recommended to
+end this in C<.png> or C<.gif> but B<rrdtool> does not enforce this.
+
+I<filename> can be 'C<->' to send the image to C<stdout>. In
+that case, no other output is generated.  
+
+Z<>
+
+=item Time range
+
+B<[-s|--start E<lt>timeE<gt>]>
+B<[-e|--end E<lt>timeE<gt>]>
+B<[--step E<lt>secondsE<gt>]>
+
+The start and end of what you would like to display, and which
+B<RRA> the data should come from.  Defaults are: 1 day ago until
+now, with the best possible resolution. B<Start> and B<end> can 
+be specified in several formats, see
+L<AT-STYLE TIME SPECIFICATION|rrdfetch/> and L<rrdgraph_examples>.
+By default, B<rrdtool graph> calculates the width of one pixel in
+the time domain and tries to get data from an B<RRA> with that
+resolution.  With the B<step> option you can alter this behaviour.
+If you want B<rrdtool graph> to get data at a one-hour resolution
+from the B<RRD>, set B<step> to 3600.  Note: a step smaller than
+one pixel will silently be ignored.
+
+Z<>
+
+=item Labels
+
+B<[-t|--title E<lt>stringE<gt>]>
+B<[-v|--vertical-label E<lt>stringE<gt>]>
+
+A horizontal string at the top of the graph and/or a vertically
+placed string at the left hand side of the graph. I<New: (not
+yet implemented)> The string can contain formatter options that
+are used to include variables (from B<VDEF>s) and newlines.
+
+Z<>
+
+=item Size
+
+B<[-w|--width E<lt>pixelsE<gt>]>
+B<[-h|--heigth E<lt>pixelsE<gt>]>
+
+The width and height of the B<canvas> (the part of the graph with
+the actual lines and such). Defaults are 400 pixels by 100 pixels.
+
+Z<>
+
+=item Limits
+
+I<Old behaviour, until the new options are implemented>
+B<[-u|--upper-limit E<lt>valueE<gt>]>
+B<[-l|--lower-limit E<lt>valueE<gt>]>
+B<[-r|--rigid]>
+
+By default the graph will be autoscaling so that it displays the
+portion of the y-axis that is actually used. You can change this
+behaviour by setting the limits.  The displayed y-axis will show
+at least from B<lower-limit> to B<upper-limit>.  Autoscaling will
+still permit those boundaries to be stretched unless the B<rigid>
+option is set.
+
+I<New behaviour, after the new options are implemented>
+B<[--maximum-upper-limit E<lt>valueE<gt>]>
+B<[--minimum-upper-limit E<lt>valueE<gt>]>
+B<[--maximum-lower-limit E<lt>valueE<gt>]>
+B<[--minimum-lower-limit E<lt>valueE<gt>]>
+
+By default the graph will be autoscaling so that it displays the
+portion of the y-axis that is actually used. You can change this
+behaviour by setting the limits.  The displayed y-axis will show
+at most B<maximum-upper-limit> and at least B<minimum-upper-limit>
+at the top, and similarily at least B<maximum-lower-limit> and
+at most B<minimum-lower-limit> at the bottom.  The default is to
+display at most B<infinity> (so: no limit) and at least
+B<negative infinity> (no minimal value) at the top. The bottom of
+the graph has similar defaults. Note that the minimum lower limit
+is the lowest one so you should compare this with maximum upper
+limit when you try to figure out what you should set.
+
+To make sure the graph shows the range of I<-1000> to I<2000>,
+optionally expanding to no more than I<-3000> to I<4000>,
+set the following options:
+
+--maximum-upper-limit 4000 --minimum-upper-limit 2000
+--maximum-lower-limit -1000 --minimum-lower-limit -3000
+
+To mimic the old B<rigid> option, you can do:
+
+--maximum-upper-limit 4000 --minimum-upper-limit 4000
+--maximum-lower-limit -3000 --minimum-lower-limit -3000
+
+B<[--alt-autoscale]>
+
+Sometimes the default algorithm for selecting the y-axis scale is not
+performing very well.  Normally the scale is selected from a predefined
+set of ranges and this fails miserably when you need to graph something
+like C<260 + 0.001 * sin(x)>. This option calculates the minimum and
+maximum y-axis from the actual minimum and maximum values. Our example
+would display slightly less than C<260-0.001> to slightly more than
+C<260+0.001> (Contributed by Sasha Mikheev).
+
+B<[--alt-autoscale-max]>
+
+Where C<--alt-autoscale> will modify both the absolute maximum AND minimum
+values, this option will only affect the maximum value. The minimum
+value, if not defined on the command line, will be 0. This option can
+be useful when graphing router traffic when the WAN line uses compression,
+and thus the throughput may be higher than the WAN line speed.
+
+Z<>
+
+=item Grid
+
+=over 4
+
+=item X-Axis
+
+B<[-x|--x-grid E<lt>I<GTMC<:>GSTC<:>MTMC<:>MSTC<:>LTMC<:>LSTC<:>LPRC<:>LFM>E<gt>|C<none>]>
+
+The x-axis label is quite complex to configure, if you don't have
+very special needs it is probably best to rely on the autoconfiguration
+to get this right.  You can specify the string C<none> to skip the grid
+and labels altogether.
+
+The grid is defined by specifying a certain amount of time in the I<?TM>
+positions. You can choose from C<SECOND>, C<MINUTE>, C<HOUR>, C<DAY>,
+C<WEEK>, C<MONTH> or C<YEAR>. Then you define how many of these should
+pass between each line or label.  This pair (I<?TM:?ST>) needs to be
+specified for the base grid (I<G??>), the major grid (I<M??>) and the
+labels (I<L??>). For the labels you also need to define a precision
+in I<LPR> and a I<strftime> format string in I<LFM>.  I<LPR> defines
+where each label will be placed. If it is zero, the label will be
+placed right under the corresponding line (useful for hours, dates
+etcetera).  If you specify a number of seconds here the label is
+centered in this interval (useful for monday, januari etcetera).
+
+Example: C<--x-grid MINUTE:10:HOUR:1:HOUR:4:0:%X>
+
+This places grid lines every 10 minutes, major grid lines every hour
+and labels every 4 hours. The labels are placed under the major grid
+lines as they specify exactly that time.
+
+Example: C<--x-grid HOUR:8:DAY:1:DAY:1:0:%A>
+
+This places grid lines every 8 hours, major grid lines and labels
+each day. The labels are placed exactly between two major grid lines
+as they specify the complete day and not just midnight.
+
+Z<>
+
+=item Y-Axis
+
+B<[-y|--y-grid I<E<lt>grid stepE<gt>:E<lt>label factorE<gt>>|C<none>]>
+
+Y-axis grid lines appear at each I<grid step> interval.  Labels are
+placed every I<label factor> lines.  You can specify C<-y none> to
+skip the grid and labels altogether.  The default for this option is
+to automatically select sensible values.
+
+B<[--alt-y-grid]>
+
+Place Y grid dynamically based on graph Y range. Algorithm ensures
+that you always have grid, that there are enough but not too many
+grid lines and the grid is metric. That is grid lines are placed
+every 1, 2, 5 or 10 units.  (contributed by Sasha Mikheev)
+
+B<[-o|--logarithmic]>
+
+Logarithmic y-axis scaling.
+
+B<[--units-exponent E<lt>valueE<gt>]>
+
+This sets the 10**exponent scaling of the y-axis values.  Normally
+values will be scaled to the appropriate units (k, M, etc.).  However
+you may wish to display units always in k (Kilo, 10e3) even if the data
+is in the M (Mega, 10e6) range for instance.  Value should be an
+integer which is a multiple of 3 between -18 and 18 inclusive.  It is
+the exponent on the units you which to use.  For example, use 3 to
+display the y-axis values in k (Kilo, 10e3, thousands), use -6 to
+display the y-axis values in u (Micro, 10e-6, millionths).  Use a value
+of 0 to prevent any scaling of the y-axis values.
+
+Z<>
+
+=back
+
+Z<>
+
+=item Miscellaneous
+
+B<[-z|--lazy]>
+
+Only generate the graph, if the current graph is out of date or not
+existent.
+
+B<[-f|--imginfo E<lt>printfstrE<gt>]>
+
+After the image has been created, the graph function uses printf
+together with this format string to create output similar to the PRINT
+function, only that the printf is supplied with the parameters
+I<filename>, I<xsize> and I<ysize>. In order to generate an B<IMG> tag
+suitable for including the graph into a web page, the command line
+would look like this:
+
+    --imginfo '<IMG SRC="/img/%s" WIDTH="%lu" HEIGHT="%lu" ALT="Demo">'
+
+B<[-c|--color I<COLORTAG#rrggbb>]>
+
+Override the default colors for the standard elements of the graph.
+The I<COLORTAG> is one of C<BACK> ground, C<CANVAS>, C<SHADEA> for the
+left and top border, C<SHADEB> for the right and bottom border, C<GRID>,
+C<MGRID> for the major grid, C<FONT>, C<FRAME> and axis, C<ARROW>.
+Each color is composed out of three hexadecimal numbers specifying
+its color component (00 is off, FF is maximum) of red, green and blue.
+You may set this option several times to alter multiple defaults.
+
+A green arrow is made by: C<--color ARROW:00FF00>
+
+B<[-a|--imgformat C<GIF>|C<PNG>]>
+B<[-i|--interlaced]>
+
+The default is to generate a non-interlaced GIF image. It is recommended
+to generate PNG graphics as they take up to 40% less disk space and
+20-30% less time to generate.
+
+B<[-g|--no-legend]>
+
+Suppress generation of legend; only render the graph.
+
+B<[-b|--base E<lt>valueE<gt>]>
+
+If you are graphing memory (and NOT network traffic) this switch
+should be set to 1024 so that one Kb is 1024 byte. For traffic
+measurement, 1 kb/s is 1000 b/s.
+
+Z<>
+
+=item Data and variables
+
+B<DEF:>I<E<lt>vnameE<gt>>=I<E<lt>rrdfileE<gt>>:I<E<lt>ds-nameE<gt>>:I<E<lt>CFE<gt>>[:[I<E<lt>time rangeE<gt>>][:I<E<lt>step timeE<gt>>]]
+
+B<CDEF:>I<E<lt>vnameE<gt>>=I<E<lt>RPN expressionE<gt>>
+
+B<VDEF:>I<E<lt>vnameE<gt>>=I<E<lt>RPN expressionE<gt>>
+
+You need at least one B<DEF> statement to generate anything. The
+other statements are useful but optional.
+See L<rrdgraph_data> and L<rrdgraph_rpn> for exact format.
+
+Z<>
+
+=item Graph and print elements
+
+You need at least one graph element to generate an image and/or
+at least one print statement to generate a report.
+See L<rrdgraph_graph> for exact format.
+
+=back
+
+=include see_also

diff --git a/doc/rrdgraph_data.src b/doc/rrdgraph_data.src
new file mode 100644 (file)
index 0000000..938fb10
--- /dev/null
+++ b/doc/rrdgraph_data.src
@@ -0,0 +1,73 @@
+=include name
+
+=head1 SYNOPSYS
+
+B<DEF>:I<vname>=I<RRD file>:I<ds name>:I<CF>[:[I<time range>][:I<step size>]]
+
+B<VDEF>:I<vname>=I<RPN expression>
+
+B<CDEF>:I<vname>=I<RPN expression>
+
+=head1 DESCRIPTION
+
+These three instructions collect the data out of the B<RRD> files,
+optionally altering it (think of a bytes to bits conversion) and
+if desired you can define variables containing useful information
+such as maximum, mininimum etcetera. Two of the instructions use
+a language called B<RPN> which is described in its own manual page.
+
+=head1 DEF
+
+B<DEF>:I<vname>=I<RRD file>:I<ds name>:I<CF>[:[I<time range>][:I<step size>]]
+
+This command fetches data from an B<RRD> file.  The virtual name
+I<vname> can then be used throughout the rest of the script. By
+default, an B<RRA> which contains the correct consolidated data
+at an appropriate resolution will be chosen.  The resolution can
+be overriden with the L<--step|rrdgraph/item_Time> option. 
+I<Not yet implemented:>[ The resolution can be overriden by specifying
+the B<step size>.]  I<Not yet implemented:> [ The time span of this data
+is the same as for the graph by default, you can override this by
+specifying the B<time range>. ]
+
+If the resolution of the data is higher than the resolution of off
+graph, the data will be further consolidated.  This may result in
+a graph that spans slightly more time than requested.
+Ideally each point in the graph should correspond with one B<CDP>
+from an B<RRA>.  For instance, if your B<RRD> has an B<RRA> with
+a resolution of 1800 seconds per B<CDP>, you should create an
+image with width 400 and time span 400*1800 seconds (use appropriate
+start and end times, such as C<--start end-8days8hours>).
+
+Example: C<DEF:mydata=router.rrd:ds0:AVERAGE>
+
+Example: C<DEF:januari=router.rrd:ds0:AVERAGE:start=20010101 end=20010201>
+
+=head1 VDEF
+
+B<VDEF>:I<vname>=I<RPN expression>
+
+This command returns a value and/or a time according to the B<RPN>
+statements used. The resulting I<vname> will, depending on the
+functions used, have a value and a time component.  When you use
+this I<vname> in another B<RPN> expression, you are effectively
+inserting its value just as if you had put a number at that place.
+The variable can also be used in the various graph and print
+elements. I<Not yet implemented:> [ Everywhere you can insert a
+number, you can also use the B<VDEF> (provided that it is set of course) ]
+
+Example: C<VDEF:avg=mydata,AVERAGE>
+
+=head1 CDEF
+
+B<CDEF>:I<vname>=I<RPN expression>
+
+This command creates a new set of data points (in memory only, not
+in the B<RRD> file) out of one or more other data series. The B<RPN>
+instructions are used to evaluate a mathematical function on each
+data point. The resulting I<vname> can then be used further on in
+the script, just as if it were generated by a B<DEF> instruction.
+
+Example: C<CDEF:mydatabits=mydata,8,*>
+
+=include see_also

diff --git a/doc/rrdgraph_examples.src b/doc/rrdgraph_examples.src
new file mode 100644 (file)
index 0000000..2c61c40
--- /dev/null
+++ b/doc/rrdgraph_examples.src
@@ -0,0 +1,111 @@
+=include name
+
+=head1 SYNOPSYS
+
+B<rrdtool graph /home/httpd/html/test.png --img-format PNG \>
+
+followed by any of the examples below
+
+=head1 DESCRIPTION
+
+For your convenience some of the commands are explained here
+by using detailed examples. They are not always cut-and-paste
+ready because comments are intermixed with the examples.
+
+=head1 EXAMPLES
+
+=head2 Nicely formatted legend section
+
+    DEF:ds0=/home/rrdtool/data/router1.rrd:ds0:AVERAGE
+    DEF:ds1=/home/rrdtool/data/router1.rrd:ds1:AVERAGE
+    VDEF:ds0max=ds0,MAXIMUM,8,*
+    VDEF:ds0avg=ds0,AVERAGE,8,*
+    VDEF:ds0min=ds0,MINIMUM,8,*
+    VDEF:ds0pct=95,ds0,PERCENTILE,8,*
+    VDEF:ds1max=ds1,MAXIMUM,8,*
+    VDEF:ds1avg=ds1,AVERAGE,8,*
+    VDEF:ds1min=ds1,MINIMUM,8,*
+    VDEF:ds1pct=95,ds1,PERCENTILE,8,*
+Note: consolidation occurs here.
+    CDEF:ds0bits=ds0,8,*
+    CDEF:ds1bits=ds1,8,*
+Note: 10 spaces to move text to the right
+    COMMENT:"          "
+Note: three times size == 11 chars, "###.## xBps"
+    COMMENT:"Maximum    "
+    COMMENT:"Average    "
+    COMMENT:"Minimum    "
+Note: last line contains new-line character
+    COMMENT:"95th percentile\n"
+    AREA:ds0bits#00C000:"Inbound "
+    GPRINT:ds0max:"%6.2lf %Sbps"
+    GPRINT:ds0avg:"%6.2lf %Sbps"
+    GPRINT:ds0min:"%6.2lf %Sbps"
+    GPRINT:ds0pct:"%6.2lf %Sbps\n"
+    LINE1:ds1bits#0000FF:"Outbound"
+    GPRINT:ds1max:"%6.2lf %Sbps"
+    GPRINT:ds1avg:"%6.2lf %Sbps"
+    GPRINT:ds1min:"%6.2lf %Sbps"
+    GPRINT:ds1pct:"%6.2lf %Sbps\n"
+
+=head2 Offsetting a line on the y-axis
+
+Depending on your needs you can do this in two ways:
+
+=over 4
+
+=item *
+
+Offset the data, then graph this
+
+    DEF:mydata=my.rrd:ds:AVERAGE
+Note: this will also influence anything that uses "data"
+    CDEF:data=mydata,100,+
+    LINE1:data#FF0000:"Data with offset"
+
+=item *
+
+Graph the original data, with an offset
+
+    DEF:mydata=my.rrd:ds:AVERAGE
+Note: no color in the first line so it is not visible
+    LINE1:100
+Note: the second line gets stacked on top of the first one
+    LINE1:data#FF0000:"Data with offset":STACK
+
+=back
+
+=head2 Time ranges
+
+    Last four weeks: --start end-4w --end 00:00
+    Januari 2001:    --start 200101010000 --end start+31d
+    Januari 2001:    --start 200101010000 --end 200102010000
+    Last hour:       --start end-1h
+    Last 24 hours:   <nothing at all>
+    Yesterday:       --end 00:00
+
+=head2 Viewing Januari+Februari 2000 and 2001 together
+
+Define a graph area of 31+29 days (!) spanning Jan. and Feb.
+    --start 20000101 --end 20000301
+    DEF:jan2000=router.rrd:ds0:AVERAGE:start 20000101 end start+31d
+    DEF:jan2001=router.rrd:ds0:AVERAGE:start 20010101 end start+31d
+Note: mind the extra day in 2000 ...
+    DEF:feb2000=router.rrd:ds0:AVERAGE:start 20000201 end start+29d
+Note: 29 feb 2001 is *unknown*
+    DEF:feb2001=router.rrd:ds0:AVERAGE:start 20010201 end start+28d
+    VDEF:offset=jan2001,FIRST,jan2000,FIRST,-,-1,*
+    [ more of the usual VDEF and CDEF stuff if you like ]
+    LINE1:jan2000#00003F:"Januari 2000"
+    [ gprint stuff ]
+    LINE1:feb2001#003F00:"Februari 2000"
+    [ gprint stuff ]
+Note: offset is made negative by the VDEF statement
+    SHIFT:offset
+    LINE1:jan2001#0000FF:"Januari 2001"
+    [ gprint stuff ]
+    LINE1:feb2001#00FF00:"Februari 2001"
+    [ gprint stuff ]
+
+=include see_also
+

diff --git a/doc/rrdgraph_graph.src b/doc/rrdgraph_graph.src
new file mode 100644 (file)
index 0000000..44beac7
--- /dev/null
+++ b/doc/rrdgraph_graph.src
@@ -0,0 +1,222 @@
+=include name
+
+=head1 SYNOPSYS
+
+I<Depriciated commands>
+
+[B<PRINT:>I<vname>B<:>I<CF>B<:>I<format>]
+[B<GPRINT:>I<vname>B<:>I<CF>B<:>I<format>]
+[B<HRULE:>I<value>B<#>I<rrggbb>[B<:>I<legend>]]
+[B<STACK:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]]
+
+I<available commands>
+
+[B<PRINT:>I<vname>B<:>I<format>]
+[B<GPRINT:>I<vname>B<:>I<format>]
+[B<COMMENT:>I<text>]
+[B<VRULE:>I<vname>B<#>I<rrggbb>[B<:>I<legend>]]
+[B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]][B<:STACK>]
+[B<AREA:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]][B<:STACK>]
+
+I<to be implemented commands>
+
+[B<SHIFT:>I<vname>]
+[B<PART:>I<vname>B<#>I<rrggbb>[B<:>I<legend>]]
+
+=head1 DESCRIPTION
+
+These instructions allow you to generate your image or report.
+If you don't use any graph elements, no graph is generated.
+Similarly no report is generated if you don't use print options.
+
+=head1 PRINT
+
+B<PRINT:>I<vname>B<:>I<CF>B<:>I<format>
+
+I<Depriciated. Use the new form of this command in new scripts.>
+The first form of this command is to be used with B<CDEF> I<vname>s.
+
+B<PRINT:>I<vname>B<:>I<format>
+
+Depending on the context, either the value component or the time
+component of a B<VDEF> is printed using I<format>. It is an error
+to specify a I<vname> generated by a B<DEF> or B<CDEF>.
+
+Any text in I<format> is printed literally with one exception:
+The percent character introduces a formatter string. This string
+can be:
+
+For printing values:
+
+=over 4
+
+=item *
+
+B<%%> just prints a literal '%' character
+
+=item *
+
+B<%#.#le> (where # is an optional number) prints like 1.2346e+04
+
+=item *
+
+B<%#.#lf> prints like 12345.6789
+
+=item *
+
+B<%s> place this after B<%le> or B<%lf>.  This will be replaced by the
+appropriate SI magnitude unit and the value will be scaled
+accordingly (123456 -> 123.456 k)
+
+=item *
+
+B<%S> is similar to B<%s>. It does however use a previously defined
+magnitude unit. If there is no such unit yet, it tries to define
+one (just like B<%s>). However, if the value is zero, the magnitude
+unit stays undefined. Thus, formatter strings using B<%S> and no B<%s>
+will all use the same magnitude unit except for zero values.
+
+=back
+
+For printing times:
+
+=over 4
+
+=item *
+
+B<%%> just prints a literal '%' character
+
+=item *
+
+B<%a, %A> prints abbreviated, full weekday name
+
+=item *
+
+B<%b, %B> prints abbreviated, full month name
+
+=item *
+
+B<%d, %m, %y, %H, %M, %S> day,month,year,hour,minute,second all in two-digit format
+
+=item *
+
+B<%Y> year in 4-digit format
+
+=item *
+
+B<%I, %p>  hour (01..12), 'am' or 'pm'
+
+=item *
+
+B<%j, %w> day of the week (0..6), day of the year (1..366)
+
+=item *
+
+B<%c, %x, %X> date+time, date, time
+
+=item *
+
+B<%U, %W> week number of the current year with either the first sunday or
+the first monday determining the first week
+
+=item *
+
+B<%Z> time zone
+
+=back
+
+=head1 GRAPH
+
+B<GPRINT:>I<vname>B<:>I<CF>B<:>I<format>
+
+I<Depriciated. Use the new form of this command in new scripts.>
+This is the same as B<PRINT> but now it is printed inside the graph.
+See L<PRINT> for more information.
+
+B<GPRINT:>I<vname>B<:>I<format>
+
+This is the same as B<PRINT> but now it is printed inside the graph.
+See L<PRINT> for more information.
+
+B<COMMENT:>I<text>
+
+Text is printed literally in the legend section of the graph
+
+B<HRULE:>I<value>B<#>I<rrggbb>[B<:>I<legend>]
+
+I<Depriciated. Use a VDEF and a LINEx in new scripts.>
+
+Draw an horizontal line at I<value>. Its color is composed from three
+hexadecimal numbers specifying the color components (00 is off, FF is
+maximum) red, green and blue.  Optionally a legend box and string is
+printed in the legend section.
+
+B<VRULE:>I<time>B<#>I<rrggbb>[B<:>I<legend>]
+
+Draw a vertical line at I<time>.  Its color is composed from three
+hexadecimal numbers specifying the color components (00 is off, FF is
+maximum) red, green and blue.  Optionally a legend box and string is
+printed in the legend section. I<time> may be a number or a variable
+from a B<VDEF>. It is an error to use I<vname>s from B<DEF> or B<CDEF> here.
+
+B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]][B<:STACK>]
+
+Draw a line of the specified width into the graph. If the color
+is not specified, the drawing is done 'blind'.  This is useful when
+stacking something else on top of this line. Also optional is the
+legend box and string which will be printed in the legend section
+if specified. The B<vname> can be generated by B<DEF>, B<VDEF> and
+B<CDEF>.  If the optional B<STACK> modifier is used, this line is
+stacked on top of the previous element which can be a B<LINEx> or
+an B<AREA>
+
+B<AREA:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]][B<:STACK>]
+
+See B<LINEx>, however the area between the x-axis and the line will
+also be filled.
+
+B<STACK:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]
+
+I<Depriciated.  Use the B<STACK> modifiers on the other commands.>
+I<Note: the comments on stacking are still valid...>
+Repeats the last B<LINEx> or B<AREA> however it doesn't start at the
+x-axis but rather on top of the previous element. This implies that
+there needs to be something to stack on. An invisible B<LINEx> or
+B<AREA> is something you can stack on!
+
+Note: When you stack on something that was I<unknown>, the whole
+stack will be I<unknown> for that point in time. If the beginning
+is undefined, there's no way to end somewhere...  If you want to
+graph this stacked variable anyway you need to make sure that the
+B<LINEx> or B<AREA> it gets stacked on is not unknown. Use a CDEF
+instruction with B<IF> and B<UN> to do so.
+
+B<THE NEXT STUFF IS NOT YET IMPLEMENTED>
+
+B<SHIFT:>I<offset in seconds>
+
+Using this command B<RRDtool> will graph the following elements
+with the specified offset.  For instance, you can specify an
+offset of S<( 7*24*60*60 = ) 604800 seconds> to "look back" one
+week. Make sure to notify the viewer you did so...
+The offset will be valid until the next B<SHIFT> command, which
+can have an offset of zero to restore normal graphing.
+As with the other grapher elements, you can specify a number or
+a variable here.
+
+B<RRDtool> has now support for B<pie charts>. If you include the
+B<PART> command, the canvas is extended to make room for a chart
+(or, if no other graph elements are used, the canvas is solely
+used for the pie chart). The size of the canvas is determined by
+the lesser of L<width and height|rrdgraph/item_Size>.
+
+B<PART:>I<vname>B<#>I<rrggbb>[B<:>I<legend>]
+
+Draw a part of pie. Pie parts will be concatenated, the first one
+will start at the top and parts will be created clockwise.
+The size of the part is defined by the value part of
+the L<VDEF|rrdgraph_data/VDEF> function.  It should return
+a number between 0 and 100, being a percentage.
+Providing wrong input will produce undefined results.
+
+=include see_also

diff --git a/doc/rrdgraph_rpn.src b/doc/rrdgraph_rpn.src
new file mode 100644 (file)
index 0000000..3278f84
--- /dev/null
+++ b/doc/rrdgraph_rpn.src
@@ -0,0 +1,219 @@
+=include name
+
+=head1 SYNOPSYS
+
+I<E<lt>RPN expressionE<gt>> := 
+I<E<lt>vnameE<gt>>|I<E<lt>operatorE<gt>>|I<E<lt>valueE<gt>>
+[ , I<E<lt>RPN expressionE<gt>>]
+
+=head1 DESCRIPTION
+
+If you have ever used a traditional HP calculator you already know
+B<RPN>. The idea behind B<RPN> is that you have a stack and push
+your data onto this stack. Whenever you execute an operation, it
+takes as many elements from the stack as needed. Pushing is done
+implicit so whenever you specify a number or a variable, it gets
+pushed automatically.
+
+At the end of the calculation there should be one and exactly one
+value left on the stack.  This is the outcome of the function and
+this is what is put into the I<vname>.  For B<CDEF> instructions,
+the stack is processed for each data point on the graph. B<VDEF>
+instructions work on an entire data set in one run.
+
+Example: C<CDEF:mydatabits=mydata,8,*>
+
+This means:  push variable I<mydata>, push the number 8, execute
+the operator I<+>. The operator needs two elements and uses those
+to return one value.  This value is then stored in I<mydatabits>.
+As you may have guessed, this instruction means nothing more than
+I<mydatabits = mydata * 8>.  The real power of B<RPN> lies in the
+fact that it is always clear in which order to process the input.
+For expressions like C<a = b + 3 * 5> you need to multiply 3 with
+5 first before you add I<b> to get I<a>. However, with parentheses
+you could change this order: C<a = (b + 3) * 5>. In B<RPN>, you
+would do C<a = b, 3, +, 5, *> and need no parentheses.
+
+=head1 OPERATORS
+
+=over 4
+
+=item Boolean operators
+
+B<LT, LE, GT, GE, EQ, NE>
+
+I<Note: NE is not yet implemented>
+
+Pop two elements from the stack, compare them for the selected condition
+and return 1 for true or 0 for false. Comparing an I<unknown> or an
+I<infinite> value will always result in 0 (false).
+
+B<UN, ISINF>
+
+I<Note: ISINF is not yet implemented>
+
+Pop one element from the stack, compare this to I<unknown> respectively
+to I<positive or negative infinity>. Returns 1 for true or 0 for false.
+
+B<IF>
+
+Pops three elements from the stack.  If the last element is 0 (false),
+the first value is pushed back onto the stack, otherwise the second
+popped value is pushed back. This does, indeed, mean that any value
+other than 0 is considered true.
+I<Note: Should this change? It should IMHO as all the other functions
+would return unknown if A,B or C were unknown>
+
+Example: C<A,B,C,IF> should be read as C<if (A) then (B) else (C)>
+
+Z<>
+
+=item Comparing values
+
+B<MIN, MAX> 
+
+Pops two elements from the stack and returns the lesser or larger.
+The two numbers shouldn't be I<infinite> or I<unknown>, if they are
+that value is pushed back onto the stack as the result.
+
+B<LIMIT>
+
+Pops two elements from the stack and uses them to define a range.
+Then it pops another element and if it falls inside the range, it
+is pushed back. If not, an I<unknown> is pushed.
+
+The range defined includes the two boundaries (so: a number equal
+to one of the boundaries will be pushed back). If any of the three
+numbers involved is either I<unknown> or I<infinite> this function
+will always return an I<unknown>
+
+Example: C<CDEF:a=alpha,0,100,LIMIT> will return I<unknown> if
+alpha is lower than 0 or if it is higher than 100.
+
+Z<>
+
+=item Arithmetics
+
+B<+, -, *, /, %>
+
+Add, subtract, multiply, divide, modulo
+
+B<SIN, COS, LOG, EXP>
+
+Sine, cosine (input in radians), log, exp (natural logarithm)
+
+B<FLOOR, CEIL>
+
+Round down,up to the nearest integer
+
+Z<>
+
+=item Special values
+
+B<UNKN>
+
+Pushes an unknown value on the stack
+
+B<INF, NEGINF>
+
+Pushes a positive or negative infinite value on the stack. When
+such a value is graphed, it appears at the top or bottom of the
+graph, no matter what the actual value on the y-axis is.
+
+B<PREV>
+
+Pushes an I<unknown> value if this is the first value of a data
+set or otherwise the result of this B<CDEF> at the previous time
+step. This allows you to do calculations across the data.  This
+function cannot be used in B<VDEF> instructions.
+
+Z<>
+
+=item Time
+
+Time inside RRDtool is measured in seconds since the epoch. This
+epoch is defined to be S<C<Thu Jan  1 00:00:00 UTC 1970>>.
+
+Z<>
+
+=over 4
+
+=item NOW
+
+Pushes the current time on the stack.
+
+Z<>
+
+=item TIME
+
+Pushes the time the currently processed value was taken onto the stack.
+
+Z<>
+
+=item LTIME
+
+Takes the time as defined by B<TIME>, applies the time zone offset
+valid at that time including daylight saving time if your OS supports
+it, and pushes the result on the stack.  There is an elaborate example
+in the examples section on how to use this.
+
+=back
+
+For B<VDEF> operations, B<TIME> and B<LTIME> have a different meaning
+I<not yet implemented>.  As the B<VDEF> statement does not work per
+value but rather on a complete time series, there is no such thing as
+the currently processed value.  However, if you have used an operator
+that returned a time component and would like to have this available
+in the value component in stead (so you can use it as a number), you
+can use B<TIME> or B<LTIME> for that.
+
+Z<>
+
+=item Processing the stack directly
+
+B<DUP, POP, EXC>
+
+Duplicate the top element, remove the top element, exchange the two
+top elements.
+
+Z<>
+
+=item Selecting characteristics
+
+These operators work only on B<VDEF> statements.
+I<We can make most of them work at DEF and CDEF statements. If we do
+so, we have a moving (not rolling!) average, max,min etcetera>
+
+Z<>
+
+=over 4
+
+=item MAXIMUM, MINIMUM, AVERAGE
+
+Return the corresponding value
+
+Z<>
+
+=item LAST, FIRST
+
+Return the last,first value including its time 
+
+Z<>
+
+=item PERCENTILE
+
+Should follow a B<DEF> or B<CDEF> I<vname>. This I<vname> is popped,
+another number is popped which is a certain percentage (0..100). The
+data set is then sorted and the value returned is chosen such that
+I<percentage> percent of the values is lower or equal than the result.
+I<Unknown> values are considered lower than any finite number for this
+purpose so if this operator returns an I<unknown> you have quite a lot
+of them in your data...
+
+Example: C<VDEF:perc95=95,mydata,PERCENTILE>
+
+=back
+
+=back
+
+=include see_also

diff --git a/doc/see_also.inc b/doc/see_also.inc
new file mode 100644 (file)
index 0000000..eb2fa5b
--- /dev/null
+++ b/doc/see_also.inc
@@ -0,0 +1,14 @@
+=head1 SEE ALSO
+
+L<rrdgraph> gives an overview of how B<rrdtool graph> works.
+L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail,
+L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements,
+L<rrdgraph_graph> page describes all of the graph and print functions.
+
+Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
+
+=head1 AUTHOR
+
+Program by Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt>
+
+This manual page by Alex van den Bogaerdt E<lt>alex@ergens.op.het.netE<gt>

diff --git a/src/rrd_tune.c b/src/rrd_tune.c
index b45e5db2465c849937bd902515e88711d507f886..f38319ed67274109c874bee4aa4a46ef8f63f033 100644 (file)
--- a/src/rrd_tune.c
+++ b/src/rrd_tune.c
@@ -5,6 +5,11 @@
  *****************************************************************************
  * $Id$
  * $Log$
+ * Revision 1.3  2001/03/07 21:21:54  oetiker
+ * complete rewrite of rrdgraph documentation. This also includs info
+ * on upcomming/planned changes to the rrdgraph interface and functionality
+ * -- Alex van den Bogaerdt <alex@slot.hollandcasino.nl>
+ *
  * Revision 1.2  2001/03/04 13:01:55  oetiker
  * Aberrant Behavior Detection support. A brief overview added to rrdtool.pod.
  * Major updates to rrd_update.c, rrd_create.c. Minor update to other core files.
@@ -12,9 +17,6 @@
  * by old rrdtool versions. See http://cricket.sourceforge.net/aberrant/rrd_hw.htm
  * -- Jake Brutlag <jakeb@corp.webtv.net>
  *
- * Revision 1.1.1.1  2001/02/25 22:25:06  oetiker
- * checkin
- *
  *****************************************************************************/
 
 #include "rrd_tool.h"