diff --git a/doc/rrdgraph.pod b/doc/rrdgraph.pod
index 89cacd6bcbb9700639b1de705d7a706f6b76a7b3..71a1e1dde1236d1512d7a7533aa42e69c9d50f08 100644 (file)
--- a/doc/rrdgraph.pod
+++ b/doc/rrdgraph.pod
=head1 NAME
-rrdgraph - Round Robin Database tool grapher functions
+rrdgraph - Round Robin Database tool graphing functions
=head1 SYNOPSIS
it is best to collect them now using the
B<L<variable definition|rrdgraph_data/VDEF>> statement.
Currently this makes no difference, but in a future version
-of rrdtool you may want to collect these values before consolidation.
+of RRDtool you may want to collect these values before consolidation.
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
+there is exactly one data point per pixel in the graph. If you do
not take care yourself, B<RRDtool> will expand the range slightly
if necessary. Note, in that case the first and/or last pixel may very
well become unknown!
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
-
+Use B<graphv> instead of B<graph> to get detailed information about the
+graph geometry and data once it is drawn. See the bottom of the document for
+more information.
-=head2 B<graphv>
+=head1 OPTIONS
-This alternate version of B<graph> takes the same arguments and performs the
-same function. The I<v> stands for I<verbose>, which describes the output
-returned. B<graphv> will return a lot of information about the graph using
-the same format as rrdtool info (key = value). See the bottom of the document for more information.
=head2 I<filename>
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.
+resolution. With the B<step> option you can alter this behavior.
If you want B<rrdtool graph> to get data at a one-hour resolution
from the B<RRD>, set B<step> to 3'600. Note: a step smaller than
one pixel will silently be ignored.
A horizontal string at the top of the graph and/or a vertically
placed string at the left hand side of the graph.
-=item Right Axis
-
-[B<--right-axis> I<scale>B<:>I<shift>]
-[B<--right-axis-label> I<label>]
-
-A second axis will be drawn to the right of the graph. It is tied to the
-left axis via the scale and shift parameters. You can also define a label
-for the right axis.
-
-[B<--right-axis-format> I<format-string>]
-
-By default the format of the axis lables gets determined automatically. If
-you want todo this your self, use this option with the same %lf arguments
-you know from the PRING and GPRINT commands.
=head2 Size
[B<-r>|B<--rigid>]
By default the graph will be autoscaling so that it will adjust the
-y-axis to the range of the data. You can change this behaviour by
+y-axis to the range of the data. You can change this behavior by
explicitly setting the limits. The displayed y-axis will then range 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
[B<-N>|B<--no-gridfit>]
-In order to avoid anti-aliasing blurring effects rrdtool snaps
+In order to avoid anti-aliasing blurring effects RRDtool snaps
points to device resolution pixels, this results in a crisper
appearance. If this is not to your liking, you can use this switch
-to turn this behaviour off.
-
-Gridfitting is turned off for PDF, EPS, SVG output by default.
+to turn this behavior off.
-=head2 Grid
+Grid-fitting is turned off for PDF, EPS, SVG output by default.
-=over
-
-=item X-Axis
+=head2 X-Axis
[B<-x>|B<--x-grid> I<GTM>B<:>I<GST>B<:>I<MTM>B<:>I<MST>B<:>I<LTM>B<:>I<LST>B<:>I<LPR>B<:>I<LFM>]
[B<-x>|B<--x-grid> B<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
+very special needs it is probably best to rely on the auto configuration
to get this right. You can specify the string C<none> to suppress the grid
and labels altogether.
each day. The labels are placed exactly between two major grid lines
as they specify the complete day and not just midnight.
-=item Y-Axis
+[B<--week-fmt> I<strftime format string>]
+
+By default rrdtool uses "Week %V" to render the week number. With this option
+you can define your own format, without completely overriding the xaxis format.
+
+=head2 Y-Axis
[B<-y>|B<--y-grid> I<grid step>B<:>I<label factor>]
of 0 to prevent any scaling of the y-axis values.
This option is very effective at confusing the heck out of the default
-rrdtool autoscaler and grid painter. If rrdtool detects that it is not
+RRDtool autoscaling function and grid painter. If RRDtool detects that it is not
successful in labeling the graph under the given circumstances, it will switch
to the more robust B<--alt-y-grid> mode.
[B<-L>|B<--units-length> I<value>]
-How many digits should rrdtool assume the y-axis labels to be? You
+How many digits should RRDtool assume the y-axis labels to be? You
may have to use this option to make enough space once you start
fiddling with the y-axis labeling.
the appropriate units (k, M, etc.) instead of using exponential notation.
Note that for linear graphs, SI notation is used by default.
-=back
+=head2 Right Y Axis
+
+[B<--right-axis> I<scale>B<:>I<shift>]
+[B<--right-axis-label> I<label>]
+
+A second axis will be drawn to the right of the graph. It is tied to the
+left axis via the scale and shift parameters. You can also define a label
+for the right axis.
+
+[B<--right-axis-format> I<format-string>]
+
+By default the format of the axis labels gets determined automatically. If
+you want to do this your self, use this option with the same %lf arguments
+you know from the PRINT and GPRINT commands.
+
+=head2 Legend
+
+[B<-g>|B<--no-legend>]
+
+Suppress generation of the legend; only render the graph.
+
+[B<-F>|B<--force-rules-legend>]
+
+Force the generation of HRULE and VRULE legends even if those HRULE or
+VRULE will not be drawn because out of graph boundaries (mimics
+behavior of pre 1.0.42 versions).
+
+[B<--legend-position>=(north|south|west|east)]
+
+Place the legend at the given side of the graph. The default is south.
+In west or east position it is necessary to add line breaks manually.
+
+[B<--legend-direction>=(topdown|bottomup)]
+
+Place the legend items in the given vertical order. The default is topdown.
+Using bottomup the legend items appear in the same vertical order as a
+stack of lines or areas.
=head2 Miscellaneous
[B<-z>|B<--lazy>]
Only generate the graph if the current graph is out of date or not existent.
-Note, that only the image size will be returned, if you run with lazy even
-when using graphv and even when using PRINT.
-
+Note, that all the calculations will happen regardless so that the output of
+PRINT and graphv will be complete regardless. Note that the behavior of
+lazy in this regard has seen several changes over time. The only thing you
+can really rely on before RRDtool 1.3.7 is that lazy will not generate the
+graph when it is already there and up to date, and also that it will output
+the size of the graph.
[B<--daemon> I<address>]
A green arrow is made by: C<--color ARROW#00FF00>
-[B<--zoom> I<factor>]
+[B<--grid-dash> I<on>B<:>I<off>]
+
+by default the grid is drawn in a 1 on, 1 off pattern. With this option you can set this yourself
+
+ --grid-dash 1:3 for a dot grid
+
+ --grid-dash 1:0 for uninterrupted grid lines
+
+[B<--border> I<width>]]
+
+Width in pixels for the 3d border drawn around the image. Default 2, 0
+disables the border. See C<SHADEA> and C<SHADEB> above for setting the border
+color.
+
+[B<--dynamic-labels>]
+
+Pick the shape of the color marker next to the label according to the element drawn on the graph.
+
+[B<-m>|B<--zoom> I<factor>]
Zoom the graphics by the given amount. The factor must be E<gt> 0
Use Times for the title: C<--font TITLE:13:Times>
+Note that you need to quote the argument to B<--font> if the font-name
+contains whitespace:
+--font "TITLE:13:Some Font"
+
If you do not give a font string you can modify just the size of the default font:
C<--font TITLE:13:>.
There are 3 font render modes:
-B<normal>: Full Hinting and Antialiasing (default)
+B<normal>: Full Hinting and Anti-aliasing (default)
-B<light>: Slight Hinting and Antialiasing
+B<light>: Slight Hinting and Anti-aliasing
-B<mono>: Full Hinting and NO Antialiasing
+B<mono>: Full Hinting and NO Anti-aliasing
[B<-B>|B<--font-smoothing-threshold> I<size>]
[B<-P>|B<--pango-markup>]
-All text in rrdtool is rendered using Pango. With the B<--pango-markup> option, all
+All text in RRDtool is rendered using Pango. With the B<--pango-markup> option, all
text will be processed by pango markup. This allows to embed some simple html
like markup tags using
@@ -398,9 +443,9 @@ More details on L<http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat
There are 2 render modes:
-B<normal>: Graphs are fully Antialiased (default)
+B<normal>: Graphs are fully Anti-aliased (default)
-B<mono>: No Antialiasing
+B<mono>: No Anti-aliasing
[B<-E>|B<--slope-mode>]
If images are interlaced they become visible on browsers more quickly.
-[B<-g>|B<--no-legend>]
-
-Suppress generation of the legend; only render the graph.
-
-[B<-F>|B<--force-rules-legend>]
-
-Force the generation of HRULE and VRULE legends even if those HRULE or
-VRULE will not be drawn because out of graph boundaries (mimics
-behaviour of pre 1.0.42 versions).
-
[B<-T>|B<--tabwidth> I<value>]
By default the tab-width is 40 pixels, use this option to change it.
[B<-W>|B<--watermark> I<string>]
-Adds the given string as a watermark, horizontally centred, at the bottom
+Adds the given string as a watermark, horizontally centered, at the bottom
of the graph.
=head2 Data and variables
B<VDEF:>I<vname>B<=>I<RPN expression>
-You need at least one B<DEF> statement to generate anything. The
-other statements are useful but optional.
+You need at least one B<DEF> and one B<LINE>, B<AREA>, B<GPRINT>, B<PRINT>
+statement to generate anything useful.
+
See L<rrdgraph_data> and L<rrdgraph_rpn> for the exact format.
NOTE: B<Graph and print elements>
=head2 graphv
-Calling rrdtool with the graphv option will return information in the
-rrdtool info format. On the command line this means that all output will be
+Calling RRDtool with the graphv option will return information in the
+RRDtool info format. On the command line this means that all output will be
in key=value format. When used from the Perl and Ruby bindings a hash
pointer will be returned from the call.
graph_top = 22
graph_width = 400
graph_height = 100
+ graph_start = 1232908800
+ graph_end = 1232914200
image_width = 481
image_height = 154
value_min = 0.0000000000e+00
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