xplot 1.19-9 / usr / share / xplot / xplot.help

 [Introduction]
     [Copyright notice]
     [Obtaining XPlot]
     [Bug reports and wishlists]
 [Program invocation]
     [Command line arguments]
     [Format of the data]
     [Flag arguments]
 [The XPlot window]
     [Boundaries of the plot]
     [Selecting and deselecting datasets]
     [Making larger plots: blowups]
     [Line types of the plots]
     [Postponed or immediate plotting]
     [Plot titles]
     [Quitting XPlot]
 [Installing XPlot]
     [Compiling XPlot]

[Introduction]

@C4@l@b@i@cIntroduction

XPlot is a small program to plot one- or twodimensional datasets, which are
present either in a file or are generated `on-the-fly' and piped to XPlot.
XPlot lets you display one or more datasets and lets you zoom to different
sections of the sets. Also. `blowups' of the currently shown portion of the
data can be made.

[Copyright notice]

@b@i@C4Copyright notice

@i@cCopyright (C) 1995  Karel Kubat. 

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.

You may link this software with XForms (Copyright (C) by T.C. Zhao and
Mark Overmars) and distribute the resulting binary, under the
restrictions in clause 3 of the GPL, even though the resulting binary is
not, as a whole, covered by the GPL. (You still need a separate license
to do so from the owner(s) of the copyright for XForms, however).  If a
derivative no longer requires XForms, you may use the unsupplemented GPL
as its license by deleting this paragraph and therefore removing this
exemption for XForms.

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.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA

[Obtaining XPlot]

@C4@b@iObtaining XPlot

XPlot can be obtained via anonymous ftp at the site ftp.icce.rug.nl, directory
/pub/unix, files xplot*. You will need the archive xplot-X.YY.tar.gz (where
X.YY is the version number); check this site for new versions.

Once you unpack the archive, see the file xplot.help for more information
about installation (this is in fact this text).

[Bug reports and wishlists]

@C4@b@iBug reports and wishlists

I, the author, can be reached via e-mail at karel@icce.rug.nl. You can mail me
if you have bug reports or specific wishes for XPlot. Please keep in mind that
XPlot is meant to be an easy and fast datafile plotter, so don't mail me
suggestions like "XPlot should be able to plot functions like y = sin(x)". 
XPlot will never calculate functions to plot them. Similarly, don't mail me 
that "XPlot doesn't have a PRINT button that sends the plot to my SuperMega 
LaserPrinter". XPlot is meant to show data on the screen. If you're shopping 
for a more `complete' program, check out gnuplot.

If you encounter bugs in the XPlot program, mail me the full description of
the error, the number of your version of XPlot, and preferably a datafile to
demonstrate. I'll repair the bug when I find the time. Also, please CHECK
the ftp site for newer versions of XPlot: it may well be that the bug was
discovered previously and repaired.

[Program invocation]

@C4@l@b@i@cProgram invocation

The program invocation is described in three subsections: command line
arguments, format of the data, and flag arguments.

[Command line arguments]

@b@i@C4Command line arguments

XPlot must be invoked by providing at least one source of data. That means
that you can start XPlot as:

    xplot datafile(s)

or as:

    command | xplot

Several datafiles can be stated on the commandline, in which several lines are
plotted (with different colors).  XPlot can simultaneously show up to 11
datasets. Later you can interactively select or deselect the datasets that are 
simultaneously shown.

XPlot currently supports the following flags: 

    "-title STRING". The string is used as a title for the plot and can also 
    be set interactively (see [Plot titles]). 

    "-format FORMAT". The formatstring FORMAT is used to read in data. If
    you're familiar with C, then you know what a formatstring is. The default 
    formatstring is "%f %f ", meaning that XPlot should try to interpret each 
    linetwo  as two numbers (%f, for `floating point value'), separated 
    by one or more whitespace characters. The -format flag can be handy if,
    e.g., you want to read in a file like
        time 12.0       value 3
        time 12.1       value 4
        time 12.2       value 5
    You'd then have a format string "time %f value %f ". Don't forget the 
    trailing blank in the formatstring, it makes sure that the end-of-line 
    character is skipped.
    
    "-v". This flag increases the `verbosity': XPlot prints information about 
    what files are read and of how many points they consist when this flag is 
    present. 
    
    "-y YRANGE". This flag allows you to specify the range of the Y axis at 
    startup. Normally XPlot determines the range from the read data. The 
    YRANGE specifier must be in the form NUMBER:NUMBER, where the first number 
    specifies the lowest value of the Y axis, and the second number specifies 
    the highest value.
    
When XPlot is started with incorrect arguments, usage information is shown.

[Format of the data]

@b@i@C4Format of the data

XPlot supports either one- or twodimensional data. One-dimensional data
consist of values, separated by newlines, one value per line.  XPlot
interprets this format as a series of Y values, to which X values are created
by using 0 for the first X value, 1 for the next X value, etc..

Two-dimensional sets consist of two values per line, an X and an Y value. The
values must be separated by whitespace characters (spaces or tabs).

[Flag arguments]

@b@i@C4Flag arguments

XPlot is built with the XForms Graphical User Interface Toolkit for X, and
hence supports a number of flags which are interpreted by XForms.  The flags
must be stated before any file arguments, and are:

    -display host:dpy (defines the X display)
    -name appname (defines the application name)
    -visual class (TrueColor, PseudoColor etc..)
    -depth d (visual depth in bits)
    -private (forces a private colormap)
    -shared (forces a shared colormap)
    -stdcmap (forces a standard colormap)
    -debug l (prints debugging information, l is the level)
    -sync (forces synchronous mode)

[The XPlot window]

@C4@l@b@i@cThe XPlot window

The main XPlot window is called the `Control window'. It lets you select
boundaries for the plot, activate or deactivate cetain datasets, etc.. See
further the subsections.

