X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=doc%2Frrdgraph_data.pod;h=6c8b28a159b2732682610af1e3d680dcdb822fae;hb=a6d79528b4812e8eb3927dba3cdd42e6ca51b287;hp=afbe851c3356965e53713e026115cd8d4acf7388;hpb=4b4a568a4322288a7ec2e4b63e4596f76d65b76f;p=rrdtool.git

diff --git a/doc/rrdgraph_data.pod b/doc/rrdgraph_data.pod
index afbe851..6c8b28a 100644
--- a/doc/rrdgraph_data.pod
+++ b/doc/rrdgraph_data.pod
@@ -1,19 +1,10 @@
 =head1 NAME
 
-rrdtool graph - Round Robin Database tool grapher functions
+rrdgraph_data - preparing data for graphing in rrdtool graph
 
-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 SYNOPSIS
 
-=head1 SYNOPSYS
-
-B<DEF>:I<vname>=I<RRD file>:I<ds name>:I<CF>[:[I<time range>][:I<step size>]]
+B<DEF:>I<E<lt>vnameE<gt>>=I<E<lt>rrdfileE<gt>>:I<E<lt>ds-nameE<gt>>:I<E<lt>CFE<gt>>[:step=I<E<lt>stepE<gt>>][:start=I<E<lt>timeE<gt>>][:end=I<E<lt>timeE<gt>>][:reduce=I<E<lt>B<CF>E<gt>>]
 
 B<VDEF>:I<vname>=I<RPN expression>
 
@@ -21,28 +12,36 @@ 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.
+These three instructions extract data values out of the B<RRD> files,
+optionally altering them (think, for example, of a bytes to bits
+conversion). If so desired, you can also define variables containing
+useful information such as maximum, minimum etcetera. Two of the
+instructions use a language called B<RPN> which is described in its
+own manual page.
+
+Variable names (I<vname>) must be made up strings of the following characters
+C<A-Z, a-z, 0-9, -,_> and a maximum length of 255 characters.
+
+When picking variable names, make sure you do not choose a name that is
+already taken by an RPN operator. A save bet it to use lowercase or
+mixedcase names for variables since operators will always be in uppercase.
 
 =head1 DEF
 
-B<DEF>:I<vname>=I<RRD file>:I<ds name>:I<CF>[:[I<time range>][:I<step size>]]
+B<DEF:>I<E<lt>vnameE<gt>>=I<E<lt>rrdfileE<gt>>:I<E<lt>ds-nameE<gt>>:I<E<lt>CFE<gt>>[:step=I<E<lt>stepE<gt>>][:start=I<E<lt>timeE<gt>>][:end=I<E<lt>timeE<gt>>][:reduce=I<E<lt>B<CF>E<gt>>]
 
 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
+be overridden with the L<--step|rrdgraph/item_Time> option.
+The resolution can again be overridden by specifying the B<step size>.
+The time span of this data is the same as for the graph by default,
+you can override this by specifying B<start and end>.  Remember to
+escape colons in the time specification!
+
+If the resolution of the data is higher than the resolution of the
+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
@@ -50,9 +49,17 @@ 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>
+If consolidation needs to be done, the B<CF> of the B<RRA> specified in the
+B<DEF> itself will be used to reduce the data density. This behaviour can
+be changed using C<:reduce=I<E<lt>B<CF>E<gt>>>.  This optional parameter
+specifies the B<CF> to use during the data reduction phase.
 
-Example: C<DEF:januari=router.rrd:ds0:AVERAGE:start=20010101 end=20010201>
+Example:
+
+        DEF:ds0=router.rrd:ds0:AVERAGE
+        DEF:ds0weekly=router.rrd:ds0:AVERAGE:step=7200
+        DEF:ds0weekly=router.rrd:ds0:AVERAGE:start=end-1h
+        DEF:ds0weekly=router.rrd:ds0:AVERAGE:start=11\:00:end=start+1h
 
 =head1 VDEF
 
@@ -64,11 +71,13 @@ 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) ]
+elements.
 
 Example: C<VDEF:avg=mydata,AVERAGE>
 
+Note that currently only agregation functions work in VDEF rpn expressions.
+Patches to change this are welcome.
+
 =head1 CDEF
 
 B<CDEF>:I<vname>=I<RPN expression>
@@ -84,14 +93,14 @@ Example: C<CDEF:mydatabits=mydata,8,*>
 =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_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>
+Program by Tobias Oetiker E<lt>tobi@oetiker.chE<gt>
 
 This manual page by Alex van den Bogaerdt E<lt>alex@ergens.op.het.netE<gt>