X-Git-Url: https://git.verplant.org/?a=blobdiff_plain;f=doc%2Frrdgraph_graph.pod;h=754e703e3a19ddd58bf6e693411e9f925c546a4a;hb=ac2cd917b8b2c9a76824285c3d01050665d6b5c7;hp=bf92d454ac84c58000594b36dce362c478066e89;hpb=1ed31d581dfed23377a61d4df88bb9c2b9b2c94b;p=rrdtool.git

diff --git a/doc/rrdgraph_graph.pod b/doc/rrdgraph_graph.pod
index bf92d45..754e703 100644
--- a/doc/rrdgraph_graph.pod
+++ b/doc/rrdgraph_graph.pod
@@ -1,4 +1,6 @@
-=head1 NAME  
+=pod
+
+=head1 NAME
 
 rrdgraph_graph - rrdtool graph command reference
 
@@ -10,11 +12,11 @@ B<GPRINT>B<:>I<vname>B<:>I<format>
 
 B<COMMENT>B<:>I<text>
 
-B<VRULE>B<:>I<vname>B<#>I<color>[B<:>I<legend>]
+B<VRULE>B<:>I<time>B<#>I<color>[B<:>I<legend>]
 
-B<LINE>I<width>B<:>I<vname>B<#>I<color>[B<:>I<legend>][B<:>B<STACK>]
+B<LINE>[I<width>]B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]]
 
-B<AREA>B<:>I<vname>B<#>I<color>[B<:>I<legend>][B<:>B<STACK>]
+B<AREA>B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]]
 
 B<TICK>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<fraction>[B<:>I<legend>]]
 
@@ -22,7 +24,9 @@ B<SHIFT>B<:>I<vname>B<:>I<offset>
 
 =cut
 
-B<PART>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<legend>]
+#
+#B<PART>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<legend>]
+#
 
 =pod
 
@@ -38,16 +42,12 @@ B<STACK>B<:>I<vname>B<#>I<color>[B<:>I<legend>] (deprecated)
 
 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.
+Similarly, no report is generated if you don't use print options.
 
 =head1 PRINT
 
 =over 4
 
-=item B<PRINT:>I<vname>B<:>I<CF><:>I<format>
-
-I<Deprecated. 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.
 
 =item B<PRINT:>I<vname>B<:>I<format>
 
@@ -69,24 +69,25 @@ B<%%> just prints a literal '%' character
 
 =item *
 
-B<%#.#le> prints like 1.2346e+04. Optional numbers # are field width and
-decimal precision
+B<%#.#le> prints numbers like 1.2346e+04. The optional integers # denote field
+width and decimal precision.
 
 =item *
 
-B<%#.#lf> prints like 12345.6789, with optional field width and precision
+B<%#.#lf> prints numbers like 12345.6789, with optional field width
+and precision.
 
 =item *
 
 B<%s> place this after B<%le>, B<%lf> or B<%lg>. This will be replaced by the
 appropriate SI magnitude unit and the value will be scaled
-accordingly (123456 -> 123.456 k)
+accordingly (123456 -> 123.456 k).
 
 =item *
 
-B<%S> is similar to B<%s>. It does however use a previously defined
+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
+one (just like B<%s>) unless the value is zero, in which case 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.
 
@@ -102,122 +103,138 @@ B<%%> just prints a literal '%' character
 
 =item *
 
-B<%a, %A> prints abbreviated, full weekday name
+B<%a, %A> print the abbreviated or full name of the day of the week.
 
 =item *
 
-B<%b, %B> prints abbreviated, full month name
+B<%b, %B> print the abbreviated or full name of the month.
 
 =item *
 
-B<%d, %m, %y, %H, %M, %S> day,month,year,hour,minute,second all in two-digit format
+B<%d, %m, %y, %H, %M, %S> print day, month, year, hour, minute, and
+second in two-digit format.
 
 =item *
 
-B<%Y> year in 4-digit format
+B<%Y> prints the year in 4-digit format.
 
 =item *
 
-B<%I, %p>  hour (01..12), 'am' or 'pm'
+B<%I, %p> print the hour (01..12), 'am' or 'pm'.
 
 =item *
 
-B<%j, %w> day of the week (0..6), day of the year (1..366)
+B<%j, %w> print day of the week (0..6), day of the year (1..366)
 
 =item *
 
-B<%c, %x, %X> date+time, date, time
+B<%c, %x, %X> print date+time, date only, time only.
 
 =item *
 
-B<%U, %W> week number of the current year with either the first Sunday or
-the first Monday determining the first week
+B<%U, %W> number of the week of the current year, with either the
+first Sunday (%U) or the first Monday (%W) determining the first week.
 
 =item *
 
-B<%Z> time zone
+B<%Z> prints the time zone.
 
 =back
 
+=item B<PRINT:>I<vname>B<:>I<CF><:>I<format>
+
+I<Deprecated. 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.
+
 =back
 
 =head1 GRAPH
 
 =over 4
 
-=item B<GPRINT>B<:>I<vname>B<:>I<CF>B<:>I<format>
+=item B<GPRINT>B<:>I<vname>B<:>I<format>
 
-I<Deprecated. Use the new form of this command in new scripts.>
-This is the same as C<PRINT> but now it is printed inside the graph.
+This is the same as C<PRINT>, but printed inside the graph.
 
-=item B<GPRINT>B<:>I<vname>B<:>I<format>
+=item B<GPRINT>B<:>I<vname>B<:>I<CF>B<:>I<format>
 