[Boundaries of the plot]

@b@i@C4Boundaries of the plot

The main XPlot window (called Control) shows the datasets in a small plot,
surrounded by sliders. Two sliders are provided per axis, one selecting the
minimum value and one selecting the maximum value. E.g., if you want to see
the middle portion of the plot, set the upper horizontal slider (the minimum X
value to display) to about 1/3 of its length and set the lower horizontal
slider to 2/3 of its length.

The boundaries of the plot can furthermore be entered in the input fields,
below the small plot.

One last button, labeled `Scale Y', affects the sizing of the graph. The
button scales the Y axis to contain all points given a certain X range. The
scaling of the Y axis is performed over all active datasets (you can also
deactivate sets, see the appropriate section).

[Selecting and deselecting datasets]

@b@i@C4Selecting and deselecting datasets

When many datasets are plotted, it may be useful to deactivate (or later,
reactivate) some of the sets. The button which is labeled `(De)activate sets',
on the right hand side of the control window, starts a small window (called
the `activator'), showing an overview of the plotted sets. The names of the
active sets are prefixed with [+], the inactive sets are prefixed with [-].
Clicking on the line with a name of a dataset `toggles' the activity: an
active set becomes inactive and v.v..

Initially, all datasets are `active' (i.e., displayed).

The activator stays on-screen until you click the `dismiss' button of the
activator window.

[Making larger plots: blowups]

@b@i@C4Making larger plots: blowups

The buttons `static blowup' and `dynamic blowup' in the control window start
a `blowup' of the current plot: i.e. using the current borders and currently 
active sets. The blown up graph is dismissed by clicking in the blowup window. 
The blown up graph can be resized, e.g., to grab its contents in a paint 
program.

The difference between a static and a dynamic blowup is the following. A 
static blowup will remain to show the the plotted data even when you, e.g., 
deactivate a set or change the boundaries. A static blowup is handy when e.g. 
you want to compare one part of the data with another part: make a static plot 
of the first part, move to the second part, and compare. In contrast, a 
dynamic plot redraws its data whenever necessary; therefore, it is an 
`enlargement' of the plot in the control window.

XPlot can create an unlimited number of blowups: that way, you can
simultaneously view different sets with different boundaries in different
blowups..

[Line types of the plots]

@b@i@C4Line types of the plots

The radio buttons labelled `Line types', on the right hand side of the control
window, select the line types for the plotting of the datasets. All sets are
plotted in the same style.

The default style, `solid or circles', plots a set either with a solid line,
or with a solid line and circles on the separate points. The points are
plotted when the graph contains less than 20 points: the idea here is that the
presence of circles obfuscates a graph when more than 20 circles would be
present in the graph.

Other styles force either solid lines, solid lines with circles, or solid
lines with squares.

[Postponed or immediate plotting]

@b@i@C4Postponed or immediate plotting

The button labeled `Auto-redraw', on the right hand side of the Control
window, selects whether XPlot should redo a plot when any change occurs (e.g.,
when the boundaries are altered or when a linestyle is defined). Initially,
auto-redraw is `on'.

Setting auto-redraw to `off' is a good idea when you are plotting large
datasets. The reason for this is that the replotting of all sets (e.g., when
sliding one of the boundary sliders) may take too long. In this case, you can
disable the automatic redrawing, and `manually' redraw the plot when you are
satisfied with all necessary changes. The `manual redraw' is always done when
you press the button labeled `Redraw now'.

[Plot titles]

@b@i@C4 Plot titles

The input field labeled `Title', below the small plot on the Control window,
lets you enter a title for the plot. XPlot's title facility is restricted to
one title, which als used in blowups. You might want to define a title, make a
blowup, and dump it to say a printer using `xwd' and related programs.

[Quitting XPlot]

@b@i@C4 Quitting XPlot

The button labelled `dismiss' on the XPlot control window removes the control
window from the screen. The XPlot program will only terminate when no blowups
are on-screen. To quit XPlot, you need to remove all blowups (by clicking on
them) and to click the `dismiss' button of the control window.

[Installing XPlot]

@C4@l@b@i@cInstalling XPlot

XPlot is contained in an archive xplot-X.YY.tar.gz, available via anonymous
ftp, at the site ftp.icce.rug.nl, directory /pub/unix. Check there for newest
versions. 

Once you obtain the archive xplot-X.YY.tar.gz (X.YY being a version number,
say 1.00), unpack the archive in a `sources' directory, preferably
/usr/local/src:

@f    tar xvzf xplot-X.YY.tar.gz

The archive spills its contents into a subdirectory xplot. The actual sources
are in xplot/src. Change-dir to this directory:

@f    cd xplot/src

[Compiling XPlot]

@b@i@C4Compiling XPlot

In order to compile XPlot, you will need two additional libraries and header
files: the XForms library and header (a graphical user interface toolkit for
X) and the Fli library and header (ICCE add-ons for XForms). See the file
Makefile in the xplot/src directory for an overview of XForms ftp sites.
The Fli library is included with XPlot sources, and it built
automatically.  Not that those who want to use the Fli library in their own
project should download it from ftp://ftp.icce.rug.nl/pub/unix/libfli-X.tar.gz
beacuse it may be more up-to-date, and that packages also includes extras
(xfliman). 

When you have obtained XForms version 0.88 (or even 0.81), edit the
Makefile and adjust the macros at the top. You can specify your `bin'
directory, used for a `make install' and other things. Generally, the
Makefile won't need tweaking.

Next, try a `make tests' in the sources directory. You should see plots with a
couple of different datafiles. When you are satisfied, do a `make install':
this will copy the executable and its helpfile to their destinations.