missing documentation ... -- Alex van den Bogaerdt <alex@slot.hollandcasino.nl>

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

diff --git a/doc/rrdgraph_data.pod b/doc/rrdgraph_data.pod
new file mode 100644 (file)
index 0000000..afbe851
--- /dev/null
+++ b/doc/rrdgraph_data.pod
@@ -0,0 +1,97 @@
+=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.
+
+=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,*>
+
+=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/doc/rrdgraph_examples.pod b/doc/rrdgraph_examples.pod
new file mode 100644 (file)
index 0000000..2cbf49c
--- /dev/null
+++ b/doc/rrdgraph_examples.pod
@@ -0,0 +1,135 @@
+=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.
+
+=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 ]
+
+=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/doc/rrdgraph_graph.pod b/doc/rrdgraph_graph.pod
new file mode 100644 (file)
index 0000000..a94aa37
--- /dev/null
+++ b/doc/rrdgraph_graph.pod
@@ -0,0 +1,246 @@
+=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.
+
+=head1 SYNOPSYS
+
+I<(to be) 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<(soon) 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<Soon 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<Soon 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<Soon 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.
+
+=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/doc/rrdgraph_rpn.pod b/doc/rrdgraph_rpn.pod
new file mode 100644 (file)
index 0000000..16c5996
--- /dev/null
+++ b/doc/rrdgraph_rpn.pod
@@ -0,0 +1,244 @@
+=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.
+
+=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 PERCENT
+
+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.  I<Inf>inite numbers are lesser, or more, than the
+finite numbers and are always more than the I<Unknown> numbers.
+
+Example: C<VDEF:perc95=mydata,95,PERCENT>
+
+=back
+
+=back
+
+=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>