\c -*-latexinfo-*-
\c intro.tex
\c Geoffrey Furnish
\c 9 May 1994

\node Introduction, Simple Use, Top, Top
\chapter{Introduction}
\cindex{PLplot Introduction}

This chapter introduces the incredibly cool PLplot scientific plotting
package.

\begin{menu}
* Library::		The PLplot Plotting Library
* Acquiring PLplot::	How to get it.
* Installing::		Installing and Using PLplot
* Organization::	Of this Manual
* Copyrights::		Copyrights and distribution status
* Credits::		To whom it's due.
\end{menu}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node Library, Acquiring PLplot, Introduction, Introduction
\section{The PLplot Plotting Library}

PLplot is a library of C functions that are useful for making scientific
plots from a program written in C, C++, or Fortran.  The PLplot library
can be used to create standard x-y plots, semilog plots, log-log plots,
contour plots, 3D plots, mesh plots, bar charts and pie charts.  Multiple
graphs (of the same or different sizes) may be placed on a single page
with multiple lines in each graph.  Different line styles, widths and
colors are supported.  A virtually infinite number of distinct area fill
patterns may be used.  There are almost 1000 characters in the extended
character set.  This includes four different fonts, the Greek alphabet and
a host of mathematical, musical, and other symbols.  The fonts can be
scaled to any desired size.  A variety of output devices are supported and
new devices can be easily added by writing a small number of device
dependent routines.

PLplot was originally developed by Sze Tan of the University of Auckland
in Fortran-77.  Many of the underlying concepts used in the PLplot
package are based on ideas used in Tim Pearson's PGPLOT package.  Sze
Tan writes:

\begin{quotation}
I'm rather amazed how far PLPLOT has travelled given its origins etc. I
first used PGPLOT on the Starlink VAX computers while I was a graduate
student at the Mullard Radio Astronomy Observatory in Cambridge from
1983-1987. At the beginning of 1986, I was to give a seminar within the
department at which I wanted to have a computer graphics demonstration
on an IBM PC which was connected to a completely non-standard graphics
card. Having about a week to do this and not having any drivers for the
card, I started from the back end and designed PLPLOT to be such that
one only needed to be able to draw a line or a dot on the screen in
order to do arbitrary graphics.  The application programmer's interface
was made as similar as possible to PGPLOT so that I could easily port my
programs from the VAX to the PC.  The kernel of PLPLOT was modelled on
PGPLOT but the code is not derived from it.
\end{quotation}

The C version of PLplot was developed by Tony Richardson on a
Commodore Amiga.  In the process, several of the routines were
rewritten to improve efficiency and some new features added.  The
program structure was changed somewhat to make it easier to
incorporate new devices.  Additional features were added to allow
three-dimensional plotting and better access to low-level routines.

PLplot 5.0 is a continuation of our work on PLplot 4.0, which never got
widely distributed.  It became clear during the work on 4.0 that in
order to support an interactive driver under Unix (using Tcl/Tk), many
additions to the basic capabilities of the package were needed.  So
without stopping to fully document and bug-fix the 4.0 additions, work
on 5.0 was begun.  The result is that a very capable PLplot-based widget
for the Tk toolkit has been written.  This widget can manipulate the
plot (zoom/pan, scale, orient, change colors), as well dump it to any
supported device.  There are help menus and user customization options.
These are still in the process of being documented.

Other changes include the introduction of a new color palette (cmap1)
for smooth color shaded images (typically for 2d or 3d plots -- in which
color represents function intensity), support for color fill plots, and
lots more cool stuff.  The manual has been rewritten in LaTeXinfo, so
that there is now a printed version and an online (info) version of the
document.  The manual is still in a state of flux and will be fleshed
out in more detail in later updates. 

PLplot 4.0 was primarily the result of efforts by Maurice LeBrun and
Geoff Furnish of University of Texas at Austin to extend and improve
the previous work (PLplot 2.6b and 3.0, by Tony Richardson).  PLplot
4.0 is currently used as the main graphics engine for TPC (Toroidal
Particle Code), a large plasma simulation code developed at the IFS
\cite{lebrun89a}.  During this work we have found that PLplot compares
well with ``heavier'' packages (read: expensive, slow) and is an
excellent choice for scientists seeking an inexpensive (or free) but
high quality graphics package that runs on many different computing
platforms.

