X-Git-Url: https://git.octo.it/?p=rrdtool.git;a=blobdiff_plain;f=doc%2Frrdgraph_data.pod;h=d5ceddbfb68ffa6ed1d658bd14f995818c74b610;hp=64c559aba27f36485883ea513484487a46cdc112;hb=dc4997373f9cc1c170bc378ff12fa2c3a23161e9;hpb=342b22c3e74a10d7049285c2cea7383676bcfc95

diff --git a/doc/rrdgraph_data.pod b/doc/rrdgraph_data.pod
index 64c559a..d5ceddb 100644
--- a/doc/rrdgraph_data.pod
+++ b/doc/rrdgraph_data.pod
@@ -22,6 +22,10 @@ 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 safe bet it to use lowercase or
+mixed case names for variables since operators will always be in uppercase.
+
 =head1 DEF
 
 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>>]
@@ -46,7 +50,7 @@ image with width 400 and time span 400*1800 seconds (use appropriate
 start and end times, such as C<--start end-8days8hours>).
 
 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
+B<DEF> itself will be used to reduce the data density. This behavior 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.
 
@@ -71,7 +75,7 @@ elements.
 
 Example: C<VDEF:avg=mydata,AVERAGE>
 
-Note that currently only agregation functions work in VDEF rpn expressions.
+Note that currently only aggregation functions work in VDEF rpn expressions.
 Patches to change this are welcome.
 
 =head1 CDEF
@@ -86,6 +90,34 @@ the script, just as if it were generated by a B<DEF> instruction.
 
 Example: C<CDEF:mydatabits=mydata,8,*>
 
+=head1 About CDEF versus VDEF
+
+At some point in processing, B<RRDtool> has gathered an array of rates
+ready to display.
+
+B<CDEF> works on such an array.  For example, I<CDEF:new=ds0,8,*>
+would multiply each of the array members by eight (probably
+transforming bytes into bits). The result is an array containing the
+new values.
+
+B<VDEF> also works on such an array but in a different way.  For
+example, I<VDEF:max=ds0,MAXIMUM> would scan each of the array members
+and store the maximum value.
+
+=head2 When do you use B<VDEF> versus B<CDEF>?  
+
+Use B<CDEF> to transform your data prior to graphing.  In the above
+example, we'd use a B<CDEF> to transform bytes to bits before
+graphing the bits.
+
+You use a B<VDEF> if you want I<max(1,5,3,2,4)> to return five which
+would be displayed in the graph's legend (to answer, what was the
+maximum value during the graph period).
+
+If you want to apply 'complex' operations to the result of a VDEF you have
+to use a CDEF again since VDEFs only look like RPN expressions, they aren't
+really.
+
 =head1 SEE ALSO
 
 L<rrdgraph> gives an overview of how B<rrdtool graph> works.
@@ -99,4 +131,5 @@ Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
 
 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>
+This manual page by Alex van den Bogaerdt E<lt>alex@vandenbogaerdt.nlE<gt>
+with corrections and/or additions by several people