-This is the same as C<PRINT> but now it is printed inside the graph.
+I<Deprecated. Use the new form of this command in new scripts.>
+This is the same as C<PRINT>, but printed inside the graph.
 
 =item B<COMMENT>B<:>I<text>
 
-Text is printed literally in the legend section of the graph
+Text is printed literally in the legend section of the graph. Note that in
+RRDtool 1.2 you have to escape colons in COMMENT text in the same way you
+have to escape them in B<*PRINT> commands by writing B<'\:'>.
 
 =item B<HRULE>B<:>I<value>B<#>I<color> [ :I<legend> ]
 
-I<Deprecated. Use B<LINEx> in new scripts.>
+I<Deprecated. Use B<LINE> in new scripts.>
 
-=item B<VRULE>B<:>I<vname>B<#>I<color> [B<:>I<legend> ]
+=item B<VRULE>B<:>I<time>B<#>I<color> [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
+hexadecimal numbers specifying the rgb 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.
 
-=item B<LINE>I<width>B<:>I<{vname or number}>B<#>I<color>[B<:>I<legend>]
-[ C<:STACK> ]
+=item B<LINE>[I<width>]B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]]
+
+Draw a line of the specified width onto the graph. I<width> can be a
+floating point number. If the color is not specified, the drawing is done
+'invisibly'. 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<value> 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<LINE> or an
+B<AREA>.
 
-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>
+When you do not specify a color, you cannot specify a legend.  Should
+you want to use STACK, use the "LINEx:<value>::STACK" form.
 
-=item B<AREA>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<legend>][B<:STACK>]
+=item B<AREA>B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]]
 
 See B<LINE>, however the area between the x-axis and the line will
-also be filled.
+be filled.
 
 =item B<TICK>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<fraction>[B<:>I<legend>]]
 
 Plot a tick mark (a vertical line) for each value of I<vname> that is
-non-zero and not *UNKNOWN*. The I<fraction> argument specifies the
-length of the tick mark as a fraction of the y-axis; the default value
-is 0.1 (10% of the axis). Note that the color specification is not
-optional.
+non-zero and not *UNKNOWN*. The I<fraction> argument specifies the length of
+the tick mark as a fraction of the y-axis; the default value is 0.1 (10% of
+the axis). Note that the color specification is not optional. The TICK marks normaly
+start at the lower edge of the graphing area. If the fraction is negative they start
+at the upper border of the graphing area.
 
 =item B<SHIFT>B<:>I<vname>B<:>I<offset>
 
 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...
+offset of S<( 7*24*60*60 = ) 604'800 seconds> to "look back" one
+week. Make sure to tell the viewer of your graph you did this ...
 As with the other graphing elements, you can specify a number or
 a variable here.
 
 =cut
 
-=item B<PART>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<legend>]
-
-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
-The size of the canvas is determined by the lesser of
-L<width and height|rrdgraph/item_Size>.
-
-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.
+# This section describes the curruently defunct
+# PieChart code.
+#
+# =item B<PART>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<legend>]
+#
+# 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.
+# The size of the canvas is determined by the lesser of
+# L<width and height|rrdgraph/item_Size>.
+#
+# 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.
+#
+#
 
 =pod
 
@@ -233,7 +250,7 @@ When stacking, an element is not placed above the X-axis but rather
 on top of the previous element.  There must be something to stack
 upon.
 
-An B<invisible> LINEx or AREA B<is> present and can be stacked upon.  
+You can use an B<invisible> LINE or AREA to stacked upon.
 
 An B<unknown> value makes the entire stack unknown from that moment on.
 You don't know where to begin (the unknown value) and therefore do
@@ -247,21 +264,22 @@ with B<IF> and B<UN> to do so.
 
 =head2 Escaping the colon
 
-In a ':' in a I<legend> argument will mark the end of the legend. To
-enter a ':' into a legend, the colon must be escaped with a backslash '\:'.
-Beware, that many environments look for backslashes themselves, so it may
-be necessary to write two backslashes so that one is passed onto rrd_graph.
+A colon ':' in a I<legend> argument will mark the end of the
+legend. To enter a ':' as part of a legend, the colon must be escaped
+with a backslash '\:'.  Beware that many environments process
+backslashes themselves, so it may be necessary to write two
+backslashes in order to one being passed onto rrd_graph.
 
 =head2 String Formatting
 
-The text printed below the actual graph can be formated by appending special
-escaped characters at the end of a text. When ever such a character occurs,
+The text printed below the actual graph can be formatted by appending special
+escape characters at the end of a text. When ever such a character occurs,
 all pending text is pushed onto the graph according to the character
 specified.
 
 Valid markers are: B<\j> for justified, B<\l> for left aligned, B<\r> for
-right aligned and B<\c> for centered. In the next section there is an
-example showing how to use centered formating.
+right aligned, and B<\c> for centered. In the next section there is an
+example showing how to use centered formatting.
 
 Normally there are two space characters inserted between every two items
 printed into the graph. The space following a string can be suppressed by
@@ -271,18 +289,19 @@ in connection with B<%s> to suppress empty unit strings.
 
  GPRINT:a:MAX:%lf%s\g
 
-A special case is COMMENT:B<\s> this inserts some additional vertical space
+A special case is COMMENT:B<\s> which inserts some additional vertical space
 before placing the next row of legends.
 
-If you are using the proportional font in your graph, you can use tab characters
-or the sequence B<\t> to lin-up legend elements. Note that the tabs inserted are
-relative to the start of the current legend element!
+If you are using the proportional font in your graph, you can use tab
+characters or the sequence B<\t> to line-up legend elements. Note that
+the tabs inserted are relative to the start of the current legend
+element!
 
 =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.