X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=doc%2Frrdgraph_data.1;h=8f70d0255dcbfcef25dfc6c7ec10b0cfc2c27f73;hb=6e58e96d05b3300ff189d192d490da081d5fdffa;hp=1731aa6225c21b6fa531d338f6cae061654fbbef;hpb=ecfac614b914cef110a81ac665997a9b186da500;p=pkg-rrdtool.git

diff --git a/doc/rrdgraph_data.1 b/doc/rrdgraph_data.1
index 1731aa6..8f70d02 100644
--- a/doc/rrdgraph_data.1
+++ b/doc/rrdgraph_data.1
@@ -1,15 +1,7 @@
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
-.de Sh \" Subsection heading
-.br
-.if t .Sp
-.ne 5
-.PP
-\fB\\$1\fR
-.PP
-..
 .de Sp \" Vertical space (when we can't use .PP)
 .if t .sp .5v
 .if n .sp
@@ -48,22 +40,25 @@
 .    ds R" ''
 'br\}
 .\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
 .\" If the F register is turned on, we'll generate index entries on stderr for
-.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
 .\" entries marked with X<> in POD.  Of course, you'll have to process the
 .\" output yourself in some meaningful fashion.
-.if \nF \{\
+.ie \nF \{\
 .    de IX
 .    tm Index:\\$1\t\\n%\t"\\$2"
 ..
 .    nr % 0
 .    rr F
 .\}
-.\"
-.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.hy 0
-.if n .na
+.el \{\
+.    de IX
+..
+.\}
 .\"
 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
@@ -129,12 +124,16 @@
 .\" ========================================================================
 .\"
 .IX Title "RRDGRAPH_DATA 1"
-.TH RRDGRAPH_DATA 1 "2007-11-20" "1.2.26" "rrdtool"
+.TH RRDGRAPH_DATA 1 "2013-05-23" "1.4.8" "rrdtool"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
 .SH "NAME"
 rrdgraph_data \- preparing data for graphing in rrdtool graph
 .SH "SYNOPSIS"
 .IX Header "SYNOPSIS"
-\&\fB\s-1DEF:\s0\fR\fI<vname>\fR=\fI<rrdfile>\fR:\fI<ds-name>\fR:\fI<\s-1CF\s0>\fR[:step=\fI<step>\fR][:start=\fI<time>\fR][:end=\fI<time>\fR][:reduce=\fI<\f(BI\s-1CF\s0\fI>\fR]
+\&\fB\s-1DEF:\s0\fR\fI<vname>\fR=\fI<rrdfile>\fR:\fI<ds\-name>\fR:\fI<\s-1CF\s0>\fR[:step=\fI<step>\fR][:start=\fI<time>\fR][:end=\fI<time>\fR][:reduce=\fI<\f(BI\s-1CF\s0\fI>\fR]
 .PP
 \&\fB\s-1VDEF\s0\fR:\fIvname\fR=\fI\s-1RPN\s0 expression\fR
 .PP
@@ -152,11 +151,11 @@ Variable names (\fIvname\fR) must be made up strings of the following characters
 \&\f(CW\*(C`A\-Z, a\-z, 0\-9, \-,_\*(C'\fR and a maximum length of 255 characters.
 .PP
 When picking variable names, make sure you do not choose a name that is
-already taken by an \s-1RPN\s0 operator. A save bet it to use lowercase or
-mixedcase names for variables since operators will always be in uppercase.
+already taken by an \s-1RPN\s0 operator. A safe bet it to use lowercase or
+mixed case names for variables since operators will always be in uppercase.
 .SH "DEF"
 .IX Header "DEF"
-\&\fB\s-1DEF:\s0\fR\fI<vname>\fR=\fI<rrdfile>\fR:\fI<ds-name>\fR:\fI<\s-1CF\s0>\fR[:step=\fI<step>\fR][:start=\fI<time>\fR][:end=\fI<time>\fR][:reduce=\fI<\f(BI\s-1CF\s0\fI>\fR]
+\&\fB\s-1DEF:\s0\fR\fI<vname>\fR=\fI<rrdfile>\fR:\fI<ds\-name>\fR:\fI<\s-1CF\s0>\fR[:step=\fI<step>\fR][:start=\fI<time>\fR][:end=\fI<time>\fR][:reduce=\fI<\f(BI\s-1CF\s0\fI>\fR]
 .PP
 This command fetches data from an \fB\s-1RRD\s0\fR file.  The virtual name
 \&\fIvname\fR can then be used throughout the rest of the script. By
@@ -178,8 +177,8 @@ image with width 400 and time span 400*1800 seconds (use appropriate
 start and end times, such as \f(CW\*(C`\-\-start end\-8days8hours\*(C'\fR).
 .PP
 If consolidation needs to be done, the \fB\s-1CF\s0\fR of the \fB\s-1RRA\s0\fR specified in the
-\&\fB\s-1DEF\s0\fR itself will be used to reduce the data density. This behaviour can
-be changed using \f(CW\*(C`:reduce=\f(CI<\f(CB\s-1CF\s0\f(CI>\f(CW\*(C'\fR.  This optional parameter
+\&\fB\s-1DEF\s0\fR itself will be used to reduce the data density. This behavior can
+be changed using \f(CW\*(C`:reduce=\f(CI<\f(CBCF\f(CI>\f(CW\*(C'\fR.  This optional parameter
 specifies the \fB\s-1CF\s0\fR to use during the data reduction phase.
 .PP
 Example:
@@ -204,7 +203,7 @@ elements.
 .PP
 Example: \f(CW\*(C`VDEF:avg=mydata,AVERAGE\*(C'\fR
 .PP
-Note that currently only agregation functions work in \s-1VDEF\s0 rpn expressions.
+Note that currently only aggregation functions work in \s-1VDEF\s0 rpn expressions.
 Patches to change this are welcome.
 .SH "CDEF"
 .IX Header "CDEF"
@@ -217,6 +216,32 @@ data point. The resulting \fIvname\fR can then be used further on in
 the script, just as if it were generated by a \fB\s-1DEF\s0\fR instruction.
 .PP
 Example: \f(CW\*(C`CDEF:mydatabits=mydata,8,*\*(C'\fR
+.SH "About CDEF versus VDEF"
+.IX Header "About CDEF versus VDEF"
+At some point in processing, \fBRRDtool\fR has gathered an array of rates
+ready to display.
+.PP
+\&\fB\s-1CDEF\s0\fR works on such an array.  For example, \fICDEF:new=ds0,8,*\fR
+would multiply each of the array members by eight (probably
+transforming bytes into bits). The result is an array containing the
+new values.
+.PP
+\&\fB\s-1VDEF\s0\fR also works on such an array but in a different way.  For
+example, \fIVDEF:max=ds0,MAXIMUM\fR would scan each of the array members
+and store the maximum value.
+.SS "When do you use \fB\s-1VDEF\s0\fP versus \fB\s-1CDEF\s0\fP?"
+.IX Subsection "When do you use VDEF versus CDEF?"
+Use \fB\s-1CDEF\s0\fR to transform your data prior to graphing.  In the above
+example, we'd use a \fB\s-1CDEF\s0\fR to transform bytes to bits before
+graphing the bits.
+.PP
+You use a \fB\s-1VDEF\s0\fR if you want \fImax(1,5,3,2,4)\fR to return five which
+would be displayed in the graph's legend (to answer, what was the
+maximum value during the graph period).
+.PP
+If you want to apply 'complex' operations to the result of a \s-1VDEF\s0 you have
+to use a \s-1CDEF\s0 again since VDEFs only look like \s-1RPN\s0 expressions, they aren't
+really.
 .SH "SEE ALSO"
 .IX Header "SEE ALSO"
 rrdgraph gives an overview of how \fBrrdtool graph\fR works.
@@ -229,4 +254,5 @@ Make sure to read rrdgraph_examples for tips&tricks.
 .IX Header "AUTHOR"
 Program by Tobias Oetiker <tobi@oetiker.ch>
 .PP
-This manual page by Alex van den Bogaerdt <alex@ergens.op.het.net>
+This manual page by Alex van den Bogaerdt <alex@vandenbogaerdt.nl>
+with corrections and/or additions by several people