PLOVE
~~~~~

OVERVIEW
--------

Plove is a handy tool for plotting OMNeT++ output vectors. It uses
gnuplot to do the actual work.

You can specify the drawing style (lines, dots etc) for each vector
as well as set the most frequent drawing options like axis bounds,
scaling, titles and labels etc.

You can save the gnuplot graphs to files (postscript, latex, pbm etc)
with a click. Plove can also generate standalone shell scripts
that plot output vectors in much the same way Plove does itself. These
scripts can be used for batch processing or to debug filters (see later).

Plove does not take away any of gnuplot's flexibility -- you can embed
your own gnuplot commands to customize the output.

Filtering the results before plotting (averaging, truncation, smoothing,
etc) is possible. Some filters are built in, and you can easily create
new filters or modify the existing ones. Filters can be incorporated
in one of three ways: as awk expressions, as awk programs and as external
filter programs. Filters can be parameterized.

Multiple filters for the same vector is not currently supported;
also, you cannot currently feed several vectors into a single filter.

Plove does not create temporary files, so you don't need to worry
about disk space: if the output vector is there, Plove can
plot it for you. Moreover, it can also work with gzipped vector
files without extracting them -- just make sure you have zcat.

Plove never modifies the output vector files themselves.

On startup, Plove automatically reads the .ploverc file in your home
directory. The file contains general gnuplot settings, the filter
configuration etc (that is, the stuff from the Options menu).


REQUIRED PROGRAMS
-----------------
grep, gnuplot -- absolutely needed
awk (gawk) -- if you want to use the built-in filters
zcat -- if you want to process gzipped output vector files (without decomp-
        ressing them)


WINDOWS
-------

Windows users should create a plove.bat file which starts plove using wish,
e.g:
   @c:\tcl82\bin\wish82.exe -f c:\omnetpp\src\plove\plove
or rename the plove file to plove.tcl and associate the .tcl extension with
the wish application.

Be sure to fill in the Options|External programs dialog. If still you cannot
load an output vector file properly (you see garbage in the left listbox),
your grep program is probably broken (it has difficulties with Unix-style,
LF-terminated lines). Especially, the Borland grep is not good. You should
get a decent one, for example from the Cygwin package.


USAGE
-----

First, you load an output vector file (.vec) into the left pane. You can
also load gzipped vector files (.vec.gz) without having to decompress them.
You can copy vectors from the left pane to the right pane by clicking
the right arrow icon in the middle. The large PLOT button will plot the
_selected_ vectors in the right pane. Selection works as in Windows:
dragging and shift+left click selects a range, and ctrl+left click
selects/deselects individual items. To adjust drawing style, change vector
title or add filter, push the Options... button. This works for several
selected vectors too.  Plove accepts nc/mc-like keystrokes: F3, F4, F5,
F6, F8, grey'+' and grey '*'.

The left pane works as a general storage for vectors you're working with.
You can load several vector files, delete unnecessary vectors, rename them
etc. All this will not affect the vector files on disk. In the right pane,
you can duplicate vectors if you want to filter the vector and also keep
the original. If you set the right options for a vector but temporarily
do not want it to hang around in the right pane, you can put it back
into the left pane for storage.


WRITING FILTERS
---------------

As you might have guessed already, filters get an output vector on
their standard input (as plain text, with the timestamp being the second
and the value being the third field on each line), do some processing
to it and write the result to the standard output.

Filters can be incorporated in one of three ways: as awk expressions, as
awk programs and as external programs. The 'awk expression' filters mean
assembling and launching commands like this:
 ... | awk '{$3 = <expression>; print}' | ...
An awk program filter means running the following command:
 ... | awk '<program>' | ...
The third type of filters will be used like this:
 ... | <program> <parameters> | ...
Before the filter pipeline is launched, the following substitutions
are performed on the awk scripts:
  t --> $2
  x --> $3
The parameters of the form $(paramname) are also replaced with their
actual value.

Thus, if you want to add 1 to all value, you can use the awk expression
filter x+1 (this will turn into: awk '{$3 = $3+1}; print').
When you want to shift the vector by a used-defined DT time, you can
create the following awk program filter: {t += $(DT); print}.
Do not forget the print statement, or your filter will not output
anything and the gnuplot graph will be empty.

If you push the PLOT button and nothing shows up, probably there's something
wrong with the filter expression. If you're writing a new filter and it
doesn't seem to work, choose File|Save script and do your debugging on the
resulting script. For example, it is a common mistake to leave out 'print'
from the script.


PORTABILITY
-----------

Plove works fine on Unix and (with some limitations) on Win95/NT.
(The limitations come from the facts that Win95/NT doesn't have named
pipes in the way Unix does, the length of the command line is limited,
the shell is crippled etc... I had to use a dozen temporary files.
And expect the Win95/NT version to be slower than Unix version.)

Known bug:
If you plot too many vectors at the same time, some of them may not
appear in the plot because the length of the 'plot' command exceeds
the limit hardwired in gnuplot.

Enjoy!

--Andras

