removed old README file

README

@@ -1,115 +0,0 @@
-feedGnuplot README
-==================
-
-This is a flexible, command-line-oriented frontend to Gnuplot. It creates
-plots from data coming in on STDIN or given in a filename passed on the
-commandline. Various data representations are supported, as is hardcopy
-output and streaming display of live data. A simple example:
-
-
-seq 5 | awk '{print 2*$1, $1*$1}' |
-feedGnuplot.pl --lines --points --legend "data 0" --title "Test plot" --y2 1
-
-
-You should see a plot with two curves (one on the y1 axis and the other on
-the y2 axis), a legend and a title. The first line of the example generates
-some data to plot and the second reads it in from STDIN and generates the
-plot. None of the commandline-options are required for the most basic
-plotting. Input parsing is flexible; every line need not have the same
-number of points. New curves will be created as needed.
-
-By default, the line number of the incoming data is used for the x-axis. To
-plot an x-y dataset, feed in the x values as the first element in every line
-and pass in --domain. With the previous example:
-
-
-seq 5 | awk '{print 2*$1, $1*$1}' |
-feedGnuplot.pl --domain --lines --points --legend "data 0" --title "Test plot" --y2 1
-
-
-we get only one curve, with different x values. As many points as desired
-can appear on a single line, but all points on a line are associated with
-the X value that starts that line.
-
-By default, each column represents a separate curve. If sparse data is to be
-plotted, this is undesireable. With the --dataid option, each point in the
-input is preceded by string identifying the curve the point belongs
-to. With the previous example:
-
-
-seq 5 | awk '{print 2*$1, $1*$1}' |
-feedGnuplot.pl --dataid --lines --points --legend "data 0" --title "Test plot" --y2 1
-
-
-we get 5 different curves with one point in each. The first column, as
-produced by awk, is '2,4,6,8,10'. These are interpreted as the indices of
-the curves to be plotted. The feedGnuplot.pl script created 11 different
-curves (0-10 inclusive), but only 5 of them were given any data. Note that
-with this invocation of the example no legend was created. This is because
-the legend commandline parameters are applied in order to curves
-0,1,2,... Above, "data 0" applied to curve 0, which had no data. If we
-passed in --legend "data 0" --legend "data 1" --legend "data 2", a legend
-would be created with "data 2" labeled, but no labels for the other
-curves. As many points as desired can appear on a single line, and --domain
-can be used together with --dataid.
-
-Note that the IDs used with --dataid are general strings, NOT just
-numbers. These IDs can be used to generate the plot legend with --autolegend.
-
-The script is able to produce hardcopy output with "--hardcopy
-outputfile". The output type is inferred from the filename with .ps, .pdf
-and .png currently supported.
-
-If live data is received in realtime, feedGnuplot.pl can be used to produce a
-realtime display by passing in the --stream option. The "--xlen windowsize"
-option can be passed in also to plot a scrolling window, containing the last
-windowsize-worth of data (windowsize has the units of the x axis, whether it
-is a point index or the passed-in domain). If --xlen is omitted or set to 0,
-all of the available data is plotted, with no moving window. The realtime data
-is updated at 1 Hz, so the script can handle rapidly-incoming data without
-spending all of its time replotting. Example:
-
-
-seq 500 | awk '{print 2*$1, $1*$1; system("sleep 2"); fflush()}' |
-feedGnuplot.pl --stream --lines --points --legend "data 0" --title "Test plot" --y2 1
-
-
-This script can be used to generate self-plotting data files. If a file
-called 'data' is created with:
-
-
-#!/usr/local/bin/feedGnuplot.pl --lines --points --legend "data 0" --title "Test plot" --y2 1
-2 1
-4 4
-6 9
-8 16
-10 25
-12 36
-14 49
-16 64
-18 81
-20 100
-22 121
-24 144
-26 169
-28 196
-30 225
-
-
-This file can be plotted with
-
-
-bash$ ./tst
-
-
-The caveats here are that on Linux the whole #! line is limited to 127
-charaters and that the full path to feedGnuplot.pl must be given.
-
-For more information, invoke with --help, or read the source. Any bugs or
-suggestions should be addressed to dkogan@cds.caltech.edu. The latest
-version of the script is available at http://github.com/dkogan/feedgnuplot
-
-
-This program is originally based on the driveGnuPlots.pl script from
-Thanassis Tsiodras. It is available from his site at
-http://users.softlab.ece.ntua.gr/~ttsiod/gnuplotStreaming.html

