diff --git a/doc/rrdcgi.pod b/doc/rrdcgi.pod
index cfa79a511b092015d9ebdf672ea3f476844017aa..e34d4c00e29d5b43c646cf6072dd00205db71a57 100644 (file)
--- a/doc/rrdcgi.pod
+++ b/doc/rrdcgi.pod
=head1 NAME
-rrdcgi - create web pages containing RRD graphs based on templates
-
-=for html <div align="right"><a href="rrdcgi.pdf">PDF</a> version.</div>
+rrdcgi - Create web pages containing RRD graphs based on templates
=head1 SYNOPSIS
-#!/path/to/B<rrdcgi>
-S<[B<--filter>]>
+C<#!/path/to/>B<rrdcgi> S<[B<--filter>]>
=head1 DESCRIPTION
In the end it will printout a web page including the necessary CGI headers.
B<rrdcgi> parses the contents of the template in 3 steps. In each step it looks
-only for a subset of tags. This allows to nest tags.
+only for a subset of tags. This allows nesting of tags.
-The argument parser uses the same semantics as you are used from your c shell.
+The argument parser uses the same semantics as you are used from your C-shell.
=over 8
-
=item B<--filter>
-Assume that rrdcgi is being run as a filter and not as a cgi.
+Assume that rrdcgi is run as a filter and not as a cgi.
=back
-=head2 Pass 1
+=head2 Keywords
=over 8
Inserts the CGI variable of the given name but quotes it, ready for
use as an argument in another RRD:: tag. So even when there are spaces in the
-value of the CGI variable it will still be considered as one argument.
+value of the CGI variable it will still be considered to be one argument.
=item RRD::CV::PATH I<name>
Inserts the CGI variable of the given name, quotes it and makes sure
-the it starts neither with a '/' nor contains '..'. This is to make
-sure that no problematic pathnames can be introduced through the
+it starts neither with a '/' nor contains '..'. This is to make
+sure that no problematic pathnames can be introduced through the
CGI interface.
=item RRD::GETENV I<variable>
<RRD::GETENV REMOTE_USER>
might give you the name of the remote user given you are using
-some sort of access control on the directory
+some sort of access control on the directory.
-=back
-
-=head2 Pass 2
-
-=over 8
=item RRD::GOODFOR I<seconds>
Specify the number of seconds this page should remain valid. This will prompt
the rrdcgi to output a Last-Modified, an Expire and if the number of
-seconds is I<negative> a Refresh headers.
+seconds is I<negative> a Refresh header.
=item RRD::INCLUDE I<filename>
-Include the contents of the given file into the page returned from the cgi
+Include the contents of the specified file into the page returned from the cgi.
=item RRD::SETENV I<variable> I<value>
to make sure everything is presented in Universal Time. Note that the
values permitted to TZ depend on your OS.
+=item RRD::SETVAR I<variable> I<value>
+
+Analog to SETENV but for local variables.
+
+=item RRD::GETVAR I<variable>
+
+Analog to GETENV but for local variables.
+
=item RRD::TIME::LAST I<rrd-file> I<strftime-format>
This gets replaced by the last modification time of the selected RRD. The
-time is I<strftime>-formated with the string specified in the second argument.
+time is I<strftime>-formatted with the string specified in the second argument.
=item RRD::TIME::NOW I<strftime-format>
-This gets replaced by the current time of day. The
-time is I<strftime>-formated with the string specified in the argument.
+This gets replaced by the current time of day. The time is
+I<strftime>-formatted with the string specified in the argument.
+
+Note that if you return : (colons) from your strftime format you may
+have to escape them using \ if the time is to be used as an argument
+to a GRAPH command.
=item RRD::TIME::STRFTIME I<START|END> I<start-spec> I<end-spec> I<strftime-format>
I<strftime-format> on either I<start-spec> or I<end-spec> depending on
whether I<START> or I<END> is specified. Both I<start-spec> and I<end-spec>
must be supplied as either could be relative to the other. This is intended
-to allow pretty titles on graphs with times that are easier for non rrdtool
+to allow pretty titles on graphs with times that are easier for non RRDtool
folks to figure out than "-2weeks".
-=back
-
-=head2 Pass 3
-
-=over 8
+Note that again, if you return : (colon) from your strftime format,
+you may have to escape them using \ if the time is to be used as an
+argument to a GRAPH command.
=item RRD::GRAPH I<rrdgraph arguments>
-This tag creates the RRD graph defined in its argument and then gets
-replaced by an appropriate E<lt>IMGE<gt> tag referring to the graph.
+This tag creates the RRD graph defined by its argument and then is
+replaced by an appropriate E<lt>IMG ... E<gt> tag referring to the graph.
The B<--lazy> option in RRD graph can be used to make sure that graphs
are only regenerated when they are out of date. The arguments
to the B<RRD::GRAPH> tag work as described in the B<rrdgraph> manual page.
then you can access their output with this tag. The I<number> argument refers to the
number of the B<PRINT> argument. This first B<PRINT> has I<number> 0.
+=item RRD::INTERNAL <var>
+
+This tag gets replaced by an internal var. Currently these vars are known:
+VERSION, COMPILETIME.
+These vars represent the compiled-in values.
+
=back
=head1 EXAMPLE 1
=head1 EXAMPLE 2
-This script is slightly more elaborate, it allows you to run it from
+This script is slightly more elaborate, it allows you to run it from
a form which sets RRD_NAME. RRD_NAME is then used to select which RRD
-you want to use a source for your graph.
+you want to use as source for your graph.
#!/usr/local/bin/rrdcgi
<HTML>
<INPUT TYPE=SUBMIT></FORM>
<H2>Graph</H2>
<P>
- <RRD::GRAPH <RRD::CV::PATH RRD_NAME>.png --lazy
+ <RRD::GRAPH <RRD::CV::PATH RRD_NAME>.png --lazy
--title "Temperatures for "<RRD::CV::QUOTE RRD_NAME>
DEF:cel=<RRD::CV::PATH RRD_NAME>.rrd:exhaust:AVERAGE
LINE2:cel#00a000:"D. Celsius">
=head1 EXAMPLE 3
This example shows how to handle the case where the RRD, graphs and
-cgi-bins are seperate directories
+cgi-bins are separate directories
#!/.../bin/rrdcgi
<HTML>
=head1 AUTHOR
-Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt>
+Tobias Oetiker E<lt>tobi@oetiker.chE<gt>