<!-- -*-  mode: nxml -*- -->
<!--
    intro.xml: "Introduction" chapter

Copyright (C) 1994  Geoffrey Furnish and Maurice LeBrun
Copyright (C) 1999, 2000, 2001, 2002, 2003  Alan W. Irwin
Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004  Rafael Laboissiere
Copyright (C) 2003  Joao Cardoso

Redistribution and use in source (XML DocBook) and "compiled" forms
(HTML, PDF, PostScript, DVI, TeXinfo and so forth) with or without
modification, are permitted provided that the following conditions are
met:

1. Redistributions of source code (XML DocBook) must retain the
above copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.

2. Redistributions in compiled form (transformed to other DTDs,
converted to HTML, PDF, PostScript, and other formats) must
reproduce the above copyright notice, this list of conditions and
the following disclaimer in the documentation and/or other
materials provided with the distribution.

Important: THIS DOCUMENTATION IS PROVIDED BY THE PLPLOT PROJECT "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE PLPLOT PROJECT BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-->

<chapter id="intro">
  <title>Introduction</title>
  <sect1 id="plplot-plotting-library">
    <title>The PLplot Plotting Library</title>

    <para> PLplot is a library of C functions that are useful for making
    scientific plots from programs written in C, C++, Fortran95, Java, Octave, 
    Perl, Python, and Tcl/Tk. The PLplot project is being developed by a world-wide 
    team who interact via the facilities provided by SourceForge (<ulink
    url="http://sourceforge.net/projects/plplot">http://sourceforge.net/projects/plplot</ulink>)
    </para>

    <para> The PLplot library can be used to create standard x-y plots, semi-log
    plots, log-log plots, contour plots, 3D plots, shade (gray-scale and color)
    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 is full unicode support in the PLplot library, and most of the
    display drivers are capable of displaying any of the millions(?) of
    characters in the unicode standard. Those driver that are not unicode
    enabled can still display 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. A variety of output devices and 
    file formats are supported including a metafile format which can be 
    subsequently rendered to any device/file.  New devices and file formats can 
    be easily added by writing a driver routine. For example, we have recently 
    added a postscript driver with TrueType font support (PSTTF), a SVG file 
    driver and a PDF file driver. A wxWidgets interactive driver is currently 
    in development. 
    </para>

    <para>
      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:
      <blockquote>
	<para>
	  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.
	</para>
      </blockquote>
    </para>

    <para>
      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.
    </para>
    <para>
      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.
    </para>
    <para>
      Other changes include the introduction of a new color palette (cmap1)
      for smooth color shaded images (typically for 2d or 3d plots &ndash;
      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.
    </para>
    <para>
      Some of the improvements in PLplot 5.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.
    </para>
    <para>
      We have attempted to keep PLplot 5.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 <filename>plplot.h</filename> before
      linking to the new PLplot library.
    </para>
    <para>
      PLplot is currently known to work on the following systems:
      Unix/Linux, Mac OS-X and Windows XP. The Unix/Linux version is
      the best supported of these possibilities.
      The PLplot package is freely
      distributable, but <emphasis>not</emphasis> in the public domain.
      See <xref linkend="copyrights"/> for distribution criteria.
    </para>
    <para>
      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 acknowledgement
      or citation of our work, which will help us to continue improving
      PLplot.  Please direct all communication to the general PLplot
      mailing list, plplot-general@lists.sourceforge.net.
    </para>

  </sect1>
  <sect1 id="acquiring-plplot">
    <title>Getting a Copy of the PLplot Package</title>
    <para>
      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 is a SourceForge project and may be obtained by
      the usual SourceForge file release and anonymous svn repository access that is made
      available from links at
      <ulink url="http://sourceforge.net/projects/plplot">http://sourceforge.net/projects/plplot</ulink>.
    </para>
  </sect1>
  <sect1 id="installing">
    <title>Installing and Using the PLplot Library</title>
    <para>
      The installation procedure is by necessity system specific;
      installation notes for each system are provided in
      <xref linkend="os-notes"/>.
      The procedure requires that all of the routines be
      compiled and they are then usually placed in a linkable
      library.
    </para>
    <para>
      After the library has been created, you can write your main program
      to make the desired PLplot calls.  Example programs in C, C++,
      Fortran95 and Java are included as a guide.
      Plots generated from the example programs are shown
      <ulink url="http://&PLplot-website;/examples.php">here</ulink>.
    </para>
    <para>
      You will then need to compile your program and link it with the
      PLplot library(s).  See
      <xref linkend="os-notes"/> for more details).
    </para>
    <para>
      You can also use Tcl/Tk, Perl and Python scripts to generate plots
      using the PLplot libraries.  Examples of these possibilities are
      also included as a guide.
    </para>
  </sect1>
  <sect1 id="organization">
    <title>Organization of this Manual</title>
    <para>
      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 accommodated by providing lower-level
      routines which change the system defaults.  The manual first describes
      the overall process of producing a graph using the high-level
      routines (see <xref linkend="simple-graph"/>).  For a discussion of
      the underlying concepts of the plotting process and an introduction
      to some of the more complex routines (see <xref linkend="advanced"/>).
      An alphabetical list of the user-accessible PLplot functions with
      detailed descriptions is given in the reference section of the manual
      (see <xref linkend="API"/>).
    </para>
    <para>
      Because the PLplot kernel is written in C, standard C syntax is used
      in the description of each PLplot function. If you have difficulty
      interpreting the call syntax as described in this manual, please refer
      to part III, Language Bindings. This manual includes:
      C (<xref linkend="c"/>), 
      C++ (<xref linkend="cplusplus"/>), 
      Fortran 95 (<xref linkend="fortran95"/>), 
      Java (???),
      Tcl (<xref linkend="tcl"/>),
      Perl (<xref linkend="perl"/>) and
      Python (<xref linkend="python"/>). Since PLplot has a long
      history, bindings to your language of choice are probably available
      though not necessarily in the PLplot distribution. It is a good idea
      to ask around and do a quick search before rolling your own.
    </para>
    <para>
      The meaning of the function (subroutine)
      arguments is typically the same regardless of what language you are
      using to call PLplot (but there are some exceptions to this).  The
      arguments for each function are usually specified in terms of PLBOOL,
      PLINT,and PLFLT&mdash;these are the internal PLplot representations for
      logical, integer, and floating point, and are typically a zero (false) or
      non-zero (true) contained in a long, a long, and a float (or
      a LOGICAL, INTEGER, and a REAL, for Fortran programmers).  See
      <xref linkend="c"/> for more detail.
    </para>
    <para>
      Most of the output devices supported by PLplot are listed in
      <xref linkend="x-drivers"/> and <xref linkend="output-drivers"/>, 
      along with description of the device driver--PLplot interface, 
      metafile output, family files, and vt100/tek4010 emulators.
    </para>
  </sect1>
  <sect1 id="copyrights">
    <title>Copyrights</title>
    <para>
      The PLplot package may be distributed under the following terms:
    </para>
    <programlisting>
      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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
    </programlisting>
    <para>
      The text of this license is given in the file COPYING.LIB in the
      distribution directory.  Exceptions are noted below.
    </para>
    <para>
      The intent behind distributing PLplot under the LGPL is to ensure that
      it continues to evolve in a positive way, while remaining freely
      distributable. Note in particular that either open-source or
      proprietary code can be linked to LGPLed code such as PLplot, see the
      interpretation <ulink
      url="http://www.gnu.org/philosophy/license-list.html">here</ulink>.
      Full details of the LGPL are given <ulink
      url="http://www.gnu.org/copyleft/lesser.html">here</ulink>.
    </para>
    <sect2 id="additional-copyrights">
      <title>Additional Copyrights</title>
      <para>
	The start up code used in argument handling
	(<filename>utils/plrender.c</filename> and
	<filename>src/plargs.c</filename>) is partially derived from
	<filename>xterm.c</filename> of the X11R5 distribution, and its
	copyright is reproduced here:
      </para>
      <programlisting>
	******************************************************************************
	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.
	******************************************************************************
      </programlisting>
      <para>
	Any file that is explicitly marked as "public domain" is free
	from any restriction on distribution.
      </para>
      <para>
	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.
      </para>
    </sect2>
  </sect1>
  <sect1 id="credits">
    <title>Credits</title>
    <para>
      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:
    </para>
    <itemizedlist>
      <listitem>
	<para>
	  The Institute for Fusion Studies, University of Texas at Austin
	</para>
      </listitem>
      <listitem>
	<para>
	  The Scientific and Technology Agency of Japan
	</para>
      </listitem>
      <listitem>
	<para>
	  Japan Atomic Energy Research Institute
	</para>
      </listitem>
      <listitem>
	<para>
	  Duke University
	</para>
      </listitem>
      <listitem>
	<para>
	  Universite de Nice
	</para>
      </listitem>
      <listitem>
	<para>
	  National Energy Research Supercomputer Center
	</para>
      </listitem>
      <listitem>
	<para>
	  Los Alamos National Labs
	</para>
      </listitem>
    </itemizedlist>
    <para>
      Thanks are also due to the many contributors to PLplot, including:
    </para>
    <itemizedlist>
      <listitem>
	<para>
	  Tony Richardson: Creator of PLplot 2.6b, 3.0
	</para>
      </listitem>
      <listitem>
	<para>
	  Sam Paolucci (postscript driver)
	</para>
      </listitem>
      <listitem>
	<para>
	  Sam Paolucci (postscript driver)
	</para>
      </listitem>
      <listitem>
	<para>
	  Tom Rokicki (IFF driver and Amiga printer driver)
	</para>
      </listitem>
    </itemizedlist>
    <para>
      Finally, thanks to all those who submitted bug reports and other
      suggestions.
    </para>
  </sect1>
</chapter>
