<!-- -*-  mode: nxml -*- -->
<!--
    api.xml: "The Common API for PLplot" chapter

Copyright (C) 1994  Geoffrey Furnish and Maurice LeBrun
Copyright (C) 1999-2013  Alan W. Irwin
Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004  Rafael Laboissiere
Copyright (C) 2003  Joao Cardoso
Copyright (C) 2004, 2007  Andrew Ross
Copyright (C) 2007  Hazen Babcock
Copyright (C) 2008, 2009  Hezekiah M. Carty

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="API">
  <title>The Common API for PLplot</title>

  <para>
    The purpose of this chapter is to document the API for every PLplot
    function that should be available across all PLplot language bindings.
    This common API between the various languages constitutes the
    most important part of the PLplot API that programmers need to know.
    Note that in C, these common API routines have a special 
    <quote>c_</quote> prefix name assigned to them in 
    <filename>plplot.h</filename>.
  </para>

  <para>
    What follows is a list of all common API functions of the latest
    PLplot version with their arguments except for obsolete/deprecated API 
    functions which are listed in <xref linkend="API-OBSOLETE"/>. The
    following information is provided for each function:
    <orderedlist>
      <listitem>
	<para>
	  The function name and a brief description.
	</para>
      </listitem>
      <listitem>
	<para>
	  The function as it would be called from C.
	</para>
      </listitem>
      <listitem>
	<para>
	  A complete description of the function.
	</para>
      </listitem>
      <listitem>
	<para>
	  A description of each argument that the function takes.
	</para>
      </listitem>
      <listitem>
	<para>
	  The redacted argument form of the function, currently used 
	  by the programming languages Fortran95, Python, Java and 
	  Perl, as well as any language specific variations that 
	  might occur on the general calling scheme described in 
	  the following paragraph.
	</para>
      </listitem>
      <listitem>
	<para>
	  A list of PLplot examples that demonstrate how to use
	  the function.
	</para>
      </listitem>
    </orderedlist>
    Additional PLplot API specialized for each language binding is 
    documented in <xref linkend="API-C"/> and subsequent chapters.
  </para>

  <para>
    The general calling scheme for the other languages supported
    by PLplot is as follows, using the function 
    <function>plline</function> as an example.
    <itemizedlist>
      <listitem>
	<para>
	  C: <function>plline(n,x,y)</function>
	</para>
      </listitem>
      <listitem>
	<para>
	  F95: <function>plline(x,y)</function>
	</para>
      </listitem>
      <listitem>
	<para>
	  C++: <function>pls->line(n,x,y)</function>
	</para>
      </listitem>
      <listitem>
	<para>
	  Java: <function>pls.line(x,y)</function>
	</para>
      </listitem>
      <listitem>
	<para>
	  Perl/PDL: <function>plline($x,$y)</function>
	</para>
      </listitem>
      <listitem>
	<para>
	  Python: <function>plline(x,y)</function>
	</para>
      </listitem>
      <listitem>
	<para>
	  Tcl/Tk: <function>$w cmd plline $n x y</function>
	</para>
      </listitem>
    </itemizedlist>
    Note that in some languages the argument n (which specifies
    the length of the arrays x and y) is not necessary, this
    is what we refer to above as the <quote>redacted argument
    form</quote> of the function.
  </para>

  <sect1 id="pl_setcontlabelformat" renderas="sect3">
    <title><function>pl_setcontlabelformat</function>: Set
    format of numerical label for contours</title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>pl_setcontlabelformat</function>
	  </funcdef>
	  <paramdef><parameter>lexp</parameter></paramdef>
	  <paramdef><parameter>sigdig</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set format of numerical label for contours.
    </para>
    <!-- TODO: units unclear - have to be documented -->

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>lexp</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    If the contour numerical label is greater than 10^(lexp) or less
	    than 10^(-lexp), then the
	    exponential format is used.  Default value of lexp is 4.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>sigdig</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of significant digits.  Default value is 2.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>pl_setcontlabelformat(lexp, sigdig)</function>
    </para>

    <para>
      This function is used example 9.
    </para>

  </sect1>

  <sect1 id="pl_setcontlabelparam" renderas="sect3">
    <title><function>pl_setcontlabelparam</function>: Set parameters of
    contour labelling other than format of numerical label</title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>pl_setcontlabelparam</function>
	  </funcdef>
	  <paramdef><parameter>offset</parameter></paramdef>
	  <paramdef><parameter>size</parameter></paramdef>
	  <paramdef><parameter>spacing</parameter></paramdef>
	  <paramdef><parameter>active</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set parameters of
      contour labelling other than those handled by &pl_setcontlabelformat;.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>offset</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Offset of label from contour line (if set to 0.0, labels are
	    printed on the lines).  Default value is 0.006.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>size</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Font height for contour labels (normalized).  Default value is 0.3.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>spacing</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Spacing parameter for contour labels.  Default value is 0.1.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>active</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Activate labels.  Set to 1 if you want contour labels on.
	    Default is off (0).
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>pl_setcontlabelparam(offset, size, spacing, active)</function>
    </para>

    <para>
      This function is used in example 9.
    </para>

  </sect1>

  <sect1 id="pladv" renderas="sect3">
    <title><function>pladv</function>: Advance the (sub-)page</title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>pladv</function>
	  </funcdef>
	  <paramdef><parameter>page</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Advances to the next subpage if
      <literal><parameter>sub</parameter>=0</literal>, performing a page
      advance if there are no remaining subpages on the current page.  If
      subpages aren't being used, <literal>&pladv;(0)</literal> will
      always advance the page.  If
      <literal><parameter>page</parameter>&gt;0</literal>, PLplot switches
      to the specified subpage.  Note that this allows you to overwrite a
      plot on the specified subpage; if this is not what you intended, use
      &pleop; followed by &plbop; to first advance the page.  This routine
      is called automatically (with
      <literal><parameter>page</parameter>=0</literal>) by &plenv;, but if
      &plenv; is not used, &pladv; must be called after initializing PLplot
      but before defining the viewport.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>page</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Specifies the subpage number (starting from 1 in the top left
	    corner and increasing along the rows) to which to advance.  Set
	    to zero to advance to the next subpage (or to the next page
            if subpages are not being used).
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>pladv(page)</function>
    </para>

    <para>
      This function is used in examples 1,2,4,6-12,14-18,20,21,23-27,29,31.
    </para>

  </sect1>

  <sect1 id="plarc" renderas="sect3">
    <title>
      <function>plarc</function>: Draw a circular or elliptical arc
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plarc</function>
	  </funcdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>a</parameter></paramdef>
	  <paramdef><parameter>b</parameter></paramdef>
	  <paramdef><parameter>angle1</parameter></paramdef>
	  <paramdef><parameter>angle2</parameter></paramdef>
	  <paramdef><parameter>rotate</parameter></paramdef>
	  <paramdef><parameter>fill</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Draw a possibly filled arc centered at
      <literal><parameter>x</parameter></literal>,
      <literal><parameter>y</parameter></literal> with semimajor axis 
      <literal><parameter>a</parameter></literal> and semiminor axis 
      <literal><parameter>b</parameter></literal>, starting at 
      <literal><parameter>angle1</parameter></literal> and ending at 
      <literal><parameter>angle2</parameter></literal>.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    X coordinate of arc center.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Y coordinate of arc center.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>a</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Length of the semimajor axis of the arc.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>b</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Length of the semiminor axis of the arc.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>angle1</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Starting angle of the arc relative to the semimajor axis.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>angle2</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Ending angle of the arc relative to the semimajor axis.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>rotate</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Angle of the semimajor axis relative to the X-axis.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>fill</parameter>
	  (<literal>PLBOOL</literal>, input)
	</term>
	<listitem>
	  <para>
	    Draw a filled arc.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plarc(x, y, a, b, angle1, angle2, rotate, fill)</function>
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in examples 3 and 27.
    </para>

  </sect1>

  <sect1 id="plaxes" renderas="sect3">
    <title>
      <function>plaxes</function>: Draw a box with axes, etc. with arbitrary
      origin
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plaxes</function>
	  </funcdef>
	  <paramdef><parameter>x0</parameter></paramdef>
	  <paramdef><parameter>y0</parameter></paramdef>
	  <paramdef><parameter>xopt</parameter></paramdef>
	  <paramdef><parameter>xtick</parameter></paramdef>
	  <paramdef><parameter>nxsub</parameter></paramdef>
	  <paramdef><parameter>yopt</parameter></paramdef>
	  <paramdef><parameter>ytick</parameter></paramdef>
	  <paramdef><parameter>nysub</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Draws a box around the currently defined viewport with arbitrary
      world-coordinate origin specified by
      <literal><parameter>x0</parameter></literal> and
      <literal><parameter>y0</parameter></literal>
      and labels it with world coordinate values appropriate to the
      window.  Thus &plaxes; should only be called after defining both
      viewport and window.  The character strings
      <literal><parameter>xopt</parameter></literal> and
      <literal><parameter>yopt</parameter></literal> specify how the box
      should be drawn as described below.  If ticks and/or subticks are to
      be drawn for a particular axis, the tick intervals and number of
      subintervals may be specified explicitly, or they may be defaulted by
    setting the appropriate arguments to zero. </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>x0</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    World X coordinate of origin.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y0</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    World Y coordinate of origin.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xopt</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to character string specifying options for horizontal
	    axis.  The string can include any combination of the following
	    letters (upper or lower case) in any order:
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal>a</literal>: Draws axis, X-axis is horizontal
		  line (<literal>y=0</literal>), and Y-axis is vertical
		  line (<literal>x=0</literal>).
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>b</literal>: Draws bottom (X) or left (Y) edge
		  of frame.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>c</literal>: Draws top (X) or right (Y) edge of
		  frame.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>d</literal>: Plot labels as date / time. 
		  Values are assumed to be seconds since the epoch 
		  (as used by gmtime).
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>f</literal>:  Always use fixed point numeric labels.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>g</literal>: Draws a grid at the major tick
		  interval.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>h</literal>: Draws a grid at the minor tick
		  interval.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>i</literal>: Inverts tick marks, so they are
		  drawn outwards, rather than inwards.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>l</literal>: Labels axis logarithmically.  This
		  only affects the labels, not the data, and so it is
		  necessary to compute the logarithms of data points before
		  passing them to any of the drawing routines.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>m</literal>: Writes numeric labels at major tick
		  intervals in the unconventional location (above box for
		  X, right of box for Y).
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>n</literal>: Writes numeric labels at major tick
		  intervals in the conventional location (below box for X,
		  left of box for Y).
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>o</literal>: Use custom labelling function to
		  generate axis label text.  The custom labelling function
		  can be defined with the &plslabelfunc; command.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>s</literal>: Enables subticks between major
		  ticks, only valid if <literal>t</literal> is also
		  specified.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>t</literal>: Draws major ticks.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>u</literal>: Exactly like "b" except don't draw edge line.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>w</literal>: Exactly like "c" except don't draw edge line.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>x</literal>: Exactly like "t" (including the side effect of
		  the numerical labels for the major ticks) except exclude drawing the
		  major and minor tick marks.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xtick</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    World coordinate interval between major ticks on the x axis.
	    If it is set to zero, PLplot automatically generates a suitable
	    tick interval.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nxsub</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of subintervals between major x axis ticks for minor
	    ticks.  If it is set to zero, PLplot automatically generates a
	    suitable minor tick interval.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>yopt</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to character string specifying options for vertical
	    axis.  The string can include any combination of the letters
	    defined above for
	    <literal><parameter>xopt</parameter></literal>, and in addition
	    may contain:
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal>v</literal>: Write numeric labels for vertical
		  axis parallel to the base of the graph, rather than
		  parallel to the axis.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ytick</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    World coordinate interval between major ticks on the y axis.
	    If it is set to zero, PLplot automatically generates a suitable
	    tick interval.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nysub</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of subintervals between major y axis ticks for minor
	    ticks.  If it is set to zero, PLplot automatically generates a
	    suitable minor tick interval.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plaxes(x0, y0, xopt, xtick, nxsub, yopt, ytick, nysub)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: <function>plaxes(x0, y0, xtick, nxsub, ytick, nysub, xopt, yopt)</function>
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is not used in any examples.
    </para>

  </sect1>

  <sect1 id="plbin" renderas="sect3">
    <title>
      <function>plbin</function>: Plot a histogram from binned data
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plbin</function>
	  </funcdef>
	  <paramdef><parameter>nbin</parameter></paramdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>opt</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Plots a histogram consisting of
      <literal><parameter>nbin</parameter></literal> bins.  The value
      associated with the <literal>i</literal>'th bin is placed in
      <literal><parameter>x</parameter>[i]</literal>, and the number of
      points in the bin is placed in
      <literal><parameter>y</parameter>[i]</literal>.  For proper
      operation, the values in
      <literal><parameter>x</parameter>[i]</literal> must form a strictly
      increasing sequence.  By default,
      <literal><parameter>x</parameter>[i]</literal> is the left-hand edge
      of the <literal>i</literal>'th bin. If
      <literal><parameter>opt</parameter>=PL_BIN_CENTRED</literal> is
      used, the bin boundaries are placed midway between the values in the
      <literal><parameter>x</parameter></literal> array.  Also see &plhist;
      for drawing histograms from unbinned data.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>nbin</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of bins (i.e., number of values in
	    <literal><parameter>x</parameter></literal> and
	    <literal><parameter>y</parameter></literal> arrays.)
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array containing values associated with bins.  These
	    must form a strictly increasing sequence.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array containing number of points in bin.  This is a
	    <literal>PLFLT</literal> (instead of <literal>PLINT</literal>)
	    array so as to allow histograms of probabilities, etc.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>opt</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Is a combination of several flags:
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=PL_BIN_DEFAULT</literal>:
		  The <literal><parameter>x</parameter></literal> represent the lower
		  bin boundaries, the outer bins are expanded to fill up the
		  entire x-axis and bins of zero height are simply drawn.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=PL_BIN_CENTRED|...</literal>:
		  The bin boundaries are to be midway between the
		  <literal><parameter>x</parameter></literal> values. If the
		  values in <literal><parameter>x</parameter></literal> are
		  equally spaced, the values are the center values of the bins.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=PL_BIN_NOEXPAND|...</literal>:
		  The outer bins are drawn with equal size as the ones inside.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=PL_BIN_NOEMPTY|...</literal>:
		  Bins with zero height are not drawn (there is a gap for
		  such bins).
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plbin(x, y, opt)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: <function>plbin(nbin, x, y, opt)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Python: <function>plbin(nbin, x, y, opt)</function>
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is not used in any examples.
    </para>


  </sect1>

  <sect1 id="plbop" renderas="sect3">
    <title><function>plbop</function>: Begin a new page</title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plbop</function>
	  </funcdef>
	  <paramdef></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>
    <para>
      Begins a new page.  For a file driver, the output file is opened if
      necessary.  Advancing the page via &pleop; and &plbop; is useful when
      a page break is desired at a particular point when plotting to
      subpages.  Another use for &pleop; and &plbop; is when plotting pages
      to different files, since you can manually set the file name
      by calling &plsfnam; after the call to &pleop;.
      (In fact some drivers may only support a single page per file, making
      this a necessity.)  One way to handle this case automatically is to
      page advance via &pladv;, but enable familying (see &plsfam;) with a
      small limit on the file size so that a new family member file will be
      created on each page break.
    </para>

    <para>
      Redacted form: <function>plbop()</function>
    </para>

    <para>
      This function is used in examples 2,20.
    </para>

  </sect1>

  <sect1 id="plbox" renderas="sect3">
    <title><function>plbox</function>: Draw a box with axes, etc</title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plbox</function>
	  </funcdef>
	  <paramdef><parameter>xopt</parameter></paramdef>
	  <paramdef><parameter>xtick</parameter></paramdef>
	  <paramdef><parameter>nxsub</parameter></paramdef>
	  <paramdef><parameter>yopt</parameter></paramdef>
	  <paramdef><parameter>ytick</parameter></paramdef>
	  <paramdef><parameter>nysub</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Draws a box around the currently defined viewport, and labels it with
      world coordinate values appropriate to the window.  Thus &plbox;
      should only be called after defining both viewport and window.  The
      character strings <literal><parameter>xopt</parameter></literal> and
      <literal><parameter>yopt</parameter></literal> specify how the box
      should be drawn as described below.  If ticks and/or subticks are to
      be drawn for a particular axis, the tick intervals and number of
      subintervals may be specified explicitly, or they may be defaulted by
      setting the appropriate arguments to zero.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>xopt</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to character string specifying options for horizontal
	    axis.  The string can include any combination of the following
	    letters (upper or lower case) in any order:
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal>a</literal>: Draws axis, X-axis is horizontal
		  line (<literal>y=0</literal>), and Y-axis is vertical
		  line (<literal>x=0</literal>).
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>b</literal>: Draws bottom (X) or left (Y) edge
		  of frame.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>c</literal>: Draws top (X) or right (Y) edge of
		  frame.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>d</literal>: Plot labels as date / time. 
		  Values are assumed to be seconds since the epoch 
		  (as used by gmtime).
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>f</literal>:  Always use fixed point numeric labels.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>g</literal>: Draws a grid at the major tick
		  interval.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>h</literal>: Draws a grid at the minor tick
		  interval.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>i</literal>: Inverts tick marks, so they are
		  drawn outwards, rather than inwards.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>l</literal>: Labels axis logarithmically.  This
		  only affects the labels, not the data, and so it is
		  necessary to compute the logarithms of data points before
		  passing them to any of the drawing routines.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>m</literal>: Writes numeric labels at major tick
		  intervals in the unconventional location (above box for
		  X, right of box for Y).
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>n</literal>: Writes numeric labels at major tick
		  intervals in the conventional location (below box for X,
		  left of box for Y).
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>o</literal>: Use custom labelling function to
		  generate axis label text.  The custom labelling function
		  can be defined with the &plslabelfunc; command.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>s</literal>: Enables subticks between major
		  ticks, only valid if <literal>t</literal> is also
		  specified.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>t</literal>: Draws major ticks.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>u</literal>: Exactly like "b" except don't draw edge line.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>w</literal>: Exactly like "c" except don't draw edge line.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>x</literal>: Exactly like "t" (including the side effect of
		  the numerical labels for the major ticks) except exclude drawing the
		  major and minor tick marks.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xtick</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    World coordinate interval between major ticks on the x axis.
	    If it is set to zero, PLplot automatically generates a suitable
	    tick interval.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nxsub</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of subintervals between major x axis ticks for minor
	    ticks.  If it is set to zero, PLplot automatically generates a
	    suitable minor tick interval.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>yopt</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to character string specifying options for vertical
	    axis.  The string can include any combination of the letters
	    defined above for
	    <literal><parameter>xopt</parameter></literal>, and in addition
	    may contain:
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal>v</literal>: Write numeric labels for vertical
		  axis parallel to the base of the graph, rather than
		  parallel to the axis.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ytick</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    World coordinate interval between major ticks on the y axis.
	    If it is set to zero, PLplot automatically generates a suitable
	    tick interval.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nysub</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of subintervals between major y axis ticks for minor
	    ticks.  If it is set to zero, PLplot automatically generates a
	    suitable minor tick interval.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plbox(xopt, xtick, nxsub, yopt, ytick, nysub)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: <function>plbox(xtick, nxsub, ytick, nysub, xopt, yopt)</function>
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in examples 1,2,4,6,6-12,14-18,21,23-26,29.
    </para>

  </sect1>

  <sect1 id="plbox3" renderas="sect3">
    <title>
      <function>plbox3</function>: Draw a box with axes, etc, in 3-d
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plbox3</function>
	  </funcdef>
	  <paramdef><parameter>xopt</parameter></paramdef>
	  <paramdef><parameter>xlabel</parameter></paramdef>
	  <paramdef><parameter>xtick</parameter></paramdef>
	  <paramdef><parameter>nxsub</parameter></paramdef>
	  <paramdef><parameter>yopt</parameter></paramdef>
	  <paramdef><parameter>ylabel</parameter></paramdef>
	  <paramdef><parameter>ytick</parameter></paramdef>
	  <paramdef><parameter>nysub</parameter></paramdef>
	  <paramdef><parameter>zopt</parameter></paramdef>
	  <paramdef><parameter>zlabel</parameter></paramdef>
	  <paramdef><parameter>ztick</parameter></paramdef>
	  <paramdef><parameter>nzsub</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>
    <para>
      Draws axes, numeric and text labels for a three-dimensional surface
      plot.  For a more complete description of three-dimensional plotting
      see <xref linkend="tri-d-plots"/>.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>xopt</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to character string specifying options for the x axis.
	    The string can include any combination of the following letters
	    (upper or lower case) in any order:
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal>b</literal>: Draws axis at base, at height
		  <literal>z=<parameter>zmin</parameter></literal> where
		  <literal><parameter>zmin</parameter></literal> is defined
		  by call to &plw3d;.  This character must be specified in
		  order to use any of the other options.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>f</literal>: Always use fixed point numeric labels.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>i</literal>: Inverts tick marks, so they are
		  drawn downwards, rather than upwards.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>l</literal>: Labels axis logarithmically.  This
		  only affects the labels, not the data, and so it is
		  necessary to compute the logarithms of data points before
		  passing them to any of the drawing routines.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>n</literal>: Writes numeric labels at major tick
		  intervals.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>o</literal>: Use custom labelling function to
		  generate axis label text.  The custom labelling function
		  can be defined with the &plslabelfunc; command.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>s</literal>: Enables subticks between major
		  ticks, only valid if <literal>t</literal> is also
		  specified.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>t</literal>: Draws major ticks.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>u</literal>: If this is specified, the text
		  label for the axis is written under the axis.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xlabel</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to character string specifying text label for the x
	    axis.  It is only drawn if <literal>u</literal> is in the
	    <literal><parameter>xopt</parameter></literal> string.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xtick</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    World coordinate interval between major ticks on the x axis.
	    If it is set to zero, PLplot automatically generates a suitable
	    tick interval.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nxsub</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of subintervals between major x axis ticks for minor
	    ticks.  If it is set to zero, PLplot automatically generates a
	    suitable minor tick interval.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>yopt</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to character string specifying options for the y axis.
	    The string is interpreted in the same way as
	    <literal><parameter>xopt</parameter></literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ylabel</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to character string specifying text label for the y
	    axis.  It is only drawn if <literal>u</literal> is in the
	    <literal><parameter>yopt</parameter></literal> string.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ytick</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    World coordinate interval between major ticks on the y axis.
	    If it is set to zero, PLplot automatically generates a suitable
	    tick interval.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nysub</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of subintervals between major y axis ticks for minor
	    ticks.  If it is set to zero, PLplot automatically generates a
	    suitable minor tick interval.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>zopt</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to character string specifying options for the z axis.
	    The string can include any combination of the following letters
	    (upper or lower case) in any order:
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal>b</literal>: Draws z axis to the left of the
		  surface plot.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>c</literal>: Draws z axis to the right of the
		  surface plot.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>d</literal>: Draws grid lines parallel to the
		  x-y plane behind the figure.  These lines are not drawn
		  until after &plot3d; or &plmesh; are called because of
		  the need for hidden line removal.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>f</literal>: Always use fixed point numeric labels.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>i</literal>: Inverts tick marks, so they are
		  drawn away from the center.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>l</literal>: Labels axis logarithmically.  This
		  only affects the labels, not the data, and so it is
		  necessary to compute the logarithms of data points before
		  passing them to any of the drawing routines.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>m</literal>: Writes numeric labels at major tick
		  intervals on the right-hand vertical axis.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>n</literal>: Writes numeric labels at major tick
		  intervals on the left-hand vertical axis.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>o</literal>: Use custom labelling function to
		  generate axis label text.  The custom labelling function
		  can be defined with the &plslabelfunc; command.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>s</literal>: Enables subticks between major
		  ticks, only valid if <literal>t</literal> is also
		  specified.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>t</literal>: Draws major ticks.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>u</literal>: If this is specified, the text
		  label is written beside the left-hand axis.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>v</literal>: If this is specified, the text
		  label is written beside the right-hand axis.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>zlabel</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to character string specifying text label for the z
	    axis.  It is only drawn if <literal>u</literal> or
	    <literal>v</literal> are in the
	    <literal><parameter>zopt</parameter></literal> string.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ztick</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    World coordinate interval between major ticks on the z axis.
	    If it is set to zero, PLplot automatically generates a suitable
	    tick interval.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nzsub</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of subintervals between major z axis ticks for minor
	    ticks.  If it is set to zero, PLplot automatically generates a
	    suitable minor tick interval.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plbox3(xopt, xlabel, xtick, nxsub, yopt, ylabel, ytick, nysub, zopt, zlabel, ztick, nzsub)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: <function>plbox3(xtick, nxsub, ytick, nysub, ztick, nzsub, xopt, xlabel, yopt, ylabel, zopt, zlabel)</function>
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in examples 8,11,18,21.
    </para>

  </sect1>

  <sect1 id="plbtime" renderas="sect3">
    <title>
      <function>plbtime</function>: Calculate broken-down time from
      continuous time for the current stream
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plbtime</function>
	  </funcdef>
	  <paramdef><parameter>year</parameter></paramdef>
	  <paramdef><parameter>month</parameter></paramdef>
	  <paramdef><parameter>day</parameter></paramdef>
	  <paramdef><parameter>hour</parameter></paramdef>
	  <paramdef><parameter>min</parameter></paramdef>
	  <paramdef><parameter>sec</parameter></paramdef>
	  <paramdef><parameter>ctime</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>
    <para>
      Calculate broken-down time; 
      <literal><parameter>year</parameter></literal>,
      <literal><parameter>month</parameter></literal>,
      <literal><parameter>day</parameter></literal>,
      <literal><parameter>hour</parameter></literal>,
      <literal><parameter>min</parameter></literal>,
      <literal><parameter>sec</parameter></literal>; from
      continuous time, <literal><parameter>ctime</parameter></literal>
      for the current stream.  This function is the inverse
      of &plctime;.
    </para>
    <para>
      The PLplot definition of broken-down time is a calendar time
      that completely ignores all time zone offsets, i.e., it is the
      user's responsibility to apply those offsets (if so desired)
      before using the PLplot time API.  By default broken-down time
      is defined using the proleptic Gregorian calendar without the
      insertion of leap seconds and continuous time is defined as the
      number of seconds since the Unix epoch of 1970-01-01T00:00:00Z.
      However, other definitions of broken-down and continuous time
      are possible, see &plconfigtime;.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>year</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Output year.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>month</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Output month in range from 0 (January) to 11 (December).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>day</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Output day in range from 1 to 31.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>hour</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Output hour in range from 0 to 23.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>min</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Output minute in range from 0 to 59
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>sec</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Output second in floating range from 0. to 60.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ctime</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Continous time from which the broken-down time is calculated.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plbtime(year, month, day, hour, min, sec, ctime)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: Not available?
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in example 29.
    </para>

  </sect1>

  <sect1 id="plcalc_world" renderas="sect3">
    <title>
      <function>plcalc_world</function>: Calculate world coordinates and
      corresponding window index from relative device coordinates
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plcalc_world</function>
	  </funcdef>
	  <paramdef><parameter>rx</parameter></paramdef>
	  <paramdef><parameter>ry</parameter></paramdef>
	  <paramdef><parameter>wx</parameter></paramdef>
	  <paramdef><parameter>wy</parameter></paramdef>
	  <paramdef><parameter>window</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>
    <para>
      Calculate world coordinates,
      <literal><parameter>wx</parameter></literal> and
      <literal><parameter>wy</parameter></literal>, and corresponding
      <literal><parameter>window</parameter></literal> index
      from relative device coordinates,
      <literal><parameter>rx</parameter></literal> and
      <literal><parameter>ry</parameter></literal>.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>rx</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Input relative device coordinate (ranging from 0. to 1.) for the
	    x coordinate.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ry</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Input relative device coordinate (ranging from 0. to 1.) for the
	    y coordinate.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>wx</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to the returned world coordinate for x corresponding
	    to the relative device coordinates
	    <literal><parameter>rx</parameter></literal> and
	    <literal><parameter>ry</parameter></literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>wy</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to the returned world coordinate for y corresponding
	    to the relative device coordinates
	    <literal><parameter>rx</parameter></literal> and
	    <literal><parameter>ry</parameter></literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>window</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to the returned last defined window index that corresponds to the
	    input relative device coordinates (and the returned world
	    coordinates).  To give some background on the window index,
	    for each page the initial window index is set to
	    zero, and each time &plwind; is called within the page, world
	    and device coordinates are stored for the window and the window
	    index is incremented.  Thus, for a simple page layout with
	    non-overlapping viewports and one window per viewport,
	    <literal><parameter>window</parameter></literal> corresponds to
	    the viewport index (in the order which the viewport/windows
	    were created) of the only viewport/window corresponding to
	    <literal><parameter>rx</parameter></literal> and
	    <literal><parameter>ry</parameter></literal>.  However, for
	    more complicated layouts with potentially overlapping viewports
	    and possibly more than one window (set of world coordinates) per
	    viewport, <literal><parameter>window</parameter></literal>
	    and the corresponding output world coordinates
	    corresponds to the last window created that fulfills the criterion
	    that the relative device coordinates are inside it.  Finally, in
	    all cases where the input relative device coordinates are not
	    inside any viewport/window, then
	    <literal><parameter>window</parameter></literal> is set to -1.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plcalc_world(rx, ry, wx, wy, window)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: Not available?
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in example 31.
    </para>

  </sect1>

  <sect1 id="plclear" renderas="sect3">
    <title>
      <function>plclear</function>: Clear current (sub)page
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plclear</function>
	  </funcdef>
	  <paramdef></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Clears the current page, effectively erasing everything that have
      been drawn.  This command only works with interactive drivers; if the driver
      does not support this, the page is filled with the background color in use.
      If the current page is divided into subpages, only the current subpage
      is erased.  The nth subpage can be selected with &pladv;(n).
    </para>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plclear()</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: Not available?
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is not used in any examples.
    </para>

  </sect1>

  <sect1 id="plcol0" renderas="sect3">
    <title>
      <function>plcol0</function>: Set color, cmap0
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plcol0</function>
	  </funcdef>
	  <paramdef><parameter>icol0</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets the color index for cmap0 (see <xref linkend="color-map-0"/>).
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>icol0</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Integer representing the color.  The defaults at present are
	    (these may change):
	    <simplelist type="horiz" columns="2">
	      <member> 0 </member>  <member>black (default background)</member>
	      <member> 1 </member>  <member>red (default foreground)</member>
	      <member> 2 </member>  <member>yellow</member>
	      <member> 3 </member>  <member>green</member>
	      <member> 4 </member>  <member>aquamarine</member>
	      <member> 5 </member>  <member>pink</member>
	      <member> 6 </member>  <member>wheat</member>
	      <member> 7 </member>  <member>grey</member>
	      <member> 8 </member>  <member>brown</member>
	      <member> 9 </member>  <member>blue</member>
	      <member>10 </member>  <member>BlueViolet</member>
	      <member>11 </member>  <member>cyan</member>
	      <member>12 </member>  <member>turquoise</member>
	      <member>13 </member>  <member>magenta</member>
	      <member>14 </member>  <member>salmon</member>
	      <member>15 </member>  <member>white</member>
	    </simplelist>
	    Use &plscmap0; to change the entire map0 color palette and
	    &plscol0; to change an individual color in the map0 color
	    palette.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plcol0(icol0)</function>
    </para>

    <para>
      This function is used in examples 1-9,11-16,18-27,29.
    </para>

  </sect1>

  <sect1 id="plcol1" renderas="sect3">
    <title>
      <function>plcol1</function>: Set color, cmap1
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plcol1</function>
	  </funcdef>
	  <paramdef><parameter>col1</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para> Sets the color for cmap1 (see <xref
    linkend="color-map-1"/>).  </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>col1</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    This value must be in the range from 0. to 1. and is mapped to
	    color using the continuous map1 color palette which by default
	    ranges from blue to the background color to red.  The map1
	    palette can also be straightforwardly changed by the user with
	    &plscmap1; or &plscmap1l;.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plcol1(col1)</function>
    </para>

    <para>
      This function is used in examples 12 and 21.
    </para>

  </sect1>

  <sect1 id="plcolorbar" renderas="sect3">
    <title>
      <function>plcolorbar</function>: Plot color bar for image, shade or gradient plots
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plcolorbar</function>
	  </funcdef>
	  <paramdef><parameter>p_colorbar_width</parameter></paramdef>
	  <paramdef><parameter>p_colorbar_height</parameter></paramdef>
	  <paramdef><parameter>opt</parameter></paramdef>
	  <paramdef><parameter>position</parameter></paramdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>x_length</parameter></paramdef>
	  <paramdef><parameter>y_length</parameter></paramdef>
	  <paramdef><parameter>bg_color</parameter></paramdef>
	  <paramdef><parameter>bb_color</parameter></paramdef>
	  <paramdef><parameter>bb_style</parameter></paramdef>
	  <paramdef><parameter>low_cap_color</parameter></paramdef>
	  <paramdef><parameter>high_cap_color</parameter></paramdef>
	  <paramdef><parameter>cont_color</parameter></paramdef>
	  <paramdef><parameter>cont_width</parameter></paramdef>
	  <paramdef><parameter>n_labels</parameter></paramdef>
	  <paramdef><parameter>label_opts</parameter></paramdef>
	  <paramdef><parameter>labels</parameter></paramdef>
	  <paramdef><parameter>naxes</parameter></paramdef>
	  <paramdef><parameter>axis_opts</parameter></paramdef>
	  <paramdef><parameter>ticks</parameter></paramdef>
	  <paramdef><parameter>sub_ticks</parameter></paramdef>
	  <paramdef><parameter>n_values</parameter></paramdef>
	  <paramdef><parameter>values</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Routine for creating a continuous color bar for image, shade, or gradient plots.
      (See &pllegend; for similar functionality for creating legends with discrete elements).
      The arguments of plcolorbar provide control over the location
      and size of the color bar as well as the location and characteristics of
      the elements (most of which are optional) within that color bar.  The
      resulting color bar is clipped at the boundaries of the current subpage.
      (N.B. the adopted coordinate system used for some of the parameters is
      defined in the documentation of the
      <literal><parameter>position</parameter></literal> parameter.)
    </para>
    <variablelist>
      <varlistentry>
	<term>
	  <parameter>p_colorbar_width</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to a location which contains (after the call) the
	    labelled and decorated color bar width in adopted coordinates.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_colorbar_height</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to a location which contains (after the call) the
	    labelled and decorated color bar height in adopted coordinates.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>opt</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    <literal><parameter>opt</parameter></literal> contains
	    bits controlling the overall color bar.  The orientation (direction of
	    the maximum value) of the color bar is specified with
	    <literal>PL_ORIENT_RIGHT</literal>, <literal>PL_ORIENT_TOP</literal>,
	    <literal>PL_ORIENT_LEFT</literal>, or
	    <literal>PL_ORIENT_BOTTOM</literal>.  If none of these bits are
	    specified, the default orientation is toward the top if the colorbar
	    is placed on the left or right of the viewport or toward the right if
	    the colorbar is placed on the top or bottom of the viewport. If the
	    <literal>PL_COLORBAR_BACKGROUND</literal> bit is set, plot a
	    (semi-transparent) background for the color bar. If the
	    <literal>PL_COLORBAR_BOUNDING_BOX</literal> bit is set, plot a
	    bounding box for the color bar. The type of color bar must be
	    specified with one of <literal>PL_COLORBAR_IMAGE</literal>,
	    <literal>PL_COLORBAR_SHADE</literal>, or
	    <literal>PL_COLORBAR_GRADIENT</literal>. If more than one of those
	    bits is set only the first one in the above list is honored. The
	    position of the (optional) label/title can be specified with
	    <literal>PL_LABEL_RIGHT</literal>, <literal>PL_LABEL_TOP</literal>,
	    <literal>PL_LABEL_LEFT</literal>, or
	    <literal>PL_LABEL_BOTTOM</literal>.  If no label position bit is set
	    then no label will be drawn. If more than one of this list of bits is
	    specified, only the first one on the list is honored. End-caps for the
	    color bar can added with <literal>PL_COLORBAR_CAP_LOW</literal> and
	    <literal>PL_COLORBAR_CAP_HIGH</literal>. If a particular color bar cap
	    option is not specified then no cap will be drawn for that end. As a
	    special case for <literal>PL_COLORBAR_SHADE</literal>, the option
	    <literal>PL_COLORBAR_SHADE_LABEL</literal> can be specified. If this
	    option is provided then any tick marks and tick labels will be placed
	    at the breaks between shaded segments. TODO: This should be expanded
	    to support custom placement of tick marks and tick labels at custom
	    value locations for any color bar type.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>position</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    <literal><parameter>position</parameter></literal>
	    contains bits which control the overall position of the
	    color bar and the definition of the adopted coordinates used for
	    positions just like what is done for the position argument for
	    &pllegend;. However, note that the defaults for the position bits
	    (see below) are different than the &pllegend; case. The combination of
	    the <literal>PL_POSITION_LEFT</literal>,
	    <literal>PL_POSITION_RIGHT</literal>,
	    <literal>PL_POSITION_TOP</literal>,
	    <literal>PL_POSITION_BOTTOM</literal>,
	    <literal>PL_POSITION_INSIDE</literal>, and
	    <literal>PL_POSITION_OUTSIDE</literal> bits specifies one of the 16
	    possible standard positions (the 4 corners and centers of the 4 sides
	    for both the inside and outside cases) of the color bar relative to
	    the adopted coordinate system. The corner positions are specified by
	    the appropriate combination of two of the
	    <literal>PL_POSITION_LEFT</literal>,
	    <literal>PL_POSITION_RIGHT</literal>,
	    <literal>PL_POSITION_TOP</literal>, and
	    <literal>PL_POSITION_BOTTOM</literal> bits while the sides are
	    specified by a single value of one of those bits.  The adopted
	    coordinates are normalized viewport coordinates if the
	    <literal>PL_POSITION_VIEWPORT</literal> bit is set or normalized
	    subpage coordinates if the <literal>PL_POSITION_SUBPAGE</literal> bit
	    is set. Default position bits: If none of
	    <literal>PL_POSITION_LEFT</literal>,
	    <literal>PL_POSITION_RIGHT</literal>,
	    <literal>PL_POSITION_TOP</literal>, or
	    <literal>PL_POSITION_BOTTOM</literal> are set, then use
	    <literal>PL_POSITION_RIGHT</literal>. If neither of
	    <literal>PL_POSITION_INSIDE</literal> or
	    <literal>PL_POSITION_OUTSIDE</literal> is set, use
	    <literal>PL_POSITION_OUTSIDE</literal>. If neither of
	    <literal>PL_POSITION_VIEWPORT</literal> or
	    <literal>PL_POSITION_SUBPAGE</literal> is set, use
	    <literal>PL_POSITION_VIEWPORT</literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal> PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    X offset of the color bar position in adopted coordinates from the
	    specified standard position of the color bar. For positive x, the
	    direction of motion away from the standard position is inward/outward
	    from the standard corner positions or standard left or right positions
	    if the
	    <literal>PL_POSITION_INSIDE</literal>/<literal>PL_POSITION_OUTSIDE</literal>
	    bit is set in <literal><parameter>position</parameter></literal>.  For
	    the standard top or bottom positions, the direction of motion is
	    toward positive X.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Y offset of the color bar position in adopted coordinates from the
	    specified standard position of the color bar. For positive y, the
	    direction of motion away from the standard position is inward/outward
	    from the standard corner positions or standard top or bottom positions
	    if the
	    <literal>PL_POSITION_INSIDE</literal>/<literal>PL_POSITION_OUTSIDE</literal>
	    bit is set in <literal><parameter>position</parameter></literal>.  For
	    the standard left or right positions, the direction of motion is
	    toward positive Y.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>x_length</parameter>
	  (<literal> PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Length of the body of the color bar in the X direction in
	    adopted coordinates.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y_length</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Length of the body of the color bar in the Y direction in adopted
	    coordinates.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>bg_color</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
            The cmap0 color of the background for the color bar
	    (<literal>PL_COLORBAR_BACKGROUND</literal>).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>bb_color</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The cmap0 color of the bounding-box line for the color bar
	    (<literal>PL_COLORBAR_BOUNDING_BOX</literal>).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>bb_style</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The &pllsty; style number for the bounding-box line for the color bar
	    (<literal>PL_COLORBAR_BACKGROUND</literal>).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>low_cap_color</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The cmap1 color of the low-end color bar cap, if it is drawn
	    (<literal>PL_COLORBAR_CAP_LOW</literal>).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>high_cap_color</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The cmap1 color of the high-end color bar cap, if it is drawn 
	    (<literal>PL_COLORBAR_CAP_HIGH</literal>).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>cont_color</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The cmap0 contour color for <literal>PL_COLORBAR_SHADE</literal>
	    plots. This is passed directly to &plshades;, so it will be
	    interpreted according to the design of &plshades;.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>cont_width</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Contour width for <literal>PL_COLORBAR_SHADE</literal>
	    plots. This is passed directly to &plshades;, so it will be
	    interpreted according to the design of &plshades;.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>n_labels</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of labels to place around the color bar.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>label_opts</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Options for each of <parameter>n_labels</parameter> labels.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>labels</parameter>
	  (<literal>const char * const *</literal>, input)
	</term>
	<listitem>
	  <para>
	    <parameter>n_labels</parameter> text labels for the color bar. No
	    label is drawn if no label position is specified with one of the
	    <literal>PL_COLORBAR_LABEL_RIGHT</literal>,
	    <literal>PL_COLORBAR_LABEL_TOP</literal>,
	    <literal>PL_COLORBAR_LABEL_LEFT</literal>, or
	    <literal>PL_COLORBAR_LABEL_BOTTOM</literal> bits in the corresponding
	    label_opts field.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>n_axes</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of axis definitions provided. This value must be greater than
	    0. It is typically 1 (numerical axis labels are provided for one of
	    the long edges of the color bar), but it can be larger if multiple
	    numerical axis labels for the long edges of the color bar are desired.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>axis_opts</parameter>
	  (<literal>const char * const *</literal>, input)
	</term>
	<listitem>
	  <para>
	    An array of n_axes axis options (interpreted as for &plbox;) for the
	    color bar's axis definitions.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ticks</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    An array of n_axes values of the spacing of the major tick marks
	    (interpreted as for &plbox;) for the color bar's axis definitions.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>sub_ticks</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    An array of n_axes values of the number of subticks (interpreted as
	    for &plbox;) for the color bar's axis definitions.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>n_values</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    An array containing the number of elements in each of the
	    <literal><parameter>n_axes</parameter></literal> rows of the
	    two-dimensional <literal><parameter>values</parameter></literal> array.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>values</parameter>
	  (<literal>const PLFLT * const *</literal>, input)
	</term>
	<listitem>
	  <para>
	    A two-dimensional array containing the numeric values for the data
	    range represented by the color bar. For a row index of
	    <literal><parameter>i_axis</parameter></literal> (where 0 &lt;
	    <literal><parameter>i_axis</parameter></literal> &lt;
	    <literal><parameter>n_axes</parameter></literal>), the number of
	    elements in the row is specified by
	    <literal><parameter>n_values</parameter></literal>[<literal><parameter>i_axis</parameter></literal>]. For <literal>PL_COLORBAR_IMAGE</literal> and
	    <literal>PL_COLORBAR_GRADIENT</literal> the number of elements is 2,
	    and the corresponding row elements of the
	    <literal><parameter>values</parameter></literal> array are the minimum
	    and maximum value represented by the colorbar.  For
	    <literal>PL_COLORBAR_SHADE</literal>, the number and values of the
	    elements of a row of the
	    <literal><parameter>values</parameter></literal> array is interpreted
	    the same as the <literal><parameter>nlevel</parameter></literal> and
	    <literal><parameter>clevel</parameter></literal> arguments of
	    &plshades;.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plcolorbar(p_colorbar_width, p_colorbar_height, 
      opt, position, x, y, x_length, y_length, bg_color,
      bb_color, bb_style, low_cap_color, high_cap_color, cont_color, cont_width, label_opts, labels, axis_opts, ticks, sub_ticks, values)</function>
    </para>

    <para>
      This function is used in examples 16 and 33.
    </para>

  </sect1>

  <sect1 id="plconfigtime" renderas="sect3">
    <title>
      <function>plconfigtime</function>: Configure the transformation
        between continuous and broken-down time for the current stream
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plconfigtime</function>
	  </funcdef>
	  <paramdef><parameter>scale</parameter></paramdef>
	  <paramdef><parameter>offset1</parameter></paramdef>
	  <paramdef><parameter>offset2</parameter></paramdef>
	  <paramdef><parameter>ccontrol</parameter></paramdef>
	  <paramdef><parameter>ifbtime_offset</parameter></paramdef>
	  <paramdef><parameter>year</parameter></paramdef>
	  <paramdef><parameter>month</parameter></paramdef>
	  <paramdef><parameter>day</parameter></paramdef>
	  <paramdef><parameter>hour</parameter></paramdef>
	  <paramdef><parameter>min</parameter></paramdef>
	  <paramdef><parameter>sec</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Configure the transformation
      between continuous and broken-down time
      for the current stream.  This transformation is
      used by both &plbtime; and &plctime;.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>scale</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The number of days per continuous time unit.  As a special
	    case, if <parameter>scale</parameter> is 0., then all
	    other arguments are ignored, and the result (the default
	    used by PLplot) is the equivalent of a call to
	    plconfigtime(1./86400., 0., 0., 0x0, 1, 1970, 0, 1, 0, 0, 0.).
	    That is, for this special case broken-down time is
	    calculated with the proleptic Gregorian calendar with no
	    leap seconds inserted, and the continuous time is defined
            as the number of seconds since the Unix epoch of 
	    1970-01-01T00:00:00Z.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>offset1</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
            If <parameter>ifbtime_offset</parameter> is true, the
	    parameters <parameter>offset1</parameter> and
	    <parameter>offset2</parameter> are completely ignored.
	    Otherwise, the sum of these parameters (with units in
	    days) specify the epoch of the continuous time relative to
	    the MJD epoch corresponding to the Gregorian calendar date
	    of 1858-11-17T00:00:00Z or JD = 2400000.5.  Two PLFLT numbers
	    are used to specify the origin to allow users (by
	    specifying <parameter>offset1</parameter> as an integer
	    that can be exactly represented by a
	    floating-point variable and specifying
	    <parameter>offset2</parameter> as a number in the range
	    from 0. to 1) the chance to minimize the numerical errors of
	    the continuous time representation.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>offset2</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    See documentation of <parameter>offset1</parameter>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ccontrol</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
            <parameter>ccontrol</parameter> contains bits controlling
	    the transformation.  If the 0x1 bit is set, then the
	    proleptic Julian calendar is used for broken-down time
	    rather than the proleptic Gregorian calendar.  If the 0x2
	    bit is set, then leap seconds that have been historically
	    used to define UTC are inserted into the broken-down time.
	    Other possibilities for additional control bits for
	    ccontrol exist such as making the historical time
	    corrections in the broken-down time corresponding to ET
	    (ephemeris time) or making the (slightly non-constant)
	    corrections from international atomic time (TAI) to what
	    astronomers define as terrestrial time (TT).  But those
	    additional possibilities have not been implemented yet in
	    the qsastime library (one of the PLplot utility
	    libraries).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ifbtime_offset</parameter>
	  (<literal>PLBOOL</literal>, input)
	</term>
	<listitem>
	  <para>
            <parameter>ifbtime_offset</parameter> controls how the
	    epoch of the continuous time scale is specified by the
	    user. If <parameter>ifbtime_offset</parameter> is false,
	    then <parameter>offset1</parameter> and
	    <parameter>offset2</parameter> are used to specify the
	    epoch, and the following broken-down time parameters are
	    completely ignored.  If
	    <parameter>ifbtime_offset</parameter> is true, then
	    <parameter>offset1</parameter> and
	    <parameter>offset2</parameter> are completely ignored, and
	    the following broken-down time parameters are used to
	    specify the epoch.
          </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>year</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Year of epoch.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>month</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Month of epoch in range from 0 (January) to 11 (December).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>day</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Day of epoch in range from 1 to 31.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>hour</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Hour of epoch in range from 0 to 23
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>min</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Minute of epoch in range from 0 to 59.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>sec</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Second of epoch in floating range from 0. to 60.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plconfigtime(scale, offset1, offset2, ccontrol, ifbtime_offset, year, month, day, hour, min, sec)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: Not available?
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in example 29.
    </para>

  </sect1>

  <sect1 id="plcont" renderas="sect3">
    <title>
      <function>plcont</function>: Contour plot
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plcont</function>
	  </funcdef>
	  <paramdef><parameter>f</parameter></paramdef>
	  <paramdef><parameter>nx</parameter></paramdef>
	  <paramdef><parameter>ny</parameter></paramdef>
	  <paramdef><parameter>kx</parameter></paramdef>
	  <paramdef><parameter>lx</parameter></paramdef>
	  <paramdef><parameter>ky</parameter></paramdef>
	  <paramdef><parameter>ly</parameter></paramdef>
	  <paramdef><parameter>clevel</parameter></paramdef>
	  <paramdef><parameter>nlevel</parameter></paramdef>
	  <paramdef><parameter>pltr</parameter></paramdef>
	  <paramdef><parameter>pltr_data</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Draws a contour plot of the data in
      <literal><parameter>f</parameter>[<parameter>nx</parameter>][<parameter>ny</parameter>]</literal>,
      using the <literal><parameter>nlevel</parameter></literal> contour
      levels specified by <literal><parameter>clevel</parameter></literal>.
      Only the region of the array from
      <literal><parameter>kx</parameter></literal> to
      <literal><parameter>lx</parameter></literal> and from
      <literal><parameter>ky</parameter></literal> to
      <literal><parameter>ly</parameter></literal> is plotted out.  A
      transformation routine pointed to by <literal><parameter>pltr</parameter></literal>
      with a pointer <literal><parameter>pltr_data</parameter></literal>
      for additional data required by the transformation routine
      is used to map indices within the array
      to the world coordinates.  See the following discussion of the
      arguments and <xref linkend="contour-plots"/> for
      more information.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>f</parameter>
	  (<literal>const PLFLT * const *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to a vectored two-dimensional array containing data to
	    be contoured.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nx, ny</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Physical dimensions of array
	    <literal><parameter>f</parameter></literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>kx, lx</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Range of <literal>x</literal> indices to consider.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ky, ly</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Range of <literal>y</literal> indices to consider.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>clevel</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array specifying levels at which to draw contours.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nlevel</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of contour levels to draw.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>pltr</parameter>
	  (<literal>void (*) (PLFLT, PLFLT, PLFLT *, PLFLT *, PLPointer)
	  </literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to function that defines transformation between indices
	    in array <literal><parameter>f</parameter></literal> and the
	    world coordinates (C only).  Transformation functions are
	    provided in the PLplot library:
	    &pltr0; for identity mapping, and &pltr1; and &pltr2; for
	    arbitrary mappings respectively defined by one- and
	    two-dimensional arrays.  In addition, user-supplied routines
	    for the transformation can be used as well.  Examples of
	    all of these approaches are given in
	    <xref linkend="contour-plots-c"/>.
	    The transformation function should
	    have the form given by any of &pltr0;, &pltr1;, or &pltr2;.
	    Note that unlike &plshades; and similar PLplot functions
	    which have a <literal><parameter>pltr</parameter></literal>
	    argument, plcont requires that a transformation function be
	    provided in the C interface.  Leaving 
	    <literal><parameter>pltr</parameter></literal> NULL will result
	    in an error.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>pltr_data</parameter>
	  (<literal>PLPointer</literal>, input)
	</term>
	<listitem>
	  <para>
	    Extra parameter to help
	    pass information to &pltr0;, &pltr1;, &pltr2;, or whatever routine
	    that is externally supplied.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: [PLEASE UPDATE! ONLY PERL INFO IS LIKELY CORRECT!]
      <itemizedlist>
	<listitem>
	  <para>
	    F95: <function>plcont(f, kx, lx, ky, ly, clevel, tr?)</function> or
	    <function>plcont(f, kx, lx, ky, ly, clevel, xgrid, ygrid)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Java: <function>pls.cont(f, kx, lx, ky, ly, clevel, xgrid, ygrid)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: <function>plcont(f, kx, lx, ky, ly, clevel, pltr, pltr_data)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Python: <function>plcont2(f, kx, lx, ky, ly, clevel)</function>
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in examples 9,14,16,22.
    </para>

  </sect1>

  <sect1 id="plcpstrm" renderas="sect3">
    <title>
      <function>plcpstrm</function>: Copy state parameters from the
      reference stream to the current stream
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plcpstrm</function>
	  </funcdef>
	  <paramdef><parameter>iplsr</parameter></paramdef>
	  <paramdef><parameter>flags</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Copies state parameters from the reference stream to the current stream.
      Tell driver interface to map device coordinates unless
      <literal><parameter>flags</parameter> == 1</literal>.
    </para>

    <para>
      This function is used for making save files of selected plots (e.g.
      from the TK driver).  After initializing, you can get a copy of the
      current plot to the specified device by switching to this stream and
      issuing a &plcpstrm; and a &plreplot;, with calls to &plbop; and
      &pleop; as appropriate.  The plot buffer must have previously been
      enabled (done automatically by some display drivers, such as X).
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>iplsr</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of reference stream.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>flags</parameter>
	  (<literal>PLBOOL</literal>, input)
	</term>
	<listitem>
	  <para>
	    If <literal><parameter>flags</parameter></literal> is set to true
	    the device coordinates are <emphasis>not</emphasis> copied from the reference to current
	    stream.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plcpstrm(iplsr, flags)</function>
    </para>

    <para>
      This function is used in example 1,20.
    </para>

  </sect1>

  <sect1 id="plctime" renderas="sect3">
    <title>
      <function>plctime</function>: Calculate continuous time from
      broken-down time for the current stream
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plctime</function>
	  </funcdef>
	  <paramdef><parameter>year</parameter></paramdef>
	  <paramdef><parameter>month</parameter></paramdef>
	  <paramdef><parameter>day</parameter></paramdef>
	  <paramdef><parameter>hour</parameter></paramdef>
	  <paramdef><parameter>min</parameter></paramdef>
	  <paramdef><parameter>sec</parameter></paramdef>
	  <paramdef><parameter>ctime</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>
    <para>
      Calculate continuous time, <literal><parameter>ctime</parameter></literal>,
      from broken-down time for the current stream.  The broken-down
time is specified by the following parameters:
      <literal><parameter>year</parameter></literal>,
      <literal><parameter>month</parameter></literal>,
      <literal><parameter>day</parameter></literal>,
      <literal><parameter>hour</parameter></literal>,
      <literal><parameter>min</parameter></literal>, and
      <literal><parameter>sec</parameter></literal>.
      This function is the inverse of &plbtime;.
    </para>
    <para>
      The PLplot definition of broken-down time is a calendar time
      that completely ignores all time zone offsets, i.e., it is the
      user's responsibility to apply those offsets (if so desired)
      before using the PLplot time API.  By default broken-down time
      is defined using the proleptic Gregorian calendar without the
      insertion of leap seconds and continuous time is defined as the
      number of seconds since the Unix epoch of 1970-01-01T00:00:00Z.
      However, other definitions of broken-down and continuous time
      are possible, see &plconfigtime; which specifies that
      transformation for the current stream.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>year</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Input year.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>month</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Input month in range from 0 (January) to 11 (December).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>day</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Input day in range from 1 to 31.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>hour</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Input hour in range from 0 to 23
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>min</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Input minute in range from 0 to 59.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>sec</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Input second in floating range from 0. to 60.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ctime</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Continous time calculated from the broken-down time
            specified by the previous parameters.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plctime(year, month, day, hour, min, sec, ctime)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: Not available?
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in example 29.
    </para>

  </sect1>

  <sect1 id="plend" renderas="sect3">
    <title>
      <function>plend</function>: End plotting session
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plend</function>
	  </funcdef>
	  <paramdef></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Ends a plotting session, tidies up all the output files, switches
      interactive devices back into text mode and frees up any memory that
      was allocated.  Must be called before end of program.
    </para>

    <para>
      By default, PLplot's interactive devices (Xwin, TK, etc.) 
      go into a wait state after a call to plend
      or other functions which trigger the end of a plot page.
      To avoid this, use the &plspause; function.
    </para>

    <para>
      Redacted form: <function>plend()</function>
    </para>

    <para>
      This function is used in all of the examples.
    </para>

  </sect1>

  <sect1 id="plend1" renderas="sect3">
    <title>
      <function>plend1</function>: End plotting session for current stream
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plend1</function>
	  </funcdef>
	  <paramdef></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Ends a plotting session for the current output stream only.  See
      &plsstrm; for more info.
    </para>

    <para>
      Redacted form: <function>plend1()</function>
    </para>

    <para>
      This function is used in examples 1,20.
    </para>

  </sect1>

  <sect1 id="plenv0" renderas="sect3">
    <title>
      <function>plenv0</function>: Same as &plenv; but if in multiplot
      mode does not advance the subpage, instead clears it
    </title>
    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plenv0</function>
	  </funcdef>
	  <paramdef><parameter>xmin</parameter></paramdef>
	  <paramdef><parameter>xmax</parameter></paramdef>
	  <paramdef><parameter>ymin</parameter></paramdef>
	  <paramdef><parameter>ymax</parameter></paramdef>
	  <paramdef><parameter>just</parameter></paramdef>
	  <paramdef><parameter>axis</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets up plotter environment for simple graphs by calling &pladv; and
      setting up viewport and window to sensible default values.  &plenv0;
      leaves enough room around most graphs for axis labels and a title.
      When these defaults are not suitable, use the individual routines
      &plvpas;, &plvpor;, or &plvasp; for setting up the viewport, &plwind;
      for defining the window, and &plbox; for drawing the box.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>xmin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Value of x at left-hand edge of window (in world coordinates).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xmax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Value of x at right-hand edge of window (in world coordinates).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Value of y at bottom edge of window (in world coordinates).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Value of y at top edge of window (in world coordinates).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>just</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Controls how the axes will be scaled:
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal>-1</literal>: the scales
		  will not be set, the user must set up the scale before calling
		  &plenv0; using &plsvpa;, &plvasp; or other.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>0</literal>: the x and
		  y axes are scaled independently to use as much of the screen as
		  possible.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>1</literal>: the scales of
		  the x and y axes are made equal.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>2</literal>: the axis of
		  the x and y axes are made equal, and the plot box will be square.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>axis</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Controls drawing of the box around the plot:
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal>-2</literal>: draw no box, no tick marks, no
		  numeric tick labels, no axes.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>-1</literal>: draw box only.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>0</literal>: draw box, ticks, and numeric tick labels.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>1</literal>: also draw coordinate axes at
		  <literal>x=0</literal> and <literal>y=0</literal>.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>2</literal>: also draw a grid at major tick
		  positions in both coordinates.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>3</literal>: also draw a grid at minor tick
		  positions in both coordinates.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>10</literal>: same as 0 except logarithmic
		  <literal>x</literal> tick marks. (The <literal>x</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>11</literal>: same as 1 except logarithmic
		  <literal>x</literal> tick marks. (The <literal>x</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>12</literal>: same as 2 except logarithmic
		  <literal>x</literal> tick marks. (The <literal>x</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>13</literal>: same as 3 except logarithmic
		  <literal>x</literal> tick marks. (The <literal>x</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>20</literal>: same as 0 except logarithmic
		  <literal>y</literal> tick marks. (The <literal>y</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>21</literal>: same as 1 except logarithmic
		  <literal>y</literal> tick marks. (The <literal>y</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>22</literal>: same as 2 except logarithmic
		  <literal>y</literal> tick marks. (The <literal>y</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>23</literal>: same as 3 except logarithmic
		  <literal>y</literal> tick marks. (The <literal>y</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>30</literal>: same as 0 except logarithmic
		  <literal>x</literal> and <literal>y</literal> tick marks. (The <literal>x</literal> and <literal>y</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>31</literal>: same as 1 except logarithmic
		  <literal>x</literal> and <literal>y</literal> tick marks. (The <literal>x</literal> and <literal>y</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>32</literal>: same as 2 except logarithmic
		  <literal>x</literal> and <literal>y</literal> tick marks. (The <literal>x</literal> and <literal>y</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>33</literal>: same as 3 except logarithmic
		  <literal>x</literal> and <literal>y</literal> tick marks. (The <literal>x</literal> and <literal>y</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>40</literal>: same as 0 except date / time
		  <literal>x</literal> labels. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>41</literal>: same as 1 except date / time
		  <literal>x</literal> labels. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>42</literal>: same as 2 except date / time
		  <literal>x</literal> labels. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>43</literal>: same as 3 except date / time
		  <literal>x</literal> labels. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>50</literal>: same as 0 except date / time
		  <literal>y</literal> labels. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>51</literal>: same as 1 except date / time
		  <literal>y</literal> labels. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>52</literal>: same as 2 except date / time
		  <literal>y</literal> labels.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>53</literal>: same as 3 except date / time
		  <literal>y</literal> labels. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>60</literal>: same as 0 except date / time
		  <literal>x</literal> and <literal>y</literal> labels. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>61</literal>: same as 1 except date / time
		  <literal>x</literal> and <literal>y</literal> labels. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>62</literal>: same as 2 except date / time
		  <literal>x</literal> and <literal>y</literal> labels. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>63</literal>: same as 3 except date / time
		  <literal>x</literal> and <literal>y</literal> labels.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>70</literal>: same as 0 except custom
		  <literal>x</literal> and <literal>y</literal> labels.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>71</literal>: same as 1 except custom
		  <literal>x</literal> and <literal>y</literal> labels.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>72</literal>: same as 2 except custom
		  <literal>x</literal> and <literal>y</literal> labels.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>73</literal>: same as 3 except custom
		  <literal>x</literal> and <literal>y</literal> labels.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plenv0(xmin, xmax, ymin, ymax, just, axis)</function>
    </para>

    <para>
      This function is used in example 21.
    </para>

  </sect1>

  <sect1 id="plenv" renderas="sect3">
    <title>
      <function>plenv</function>: Set up standard window and draw box
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plenv</function>
	  </funcdef>
	  <paramdef><parameter>xmin</parameter></paramdef>
	  <paramdef><parameter>xmax</parameter></paramdef>
	  <paramdef><parameter>ymin</parameter></paramdef>
	  <paramdef><parameter>ymax</parameter></paramdef>
	  <paramdef><parameter>just</parameter></paramdef>
	  <paramdef><parameter>axis</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets up plotter environment for simple graphs by calling &pladv; and
      setting up viewport and window to sensible default values.  &plenv;
      leaves enough room around most graphs for axis labels and a title.
      When these defaults are not suitable, use the individual routines
      &plvpas;, &plvpor;, or &plvasp; for setting up the viewport, &plwind;
      for defining the window, and &plbox; for drawing the box.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>xmin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Value of x at left-hand edge of window (in world coordinates).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xmax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Value of x at right-hand edge of window (in world coordinates).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Value of y at bottom edge of window (in world coordinates).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Value of y at top edge of window (in world coordinates).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>just</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Controls how the axes will be scaled:
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal>-1</literal>: the scales
		  will not be set, the user must set up the scale before calling
		  &plenv; using &plsvpa;, &plvasp; or other.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>0</literal>: the x and
		  y axes are scaled independently to use as much of the screen as
		  possible.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>1</literal>: the scales of
		  the x and y axes are made equal.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>2</literal>: the axis of
		  the x and y axes are made equal, and the plot box will be square.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>axis</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Controls drawing of the box around the plot:
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal>-2</literal>: draw no box, no tick marks, no
		  numeric tick labels, no axes.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>-1</literal>: draw box only.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>0</literal>: draw box, ticks, and numeric tick labels.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>1</literal>: also draw coordinate axes at
		  <literal>x=0</literal> and <literal>y=0</literal>.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>2</literal>: also draw a grid at major tick
		  positions in both coordinates.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>3</literal>: also draw a grid at minor tick
		  positions in both coordinates.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>10</literal>: same as 0 except logarithmic
		  <literal>x</literal> tick marks. (The <literal>x</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>11</literal>: same as 1 except logarithmic
		  <literal>x</literal> tick marks. (The <literal>x</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>12</literal>: same as 2 except logarithmic
		  <literal>x</literal> tick marks. (The <literal>x</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>13</literal>: same as 3 except logarithmic
		  <literal>x</literal> tick marks. (The <literal>x</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>20</literal>: same as 0 except logarithmic
		  <literal>y</literal> tick marks. (The <literal>y</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>21</literal>: same as 1 except logarithmic
		  <literal>y</literal> tick marks. (The <literal>y</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>22</literal>: same as 2 except logarithmic
		  <literal>y</literal> tick marks. (The <literal>y</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>23</literal>: same as 3 except logarithmic
		  <literal>y</literal> tick marks. (The <literal>y</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>30</literal>: same as 0 except logarithmic
		  <literal>x</literal> and <literal>y</literal> tick marks. (The <literal>x</literal> and <literal>y</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>31</literal>: same as 1 except logarithmic
		  <literal>x</literal> and <literal>y</literal> tick marks. (The <literal>x</literal> and <literal>y</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>32</literal>: same as 2 except logarithmic
		  <literal>x</literal> and <literal>y</literal> tick marks. (The <literal>x</literal> and <literal>y</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>33</literal>: same as 3 except logarithmic
		  <literal>x</literal> and <literal>y</literal> tick marks. (The <literal>x</literal> and <literal>y</literal>
		  data have to be converted to logarithms separately.)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>40</literal>: same as 0 except date / time
		  <literal>x</literal> labels. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>41</literal>: same as 1 except date / time
		  <literal>x</literal> labels. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>42</literal>: same as 2 except date / time
		  <literal>x</literal> labels. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>43</literal>: same as 3 except date / time
		  <literal>x</literal> labels. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>50</literal>: same as 0 except date / time
		  <literal>y</literal> labels. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>51</literal>: same as 1 except date / time
		  <literal>y</literal> labels. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>52</literal>: same as 2 except date / time
		  <literal>y</literal> labels.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>53</literal>: same as 3 except date / time
		  <literal>y</literal> labels. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>60</literal>: same as 0 except date / time
		  <literal>x</literal> and <literal>y</literal> labels. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>61</literal>: same as 1 except date / time
		  <literal>x</literal> and <literal>y</literal> labels. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>62</literal>: same as 2 except date / time
		  <literal>x</literal> and <literal>y</literal> labels. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>63</literal>: same as 3 except date / time
		  <literal>x</literal> and <literal>y</literal> labels.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>70</literal>: same as 0 except custom
		  <literal>x</literal> and <literal>y</literal> labels.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>71</literal>: same as 1 except custom
		  <literal>x</literal> and <literal>y</literal> labels.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>72</literal>: same as 2 except custom
		  <literal>x</literal> and <literal>y</literal> labels.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>73</literal>: same as 3 except custom
		  <literal>x</literal> and <literal>y</literal> labels.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plenv(xmin, xmax, ymin, ymax, just, axis)</function>
    </para>

    <para>
      This function is used in example 1,3,9,13,14,19-22,29.
    </para>

  </sect1>

  <sect1 id="pleop" renderas="sect3">
    <title>
      <function>pleop</function>: Eject current page
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>pleop</function>
	  </funcdef>
	  <paramdef></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Clears the graphics screen of an interactive device, or ejects a page
      on a plotter.  See &plbop; for more information.
    </para>

    <para>
      Redacted form: <function>pleop()</function>
    </para>

    <para>
      This function is used in example 2,14.
    </para>

  </sect1>

  <sect1 id="plerrx" renderas="sect3">
    <title>
      <function>plerrx</function>: Draw x error bar
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plerrx</function>
	  </funcdef>
	  <paramdef><parameter>n</parameter></paramdef>
	  <paramdef><parameter>xmin</parameter></paramdef>
	  <paramdef><parameter>xmax</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Draws a set of <literal><parameter>n</parameter></literal>
      horizontal error bars, the
      <literal>i</literal>'th error
      bar extending from <literal><parameter>xmin</parameter>[i]</literal>
      to <literal><parameter>xmax</parameter>[i]</literal> at y coordinate
      <literal><parameter>y</parameter>[i]</literal>.  The terminals of the error bar are of length equal to the
      minor tick length (settable using &plsmin;).
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>n</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of error bars to draw.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xmin</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with x coordinates of
	    left-hand endpoint of error bars.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xmax</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with x coordinates of
	    right-hand endpoint of error bars.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with y coordinates of
	    error bar.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plerrx(xmin, ymax, y)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: <function>plerrx(n, xmin, xmax, y)</function>
	  </para>
	</listitem>
	<!--
	    <listitem>
	    <para>
	    Python: Not available?
	    </para>
	    </listitem>
	-->
      </itemizedlist>
    </para>

    <para>
      This function is used in example 29.
    </para>

  </sect1>

  <sect1 id="plerry" renderas="sect3">
    <title>
      <function>plerry</function>: Draw y error bar
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plerry</function>
	  </funcdef>
	  <paramdef><parameter>n</parameter></paramdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>ymin</parameter></paramdef>
	  <paramdef><parameter>ymax</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Draws a set of <literal><parameter>n</parameter></literal> vertical
      error bars, the <literal>i</literal>'th error bar extending from
      <literal><parameter>ymin</parameter>[i]</literal> to
      <literal><parameter>ymax</parameter>[i]</literal> at x coordinate
      <literal><parameter>x</parameter>[i]</literal>.  The terminals of the
      error bar are of length equal to the minor tick length (settable
      using &plsmin;).
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>n</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of error bars to draw.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with x coordinates of error bars.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymin</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with y coordinates of lower endpoint of error
	    bars.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymax</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with y coordinate of upper endpoint of error
	    bar.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plerry(x, ymin, ymax)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: <function>plerry(n, x, ymin, ymax)</function>
	  </para>
	</listitem>
	<!--
	    <listitem>
	    <para>
	    Python: Not available?
	    </para>
	    </listitem>
	-->
      </itemizedlist>
    </para>

    <para>
      This function is used in example 29.
    </para>

  </sect1>

  <sect1 id="plfamadv" renderas="sect3">
    <title>
      <function>plfamadv</function>: Advance to the next family file on the
      next new page
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plfamadv</function>
	  </funcdef>
	  <paramdef></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Advance to the next family file on the next new page.
    </para>

    <para>
      Redacted form: <function>plfamadv()</function>
    </para>

    <para>
      This function is not used in any examples.
    </para>

  </sect1>

  <sect1 id="plfill" renderas="sect3">
    <title>
      <function>plfill</function>: Draw filled polygon
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plfill</function>
	  </funcdef>
	  <paramdef><parameter>n</parameter></paramdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Fills the polygon defined by the
      <literal><parameter>n</parameter></literal> points
      <literal>(<parameter>x</parameter>[i],
      <parameter>y</parameter>[i])</literal> using the pattern defined by
      &plpsty; or &plpat;.  The default fill style is a solid fill. 
      The routine will automatically close the
      polygon between the last and first vertices.  If multiple closed
      polygons are passed in <literal><parameter>x</parameter></literal>
      and <literal><parameter>y</parameter></literal> then &plfill; will
      fill in between them.
    </para>

    <!-- TODO: what does "fill in between them mean? -->

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>n</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of vertices in polygon.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with x coordinates of vertices.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with y coordinates of vertices.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plfill(x,y)</function>
    </para>

    <para>
      This function is used in examples 12,13,15,16,21,24,25.
    </para>

  </sect1>

  <sect1 id="plfill3" renderas="sect3">
    <title>
      <function>plfill3</function>: Draw filled polygon in 3D
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plfill3</function>
	  </funcdef>
	  <paramdef><parameter>n</parameter></paramdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>z</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Fills the 3D polygon defined by the
      <literal><parameter>n</parameter></literal> points in the
      <literal><parameter>x</parameter></literal>,
      <literal><parameter>y</parameter></literal>, and
      <literal><parameter>z</parameter></literal> arrays
      using the pattern defined by
      &plpsty; or &plpat;.  The routine will automatically close the
      polygon between the last and first vertices.  If multiple closed
      polygons are passed in <literal><parameter>x</parameter></literal>,
      <literal><parameter>y</parameter></literal>,
      and <literal><parameter>z</parameter></literal> then &plfill3; will
      fill in between them.
    </para>

    <!-- TODO: what does "fill in between them mean? -->

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>n</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of vertices in polygon.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with x coordinates of vertices.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with y coordinates of vertices.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>z</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with z coordinates of vertices.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plfill3(x, y, z)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: <function>plfill3(n, x, y, z)</function>
	  </para>
	</listitem>
	<!--
	    <listitem>
	    <para>
	    Python: Not available?
	    </para>
	    </listitem>
	-->
      </itemizedlist>
    </para>

    <para>
      This function is used in example 15.
    </para>

  </sect1>

  <sect1 id="plflush" renderas="sect3">
    <title>
      <function>plflush</function>: Flushes the output stream
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plflush</function>
	  </funcdef>
	  <paramdef></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Flushes the output stream. Use sparingly, if at all.
    </para>

    <para>
      Redacted form: <function>plflush()</function>
    </para>

    <para>
      This function is used in examples 1,14.
    </para>

  </sect1>

  <sect1 id="plfont" renderas="sect3">
    <title>
      <function>plfont</function>: Set character font
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plfont</function>
	  </funcdef>
	  <paramdef><parameter>ifont</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets the default character font for subsequent character drawing.
      Also affects symbols produced by &plpoin;.  This routine has no
      effect unless the extended character set is loaded (see &plfontld;).
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>ifont</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Specifies the font:
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal>1</literal>: Normal font (simplest and fastest)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>2</literal>: Roman font
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>3</literal>: Italic font
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>4</literal>: Script font
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plfont(ifont)</function>
    </para>

    <para>
      This function is used in examples 1,2,4,7,13,24,26.
    </para>

  </sect1>

  <sect1 id="plfontld" renderas="sect3">
    <title>
      <function>plfontld</function>: Load character font
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plfontld</function>
	  </funcdef>
	  <paramdef><parameter>fnt</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets the character set to use for subsequent character drawing.  May
      be called before initializing PLplot.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>fnt</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Specifies the character set to load:
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal>0</literal>: Standard character set
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>1</literal>: Extended character set
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plfontld(fnt)</function>
    </para>

    <para>
      This function is used in examples 1,7.
    </para>

  </sect1>

  <sect1 id="plgchr" renderas="sect3">
    <title>
      <function>plgchr</function>: Get character default height and current
      (scaled) height
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgchr</function>
	  </funcdef>
	  <paramdef><parameter>p_def</parameter></paramdef>
	  <paramdef><parameter>p_ht</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Get character default height and current (scaled) height.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>p_def</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to default character height (mm).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_ht</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to current (scaled) character height (mm).
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plgchr(p_def, p_ht)</function>
    </para>

    <para>
      This function is used in example 23.
    </para>

  </sect1>

  <sect1 id="plgcmap1_range" renderas="sect3">
    <title>
      <function>plgcmap1_range</function>: Get the cmap1 argument
      range for continuous color plots
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgcmap1_range</function>
	  </funcdef>
	  <paramdef><parameter>min_color</parameter></paramdef>
	  <paramdef><parameter>max_color</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Get the cmap1 argument range for continuous color plots.
      (Use &plscmap1_range; to set the cmap1 argument range.)
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>min_color</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to the current minimum cmap1 floating point argument.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>max_color</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to the current maximum cmap1 floating point argument.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plgcmap1_range(min_color, max_color)</function>
    </para>

    <para>
      This function is currently not used in any example.
    </para>

  </sect1>

  <sect1 id="plgcol0" renderas="sect3">
    <title>
      <function>plgcol0</function>: Returns 8-bit RGB values for given color
      index from cmap0
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgcol0</function>
	  </funcdef>
	  <paramdef><parameter>icol0</parameter></paramdef>
	  <paramdef><parameter>r</parameter></paramdef>
	  <paramdef><parameter>g</parameter></paramdef>
	  <paramdef><parameter>b</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Returns 8-bit RGB values (0-255) for given color from cmap0 (see
      <xref linkend="color-map-0"/>).  Values are
      negative if an invalid color id is given.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>icol0</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Index of desired cmap0 color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>r</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to 8-bit red value.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>g</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to 8-bit green value.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>b</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to 8-bit blue value.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plgcol0(icol0, r, g, b)</function>
    </para>

    <para>
      This function is used in example 2.
    </para>

  </sect1>

  <sect1 id="plgcol0a" renderas="sect3">
    <title>
      <function>plgcol0a</function>: Returns 8-bit RGB values and double alpha
      transparency value for given color index from cmap0
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgcol0a</function>
	  </funcdef>
	  <paramdef><parameter>icol0</parameter></paramdef>
	  <paramdef><parameter>r</parameter></paramdef>
	  <paramdef><parameter>g</parameter></paramdef>
	  <paramdef><parameter>b</parameter></paramdef>
	  <paramdef><parameter>alpha</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Returns 8-bit RGB values (0-255) and double alpha transparency value (0.0 - 1.0) for 
      given color from cmap0 (see <xref linkend="color-map-0"/>).  Values 
      are negative if an invalid color id is given.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>icol0</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Index of desired cmap0 color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>r</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to 8-bit red value.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>g</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to 8-bit green value.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>b</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to 8-bit blue value.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>alpha</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to PLFLT alpha transparency value.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      This function is used in example 30.
    </para>

  </sect1>

  <sect1 id="plgcolbg" renderas="sect3">
    <title>
      <function>plgcolbg</function>:  Returns the background color
      (cmap0[0]) by 8-bit RGB value
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgcolbg</function>
	  </funcdef>
	  <paramdef><parameter>r</parameter></paramdef>
	  <paramdef><parameter>g</parameter></paramdef>
	  <paramdef><parameter>b</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Returns the background color (cmap0[0]) by 8-bit RGB value.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>r</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to an unsigned 8-bit integer (0-255) representing
	    the degree of red in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>g</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to an unsigned 8-bit integer (0-255) representing
	    the degree of green in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>b</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to an unsigned 8-bit integer (0-255) representing
	    the degree of blue in the color.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plgcolbg(r, g, b)</function>
    </para>

    <para>
      This function is used in example 31.
    </para>

  </sect1>

  <sect1 id="plgcolbga" renderas="sect3">
    <title>
      <function>plgcolbga</function>:  Returns the background color (cmap0[0]) 
      by 8-bit RGB value and double alpha transparency value
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgcolbga</function>
	  </funcdef>
	  <paramdef><parameter>r</parameter></paramdef>
	  <paramdef><parameter>g</parameter></paramdef>
	  <paramdef><parameter>b</parameter></paramdef>
	  <paramdef><parameter>alpha</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Returns the background color (cmap0[0]) by 8-bit RGB value and double
      alpha transparency value.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>r</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to an unsigned 8-bit integer (0-255) representing
	    the degree of red in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>g</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to an unsigned 8-bit integer (0-255) representing
	    the degree of green in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>b</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to an unsigned 8-bit integer (0-255) representing
	    the degree of blue in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>alpha</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to PLFLT alpha transparency value.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      This function is used in example 31.
    </para>

  </sect1>

  <sect1 id="plgcompression" renderas="sect3">
    <title>
      <function>plgcompression</function>: Get the current
      device-compression setting
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgcompression</function>
	  </funcdef>
	  <paramdef><parameter>compression</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Get the current device-compression setting.  This parameter is
      only used for drivers that provide compression.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>compression</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to a variable to be filled with the current
	    device-compression setting.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plgcompression(compression)</function>
    </para>

    <para>
      This function is used in example 31.
    </para>

  </sect1>

  <sect1 id="plgdev" renderas="sect3">
    <title>
      <function>plgdev</function>: Get the current device (keyword) name
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgdev</function>
	  </funcdef>
	  <paramdef><parameter>p_dev</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Get the current device (keyword) name.  Note: you
      <emphasis>must</emphasis> have allocated
      space for this (80 characters is safe).
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>p_dev</parameter>
	  (<literal>char *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to device (keyword) name string.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plgdev(p_dev)</function>
    </para>

    <para>
      This function is used in example 14.
    </para>

  </sect1>

  <sect1 id="plgdidev" renderas="sect3">
    <title>
      <function>plgdidev</function>: Get parameters that define current
      device-space window
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgdidev</function>
	  </funcdef>
	  <paramdef><parameter>p_mar</parameter></paramdef>
	  <paramdef><parameter>p_aspect</parameter></paramdef>
	  <paramdef><parameter>p_jx</parameter></paramdef>
	  <paramdef><parameter>p_jy</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Get relative margin width, aspect ratio, and relative justification
      that define current device-space window.
      If &plsdidev; has not been called the default values pointed to by
      <literal><parameter>p_mar</parameter></literal>,
      <literal><parameter>p_aspect</parameter></literal>,
      <literal><parameter>p_jx</parameter></literal>, and
      <literal><parameter>p_jy</parameter></literal>
      will all be 0.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>p_mar</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to relative margin width.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_aspect</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to aspect ratio.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_jx</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to relative justification in x.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_jy</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to relative justification in y.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plgdidev(p_mar, p_aspect, p_jx, p_jy)</function>
    </para>

    <para>
      This function is used in example 31.
    </para>

  </sect1>

  <sect1 id="plgdiori" renderas="sect3">
    <title>
      <function>plgdiori</function>: Get plot orientation
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgdiori</function>
	  </funcdef>
	  <paramdef><parameter>p_rot</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Get plot orientation parameter which is multiplied by 90&deg; to
      obtain the angle of rotation.  Note, arbitrary rotation parameters
      such as 0.2 (corresponding to 18&deg;) are possible, but the usual
      values for the rotation parameter are 0., 1., 2., and 3. corresponding
      to 0&deg; (landscape mode), 90&deg; (portrait mode), 180&deg;
      (seascape mode), and 270&deg; (upside-down mode).
      If &plsdiori; has not been called the default value pointed to by
      <literal><parameter>p_rot</parameter></literal>
      will be 0.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>p_rot</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to orientation parameter.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plgdiori(p_rot)</function>
    </para>

    <para>
      This function is not used in any examples.
    </para>

  </sect1>

  <sect1 id="plgdiplt" renderas="sect3">
    <title>
      <function>plgdiplt</function>: Get parameters that define current
      plot-space window
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgdiplt</function>
	  </funcdef>
	  <paramdef><parameter>p_xmin</parameter></paramdef>
	  <paramdef><parameter>p_ymin</parameter></paramdef>
	  <paramdef><parameter>p_xmax</parameter></paramdef>
	  <paramdef><parameter>p_ymax</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Get relative minima and maxima that define current
      plot-space window.
      If &plsdiplt; has not been called the default values pointed to by
      <literal><parameter>p_xmin</parameter></literal>,
      <literal><parameter>p_ymin</parameter></literal>,
      <literal><parameter>p_xmax</parameter></literal>, and
      <literal><parameter>p_ymax</parameter></literal>
      will be 0., 0., 1., and 1.

    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>p_xmin</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to relative minimum in x.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_ymin</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to relative minimum in y.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_xmax</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to relative maximum in x.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_ymax</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to relative maximum in y.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plgdiplt(p_xmin, p_ymin, p_xmax, p_ymax)</function>
    </para>

    <para>
      This function is used in example 31.
    </para>

  </sect1>

  <sect1 id="plgdrawmode" renderas="sect3">
    <title>
      <function>plgdrawmode</function>: Get drawing mode (depends on
device support!)
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgdrawmode</function>
	  </funcdef>
	  <paramdef></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Get drawing mode.  Note only one device driver (cairo) currently
      supports this at the moment, and for that case the PLINT value
      returned by this function is one of
      <literal>PL_DRAWMODE_DEFAULT</literal>,
      <literal>PL_DRAWMODE_REPLACE</literal>,
      <literal>PL_DRAWMODE_XOR</literal>, or
      <literal>PL_DRAWMODE_UNKNOWN</literal>. This function returns
      <literal>PL_DRAWMODE_UNKNOWN</literal> for the rest of the
      device drivers.  See also &plsdrawmode;.
    </para>

    <para>
      Redacted form: <function>plgdrawmode()</function>
    </para>

    <para>
      This function is used in example 34.
    </para>

  </sect1>

  <sect1 id="plgfam" renderas="sect3">
    <title>
      <function>plgfam</function>: Get family file parameters
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgfam</function>
	  </funcdef>
	  <paramdef><parameter>p_fam</parameter></paramdef>
	  <paramdef><parameter>p_num</parameter></paramdef>
	  <paramdef><parameter>p_bmax</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Gets information about current family file, if familying is
      enabled.  See <xref linkend="familying"/> for more information.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>p_fam</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to variable with the Boolean family flag value.  If
	    nonzero, familying is enabled.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_num</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to variable with the current family file number.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_bmax</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to variable with the maximum file size (in bytes) for a
	    family file.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plgfam(p_fam, p_num, p_bmax)</function>
    </para>

    <para>
      This function is used in examples 14,31.
    </para>

  </sect1>

  <sect1 id="plgfci" renderas="sect3">
    <title>
      <function>plgfci</function>: Get FCI (font characterization integer)
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgfci</function>
	  </funcdef>
	  <paramdef><parameter>p_fci</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Gets information about the current font using the FCI approach.
      See <xref linkend="fci"/> for more information.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>p_fci</parameter>
	  (<literal>PLUNICODE *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to PLUNICODE (unsigned 32-bit integer) variable which
	    is updated with current FCI value.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plgfci(p_fci)</function>
    </para>

    <para>
      This function is used in example 23.
    </para>

  </sect1>

  <sect1 id="plgfnam" renderas="sect3">
    <title>
      <function>plgfnam</function>: Get output file name
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgfnam</function>
	  </funcdef>
	  <paramdef><parameter>fnam</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Gets the current output file name, if applicable.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>fnam</parameter>
	  (<literal>char *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to file name string (a preallocated string of 80 characters or more).
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plgfnam(fnam)</function>
    </para>

    <para>
      This function is used in example 31.
    </para>

  </sect1>

  <sect1 id="plgfont" renderas="sect3">
    <title>
      <function>plgfont</function>: Get family, style and weight of the
      current font
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgfont</function>
	  </funcdef>
	  <paramdef><parameter>p_family</parameter></paramdef>
	  <paramdef><parameter>p_style</parameter></paramdef>
	  <paramdef><parameter>p_weight</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Gets information about current font.  See <xref
      linkend="fci"/> for more information on font selection.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>p_family</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to variable with the current font family. The available
	    values are given by the PL_FCI_* constants in
	    plplot.h. Current options are PL_FCI_SANS, PL_FCI_SERIF,
	    PL_FCI_MONO, PL_FCI_SCRIPT and PL_FCI_SYMBOL. If
	    p_family is NULL then the font family is not returned.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_style</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to variable with the current font style. The available
	    values are given by the PL_FCI_* constants in
	    plplot.h. Current options are PL_FCI_UPRIGHT, PL_FCI_ITALIC 
	    and PL_FCI_OBLIQUE. If
	    p_style is NULL then the font style is not returned.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_weight</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to variable with the current font weight. The available
	    values are given by the PL_FCI_* constants in
	    plplot.h. Current options are PL_FCI_MEDIUM and
	    PL_FCI_BOLD. If
	    p_weight is NULL then the font weight is not returned.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plgfont(p_family, p_style, p_weight)</function>
    </para>

    <para>
      This function is used in example 23.
    </para>

  </sect1>


  <sect1 id="plglevel" renderas="sect3">
    <title>
      <function>plglevel</function>: Get the (current) run level
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plglevel</function>
	  </funcdef>
	  <paramdef><parameter>p_level</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Get the (current) run level. Valid settings are:
      <itemizedlist>
	<listitem>
	  <para>
	    0,  uninitialized
	  </para>
	</listitem>
	<listitem>
	  <para>
	    1,  initialized
	  </para>
	</listitem>
	<listitem>
	  <para>
	    2,  viewport defined
	  </para>
	</listitem>
	<listitem>
	  <para>
	    3,  world coordinates defined
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>p_level</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to the run level.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plglevel(p_level)</function>
    </para>

    <para>
      This function is used in example 31.
    </para>

  </sect1>

  <sect1 id="plgpage" renderas="sect3">
    <title>
      <function>plgpage</function>: Get page parameters
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgpage</function>
	  </funcdef>
	  <paramdef><parameter>p_xp</parameter></paramdef>
	  <paramdef><parameter>p_yp</parameter></paramdef>
	  <paramdef><parameter>p_xleng</parameter></paramdef>
	  <paramdef><parameter>p_yleng</parameter></paramdef>
	  <paramdef><parameter>p_xoff</parameter></paramdef>
	  <paramdef><parameter>p_yoff</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Gets the current page configuration. The length and offset values are expressed
      in units that are specific to the current driver. For instance:
      screen drivers will usually interpret them as number of pixels,
      whereas printer drivers will usually use mm.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>p_xp</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to number of pixels/inch (DPI), x.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_yp</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to number of pixels/inch (DPI) in y.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_xleng</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to x page length value.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_yleng</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to y page length value.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_xoff</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to x page offset.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_yoff</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to y page offset.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plgpage(p_xp, p_yp, p_xleng, p_yleng, p_xoff, p_yoff)</function>
    </para>

    <para>
      This function is used in examples 14 and 31.
    </para>

  </sect1>

  <sect1 id="plgra" renderas="sect3">
    <title>
      <function>plgra</function>: Switch to graphics screen
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgra</function>
	  </funcdef>
	  <paramdef></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets an interactive device to graphics mode, used in conjunction with
      &pltext; to allow graphics and text to be interspersed.  On a device
      which supports separate text and graphics windows, this command
      causes control to be switched to the graphics window.  If already in
      graphics mode, this command is ignored.  It is also ignored on
      devices which only support a single window or use a different method
      for shifting focus.  See also &pltext;.
    </para>

    <para>
      Redacted form: <function>plgra()</function>
    </para>

    <para>
      This function is used in example 1.
    </para>

  </sect1>

  <sect1 id="plgradient" renderas="sect3">
    <title>
      <function>plgradient</function>: Draw linear gradient inside polygon
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgradient</function>
	  </funcdef>
	  <paramdef><parameter>n</parameter></paramdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>angle</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Draw a linear gradient using colour map 1 inside the polygon
      defined by the <literal><parameter>n</parameter></literal> points
      <literal>(<parameter>x</parameter>[i],
      <parameter>y</parameter>[i])</literal>.  Interpretation of the polygon
      is the same as for &plfill;.  The polygon coordinates and the gradient
      angle are all expressed in world coordinates.  The angle from the
      <literal><parameter>x</parameter></literal> axis for both the rotated
      coordinate system and the gradient vector is specified by
      <literal><parameter>angle</parameter></literal>.  The magnitude of the
      gradient vector is the difference between the maximum and minimum
      values of <literal><parameter>x</parameter></literal> for the vertices
      in the rotated coordinate system.  The origin of the gradient vector
      can be interpreted as being anywhere on the line corresponding to the
      minimum <literal><parameter>x</parameter></literal> value for the
      vertices in the rotated coordinate system.  The distance along the gradient
      vector is linearly transformed to the independent variable of colour
      map 1 which ranges from 0. at the tail of the gradient vector to 1. at
      the head of the gradient vector.  What is drawn is the RGBA colour
      corresponding to the independent variable of colour map 1.  For more
      information about colour map 1 (see <xref linkend="color-map-1"/>).
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>n</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of vertices in polygon.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with x coordinates of vertices.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with y coordinates of vertices.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>angle</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Angle (degrees) of gradient vector from x axis.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plgradient(x,y,angle)</function>
    </para>

    <para>
      This function is used in examples 25,30.
    </para>

  </sect1>

  <sect1 id="plgriddata" renderas="sect3">
    <title>
      <function>plgriddata</function>: Grid data from irregularly sampled
      data
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgriddata</function>
	  </funcdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>z</parameter></paramdef>
	  <paramdef><parameter>npts</parameter></paramdef>
	  <paramdef><parameter>xg</parameter></paramdef>
	  <paramdef><parameter>nptsx</parameter></paramdef>
	  <paramdef><parameter>yg</parameter></paramdef>
	  <paramdef><parameter>nptsy</parameter></paramdef>
	  <paramdef><parameter>zg</parameter></paramdef>
	  <paramdef><parameter>type</parameter></paramdef>
	  <paramdef><parameter>data</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Real world data is frequently irregularly sampled, but all PLplot 3D
      plots require data placed in a uniform grid. This function takes
      irregularly sampled data from three input arrays
      <literal>x[npts]</literal>, <literal>y[npts]</literal>, and
      <literal>z[npts]</literal>, reads the desired grid location from
      input arrays <literal>xg[nptsx]</literal> and
      <literal>yg[nptsy]</literal>, and returns the gridded data into
      output array <literal>zg[nptsx][nptsy]</literal>.  The algorithm used
      to grid the data is specified with the argument
      <literal>type</literal> which can have one parameter specified in
      argument <literal>data</literal>.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    The input <literal>x</literal> array.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    The input <literal>y</literal> array.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>z</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    The input <literal>z</literal> array. Each triple
	    <literal>x[i]</literal>, <literal>y[i]</literal>,
	    <literal>z[i]</literal> represents one data sample coordinate.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>npts</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The number of data samples in the <literal>x</literal>,
	    <literal>y</literal> and <literal>z</literal> arrays.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xg</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    The input array that specifies the grid spacing in the x
	    direction. Usually <literal>xg</literal> has
	    <literal>nptsx</literal> equally spaced values from the minimum
	    to the maximum values of the <literal>x</literal> input array.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nptsx</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The number of points in the <literal>xg</literal> array.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>yg</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    The input array that specifies the grid spacing in the y
	    direction. Similar to the <literal>xg</literal> parameter.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nptsy</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The number of points in the <literal>yg</literal> array.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>zg</parameter>
	  (<literal>PLFLT **</literal>, output)
	</term>
	<listitem>
	  <para>
	    The output array, where data lies in the regular grid
	    specified by <literal>xg</literal> and <literal>yg.</literal>
	    the <literal>zg</literal> array must exist or be allocated by
	    the user prior to the call, and must have dimension
	    <literal>zg[nptsx][nptsy]</literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>type</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The type of gridding algorithm to use, which can be:
	  </para>
	  <itemizedlist>
	    <listitem>
	      <para>
		<literal>GRID_CSA</literal>: Bivariate Cubic Spline
		approximation
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<literal>GRID_DTLI</literal>: Delaunay Triangulation Linear
		Interpolation
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<literal>GRID_NNI</literal>: Natural Neighbors Interpolation
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<literal>GRID_NNIDW</literal>: Nearest Neighbors Inverse
		Distance Weighted
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<literal>GRID_NNLI</literal>: Nearest Neighbors Linear
		Interpolation
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<literal>GRID_NNAIDW</literal>:  Nearest Neighbors Around
		Inverse Distance Weighted
	      </para>
	    </listitem>
	  </itemizedlist>
	  <para>
	    For details of the algorithms read the source file
	    <filename>plgridd.c</filename>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>data</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Some gridding algorithms require extra data, which can be
	    specified through this argument. Currently, for algorithm:
	  </para>
	  <itemizedlist>
	    <listitem>
	      <para>
		<literal>GRID_NNIDW</literal>, <literal>data</literal>
		specifies the number of neighbors to use, the lower the
		value, the noisier (more local) the approximation is.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<literal>GRID_NNLI</literal>, <literal>data</literal>
		specifies what a thin triangle is, in the range
		[1. .. 2.]. High values enable the usage of very thin
		triangles for interpolation, possibly resulting in error in
		the approximation.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<literal>GRID_NNI</literal>, only weights greater than
		<literal>data</literal> will be accepted. If 0, all weights
		will be accepted.
	      </para>
	    </listitem>
	  </itemizedlist>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plgriddata(x, y, z, xg, yg, zg, type, data)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: Not available?
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Python: <literal><parameter>zg</parameter>=<function>plgriddata(x, y, z, xg, yg, type, data)</function></literal>
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in example 21.
    </para>

  </sect1>

  <sect1 id="plgspa" renderas="sect3">
    <title>
      <function>plgspa</function>: Get current subpage parameters
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgspa</function>
	  </funcdef>
	  <paramdef><parameter>xmin</parameter></paramdef>
	  <paramdef><parameter>xmax</parameter></paramdef>
	  <paramdef><parameter>ymin</parameter></paramdef>
	  <paramdef><parameter>ymax</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Gets the size of the current subpage in millimeters measured from the
      bottom left hand corner of the output device page or screen.  Can be
      used in conjunction with &plsvpa; for setting the size of a viewport
      in absolute coordinates (millimeters).
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>xmin</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to variable with position of left hand edge of subpage
	    in millimeters.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xmax</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to variable with position of right hand edge of subpage
	    in millimeters.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymin</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to variable with position of bottom edge of subpage in
	    millimeters.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymax</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to variable with position of top edge of subpage in
	    millimeters.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plgspa(xmin, xmax, ymin, ymax)</function>
    </para>

    <para>
      This function is used in example 23.
    </para>

  </sect1>

  <sect1 id="plgstrm" renderas="sect3">
    <title>
      <function>plgstrm</function>: Get current stream number
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgstrm</function>
	  </funcdef>
	  <paramdef><parameter>p_strm</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Gets the number of the current output stream. See also &plsstrm;.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>p_strm</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to current stream value.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plgstrm(p_strm)</function>
    </para>

    <para>
      This function is used in example 1,20.
    </para>

  </sect1>

  <sect1 id="plgver" renderas="sect3">
    <title>
      <function>plgver</function>: Get the current library version number
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgver</function>
	  </funcdef>
	  <paramdef><parameter>p_ver</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Get the current library version number.  Note: you <emphasis>must</emphasis>
      have allocated space for this (80 characters is safe).
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>p_ver</parameter>
	  (<literal>char *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to the current library version number.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plgver(p_ver)</function>
    </para>

    <para>
      This function is used in example 1.
    </para>

  </sect1>

  <sect1 id="plgvpd" renderas="sect3">
    <title>
      <function>plgvpd</function>: Get viewport limits in normalized
      device coordinates
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgvpd</function>
	  </funcdef>
	  <paramdef><parameter>p_xmin</parameter></paramdef>
	  <paramdef><parameter>p_xmax</parameter></paramdef>
	  <paramdef><parameter>p_ymin</parameter></paramdef>
	  <paramdef><parameter>p_ymax</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Get viewport limits in normalized device coordinates.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>p_xmin</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Lower viewport limit of the normalized device coordinate in x.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_xmax</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Upper viewport limit of the normalized device coordinate in x.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_ymin</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Lower viewport limit of the normalized device coordinate in y.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_ymax</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Upper viewport limit of the normalized device coordinate in y.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plgvpd(p_xmin, p_xmax, p_ymin, p_ymax)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: Not available?
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in example 31.
    </para>

  </sect1>

  <sect1 id="plgvpw" renderas="sect3">
    <title>
      <function>plgvpw</function>: Get viewport limits in world coordinates
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgvpw</function>
	  </funcdef>
	  <paramdef><parameter>p_xmin</parameter></paramdef>
	  <paramdef><parameter>p_xmax</parameter></paramdef>
	  <paramdef><parameter>p_ymin</parameter></paramdef>
	  <paramdef><parameter>p_ymax</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Get viewport limits in world coordinates.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>p_xmin</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Lower viewport limit of the world coordinate in x.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_xmax</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Upper viewport limit of the world coordinate in x.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_ymin</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Lower viewport limit of the world coordinate in y.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_ymax</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Upper viewport limit of the world coordinate in y.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plgvpw(p_xmin, p_xmax, p_ymin, p_ymax)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: Not available?
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in example 31.
    </para>

  </sect1>

  <sect1 id="plgxax" renderas="sect3">
    <title>
      <function>plgxax</function>: Get x axis parameters
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgxax</function>
	  </funcdef>
	  <paramdef><parameter>p_digmax</parameter></paramdef>
	  <paramdef><parameter>p_digits</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Returns current values of the
      <literal><parameter>p_digmax</parameter></literal> and
      <literal><parameter>p_digits</parameter></literal> flags for the x
      axis.  <literal><parameter>p_digits</parameter></literal> is updated
      after the plot is drawn, so this routine should only be called
      <emphasis>after</emphasis> the call to &plbox; (or &plbox3;) is
      complete.  See <xref linkend="annotation"/> for more information.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>p_digmax</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to variable with the maximum number of digits for the x axis.  If
	    nonzero, the printed label has been switched to a floating point
	    representation when the number of digits exceeds
	    <literal><parameter>p_digmax</parameter></literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_digits</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to variable with the actual number of digits for the
	    numeric labels (x axis) from the last plot.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plgxax(p_digmax, p_digits)</function>
    </para>

    <para>
      This function is used in example 31.
    </para>

  </sect1>

  <sect1 id="plgyax" renderas="sect3">
    <title>
      <function>plgyax</function>: Get y axis parameters
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgyax</function>
	  </funcdef>
	  <paramdef><parameter>p_digmax</parameter></paramdef>
	  <paramdef><parameter>p_digits</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Identical to &plgxax;, except that arguments are flags for y axis.
      See the description of &plgxax; for more detail.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>p_digmax</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to variable with the maximum number of digits for the y axis.  If
	    nonzero, the printed label has been switched to a floating point
	    representation when the number of digits exceeds
	    <literal><parameter>p_digmax</parameter></literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_digits</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to variable with the actual number of digits for the
	    numeric labels (y axis) from the last plot.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plgyax(p_digmax, p_digits)</function>
    </para>

    <para>
      This function is used in example 31.
    </para>

  </sect1>

  <sect1 id="plgzax" renderas="sect3">
    <title>
      <function>plgzax</function>: Get z axis parameters
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plgzax</function>
	  </funcdef>
	  <paramdef><parameter>p_digmax</parameter></paramdef>
	  <paramdef><parameter>p_digits</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Identical to &plgxax;, except that arguments are flags for z axis.
      See the description of &plgxax; for more detail.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>p_digmax</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to variable with the maximum number of digits for the z axis.  If
	    nonzero, the printed label has been switched to a floating point
	    representation when the number of digits exceeds
	    <literal><parameter>p_digmax</parameter></literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_digits</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to variable with the actual number of digits for the
	    numeric labels (z axis) from the last plot.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plgzax(p_digmax, p_digits)</function>
    </para>

    <para>
      This function is used in example 31.
    </para>

  </sect1>

  <sect1 id="plhist" renderas="sect3">
    <title>
      <function>plhist</function>: Plot a histogram from unbinned data
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plhist</function>
	  </funcdef>
	  <paramdef><parameter>n</parameter></paramdef>
	  <paramdef><parameter>data</parameter></paramdef>
	  <paramdef><parameter>datmin</parameter></paramdef>
	  <paramdef><parameter>datmax</parameter></paramdef>
	  <paramdef><parameter>nbin</parameter></paramdef>
	  <paramdef><parameter>opt</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Plots a histogram from <literal><parameter>n</parameter></literal>
      data points stored in the array
      <literal><parameter>data</parameter></literal>.  This routine bins
      the data into <literal><parameter>nbin</parameter></literal> bins
      equally spaced between
      <literal><parameter>datmin</parameter></literal> and
      <literal><parameter>datmax</parameter></literal>, and calls &plbin;
      to draw the resulting histogram.  Parameter
      <literal><parameter>opt</parameter></literal> allows, among
      other things, the histogram either to be plotted in an existing window
      or causes &plhist; to call &plenv; with suitable limits before plotting
      the histogram.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>n</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of data points.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>data</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with values of the
	    <literal><parameter>n</parameter></literal> data points.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>datmin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Left-hand edge of lowest-valued bin.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>datmax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Right-hand edge of highest-valued bin.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nbin</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of (equal-sized) bins into which to divide the interval
	    <literal><parameter>xmin</parameter></literal> to
	    <literal><parameter>xmax</parameter></literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>opt</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Is a combination of several flags:
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=PL_HIST_DEFAULT</literal>:
		  The axes are automatically rescaled to fit the histogram data,
		  the outer bins are expanded to fill up the entire x-axis,
		  data outside the given extremes are assigned to the outer
		  bins and bins of zero height are simply drawn.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=PL_HIST_NOSCALING|...</literal>:
		  The existing axes are not rescaled to fit the histogram data,
		  without this flag, &plenv; is called to set the world coordinates.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=PL_HIST_IGNORE_OUTLIERS|...</literal>:
		  Data outside the given extremes are not taken into account.
		  This option should probably be combined with
		  <literal><parameter>opt</parameter>=PL_HIST_NOEXPAND|...</literal>,
		  so as to properly present the data.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=PL_HIST_NOEXPAND|...</literal>:
		  The outer bins are drawn with equal size as the ones inside.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=PL_HIST_NOEMPTY|...</literal>:
		  Bins with zero height are not drawn (there is a gap for
		  such bins).
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plhist(data, datmin, datmax, nbin, opt)</function>
    </para>

    <para>
      This function is used in example 5.
    </para>

  </sect1>

  <sect1 id="plhlsrgb" renderas="sect3">
    <title>
      <function>plhlsrgb</function>: Convert HLS color to RGB
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plhlsrgb</function>
	  </funcdef>
	  <paramdef><parameter>h</parameter></paramdef>
	  <paramdef><parameter>l</parameter></paramdef>
	  <paramdef><parameter>s</parameter></paramdef>
	  <paramdef><parameter>p_r</parameter></paramdef>
	  <paramdef><parameter>p_g</parameter></paramdef>
	  <paramdef><parameter>p_b</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Convert HLS color coordinates to RGB.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>h</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Hue, in degrees on the colour cone (0.0-360.0)
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>l</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Lightness, expressed as a fraction of the axis of the colour
	    cone (0.0-1.0)
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>s</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Saturation, expressed as a fraction of the radius of the
	    colour cone (0.0-1.0)
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_r</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to red intensity (0.0-1.0) of the colour
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_g</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to green intensity (0.0-1.0) of the colour
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_b</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to blue intensity (0.0-1.0) of the colour
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plhlsrgb(h, l, s, p_r, p_g, p_b)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: Not available? Implemented as plhls?
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in example 2.
    </para>

  </sect1>

  <sect1 id="plimagefr" renderas="sect3">
    <title>
      <function>plimagefr</function>: Plot a 2D matrix using cmap1
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plimagefr</function>
	  </funcdef>
	  <paramdef><parameter>idata</parameter></paramdef>
	  <paramdef><parameter>nx</parameter></paramdef>
	  <paramdef><parameter>ny</parameter></paramdef>
	  <paramdef><parameter>xmin</parameter></paramdef>
	  <paramdef><parameter>xmax</parameter></paramdef>
	  <paramdef><parameter>ymin</parameter></paramdef>
	  <paramdef><parameter>ymax</parameter></paramdef>
	  <paramdef><parameter>zmin</parameter></paramdef>
	  <paramdef><parameter>zmax</parameter></paramdef>
	  <paramdef><parameter>valuemin</parameter></paramdef>
	  <paramdef><parameter>valuemax</parameter></paramdef>
	  <paramdef><parameter>pltr</parameter></paramdef>
	  <paramdef><parameter>pltr_data</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Plot a 2D matrix using cmap1.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>idata</parameter>
	  (<literal>const PLFLT * const *</literal>, input)
	</term>
	<listitem>
	  <para>
	    A 2D array of values (intensities) to plot.  Should have
	    dimensions idata[nx][ny].
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nx, ny</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Dimensions of idata
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xmin, xmax, ymin, ymax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Stretch image data to these Plot coordinates.  idata[0][0]
	    corresponds to (xmin, ymin) and idata[nx - 1][ny - 1] corresponds
	    to (xmax, ymax).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>zmin, zmax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Only data between zmin and zmax (inclusive) will be plotted.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>valuemin, valuemax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The minimum and maximum data values to use for value to color
	    mappings.  A datum equal to or less than valuemin will be
	    plotted with color 0.0, while a datum equal to or greater than
	    valuemax will be plotted with color 1.0.  Data between valuemin
	    and valuemax map linearly to colors between 0.0 and 1.0.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>pltr</parameter>
	  (<literal>void (*) (PLFLT, PLFLT, PLFLT *, PLFLT *, PLPointer)
	  </literal>, input)
	</term>
	<listitem>
	  <para>
            Pointer to function that defines a transformation between the data
            in the array <literal><parameter>idata</parameter></literal> and
            world coordinates.  An input coordinate of
            <literal>(0, 0)</literal> corresponds to the "top-left" corner of
            <literal><parameter>idata</parameter></literal> while
            <literal>(nx, ny)</literal> corresponds to the "bottom-right"
            corner of <literal><parameter>idata</parameter></literal>.  Some
            transformation functions are provided in the PLplot library:
            &pltr0; for identity mapping, and &pltr1; and &pltr2; for
            arbitrary mappings respectively defined by one- and
            two-dimensional arrays.  In addition, user-supplied routines for
            the transformation can be used as well.  Examples of all of these
            approaches are given in <xref linkend="contour-plots-c"/>.  The
            transformation function should have the form given by any of
            &pltr0;, &pltr1;, or &pltr2;.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>pltr_data</parameter>
	  (<literal>PLPointer</literal>, input)
	</term>
	<listitem>
	  <para>
	    Extra parameter to help
	    pass information to &pltr0;, &pltr1;, &pltr2;, or whatever routine
	    is externally supplied.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General:
	    <function>
	      plimagefr(idata, xmin, xmax, ymin, ymax,
	      zmin, zmax, valuemin, valuemax, pltr, pltr_data)
	    </function>
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in example 20.
    </para>

  </sect1>

  <sect1 id="plimage" renderas="sect3">
    <title>
      <function>plimage</function>: Plot a 2D matrix using cmap1 with
      automatic colour adjustment
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plimage</function>
	  </funcdef>
	  <paramdef><parameter>idata</parameter></paramdef>
	  <paramdef><parameter>nx</parameter></paramdef>
	  <paramdef><parameter>ny</parameter></paramdef>
	  <paramdef><parameter>xmin</parameter></paramdef>
	  <paramdef><parameter>xmax</parameter></paramdef>
	  <paramdef><parameter>ymin</parameter></paramdef>
	  <paramdef><parameter>ymax</parameter></paramdef>
	  <paramdef><parameter>zmin</parameter></paramdef>
	  <paramdef><parameter>zmax</parameter></paramdef>
	  <paramdef><parameter>Dxmin</parameter></paramdef>
	  <paramdef><parameter>Dxmax</parameter></paramdef>
	  <paramdef><parameter>Dymin</parameter></paramdef>
	  <paramdef><parameter>Dymax</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Plot a 2D matrix using color palette 1.  The color scale is
      automatically adjusted to use the maximum and minimum values in
      idata as valuemin and valuemax in a call to &plimagefr;.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>idata</parameter>
	  (<literal>const PLFLT * const *</literal>, input)
	</term>
	<listitem>
	  <para>
	    A 2D array of values (intensities) to plot.  Should have
	    dimensions idata[nx][ny].
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nx, ny</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Dimensions of idata
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xmin, xmax, ymin, ymax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Plot coordinates to stretch the image data to.  idata[0][0]
	    corresponds to (xmin, ymin) and idata[nx - 1][ny - 1] corresponds
	    to (xmax, ymax).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>zmin, zmax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Only data between zmin and zmax (inclusive) will be plotted.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>Dxmin, Dxmax, Dymin, Dymax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Plot only the window of points whose plot coordinates fall inside
	    the window of (Dxmin, Dymin) to (Dxmax, Dymax).
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General:
	    <function>
	      plimage(idata, xmin, xmax, ymin, ymax,
	      zmin, zmax, Dxmin, Dxmax, Dymin, Dymax)
	    </function>
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in example 20.
    </para>

  </sect1>

  <sect1 id="plinit" renderas="sect3">
    <title>
      <function>plinit</function>: Initialize PLplot
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plinit</function>
	  </funcdef>
	  <paramdef></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Initializing the plotting package.  The program prompts for the
      device keyword or number of the desired output device.  Hitting a
      RETURN in response to the prompt is the same as selecting the first
      device.  &plinit; will issue no prompt if either the device was
      specified previously (via command line flag, the &plsetopt; function,
      or the &plsdev; function), or if only one device is
      enabled when PLplot is installed.  If subpages have been specified,
      the output device is divided into <literal>nx</literal> by
      <literal>ny</literal> subpages, each of which may be used
      independently.  If &plinit; is called again during a program, the
      previously opened file will be closed.  The subroutine &pladv; is
      used to advance from one subpage to the next.
    </para>

    <para>
      Redacted form: <function>plinit()</function>
    </para>

    <para>
      This function is used in all of the examples.
    </para>

  </sect1>

  <sect1 id="pljoin" renderas="sect3">
    <title>
      <function>pljoin</function>: Draw a line between two points
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>pljoin</function>
	  </funcdef>
	  <paramdef><parameter>x1</parameter></paramdef>
	  <paramdef><parameter>y1</parameter></paramdef>
	  <paramdef><parameter>x2</parameter></paramdef>
	  <paramdef><parameter>y2</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Joins the point <literal>(<parameter>x1</parameter>,
      <parameter>y1</parameter>)</literal> to
      <literal>(<parameter>x2</parameter>,
      <parameter>y2</parameter>)</literal>.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>x1</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    x coordinate of first point.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y1</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    y coordinate of first point.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>x2</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    x coordinate of second point.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y2</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    y coordinate of second point.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>pljoin(x1,y1,x2,y2)</function>
    </para>

    <para>
      This function is used in examples 3,14.
    </para>

  </sect1>

  <sect1 id="pllab" renderas="sect3">
    <title>
      <function>pllab</function>: Simple routine to write labels
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>pllab</function>
	  </funcdef>
	  <paramdef><parameter>xlabel</parameter></paramdef>
	  <paramdef><parameter>ylabel</parameter></paramdef>
	  <paramdef><parameter>tlabel</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Routine for writing simple labels. Use &plmtex; for more complex
      labels.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>xlabel</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Label for horizontal axis.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ylabel</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Label for vertical axis.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>tlabel</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Title of graph.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>pllab(xlabel, ylabel, tlabel)</function>
    </para>

    <para>
      This function is used in examples 1,5,9,12,14-16,20-22,29.
    </para>

  </sect1>

  <sect1 id="pllegend" renderas="sect3">
    <title>
      <function>pllegend</function>: Plot legend using discretely annotated filled boxes, lines, and/or lines of symbols
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>pllegend</function>
	  </funcdef>
	  <paramdef><parameter>p_legend_width</parameter></paramdef>
	  <paramdef><parameter>p_legend_height</parameter></paramdef>
	  <paramdef><parameter>opt</parameter></paramdef>
	  <paramdef><parameter>position</parameter></paramdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>plot_width</parameter></paramdef>
	  <paramdef><parameter>bg_color</parameter></paramdef>
	  <paramdef><parameter>bb_color</parameter></paramdef>
	  <paramdef><parameter>bb_style</parameter></paramdef>
	  <paramdef><parameter>nrow</parameter></paramdef>
	  <paramdef><parameter>ncolumn</parameter></paramdef>
	  <paramdef><parameter>nlegend</parameter></paramdef>
	  <paramdef><parameter>opt_array</parameter></paramdef>
	  <paramdef><parameter>text_offset</parameter></paramdef>
	  <paramdef><parameter>text_scale</parameter></paramdef>
	  <paramdef><parameter>text_spacing</parameter></paramdef>
	  <paramdef><parameter>test_justification</parameter></paramdef>
	  <paramdef><parameter>text_colors</parameter></paramdef>
	  <paramdef><parameter>text</parameter></paramdef>
	  <paramdef><parameter>box_colors</parameter></paramdef>
	  <paramdef><parameter>box_patterns</parameter></paramdef>
	  <paramdef><parameter>box_scales</parameter></paramdef>
	  <paramdef><parameter>box_line_widths</parameter></paramdef>
	  <paramdef><parameter>line_colors</parameter></paramdef>
	  <paramdef><parameter>line_styles</parameter></paramdef>
	  <paramdef><parameter>line_widths</parameter></paramdef>
	  <paramdef><parameter>symbol_colors</parameter></paramdef>
	  <paramdef><parameter>symbol_scales</parameter></paramdef>
	  <paramdef><parameter>symbol_numbers</parameter></paramdef>
	  <paramdef><parameter>symbols</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Routine for creating a discrete plot legend with a plotted
      filled box, line, and/or line of symbols for each annotated legend
      entry.  (See &plcolorbar; for similar functionality for creating
      continuous color bars.)  The arguments of pllegend provide control
      over the location and size of the legend as well as the location and
      characteristics of the elements (most of which are optional) within
      that legend.  The resulting legend is clipped at the boundaries of the
      current subpage.  (N.B. the adopted coordinate system used for some of
      the parameters is defined in the documentation of the
      <literal><parameter>position</parameter></literal> parameter.)
    </para>
    <variablelist>
      <varlistentry>
	<term>
	  <parameter>p_legend_width</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to a location which contains (after the call) the
	    legend width in adopted coordinates. This quantity is
	    calculated from <literal><parameter>plot_width</parameter></literal>,
	    <literal><parameter>text_offset</parameter></literal>,
	    <literal><parameter>ncolumn</parameter></literal> (possibly modified
	    inside the routine depending on
	    <literal><parameter>nlegend</parameter></literal> and
	    <literal><parameter>nrow</parameter></literal>), and the length
	    (calculated internally) of the longest text string.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_legend_height</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to a location which contains (after the call) the
	    legend height in adopted coordinates. This quantity is
	    calculated from <literal><parameter>text_scale</parameter></literal>,
	    <literal><parameter>text_spacing</parameter></literal>, and
	    <literal><parameter>nrow</parameter></literal> (possibly modified
	    inside the routine depending on
	    <literal><parameter>nlegend</parameter></literal> and
	    <literal><parameter>nrow</parameter></literal>).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>opt</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    <literal><parameter>opt</parameter></literal> contains
	    bits controlling the overall legend. If the
	    <literal>PL_LEGEND_TEXT_LEFT</literal> bit is set, put the text area
	    on the left of the legend and the plotted area on the
	    right. Otherwise, put the text area on the right of the legend and the
	    plotted area on the left. If the
	    <literal>PL_LEGEND_BACKGROUND</literal> bit is set, plot a
	    (semi-transparent) background for the legend. If the
	    <literal>PL_LEGEND_BOUNDING_BOX</literal> bit is set, plot a bounding
	    box for the legend. If the <literal>PL_LEGEND_ROW_MAJOR</literal> bit
	    is set and (both of the possibly internally transformed)
	    <literal><parameter>nrow</parameter></literal> &gt; 1 and
	    <literal><parameter>ncolumn</parameter></literal> &gt; 1, then plot
	    the resulting array of legend entries in row-major order.
	    Otherwise, plot the legend entries in column-major order.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>position</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    <literal><parameter>position</parameter></literal>
	    contains bits which control the overall position of the legend and the
	    definition of the adopted coordinates used for positions just like
	    what is done for the position argument for &plcolorbar;. However,
	    note that the defaults for the position bits (see below) are
	    different than the &plcolorbar; case.  The combination of the
	    <literal>PL_POSITION_LEFT</literal>,
	    <literal>PL_POSITION_RIGHT</literal>,
	    <literal>PL_POSITION_TOP</literal>,
	    <literal>PL_POSITION_BOTTOM</literal>,
	    <literal>PL_POSITION_INSIDE</literal>, and
	    <literal>PL_POSITION_OUTSIDE</literal> bits specifies one of the 16
	    possible standard positions (the 4 corners and centers of the 4 sides
	    for both the inside and outside cases) of the legend relative to the
	    adopted coordinate system. The corner positions are specified by the
	    appropriate combination of two of the
	    <literal>PL_POSITION_LEFT</literal>,
	    <literal>PL_POSITION_RIGHT</literal>,
	    <literal>PL_POSITION_TOP</literal>, and
	    <literal>PL_POSITION_BOTTOM</literal> bits while the sides are
	    specified by a single value of one of those bits.  The adopted
	    coordinates are normalized viewport coordinates if the
	    <literal>PL_POSITION_VIEWPORT</literal> bit is set or normalized
	    subpage coordinates if the <literal>PL_POSITION_SUBPAGE</literal> bit
	    is set. Default position bits: If none of
	    <literal>PL_POSITION_LEFT</literal>,
	    <literal>PL_POSITION_RIGHT</literal>,
	    <literal>PL_POSITION_TOP</literal>, or
	    <literal>PL_POSITION_BOTTOM</literal> are set, then use the
	    combination of <literal>PL_POSITION_RIGHT</literal> and
	    <literal>PL_POSITION_TOP</literal>. If neither of
	    <literal>PL_POSITION_INSIDE</literal> or
	    <literal>PL_POSITION_OUTSIDE</literal> is set, use
	    <literal>PL_POSITION_INSIDE</literal>. If neither of
	    <literal>PL_POSITION_VIEWPORT</literal> or
	    <literal>PL_POSITION_SUBPAGE</literal> is set, use
	    <literal>PL_POSITION_VIEWPORT</literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal> PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    X offset of the legend position in adopted coordinates
	    from the specified standard position of the legend. For positive x,
	    the direction of motion away from the standard position is
	    inward/outward from the standard corner positions or
	    standard left or right positions if the
	    <literal>PL_POSITION_INSIDE</literal>/<literal>PL_POSITION_OUTSIDE</literal>
	    bit is set in <literal><parameter>position</parameter></literal>.  For
	    the standard top or bottom positions, the direction of motion is
	    toward positive X.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Y offset of the legend position in adopted coordinates
	    from the specified standard position of the legend. For positive y,
	    the direction of motion away from the standard position is
	    inward/outward from the standard corner positions or standard
	    top or bottom positions if the
	    <literal>PL_POSITION_INSIDE</literal>/<literal>PL_POSITION_OUTSIDE</literal>
	    bit is set in <literal><parameter>position</parameter></literal>. 
	    For the standard left or right positions, the 
	    direction of motion is toward positive Y.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>plot_width</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Horizontal width in adopted coordinates of the plot area
	    (where the colored boxes, lines, and/or lines of symbols are drawn) of
	    the legend.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>bg_color</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The cmap0 color of the background for the legend
	    (<literal>PL_LEGEND_BACKGROUND</literal>).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>bb_color</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The cmap0 color of the bounding-box line for the legend
	    (<literal>PL_LEGEND_BOUNDING_BOX</literal>).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>bb_style</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The pllsty style number for the bounding-box line for the legend
	    (<literal>PL_LEGEND_BACKGROUND</literal>).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nrow</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The cmap0 index of the background color for the legend
	    (<literal>PL_LEGEND_BACKGROUND</literal>).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ncolumn</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The cmap0 index of the background color for the legend
	    (<literal>PL_LEGEND_BACKGROUND</literal>).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nlegend</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of legend entries.  N.B.  The total vertical height
	    of the legend in adopted coordinates is calculated
	    internally from <literal><parameter>nlegend</parameter></literal>,
	    <literal><parameter>text_scale</parameter></literal> (see below), and
	    <literal><parameter>text_spacing</parameter></literal> (see below).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>opt_array</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Array of nlegend values of options to control each
	    individual plotted area corresponding to a legend entry.  If the
	    <parameter>PL_LEGEND_NONE</parameter> bit is set, then nothing is
	    plotted in the plotted area.  If the
	    <parameter>PL_LEGEND_COLOR_BOX</parameter>,
	    <parameter>PL_LEGEND_LINE</parameter>, and/or
	    <parameter>PL_LEGEND_SYMBOL</parameter> bits are set, the area
	    corresponding to a legend entry is plotted with a colored box; a line;
	    and/or a line of symbols.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>text_offset</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Offset of the text area from the plot area in units of
	    character width.  N.B.  The total horizontal width of the legend in
	    adopted coordinates is calculated internally from
	    <parameter>plot_width</parameter> (see above),
	    <parameter>text_offset</parameter>, and length (calculated internally)
	    of the longest text string.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>text_scale</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Character height scale for text annotations.  N.B.  The
	    total vertical height of the legend in adopted coordinates
	    is calculated internally from <parameter>nlegend</parameter> (see
	    above), <parameter>text_scale</parameter>, and
	    <parameter>text_spacing</parameter> (see below).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>text_spacing</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Vertical spacing in units of the character height from one
	    legend entry to the next.  N.B.  The total vertical height of the
	    legend in adopted coordinates is calculated internally from
	    <parameter>nlegend</parameter> (see above),
	    <parameter>text_scale</parameter> (see above), and
	    <parameter>text_spacing</parameter>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>text_justification</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Justification parameter used for text justification.  The most common
	    values of text_justification are 0., 0.5, or 1. corresponding to a
	    text that is left justified, centred, or right justified within the
	    text area, but other values are allowed as well.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>text_colors</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Array of nlegend cmap0 text colors.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>text</parameter>
	  (<literal>const char * const *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Array of nlegend text string annotations.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>box_colors</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Array of nlegend cmap0 colors for the discrete colored boxes
	    (<parameter>PL_LEGEND_COLOR_BOX</parameter>).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>box_patterns</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Array of nlegend patterns (plpsty indices) for the discrete colored
	    boxes (<parameter>PL_LEGEND_COLOR_BOX</parameter>).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>box_scales</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Array of nlegend scales (units of fraction of character height) for
	    the height of the discrete colored boxes 
	    (<parameter>PL_LEGEND_COLOR_BOX</parameter>).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>box_line_widths</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Array of nlegend line widths for the patterns specified by
            box_patterns (<parameter>PL_LEGEND_COLOR_BOX</parameter>).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>line_colors</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Array of nlegend cmap0 line colors
	    (<parameter>PL_LEGEND_LINE</parameter>).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>line_styles</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Array of nlegend line styles (plsty indices) 
	    (<parameter>PL_LEGEND_LINE</parameter>).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>line_widths</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Array of nlegend line widths
	    (<parameter>PL_LEGEND_LINE</parameter>).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>symbol_colors</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Array of nlegend cmap0 symbol colors 
	    (<parameter>PL_LEGEND_SYMBOL</parameter>).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>symbol_scales</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Array of nlegend scale values for the symbol height 
	    (<parameter>PL_LEGEND_SYMBOL</parameter>).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>symbol_numbers</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Array of nlegend numbers of symbols to be drawn across the width of
	    the plotted area (<parameter>PL_LEGEND_SYMBOL</parameter>).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>symbols</parameter>
	  (<literal>const char * const *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Array of nlegend symbols (plpoin indices) 
	    (<parameter>PL_LEGEND_SYMBOL</parameter>).
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>pllegend(p_legend_width, p_legend_height, 
      opt, position, x, y, plot_width,
      bg_color, bb_color, bb_style,
      nrow, ncolumn,
      opt_array, 
      text_offset, text_scale, text_spacing, test_justification,
      text_colors, text, 
      box_colors, box_patterns,
      box_scales, box_line_widths,
      line_colors, line_styles, line_widths,
      symbol_colors, symbol_scales, 
      symbol_numbers, symbols)</function>
    </para>

    <para>
      This function is used in examples 4, 26, and 33.
    </para>

  </sect1>

  <sect1 id="pllightsource" renderas="sect3">
    <title>
      <function>pllightsource</function>: Sets the 3D position of the light
      source
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>pllightsource</function>
	  </funcdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>z</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets the 3D position of the light source for use with &plsurf3d;.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    X-coordinate of the light source.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Y-coordinate of the light source.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>z</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Z-coordinate of the light source.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>pllightsource(x, y, z)</function>
    </para>

    <para>
      This function is used in example 8.
    </para>

  </sect1>

  <sect1 id="plline" renderas="sect3">
    <title>
      <function>plline</function>: Draw a line
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plline</function>
	  </funcdef>
	  <paramdef><parameter>n</parameter></paramdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Draws line defined by <literal><parameter>n</parameter></literal>
      points in
      <literal><parameter>x</parameter></literal> and
      <literal><parameter>y</parameter></literal>.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>n</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of points defining line.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with x coordinates of points.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with y coordinates of points.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plline(x, y)</function>
    </para>

    <para>
      This function is used in examples 1,3,4,9,12-14,16,18,20,22,25-27,29.
    </para>

  </sect1>

  <sect1 id="plline3" renderas="sect3">
    <title>
      <function>plline3</function>: Draw a line in 3 space
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plline3</function>
	  </funcdef>
	  <paramdef><parameter>n</parameter></paramdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>z</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Draws line in 3 space defined by <literal><parameter>n</parameter></literal>
      points in
      <literal><parameter>x</parameter></literal>,
      <literal><parameter>y</parameter></literal>, and
      <literal><parameter>z</parameter></literal>.
      You must first set up the viewport, the
      2d viewing window (in world coordinates), and the 3d normalized
      coordinate box.  See <filename>x18c.c</filename> for more info.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>n</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of points defining line.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with x coordinates of points.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with y coordinates of points.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>z</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with z coordinates of points.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plline3(x, y, z)</function>
    </para>

    <para>
      This function is used in example 18.
    </para>

  </sect1>

  <sect1 id="pllsty" renderas="sect3">
    <title>
      <function>pllsty</function>: Select line style
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>pllsty</function>
	  </funcdef>
	  <paramdef><parameter>lin</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      This sets the line style according to one of eight predefined
      patterns (also see &plstyl;).
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>lin</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Integer value between 1 and 8. Line style 1 is a continuous line,
	    line style 2 is a line with short dashes and gaps, line style 3 is
	    a line with long dashes and gaps, line style 4 has long dashes and
	    short gaps and so on.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>pllsty(lin)</function>
    </para>

    <para>
      This function is used in examples 9,12,22,25.
    </para>

  </sect1>

  <sect1 id="plmap" renderas="sect3">
    <title>
      <function>plmap</function>: Plot continental outline in world coordinates
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plmap</function>
	  </funcdef>
	  <paramdef><parameter>mapform</parameter></paramdef>
	  <paramdef><parameter>type</parameter></paramdef>
	  <paramdef><parameter>minlong</parameter></paramdef>
	  <paramdef><parameter>maxlong</parameter></paramdef>
	  <paramdef><parameter>minlat</parameter></paramdef>
	  <paramdef><parameter>maxlat</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Plots continental outlines in world coordinates.
      examples/c/x19c demonstrates how to use this 
      function to create different projections.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>mapform</parameter>
	  (<literal>void (*) (PLINT, PLFLT *, PLFLT *)</literal>, input)
	</term>
	<listitem>
	  <para>
	    A user supplied function to transform the coordinate 
	    longitudes and latitudes to a plot coordinate system.  
	    By using this transform, we can change from a longitude, 
	    latitude coordinate to a polar stereographic project, for 
	    example.  Initially, x[0]..[n-1] are the longitudes and y[0]..y[n-1] 
	    are the corresponding latitudes.  After the call to mapform(), x[] 
	    and y[] should be replaced by the corresponding plot coordinates.  
	    If no transform is desired, mapform can be replaced by NULL.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>type</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    type is a character string. The value of this parameter determines the
	    type of background. The possible values are:
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal>"globe"</literal> -- continental outlines
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>"usa"</literal> -- USA and state boundaries
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>"cglobe"</literal> -- continental outlines and countries
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>"usaglobe"</literal> -- USA, state boundaries and continental outlines
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>minlong</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The value of the longitude on the left side of the plot. 
	    The value of minlong must be less than the value of maxlong, and the 
	    quantity maxlong-minlong must be less than or equal to 360.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>maxlong</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The value of the longitude on the right side of the plot.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>minlat</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The minimum latitude to be plotted on the background.  
	    One can always use -90.0 as the boundary outside the plot window 
	    will be automatically eliminated.  However, the program will be 
	    faster if one can reduce the size of the background plotted.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>maxlat</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The maximum latitudes to be plotted on the background.  
	    One can always use 90.0 as the boundary outside the plot window 
	    will be automatically eliminated.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>


    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plmap(mapform, type, minlong, maxlong, minlat, maxlat)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    F95, Java, Perl/PDL, Python: Not implemented?
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in example 19.
    </para>

  </sect1>

  <sect1 id="plmeridians" renderas="sect3">
    <title>
      <function>plmeridians</function>: Plot latitude and longitude lines
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plmeridians</function>
	  </funcdef>
	  <paramdef><parameter>mapform</parameter></paramdef>
	  <paramdef><parameter>dlong</parameter></paramdef>
	  <paramdef><parameter>dlat</parameter></paramdef>
	  <paramdef><parameter>minlong</parameter></paramdef>
	  <paramdef><parameter>maxlong</parameter></paramdef>
	  <paramdef><parameter>minlat</parameter></paramdef>
	  <paramdef><parameter>maxlat</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Displays latitude and longitude on the current plot.  The lines
      are plotted in the current color and line style.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>mapform</parameter>
	  (<literal>void (*) (PLINT, PLFLT *, PLFLT *)</literal>, input)
	</term>
	<listitem>
	  <para>
	    A user supplied function to transform the coordinate 
	    longitudes and latitudes to a plot coordinate system.  
	    By using this transform, we can change from a longitude, 
	    latitude coordinate to a polar stereographic project, for 
	    example.  Initially, x[0]..[n-1] are the longitudes and y[0]..y[n-1] 
	    are the corresponding latitudes.  After the call to mapform(), x[] 
	    and y[] should be replaced by the corresponding plot coordinates.  
	    If no transform is desired, mapform can be replaced by NULL.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>dlong</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The interval in degrees at which the longitude lines are to be plotted.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>dlat</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The interval in degrees at which the latitude lines are to be plotted.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>minlong</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The value of the longitude on the left side of the plot. 
	    The value of minlong must be less than the value of maxlong, and the 
	    quantity maxlong-minlong must be less than or equal to 360.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>maxlong</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The value of the longitude on the right side of the plot.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>minlat</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The minimum latitude to be plotted on the background.  
	    One can always use -90.0 as the boundary outside the plot window 
	    will be automatically eliminated.  However, the program will be 
	    faster if one can reduce the size of the background plotted.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>maxlat</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The maximum latitudes to be plotted on the background.  
	    One can always use 90.0 as the boundary outside the plot window 
	    will be automatically eliminated.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plmeridians(mapform, dlong, dlat, minlong, maxlong, minlat, maxlat)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    F95, Java, Perl/PDL, Python: Not implemented?
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in example 19.
    </para>

  </sect1>

  <sect1 id="plmesh" renderas="sect3">
    <title>
      <function>plmesh</function>: Plot surface mesh
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plmesh</function>
	  </funcdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>z</parameter></paramdef>
	  <paramdef><parameter>nx</parameter></paramdef>
	  <paramdef><parameter>ny</parameter></paramdef>
	  <paramdef><parameter>opt</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Plots a surface mesh within the environment set up by &plw3d;.  The
      surface is defined by the two-dimensional array
      <literal><parameter>z</parameter>[<parameter>nx</parameter>][<parameter>ny</parameter>]</literal>,
      the point <literal><parameter>z</parameter>[i][j]</literal> being the
      value of the function at <literal>(<parameter>x</parameter>[i],
      <parameter>y</parameter>[j])</literal>.  Note that the points in
      arrays <literal><parameter>x</parameter></literal> and
      <literal><parameter>y</parameter></literal> do not need to be equally
      spaced, but must be stored in ascending order.  The parameter
      <literal><parameter>opt</parameter></literal> controls the way in
      which the surface is displayed.  For further details see <xref
      linkend="tri-d-plots"/>.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to set of x coordinate values at which the function is
	    evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to set of y coordinate values at which the function is
	    evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>z</parameter>
	  (<literal>const PLFLT * const *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to a vectored two-dimensional array with set of
	    function values.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nx</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of <literal><parameter>x</parameter></literal> values at
	    which function is evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ny</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of <literal><parameter>y</parameter></literal> values at
	    which function is evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>opt</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Determines the way in which the surface is represented:
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=DRAW_LINEX</literal>: Lines
		  are drawn showing
		  <literal><parameter>z</parameter></literal> as a function
		  of <literal><parameter>x</parameter></literal> for each
		  value of <literal><parameter>y</parameter>[j]</literal>.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=DRAW_LINEY</literal>: Lines
		  are drawn showing
		  <literal><parameter>z</parameter></literal> as a function
		  of <literal><parameter>y</parameter></literal> for each
		  value of <literal><parameter>x</parameter>[i]</literal>.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=DRAW_LINEXY</literal>: Network
		  of lines is drawn connecting points at which function is
		  defined.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plmesh(x, y, z, opt)</function>
    </para>

    <para>
      This function is used in example 11.
    </para>

  </sect1>


  <sect1 id="plmeshc" renderas="sect3">
    <title>
      <function>plmeshc</function>: Magnitude colored plot surface mesh with contour
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plmeshc</function>
	  </funcdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>z</parameter></paramdef>
	  <paramdef><parameter>nx</parameter></paramdef>
	  <paramdef><parameter>ny</parameter></paramdef>
	  <paramdef><parameter>opt</parameter></paramdef>
	  <paramdef><parameter>clevel</parameter></paramdef>
	  <paramdef><parameter>nlevel</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      A more powerful form of <function>&plmesh;</function>:
      the surface mesh can be colored accordingly to the current z value being plotted,
      a contour plot can be drawn at the base XY plane, and a curtain can be drawn between
      the plotted function border and the base XY plane.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to set of x coordinate values at which the function is
	    evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to set of y coordinate values at which the function is
	    evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>z</parameter>
	  (<literal>const PLFLT * const *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to a vectored two-dimensional array with set of
	    function values.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nx</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of <literal><parameter>x</parameter></literal> values at
	    which function is evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ny</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of <literal><parameter>y</parameter></literal> values at
	    which function is evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>opt</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Determines the way in which the surface is represented. To specify
	    more than one option just add the options, e.g. DRAW_LINEXY + MAG_COLOR
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=DRAW_LINEX</literal>: Lines
		  are drawn showing
		  <literal><parameter>z</parameter></literal> as a function
		  of <literal><parameter>x</parameter></literal> for each
		  value of <literal><parameter>y</parameter>[j]</literal>.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=DRAW_LINEY</literal>: Lines
		  are drawn showing
		  <literal><parameter>z</parameter></literal> as a function
		  of <literal><parameter>y</parameter></literal> for each
		  value of <literal><parameter>x</parameter>[i]</literal>.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=DRAW_LINEXY</literal>: Network
		  of lines is drawn connecting points at which function is
		  defined.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=MAG_COLOR</literal>: Each line
		  in the mesh is colored according to the z value being plotted. The
		  color is used from the current color map 1.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=BASE_CONT</literal>: A contour
		  plot is drawn at the base XY plane using parameters
		  <parameter>nlevel</parameter> and <parameter>clevel</parameter>.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=DRAW_SIDES</literal>: draws a curtain
		  between the base XY plane and the borders of the plotted function.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>clevel</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to the array that defines the contour level spacing.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nlevel</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of elements in the <literal>clevel</literal> array.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plmeshc(x, y, z, opt, clevel)</function>
    </para>

    <para>
      This function is used in example 11.
    </para>

  </sect1>

  <sect1 id="plmkstrm" renderas="sect3">
    <title>
      <function>plmkstrm</function>: Creates a new stream and makes it the
      default
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plmkstrm</function>
	  </funcdef>
	  <paramdef><parameter>p_strm</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Creates a new stream and makes it the default.  Differs from using
      &plsstrm;, in that a free stream number is found, and returned.
      Unfortunately, I <emphasis>have</emphasis> to start at stream 1 and work upward, since
      stream 0 is preallocated.  One of the <emphasis>big</emphasis> flaws in the PLplot API is
      that no initial, library-opening call is required.  So stream 0 must
      be preallocated, and there is no simple way of determining whether it
      is already in use or not.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>p_strm</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to stream number of the created stream.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plmkstrm(p_strm)</function>
    </para>

    <para>
      This function is used in examples 1,20.
    </para>

  </sect1>

  <sect1 id="plmtex" renderas="sect3">
    <title>
      <function>plmtex</function>: Write text relative to viewport boundaries
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plmtex</function>
	  </funcdef>
	  <paramdef><parameter>side</parameter></paramdef>
	  <paramdef><parameter>disp</parameter></paramdef>
	  <paramdef><parameter>pos</parameter></paramdef>
	  <paramdef><parameter>just</parameter></paramdef>
	  <paramdef><parameter>text</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Writes text at a specified position relative to the viewport
      boundaries.  Text may be written inside or outside the viewport, but
      is clipped at the subpage boundaries.  The reference point of a
      string lies along a line passing through the string at half the
      height of a capital letter.  The position of the reference point
      along this line is determined by
      <literal><parameter>just</parameter></literal>, and the position of
      the reference point relative to the viewport is set by
      <literal><parameter>disp</parameter></literal> and
      <literal><parameter>pos</parameter></literal>.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>side</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Specifies the side of the viewport along which the text is to
	    be written. The string must be one of:
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal>b</literal>: Bottom of viewport, text written
		  parallel to edge.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>bv</literal>: Bottom of viewport, text written at
		  right angles to edge.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>l</literal>: Left of viewport, text written
		  parallel to edge.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>lv</literal>: Left of viewport, text written at
		  right angles to edge.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>r</literal>: Right of viewport, text written
		  parallel to edge.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>rv</literal>: Right of viewport, text written at
		  right angles to edge.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>t</literal>: Top of viewport, text written
		  parallel to edge.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>tv</literal>: Top of viewport, text written at
		  right angles to edge.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>disp</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Position of the reference point of string, measured outwards
	    from the specified viewport edge in units of the current
	    character height.  Use negative
	    <literal><parameter>disp</parameter></literal> to write within
	    the viewport.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>pos</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Position of the reference point of string along the specified
	    edge, expressed as a fraction of the length of the edge.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>just</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Specifies the position of the string relative to its reference
	    point.  If <literal><parameter>just</parameter>=0.</literal>,
	    the reference point is at the left and if
	    <literal><parameter>just</parameter>=1.</literal>, it is at the
	    right of the string.  Other values of
	    <literal><parameter>just</parameter></literal> give
	    intermediate justifications.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>text</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    The string to be written out.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plmtex(side, disp, pos, just, text)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: <function>plmtex(disp, pos, just, side, text)</function>
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in examples 3,4,6-8,11,12,14,18,23,26.
    </para>

  </sect1>

  <sect1 id="plmtex3" renderas="sect3">
    <title>
      <function>plmtex3</function>: Write text relative to viewport boundaries
      in 3D plots
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plmtex3</function>
	  </funcdef>
	  <paramdef><parameter>side</parameter></paramdef>
	  <paramdef><parameter>disp</parameter></paramdef>
	  <paramdef><parameter>pos</parameter></paramdef>
	  <paramdef><parameter>just</parameter></paramdef>
	  <paramdef><parameter>text</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Writes text at a specified position relative to the viewport
      boundaries.  Text may be written inside or outside the viewport, but
      is clipped at the subpage boundaries.  The reference point of a
      string lies along a line passing through the string at half the
      height of a capital letter.  The position of the reference point
      along this line is determined by
      <literal><parameter>just</parameter></literal>, and the position of
      the reference point relative to the viewport is set by
      <literal><parameter>disp</parameter></literal> and
      <literal><parameter>pos</parameter></literal>.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>side</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Specifies the side of the viewport along which the text is to
	    be written. The string should contain one or more of the
	    following characters: <literal>[xyz][ps][v]</literal>. 
	    Only one label is drawn at a time, i.e. <literal>xyp</literal>
	    will only label the X axis, not both the X and Y axes.
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal>x</literal>: Label the X axis.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>y</literal>: Label the Y axis.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>z</literal>: Label the Z axis.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>p</literal>: Label the <quote>primary</quote>
		  axis. For Z this is the leftmost Z axis. For X it is
		  the axis that starts at y-min. For Y it is the axis that
		  starts at x-min.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>s</literal>: Label the <quote>secondary</quote>
		  axis.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>v</literal>: Draw the text perpendicular to the
		  axis.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>disp</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Position of the reference point of string, measured outwards
	    from the specified viewport edge in units of the current
	    character height.  Use negative
	    <literal><parameter>disp</parameter></literal> to write within
	    the viewport.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>pos</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Position of the reference point of string along the specified
	    edge, expressed as a fraction of the length of the edge.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>just</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Specifies the position of the string relative to its reference
	    point.  If <literal><parameter>just</parameter>=0.</literal>,
	    the reference point is at the left and if
	    <literal><parameter>just</parameter>=1.</literal>, it is at the
	    right of the string.  Other values of
	    <literal><parameter>just</parameter></literal> give
	    intermediate justifications.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>text</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    The string to be written out.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plmtex3(side, disp, pos, just, text)</function>
    </para>

    <para>
      This function is used in example 28.
    </para>

  </sect1>


  <sect1 id="plot3d" renderas="sect3">
    <title>
      <function>plot3d</function>: Plot 3-d surface plot
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plot3d</function>
	  </funcdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>z</parameter></paramdef>
	  <paramdef><parameter>nx</parameter></paramdef>
	  <paramdef><parameter>ny</parameter></paramdef>
	  <paramdef><parameter>opt</parameter></paramdef>
	  <paramdef><parameter>side</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Plots a three dimensional surface plot within the environment set up
      by &plw3d;.  The surface is defined by the two-dimensional array
      <literal><parameter>z</parameter>[<parameter>nx</parameter>][<parameter>ny</parameter>]</literal>,
      the point <literal><parameter>z</parameter>[i][j]</literal> being the
      value of the function at <literal>(<parameter>x</parameter>[i],
      <parameter>y</parameter>[j])</literal>.  Note that the points in
      arrays <literal><parameter>x</parameter></literal> and
      <literal><parameter>y</parameter></literal> do not need to be equally
      spaced, but must be stored in ascending order.  The parameter
      <literal><parameter>opt</parameter></literal> controls the way in
      which the surface is displayed.  For further details see <xref
      linkend="tri-d-plots"/>.
      The only difference between &plmesh; and &plot3d; is that &plmesh; draws
      the bottom side of the surface, while &plot3d; only draws the surface as
      viewed from the top.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to set of x coordinate values at which the function is
	    evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to set of y coordinate values at which the function is
	    evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>z</parameter>
	  (<literal>const PLFLT * const *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to a vectored two-dimensional array with set of
	    function values.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nx</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of <literal><parameter>x</parameter></literal> values at
	    which function is evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ny</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of <literal><parameter>y</parameter></literal> values at
	    which function is evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>opt</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Determines the way in which the surface is represented:
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=DRAW_LINEX</literal>: Lines
		  are drawn showing
		  <literal><parameter>z</parameter></literal> as a function
		  of <literal><parameter>x</parameter></literal> for each
		  value of <literal><parameter>y</parameter>[j]</literal>.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=DRAW_LINEY</literal>: Lines
		  are drawn showing
		  <literal><parameter>z</parameter></literal> as a function
		  of <literal><parameter>y</parameter></literal> for each
		  value of <literal><parameter>x</parameter>[i]</literal>.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=DRAW_LINEXY</literal>: Network
		  of lines is drawn connecting points at which function is
		  defined.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>side</parameter>
	  (<literal>PLBOOL</literal>, input)
	</term>
	<listitem>
	  <para>
	    Flag to indicate whether or not ``sides'' should be draw on the
	    figure.  If <literal><parameter>side</parameter></literal> is true
	    sides are drawn, otherwise no sides are drawn.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plot3d(x, y, z, opt, side)</function>
    </para>

    <para>
      This function is used in examples 11,21.
    </para>

  </sect1>

  <sect1 id="plot3dc" renderas="sect3">
    <title>
      <function>plot3dc</function>: Magnitude colored plot surface with contour
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plot3dc</function>
	  </funcdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>z</parameter></paramdef>
	  <paramdef><parameter>nx</parameter></paramdef>
	  <paramdef><parameter>ny</parameter></paramdef>
	  <paramdef><parameter>opt</parameter></paramdef>
	  <paramdef><parameter>clevel</parameter></paramdef>
	  <paramdef><parameter>nlevel</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Aside from dropping the <parameter>side</parameter>
      functionality this is a more powerful form of <function>&plot3d;</function>:
      the surface mesh can be colored accordingly to the current z value being plotted,
      a contour plot can be drawn at the base XY plane, and a curtain can be drawn between
      the plotted function border and the base XY plane.
      The arguments are identical to those of <function>&plmeshc;</function>. The only difference between
      &plmeshc; and &plot3dc; is that &plmeshc; draws the bottom side of the surface, while
      &plot3dc; only draws the surface as viewed from the top.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to set of x coordinate values at which the function is
	    evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to set of y coordinate values at which the function is
	    evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>z</parameter>
	  (<literal>const PLFLT * const *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to a vectored two-dimensional array with set of
	    function values.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nx</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of <literal><parameter>x</parameter></literal> values at
	    which function is evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ny</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of <literal><parameter>y</parameter></literal> values at
	    which function is evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>opt</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Determines the way in which the surface is represented. To specify
	    more than one option just add the options, e.g. DRAW_LINEXY + MAG_COLOR
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=DRAW_LINEX</literal>: Lines
		  are drawn showing
		  <literal><parameter>z</parameter></literal> as a function
		  of <literal><parameter>x</parameter></literal> for each
		  value of <literal><parameter>y</parameter>[j]</literal>.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=DRAW_LINEY</literal>: Lines
		  are drawn showing
		  <literal><parameter>z</parameter></literal> as a function
		  of <literal><parameter>y</parameter></literal> for each
		  value of <literal><parameter>x</parameter>[i]</literal>.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=DRAW_LINEXY</literal>: Network
		  of lines is drawn connecting points at which function is
		  defined.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=MAG_COLOR</literal>: Each line
		  in the mesh is colored according to the z value being plotted. The
		  color is used from the current color map 1.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=BASE_CONT</literal>: A contour
		  plot is drawn at the base XY plane using parameters
		  <parameter>nlevel</parameter> and <parameter>clevel</parameter>.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=DRAW_SIDES</literal>: draws a curtain
		  between the base XY plane and the borders of the plotted function.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>clevel</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to the array that defines the contour level spacing.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nlevel</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of elements in the <literal>clevel</literal> array.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plot3dc(x, y, z, opt, clevel)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: Not available?
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in example 21.
    </para>

  </sect1>

  <sect1 id="plot3dcl" renderas="sect3">
    <title>
      <function>plot3dcl</function>: Magnitude colored plot surface
      with contour for z[x][y] with y index limits
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plot3dcl</function>
	  </funcdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>z</parameter></paramdef>
	  <paramdef><parameter>nx</parameter></paramdef>
	  <paramdef><parameter>ny</parameter></paramdef>
	  <paramdef><parameter>opt</parameter></paramdef>
	  <paramdef><parameter>clevel</parameter></paramdef>
	  <paramdef><parameter>nlevel</parameter></paramdef>
	  <paramdef><parameter>indexxmin</parameter></paramdef>
	  <paramdef><parameter>indexxmax</parameter></paramdef>
	  <paramdef><parameter>indexymin</parameter></paramdef>
	  <paramdef><parameter>indexymax</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      When the implementation is completed this variant of &plot3dc;
      (see that function's documentation for more details)
      should be suitable for the case where the area of the
      <literal><parameter>x</parameter></literal>,
      <literal><parameter>y</parameter></literal> coordinate grid
      where <literal><parameter>z</parameter></literal> is defined can
      be non-rectangular. The implementation is incomplete so the last
      4 parameters of plot3dcl;
      <literal><parameter>indexxmin</parameter></literal>,
      <literal><parameter>indexxmax</parameter></literal>,
      <literal><parameter>indexymin</parameter></literal>, and
      <literal><parameter>indexymax</parameter></literal>; are
      currently ignored and the functionality is otherwise identical
      to that of &plot3dc;.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to set of x coordinate values at which the function is
	    evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to set of y coordinate values at which the function is
	    evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>z</parameter>
	  (<literal>const PLFLT * const *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to a vectored two-dimensional array with set of
	    function values.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nx</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of <literal><parameter>x</parameter></literal> values at
	    which the function is evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ny</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of <literal><parameter>y</parameter></literal> values at
	    which the function is evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>opt</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Determines the way in which the surface is represented. To specify
	    more than one option just add the options, e.g. DRAW_LINEXY + MAG_COLOR
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=DRAW_LINEX</literal>: Lines
		  are drawn showing
		  <literal><parameter>z</parameter></literal> as a function
		  of <literal><parameter>x</parameter></literal> for each
		  value of <literal><parameter>y</parameter>[j]</literal>.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=DRAW_LINEY</literal>: Lines
		  are drawn showing
		  <literal><parameter>z</parameter></literal> as a function
		  of <literal><parameter>y</parameter></literal> for each
		  value of <literal><parameter>x</parameter>[i]</literal>.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=DRAW_LINEXY</literal>: Network
		  of lines is drawn connecting points at which function is
		  defined.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=MAG_COLOR</literal>: Each line
		  in the mesh is colored according to the z value being plotted. The
		  color is used from the current color map 1.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=BASE_CONT</literal>: A contour
		  plot is drawn at the base XY plane using parameters
		  <parameter>nlevel</parameter> and <parameter>clevel</parameter>.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=DRAW_SIDES</literal>: draws a curtain
		  between the base XY plane and the borders of the plotted function.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>clevel</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to the array that defines the contour level spacing.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nlevel</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of elements in the <literal>clevel</literal> array.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>indexxmin</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The index value (which must be ≥ 0) that corresponds to
	    the first <literal><parameter>x</parameter></literal> index where
	    <literal><parameter>z</parameter></literal> is defined.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>indexxmax</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The index value (which must be ≤
	    <literal><parameter>nx</parameter></literal>) which corresponds (by
	    convention) to one more than the last
	    <literal><parameter>x</parameter></literal> index value where
	    <literal><parameter>z</parameter></literal> is defined.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>indexymin</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Array of <literal><parameter>y</parameter></literal> index
	    values which all must be ≥ 0.  These values are the first
	    <literal><parameter>y</parameter></literal> index where
	    <literal><parameter>z</parameter></literal> is defined for a
	    particular <literal><parameter>x</parameter></literal> index in the
	    range from <literal><parameter>indexxmin</parameter></literal> to
	    <literal><parameter>indexxmax - 1</parameter></literal>.  The dimension of
	    <literal><parameter>indexymin</parameter></literal> is
	    <literal><parameter>indexxmax</parameter></literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>indexymax</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Array of <literal><parameter>y</parameter></literal> index
	    values which all must be ≤
	    <literal><parameter>ny</parameter></literal>.  These values
	    correspond (by convention) to one more than the last
	    <literal><parameter>y</parameter></literal> index where
	    <literal><parameter>z</parameter></literal> is defined for a
	    particular <literal><parameter>x</parameter></literal> index in the
	    range from <literal><parameter>indexxmin</parameter></literal> to
	    <literal><parameter>indexxmax - 1</parameter></literal>.  The dimension of
	    <literal><parameter>indexymax</parameter></literal> is
	    <literal><parameter>indexxmax</parameter></literal>.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plot3dcl(x, y, z, opt, clevel, indexxmin,
            indexymin, indexymax)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: Not available?
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is not used in any example.
    </para>

  </sect1>

  <sect1 id="plparseopts" renderas="sect3">
    <title>
      <function>plparseopts</function>: Parse command-line arguments
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>int
	  <function>plparseopts</function>
	  </funcdef>
	  <paramdef><parameter>p_argc</parameter></paramdef>
	  <paramdef><parameter>argv</parameter></paramdef>
	  <paramdef><parameter>mode</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Parse command-line arguments.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>p_argc</parameter>
	  (<literal>int *</literal>, input)
	</term>
	<listitem>
	  <para>
	    pointer to number of arguments.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>argv</parameter>
	  (<literal>const char **</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to character array containing
	    <literal><parameter>*p_argc</parameter></literal> command-line
	    arguments.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>mode</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Parsing mode with the following possibilities:
	    <itemizedlist>
	      <listitem>
		<para>
		  PL_PARSE_FULL (1) -- Full parsing of command line and all error messages
		  enabled, including program exit when an error occurs.  Anything on the
		  command line that isn't recognized as a valid option or option argument is
		  flagged as an error.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  PL_PARSE_QUIET (2) -- Turns off all output except in the case of errors.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  PL_PARSE_NODELETE (4) -- Turns off deletion of processed arguments.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  PL_PARSE_SHOWALL (8) -- Show invisible options
		</para>
	      </listitem>
	      <listitem>
		<para>
		  PL_PARSE_NOPROGRAM (32) -- Specified if argv[0] is NOT a pointer to the
		  program name.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  PL_PARSE_NODASH (64) -- Set if leading dash is NOT required.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  PL_PARSE_SKIP (128) -- Set to quietly skip over any unrecognized arguments.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      &plparseopts; removes all recognized flags
      (decreasing argc accordingly), so that invalid input may be readily
      detected.  It can also be used to process user command line flags.  The
      user can merge an option table of type PLOptionTable into the internal
      option table info structure using &plMergeOpts;.  Or, the user can
      specify that ONLY the external table(s) be parsed by calling
      &plClearOpts; before &plMergeOpts;.
    </para>

    <para>
      The default action taken by &plparseopts; is as follows:
      <simplelist columns="1">
	<member>
	  Returns with an error if an unrecognized option or badly formed
	  option-value pair are encountered.
	</member>
	<member>
	  Returns immediately (return code 0) when the first non-option
	  command line argument is found.
	</member>
	<member>
	  Returns with the return code of the option handler, if one
	  was called.
	</member>
	<member>
	  Deletes command line arguments from argv list as they are found,
	  and decrements argc accordingly.
	</member>
	<member>
	  Does not show "invisible" options in usage or help messages.
	</member>
	<member>
	  Assumes the program name is contained in argv[0].
	</member>
      </simplelist>
    </para>

    <para>
      These behaviors may be controlled through the 
      <parameter>mode</parameter> argument.
    </para>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plparseopts(argv, mode)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: Not available?
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in all of the examples.
    </para>

  </sect1>

  <sect1 id="plpat" renderas="sect3">
    <title>
      <function>plpat</function>: Set area fill pattern
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plpat</function>
	  </funcdef>
	  <paramdef><parameter>nlin</parameter></paramdef>
	  <paramdef><parameter>inc</parameter></paramdef>
	  <paramdef><parameter>del</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets the area fill pattern.  The pattern consists of 1 or 2 sets of
      parallel lines with specified inclinations and spacings.  The
      arguments to this routine are the number of sets to use (1 or 2)
      followed by two pointers to integer arrays (of 1 or 2 elements)
      specifying the inclinations in tenths of a degree and the spacing in
      micrometers.  (also see &plpsty;)
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>nlin</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of sets of lines making up the pattern, either 1 or 2.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>inc</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with
	    <literal><parameter>nlin</parameter></literal> elements.
	    Specifies the line inclination in tenths of a degree.  (Should
	    be between -900 and 900).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>del</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with
	    <literal><parameter>nlin</parameter></literal> elements.
	    Specifies the spacing in micrometers between the lines making
	    up the pattern.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plpat(inc, del)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: <function>plpat(nlin, inc, del)</function>
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in example 15.
    </para>

  </sect1>

  <sect1 id="plpath" renderas="sect3">
    <title>
      <function>plpath</function>: Draw a line between two points, accounting
      for coordinate transforms
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plpath</function>
	  </funcdef>
	  <paramdef><parameter>n</parameter></paramdef>
	  <paramdef><parameter>x1</parameter></paramdef>
	  <paramdef><parameter>y1</parameter></paramdef>
	  <paramdef><parameter>x2</parameter></paramdef>
	  <paramdef><parameter>y2</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Joins the point <literal>(<parameter>x1</parameter>,
      <parameter>y1</parameter>)</literal> to
      <literal>(<parameter>x2</parameter>,
      <parameter>y2</parameter>)</literal>.  If a global coordinate transform
      is defined then the line is broken in to
      <literal><parameter>n</parameter></literal> segments to approximate the
      path.  If no transform is defined then this simply acts like a call to
      &pljoin;.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>n</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    number of points to use to approximate the path.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>x1</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    x coordinate of first point.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y1</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    y coordinate of first point.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>x2</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    x coordinate of second point.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y2</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    y coordinate of second point.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plpath(n,x1,y1,x2,y2)</function>
    </para>

    <para>
      This function is used in example 22.
    </para>

  </sect1>

  <sect1 id="plpoin" renderas="sect3">
    <title>
      <function>plpoin</function>: Plot a glyph at the specified points
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plpoin</function>
	  </funcdef>
	  <paramdef><parameter>n</parameter></paramdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>code</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Plot a glyph at the specified points.  (This function is largely
      superseded by &plstring; which gives access to many[!] more glyphs.)
      <literal><parameter>code</parameter>=-1</literal> means try to
      just draw a point.  Right now it's just a move
      and a draw at the same place.  Not ideal, since a sufficiently
      intelligent output device may optimize it away, or there may be faster
      ways of doing it.  This is OK for now, though, and offers a 4X speedup
      over drawing a Hershey font "point" (which is actually diamond shaped
      and therefore takes 4 strokes to draw).  If 0 &lt; code &lt; 32, then
      a useful (but small subset) of Hershey symbols is plotted.  If 32
      &lt;= code &lt;= 127 the corresponding printable ASCII character is
      plotted.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>n</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of points in the
	    <literal><parameter>x</parameter></literal> and
	    <literal><parameter>y</parameter></literal> arrays.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to an array with X coordinates of points.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to an array with Y coordinates of points.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>code</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Hershey symbol code (in "ascii-indexed" form with -1 &lt;= code &lt;=
	    127) corresponding to a glyph to be plotted at each of the
	    <literal><parameter>n</parameter></literal> points.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plpoin(x, y, code)</function>
    </para>

    <para>
      This function is used in examples 1,6,14,29.
    </para>

  </sect1>

  <sect1 id="plpoin3" renderas="sect3">
    <title>
      <function>plpoin3</function>: Plot a glyph at the specified 3D points
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plpoin3</function>
	  </funcdef>
	  <paramdef><parameter>n</parameter></paramdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>z</parameter></paramdef>
	  <paramdef><parameter>code</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Plot a glyph at the specified 3D points.  (This function is largely
      superseded by &plstring3; which gives access to many[!] more glyphs.)
      Set up the call to this function similar to what is done for &plline3;.
      <literal><parameter>code</parameter>=-1</literal> means try to
      just draw a point.  Right now it's just a move and a draw at the same
      place.  Not ideal, since a sufficiently intelligent output device may
      optimize it away, or there may be faster ways of doing it.  This is OK
      for now, though, and offers a 4X speedup over drawing a Hershey font
      "point" (which is actually diamond shaped and therefore takes 4
      strokes to draw).  If 0 &lt; code &lt; 32, then a useful (but small
      subset) of Hershey symbols is plotted.  If 32 &lt;= code &lt;= 127 the
      corresponding printable ASCII character is plotted.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>n</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of points in the
	    <literal><parameter>x</parameter></literal> and
	    <literal><parameter>y</parameter></literal> arrays.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to an array with X coordinates of points.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to an array with Y coordinates of points.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>z</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to an array with Z coordinates of points.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>code</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Hershey symbol code (in "ascii-indexed" form with -1 &lt;= code &lt;=
	    127) corresponding to a glyph to be plotted at each of the
	    <literal><parameter>n</parameter></literal> points.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plpoin3(x, y, z, code)</function>
    </para>

    <para>
      This function is not used in any example.
    </para>

  </sect1>

  <sect1 id="plpoly3" renderas="sect3">
    <title>
      <function>plpoly3</function>: Draw a polygon in 3 space
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plpoly3</function>
	  </funcdef>
	  <paramdef><parameter>n</parameter></paramdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>z</parameter></paramdef>
	  <paramdef><parameter>draw</parameter></paramdef>
	  <paramdef><parameter>ifcc</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Draws a polygon in 3 space defined by <literal><parameter>n</parameter></literal>
      points in
      <literal><parameter>x</parameter></literal>,
      <literal><parameter>y</parameter></literal>, and
      <literal><parameter>z</parameter></literal>.
      Setup like &plline3;, but differs from that function in that &plpoly3;
      attempts to determine if the polygon is viewable depending on the
      order of the points within the arrays and the value of
      <literal><parameter>ifcc</parameter></literal>.  If the back of
      polygon is facing the viewer, then it isn't drawn.  If this isn't what
      you want, then use &plline3; instead.
    </para>

    <para>
      The points are assumed to be in a plane, and the directionality of
      the plane is determined from the first three points.  Additional
      points do not <emphasis>have</emphasis> to lie on the plane defined
      by the first three, but if they do not, then the determination of
      visibility obviously can't be 100% accurate... So if you're 3 space
      polygons are too far from planar, consider breaking them into smaller
      polygons.  <quote>3 points define a plane</quote> :-).
    </para>

    <para>
      <emphasis>Bugs</emphasis>:  If one of the first two segments is of
      zero length, or if they are co-linear, the calculation of visibility
      has a 50/50 chance of being correct.  Avoid such situations :-).  See
      <filename>x18c.c</filename> for an example of this problem.
      (Search for <quote>20.1</quote>).
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>n</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of points defining line.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with x coordinates of points.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with y coordinates of points.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>z</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with z coordinates of points.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>draw</parameter>
	  (<literal>const PLBOOL *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array which controls drawing the segments of the
	    polygon.  If <literal><parameter>draw[i]</parameter></literal> is true,
	    then the polygon segment from index
	    <literal><parameter>[i]</parameter></literal> to
	    <literal><parameter>[i+1]</parameter></literal> is drawn, otherwise, not.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ifcc</parameter>
	  (<literal>PLBOOL</literal>, input)
	</term>
	<listitem>
	  <para>
	    If <literal><parameter>ifcc</parameter></literal> is true
	    the directionality of the polygon is determined by assuming the points
	    are laid out in a counter-clockwise order.  Otherwise,
	    the directionality of the polygon is determined by assuming the points
	    are laid out in a clockwise order.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plpoly3(x, y, z, code)</function>
    </para>

    <para>
      This function is used in example 18.
    </para>

  </sect1>

  <sect1 id="plprec" renderas="sect3">
    <title>
      <function>plprec</function>: Set precision in numeric labels
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plprec</function>
	  </funcdef>
	  <paramdef><parameter>setp</parameter></paramdef>
	  <paramdef><parameter>prec</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets the number of places after the decimal point in numeric labels.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>setp</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    If <literal><parameter>setp</parameter></literal> is equal to 0
	    then PLplot automatically determines the number of places to
	    use after the decimal point in numeric labels (like those used
	    to label axes).  If
	    <literal><parameter>setp</parameter></literal> is 1 then
	    <literal><parameter>prec</parameter></literal> sets the number
	    of places.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>prec</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The number of characters to draw after the decimal point in
	    numeric labels.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plprec(setp, prec)</function>
    </para>

    <para>
      This function is used in example 29.
    </para>

  </sect1>

  <sect1 id="plpsty" renderas="sect3">
    <title>
      <function>plpsty</function>: Select area fill pattern
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plpsty</function>
	  </funcdef>
	  <paramdef><parameter>patt</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Select one of eight predefined area fill patterns to use (also see
      &plpat;). Setting the fill style to 0 gives a solid fill.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>patt</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The desired pattern. Pattern 1 consists of horizontal lines,
	    pattern 2 consists of vertical lines, pattern 3 consists of lines
	    at 45 degrees angle (upward), and so on.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plpsty(patt)</function>
    </para>

    <para>
      This function is used in examples 12,13,15,16,25.
    </para>

  </sect1>

  <sect1 id="plptex" renderas="sect3">
    <title>
      <function>plptex</function>: Write text inside the viewport
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plptex</function>
	  </funcdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>dx</parameter></paramdef>
	  <paramdef><parameter>dy</parameter></paramdef>
	  <paramdef><parameter>just</parameter></paramdef>
	  <paramdef><parameter>text</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Writes text at a specified position and inclination within the
      viewport.  Text is clipped at the viewport boundaries.  The reference
      point of a string lies along a line passing through the string at
      half the height of a capital letter.  The position of the reference
      point along this line is determined by
      <literal><parameter>just</parameter></literal>, the reference point
      is placed at world coordinates <literal>(<parameter>x</parameter>,
      <parameter>y</parameter>)</literal> within the viewport.  The
      inclination of the string is specified in terms of differences of
      world coordinates making it easy to write text parallel to a line in
      a graph.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    x coordinate of reference point of string.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    y coordinate of reference point of string.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>dx</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Together with <literal><parameter>dy</parameter></literal>,
	    this specifies the inclination of the string.  The baseline of
	    the string is parallel to a line joining
	    <literal>(<parameter>x</parameter>,
	    <parameter>y</parameter>)</literal> to
	    <literal>(<parameter>x</parameter>+<parameter>dx</parameter>,
	    <parameter>y</parameter>+<parameter>dy</parameter>)</literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>dy</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Together with <literal><parameter>dx</parameter></literal>,
	    this specifies the inclination of the string.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>just</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Specifies the position of the string relative to its reference
	    point.  If <literal><parameter>just</parameter>=0.</literal>,
	    the reference point is at the left and if
	    <literal><parameter>just</parameter>=1.</literal>, it is at the
	    right of the string.  Other values of
	    <literal><parameter>just</parameter></literal> give
	    intermediate justifications.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>text</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    The string to be written out.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plptex(x, y, dx, dy, just, text)</function>
    </para>

    <para>
      This function is used in example 2-4,10,12-14,20,23,24,26.
    </para>

  </sect1>


  <sect1 id="plptex3" renderas="sect3">
    <title>
      <function>plptex3</function>: Write text inside the viewport of a 3D plot
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plptex3</function>
	  </funcdef>
	  <paramdef><parameter>wx</parameter></paramdef>
	  <paramdef><parameter>wy</parameter></paramdef>
	  <paramdef><parameter>wz</parameter></paramdef>
	  <paramdef><parameter>dx</parameter></paramdef>
	  <paramdef><parameter>dy</parameter></paramdef>
	  <paramdef><parameter>dz</parameter></paramdef>
	  <paramdef><parameter>sx</parameter></paramdef>
	  <paramdef><parameter>sy</parameter></paramdef>
	  <paramdef><parameter>sz</parameter></paramdef>
	  <paramdef><parameter>just</parameter></paramdef>
	  <paramdef><parameter>text</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Writes text at a specified position and inclination and with a
      specified shear within the viewport.  Text is clipped at the viewport
      boundaries.  The reference point of a string lies along a line passing
      through the string at half the height of a capital letter.  The
      position of the reference point along this line is determined by
      <literal><parameter>just</parameter></literal>, and the reference
      point is placed at world coordinates
      <literal>(<parameter>wx</parameter>, <parameter>wy</parameter>,
      <parameter>wz</parameter>)</literal> within the viewport. The
      inclination and shear of the string is specified in terms of
      differences of world coordinates making it easy to write text parallel
      to a line in a graph.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>wx</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    x world coordinate of reference point of string.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>wy</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    y world coordinate of reference point of string.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>wz</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    z world coordinate of reference point of string.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>dx</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Together with <literal><parameter>dy</parameter> and <parameter>
	    dz</parameter></literal>, this specifies the inclination of 
	    the string.  The baseline of the string is parallel to a line 
	    joining <literal>(<parameter>x</parameter>, <parameter>y</parameter>,
	    <parameter>z</parameter>)</literal> to <literal>
	    (<parameter>x</parameter>+<parameter>dx</parameter>,
	    <parameter>y</parameter>+<parameter>dy</parameter>,
	    <parameter>z</parameter>+<parameter>dz</parameter>)</literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>dy</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Together with <literal><parameter>dx</parameter> and
	    <parameter>dz</parameter></literal>,
	    this specifies the inclination of the string.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>dz</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Together with <literal><parameter>dx</parameter> and
	    <parameter>dy</parameter></literal>,
	    this specifies the inclination of the string.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>sx</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Together with <literal><parameter>sy</parameter> and <parameter>
	    sz</parameter></literal>, this specifies the shear of 
	    the string.  The string is sheared so that the characters are 
	    vertically parallel to a line joining <literal>
	    (<parameter>x</parameter>, <parameter>y</parameter>,
	    <parameter>z</parameter>)</literal> to <literal>
	    (<parameter>x</parameter>+<parameter>sx</parameter>,
	    <parameter>y</parameter>+<parameter>sy</parameter>,
	    <parameter>z</parameter>+<parameter>sz</parameter>)</literal>.
	    If <literal><parameter>sx</parameter> = <parameter>sy</parameter>
	    = <parameter>sz</parameter> = 0.)</literal> then the text is not
	    sheared.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>sy</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Together with <literal><parameter>sx</parameter> and
	    <parameter>sz</parameter></literal>,
	    this specifies shear of the string.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>sz</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Together with <literal><parameter>sx</parameter> and
	    <parameter>sy</parameter></literal>,
	    this specifies shear of the string.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>just</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Specifies the position of the string relative to its reference
	    point.  If <literal><parameter>just</parameter>=0.</literal>,
	    the reference point is at the left and if
	    <literal><parameter>just</parameter>=1.</literal>, it is at the
	    right of the string.  Other values of
	    <literal><parameter>just</parameter></literal> give
	    intermediate justifications.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>text</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    The string to be written out.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plptex3(x, y, z, dx, dy, dz, sx, sy, sz, 
      just, text)</function>
    </para>

    <para>
      This function is used in example 28.
    </para>

  </sect1>

  <sect1 id="plrandd" renderas="sect3">
    <title>
      <function>plrandd</function>: Random number generator 
      returning a real random number in the range [0,1]
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plrandd</function>
	  </funcdef>
	  <paramdef></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Random number generator returning a real random number in the 
      range [0,1]. The generator is based on the Mersenne Twister. 
      Most languages / compilers provide their own random number generator, 
      and so this is provided purely for convenience and to give a
      consistent random number generator across all languages supported 
      by PLplot. This is particularly useful for comparing results 
      from the test suite of examples.
    </para>

    <para>
      Redacted form: <function>plrandd()</function>
    </para>

    <para>
      This function is used in examples 17,21.
    </para>

  </sect1>

  <sect1 id="plreplot" renderas="sect3">
    <title>
      <function>plreplot</function>: Replays contents of plot buffer to
      current device/file
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plreplot</function>
	  </funcdef>
	  <paramdef></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Replays contents of plot buffer to current device/file.
    </para>

    <para>
      Redacted form: <function>plreplot()</function>
    </para>

    <para>
      This function is used in example 1,20.
    </para>

  </sect1>

  <sect1 id="plrgbhls" renderas="sect3">
    <title>
      <function>plrgbhls</function>: Convert RGB color to HLS
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plrgbhls</function>
	  </funcdef>
	  <paramdef><parameter>r</parameter></paramdef>
	  <paramdef><parameter>g</parameter></paramdef>
	  <paramdef><parameter>b</parameter></paramdef>
	  <paramdef><parameter>p_h</parameter></paramdef>
	  <paramdef><parameter>p_l</parameter></paramdef>
	  <paramdef><parameter>p_s</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Convert RGB color coordinates to HLS
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>r</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Red intensity (0.0-1.0) of the colour
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>g</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Green intensity (0.0-1.0) of the colour
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>b</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Blue intensity (0.0-1.0) of the colour
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_h</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to hue, in degrees on the colour cone (0.0-360.0)
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_l</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to lightness, expressed as a fraction of the axis of the colour
	    cone (0.0-1.0)
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>p_s</parameter>
	  (<literal>PLFLT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to saturation, expressed as a fraction of the radius of the
	    colour cone (0.0-1.0)
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plrgbhls(r, g, b, p_h, p_l, p_s)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: Not available? Implemented as plrgb/plrgb1?
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in example 2.
    </para>

  </sect1>

  <sect1 id="plschr" renderas="sect3">
    <title>
      <function>plschr</function>: Set character size
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plschr</function>
	  </funcdef>
	  <paramdef><parameter>def</parameter></paramdef>
	  <paramdef><parameter>scale</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      This sets up the size of all subsequent characters drawn.  The actual
      height of a character is the product of the default character size
      and a scaling factor.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>def</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The default height of a character in millimeters, should be set
	    to zero if the default height is to remain unchanged.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>scale</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Scale factor to be applied to default to get actual character
	    height.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plschr(def, scale)</function>
    </para>

    <para>
      This function is used in example 2,13,23,24.
    </para>

  </sect1>

  <sect1 id="plscmap0" renderas="sect3">
    <title>
      <function>plscmap0</function>: Set cmap0 colors by 8-bit RGB values
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plscmap0</function>
	  </funcdef>
	  <paramdef><parameter>r</parameter></paramdef>
	  <paramdef><parameter>g</parameter></paramdef>
	  <paramdef><parameter>b</parameter></paramdef>
	  <paramdef><parameter>ncol0</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set cmap0 colors using 8-bit RGB values (see <xref linkend="color-map-0"/>).  This sets the entire color
      map &ndash; only as many colors as specified will be allocated.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>r</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with set of unsigned 8-bit integers (0-255)
	    representing the degree of red in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>g</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with set of unsigned 8-bit integers (0-255)
	    representing the degree of green in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>b</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with set of unsigned 8-bit integers (0-255)
	    representing the degree of blue in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ncol0</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of items in the
	    <literal><parameter>r</parameter></literal>,
	    <literal><parameter>g</parameter></literal>, and
	    <literal><parameter>b</parameter></literal> arrays.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plscmap0(r, g, b)</function>
    </para>

    <para>
      This function is used in examples 2,24.
    </para>

  </sect1>

  <sect1 id="plscmap0a" renderas="sect3">
    <title>
      <function>plscmap0a</function>: Set cmap0 colors by 8-bit RGB values and 
      double alpha transparency value
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plscmap0a</function>
	  </funcdef>
	  <paramdef><parameter>r</parameter></paramdef>
	  <paramdef><parameter>g</parameter></paramdef>
	  <paramdef><parameter>b</parameter></paramdef>
	  <paramdef><parameter>alpha</parameter></paramdef>
	  <paramdef><parameter>ncol0</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set cmap0 colors using 8-bit RGB values (see <xref linkend="color-map-0"/>) 
      and floating point alpha transparency value.  This sets the entire color
      map &ndash; only as many colors as specified will be allocated.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>r</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with set of unsigned 8-bit integers (0-255)
	    representing the degree of red in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>g</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with set of unsigned 8-bit integers (0-255)
	    representing the degree of green in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>b</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with set of unsigned 8-bit integers (0-255)
	    representing the degree of blue in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>alpha</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with set of PLFLT values (0.0 - 1.0)
	    representing the alpha transparency of the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ncol0</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of items in the
	    <literal><parameter>r</parameter></literal>,
	    <literal><parameter>g</parameter></literal>,
	    <literal><parameter>b</parameter></literal>, and
	    <literal><parameter>alpha</parameter></literal> arrays.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plscmap0a(r, g, b, alpha)</function>
    </para>

    <para>
      This function is used in examples 30.
    </para>

  </sect1>

  <sect1 id="plscmap0n" renderas="sect3">
    <title>
      <function>plscmap0n</function>: Set number of colors in cmap0
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plscmap0n</function>
	  </funcdef>
	  <paramdef><parameter>ncol0</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para> Set number of colors in color map0 (see <xref linkend="color-map-0"/>). Allocate (or reallocate) color map0,
    and fill with default values for those colors not previously allocated.
    The first 16 default colors are given in the &plcol0; documentation.
    For larger indices the default color is red. </para>

    <para>
      The drivers are not guaranteed to support more than 16 colors.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>ncol0</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of colors that will be allocated in the map0 palette.
	    If this number is zero or less, then the value from the
	    previous call to &plscmap0n; is used and if there is no
	    previous call, then a default value is used.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plscmap0n(ncol0)</function>
    </para>

    <para>
      This function is used in examples 15,16,24.
    </para>

  </sect1>

  <sect1 id="plscmap1_range" renderas="sect3">
    <title>
      <function>plscmap1_range</function>: Set the cmap1 argument
      range for continuous color plots
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plscmap1_range</function>
	  </funcdef>
	  <paramdef><parameter>min_color</parameter></paramdef>
	  <paramdef><parameter>max_color</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set the cmap1 argument range for continuous color
      plots. If <parameter>min_color</parameter> is greater than
      <parameter>max_color</parameter> or
      <parameter>max_color</parameter> is greater than 1.0 or
      <parameter>min_color</parameter> is less than 0.0 then no change
      is made.  (Use &plgcmap1_range; to get the cmap1
      argument range.)
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>min_color</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The minimum cmap1 floating point argument.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>max_color</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The maximum cmap1 floating point argument.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plscmap1_range(min_color, max_color)</function>
    </para>

    <para>
      This function is currently used in example 33.
    </para>

  </sect1>

  <sect1 id="plscmap1" renderas="sect3">
    <title>
      <function>plscmap1</function>: Set cmap1 colors using 8-bit RGB
      values
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plscmap1</function>
	  </funcdef>
	  <paramdef><parameter>r</parameter></paramdef>
	  <paramdef><parameter>g</parameter></paramdef>
	  <paramdef><parameter>b</parameter></paramdef>
	  <paramdef><parameter>ncol1</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para> Set cmap1 colors using 8-bit RGB values (see <xref
    linkend="color-map-1"/>).  This also sets the number of colors.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>r</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with set of unsigned 8-bit integers (0-255)
	    representing the degree of red in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>g</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with set of unsigned 8-bit integers (0-255)
	    representing the degree of green in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>b</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with set of unsigned 8-bit integers (0-255)
	    representing the degree of blue in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ncol1</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of items in the
	    <literal><parameter>r</parameter></literal>,
	    <literal><parameter>g</parameter></literal>, and
	    <literal><parameter>b</parameter></literal> arrays.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plscmap1(r, g, b)</function>
    </para>

    <para>
      This function is used in example 31.
    </para>

  </sect1>

  <sect1 id="plscmap1a" renderas="sect3">
    <title>
      <function>plscmap1a</function>: Set cmap1 colors using 8-bit RGB values
      and double alpha transparency values
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plscmap1a</function>
	  </funcdef>
	  <paramdef><parameter>r</parameter></paramdef>
	  <paramdef><parameter>g</parameter></paramdef>
	  <paramdef><parameter>b</parameter></paramdef>
	  <paramdef><parameter>alpha</parameter></paramdef>
	  <paramdef><parameter>ncol1</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para> Set cmap1 colors using 8-bit RGB values (see <xref
    linkend="color-map-1"/>) and double alpha transparency values.
    This also sets the number of colors.</para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>r</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with set of unsigned 8-bit integers (0-255)
	    representing the degree of red in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>g</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with set of unsigned 8-bit integers (0-255)
	    representing the degree of green in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>b</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with set of unsigned 8-bit integers (0-255)
	    representing the degree of blue in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>alpha</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with set of double values (0.0-1.0)
	    representing the alpha transparency value of the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ncol1</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of items in the
	    <literal><parameter>r</parameter></literal>,
	    <literal><parameter>g</parameter></literal>,
	    <literal><parameter>b</parameter></literal>, and
	    <literal><parameter>alpha</parameter></literal> arrays.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plscmap1a(r, g, b, alpha)</function>
    </para>

    <para>
      This function is used in example 31.
    </para>

  </sect1>

  <sect1 id="plscmap1l" renderas="sect3">
    <title>
      <function>plscmap1l</function>: Set cmap1 colors using a
      piece-wise linear relationship
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plscmap1l</function>
	  </funcdef>
	  <paramdef><parameter>itype</parameter></paramdef>
	  <paramdef><parameter>npts</parameter></paramdef>
	  <paramdef><parameter>intensity</parameter></paramdef>
	  <paramdef><parameter>coord1</parameter></paramdef>
	  <paramdef><parameter>coord2</parameter></paramdef>
	  <paramdef><parameter>coord3</parameter></paramdef>
	  <paramdef><parameter>alt_hue_path</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para> Set cmap1 colors using a piece-wise linear relationship
    between intensity index (from 0. to 1.) of cmap1 and position in HLS or
    RGB color space (see <xref linkend="color-map-1"/>).  May be called at
    any time. </para>

    <para>
      The idea here is to specify a number of control points that define
      the mapping between input cmap1 intensity indices and 
      HLS (or RGB).  Between
      these points, linear interpolation is used which
      gives a smooth variation of
      color with intensity index.  Any number of control points may be specified,
      located at arbitrary positions, although typically 2 - 4
      are enough. Another way of stating this is that we are traversing a
      given number of lines through HLS (or RGB) space as we move through
      cmap1 intensity indices.  The control points at the minimum and maximum
      position (0 and 1) must always be specified.  By adding more control
      points you can get more variation.  One good technique for plotting
      functions that vary about some expected average is to use an
      additional 2 control points in the center (position ~= 0.5) that are
      the same lightness as the background (typically white for paper output,
      black for crt), and same hue as the boundary control points.  This
      allows the highs and lows to be very easily distinguished.
    </para>
    <para>
      Each control point must specify the cmap1 intensity index and
      the associated 
      three coordinates in HLS or RGB space.  The first point
      <emphasis>must</emphasis> correspond to position = 0, and the last to
      position = 1.
    </para>

    <para> 
    The default behaviour is for the hue to be linearly interpolated 
    between the control points. Since the hue lies in the range [0, 360] this
    corresponds to interpolation around the "front" of the color wheel
    (red&lt;->green&lt;->blue&lt;->red). If <literal>alt_hue_path[i]</literal> 
    is true, then an alternative interpolation is used between control points
    <literal>i</literal> and <literal>i+1</literal>. If 
    <literal>hue[i+1]-hue[i] > 0</literal> then interpolation is between 
    <literal>hue[i]</literal> and <literal>hue[i+1] - 360</literal>, otherwise 
    between <literal>hue[i]</literal> and <literal>hue[i+1] + 360</literal>. 
    You can consider this as interpolation around the "back" or "reverse" of 
    the color wheel. Specifying <literal>alt_hue_path=NULL</literal> is
    equivalent to setting <literal>alt_hue_path[] = false</literal> for 
    every control point. 
    </para>

    <para>
      <table frame="none"><title> Examples of interpolation </title>
      <tgroup cols="3" align="center" colsep="0" rowsep="0">
        <thead>
          <row><entry>Hue</entry><entry>alt_hue_path</entry><entry>color scheme</entry></row>
        </thead>
	<tbody>
	  <row><entry>[120 240]</entry><entry>false</entry><entry>green-cyan-blue</entry> </row>
	  <row><entry>[240 120]</entry><entry>false</entry><entry>blue-cyan-green</entry> </row>
	  <row><entry>[120 240]</entry><entry>true</entry><entry>green-yellow-red-magenta-blue</entry> </row>
	  <row><entry>[240 120]</entry><entry>true</entry><entry>blue-magenta-red-yellow-green</entry> </row>
	</tbody>
      </tgroup>
      </table>
    </para>

    <para>
      <table frame="none"><title> Bounds on coordinates</title>
      <tgroup cols="4" align="center" colsep="0" rowsep="0">
	<tbody>
	  <row><entry>RGB</entry><entry>R</entry><entry>[0, 1]</entry><entry>magnitude</entry> </row>
	  <row><entry>RGB</entry><entry>G</entry><entry>[0, 1]</entry><entry>magnitude</entry> </row>
	  <row><entry>RGB</entry><entry>B</entry><entry>[0, 1]</entry><entry>magnitude</entry> </row>
	  <row><entry>HLS</entry><entry>hue</entry><entry>[0, 360]</entry><entry>degrees</entry> </row>
	  <row><entry>HLS</entry><entry>lightness</entry><entry>[0, 1]</entry><entry>magnitude</entry> </row>
	  <row><entry>HLS</entry><entry>saturation</entry><entry>[0, 1]</entry><entry>magnitude</entry> </row>
	</tbody>
      </tgroup>
      </table>
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>itype</parameter>
	  (<literal>PLBOOL</literal>, input)
	</term>
	<listitem>
	  <para>
	    true: RGB, false: HLS.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>npts</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    number of control points
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>intensity</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    intensity index for each control point (between 0.0 and 1.0, in
	    ascending order)
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>coord1</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    first coordinate (H or R) for each control point
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>coord2</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    second coordinate (L or G) for each control point
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>coord3</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    third coordinate (S or B) for each control point
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>alt_hue_path</parameter>
	  (<literal>const PLBOOL *</literal>, input)
	</term>
	<listitem>
	  <para>
	    alternative interpolation method flag for each control point. 
            (<literal>alt_hue_path[i]</literal> refers
	    to the interpolation interval between the <literal>i</literal> and
	    <literal>i + 1</literal> control points).
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plscmap1l(itype, intensity, coord1, coord2, coord3, alt_hue_path)</function>
    </para>

    <para>
      This function is used in examples 8,11,12,15,20,21.
    </para>

  </sect1>

  <sect1 id="plscmap1la" renderas="sect3">
    <title>
      <function>plscmap1la</function>: Set cmap1 colors and alpha
      transparency using a piece-wise linear relationship
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plscmap1la</function>
	  </funcdef>
	  <paramdef><parameter>itype</parameter></paramdef>
	  <paramdef><parameter>npts</parameter></paramdef>
	  <paramdef><parameter>intensity</parameter></paramdef>
	  <paramdef><parameter>coord1</parameter></paramdef>
	  <paramdef><parameter>coord2</parameter></paramdef>
	  <paramdef><parameter>coord3</parameter></paramdef>
	  <paramdef><parameter>alpha</parameter></paramdef>	
	  <paramdef><parameter>alt_hue_path</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      This is a variant of &plscmap1l; that supports alpha channel
      transparency. It sets cmap1 colors using a piece-wise linear
      relationship between cmap1 intensity index (from 0. to 1.) and
      position in HLS or RGB color space (see <xref linkend="color-map-1"/>)
      with <literal><parameter>alpha</parameter></literal> transparency value 
      (0.0 - 1.0). It may be called at any time.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>itype</parameter>
	  (<literal>PLBOOL</literal>, input)
	</term>
	<listitem>
	  <para>
	    true: RGB, false: HLS.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>npts</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    number of control points
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>intensity</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    position for each control point (between 0.0 and 1.0, in
	    ascending order)
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>coord1</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    first coordinate (H or R) for each control point
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>coord2</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    second coordinate (L or G) for each control point
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>coord3</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    third coordinate (S or B) for each control point
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>alpha</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    the alpha transparency value for each control point
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>alt_hue_path</parameter>
	  (<literal>const PLBOOL *</literal>, input)
	</term>
	<listitem>
	  <para>
	    alternative interpolation method flag for each control point. 
            (<literal>alt_hue_path[i]</literal> refers
	    to the interpolation interval between the <literal>i</literal> and
	    <literal>i + 1</literal> control points).
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plscmap1la(itype, intensity, coord1,
      coord2, coord3, alpha, alt_hue_path)</function>
    </para>

    <para>
      This function is used in example 30.
    </para>

  </sect1>

  <sect1 id="plscmap1n" renderas="sect3">
    <title>
      <function>plscmap1n</function>: Set number of colors in cmap1
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plscmap1n</function>
	  </funcdef>
	  <paramdef><parameter>ncol1</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para> Set number of colors in cmap1, (re-)allocate color map1, and
    set default values if this is the first allocation (see <xref
    linkend="color-map-1"/>). </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>ncol1</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of colors that will be allocated in the map1 palette.
	    If this number is zero or less, then the value from the
	    previous call to &plscmap1n; is used and if there is no
	    previous call, then a default value is used.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plscmap1n(ncol1)</function>
    </para>

    <para>
      This function is used in examples 8,11,20,21.
    </para>

  </sect1>

  <sect1 id="plscol0" renderas="sect3">
    <title>
      <function>plscol0</function>:  Set 8-bit RGB values for given
      cmap0 color index
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plscol0</function>
	  </funcdef>
	  <paramdef><parameter>icol0</parameter></paramdef>
	  <paramdef><parameter>r</parameter></paramdef>
	  <paramdef><parameter>g</parameter></paramdef>
	  <paramdef><parameter>b</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para> Set 8-bit RGB values for given cmap0 (see <xref
    linkend="color-map-0"/>) index.  Overwrites
    the previous color value for the given index and, thus, does
    not result in any additional allocation of space for colors. </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>icol0</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Color index.  Must be less than the maximum number of colors
	    (which is set by default, by &plscmap0n;, or even by &plscmap0;).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>r</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Unsigned 8-bit integer (0-255) representing
	    the degree of red in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>g</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Unsigned 8-bit integer (0-255) representing
	    the degree of green in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>b</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Unsigned 8-bit integer (0-255) representing
	    the degree of blue in the color.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plscol0(icol0, r, g, b)</function>
    </para>

    <para>
      This function is used in any example 31.
    </para>

  </sect1>

  <sect1 id="plscol0a" renderas="sect3">
    <title>
      <function>plscol0a</function>:  Set 8-bit 
      RGB values and double alpha transparency value for given
      cmap0 color index
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plscol0a</function>
	  </funcdef>
	  <paramdef><parameter>icol0</parameter></paramdef>
	  <paramdef><parameter>r</parameter></paramdef>
	  <paramdef><parameter>g</parameter></paramdef>
	  <paramdef><parameter>b</parameter></paramdef>
	  <paramdef><parameter>alpha</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para> Set 8-bit RGB value and double alpha transparency value for given
    cmap0 (see <xref linkend="color-map-0"/>) index.  Overwrites the previous color value 
    for the given index and, thus, does not result in any additional allocation 
    of space for colors. </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>icol0</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Color index.  Must be less than the maximum number of colors
	    (which is set by default, by &plscmap0n;, or even by &plscmap0;).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>r</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Unsigned 8-bit integer (0-255) representing
	    the degree of red in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>g</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Unsigned 8-bit integer (0-255) representing
	    the degree of green in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>b</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Unsigned 8-bit integer (0-255) representing
	    the degree of blue in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>alpha</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    double value (0.0-1.0) representing the
	    alpha transparency value of the color.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      This function is used in example 30.
    </para>

  </sect1>

  <sect1 id="plscolbg" renderas="sect3">
    <title>
      <function>plscolbg</function>: Set the background color
      by 8-bit RGB value
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plscolbg</function>
	  </funcdef>
	  <paramdef><parameter>r</parameter></paramdef>
	  <paramdef><parameter>g</parameter></paramdef>
	  <paramdef><parameter>b</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set the background color (color 0 in color map 0) by 8-bit RGB value (see
      <xref linkend="color-map-0"/>).
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>r</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Unsigned 8-bit integer (0-255) representing
	    the degree of red in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>g</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Unsigned 8-bit integer (0-255) representing
	    the degree of green in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>b</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Unsigned 8-bit integer (0-255) representing
	    the degree of blue in the color.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plscolbg(r, g, b)</function>
    </para>

    <para>
      This function is used in examples 15,31.
    </para>

  </sect1>

  <sect1 id="plscolbga" renderas="sect3">
    <title>
      <function>plscolbga</function>: Set the background color
      by 8-bit RGB value and double alpha transparency value.
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plscolbga</function>
	  </funcdef>
	  <paramdef><parameter>r</parameter></paramdef>
	  <paramdef><parameter>g</parameter></paramdef>
	  <paramdef><parameter>b</parameter></paramdef>
	  <paramdef><parameter>alpha</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set the background color (color 0 in color map 0) by 8-bit RGB value (see
      <xref linkend="color-map-0"/>) and double alpha transparency value.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>r</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Unsigned 8-bit integer (0-255) representing
	    the degree of red in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>g</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Unsigned 8-bit integer (0-255) representing
	    the degree of green in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>b</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Unsigned 8-bit integer (0-255) representing
	    the degree of blue in the color.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>alpha</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    double value (0.0-1.0) representing the
	    alpha transparency value of the color.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      This function is used in example 31.
    </para>

  </sect1>

  <sect1 id="plscolor" renderas="sect3">
    <title>
      <function>plscolor</function>: Used to globally turn color output on/off
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plscolor</function>
	  </funcdef>
	  <paramdef><parameter>color</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Used to globally turn color output on/off for those drivers/devices
      that support it.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>color</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Color flag (Boolean).  If zero, color is turned off.  If
	    non-zero, color is turned on.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plscolor(color)</function>
    </para>

    <para>
      This function is used in example 31.
    </para>

  </sect1>

  <sect1 id="plscompression" renderas="sect3">
    <title>
      <function>plscompression</function>: Set device-compression level
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plscompression</function>
	  </funcdef>
	  <paramdef><parameter>compression</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set device-compression level.  Only used for drivers that provide
      compression.  This function, if used, should be invoked
      before a call to &plinit;. 
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>compression</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The desired compression level. This is a device-dependent
	    value.
	    Currently only the jpeg and png devices use these values. For jpeg 
	    value is the jpeg quality which should normally be in the range 0-95.
	    Higher values denote higher quality and hence larger image sizes. For
	    png values are in the range -1 to 99. Values of 0-9 are taken as the 
	    compression level for zlib. A value of -1 denotes the default zlib 
	    compression level. Values in the range 10-99 are divided by 10 and 
	    then used as the zlib compression level. Higher compression levels
	    correspond to greater compression and small file sizes at the
	    expense of more computation.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plscompression(compression)</function>
    </para>

    <para>
      This function is used in example 31.
    </para>

  </sect1>

  <sect1 id="plsdev" renderas="sect3">
    <title>
      <function>plsdev</function>: Set the device (keyword) name
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsdev</function>
	  </funcdef>
	  <paramdef><parameter>devname</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set the device (keyword) name.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>devname</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to device (keyword) name string.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plsdev(devname)</function>
    </para>

    <para>
      This function is used in examples 1,14,20.
    </para>

  </sect1>

  <sect1 id="plsdidev" renderas="sect3">
    <title>
      <function>plsdidev</function>: Set parameters that define current
      device-space window
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsdidev</function>
	  </funcdef>
	  <paramdef><parameter>mar</parameter></paramdef>
	  <paramdef><parameter>aspect</parameter></paramdef>
	  <paramdef><parameter>jx</parameter></paramdef>
	  <paramdef><parameter>jy</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set relative margin width, aspect ratio, and relative
      justification that define current device-space window.  If you want to just use the previous value for any of
      these, just pass in the magic value PL_NOTSET. It is unlikely that one
      should ever need to change the aspect ratio but it's in there for
      completeness.
      If &plsdidev; is not called the default values
      of <literal><parameter>mar</parameter></literal>,
      <literal><parameter>jx</parameter></literal>, and
      <literal><parameter>jy</parameter></literal>
      are all 0. <literal><parameter>aspect</parameter></literal>
      is set to a device-specific value.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>mar</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Relative margin width.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>aspect</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Aspect ratio.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>jx</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Relative justification in x. Value must lie in the
	    range -0.5 to 0.5.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>jy</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Relative justification in y. Value must lie in the
	    range -0.5 to 0.5.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plsdidev(mar, aspect, jx, jy)</function>
    </para>

    <para>
      This function is used in example 31.
    </para>

  </sect1>

  <sect1 id="plsdimap" renderas="sect3">
    <title>
      <function>plsdimap</function>: Set up transformation from metafile
      coordinates
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsdimap</function>
	  </funcdef>
	  <paramdef><parameter>dimxmin</parameter></paramdef>
	  <paramdef><parameter>dimxmax</parameter></paramdef>
	  <paramdef><parameter>dimymin</parameter></paramdef>
	  <paramdef><parameter>dimymax</parameter></paramdef>
	  <paramdef><parameter>dimxpmm</parameter></paramdef>
	  <paramdef><parameter>dimypmm</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set up transformation from metafile coordinates.  The size of the plot
      is scaled so as to preserve aspect ratio.  This isn't intended to be a
      general-purpose facility just yet (not sure why the user would need
      it, for one).
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>dimxmin</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    NEEDS DOCUMENTATION
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>dimxmax</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    NEEDS DOCUMENTATION
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>dimymin</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    NEEDS DOCUMENTATION
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>dimymax</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    NEEDS DOCUMENTATION
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>dimxpmm</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    NEEDS DOCUMENTATION
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>dimypmm</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    NEEDS DOCUMENTATION
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plsdimap(dimxmin, dimxmax, dimymin, dimymax, dimxpmm, dimypmm)</function>
    </para>

    <para>
      This function is not used in any examples.
    </para>

  </sect1>

  <sect1 id="plsdiori" renderas="sect3">
    <title>
      <function>plsdiori</function>: Set plot orientation
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsdiori</function>
	  </funcdef>
	  <paramdef><parameter>rot</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set plot orientation parameter which is multiplied by 90&deg; to
      obtain the angle of rotation.  Note, arbitrary rotation parameters
      such as 0.2 (corresponding to 18&deg;) are possible, but the usual
      values for the rotation parameter are 0., 1., 2., and 3. corresponding
      to 0&deg; (landscape mode), 90&deg; (portrait mode), 180&deg;
      (seascape mode), and 270&deg; (upside-down mode).  If &plsdiori; is
      not called the default value of
      <literal><parameter>rot</parameter></literal> is 0.
    </para>
    <para>
      N.B. aspect ratio is unaffected by calls to &plsdiori;.  So you will
      probably want to change the aspect ratio to a value suitable for the
      plot orientation using a call to &plsdidev; or the command-line
      options <literal><parameter>-a</parameter></literal> or
      <literal><parameter>-freeaspect</parameter></literal>.  For more
      documentation of those options see <xref linkend="arguments"/>.  Such
      command-line options can be set internally using &plsetopt; or set
      directly using the command line and parsed using a call to 
      &plparseopts;.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>rot</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Plot orientation parameter.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plsdiori(rot)</function>
    </para>

    <para>
      This function is not used in any examples.
    </para>

  </sect1>

  <sect1 id="plsdiplt" renderas="sect3">
    <title>
      <function>plsdiplt</function>: Set parameters that define current
      plot-space window
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsdiplt</function>
	  </funcdef>
	  <paramdef><parameter>xmin</parameter></paramdef>
	  <paramdef><parameter>ymin</parameter></paramdef>
	  <paramdef><parameter>xmax</parameter></paramdef>
	  <paramdef><parameter>ymax</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set relative minima and maxima that define the current
      plot-space window.  If &plsdiplt; is not called the default values
      of <literal><parameter>xmin</parameter></literal>,
      <literal><parameter>ymin</parameter></literal>,
      <literal><parameter>xmax</parameter></literal>, and
      <literal><parameter>ymax</parameter></literal>
      are 0., 0., 1., and 1.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>xmin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Relative minimum in x.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Relative minimum in y.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xmax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Relative maximum in x.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Relative maximum in y.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plsdiplt(xmin, ymin, xmax, ymax)</function>
    </para>

    <para>
      This function is used in example 31.
    </para>

  </sect1>

  <sect1 id="plsdiplz" renderas="sect3">
    <title>
      <function>plsdiplz</function>: Set parameters incrementally (zoom mode)
      that define current plot-space window
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsdiplz</function>
	  </funcdef>
	  <paramdef><parameter>xmin</parameter></paramdef>
	  <paramdef><parameter>ymin</parameter></paramdef>
	  <paramdef><parameter>xmax</parameter></paramdef>
	  <paramdef><parameter>ymax</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set relative minima and maxima incrementally (zoom mode)
      that define the current plot-space window.  This function has
      the same effect as &plsdiplt; if that function has not been previously
      called.  Otherwise, this function implements zoom mode using the
      transformation <literal>min_used = old_min + old_length*min </literal>
      and <literal>max_used = old_min + old_length*max </literal> for
      each axis.  For example, if <literal>min = 0.05</literal> and
      <literal>max = 0.95</literal> for each axis, repeated calls to
      &plsdiplz; will zoom in by 10 per cent for each call.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>xmin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Relative (incremental) minimum in x.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Relative (incremental) minimum in y.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xmax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Relative (incremental) maximum in x.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Relative (incremental) maximum in y.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plsdiplz(xmin, ymin, xmax, ymax)</function>
    </para>

    <para>
      This function is used in example 31.
    </para>

  </sect1>

  <sect1 id="plsdrawmode" renderas="sect3">
    <title>
      <function>plsdrawmode</function>: Set drawing mode (depends on
device support!)
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsdrawmode</function>
	  </funcdef>
	  <paramdef>mode</paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set drawing mode.  Note only one device driver (cairo) currently
      supports this at the moment.  See also &plgdrawmode;.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>mode</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Control variable which species the drawing mode (one of
           <literal>PL_DRAWMODE_DEFAULT</literal>,
	   <literal>PL_DRAWMODE_REPLACE</literal>, or
	   <literal>PL_DRAWMODE_XOR</literal>) to use.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plsdrawmode(mode)</function>
    </para>

    <para>
      This function is used in example 34.
    </para>

  </sect1>

  <sect1 id="plseed" renderas="sect3">
    <title>
      <function>plseed</function>: Set seed for internal random 
      number generator.
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plseed</function>
	  </funcdef>
	  <paramdef><parameter>seed</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set the seed for the internal random number generator. See &plrandd; 
      for further details.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>seed</parameter>
	  (<literal>unsigned int</literal>, input)
	</term>
	<listitem>
	  <para>
	    Seed for random number generator.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plseed(seed)</function>
    </para>

    <para>
      This function is used in example 21.
    </para>

  </sect1>

  <sect1 id="plsesc" renderas="sect3">
    <title>
      <function>plsesc</function>: Set the escape character for text strings
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsesc</function>
	  </funcdef>
	  <paramdef><parameter>esc</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set the escape character for text strings.  From C (in contrast to
      Fortran 95, see &plsescfortran95;) you pass
      <literal><parameter>esc</parameter></literal> as a character.
      Only selected characters are allowed to prevent the user from shooting
      himself in the foot (For example, a <quote>\</quote> isn't allowed since it conflicts with C's use
      of backslash as a character escape).  Here are the allowed escape
      characters and their corresponding decimal ASCII values:
      <itemizedlist>
	<listitem>
	  <para>
	    <quote>!</quote>, ASCII 33
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <quote>#</quote>, ASCII 35
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <quote>$</quote>, ASCII 36
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <quote>%</quote>, ASCII 37
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <quote>&amp;</quote>, ASCII 38
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <quote>*</quote>, ASCII 42
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <quote>@</quote>, ASCII 64
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <quote>^</quote>, ASCII 94
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <quote>~</quote>, ASCII 126
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>esc</parameter>
	  (<literal>char</literal>, input)
	</term>
	<listitem>
	  <para>
	    Escape character.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plsesc(esc)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: Not available?
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in example 29.
    </para>

  </sect1>

  <sect1 id="plsetopt" renderas="sect3">
    <title>
      <function>plsetopt</function>: Set any command-line option
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>int
	  <function>plsetopt</function>
	  </funcdef>
	  <paramdef><parameter>opt</parameter></paramdef>
	  <paramdef><parameter>optarg</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set any command-line option internally from a program before it invokes
      &plinit;. <literal>opt</literal> is the name of the command-line
      option and <literal>optarg</literal> is the corresponding command-line
      option argument. 
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>opt</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to string containing the command-line option.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>optarg</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to string containing the argument of the command-line
	    option.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      This function returns 0 on success.
    </para>

    <para>
      Redacted form: <function>plsetopt(opt, optarg)</function>
    </para>

    <para>
      This function is used in example 14.
    </para>

  </sect1>

  <sect1 id="plsfam" renderas="sect3">
    <title>
      <function>plsfam</function>: Set family file parameters
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsfam</function>
	  </funcdef>
	  <paramdef><parameter>fam</parameter></paramdef>
	  <paramdef><parameter>num</parameter></paramdef>
	  <paramdef><parameter>bmax</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets variables dealing with output file familying.  Does nothing if
      familying not supported by the driver.  This routine, if used, must
      be called before initializing PLplot.  See <xref linkend="familying"/>
      for more information.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>fam</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Family flag (Boolean).  If nonzero, familying is enabled.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>num</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Current family file number.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>bmax</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Maximum file size (in bytes) for a family file.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plsfam(fam, num, bmax)</function>
    </para>

    <para>
      This function is used in examples 14,31.
    </para>

  </sect1>

  <sect1 id="plsfci" renderas="sect3">
    <title>
      <function>plsfci</function>: Set FCI (font characterization integer)
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsfci</function>
	  </funcdef>
	  <paramdef><parameter>fci</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets font characteristics to be used at the start of the next string
      using the FCI approach.
      See <xref linkend="fci"/> for more information.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>fci</parameter>
	  (<literal>PLUNICODE</literal>, input)
	</term>
	<listitem>
	  <para>
	    PLUNICODE (unsigned 32-bit integer) value of FCI.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plsfci(fci)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: Not available?
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in example 23.
    </para>

  </sect1>

  <sect1 id="plsfnam" renderas="sect3">
    <title>
      <function>plsfnam</function>: Set output file name
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsfnam</function>
	  </funcdef>
	  <paramdef><parameter>fnam</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets the current output file name, if applicable.  If the file name
      has not been specified and is required by the driver, the user will
      be prompted for it.  If using the X-windows output driver, this sets
      the display name.  This routine, if used, must be called before
      initializing PLplot.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>fnam</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to file name string.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plsfnam(fnam)</function>
    </para>

    <para>
      This function is used in examples 1,20.
    </para>

  </sect1>

  <sect1 id="plsfont" renderas="sect3">
    <title>
      <function>plsfont</function>: Set family, style and weight of the
      current font
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsfont</function>
	  </funcdef>
	  <paramdef><parameter>family</parameter></paramdef>
	  <paramdef><parameter>style</parameter></paramdef>
	  <paramdef><parameter>weight</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets the current font.  See <xref
      linkend="fci"/> for more information on font selection.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>family</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Font family to select for the current font. The available
	    values are given by the PL_FCI_* constants in
	    plplot.h. Current options are PL_FCI_SANS, PL_FCI_SERIF, 
	    PL_FCI_MONO, PL_FCI_SCRIPT and PL_FCI_SYMBOL. A
	    negative value signifies that the font family should not be
	    altered. 
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>style</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Font style to select for the current font. The available
	    values are given by the PL_FCI_* constants in
	    plplot.h. Current options are PL_FCI_UPRIGHT, PL_FCI_ITALIC
	    and PL_FCI_OBLIQUE. A
	    negative value signifies that the font style should not be
	    altered. 
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>weight</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Font weight to select for the current font. The available
	    values are given by the PL_FCI_* constants in
	    plplot.h. Current options are PL_FCI_MEDIUM and PL_FCI_BOLD.
	    A negative value signifies that the font weight should not
	    be altered. 
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plsfont(family, style, weight)</function>
    </para>

    <para>
      This function is used in example 23.
    </para>

  </sect1>

  <sect1 id="plshades" renderas="sect3">
    <title>
      <function>plshades</function>: Shade regions on the basis of value
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plshades</function>
	  </funcdef>
	  <paramdef><parameter>a</parameter></paramdef>
	  <paramdef><parameter>nx</parameter></paramdef>
	  <paramdef><parameter>ny</parameter></paramdef>
	  <paramdef><parameter>defined</parameter></paramdef>
	  <paramdef><parameter>xmin</parameter></paramdef>
	  <paramdef><parameter>xmax</parameter></paramdef>
	  <paramdef><parameter>ymin</parameter></paramdef>
	  <paramdef><parameter>ymax</parameter></paramdef>
	  <paramdef><parameter>clevel</parameter></paramdef>
	  <paramdef><parameter>nlevel</parameter></paramdef>
	  <paramdef><parameter>fill_width</parameter></paramdef>
	  <paramdef><parameter>cont_color</parameter></paramdef>
	  <paramdef><parameter>cont_width</parameter></paramdef>
	  <paramdef><parameter>fill</parameter></paramdef>
	  <paramdef><parameter>rectangular</parameter></paramdef>
	  <paramdef><parameter>pltr</parameter></paramdef>
	  <paramdef><parameter>pltr_data</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Shade regions on the basis of value.  This is the high-level routine
      for making continuous color shaded plots with cmap1 while
      &plshade; (or &plshade1;) are used for individual shaded regions
      using either cmap0 or cmap1.
      <filename>examples/c/x16c.c</filename> shows a number of examples
      for using this function.
      See the following discussion of the
      arguments and <xref linkend="contour-plots"/> for
    more information.    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>a</parameter>
	  (<literal>const PLFLT * const *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Contains ** pointer to array to be plotted. The array must have been declared
	    as PLFLT a[nx][ny].
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nx</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    First dimension of array "a".
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ny</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Second dimension of array "a".
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>defined</parameter>
	  (<literal>PLINT (*) (PLFLT, PLFLT)</literal>, input)
	</term>
	<listitem>
	  <para>
	    User function specifying regions excluded from the shading
	    plot.  This function accepts x and y coordinates as input
	    arguments and must return 0 if the point is in the excluded
	    region or 1 otherwise. This argument can be NULL if all the
	    values are valid.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xmin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Defines the "grid" coordinates.  The data a[0][0] has a
	    position of (xmin,ymin), a[nx-1][0] has a position at (xmax,ymin)
	    and so on.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xmax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Defines the "grid" coordinates.  The data a[0][0] has a
	    position of (xmin,ymin), a[nx-1][0] has a position at (xmax,ymin)
	    and so on.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Defines the "grid" coordinates.  The data a[0][0] has a
	    position of (xmin,ymin), a[nx-1][0] has a position at (xmax,ymin)
	    and so on.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Defines the "grid" coordinates.  The data a[0][0] has a
	    position of (xmin,ymin), a[nx-1][0] has a position at (xmax,ymin)
	    and so on.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>clevel</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array containing the data levels corresponding to
	    the edges of each shaded region that will be plotted by this
	    function.  To work properly the levels should be monotonic.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nlevel</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of shades plus 1 (i.e., the number of shade edge values
	    in <literal><parameter>clevel</parameter></literal>).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>fill_width</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Defines line width used by the fill pattern.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>cont_color</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Defines pen color used for contours defining edges of shaded
	    regions.  The pen color is only temporary set for the
	    contour drawing.  Set this value to zero or less if no shade edge contours are wanted.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>cont_width</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Defines line width used for contours defining edges of shaded
	    regions.  This value may not be honored by all drivers.
	    The pen width is only temporary set for the
	    contour drawing.  Set this value to zero or less if no shade edge contours are wanted.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>fill</parameter>
	  (<literal>void (*) (PLINT, const PLFLT *, const PLFLT *)</literal>, input)
	</term>
	<listitem>
	  <para>
	    Routine used to fill the region.  Use &plfill;.  Future version of
	    PLplot may have other fill routines.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>rectangular</parameter>
	  (<literal>PLBOOL</literal>, input)
	</term>
	<listitem>
	  <para>
	    Set <literal><parameter>rectangular</parameter></literal> to true
	    if rectangles map to rectangles after coordinate transformation
	    with <literal><parameter>pltrl</parameter></literal>.  Otherwise,
	    set <literal><parameter>rectangular</parameter></literal> to false.
	    If <literal><parameter>rectangular</parameter></literal>
	    is set to true, plshade tries to save time by
	    filling large rectangles.  This optimization fails if
	    the coordinate transformation distorts the shape of rectangles.
	    For example a plot in polar coordinates has to have 
	    <literal><parameter>rectangular</parameter></literal>
	    set to false.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>pltr</parameter>
	  (<literal>void (*) (PLFLT, PLFLT, PLFLT *, PLFLT *, PLPointer)
	  </literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to function that defines transformation between indices
	    in array <literal><parameter>z</parameter></literal> and the
	    world coordinates (C only).  Transformation functions are
	    provided in the PLplot library:
	    &pltr0; for identity mapping, and &pltr1; and &pltr2; for
	    arbitrary mappings respectively defined by one- and
	    two-dimensional arrays.  In addition, user-supplied routines
	    for the transformation can be used as well.  Examples of
	    all of these approaches are given in
	    <xref linkend="contour-plots-c"/>.
	    The transformation function should
	    have the form given by any of &pltr0;, &pltr1;, or &pltr2;.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>pltr_data</parameter>
	  (<literal>PLPointer</literal>, input)
	</term>
	<listitem>
	  <para>
	    Extra parameter to help
	    pass information to &pltr0;, &pltr1;, &pltr2;, or whatever routine
	    that is externally supplied.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plshades(a, defined, xmin, xmax, ymin, ymax, clevel, fill_width, cont_color, cont_width, fill, rectangular, pltr, pltr_data)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: <function>plshades(a, xmin, xmax, ymin, ymax, clevel, fill_width, cont_color, cont_width, fill, rectangular, defined, pltr, pltr_data)</function>
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in examples 16,21.
    </para>

  </sect1>

  <sect1 id="plshade" renderas="sect3">
    <title>
      <function>plshade</function>:  Shade individual region on the basis of value
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plshade</function>
	  </funcdef>
	  <paramdef><parameter>a</parameter></paramdef>
	  <paramdef><parameter>nx</parameter></paramdef>
	  <paramdef><parameter>ny</parameter></paramdef>
	  <paramdef><parameter>defined</parameter></paramdef>
	  <paramdef><parameter>xmin</parameter></paramdef>
	  <paramdef><parameter>xmax</parameter></paramdef>
	  <paramdef><parameter>ymin</parameter></paramdef>
	  <paramdef><parameter>ymax</parameter></paramdef>
	  <paramdef><parameter>shade_min</parameter></paramdef>
	  <paramdef><parameter>shade_max</parameter></paramdef>
	  <paramdef><parameter>sh_cmap</parameter></paramdef>
	  <paramdef><parameter>sh_color</parameter></paramdef>
	  <paramdef><parameter>sh_width</parameter></paramdef>
	  <paramdef><parameter>min_color</parameter></paramdef>
	  <paramdef><parameter>min_width</parameter></paramdef>
	  <paramdef><parameter>max_color</parameter></paramdef>
	  <paramdef><parameter>max_width</parameter></paramdef>
	  <paramdef><parameter>fill</parameter></paramdef>
	  <paramdef><parameter>rectangular</parameter></paramdef>
	  <paramdef><parameter>pltr</parameter></paramdef>
	  <paramdef><parameter>pltr_data</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Shade individual region on the basis of value.  Use &plshades; if you want to
      shade a number of regions using continuous colors.
      &plshade; is identical to &plshade1;
      except for the type of the first parameter.
      See &plshade1; for further discussion.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>a</parameter>
	  (<literal>const PLFLT * const *</literal>, input)
	</term>
	<listitem>
	  <para>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nx</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ny</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>defined</parameter>
	  (<literal>PLINT (*) (PLFLT, PLFLT)</literal>, input)
	</term>
	<listitem>
	  <para>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xmin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xmax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>shade_min</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>shade_max</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>sh_cmap</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>sh_color</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>sh_width</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>min_color</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>min_width</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>max_color</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>max_width</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>fill</parameter>
	  (<literal>void (*) (PLINT, const PLFLT *, const PLFLT *)</literal>, input)
	</term>
	<listitem>
	  <para>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>rectangular</parameter>
	  (<literal>PLBOOL</literal>, input)
	</term>
	<listitem>
	  <para>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>pltr</parameter>
	  (<literal>void (*) (PLFLT, PLFLT, PLFLT *, PLFLT *, PLPointer)
	  </literal>, input)
	</term>
	<listitem>
	  <para>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>pltr_data</parameter>
	  (<literal>PLPointer</literal>, input)
	</term>
	<listitem>
	  <para>
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plshade(a, defined, xmin, xmax, ymin, ymax, shade_min, shade_max, sh_cmap, sh_color, sh_width, min_color, min_width, max_color, max_width, fill, rectangular, pltr, pltr_data)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: Not available?
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in example 15.
    </para>

  </sect1>

  <sect1 id="plshade1" renderas="sect3">
    <title>
      <function>plshade1</function>: Shade individual region on the basis of value
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plshade1</function>
	  </funcdef>
	  <paramdef><parameter>a</parameter></paramdef>
	  <paramdef><parameter>nx</parameter></paramdef>
	  <paramdef><parameter>ny</parameter></paramdef>
	  <paramdef><parameter>defined</parameter></paramdef>
	  <paramdef><parameter>xmin</parameter></paramdef>
	  <paramdef><parameter>xmax</parameter></paramdef>
	  <paramdef><parameter>ymin</parameter></paramdef>
	  <paramdef><parameter>ymax</parameter></paramdef>
	  <paramdef><parameter>shade_min</parameter></paramdef>
	  <paramdef><parameter>shade_max</parameter></paramdef>
	  <paramdef><parameter>sh_cmap</parameter></paramdef>
	  <paramdef><parameter>sh_color</parameter></paramdef>
	  <paramdef><parameter>sh_width</parameter></paramdef>
	  <paramdef><parameter>min_color</parameter></paramdef>
	  <paramdef><parameter>min_width</parameter></paramdef>
	  <paramdef><parameter>max_color</parameter></paramdef>
	  <paramdef><parameter>max_width</parameter></paramdef>
	  <paramdef><parameter>fill</parameter></paramdef>
	  <paramdef><parameter>rectangular</parameter></paramdef>
	  <paramdef><parameter>pltr</parameter></paramdef>
	  <paramdef><parameter>pltr_data</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Shade individual region on the basis of value.  Use &plshades; if you want to
      shade a number of contiguous regions using continuous colors.  In
      particular the edge contours are treated properly in &plshades;.
      If you attempt to do contiguous regions with &plshade1; (or &plshade;)
      the contours at the edge of the shade are partially obliterated by subsequent
      plots of contiguous shaded regions.
      &plshade1; differs from &plshade; by the type of the first
      argument.  Look at the argument list below, &plcont; and
      <xref linkend="contour-plots"/> for
      more information about the transformation from grid to world
      coordinates.  Shading NEEDS DOCUMENTATION, but
      as a stopgap look at how &plshade; is used in
      <filename>examples/c/x15c.c</filename>
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>a</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Contains array to be plotted. The array must have been declared
	    as PLFLT a[nx][ny].
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nx</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    First dimension of array "a".
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ny</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Second dimension of array "a".
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>defined</parameter>
	  (<literal>PLINT (*) (PLFLT, PLFLT)</literal>, input)
	</term>
	<listitem>
	  <para>
	    User function specifying regions excluded from the shading
	    plot.  This function accepts x and y coordinates as input
	    arguments and must return 0 if the point is in the excluded
	    region or 1 otherwise. This argument can be NULL if all the
	    values are valid.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xmin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Defines the "grid" coordinates.  The data a[0][0] has a
	    position of (xmin,ymin), a[nx-1][0] has a position at (xmax,ymin)
	    and so on.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xmax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Defines the "grid" coordinates.  The data a[0][0] has a
	    position of (xmin,ymin), a[nx-1][0] has a position at (xmax,ymin)
	    and so on.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Defines the "grid" coordinates.  The data a[0][0] has a
	    position of (xmin,ymin), a[nx-1][0] has a position at (xmax,ymin)
	    and so on.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Defines the "grid" coordinates.  The data a[0][0] has a
	    position of (xmin,ymin), a[nx-1][0] has a position at (xmax,ymin)
	    and so on.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>shade_min</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Defines the lower end of the interval to be shaded. If
	    shade_max &leq; shade_min, &plshade1; does nothing.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>shade_max</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Defines the upper end of the interval to be shaded. If
	    shade_max &leq; shade_min,
	    &plshade1; does nothing.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>sh_cmap</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Defines color map. If 
	    <literal><parameter>sh_cmap</parameter>=0</literal>, then
	    <literal><parameter>sh_color</parameter></literal>
	    is interpreted as a color map 0 (integer) index.  If 
	    <literal><parameter>sh_cmap</parameter>=1</literal>, then
	    <literal><parameter>sh_color</parameter></literal>
	    is interpreted as a color map 1 floating-point index which
	    ranges from 0. to 1.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>sh_color</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Defines color map index if cmap0 or color map input value (ranging
	    from 0. to 1.) if cmap1.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>sh_width</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Defines width used by the fill pattern.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>min_color</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Defines pen color, width used by the boundary of shaded region.
	    The min values are used for the shade_min boundary, and the max
	    values are used on the shade_max boundary.  Set color and width
	    to zero for no plotted boundaries.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>min_width</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Defines pen color, width used by the boundary of shaded region.
	    The min values are used for the shade_min boundary, and the max
	    values are used on the shade_max boundary.  Set color and width
	    to zero for no plotted boundaries.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>max_color</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Defines pen color, width used by the boundary of shaded region.
	    The min values are used for the shade_min boundary, and the max
	    values are used on the shade_max boundary.  Set color and width
	    to zero for no plotted boundaries.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>max_width</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Defines pen color, width used by the boundary of shaded region.
	    The min values are used for the shade_min boundary, and the max
	    values are used on the shade_max boundary.  Set color and width
	    to zero for no plotted boundaries.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>fill</parameter>
	  (<literal>void (*) (PLINT, const PLFLT *, const PLFLT *)</literal>, input)
	</term>
	<listitem>
	  <para>
	    Routine used to fill the region.  Use &plfill;.  Future version of
	    plplot may have other fill routines.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>rectangular</parameter>
	  (<literal>PLBOOL</literal>, input)
	</term>
	<listitem>
	  <para>
	    Set <literal><parameter>rectangular</parameter></literal> to true
	    if rectangles map to rectangles after coordinate transformation
	    with <literal><parameter>pltrl</parameter></literal>.  Otherwise,
	    set <literal><parameter>rectangular</parameter></literal> to false.
	    If <literal><parameter>rectangular</parameter></literal>
	    is set to true, plshade tries to save time by
	    filling large rectangles.  This optimization fails if
	    the coordinate transformation distorts the shape of rectangles.
	    For example a plot in polar coordinates has to have
	    <literal><parameter>rectangular</parameter></literal>
	    set to false.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>pltr</parameter>
	  (<literal>void (*) (PLFLT, PLFLT, PLFLT *, PLFLT *, PLPointer)
	  </literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to function that defines transformation between indices
	    in array <literal><parameter>z</parameter></literal> and the
	    world coordinates (C only).  Transformation functions are
	    provided in the PLplot library:
	    &pltr0; for identity mapping, and &pltr1; and &pltr2; for
	    arbitrary mappings respectively defined by one- and
	    two-dimensional arrays.  In addition, user-supplied routines
	    for the transformation can be used as well.  Examples of
	    all of these approaches are given in
	    <xref linkend="contour-plots-c"/>.
	    The transformation function should
	    have the form given by any of &pltr0;, &pltr1;, or &pltr2;.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>pltr_data</parameter>
	  (<literal>PLPointer</literal>, input)
	</term>
	<listitem>
	  <para>
	    Extra parameter to help
	    pass information to &pltr0;, &pltr1;, &pltr2;, or whatever routine
	    that is externally supplied.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plshade1(a, defined, xmin, xmax, ymin, ymax, shade_min, shade_max, sh_cmap, sh_color, sh_width, min_color, min_width, max_color, max_width, fill, rectangular, pltr, pltr_data)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: <function>plshade1(a, xmin, xmax, ymin, ymax, shade_min, shade_max, sh_cmap, sh_color, sh_width, min_color, min_width, max_color, max_width, fill, rectangular, defined, pltr, pltr_data)</function>
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in example 15.
    </para>

  </sect1>

  <sect1 id="plslabelfunc" renderas="sect3">
    <title>
      <function>plslabelfunc</function>: Assign a function to use for generating custom axis labels
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plslabelfunc</function>
	  </funcdef>
	  <paramdef><parameter>label_func</parameter></paramdef>
	  <paramdef><parameter>label_data</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      This function allows a user to provide their own function to provide
      axis label text.  The user function is given the numeric value for a
      point on an axis and returns a string label to correspond with that
      value.  Custom axis labels can be enabled by passing appropriate
      arguments to &plenv;, &plbox;, &plbox3; and similar functions.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>label_func</parameter>
	  (<literal>void (*) (PLINT, PLFLT, char *, PLINT, PLPointer)</literal>, input)
	</term>
	<listitem>
	  <para>
	    This is the custom label function.  In order to reset to the
	    default labelling, set this to <literal>NULL</literal>.
	    The labelling function parameters are, in order:
	    <variablelist>
	      <varlistentry>
		<term><parameter>axis</parameter></term>
		<listitem>
		  <para>
		    This indicates which axis a label is being requested for.
		    The value will be one of <literal>PL_X_AXIS</literal>,
		    <literal>PL_Y_AXIS</literal> or
		    <literal>PL_Z_AXIS</literal>.
		  </para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term><parameter>value</parameter></term>
		<listitem>
		  <para>
		    This is the value along the axis which is being labelled.
		  </para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term><parameter>label_text</parameter></term>
		<listitem>
		  <para>
		    The string representation of the label
		    <literal>value</literal>.
		  </para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term><parameter>length</parameter></term>
		<listitem>
		  <para>
		    The maximum length in characters allowed for
		    <literal>label_text</literal>.
		  </para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>label_data</parameter>
	  (<literal>PLPointer</literal>, input)
	</term>
	<listitem>
	  <para>
	    This parameter may be used to pass data to the
	    <literal>label_func</literal> function.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      This function is used in example 19.
    </para>

  </sect1>

  <sect1 id="plsmaj" renderas="sect3">
    <title>
      <function>plsmaj</function>: Set length of major ticks
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsmaj</function>
	  </funcdef>
	  <paramdef><parameter>def</parameter></paramdef>
	  <paramdef><parameter>scale</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      This sets up the length of the major ticks.  The actual length is the
      product of the default length and a scaling factor as for character
      height.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>def</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The default length of a major tick in millimeters, should be
	    set to zero if the default length is to remain unchanged.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>scale</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Scale factor to be applied to default to get actual tick
	    length.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plsmaj(def, scale)</function>
    </para>

    <para>
      This function is used in example 29.
    </para>

  </sect1>

  <sect1 id="plsmem" renderas="sect3">
    <title>
      <function>plsmem</function>: Set the memory area to be plotted (RGB)
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsmem</function>
	  </funcdef>
	  <paramdef><parameter>maxx</parameter></paramdef>
	  <paramdef><parameter>maxy</parameter></paramdef>
	  <paramdef><parameter>plotmem</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set the memory area to be plotted (with the <quote>mem</quote> or
      <quote>memcairo</quote> driver)
      as the <literal>dev</literal> member of the stream structure.  Also
      set the number of pixels in the memory passed in
      <parameter>plotmem</parameter>, which is a block of memory
      <parameter>maxy</parameter> by <parameter>maxx</parameter> by 3 bytes
      long, say: 480 x 640 x 3 (Y, X, RGB)
    </para>

    <para>
      This memory will have to be freed by the user!
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>maxx</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Size of memory area in the X coordinate.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>maxy</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Size of memory area in the Y coordinate.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>plotmem</parameter>
	  (<literal>void *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to the beginning of the user-supplied memory area.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plsmem(maxx, maxy, plotmem)</function>
    </para>

    <para>
      This function is not used in any examples.
    </para>

  </sect1>

  <sect1 id="plsmema" renderas="sect3">
    <title>
      <function>plsmema</function>: Set the memory area to be plotted (RGBA)
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsmema</function>
	  </funcdef>
	  <paramdef><parameter>maxx</parameter></paramdef>
	  <paramdef><parameter>maxy</parameter></paramdef>
	  <paramdef><parameter>plotmem</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set the memory area to be plotted (with the <quote>memcairo</quote> 
      driver) as the <literal>dev</literal> member of the stream structure.
      Also set the number of pixels in the memory passed in
      <parameter>plotmem</parameter>, which is a block of memory
      <parameter>maxy</parameter> by <parameter>maxx</parameter> by 4 bytes
      long, say: 480 x 640 x 4 (Y, X, RGBA)
    </para>

    <para>
      This memory will have to be freed by the user!
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>maxx</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Size of memory area in the X coordinate.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>maxy</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Size of memory area in the Y coordinate.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>plotmem</parameter>
	  (<literal>void *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to the beginning of the user-supplied memory area.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plsmema(maxx, maxy, plotmem)</function>
    </para>

    <para>
      This function is not used in any examples.
    </para>

  </sect1>

  <sect1 id="plsmin" renderas="sect3">
    <title>
      <function>plsmin</function>: Set length of minor ticks
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsmin</function>
	  </funcdef>
	  <paramdef><parameter>def</parameter></paramdef>
	  <paramdef><parameter>scale</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      This sets up the length of the minor ticks and the length of the
      terminals on error bars.  The actual length is the product of the
      default length and a scaling factor as for character height.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>def</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The default length of a minor tick in millimeters, should be
	    set to zero if the default length is to remain unchanged.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>scale</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Scale factor to be applied to default to get actual tick
	    length.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plsmin(def, scale)</function>
    </para>

    <para>
      This function is used in example 29.
    </para>

  </sect1>

  <sect1 id="plsori" renderas="sect3">
    <title>
      <function>plsori</function>: Set orientation
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsori</function>
	  </funcdef>
	  <paramdef><parameter>ori</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set integer plot orientation parameter.  This function is
      identical to &plsdiori; except for the type of the argument, and
      should be used in the same way.  See <xref linkend="plsdiori"/> for
      details.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>ori</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Orientation value (0 for landscape, 1 for portrait, etc.)
	    The value is multiplied by 90 degrees to get the angle.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plsori(ori)</function>
    </para>

    <para>
      This function is used in example 3.
    </para>

  </sect1>

  <sect1 id="plspage" renderas="sect3">
    <title>
      <function>plspage</function>: Set page parameters
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plspage</function>
	  </funcdef>
	  <paramdef><parameter>xp</parameter></paramdef>
	  <paramdef><parameter>yp</parameter></paramdef>
	  <paramdef><parameter>xleng</parameter></paramdef>
	  <paramdef><parameter>yleng</parameter></paramdef>
	  <paramdef><parameter>xoff</parameter></paramdef>
	  <paramdef><parameter>yoff</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets the page configuration (optional).  If an individual parameter
      is zero then that parameter value is not updated.  Not all parameters are
      recognized by all drivers and the interpretation is device-dependent.
      The X-window driver uses the length and offset parameters to determine
      the window size and location.  The length and offset values are expressed
      in units that are specific to the current driver. For instance:
      screen drivers will usually interpret them as number of pixels,
      whereas printer drivers will usually use mm.
      This routine, if used, must be called
      before initializing PLplot.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>xp</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of pixels/inch (DPI), x.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>yp</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of pixels/inch (DPI), y.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xleng</parameter>
	  (<literal>PLINT </literal>, input)
	</term>
	<listitem>
	  <para>
	    Page length, x.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>yleng</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Page length, y.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xoff</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Page offset, x.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>yoff</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Page offset, y.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plspage(xp, yp, xleng, yleng, xoff, yoff)</function>
    </para>

    <para>
      This function is used in examples 14 and 31.
    </para>

  </sect1>

  <sect1 id="plspal0" renderas="sect3">
    <title>
      <function>plspal0</function>: Set the colors for color table 0
      from a cmap0 file
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plspal0</function>
	  </funcdef>
	  <paramdef><parameter>filename</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set the colors for color table 0 from a cmap0 file
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>filename</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    The name of the cmap0 file, or a empty to string to
	    specify the default cmap0 file.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plspal0(filename)</function>
    </para>

    <para>
      This function is in example 16.
    </para>

  </sect1>

  <sect1 id="plspal1" renderas="sect3">
    <title>
      <function>plspal1</function>: Set the palette for cmap1
      using the specified cmap1*.pal format file
    </title>
    
    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plspal1</function>
	  </funcdef>
	  <paramdef><parameter>filename</parameter></paramdef>
	  <paramdef><parameter>interpolate</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set the palette for cmap1 using the specified cmap1*.pal format file.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>filename</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    The name of the cmap1*.pal file, or an empty string to
	    specify the default cmap1.pal file.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>interpolate</parameter>
	  (<literal>PLBOOL</literal>, input)
	</term>
	<listitem>
	  <para>
	    If this parameter is true, the columns containing the
	    intensity index, r, g, b, alpha and
	    alt_hue_path in the cmap1*.pal file are used to set
	    the cmap1 palette with a call to &plscmap1la;.
	    (The cmap1*.pal header contains a flag which controls
	    whether the r, g, b data sent to &plscmap1la; are
	    interpreted as HLS or RGB.)
	  </para>
	  <para>
	    If this parameter is false, the intensity index and alt_hue_path columns
	    are ignored and the r, g, b (interpreted as RGB), and alpha columns of the
	    cmap1*.pal file are used instead to set the cmap1 palette directly
	    with a call to &plscmap1a;.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plspal1(filename, interpolate)</function>
    </para>

    <para>
      This function is used in example 16.
    </para>

  </sect1>

  <sect1 id="plspause" renderas="sect3">
    <title>
      <function>plspause</function>: Set the pause (on end-of-page) status
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plspause</function>
	  </funcdef>
	  <paramdef><parameter>pause</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set the pause (on end-of-page) status.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>pause</parameter>
	  (<literal>PLBOOL</literal>, input)
	</term>
	<listitem>
	  <para>
	    If <literal><parameter>pause</parameter></literal> is true there
	    will be a pause on end-of-page for those drivers which support
	    this.  Otherwise there is no pause.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plspause(pause)</function>
    </para>

    <para>
      This function is in examples 14,20.
    </para>

  </sect1>

  <sect1 id="plsstrm" renderas="sect3">
    <title>
      <function>plsstrm</function>: Set current output stream
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsstrm</function>
	  </funcdef>
	  <paramdef><parameter>strm</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets the number of the current output stream.  The stream number
      defaults to 0 unless changed by this routine.  The first use of this
      routine must be followed by a call initializing PLplot
      (e.g. &plstar;).
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>strm</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The current stream number.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plsstrm(strm)</function>
    </para>

    <para>
      This function is examples 1,14,20.
    </para>

  </sect1>

  <sect1 id="plssub" renderas="sect3">
    <title>
      <function>plssub</function>: Set the number of subpages in x and y
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plssub</function>
	  </funcdef>
	  <paramdef><parameter>nx</parameter></paramdef>
	  <paramdef><parameter>ny</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set the number of subpages in x and y.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>nx</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of windows in x direction (i.e., number of window columns).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ny</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of windows in y direction (i.e., number of window rows).
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plssub(nx, ny)</function>
    </para>

    <para>
      This function is examples 1,2,14,21,25,27.
    </para>

  </sect1>

  <sect1 id="plssym" renderas="sect3">
    <title>
      <function>plssym</function>: Set symbol size
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plssym</function>
	  </funcdef>
	  <paramdef><parameter>def</parameter></paramdef>
	  <paramdef><parameter>scale</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      This sets up the size of all subsequent symbols drawn by &plpoin; and
      &plsym;.  The actual height of a symbol is the product of the default
      symbol size and a scaling factor as for the character height.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>def</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The default height of a symbol in millimeters, should be set to
	    zero if the default height is to remain unchanged.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>scale</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Scale factor to be applied to default to get actual symbol
	    height.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plssym(def, scale)</function>
    </para>

    <para>
      This function is used in example 29.
    </para>

  </sect1>

  <sect1 id="plstar" renderas="sect3">
    <title>
      <function>plstar</function>: Initialization
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plstar</function>
	  </funcdef>
	  <paramdef><parameter>nx</parameter></paramdef>
	  <paramdef><parameter>ny</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Initializing the plotting package.  The program prompts for the
      device keyword or number of the desired output device.  Hitting a
      RETURN in response to the prompt is the same as selecting the first
      device.  If only one device is enabled when PLplot is installed,
      &plstar; will issue no prompt.  The output device is divided into
      <literal><parameter>nx</parameter></literal> by
      <literal><parameter>ny</parameter></literal> subpages, each of which
      may be used independently.  The subroutine &pladv; is used to advance
      from one subpage to the next.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>nx</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of subpages to divide output page in the horizontal
	    direction.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ny</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of subpages to divide output page in the vertical
	    direction.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plstar(nx, ny)</function>
    </para>

    <para>
      This function is used in example 1.
    </para>

  </sect1>

  <sect1 id="plstart" renderas="sect3">
    <title>
      <function>plstart</function>: Initialization
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plstart</function>
	  </funcdef>
	  <paramdef><parameter>devname</parameter></paramdef>
	  <paramdef><parameter>nx</parameter></paramdef>
	  <paramdef><parameter>ny</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Alternative to &plstar; for initializing the plotting package.  The
      device name keyword for the
      desired output device must be supplied as an argument.  These
      keywords are the same as those printed out by &plstar;.  If the
      requested device is not available, or if the input string is empty or
      begins with ``?'', the prompted start up of &plstar; is used.  This
      routine also divides the output device page into
      <literal><parameter>nx</parameter></literal> by
      <literal><parameter>ny</parameter></literal> subpages, each of which
      may be used independently.  The subroutine &pladv; is used to advance
      from one subpage to the next.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>devname</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Device name keyword of the required output device.  If NULL
	    or if the first character is a ``?'', the normal (prompted)
	    start up is used.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nx</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of subpages to divide output page in the horizontal
	    direction.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ny</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of subpages to divide output page in the vertical
	    direction.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plstart(devname, nx, ny)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: <function>plstart(nx, ny, devname)</function>
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is not used in any examples.
    </para>

  </sect1>

  <sect1 id="plstransform" renderas="sect3">
    <title>
      <function>plstransform</function>: Set a global coordinate transform
      function
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plstransform</function>
	  </funcdef>
	  <paramdef><parameter>coordinate_transform</parameter></paramdef>
	  <paramdef><parameter>coordinate_transform_data</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      This function can be used to define a coordinate transformation
      which affects all elements drawn within the current plot window.
      The <literal><parameter>coordinate_transform</parameter></literal>
      function is similar to that provided for the &plmap; and
      &plmeridians; functions.  The
      <literal><parameter>coordinate_transform_data</parameter></literal>
      parameter may be used to pass extra data to
      <literal><parameter>coordinate_transform</parameter></literal>.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>coordinate_transform</parameter>
          (<literal>void (*) (PLFLT, PLFLT, PLFLT *, PLFLT *, PLPointer)
          </literal>, input)
	</term>
	<listitem>
	  <para>
            Pointer to a function that defines a transformation from the
            input (x, y) coordinate to a new plot world coordinate. A NULL pointer 
            means that no transform is applied.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>coordinate_transform_data</parameter>
	  (<literal>PLPointer</literal>, input)
	</term>
	<listitem>
	  <para>
            Optional extra data for
            <parameter><literal>coordinate_transform</literal></parameter>.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plstransform(coordinate_transform, coordinate_transform_data)</function>
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in examples 19 and 22.
    </para>

  </sect1>

  <sect1 id="plstring" renderas="sect3">
    <title>
      <function>plstring</function>: Plot a glyph at the specified points
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plstring</function>
	  </funcdef>
	  <paramdef><parameter>n</parameter></paramdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>string</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Plot a glyph at the specified points. (Supersedes &plpoin; and
      &plsym; because many[!] more glyphs are accessible with &plstring;.)
      The glyph is specified with a PLplot user string.  Note that the user
      string is not actually limited to one glyph so it is possible (but not
      normally useful) to plot more than one glyph at the specified points
      with this function.  As with &plmtex; and &plptex;, the user string
      can contain FCI escapes to determine the font, UTF-8 code to determine
      the glyph or else PLplot escapes for Hershey or unicode text to
      determine the glyph.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>n</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of points in the
	    <literal><parameter>x</parameter></literal> and
	    <literal><parameter>y</parameter></literal> arrays.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to an array with X coordinates of points.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to an array with Y coordinates of points.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>string</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    PLplot user string corresponding to the glyph to be
	    plotted at each of the <literal><parameter>n</parameter></literal>
	    points.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plstring(x, y, string)</function>
    </para>

    <para>
      This function is used in examples 4, 21 and 26.
    </para>

  </sect1>

  <sect1 id="plstring3" renderas="sect3">
    <title>
      <function>plstring3</function>: Plot a glyph at the specified 3D points
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plstring3</function>
	  </funcdef>
	  <paramdef><parameter>n</parameter></paramdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>z</parameter></paramdef>
	  <paramdef><parameter>string</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Plot a glyph at the specified 3D points. (Supersedes &plpoin3; 
      because many[!] more glyphs are accessible with &plstring3;.)
      Set up the call to this function similar to what is done for &plline3;.
      The glyph is specified with a PLplot user string.  Note that the user
      string is not actually limited to one glyph so it is possible (but not
      normally useful) to plot more than one glyph at the specified points
      with this function.  As with &plmtex; and &plptex;, the user string
      can contain FCI escapes to determine the font, UTF-8 code to determine
      the glyph or else PLplot escapes for Hershey or unicode text to
      determine the glyph.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>n</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of points in the
	    <literal><parameter>x</parameter></literal>,
	    <literal><parameter>y</parameter></literal>, and
	    <literal><parameter>z</parameter></literal> arrays.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to an array with X coordinates of points.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to an array with Y coordinates of points.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>z</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to an array with Z coordinates of points.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>string</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    PLplot user string corresponding to the glyph to be
	    plotted at each of the <literal><parameter>n</parameter></literal>
	    points.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plstring3(x, y, z, string)</function>
    </para>

    <para>
      This function is used in example 18.
    </para>

  </sect1>

  <sect1 id="plstripa" renderas="sect3">
    <title>
      <function>plstripa</function>: Add a point to a strip chart
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plstripa</function>
	  </funcdef>
	  <paramdef><parameter>id</parameter></paramdef>
	  <paramdef><parameter>pen</parameter></paramdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Add a point to a given pen of a given strip chart.
      There is no need for all pens to have the same number of
      points or to be equally sampled in the x coordinate.
      Allocates memory and rescales as
      necessary.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>id</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Identification number of the strip chart (set up in &plstripc;).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>pen</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pen number (ranges from 0 to 3).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    X coordinate of point to plot.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Y coordinate of point to plot.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plstripa(id, pen, x, y)</function>
    </para>

    <para>
      This function is used in example 17.
    </para>

  </sect1>

  <sect1 id="plstripc" renderas="sect3">
    <title>
      <function>plstripc</function>: Create a 4-pen strip chart
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plstripc</function>
	  </funcdef>
	  <paramdef><parameter>id</parameter></paramdef>
	  <paramdef><parameter>xspec</parameter></paramdef>
	  <paramdef><parameter>yspec</parameter></paramdef>
	  <paramdef><parameter>xmin</parameter></paramdef>
	  <paramdef><parameter>xmax</parameter></paramdef>
	  <paramdef><parameter>xjump</parameter></paramdef>
	  <paramdef><parameter>ymin</parameter></paramdef>
	  <paramdef><parameter>ymax</parameter></paramdef>
	  <paramdef><parameter>xlpos</parameter></paramdef>
	  <paramdef><parameter>ylpos</parameter></paramdef>
	  <paramdef><parameter>y_ascl</parameter></paramdef>
	  <paramdef><parameter>acc</parameter></paramdef>
	  <paramdef><parameter>colbox</parameter></paramdef>
	  <paramdef><parameter>collab</parameter></paramdef>
	  <paramdef><parameter>colline</parameter></paramdef>
	  <paramdef><parameter>styline</parameter></paramdef>
	  <paramdef><parameter>legline[]</parameter></paramdef>
	  <paramdef><parameter>labx</parameter></paramdef>
	  <paramdef><parameter>laby</parameter></paramdef>
	  <paramdef><parameter>labtop</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Create a 4-pen strip chart, to be used afterwards by &plstripa;
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>id</parameter>
	  (<literal>PLINT *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Identification number of strip chart to use on &plstripa; and &plstripd;.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xspec</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    X-axis specification as in &plbox;.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>yspec</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Y-axis specification as in &plbox;.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xmin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Initial coordinates of plot box; they will change as data are
	    added.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xmax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Initial coordinates of plot box; they will change as data are
	    added.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xjump</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    When x attains <literal><parameter>xmax</parameter></literal>,
	    the length of the plot is multiplied by the
	    factor <literal>(1 + <parameter>xjump</parameter>)</literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Initial coordinates of plot box; they will change as data are
	    added.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Initial coordinates of plot box; they will change as data are
	    added.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xlpos</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    X legend box position (range from 0 to 1).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ylpos</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Y legend box position (range from 0 to 1).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y_ascl</parameter>
	  (<literal>PLBOOL</literal>, input)
	</term>
	<listitem>
	  <para>
	    Autoscale y between x jumps if
	    <literal><parameter>y_ascl</parameter></literal> is true,
	    otherwise not.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>acc</parameter>
	  (<literal>PLBOOL</literal>, input)
	</term>
	<listitem>
	  <para>
	    Accumulate strip plot if
	    <literal><parameter>acc</parameter></literal> is true,
	    otherwise slide display.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>colbox</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Plot box color index (cmap0).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>collab</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Legend color index (cmap0).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>colline</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with color indices (cmap0) for the 4 pens.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>styline</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with line styles for the 4 pens.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>legline</parameter>
	  (<literal>const char **</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to character array containing legends for the 4 pens.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>labx</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    X-axis label.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>laby</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Y-axis label.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>labtop</parameter>
	  (<literal>const char *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Plot title.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: 
      <itemizedlist>
	<listitem>
	  <para>
	    General: <function>plstripc(id, xspec, yspec, xmin, xmax, xjump, ymin, ymax, xlpos, ylpos, y_ascl, acc, colbox, collab, colline, styline, legline, labx, laby, labz)</function>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Perl/PDL: <function>plstripc(xmin, xmax, xjump, ymin, ymax, xlpos, ylpos, y_ascl, acc, colbox, collab, colline, styline, id, xspec, ypsec, legline, labx, laby, labtop)</function>
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>
      This function is used in example 17.
    </para>

  </sect1>

  <sect1 id="plstripd" renderas="sect3">
    <title>
      <function>plstripd</function>: Deletes and releases memory used by a
      strip chart
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plstripd</function>
	  </funcdef>
	  <paramdef><parameter>id</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Deletes and releases memory used by a strip chart.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>id</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Identification number of strip chart to delete.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plstripd(id)</function>
    </para>

    <para>
      This function is used in example 17.
    </para>

  </sect1>

  <sect1 id="plstyl" renderas="sect3">
    <title>
      <function>plstyl</function>: Set line style
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plstyl</function>
	  </funcdef>
	  <paramdef><parameter>nms</parameter></paramdef>
	  <paramdef><parameter>mark</parameter></paramdef>
	  <paramdef><parameter>space</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      This sets up the line style for all lines subsequently drawn.  A line
      consists of segments in which the pen is alternately down and up.
      The lengths of these segments are passed in the arrays
      <literal><parameter>mark</parameter></literal> and
      <literal><parameter>space</parameter></literal> respectively.  The
      number of mark-space pairs is specified by
      <literal><parameter>nms</parameter></literal>.  In order to return
      the line style to the default continuous line, &plstyl; should be
      called with <literal><parameter>nms</parameter>=0</literal>.(see
      also &pllsty;)
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>nms</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The number of <literal><parameter>mark</parameter></literal>
	    and <literal><parameter>space</parameter></literal> elements in
	    a line.  Thus a simple broken line can be obtained by setting
	    <literal><parameter>nms</parameter>=1</literal>.  A continuous
	    line is specified by setting
	    <literal><parameter>nms</parameter>=0</literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>mark</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with the lengths of the segments during which
	    the pen is down, measured in micrometers.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>space</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to array with the lengths of the segments during which
	    the pen is up, measured in micrometers.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plstyl(mark, space)</function>
    </para>

    <para>
      This function is used in examples 1,9,14.
    </para>

  </sect1>

  <sect1 id="plsurf3d" renderas="sect3">
    <title>
      <function>plsurf3d</function>: Plot shaded 3-d surface plot
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsurf3d</function>
	  </funcdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>z</parameter></paramdef>
	  <paramdef><parameter>nx</parameter></paramdef>
	  <paramdef><parameter>ny</parameter></paramdef>
	  <paramdef><parameter>opt</parameter></paramdef>
	  <paramdef><parameter>clevel</parameter></paramdef>
	  <paramdef><parameter>nlevel</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Plots a three dimensional shaded surface plot within the environment set up
      by &plw3d;.  The surface is defined by the two-dimensional array
      <literal><parameter>z</parameter>[<parameter>nx</parameter>][<parameter>ny</parameter>]</literal>,
      the point <literal><parameter>z</parameter>[i][j]</literal> being the
      value of the function at <literal>(<parameter>x</parameter>[i],
      <parameter>y</parameter>[j])</literal>.  Note that the points in
      arrays <literal><parameter>x</parameter></literal> and
      <literal><parameter>y</parameter></literal> do not need to be equally
      spaced, but must be stored in ascending order.
      For further details see <xref linkend="tri-d-plots"/>.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to set of x coordinate values at which the function is
	    evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to set of y coordinate values at which the function is
	    evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>z</parameter>
	  (<literal>const PLFLT * const *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to a vectored two-dimensional array with set of
	    function values.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nx</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of <literal><parameter>x</parameter></literal> values at
	    which function is evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ny</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of <literal><parameter>y</parameter></literal> values at
	    which function is evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>opt</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Determines the way in which the surface is represented. To specify
	    more than one option just add the options, e.g. FACETED + SURF_CONT
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=FACETED</literal>: Network
		  of lines is drawn connecting points at which function is
		  defined.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=BASE_CONT</literal>: A contour
		  plot is drawn at the base XY plane using parameters
		  <parameter>nlevel</parameter> and <parameter>clevel</parameter>.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=SURF_CONT</literal>: A contour
		  plot is drawn at the surface plane using parameters
		  <parameter>nlevel</parameter> and <parameter>clevel</parameter>.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=DRAW_SIDES</literal>: draws a curtain
		  between the base XY plane and the borders of the plotted function.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=MAG_COLOR</literal>:
		  the surface is colored according to the value of Z; if
		  <literal>MAG_COLOR</literal> is not used, then the default
		  the surface is colored according to the intensity of the
		  reflected light in the surface from a light source whose
		  position is set using &pllightsource;.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <parameter>clevel</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to the array that defines the contour level spacing.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nlevel</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of elements in the <literal>clevel</literal> array.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plsurf3d(x, y, z, opt, clevel)</function>
    </para>

    <para>
      This function is not used in any examples.
    </para>

  </sect1>

  <sect1 id="plsurf3dl" renderas="sect3">
    <title>
      <function>plsurf3dl</function>: Plot shaded 3-d surface plot for
      z[x][y] with y index limits
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsurf3dl</function>
	  </funcdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>z</parameter></paramdef>
	  <paramdef><parameter>nx</parameter></paramdef>
	  <paramdef><parameter>ny</parameter></paramdef>
	  <paramdef><parameter>opt</parameter></paramdef>
	  <paramdef><parameter>clevel</parameter></paramdef>
	  <paramdef><parameter>nlevel</parameter></paramdef>
          <paramdef><parameter>indexxmin</parameter></paramdef>
	  <paramdef><parameter>indexxmax</parameter></paramdef>
	  <paramdef><parameter>indexymin</parameter></paramdef>
	  <paramdef><parameter>indexymax</parameter></paramdef>
	  </funcprototype>
      </funcsynopsis>
    </para>

    <para>

    This variant of &plsurf3d; (see that function's documentation for
    more details) should be suitable for the case where the area of
    the <literal><parameter>x</parameter></literal>,
    <literal><parameter>y</parameter></literal> coordinate grid where
    <literal><parameter>z</parameter></literal> is defined can be
    non-rectangular.  The limits of that grid are provided by
    the parameters <literal><parameter>indexxmin</parameter></literal>,
    <literal><parameter>indexxmax</parameter></literal>,
    <literal><parameter>indexymin</parameter></literal>,
    and <literal><parameter>indexymax</parameter></literal>.

    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to set of x coordinate values at which the function is
	    evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to set of y coordinate values at which the function is
	    evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>z</parameter>
	  (<literal>const PLFLT * const *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to a vectored two-dimensional array with set of
	    function values.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nx</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of <literal><parameter>x</parameter></literal> values at
	    which function is evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ny</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of <literal><parameter>y</parameter></literal> values at
	    which function is evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>opt</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Determines the way in which the surface is represented. To specify
	    more than one option just add the options, e.g. FACETED + SURF_CONT
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=FACETED</literal>: Network
		  of lines is drawn connecting points at which function is
		  defined.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=BASE_CONT</literal>: A contour
		  plot is drawn at the base XY plane using parameters
		  <parameter>nlevel</parameter> and <parameter>clevel</parameter>.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=SURF_CONT</literal>: A contour
		  plot is drawn at the surface plane using parameters
		  <parameter>nlevel</parameter> and <parameter>clevel</parameter>.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=DRAW_SIDES</literal>: draws a curtain
		  between the base XY plane and the borders of the plotted function.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=MAG_COLOR</literal>:
		  the surface is colored according to the value of Z; if
		  <literal>MAG_COLOR</literal> is not used, then the default
		  the surface is colored according to the intensity of the
		  reflected light in the surface from a light source whose
		  position is set using &pllightsource;.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>clevel</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to the array that defines the contour level spacing.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nlevel</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of elements in the <literal>clevel</literal> array.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>indexxmin</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The index value (which must be ≥ 0) that corresponds to
	    the first <literal><parameter>x</parameter></literal> index where
	    <literal><parameter>z</parameter></literal> is defined.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>indexxmax</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The index value (which must be ≤
	    <literal><parameter>nx</parameter></literal>) which corresponds (by
	    convention) to one more than the last
	    <literal><parameter>x</parameter></literal> index value where
	    <literal><parameter>z</parameter></literal> is defined.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>indexymin</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Array of <literal><parameter>y</parameter></literal> index
	    values which all must be ≥ 0.  These values are the first
	    <literal><parameter>y</parameter></literal> index where
	    <literal><parameter>z</parameter></literal> is defined for a
	    particular <literal><parameter>x</parameter></literal> index in the
	    range from <literal><parameter>indexxmin</parameter></literal> to
	    <literal><parameter>indexxmax - 1</parameter></literal>.  The dimension of
	    <literal><parameter>indexymin</parameter></literal> is
	    <literal><parameter>indexxmax</parameter></literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>indexymax</parameter>
	  (<literal>const PLINT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Array of <literal><parameter>y</parameter></literal> index
	    values which all must be ≤
	    <literal><parameter>ny</parameter></literal>.  These values
	    correspond (by convention) to one more than the last
	    <literal><parameter>y</parameter></literal> index where
	    <literal><parameter>z</parameter></literal> is defined for a
	    particular <literal><parameter>x</parameter></literal> index in the
	    range from <literal><parameter>indexxmin</parameter></literal> to
	    <literal><parameter>indexxmax - 1</parameter></literal>.  The dimension of
	    <literal><parameter>indexymax</parameter></literal> is
	    <literal><parameter>indexxmax</parameter></literal>.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plsurf3dl(x, y, z, opt, clevel,
      indexxmin, indexymin, indexymax)</function>
    </para>

    <para>
      This function is not used in any examples.
    </para>

  </sect1>

  <sect1 id="plfsurf3d" renderas="sect3">
    <title>
      <function>plfsurf3d</function>: Plot shaded 3-d surface plot
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plfsurf3d</function>
	  </funcdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>zops</parameter></paramdef>
	  <paramdef><parameter>zp</parameter></paramdef>
	  <paramdef><parameter>nx</parameter></paramdef>
	  <paramdef><parameter>ny</parameter></paramdef>
	  <paramdef><parameter>opt</parameter></paramdef>
	  <paramdef><parameter>clevel</parameter></paramdef>
	  <paramdef><parameter>nlevel</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Plots a three dimensional shaded surface plot within the environment set up
      by &plw3d;. The surface is defined by the data contained in the 2D 
      <literal>const PLFLT * const *</literal> matrix or the <literal>PLfGrid2</literal> structure
      <literal><parameter>zp</parameter></literal>. How the data in 
      <literal><parameter>zp</parameter></literal> is rendered is determined by the 
      <literal><parameter>zops</parameter></literal> parameter.
      <literal><parameter>zops</parameter></literal> is a pointer to a function
      that reads the data out of the grid structure. The following functions in
      PLplot core will return an appropriate function pointer: 
      <literal>plf2ops_c()</literal> (use when 
      <literal><parameter>zp</parameter></literal> is of type 
      <literal>const PLFLT * const *</literal>),
      <literal>plf2ops_grid_c()</literal> (use when 
      <literal><parameter>zp</parameter></literal> 
      is a pointer to a row-major <literal>PLfGrid2</literal> structure), 
      <literal>plf2ops_grid_row_major()</literal> 
      (same as <literal>plf2ops_grid_c()</literal>?) and 
      <literal>plf2ops_grid_col_major()</literal> 
      (use when <literal><parameter>zp</parameter></literal> is a pointer to a 
      column-major <literal>PLfGrid2</literal> structure). 
      <literal><parameter>nx</parameter></literal>,
      <literal><parameter>ny</parameter></literal>
      <literal><parameter>opt</parameter></literal>
      <literal><parameter>clevel</parameter></literal> and
      <literal><parameter>nlevel</parameter></literal> are the same as in
      for example &plsurf3d;.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to set of x coordinate values at which the function is
	    evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to set of y coordinate values at which the function is
	    evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>zops</parameter>
	  (<literal>PLF2OPS</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to a function for processing the data contained in zp.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>zp</parameter>
	  (<literal>PLPointer</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to the data to be plotted, either as a vectored 
	    two-dimensional array with set of function values or as
	    a PLfGrid2 structure.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nx</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of <literal><parameter>x</parameter></literal> values at
	    which function is evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ny</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of <literal><parameter>y</parameter></literal> values at
	    which function is evaluated.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>opt</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Determines the way in which the surface is represented. To specify
	    more than one option just add the options, e.g. FACETED + SURF_CONT
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=FACETED</literal>: Network
		  of lines is drawn connecting points at which function is
		  defined.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=BASE_CONT</literal>: A contour
		  plot is drawn at the base XY plane using parameters
		  <parameter>nlevel</parameter> and <parameter>clevel</parameter>.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=SURF_CONT</literal>: A contour
		  plot is drawn at the surface plane using parameters
		  <parameter>nlevel</parameter> and <parameter>clevel</parameter>.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=DRAW_SIDES</literal>: draws a curtain
		  between the base XY plane and the borders of the plotted function.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal><parameter>opt</parameter>=MAG_COLOR</literal>:
		  the surface is colored according to the value of Z; if
		  <literal>MAG_COLOR</literal> is not used, then the default
		  the surface is colored according to the intensity of the
		  reflected light in the surface from a light source whose
		  position is set using &pllightsource;.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <parameter>clevel</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to the array that defines the contour level spacing.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nlevel</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of elements in the <literal>clevel</literal> array.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form? <function>plfsurf3d(x, y, zops, zp, opt, clevel)</function>
    </para>

    <para>
      This function is used in example 8.
    </para>

  </sect1>

  <sect1 id="plsvect" renderas="sect3">
    <title>
      <function>plsvect</function>: Set arrow style for vector plots
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsvect</function>
	  </funcdef>
	  <paramdef><parameter>arrowx</parameter></paramdef>
	  <paramdef><parameter>arrowy</parameter></paramdef>
	  <paramdef><parameter>npts</parameter></paramdef>
	  <paramdef><parameter>fill</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Set the style for the arrow used by &plvect; to plot vectors.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>arrowx, arrowy</parameter>
	  (<literal>const PLFLT *</literal>,input)
	</term>
	<listitem>
	  <para>
	    Pointers to a pair of arrays containing the x and y points
	    which make up the arrow. The arrow is plotted by joining these
	    points to form a polygon. The scaling assumes that the x and y
	    points in the arrow lie in the range
	    <literal>-0.5 &lt;= x,y &lt;= 0.5</literal>. If both 
            <literal><parameter>arrowx</parameter></literal> and
            <literal><parameter>arrowy</parameter></literal> are NULL then
            the arrow style will be reset to its default.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>npts</parameter>
	  (<literal>PLINT</literal>,input)
	</term>
	<listitem>
	  <para>
	    Number of points in the arrays
	    <literal><parameter>arrowx</parameter></literal> and
	    <literal><parameter>arrowy</parameter></literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>fill</parameter>
	  (<literal>PLBOOL</literal>,input)
	</term>
	<listitem>
	  <para>
	    If <literal><parameter>fill</parameter></literal> is true then the
	    arrow is closed, if <literal><parameter>fill</parameter></literal>
	    is false then the arrow is open.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plsvect(arrowx, arrowy, fill)</function>
    </para>

    <para>
      This function is used in example 22.
    </para>

  </sect1>

  <sect1 id="plsvpa" renderas="sect3">
    <title>
      <function>plsvpa</function>: Specify viewport in absolute coordinates
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsvpa</function>
	  </funcdef>
	  <paramdef><parameter>xmin</parameter></paramdef>
	  <paramdef><parameter>xmax</parameter></paramdef>
	  <paramdef><parameter>ymin</parameter></paramdef>
	  <paramdef><parameter>ymax</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Alternate routine to &plvpor; for setting up the viewport.  This
      routine should be used only if the viewport is required to have a
      definite size in millimeters.  The routine &plgspa; is useful for
      finding out the size of the current subpage.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>xmin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The distance of the left-hand edge of the viewport from the
	    left-hand edge of the subpage in millimeters.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xmax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The distance of the right-hand edge of the viewport from the
	    left-hand edge of the subpage in millimeters.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The distance of the bottom edge of the viewport from the bottom
	    edge of the subpage in millimeters.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The distance of the top edge of the viewport from the bottom edge
	    of the subpage in millimeters.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plsvpa(xmin, xmax, ymin, ymax)</function>
    </para>

    <para>
      This function is used in example 10.
    </para>

  </sect1>

  <sect1 id="plsxax" renderas="sect3">
    <title>
      <function>plsxax</function>: Set x axis parameters
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsxax</function>
	  </funcdef>
	  <paramdef><parameter>digmax</parameter></paramdef>
	  <paramdef><parameter>digits</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets values of the
      <literal><parameter>digmax</parameter></literal> and
      <literal><parameter>digits</parameter></literal> flags for the x
      axis.  See <xref linkend="annotation"/> for more information.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>digmax</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Variable to set the maximum number of digits for the x axis.  If nonzero, the
	    printed label will be switched to a floating point
	    representation when the number of digits exceeds
	    <literal><parameter>digmax</parameter></literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>digits</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Field digits value.  Currently, changing its value here has no
	    effect since it is set only by &plbox; or &plbox3;.  However,
	    the user may obtain its value after a call to either of these functions by
	    calling &plgxax;.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plsxax(digmax, digits)</function>
    </para>

    <para>
      This function is used in example 31.
    </para>

  </sect1>

  <sect1 id="plsyax" renderas="sect3">
    <title>
      <function>plsyax</function>: Set y axis parameters
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsyax</function>
	  </funcdef>
	  <paramdef><parameter>digmax</parameter></paramdef>
	  <paramdef><parameter>digits</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Identical to &plsxax;, except that arguments are flags for y axis.
      See the description of &plsxax; for more detail.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>digmax</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Variable to set the maximum number of digits for the y axis.  If nonzero, the
	    printed label will be switched to a floating point
	    representation when the number of digits exceeds
	    <literal><parameter>digmax</parameter></literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>digits</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Field digits value.  Currently, changing its value here has no
	    effect since it is set only by &plbox; or &plbox3;.  However,
	    the user may obtain its value after a call to either of these functions by
	    calling &plgyax;.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plsyax(digmax, digits)</function>
    </para>

    <para>
      This function is used in examples 1,14,31.
    </para>

  </sect1>

  <sect1 id="plsym" renderas="sect3">
    <title>
      <function>plsym</function>: Plot a glyph at the specified points
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plsym</function>
	  </funcdef>
	  <paramdef><parameter>n</parameter></paramdef>
	  <paramdef><parameter>x</parameter></paramdef>
	  <paramdef><parameter>y</parameter></paramdef>
	  <paramdef><parameter>code</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Plot a glyph at the specified points.  (This function is
      largely superseded by &plstring; which gives access to many[!] 
      more glyphs.)
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>n</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Number of points in the
	    <literal><parameter>x</parameter></literal> and
	    <literal><parameter>y</parameter></literal> arrays.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>x</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to an array with X coordinates of points.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>y</parameter>
	  (<literal>const PLFLT *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to an array with Y coordinates of points.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>code</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Hershey symbol code corresponding to a glyph to be plotted
	    at each of the <literal><parameter>n</parameter></literal> points.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plsym(x, y, code)</function>
    </para>

    <para>
      This function is used in example 7.
    </para>

  </sect1>

  <sect1 id="plszax" renderas="sect3">
    <title>
      <function>plszax</function>: Set z axis parameters
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plszax</function>
	  </funcdef>
	  <paramdef><parameter>digmax</parameter></paramdef>
	  <paramdef><parameter>digits</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Identical to &plsxax;, except that arguments are flags for z axis.
      See the description of &plsxax; for more detail.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>digmax</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Variable to set the maximum number of digits for the z axis.  If nonzero, the
	    printed label will be switched to a floating point
	    representation when the number of digits exceeds
	    <literal><parameter>digmax</parameter></literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>digits</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Field digits value.  Currently, changing its value here has no
	    effect since it is set only by &plbox; or &plbox3;.  However,
	    the user may obtain its value after a call to either of these functions by
	    calling &plgzax;.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plszax(digmax, digits)</function>
    </para>

    <para>
      This function is used in example 31.
    </para>

  </sect1>

  <sect1 id="pltext" renderas="sect3">
    <title>
      <function>pltext</function>: Switch to text screen
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>pltext</function>
	  </funcdef>
	  <paramdef></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets an interactive device to text mode, used in conjunction with
      &plgra; to allow graphics and text to be interspersed.  On a device
      which supports separate text and graphics windows, this command
      causes control to be switched to the text window.  This can be useful
      for printing diagnostic messages or getting user input, which would
      otherwise interfere with the plots.  The program
      <emphasis>must</emphasis> switch back to the graphics window before
      issuing plot commands, as the text (or console) device will probably
      become quite confused otherwise.  If already in text mode, this
      command is ignored.  It is also ignored on devices which only support
      a single window or use a different method for shifting focus (see
      also &plgra;).
    </para>

    <para>
      Redacted form: <function>pltext()</function>
    </para>

    <para>
      This function is used in example 1.
    </para>

  </sect1>

  <sect1 id="pltimefmt" renderas="sect3">
    <title>
      <function>pltimefmt</function>: Set format for date / time labels
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>pltimefmt</function>
	  </funcdef>
	  <paramdef><parameter>fmt</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets the format for date / time labels. To enable date / time
      format labels see the options to &plbox; and &plenv;. 
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>fmt</parameter>
	  (<literal>const char *</literal>, fmt)
	</term>
	<listitem>
	  <para>
	    This string is passed directly to the system strftime. See
	    the system documentation for a full list of conversion
	    specifications for your system. All conversion
	    specifications take the form of a '%' character followed by
	    further conversion specification character. All other text
	    is printed as-is. Common options include:
	    <itemizedlist>
	      <listitem>
		<para>
		  <literal>%c</literal>: The preferred date and time
		  representation for the current locale. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>%d</literal>: The day of the month as a
		  decimal number. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>%H</literal>: The hour as a decimal number
		  using a 24-hour clock. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>%j</literal>: The day of the year as a
		  decimal number. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>%m</literal>: The month as a decimal number. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>%M</literal>: The minute as a decimal number. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>%S</literal>: The second as a decimal number. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>%y</literal>: The year as a decimal number
		  without a century. 
		</para>
	      </listitem>
	      <listitem>
		<para>
		  <literal>%Y</literal>: The year  as a decimal number
		  including a century. 
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>pltimefmt(fmt)</function>
    </para>

    <para>
      This function is used in example 29.
    </para>

  </sect1>

  <sect1 id="plvasp" renderas="sect3">
    <title>
      <function>plvasp</function>: Specify viewport using aspect ratio only
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plvasp</function>
	  </funcdef>
	  <paramdef><parameter>aspect</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets the viewport so that the ratio of the length of the y axis to
      that of the x axis is equal to
      <literal><parameter>aspect</parameter></literal>.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>aspect</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Ratio of length of y axis to length of x axis.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plvasp(aspect)</function>
    </para>

    <para>
      This function is used in example 13.
    </para>

  </sect1>

  <sect1 id="plvect" renderas="sect3">
    <title>
      <function>plvect</function>: Vector plot
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plvect</function>
	  </funcdef>
	  <paramdef><parameter>u</parameter></paramdef>
	  <paramdef><parameter>v</parameter></paramdef>
	  <paramdef><parameter>nx</parameter></paramdef>
	  <paramdef><parameter>ny</parameter></paramdef>
	  <paramdef><parameter>scale</parameter></paramdef>
	  <paramdef><parameter>pltr</parameter></paramdef>
	  <paramdef><parameter>pltr_data</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Draws a vector plot of the vector
      <literal>(<parameter>u</parameter>[<parameter>nx</parameter>][<parameter>ny</parameter>],<parameter>v</parameter>[<parameter>nx</parameter>][<parameter>ny</parameter>])</literal>.
      The scaling factor for the vectors is given by
      <literal><parameter>scale</parameter></literal>. A
      transformation routine pointed to by <literal><parameter>pltr</parameter></literal>
      with a pointer <literal><parameter>pltr_data</parameter></literal>
      for additional data required by the transformation routine
      is used to map indices within the array
      to the world coordinates. The style of the vector arrow may be set using
      &plsvect;.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>u, v</parameter>
	  (<literal>const PLFLT * const *</literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointers to a pair of vectored two-dimensional arrays
	    containing the x and y components of the vector data to be
	    plotted.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>nx, ny</parameter>
	  (<literal>PLINT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Physical dimensions of the arrays
	    <literal><parameter>u</parameter></literal> and
	    <literal><parameter>v</parameter></literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>scale</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Parameter to control the scaling factor of the vectors for plotting.
	    If <literal><parameter>scale</parameter> = 0</literal> then
	    the scaling factor is automatically calculated for the data.
	    If <literal><parameter>scale</parameter> &lt; 0</literal> then
	    the scaling factor is automatically calculated for the data and
	    then multiplied by <literal>-<parameter>scale</parameter></literal>.
	    If <literal><parameter>scale</parameter> &gt; 0</literal> then
	    the scaling factor is set to <literal><parameter>scale</parameter></literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>pltr</parameter>
	  (<literal>void (*) (PLFLT, PLFLT, PLFLT *, PLFLT *, PLPointer)
	  </literal>, input)
	</term>
	<listitem>
	  <para>
	    Pointer to function that defines transformation between indices
	    in array <literal><parameter>z</parameter></literal> and the
	    world coordinates (C only).  Transformation functions are
	    provided in the PLplot library:
	    &pltr0; for identity mapping, and &pltr1; and &pltr2; for
	    arbitrary mappings respectively defined by one- and
	    two-dimensional arrays.  In addition, user-supplied routines
	    for the transformation can be used as well.  Examples of
	    all of these approaches are given in
	    <xref linkend="contour-plots-c"/>.
	    The transformation function should
	    have the form given by any of &pltr0;, &pltr1;, or &pltr2;.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>pltr_data</parameter>
	  (<literal>PLPointer</literal>, input)
	</term>
	<listitem>
	  <para>
	    Extra parameter to help
	    pass information to &pltr0;, &pltr1;, &pltr2;, or whatever routine
	    that is externally supplied.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plvect(u, v, scale, pltr, pltr_data)</function>
    </para>

    <para>
      This function is used in example 22.
    </para>

  </sect1>

  <sect1 id="plvpas" renderas="sect3">
    <title>
      <function>plvpas</function>: Specify viewport using coordinates and aspect ratio
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plvpas</function>
	  </funcdef>
	  <paramdef><parameter>xmin</parameter></paramdef>
	  <paramdef><parameter>xmax</parameter></paramdef>
	  <paramdef><parameter>ymin</parameter></paramdef>
	  <paramdef><parameter>ymax</parameter></paramdef>
	  <paramdef><parameter>aspect</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Device-independent routine for setting up the viewport.  The viewport
      is chosen to be the largest with the given aspect ratio that fits
      within the specified region (in terms of normalized subpage
      coordinates).  This routine is functionally equivalent to &plvpor;
      when a ``natural'' aspect ratio (0.0) is chosen.  Unlike &plvasp;,
      this routine reserves no extra space at the edges for labels.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>xmin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The normalized subpage coordinate of the left-hand edge of the
	    viewport.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xmax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The normalized subpage coordinate of the right-hand edge of the
	    viewport.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The normalized subpage coordinate of the bottom edge of the
	    viewport.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The normalized subpage coordinate of the top edge of the
	    viewport.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>aspect</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    Ratio of length of y axis to length of x axis.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plvpas(xmin, xmax, ymin, ymax, aspect)</function>
    </para>

    <para>
      This function is used in example 9.
    </para>

  </sect1>

  <sect1 id="plvpor" renderas="sect3">
    <title>
      <function>plvpor</function>: Specify viewport using coordinates
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plvpor</function>
	  </funcdef>
	  <paramdef><parameter>xmin</parameter></paramdef>
	  <paramdef><parameter>xmax</parameter></paramdef>
	  <paramdef><parameter>ymin</parameter></paramdef>
	  <paramdef><parameter>ymax</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Device-independent routine for setting up the viewport.  This defines
      the viewport in terms of normalized subpage coordinates which run
      from 0.0 to 1.0 (left to right and bottom to top) along each edge of
      the current subpage.  Use the alternate routine &plsvpa; in order to
      create a viewport of a definite size.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>xmin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The normalized subpage coordinate of the left-hand edge of the
	    viewport.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xmax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The normalized subpage coordinate of the right-hand edge of the
	    viewport.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The normalized subpage coordinate of the bottom edge of the
	    viewport.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The normalized subpage coordinate of the top edge of the
	    viewport.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plvpor(xmin, xmax, ymin, ymax)</function>
    </para>

    <para>
      This function is used in examples 2,6-8,10,11,15,16,18,21,23,24,26,27,31.
    </para>

  </sect1>

  <sect1 id="plvsta" renderas="sect3">
    <title>
      <function>plvsta</function>: Select standard viewport
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plvsta</function>
	  </funcdef>
	  <paramdef></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets up a standard viewport, leaving a left-hand margin of seven
      character heights, and four character heights around the other three
      sides.
    </para>

    <para>
      Redacted form: <function>plvsta()</function>
    </para>

    <para>
      This function is used in examples 1,12,14,17,25,29.
    </para>

  </sect1>

  <sect1 id="plw3d" renderas="sect3">
    <title>
      <function>plw3d</function>: Set up window for 3-d plotting
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plw3d</function>
	  </funcdef>
	  <paramdef><parameter>basex</parameter></paramdef>
	  <paramdef><parameter>basey</parameter></paramdef>
	  <paramdef><parameter>height</parameter></paramdef>
	  <paramdef><parameter>xmin</parameter></paramdef>
	  <paramdef><parameter>xmax</parameter></paramdef>
	  <paramdef><parameter>ymin</parameter></paramdef>
	  <paramdef><parameter>ymax</parameter></paramdef>
	  <paramdef><parameter>zmin</parameter></paramdef>
	  <paramdef><parameter>zmax</parameter></paramdef>
	  <paramdef><parameter>alt</parameter></paramdef>
	  <paramdef><parameter>az</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets up a window for a three-dimensional surface plot within the
      currently defined two-dimensional window.  The enclosing box for the
      surface plot defined by
      <literal><parameter>xmin</parameter></literal>,
      <literal><parameter>xmax</parameter></literal>,
      <literal><parameter>ymin</parameter></literal>,
      <literal><parameter>ymax</parameter></literal>,
      <literal><parameter>zmin</parameter></literal> and
      <literal><parameter>zmax</parameter></literal> in user-coordinate
      space is mapped into a box of world coordinate size
      <literal><parameter>basex</parameter></literal> by
      <literal><parameter>basey</parameter></literal> by
      <literal><parameter>height</parameter></literal> so that
      <literal><parameter>xmin</parameter></literal> maps to
      <literal>-<parameter>basex</parameter>/2</literal>,
      <literal><parameter>xmax</parameter></literal> maps to
      <literal><parameter>basex</parameter>/2</literal>,
      <literal><parameter>ymin</parameter></literal> maps to
      <literal>-<parameter>basey</parameter>/2</literal>,
      <literal><parameter>ymax</parameter></literal> maps to
      <literal><parameter>basey</parameter>/2</literal>,
      <literal><parameter>zmin</parameter></literal> maps to
      <literal>0</literal> and
      <literal><parameter>zmax</parameter></literal> maps to
      <literal><parameter>height</parameter></literal>.  The resulting
      world-coordinate box is then viewed by an observer at altitude
      <literal><parameter>alt</parameter></literal> and azimuth
      <literal><parameter>az</parameter></literal>.  This routine must be
      called before &plbox3; or &plot3d;.  For a more complete description
      of three-dimensional plotting see <xref linkend="tri-d-plots"/>.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>basex</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The x coordinate size of the world-coordinate box.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>basey</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The y coordinate size of the world-coordinate box.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>height</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The z coordinate size of the world-coordinate box.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xmin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The minimum user x coordinate value.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xmax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The maximum user x coordinate value.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The minimum user y coordinate value.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The maximum user y coordinate value.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>zmin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The minimum user z coordinate value.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>zmax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The maximum user z coordinate value.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>alt</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The viewing altitude in degrees above the XY plane.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>az</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The viewing azimuth in degrees.  When
	    <literal><parameter>az</parameter>=0</literal>, the observer is
	    looking face onto the ZX plane, and as
	    <literal><parameter>az</parameter></literal> is increased, the
	    observer moves clockwise around the box when viewed from above
	    the XY plane.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plw3d(basex, basey, height, xmin, xmax, ymin, ymax, zmin, zmax, alt, az)</function>
    </para>

    <para>
      This function is examples 8,11,18,21.
    </para>

  </sect1>

  <sect1 id="plwidth" renderas="sect3">
    <title>
      <function>plwidth</function>: Set pen width
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plwidth</function>
	  </funcdef>
	  <paramdef><parameter>width</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets the pen width.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>width</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The desired pen width.  If <literal><parameter>width</parameter></literal>
	    is negative or the same as the previous value no action is taken.
	    <literal><parameter>width</parameter> = 0.</literal> should be interpreted as
	    as the minimum valid pen width for the device.  The interpretation of positive
	    <literal><parameter>width</parameter></literal> values is also device
	    dependent.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plwidth(width)</function>
    </para>

    <para>
      This function is used in examples 1,2.
    </para>

  </sect1>

  <sect1 id="plwind" renderas="sect3">
    <title>
      <function>plwind</function>: Specify world coordinates of viewport boundaries
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plwind</function>
	  </funcdef>
	  <paramdef><parameter>xmin</parameter></paramdef>
	  <paramdef><parameter>xmax</parameter></paramdef>
	  <paramdef><parameter>ymin</parameter></paramdef>
	  <paramdef><parameter>ymax</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Sets up the world coordinates of the edges of the viewport.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>xmin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The world x coordinate of the left-hand edge of the viewport.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>xmax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The world x coordinate of the right-hand edge of the viewport.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymin</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The world y coordinate of the bottom edge of the viewport.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>ymax</parameter>
	  (<literal>PLFLT</literal>, input)
	</term>
	<listitem>
	  <para>
	    The world y coordinate of the top edge of the viewport.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plwind(xmin, xmax, ymin, ymax)</function>
    </para>

    <para>
      This function is used in examples 1,2,4,6-12,14-16,18,21,23-27,29,31.
    </para>

  </sect1>
  <sect1 id="plxormod" renderas="sect3">
    <title>
      <function>plxormod</function>: Enter or leave xor mode
    </title>

    <para>
      <funcsynopsis>
	<funcprototype>
	  <funcdef>
	    <function>plxormod</function>
	  </funcdef>
	  <paramdef><parameter>mode</parameter></paramdef>
	  <paramdef><parameter>status</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </para>

    <para>
      Enter (when <literal><parameter>mode</parameter></literal> is true) 
      or leave (when <literal><parameter>mode</parameter></literal> is false)
      xor mode for those drivers
      (e.g., the xwin driver) that support it.  Enables erasing plots by
      drawing twice the same line, symbol, etc.  If driver is not capable
      of xor operation it returns a
      <literal><parameter>status</parameter></literal> of false.
    </para>

    <variablelist>
      <varlistentry>
	<term>
	  <parameter>mode</parameter>
	  (<literal>PLBOOL</literal>, input)
	</term>
	<listitem>
	  <para>
	    <literal><parameter>mode</parameter></literal> is true
	    means enter xor mode and 
	    <literal><parameter>mode</parameter></literal> is false
	    means leave xor mode.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <parameter>status</parameter>
	  (<literal>PLBOOL *</literal>, output)
	</term>
	<listitem>
	  <para>
	    Pointer to status. Returned 
	    <literal><parameter>mode</parameter></literal>status of true (false)
	    means driver is capable (incapable) of xor mode.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      Redacted form: <function>plxormod(mode, status)</function>
    </para>

    <para>
      This function is used in examples 1,20.
    </para>

  </sect1>
</chapter>
