================================================================
This is the documentation for xgr.
John Kerl
kerl at math dot arizona dot edu
2005-07-26
================================================================

================================================================
ORIGIN

xgr is a simple program to display one-dimensional numerical data on screen.
Its companion program is xfim, which displays two-dimensional numerical data.

It has fewer features than, say, Matlab's plotter.  It is nothing more than a
quick hack.  However, it has the following benefits:

*	Since I wrote the code, I can create precisely those features I want.

*	I/O formats are what I want them to be.

*	xgr starts up quickly, unlike Matlab.

*	It can read from standard input, and is scriptable.

*	I can compile and run xgr on any machine with a C compiler and X11.

================================================================
FILE FORMAT

xgr takes as input one or more vectors, and creates an X/Y plot of them.
The user specifies whether:

*	the first column of the data file is the abscissa and the rest are
	ordinates (default), or

*	all columns of the data file are ordinates and the abscissa is taken
	from the line number (-n command-line option).

For example, suppose an input data file is as follows:

1 2
3 7
5 9

With -n, xgr plots two lines:

	(1,1) (2,3) (3,5), and
	(1,2) (2,7) (3,9).

Without -n, xgr plots one line:

	(1,2) (3,7) (5,9).

Axes are drawn in black, but no ticks or labels are written to the display
window.  However, display boundaries are printf'ed to the console, as a
consolation.

By default, input data is ASCII in the format described above.  With the -rb
option, the file is treated as a single-precision floating-point binary vector.
With the -cb option, the file is treated as a single-precision floating-binary
pair of vectors, e.g. nominally real and imaginary parts of a complex number.
Binary files are taken to be in network (big-endian) byte order.

================================================================
MOUSE NAVIGATION

*	Left-click and release a point on the screen to see its coordinates
	printf'ed to the console.

*	Left-click and drag a rectangle (xgr unfortunately does not do
	rubber-banding) to zoom in.

*	Right-click to zoom out.

*	Middle click to restore the original data dimensions.

================================================================
COMMAND-LINE ARGUMENTS

Usage:  xgr [ options ... ] {data file name}
Options include:
  -c initial upper left corner x & y location in pixels
  -w init. window width in pixels
  -h init. window height in pixels
  -xb {low x} {high x} as floats
  -yb {low y} {high y} as floats
  -rv (reverse video):  Invert background color.
  -n  to take X coordinate implicitly from line number,
      rather than from first column of data file.
  -sort:  Sort input data on X coordinate before plotting.
  --help: print this message.
  -a:   ASCII input (default)
  -rb:  Real binary input
  -cb:  Complex binary input
Use "-" as file name, or omit, to read from stdin.

================================================================
EXAMPLES

Include screenshots here.