X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=doc%2Frrdgraph_graph.src;h=3826f08a31d27afd0270cefa9caa73af47f62049;hb=1f8fb56f90e611d4b636c8cb32d0dfbae4afeeb2;hp=5b163d40c908277368e6cc9d307fa66373451938;hpb=e7de71c824fd824d345c8e7a99a815fe1525eeef;p=rrdtool.git

diff --git a/doc/rrdgraph_graph.src b/doc/rrdgraph_graph.src
index 5b163d4..3826f08 100644
--- a/doc/rrdgraph_graph.src
+++ b/doc/rrdgraph_graph.src
@@ -1,54 +1,44 @@
-=include name
+=head1 NAME  
 
-=head1 SYNOPSYS
+=cut
 
-=over 4
-
-=item B<to be depriciated commands>
-
-=over 4
-
-=item B<PRINT> : I<vname> : I<CF> : I<format>
-
-=item B<GPRINT> : I<vname> : I<CF> : I<format>
+WARNING: DO NOT EDIT THE POD FILES. THEY ARE AUTO-GENERATED
 
-=item B<HRULE> : I<value> # I<color> [ :I<legend> ]
+=pod
 
-=item B<STACK> : I<vname> # I<color> [ :I<legend> ]
+rrdgraph_graph - rrdtool graph command reference
 
-=back
-
-=item B<available commands>
+=head1 SYNOPSIS
 
-=over 8
+B<PRINT>B<:>I<vname>B<:>I<format>
 
-=item B<PRINT> : I<vname> : I<format>
+B<GPRINT>B<:>I<vname>B<:>I<format>
 
-=item B<GPRINT> : I<vname> : I<format>
+B<COMMENT>B<:>I<text>
 
-=item B<COMMENT> : I<text>
+B<VRULE>B<:>I<vname>B<#>I<color>[B<:>I<legend>]
 
-=item B<VRULE> : I<vname> # I<color> [ : I<legend> ]
+B<LINE>I<width>B<:>I<vname>B<#>I<color>[B<:>I<legend>][B<:>B<STACK>]
 
-=item B<LINE>{I<width>} : I<vname> # I<color> [ : I<legend> ] [ : STACK ]
+B<AREA>B<:>I<vname>B<#>I<color>[B<:>I<legend>][B<:>B<STACK>]
 
-=item B<AREA> C<:> I<vname> C<#> I<color> [ C<:> I<legend> ] [ C<:> C<STACK> ]
+B<TICK>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<fraction>[B<:>I<legend>]]
 
-=item B<PART> : I<vname> B<#> I<rrggbbaa> [ B<:> I<legend> ]
+B<SHIFT>B<:>I<vname>B<:>I<offset>
 
-=item B<TICK> : I<vname> B<#> I<rrggbbaa> [ : I<fraction> [ : I<legend> ] ]
+=cut
 
-=back
+B<PART>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<legend>]
 
-=item B<to be implemented commands>
+=pod
 
-=over 8
+B<PRINT>B<:>I<vname>B<:>I<CF>B<:>I<format> (deprecated)
 
-=item B<SHIFT> : I<vname> , I<offset>
+B<GPRINT>B<:>I<vname>B<:>I<CF>B<:>I<format> (deprecated)
 
-=back
+B<HRULE>B<:>I<value>B<#>I<color>[B<:>I<legend>] (deprecated)
 
-=back
+B<STACK>B<:>I<vname>B<#>I<color>[B<:>I<legend>] (deprecated)
 
 =head1 DESCRIPTION
 
@@ -60,12 +50,12 @@ Similarly no report is generated if you don't use print options.
 
 =over 4
 
-=item B<PRINT> : I<vname> : I<CF> : I<format>
+=item B<PRINT:>I<vname>B<:>I<CF><:>I<format>
 
-I<Depriciated. Use the new form of this command in new scripts.>
+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> : I<format>
+=item 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
@@ -85,15 +75,16 @@ B<%%> just prints a literal '%' character
 
 =item *
 