Some of the improvements in PLplot 4.0 include: the addition of
several new routines to enhance usage from Fortran and design of a
portable C to Fortran interface.  Additional support was added for
coordinate mappings in contour plots and some bugs fixed.  New
labelling options were added.  The font handling code was made more
flexible and portable.  A portable PLplot metafile driver and renderer
was developed, allowing one to create a generic graphics file and do
the actual rendering later (even on a different system).  The ability
to create family output files was added.  The internal code structure
was dramatically reworked, with elimination of global variables (for a
more robust package), the drivers rewritten to improve consistency,
and the ability to maintain multiple output streams added.  An XFig
driver was added.  Other contributions include Clair Nielsen's (LANL)
X-window driver (very nice for high-speed color graphics) and
tektronix file viewer.  At present, Maurice LeBrun and Geoff Furnish
are the active developers and maintainers of PLplot.

We have attempted to keep PLplot 4.0 backward compatible with previous
versions of PLplot.  However, some functions are now obsolete, and
many new ones have been added (e.g.  new contouring functions,
variable get/set routines, functions that affect label appearance).
Codes written in C that use PLplot must be recompiled including the
new header file (\code{plplot.h}) before linking to the new PLplot
library.

PLplot is currently known to work on the following systems: SUNOS,
HP-UX, A/IX, DG/UX, UNICOS, Ultrix, VMS, Amiga/Exec, MS-DOS, OS/2, and
NeXT, with more expected.  The PLplot package is freely distributable,
but {\em not\/} in the public domain.  See section \ref{sec:copyrights} for
distribution criteria.

We welcome suggestions on how to improve this code, especially in the
form of user-contributed enhancements or bug fixes.  If PLplot is used
in any published papers, please include an acknowledgment or citation
of our work, which will help us to continue improving PLplot.  Please
direct all communication to:

\begin{tex}
\begin{tabbing}
01234567\=
	89012345678901234567890123456789\= \kill
	\>Dr. Maurice LeBrun		\>mjl@fusion.ph.utexas.edu\\
	\>Institute for Fusion Studies	\>University of Texas\\
\\
	\>Geoff Furnish			\>furnish@fusion.ph.utexas.edu\\
	\>Institute for Fusion Studies	\>University of Texas\\
\end{tabbing}
\end{tex}
\begin{ifinfo}
	Dr. Maurice LeBrun		mjl@dino.ph.utexas.edu 
	Institute for Fusion Studies	University of Texas

	Geoffrey Furnish		furnish@dino.ph.utexas.edu
	Institute for Fusion Studies	University of Texas
\end{ifinfo}

The original version of this manual was written by Sze Tan.

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node Acquiring PLplot, Installing, Library, Introduction
\section{Getting a copy of the PLplot package}

At present, the only mechanism we are providing for distribution of the
PLplot is by electronic transmission over the Internet.  We encourage
others to make it available to users without Internet access.  PLplot
may be obtained by \code{ftp} from \code{dino.ph.utexas.edu}
(128.83.179.86).  Login as user \code{anonymous}, set file transfer type
to binary, and get the newest PLplot archive in the \code{plplot/}
subdirectory.  We will provide PLplot in both \code{zip} and \code{tar.gz}
archives; get whichever one you prefer.\refill

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node Installing, Organization, Acquiring PLplot, Introduction
\section{Installing and Using the PLplot Library}

OLD DOCS, NEEDS UPDATING!

The installation procedure is by necessity system specific;
installation notes for each system are provided in Appendix
\ref{ap:sys}.  The procedure requires that all of the routines be
compiled and they are then usually placed in a linkable library.

After the library has been created, you can write your main program to
make the desired PLplot calls.  Example programs in both C and Fortran
are included as a guide (if calling from C, you must include
\code{plplot.h} into your program; see Appendix \ref{ap:lang} for more
details).  Plots generated from the example programs are shown at the
end of this work.\refill

You will then need to compile your program and link it with the PLplot
library(s).  Again, please refer to the documentation specific to your
system for this.  Note that there may be more than one library
available to link with, such as single or double precision, with or
without X window libraries, IEEE floating point or Motorola FFP, etc.
Make sure you link to the correct one for your program.

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node Organization, Credits, Installing, Introduction
\section{Organization of this Manual}

OLD DOCS, NEEDS UPDATING!

