[Orca-checkins] r312 - trunk/orca/orca
Blair Zajac
blair at orcaware.com
Wed May 12 21:04:08 PDT 2004
Author: blair
Date: Wed May 12 21:02:14 2004
New Revision: 312
Modified:
trunk/orca/orca/orca.pl.in
Log:
* orca/orca.pl.in
(pod):
Cleanup Orca's POD.
Modified: trunk/orca/orca/orca.pl.in
==============================================================================
--- trunk/orca/orca/orca.pl.in (original)
+++ trunk/orca/orca/orca.pl.in Wed May 12 21:02:14 2004
@@ -1156,12 +1156,9 @@
Orca is a tool useful for plotting arbitrary data from text files onto
a directory on Web server. It has the following features:
- * Configuration file based.
* Reads white space separated data files.
* Watches data files for updates and sleeps between reads.
* Finds new files at specified times.
- * Remembers the last modification times for files so they do not
- have to be reread continuously.
* Can plot the same type of data from different files into different
or the same PNGs.
* Different plots can be created based on the filename.
@@ -1177,6 +1174,8 @@
* Creates an index of URL links listing all available targets.
* Creates an index of URL links listing all different plot types.
* No separate CGI set up required.
+ * Remembers the last modification times for files so they do not
+ have to be reread continuously.
* Can be run under cron or it can sleep itself waiting for file
updates based on when the file was last updated.
@@ -1221,19 +1220,19 @@
Orca has only five command line options. They are:
-B<-gifs>: Generate GIFs instead of PNGs. Tell Orca to generate GIFs
-instead of PNGs. You may not want to generate GIFs since PNGs are 1/3
-the size of GIFs and take less time to generate. The only reason to
-do this is if you are using a browser that does not support PNGs and
-only supports GIFs.
+B<-gifs>: Tell Orca to generate GIFs instead of PNGs. Most likely,
+you will not want to generate GIFs since PNGs are 1/3 the size of GIFs
+and take less time to generate. The only reason to do this is if you
+are using a browser that does not support PNGs and only supports GIFs.
B<-no-html>: Do not generate any HTML files and only update the
images.
B<-o>: Once. This tells Orca to go through the steps of finding
files, updating the RRDs, updating the PNGs, and creating the HTML
-files once. Normally, Orca loops continuously looking for new and
-updated files.
+files once. Normally, Orca continuously loops reading new data from
+updated data files and sleeping waiting for the data files to be
+updated.
B<-r>: RRD only. Have Orca only update its RRD files. Do not
generate any HTML or PNG files. This is useful if you are loading in
@@ -1246,9 +1245,9 @@
more than three B<-v>'s are not used by Orca.
After the command line options are listed, Orca takes one more
-argument which is the name of the configuration file to use. Sample
-configuration files can be found in the sample_configs directory with
-the distribution of this tool.
+argument which is the name of the configuration file to use. Actual
+configuration files can be found in the data_gatherers directory
+distributed with Orca.
=head1 MAILING LISTS
@@ -1256,7 +1255,7 @@
lists, please visit the URL listed below. You have the option of
choosing a digest form of the mailing list when you subscribe to the
mailing list or anytime thereafter. To send email to any of these
-lists you must subscribe to the list.
+lists you must first subscribe to the list.
B<orca-announce at orcaware.com>
@@ -1276,10 +1275,13 @@
B<orca-users at orcaware.com>
- The orca-users at orcaware.com is the mailing list for Orca users.
- Problems relating to downloading, configuring, compiling the
- necessary Perl modules, installing and configuring Orca belong
- here.
+ The orca-users at orcaware.com is a general discussion mailing list
+ for Orca users. This mailing list is appropriate for almost any
+ Orca discussion except for the development of Orca, as those
+ discussions belong on the orca-dev at orcaware.com mailing list. So
+ issues relating to the installation of, configuring of, and
+ understanding of Orca are welcome. So are questions relating to
+ the Perl module's that Orca requires.
Home Page
http://www.orcaware.com/mailman/listinfo/orca-users
@@ -1328,7 +1330,7 @@
=head1 PLOT PREFIXES
-RRDtool generates the actual GIF or PNG plots and sometimes will need
+RRDtool generates the actual PNG or GIF plots and sometimes will need
to scale the Y axis of the plot to have normal looking like numbers,
such as 1 M instead of 1,000,000. If you see a letter following the
numbers in the bottom of the plot, then use that letter to scale the Y
@@ -1384,7 +1386,7 @@
There are three main groups of parameters in a Orca configuration
file: global parameters, file specific parameters, and plot specific
parameters. Global parameters may be used by the group and plot
-specific parameters. If an parameter is required, then it is only
+specific parameters. If a parameter is required, then it is only
placed one time into the configuration file.
Global parameters break down into two main groups, required and
@@ -1394,6 +1396,13 @@
=over 4
+=item B<base_dir> I<directory>
+
+If B<base_dir> is set, then it is used to prepend to any file or
+directory names that do not begin with /. These are currently
+B<state_file>, B<html_dir>, B<rrd_dir>, and the B<find_files>
+parameter in the B<group> section.
+
=item B<state_file> I<filename>
For Orca to work efficiently, it saves the last modification time of
@@ -1435,13 +1444,6 @@
B<rrd_dir>. Orca will quit with an error if both B<rrd_dir> and
B<base_dir> are not set.
-=item B<base_dir> I<directory>
-
-If B<base_dir> is set, then it is used to prepend to any file or
-directory based names that do not begin with /. These are currently
-B<state_file>, B<html_dir>, B<rrd_dir>, and the B<find_files>
-parameter in the B<group> section.
-
=back
=head2 Optional Global Parameters
@@ -1450,36 +1452,13 @@
=item B<require> I<package name> I<version number>
-B<require> allows the configuration file to specify the minimum
-required version of a package to run as in the same way that B<use>
-and B<require> are used in Perl programs. Here, both I<package name>
+The B<require> parameter allows the configuration file to specify the
+minimum required version of a package to run. Both I<package name>
and I<version number> are required and I<version number> must be a
number, not a general Perl expression.
-Currently, only the version of Orca can be specified and I<package
-name> must be set to Orca.
-
-=item B<late_interval> I<Perl expression>
-
-B<late_interval> is used to calculate the time interval between a
-file's last modification time and the time when that file is
-considered to be late for an update. In this case, an email message
-may be sent out using the B<warn_email> addresses. Because different
-input files may be updated at different rates, B<late_interval> takes
-an arbitrary Perl expression, including mathematical expressions, as
-its argument. If the word I<interval> occurs in the mathematical
-expression it is replaced with the sampling interval of the input data
-file in question.
-
-This is useful for allowing the data files to update somewhat later
-than they would in an ideal world. For example, to add a 10% overhead
-to the sampling_interval before an input file is considered late, this
-would be used
-
- late_interval 1.1 * interval
-
-By default, the input file's sampling interval is used as the
-late_interval.
+Currently, only the minimum required version of Orca can be specified
+and I<package name> must be set to Orca.
=item B<warn_email> I<email_address> [I<email_address> ...]
@@ -1499,12 +1478,34 @@
warn_email
+=item B<late_interval> I<Perl expression>
+
+B<late_interval> is used to calculate the time interval between a
+file's last modification time and the time when that file is
+considered to be late for an update. When this happens, an email
+message will be sent out using the B<warn_email> addresses. Because
+different input files may be updated at different rates,
+B<late_interval> takes an arbitrary Perl expression, including
+mathematical expressions, as its argument. If the word I<interval>
+occurs in the mathematical expression it is replaced with the sampling
+interval of the input data file in question.
+
+This is useful for allowing the data files to update somewhat later
+than they would in an ideal world. For example, to add a 10% overhead
+to the sampling_interval before an input file is considered late, this
+would be used
+
+ late_interval 1.1*interval
+
+By default, the input file's sampling interval is used as the
+late_interval.
+
=item B<expire_images> 1
If B<expire_images> is set then .meta files will be created for all
generated PNG files. If the Apache web server 1.3.2 or greater is
-being used, then the following modifications must added to srm.conf or
-httpd.conf.
+being used, then the following modifications must added to Apache's
+httpd.conf file.
<
< #MetaDir .web
@@ -1521,9 +1522,9 @@
=item B<find_times> I<hours:minutes> [I<hours:minutes> ...]
-The B<find_times> parameter is used to tell Orca when to go and find
-new files. This particularly useful when new input data files are
-created at midnight. In this case, something like this may work:
+The B<find_times> parameter is used to tell Orca when to find new
+files. This particularly useful when new input data files are created
+at midnight. In this case, something like this may work:
# Find files at the following times:
# 0:10 to pick up new orcallator files for the new day.
@@ -1542,21 +1543,21 @@
=item B<html_top_title> I<text> ...
This sets the text, that should not be HTML markup, that is used only
-in the main index.html file. It is used in the <title></title>
+in the main index.html file. It is placed in the <title></title>
element and also placed in the HTML body after the html_page_header in
-a <h1></h1> element index.html file. By default, no additional text
-is placed at the top of the main index.html.
+a <h1></h1> element. By default, this text is empty.
=item B<html_page_header> I<html> ...
-The I<html> is placed at the top of each HTML file that Orca creates.
-By default, no additional text is placed at the top of each HTML file.
+The I<html> is placed at the top of every HTML file that Orca creates.
+It can be HTML markup. By default, I<html> is empty is empty so no
+additional HTML markup is added to the file.
=item B<html_page_footer> I<html> ...
-The I<html> is placed at the bottom of each HTML file that Orca
-creates. By default, no additional text is placed at the bottom of
-each HTML file.
+The I<html> is placed at the bottom of every HTML file that Orca
+creates. It can be HTML markup. By default, I<html> is empty is
+empty so no additional HTML markup is added to the file.
=item B<generate_hourly_plot> I<value>
More information about the Orca-checkins
mailing list