-B<%#.#le> (where # is an optional number) prints like 1.2346e+04
+B<%#.#le> prints like 1.2346e+04. Optional numbers # are field width and
+decimal precision
 
 =item *
 
-B<%#.#lf> prints like 12345.6789
+B<%#.#lf> prints like 12345.6789, with optional field width and precision
 
 =item *
 
-B<%s> place this after B<%le> or B<%lf>.  This will be replaced by the
+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)
 
@@ -145,8 +136,8 @@ 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
+B<%U, %W> week number of the current year with either the first Sunday or
+the first Monday determining the first week
 
 =item *
 
@@ -160,28 +151,24 @@ B<%Z> time zone
 
 =over 4
 
-=item B<GPRINT> : I<vname> : I<CF> : I<format>
+=item B<GPRINT>B<:>I<vname>B<:>I<CF>B<:>I<format>
 
-I<Depriciated. Use the new form of this command in new scripts.>
+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.
 
-=item B<GPRINT> : I<vname> : I<format>
+=item B<GPRINT>B<:>I<vname>B<:>I<format>
 
 This is the same as C<PRINT> but now it is printed inside the graph.
 
-=item B<COMMENT> : I<text>
+=item B<COMMENT>B<:>I<text>
 
 Text is printed literally in the legend section of the graph
 
-=item B<HRULE> : I<value> # I<color> [ :I<legend> ]
+=item B<HRULE>B<:>I<value>B<#>I<color> [ :I<legend> ]
 
-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. I<value> can be a variable from a B<VDEF>.
-It is an error to use I<vname>s from B<DEF> or B<CDEF> here.
+I<Deprecated. Use B<LINEx> in new scripts.>
 
-=item B<VRULE> : I<vname> # I<color> [ : I<legend> ]
+=item B<VRULE>B<:>I<vname>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
@@ -189,7 +176,8 @@ 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>} : I<vname> # I<color> [ : I<legend> ] [ : STACK ]
+=item B<LINE>I<width>B<:>I<{vname or number}>B<#>I<color>[B<:>I<legend>]
+[ C<: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
@@ -200,28 +188,31 @@ 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>
 
-=item B<AREA> C<:> I<vname> C<#> I<color> [ C<:> I<legend> ] [ C<:> C<STACK> ]
+=item B<AREA>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<legend>][B<:STACK>]
 
 See B<LINE>, however the area between the x-axis and the line will
 also be filled.
 
-=item B<STACK> : I<vname> # I<color> [ :I<legend> ]
+=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.
+
+=item B<SHIFT>B<:>I<vname>B<:>I<offset>
 
-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, an unknown value is not!
+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...
+As with the other graphing elements, you can specify a number or
+a variable here.
 
-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.
+=cut
 
-=item B<PART> : I<vname> B<#> I<rrggbbaa> [ B<:> I<legend> ]
+=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
@@ -234,31 +225,63 @@ 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.
 
-=item B<TICK> : I<vname> B<#> I<rrggbbaa> [ : I<fraction> [ : I<legend> ] ]
+=pod
 
-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.
+=item B<STACK>B<:>I<vname>B<#>I<color>[B<:>I<legend>]
+
+I<Deprecated.  Use the B<STACK> modifiers on the other commands.>
 
 =back
 
-B<THE NEXT COMMAND IS NOT YET IMPLEMENTED>
+B<Some notes on stacking>
 
-=over 4
+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.
 
-=item B<SHIFT> : I<vname> , I<offset>
+An B<invisible> LINEx or AREA B<is> present and can be stacked upon.  
 
-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.
+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
+not know where to end.
 
-=back
+If you want to make sure you will be displaying a certain variable,
+make sure never to stack upon the unknown value.  Use a CDEF instruction
+with B<IF> and B<UN> to do so.
+
+=head1 NOTES on legend arguments
+
+=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.
+
+=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,
+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.
+
+Normally there are two space characters inserted between every two items
+printed into the graph. The space following a string can be suppressed by
+putting a B<\g> at the end of the string. The B<\g> also ignores any space
+inside the string if it is at the very end of the string. This can be used
+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
+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!
 
 =include see_also