This is release 2.1.1 of the GNU plotutils (plotting utilities) package,
including release 1.1 of GNU libplot: a function library for
two-dimensional device-independent vector graphics.  The package now has
its own Web page: http://www.gnu.org/software/plotutils/plotutils.html .

In this directory, the file INSTALL contains generic instructions dealing
with installation of a GNU package, and the file INSTALL.pkg contains
package-specific installation instructions.  Please read them in full,
as well as this file, before attempting to install the package.

Please send bug reports to <bug-gnu-utils@gnu.org>, and suggestions for
longer-range improvements to both <bug-gnu-utils@gnu.org> and the principal
author and current maintainer, Robert Maier <rsm@math.arizona.edu>.

----------------------------------------------------------------------

The contents of the plotutils package are:

1. libplot.     This is the function library for device-independent
		two-dimensional vector graphics that the programs `graph',
		`plot', and `tek2plot' (see below) are based on.  On
		systems that support DLL's (dynamically linked libraries),
		it is installed as a DLL.

		If you are a programmer, you may use this library yourself,
		to create vector graphics in many output formats.  You may
		also use it to create vector graphics animations under the
		X Window System.
		
		libplot includes functions to draw objects of many types:
		lines and polylines, circles and ellipses, circular and
		elliptic arcs, and marker symbols.  Postscript-style
		`paths' may be drawn.  There is support for color (both pen
		color and fill color for objects).

		Output formats include X11, Postscript (editable with
		the idraw drawing editor), Fig (editable with the xfig
		drawing editor), HP-GL and HP-GL/2, Tektronix, and GNU
		metafile format.  GNU metafile format may be translated
		into any of the other formats with the `plot' utility
		(see below).

		libplot includes extensive support for accurate sizing and
		positioning of text.  This includes the placement of
		subscripts and superscripts.  Its X11, Postscript, and Fig
		drivers all support the 35 standard Postscript fonts, and
		its HP-GL/2 driver supports the 45 standard PCL 5 fonts.
		In addition, all four, together with its Tektronix driver,
		support a set of 17 Hershey vector fonts.  All supported
		fonts may be arbitrarily rotated and scaled.  All fonts,
		except for symbol and dingbat fonts, use the ISO-Latin-1
		encoding (a superset of ascii; the ISO-Latin-1 support in
		the Hershey fonts is extensive but not quite complete).
		
		(Clones of the 35 standard Postscript fonts, in Type 1
		format, have been contributed by URW GmbH and are
		distributed under the GNU General Public License as part of
		this package.  See the file ./INSTALL.fonts .)

		Similarly to Postscript, libplot has the nice feature that
		user coordinates (in terms of which you express the
		location of graphical objects) may be transformed to device
		coordinates by an arbitrary affine transformation.  A stack
		of drawing states (i.e., graphics contexts) is supported
		too.