The PLplot library has been designed so that it is easy to write programs
producing graphical output without having to set up large numbers of
parameters.  However, more precise control of the results may be
necessary, and these are accomodated by providing lower-level routines
which change the system defaults.  The manual first describs the overall
process of producing a graph using the high-level routines (\pxref{Simple
Plot}).  For a discussion of the underlying concepts of the plotting
process and an introduction to some of the more complex routines
\pxref{Advanced Use}.  An alphabetical list of the user-accessible PLplot
functions with detailed descriptions is given in the reference section of
the manual (\pxref{API}).\refill

Because the PLplot kernel is written in C, standard C syntax is used
in the description of each PLplot function.  The C and Fortran
language interfaces are discussed in Appendix \ref{ap:lang}; look
there if you have difficulty interpreting the call syntax as described
in this manual.  The meaning of function (subroutine) arguments is
typically the same regardless of whether you are calling from C or
Fortran (but there are some exceptions to this).  The arguments for
each function are usually specified in terms of PLFLT and PLINT ---
these are the internal PLplot representations for integer and floating
point, and are typically a long and a float (or an INTEGER and a REAL,
for Fortran programmers).  See Appendix \ref{ap:lang} for more detail.

Also, you can use PLplot from C++ just as you would from C.  No
special classes are available at this time, just use it as any other
procedural type library.  Simply include \code{plplot.h}, and invoke as
you would from C.

The output devices supported by PLplot are listed in Appendix
\ref{ap:dev}, along with description of the device driver--PLplot
interface, metafile output, family files, and vt100/tek4010 emulators.
In Appendix\ref{ap:sys} the usage and installation for each system
supported by PLplot is described (not guaranteed to be entirely
up-to-date; check the release notes to be sure).

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node Copyrights, Credits, Organization, Introduction
\section{Copyrights}
\label{sec:copyrights}

The PLplot package may be distributed under the following terms:

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

    This library 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
    Library General Public License for more details.

    You should have received a copy of the GNU Library General Public
    License along with this library; if not, write to the Free
    Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

The text of this license is given in the file COPYING.LIB in the
distribution directory.  Exceptions are noted below.

The intent behind distributing PLplot under the LGPL is to ensure that it
continues to evolve in a positive way, while remaining freely
distributable.  The package is considered a "library" even though there
are associated programs, such as plrender, pltek, plserver, and pltcl.
The ties between these programs and the library are so great that I
consider them as part of the library, so distribution under the terms of
the LGPL makes sense.  Software developers are allowed and encouraged to
use PLplot as an integral part of their product, even a commercial
product.  Under the conditions of the LGPL, however, the PLplot source
code must remain freely available, including any modifications you make to
it (if you distribute a program based on the modified library).  Please
read the full license for more info.


Additional Copyrights
---------------------

The startup code used in argument handling (utils/plrender.c and
src/plargs.c) is partially derived from "xterm.c" of the X11R5
distribution, and its copyright is reproduced here:

******************************************************************************
Copyright 1987, 1988 by Digital Equipment Corporation, Maynard, Massachusetts,
and the Massachusetts Institute of Technology, Cambridge, Massachusetts.

                        All Rights Reserved

Permission to use, copy, modify, and distribute this software and its 
documentation for any purpose and without fee is hereby granted, 
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in 
supporting documentation, and that the names of Digital or MIT not be
used in advertising or publicity pertaining to distribution of the
software without specific, written prior permission.  

DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
SOFTWARE.
******************************************************************************

Any file that is explicitly marked as "public domain" is free from any
restriction on distribution.  

Any file that has a explicit copyright notice may be distributed under
the terms of both the LGPL and whatever stated conditions accompany the
copyright.

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node Credits, , Copyrights, Introduction
\section{Credits}
\label{sec:credits}

PLplot 5.0 was created through the effort of many individuals and
funding agencies.  We would like to acknowledge the support (financial
and otherwise) of the following institutions:

\c \begin{description}
\c \item	The Institute for Fusion Studies, University of Texas at Austin
\c \item	The Scientific and Technology Agency of Japan
\c \item	Japan Atomic Energy Research Institute
\c \item	Duke University
\c \item	Universite de Nice
\c \item	National Energy Research Supercomputer Center
\c \item	Los Alamos National Labs
\c \end{description}

Thanks are also due to the many contributors to PLplot, including:

\c \begin{description}
\c \item Tony Richardson: Creator of PLplot 2.6b, 3.0
\c \item Sam Paolucci (postscript driver)
\c \item Clair Nielsen (X driver and tektronix file viewer)
\c \item Tom Rokicki (IFF driver and Amiga printer driver)
\c \end{description}

Finally, thanks to all those who submitted bug reports and other
suggestions.

