[Orca-checkins] r326 - trunk/orca/orca

[Blair Zajac]

Author: blair
Date: Thu May 27 20:49:51 2004
New Revision: 326

Modified:
   trunk/orca/orca/orca.pl.in
Log:
* orca/orca.pl.in
  (pod):
    Improve the plot configuration file parameter documentation.


Modified: trunk/orca/orca/orca.pl.in
==============================================================================
--- trunk/orca/orca/orca.pl.in	(original)
+++ trunk/orca/orca/orca.pl.in	Thu May 27 20:49:51 2004
@@ -1871,20 +1871,23 @@
   .
   }
 
-Unlike the group, there is no key for generating a plot.  An unlimited
-number of plots can be created.
+Unlike a group, there is no key name for a plot.  An unlimited number
+of plots can be created.
+
+The B<title> and B<legend> plot parameters, described below, may
+contain either the string %g or the string %G.  Here, the 'g' refers
+to the 'g' in subgroup.  A subgroup name is generated by joining with
+a _ character all the strings that matched ()'s in the find_files
+parameter for the group name given to the B<source> plot parameter.
+All %g's are replaced with the subgroup name and all %G's are replaced
+with the subgroup name with the first character capitalized.
 
-Some of the plot parameters if they have the two characters %g or %G
-will perform a substitution of this substring with the group name from
-the find_files ()'s matching.  %g gets replaced with the exact match
-from () and %G gets replaced with the first character capitalized.
 For example, if
 
   find_files /(olympia)/data
 
-was used to locate a file, then %g will be replaced with olympia and
-%G replaced with Olympia.  This substitution is performed on the
-B<title> and B<legend> plot parameters.
+was used to find a file, then %g will be replaced with olympia and %G
+replaced with Olympia.
 
 =head2 Required Plot Parameters
 
@@ -1892,7 +1895,7 @@
 
 =item B<source> I<group_name>
 
-The B<source> argument should be a single group name from which data
+The B<source> argument must be one of the group names from which data
 will be plotted.  Currently, only data from a single group may be put
 into a single plot.
 
@@ -1900,19 +1903,18 @@
 
 =item B<data> I<regular expression>
 
-The B<data> plot parameter tells Orca the data sources to use to place
-in a single PNG plot.  At least one B<data> parameter is required for
-a particular plot and as many as needed may be placed into a single
-plot.
+The B<data> plot parameter tells Orca which the data sources to use in
+a single plot.  At least one B<data> parameter is required for a plot.
+There is no limit on how many B<data>s may be placed in a plot.
 
 Two forms of arguments to B<data> are allowed.  The first form allows
-arbitrary Perl expressions, including mathematical expressions, that
-result in a number as a data source to plot.  The expression may
-contain the names of the columns as found in the group given to the
-B<source> parameter.  The column names must be separated with white
-space from any other characters in the expression.  For example, if
-you have number of bytes per second input and output and you want to
-plot the total number of bits per second, you could do this:
+arbitrary Perl expressions that return a number to plot.  The
+expression may contain the names of the columns as found in the group
+given to the B<source> parameter.  The column names must be separated
+with white space from any other characters in the expression.  For
+example, if you have the input and output number of bytes per second
+and you want to plot the total number of bits per second, you could do
+this:
 
   plot {
   source        bytes_per_second
@@ -1976,13 +1978,12 @@
 each plot containing the input and output number of packets per
 second.
 
-By default, when Orca finds a plot set with a regular expression
-match, it will only find one match, and then go on to the next plot
-set.  After it reaches the last plot set, it will go back to the first
-plot set with a regular expression match and look for the next data
-that matches the regular expression.  The net result of this is that
-the generated HTML files using the above configuration will have links
-in this order:
+By default, when Orca finds a plot with a regular expression, it will
+only find one match, and then go on to the next plot.  After it
+reaches the last plot, it will go back to the first plot with a
+regular expression and look for the next data that matches it.  The
+net result of this is that the generated HTML files using the above
+configuration will have the plots listed in this order:
 
   hme0 Input & Output Packets per Second
   hme0 Input & Output Kilobytes per Second
@@ -1993,14 +1994,13 @@
 
 If you wanted to have the links listed in order of hme0 and hme1, then
 you would add the B<flush_regexps> parameter to tell Orca to find all
-regular expression matches for a particular plot set and all plot sets
-before the plot set containing B<flush_regexps> before continuing on
-to the next plot set.  For example, if
+regular expression matches for a particular plot and all plots before
+the plot containing B<flush_regexps> before continuing on to the next
+plot.  For example, if
 
   flush_regexps 1
 
-were added to the plot set for InKB/s and OuKB/s, then the order would
-be
+were added to the plot for InKB/s and OuKB/s, then the order would be
 
   hme0 Input & Output Packets per Second
   hme0 Input & Output Kilobytes per Second
@@ -2011,7 +2011,7 @@
 
 If you wanted to have all of the plots be listed in order of the type
 of data being plotted, then you would add "flush_regexps 1" to all the
-plot sets and the order would be
+plot and the order would be
 
   hme0 Input & Output Packets per Second
   hme1 Input & Output Packets per Second