2. Programs, including the following.		

	graph.  A full-featured scientific plotting program for plotting XY
		(i.e. 2-dimensional) data.  It plots a stream of
		datapoints, in real time if possible.  There is a
		well-chosen set of command-line options for adjusting the
		visual appearance of the plot, labelling axes (with
		expressions that may include subscripts and superscripts,
		and mathematical symbols), choosing marker symbols from
		various fonts, etc.  Multiplotting is supported (a plot may
		include sub-plots, side-by-side or inset).  Filled regions
		are also supported.

		Unlike the well-known plotting program `gnuplot', `graph'
		is device-independent in the sense that its options do not
		depend on the display device the plot is destined for.
		To the maximum degree feasible, the output of `graph' will
		appear the same on all display devices.  
	
		Which display device is driven, or output format is
		produced, is specified by the `-T' option.  There are
		effectively six distinct variants of `graph', distinguished
		by the intended display device.

		graph -T X	A variant that pops up an X window on
				an X display, and draws the plot in it.  It
				is most useful on modern (X11R6+) displays,
				which can rotate and scale text
				arbitrarily.  It uses the 35 standard
				Postscript fonts.

		graph -T ps	A variant that produces EPS (encapsulated
				Postscript) output, which can be printed,
				displayed, or encapsulated in other
				documents.  Any standard page
				size is supported (letter, legal, ANSI
				sizes, ISO sizes such as a4 and a3, etc.)
				The EPS output includes annotations that 
				permit it to be edited with the freeware 
				`idraw' drawing editor, or its successor 
				`drawtool'.  

		graph -T fig	A variant that produces a plot that
				the freeware `xfig' drawing editor can edit.  
				xfig can export the plot in numerous formats,
				such as GIF, X11 bitmap, and EPS.

		graph -T hpgl	A variant that produces HP-GL (or by
				default, HP-GL/2) output.  HP-GL is the
				Hewlett-Packard Graphics Language, and
				may be printed out or plotted on a
				Hewlett-Packard LaserJet printer or plotter.
				Also many applications, e.g. CAD applications,
				can import HP-GL or HP-GL/2 figures.
				This variant supports the 45 standard PCL 5
				fonts that are built into many non-Postscript
				printers, such as LaserJets.

		graph -T tek	A variant that produces Tektronix output,
				suitable for viewing, e.g., on an X Windows
				xterm or an MS-DOS kermit doing Tektronix
				emulation.  (This variant lacks the
				Postscript fonts of the other variants
				though, like them, it has a complete set of
				vector Hershey fonts.  Also, it does not
				support filling of regions.)

		graph		The `raw' variant, which produces output in
				GNU graphics metafile format.  This is an
				enhanced version of the traditional plot(5)
				format found on some operating systems.
				The `plot' program (see below) must be used
				to convert this to another format, or
				to drive a display device.

		Of these six variants, `graph -T X', `graph -T tek', and raw
		`graph' are real-time.  That means that under some
		circumstances, they act as filters: they read data points
		from the standard input, and plot them as they are read.
		For this to happen, the abscissa and ordinate ranges of the
		plot must be specified on the command line.  (E.g., the
		user would do

			program | graph -T X -x xmin xmax -y ymin ymax

		where `program' generates a stream of data points.)
		
		All variants of `graph' will accept ascii input (the
		default), or unformatted binary input (i.e., a stream of
		floating point numbers or integers), or input in the
		`table' format produced by the program `gnuplot' (which you
		may select by specifying the `-I g' option).  Gnuplot will
		produce table-format output if you do `set terminal table';
		you can pipe gnuplot's output to any of the variants of
		graph by using the gnuplot `set output' command.  If you
		are piping to `graph -T X', by repeatedly using the gnuplot
		`set output' command you may easily produce an arbitrarily
		large number of plots in different X windows, each in a
		different style.

	plot.   This is a so-called plot filter, which takes a stream in GNU
		graphics metafile format, and either translates it to
		another format or uses it to drive a display device.

		Since this distribution includes `graph -T X', `graph -T
		ps', `graph -T fig', `graph -T hpgl', and `graph -T tek',
		all of which can drive display devices directly, `plot' is
		only occasionally useful.  It may be used, though, to
		produce graphical output in more than one format at once.
		To do this, you would pipe the output of a
		datapoint-generating program to the raw variant of `graph',
		and then use the `tee' command to direct the output of raw
		`graph', which is in metafile format, to two separate
		invocations of `plot'.
	
		Introducing an intermediate textual representation between
		graphics function calls and a display device necessarily
		forces communication to be one-way.  This is a handicap
		when positioning text strings, since information on the
		width of strings may not be available.  It is for this
		reason that the raw variant of `graph' is slightly less
		sophisticated about label positioning than the other
		variants.  For most applications, the non-raw variants of
		`graph' are preferred.

		`plot' may also be useful as a post-processor for older
		programs that produce output in the traditional plot(5)
		graphics format.

	spline. This program does spline interpolation of input data, which
		may be of arbitrary dimensionality.  That is, it takes a
		file of datapoints, and interpolates between them to
		produce an interpolated segment of the input data.  It acts
		as a filter, though usually not as a real-time one (in the
		most common mode of operation, the entire input must be
		read before any data points are output).

		The output spline is normally a cubic spline, but if a
		`tension' parameter is set to a nonzero value, the output
		spline will be a so-called spline under tension.  There is
		also support for doing cubic Bessel interpolation.  If this
		option is selected, `spline' acts as a true real-time
		filter, since cubic Bessel interpolation is local rather
		than global.
		
	ode.  This interactive program supplements the computation engine
		of `gnuplot', which will compute and plot functions, by
		providing the ability to integrate systems of ordinary
		differential equations (ODE's).  ode will solve the initial
		value problem for one or more first-order ODE's, when
		provided with an explicit expression for each equation.
		ode parses the set of equations and the set of initial
		conditions, which may be typed in manually or read from a
		file, and then produces a stream of data points that may be
		piped to any of the variants of `graph'.  If a real-time
		variant of `graph' (e.g. `graph -T X' or `graph -T tek') is
		used, the numerical solution will be displayed in real
		time, as it is generated.

		One application (certainly not the only one!) of ode is to
		graph the indefinite integrals of the sorts of function
		that gnuplot can graph.  All the primitive real-valued
		functions that are built into gnuplot are built into ode.

		For sample ode input files, see the ./ode-examples
		directory.

	tek2plot.  This is a utility program that emulates a Tektronix 4014
		terminal in the sense that it reads Tektronix commands, and
		drives any of the five sorts of graphic display device
		mentioned above, or (alternatively) produces GNU graphics
		metafile format.  It acts as a filter.

		tek2plot is useful only if you have a legacy program that
		is intended to drive a Tektronix terminal or emulator.  The
		directory ./tek2plot/teksamples includes a few files in
		Tektronix format which you may experiment with.  You may
		also experiment by piping the output of `gnuplot', if you
		have configured it to produce Tektronix-format plots, to
		these filters (the gnuplot terminal types `kc_tek40xx',
		`km_tek40xx', `tek40xx', and `vttek' all work).  tek2plot
		does an excellent job of emulating the non-interactive
		features of a Tektronix 4014, and although it does not
		support all the features supported by the Tektronix
		emulator in the MS-DOS version of kermit, it can certainly
		parse the output of the gnuplot Tektronix terminal drivers.
		
	double. This is a filter for converting, scaling and cutting
		unformatted (binary) or ascii data streams.  It is still
		under development and is not yet documented.
	