README.pod

@@ -0,0 +1,193 @@
+=head1 NAME
+
+feedGnuplot - A pipe-oriented frontend to Gnuplot
+
+=head1 SYNOPSIS
+
+Simple plotting of stored data:
+
+ $ seq 5 | awk '{print 2*$1, $1*$1}'
+ 2 1
+ 4 4
+ 6 9
+ 8 16
+ 10 25
+
+ $ seq 5 | awk '{print 2*$1, $1*$1}' |
+   feedGnuplot --lines --points --legend "data 0" --title "Test plot" --y2 1
+
+Simple real-time plotting example: plot how much data is received on the wlan0
+network interface in bytes/second (uses bash, awk and Linux):
+
+ $ while true; do sleep 1; cat /proc/net/dev; done |
+   awk '/wlan0/ {if(b) {print $2-b; fflush()} b=$2}' |
+   feedGnuplot --lines --stream --xlen 10 --ylabel 'Bytes/sec' --xlabel seconds
+
+=head1 DESCRIPTION
+
+This is a flexible, command-line-oriented frontend to Gnuplot. It creates
+plots from data coming in on STDIN or given in a filename passed on the
+commandline. Various data representations are supported, as is hardcopy
+output and streaming display of live data. A simple example:
+
+ $ seq 5 | awk '{print 2*$1, $1*$1}' | feedGnuplot
+
+You should see a plot with two curves. The C<awk> command generates some data to
+plot and the C<feedGnuplot> reads it in from STDIN and generates the plot. The
+<awk> invocation is just an example; more interesting things would be plotted in
+normal usage. None of the commandline-options are required for the most basic
+plotting. Input parsing is flexible; every line need not have the same number of
+points. New curves will be created as needed.
+
+The most commonly used functionality of gnuplot is supported directly by the
+script. Anything not directly supported can still be done with the
+C<--extracmds> and C<--curvestyle> options. Arbitrary gnuplot commands can be
+passed in with C<--extracmds>. For example, to turn off the grid, pass in
+C<--extracmds 'unset grid'>. As many of these options as needed can be pased
+in. To add arbitrary curve styles, use C<--curvestyle extrastyle>. Pass these
+more than once to affect more than one curve. To apply an extra style to I<all>
+the curves, pass in C<--curvestyleall extrastyle>.
+
+=head2 Data formats
+
+By default, each value present in the incoming data represents a distinct data
+point, as demonstrated in the above example (we had 10 numbers in the input and
+10 points in the plot). If requested, the script supports more sophisticated
+interpretation of input data
+
+=head3 Domain selection
+
+If C<--domain> is passed in, the first value on each line of input is
+interpreted as the I<X>-value for the rest of the data on that line. Without
+C<--domain> the I<X>-value is the line number, and the first value on a line is
+a plain data point like the others. Default is C<--nodomain>. Thus the example
+above produces 2 curves, with B<1,2,3,4,5> as the I<X>-values. If we run the
+same command with --domain:
+
+ $ seq 5 | awk '{print 2*$1, $1*$1}' | feedGnuplot --domain
+
+we get only 1 curve, with B<2,4,6,8,10> as the I<X>-values. As many points as
+desired can appear on a single line, but all points on a line are associated
+with the I<X>-value at the start of that line.
+
+=head3 Curve indexing
+
+By default, each column represents a separate curve. This is fine unless sparse
+data is to be plotted. With the C<--dataid> option, each point is represented by
+2 values: a string identifying the curve, and the value itself. If we add
+C<--dataid> to the original example:
+
+ $ seq 5 | awk '{print 2*$1, $1*$1}' | feedGnuplot --dataid --autolegend
+
+we get 5 different curves with one point in each. The first column, as produced
+by C<awk>, is B<2,4,6,8,10>. These are interpreted as the IDs of the curves to
+be plotted. The C<--autolegend> option adds a legend using the given IDs to
+label the curves. The IDs need not be numbers; generic strings are accepted. As
+many points as desired can appear on a single line. C<--domain> can be used in
+conjunction with C<--dataid>.
+
+=head3 Multi-value style support
+
+Depending on how gnuplot is plotting the data, more than one value may be needed
+to represent a single point. For example, the script has support to plot all the
+data with C<--circles>. This requires a radius to be specified for each point in
+addition to the position of the point. Thus, when plotting with C<--circles>, 2
+numbers are read for each data point instead of 1. A similar situation exists
+with C<--colormap> where each point contains the position I<and> the
+color. There are other gnuplot styles that require more data (such as error
+bars), but none of these are directly supported by the script. They can still be
+used, though, by specifying the specific style with C<--curvestyle>, and
+specifying how many extra values are needed for each point with
+C<--extraValuesPerPoint extra>. C<--extraValuesPerPoint> is ONLY needed for the
+styles not explicitly supported; supported styles set that variable
+automatically.
+
+=head3 3D data
+
+To plot 3D data, pass in C<--3d>. C<--domain> MUST be given when plotting 3D
+data to avoid domain ambiguity. If 3D data is being plotted, there are by
+definition 2 domain values instead of one (I<Z> as a function of I<X> and I<Y>
+instead of I<Y> as a function of I<X>). Thus the first 2 values on each line are
+interpreted as the domain instead of just 1. The rest of the processing happens
+the same way as before.
+
+=head2 Real-time streaming data
+
+To plot real-time data, pass in the C<--stream> option. Data will then be
+plotted as it is received, with the refresh rate limited to 1Hz (currently
+hard-coded). To plot only the most recent data (instead of I<all> the data),
+C<--xlen windowsize> can be given. This will create an constantly-updating,
+scrolling view of the recent past. C<windowsize> should be replaced by the
+desired length of the domain window to plot, in domain units (passed-in values
+if C<--domain> or line numbers otherwise).
+
+=head2 Hardcopy output
+
+The script is able to produce hardcopy output with C<--hardcopy outputfile>. The
+output type is inferred from the filename with B<.ps>, B<.eps>, B<.pdf> and
+B<.png> currently supported.
+
+=head2 Self-plotting data files
+
+This script can be used to create self-plotting data files. A self-plotting,
+executable data file C<data> is formatted as
+
+ $ cat data
+ #!/usr/bin/feedGnuplot --lines --points
+ 2 1
+ 4 4
+ 6 9
+ 8 16
+ 10 25
+ 12 36
+ 14 49
+ 16 64
+ 18 81
+ 20 100
+ 22 121
+ 24 144
+ 26 169
+ 28 196
+ 30 225
+
+This is the shebang (#!) line followed by the data, formatted as before. The
+data file can be plotted simply with
+
+ $ ./data
+
+The caveats here are that on Linux the whole #! line is limited to 127 charaters
+and that the full path to feedGnuplot must be given. The 127 character limit is
+a serious limitation, but this can likely be resolved with a kernel patch. I
+have only tried on Linux 2.6.
+
+=head2 Further help
+
+All the options are described with
+
+ $ feedGnuplot --help
+
+=head1 ACKNOWLEDGEMENT
+
+This program is originally based on the driveGnuPlots.pl script from
+Thanassis Tsiodras. It is available from his site at
+L<http://users.softlab.ece.ntua.gr/~ttsiod/gnuplotStreaming.html>
+
+=head1 REPOSITORY
+
+L<https://github.com/dkogan/feedgnuplot>
+
+=head1 AUTHOR
+
+Dima Kogan, C<< <dkogan at cds.caltech.edu> >>
+
+=head1 LICENSE AND COPYRIGHT
+
+Copyright 2011 Dima Kogan.
+
+This program is free software; you can redistribute it and/or modify it
+under the terms of either: the GNU General Public License as published
+by the Free Software Foundation; or the Artistic License.
+
+See http://dev.perl.org/licenses/ for more information.
+
+=cut

bin/feedGnuplot

@@ -677,7 +677,6 @@ sub pushPoint
   push @$curve, $xy;
 }
 
-
 __END__
 
 =head1 NAME