------------------------------------------------------------------------------
 File chart plugin for GKrellM
 Copyright (C) 2005, Geoff Kuenning, Claremont, CA
 geoff@cs.hmc.edu

 Based heavily on gkrellm-fmonitor by Anatoly Asviyan.

 This program is free software, which I release under the GNU General
 Public License.  You may redistribute and/or modify this program
 under the terms of that license as published by the Free Software
 Foundation; either version 2 of the License, or (at your option) any
 later version.

 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.

 To get a copy of the GNU General Public License,  write to the
 Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
------------------------------------------------------------------------------

This plugin monitors a file (or several) and charts its changing
contents in gkrellm.  The simplest file contains a single integer.
The most complex can contain several graphed variables, an alert code,
multiple strings to be displayed on the chart, a tooltip, and optional
debugging information.

The primary purpose of the plugin is to ease the prototyping of new
gkrellm monitors.  Rather than going to the work of writing a complete
plugin, you can just write a script that repeatedly updates a file.
Fchart will then plot the file, and you can fiddle around with the
content and format until you have something that you like, and then
you can write a plugin.  Alternatively, you can just use fchart as-is,
without ever converting your script to a plugin.  (However, if your
script updates often, you may put a lot of extra load on your system.)

The format of the monitored file is fairly strict and mildly complex.
The general outline is:

	<charted values>
	<alert>
	<label strings>
	<tooltip>
	<eof>
	<debugging information>

The file can be truncated at any point, either by a true end of file
or by the string "!!EOF!!".

The <charted values> consist of one or more lines containing of
integer values separated by whitespace.  The first three values on
each line will be added to the chart; the remainder are ignored.  All
values must be nonnegative.  Missing values are treated as zero.  If
multiple lines appear, they are added to the chart in order; if
desired, this feature can be used to completely replace the previous
chart contents.

The <alert> is the string NORMAL, WARNING, or ALERT, followed by
arbitrary text.  This field must be present if following fields are
given.  At the moment, the trailing text is simply discarded, but in
the future it may be made available to warning and alert commands.

The <label strings> are a number of arbitrary strings, one per line.
Only the first ten are processed.  These strings are saved for use in
chart labels.  If fewer than ten are needed, the list of strings can
be terminated by "!!TOOLTIP!!" or "!!EOF!!".

The <tooltip> consists of a line containing only "!!TOOLTIP!!",
followed by an arbitrary number of lines.  All of the lines are saved
and used as the tooltip for the chart.  (Note that the tooltip can
change as time passes.)

The <eof> is either the physical end of file or a line containing only
"!!EOF!!".  It may appear as soon as desired.  If it is a physical end
of file, note that the last line must be terminated with a newline or
it will be discarded.

If <eof> is encoded by "!!EOF!!", processing will halt even if there
is more information in the file.  This can be useful for debugging;
the information given is invisible to FChart but can be seen with
"cat".  One of the sample scripts provided with this plugin
(ntpgrabber) illustrates a method of placing debugging information
after the <eof>.

The plugin repeatedly checks the file at a user-configurable interval.
If "Update only on changes" is unchecked, the file will be read and
charted at every interval.  If "Update only on changes" is checked, it
will be read and charted only when it changes; this allows the program
writing the file to control the interval between updates.

It is suggested that the entire file be written in a single Unix write
to avoid race conditions; from a script this can be done by generating
output into a scratch file and then copying it to the monitored file
with "cp" or a similar tool.  As a safety measure, if the file length
is zero, the plugin will chart the last known content, or zero if
there is no previous content.

An example file to plot three curves, with two values for each curve,
might be (without the indentation):

	123 456 789
	124 457 788
	NORMAL: Life is good
	Temperature 28C
	Red Sox 5, Yankees 1
	!!TOOLTIP!!
	Today's top news story: Green aliens ask to visit president.
	!!EOF!!
	News fetched from cnn.com in 0.5 seconds.

(Of course, a real fchart file would constantly change.)

The plugin can monitor multiple files, and for each file you can specify
the following:

Label           - label of the gkrellm chart.
File to chart   - as is :) - file to monitor. It will be checked at the
		  specified interval.  For efficiency, gkrellm will
		  hold this file open, so whatever program updates the
		  file must not attempt to acquire exclusive access.
Update program  - a shell command that generates the monitored file.  It
		  will be started when the chart is first created.  If
		  it is not specified, the plugin assumes updates are
		  done by some external process.  In the command, the
		  sequence "%w" is replaced by the chart width, and "%%"
		  is replaced by a single percent sign.
Warning command - a shell command to run whenever the state changes from
		  normal to warning.
Alert command   - a shell command to run whenever the state changes from
		  normal or warning to alert.
Check interval  - how often (in gkrellm ticks) to check the file.
Label format	- how to format text on the chart.  The usual gkrellm
		  backslash escape sequences are supported.  The
		  following substitutions can be made:

		    $0 to $9	The ten strings given in the monitored file
		    $M		The maximum chart value
Update only on changes
		- if this option is checked, the file will be
		  examined at every charting interval, but the chart
		  will be updated only if the file changed.
Show first/last N values
		- if more values are given in the chart file than the
		  chart width, chooses whether the first or the last N of
		  those values is shown.


INSTALL 
tar xvzf gkrellm-fchart-xxx.tar.gz
cd gkrellm-fchart-xxx
# to install gkrellm-fchart.so 
make
make install

EXAMPLES

The "scripts" subdirectory contains some example scripts that show
ways to use the plugin and can serve as templates for writing new
ones.  Each script is self-documenting (see the comments at the
beginning). 

    ntpgrabber	- This script was the impetus for writing Fchart.  I
		  wanted to monitor several NTP servers to make sure
		  my setup was valid.  Ntpgrabber is unique in that it
		  produces output files suitable for use with both the
		  fmonitor and fchart plugins.  (I keep both active in
		  a special gkrellm instance that watches three
		  different NTP servers.)  The script is extremely
		  complex, so I don't recommend using it as an example
		  until you've looked at some simpler ones.  But it's
		  still useful for watching your NTP connection(s).
    pingtimer	- This is the simplest of the scripts, and thus the
		  best to start with.  It pings up to three hosts once
		  per second and charts the measured latency.  You
		  will find it very revealing.
    tideplot	- This uses the xtide package to plot the tides for a
		  chosen location.  It is a good example of how to
		  use the multiple-plotting feature to fill up a chart
		  window (otherwise it would take over a day,
		  depending on the parameters you chose).  Run it with
		  "-w %w".  Exercise for the reader: modify it to
		  accept up to three locations and plot all of their
		  tides on the same graph.

Authors of further useful scripts are encouraged to send either a link
(preferred) or the script itself to me for inclusion in future
distributions.

CREDITS
This plugin is heavily based on gkrellm-fmonitor by Anatoly Asviyan
(aanatoly@linuxmail.org).
