<!-- -*-  mode: nxml -*- -->
<!--
    advanced.xml: "Advanced Use of PLplot" chapter

Copyright (C) 1994  Geoffrey Furnish and Maurice LeBrun
Copyright (C) 1999-2013 Alan W. Irwin
Copyright (C) 1999, 2000, 2001, 2002, 2003 Rafael Laboissiere
Copyright (C) 2004 Andrew Roach
Copyright (C) 2005 Thomas J. Duck

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="advanced">
  <title>Advanced Use of PLplot</title>
  
  <para> In this chapter, we describe advanced use of PLplot. </para>
  
  <sect1 id="arguments">
    <title>Command Line Arguments</title>

    <para>
      PLplot supports a large number of command line arguments, but it is
      up to the user to pass these to PLplot for processing at the
      beginning of execution.
      &plparseopts; is responsible for parsing
      the argument list, removing all that are recognized by PLplot, and
      taking the appropriate action before returning.  There are an
      extensive number of options available to affect this process.  The
      command line arguments recognized by PLplot are given by the -h
      option:
    </para>
    
    <para>
      <screen>
	<prompt>%</prompt> <userinput>x01c -h</userinput>
	Usage:
	./x01c [options]

	PLplot options:
	-h                   Print out this message
	-v                   Print out the PLplot library version number
	-verbose             Be more verbose than usual
	-debug               Print debugging info (implies -verbose)
	-dev name            Output device name
	-o name              Output filename
	-display name        X server to contact
	-px number           Plots per page in x
	-py number           Plots per page in y
	-geometry geom       Window size, in pixels (e.g. -geometry 400x300)
	-wplt xl,yl,xr,yr    Relative coordinates [0-1] of window into plot
	-mar margin          Margin space in relative coordinates (0 to 0.5, def 0)
	-a aspect            Page aspect ratio (def: same as output device)
	-jx justx            Page justification in x (-0.5 to 0.5, def 0)
	-jy justy            Page justification in y (-0.5 to 0.5, def 0)
	-ori orient          Plot orientation (0,2=landscape, 1,3=portrait)
	-freeaspect          Do not preserve aspect ratio on orientation swaps
	-portrait            Sets portrait mode (both orientation and aspect ratio)
	-width width         Sets pen width (1 &lt;= width &lt;= 10)
	-bg color            Background color (0=black, FFFFFF=white)
	-ncol0 n             Number of colors to allocate in cmap 0 (upper bound)
	-ncol1 n             Number of colors to allocate in cmap 1 (upper bound)
	-fam                 Create a family of output files
	-fsiz size[kKmMgG]   Output family file size in MB (e.g. -fsiz 0.5G, def MB)
	-fbeg number         First family member number on output
	-finc number         Increment between family members
	-fflen length        Family member number minimum field width
	-nopixmap            Don't use pixmaps in X-based drivers
	-db                  Double buffer X window output
	-np                  No pause between pages
	-server_name name    Main window name of PLplot server (tk driver)
	-dpi dpi             Resolution, in dots per inch (e.g. -dpi 360x360)
	-compression num     Sets compression level in supporting devices
	-drvopt option[=value][,option[=value]]* Driver specific options
	-cmap0 name          Sets PLplot color table 0 using the file name
	-cmap1 name          Sets PLplot color table 1 using the file name
      </screen>
    </para>

    <para>
      The command-line options can also be set using the &plsetopt; function, if invoked before &plinit;.
    </para>

    <para>
      Some options are may not be recognized by individual drivers.  If an option is not recognized but should be, please contact the driver author via the plplot mailing lists.
    </para>

    <para>Many drivers have specific options that can be set using the -drvopt command line option or with &plsetopt;.  These options are documented in <xref linkend="x-drivers"/> and <xref linkend="output-drivers"/>.
    </para>

  </sect1>
  
  <sect1 id="output-devices">
    <title>Output Devices</title> 
    <para>
      PLplot supports a variety of output devices, via a set of device drivers.
      Each driver is required to emulate a small set of low-level graphics
      primitives such as initialization, line draw and page advance, as well
      as be completely independent of the PLplot package as a whole.  Thus a
      driver may be very simple, as in the case of the many black and white file
      drivers (tektronix, etc.).  More complicated and/or color systems require a
      bit more effort by the driver, with the most effort required by an output
      device with a graphical user interface, including menus for screen dumps,
      palette manipulation, and so forth.  At present only the tk driver does
      the latter on Unix systems.  At present we aren't pursuing
      a Macintosh development effort due to a lack of time and expertise, but
      will assist anyone wanting to volunteer for the job.
    </para>

    <para> Note that if you always render to a PLplot metafile, you can always
    <function>plrender</function> them to new devices as they become available.
    </para>

    <para>
      The list of available devices presented when starting PLplot (via
      <literal>plstar</literal>) is determined at compile time.  When installing PLplot you may wish
      to exclude devices not available on your system in order to reduce screen
      clutter.  To include a specified device, simply define the appropriate macro
      constant when building PLplot (see the installation instructions for your
      system).
    </para>

    <para>
      The device drivers for PLplot terminal output at present are given in 
      <xref linkend="tab_dev1"/> while 
      drivers for file output are given in
      <xref linkend="tab_dev2"/>.
      The driver for OS/2 PM is available separately.  See the section on OS/2 in
      the Appendix for more details.

      <table frame="none" id="tab_dev1">
	<title>PLplot Terminal Output Devices</title>
	<tgroup cols="3" align="center">
	  <colspec colwidth="1*"/>
	  <colspec colwidth="1*"/>
	  <colspec colwidth="1*"/>
	  <thead>
	    <row><entry>Device</entry><entry>keyword</entry><entry>driver file</entry></row>
	  </thead>
	  <tbody>
	    <row><entry>X-Window Screen</entry><entry>xwin</entry><entry>xwin.c</entry></row>
	    <row><entry>Tcl/Tk widget</entry><entry>tk</entry><entry>tk.c</entry></row>
	    <row><entry>Linux console VGA</entry><entry>vga</entry><entry>linuxvga.c</entry></row>
	    <row><entry>Xterm Window</entry><entry>xterm</entry><entry>tek.c</entry></row>
	    <row><entry>Tektronix Terminal (4010)</entry><entry>tekt</entry><entry>tek.c</entry></row>
	    <row><entry>Tektronix Terminal (4105/4107)</entry><entry>tek4107t</entry><entry>tek.c</entry></row>
	    <row><entry>MS-Kermit emulator</entry><entry>mskermit</entry><entry>tek.c</entry></row>
	    <row><entry>Versaterm vt100/tek emulator</entry><entry>versaterm</entry><entry>tek.c</entry></row>
	    <row><entry>VLT vt100/tek emulator</entry><entry>vlt</entry><entry>tek.c</entry></row>
	    <row><entry>Conex vt320/tek emulator</entry><entry>conex</entry><entry>tek.c</entry></row>
	    <row><entry>DG300 Terminal</entry><entry>dg300</entry><entry>dg300.c</entry></row>
	    <row><entry>NeXT display (unsupported)</entry><entry>nx</entry><entry>next.c</entry></row>
	  </tbody>
	</tgroup>
      </table>

      <table frame="none" id="tab_dev2">
	<title>PLplot File Output Devices</title>
	<tgroup cols="3" align="center" colsep="0" rowsep="0">
	  <colspec colwidth="1*"/>
	  <colspec colwidth="1*"/>
	  <colspec colwidth="1*"/>
	  <thead>
	    <row><entry>Device</entry><entry>keyword</entry><entry>driver file</entry></row>
	  </thead>
	  <tbody>
	    <row><entry>PLplot Native Meta-File</entry><entry>plmeta</entry><entry>plmeta.c</entry></row>
	    <row><entry>Tektronix File (4010)</entry><entry>tekf</entry><entry>tek.c</entry></row>
	    <row><entry>Tektronix File (4105/4107)</entry><entry>tek4107f</entry><entry>tek.c</entry></row>
	    <row><entry>PostScript File (monochrome)</entry><entry>ps</entry><entry>ps.c</entry></row>
	    <row><entry>PostScript File (color)</entry><entry>psc</entry><entry>ps.c</entry></row>
	    <row><entry>XFig file</entry><entry>xfig</entry><entry>xfig.c</entry></row>
	    <row><entry>LaserJet IIp Bitmap File </entry><entry>ljiip</entry><entry>ljiip.c</entry></row>
	    <row><entry>LaserJet II Bitmap File (150 dpi)</entry><entry>ljii</entry><entry>ljii.c</entry></row>
	    <row><entry>HP 7470 Plotter File (HPGL Cartridge Small Plotter)</entry><entry>hp7470</entry><entry>hpgl.c</entry></row>
	    <row><entry>HP 7580 Plotter File (Large Plotter)</entry><entry>hp7580</entry><entry>hpgl.c</entry></row>
	    <row><entry>HP Laser Jet, HPGL file</entry><entry>lj_hpgl</entry><entry>hpgl.c</entry></row>
	    <row><entry>Impress File</entry><entry>imp</entry><entry>impress.c</entry></row>
	    <row><entry>Portable bitmap file</entry><entry>pbm</entry><entry>pbm.c</entry></row>
	    <row><entry>Null device</entry><entry>null</entry><entry>null.c</entry></row>
	    <row><entry>JPEG file</entry><entry>jpeg</entry><entry>gd.c</entry></row>
	    <row><entry>PNG file</entry><entry>png</entry><entry>gd.c</entry></row>
	    <row><entry>Computer Graphics Metafile</entry><entry>cgm</entry><entry>cgm.c</entry></row>
	  </tbody>
	</tgroup>
      </table>
    </para>

    <sect2 id="driver-functions">
      <title>Driver Functions</title> 

      <para> A dispatch table is used to direct function calls to whatever driver
      is chosen at run-time.  Below are listed the names of each entry in the
      PLDispatchTable dispatch table struct defined in
      <filename>plcore.h</filename>.  The entries specific to each device (defined
      in <filename>drivers/*.c</filename>) are typically named similarly but with
      <quote>pl_</quote> replaced by a string specific for that device (the
      logical order must be preserved, however). The dispatch table entries are :

      <itemizedlist>
	<listitem>
	  <para>
	    <literal>pl_MenuStr</literal>: Pointer to string that is printed in device menu.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <literal>pl_DevName</literal>: A short device "name" for device selection by name.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <literal>pl_type</literal>: 0 for file-oriented device, 1 for interactive
	    (the null driver uses -1 here).
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <literal>pl_init</literal>: Initialize device.  This routine may also prompt the user
	    for certain device parameters or open a graphics file
	    (see Notes).  Called only once to set things up.  Certain
	    options such as familying and resolution (dots/mm) should
	    be set up before calling this routine (note: some drivers
	    ignore these).
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <literal>pl_line</literal>: Draws a line between two points.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <literal>pl_polyline</literal>: Draws a polyline (no broken segments).
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <literal>pl_eop</literal>: Finishes out current page (see Notes).
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <literal>pl_bop</literal>: Set up for plotting on a new page. May also open a new
	    a new graphics file (see Notes).
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <literal>pl_tidy</literal>: Tidy up. May close graphics file (see Notes).
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <literal>pl_state</literal>: Handle change in PLStream state
	    (color, pen width, fill attribute, etc).
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <literal>pl_esc</literal>: Escape function for driver-specific commands.
	  </para>
	</listitem>
      </itemizedlist>
      Notes: Most devices allow multi-page plots to be stored in a single graphics
      file, in which case the graphics file should be opened in the pl_init()
      routine, closed in pl_tidy(), and page advances done by calling pl_eop and
      pl_bop() in sequence. If multi-page plots need to be stored in different
      files then pl_bop() should open the file and pl_eop() should close it.  Do
      NOT open files in both pl_init() and pl_bop() or close files in both
      pl_eop() and pl_tidy(). It is recommended that when adding new functions to
      only a certain driver, the escape function be used.  Otherwise it is
      necessary to add a null routine to all the other drivers to handle the new
      function. 
      </para>

    </sect2>

    <sect2 id="metafiles-plrender">
      <title>PLplot Metafiles and Plrender</title> 

      <para>
	The PLplot metafile is a way to store and transport your graphical data for
	rendering at a later time or on a different system.  A PLplot metafile is
	in binary format in order to speed access and keep storage costs
	reasonable.  All data is stored in device-independent format (written as a
	stream of bytes); the resulting file is about as portable as a tektronix
	vector graphics file and only slightly larger. 
      </para>

      <para>
	Each PLplot metafile begins with a header string that identifies it as
	such, as well as the version number of the format since
	this may change in time.  The utility for rendering the metafile,
	<function>plrender</function>, verifies that the input file is indeed a valid PLplot metafile,
	and that it <quote>understands</quote> the format the metafile is written in.
	<function>plrender</function> is part of the PLplot package and should be built at the time of
	building PLplot, and then put into your search path.  It is capable of 
	high speed rendering of the graphics file, especially if the output device
	can accept commands at a high rate (e.g. X windows). 
      </para>

      <para>
	The commands as written by the metafile driver at present are as follows:
	<itemizedlist>
	  <listitem><para><literal>INITIALIZE</literal></para></listitem>
	  <listitem><para><literal>CLOSE</literal></para></listitem>
	  <listitem><para><literal>SWITCH_TO_TEXT</literal></para></listitem>
	  <listitem><para><literal>SWITCH_TO_GRAPH</literal></para></listitem>
	  <listitem><para><literal>CLEAR</literal></para></listitem>
	  <listitem><para><literal>PAGE</literal></para></listitem>
	  <listitem><para><literal>NEW_COLOR</literal></para></listitem>
	  <listitem><para><literal>NEW_WIDTH</literal></para></listitem>
	  <listitem><para><literal>LINE</literal></para></listitem>
	  <listitem><para><literal>LINETO</literal></para></listitem>
	  <listitem><para><literal>ESCAPE</literal></para></listitem>
	  <listitem><para><literal>ADVANCE</literal></para></listitem>
	</itemizedlist>
      </para>

      <para> 
	Each command is written as a single byte, possibly followed by
	additional data bytes.  The <literal>NEW_COLOR</literal> and
	<literal>NEW_WIDTH</literal> commands each write 2 data bytes, the
	<literal>LINETO</literal> command writes 4 data bytes, and the
	<literal>LINE</literal> command writes 8 data bytes.  The most common
	instruction in the typical metafile will be the <literal>LINETO</literal>
	command, which draws a continuation of the previous line to the given point.
	This data encoding is not quite as efficient as the tektronix format, which
	uses 4 bytes instead of 5 here (1 command <literal>+</literal> 4 data),
	however the PLplot encoding is far simpler to implement and more robust. The
	<literal>ESCAPE</literal> function writes a second command character
	(opcode) followed by an arbitrary number of data bytes depending on the
	value of the opcode. Note that any data written must be in device
	independent form to maintain the transportability of the metafile so
	floating point numbers are not allowed. 
      </para>

      <para>
	The short usage message for <function>plrender</function> is printed if one inputs
	insufficient or invalid arguments, and is as follows:
	<screen>
	  <prompt>%</prompt> <userinput>plrender</userinput>

	  No filename specified.

	  Usage:
	  plrender [options] [files]

	  plrender options:
	  [-v] [-i name] [-b number] [-e number] [-p page]

	  PLplot options:
	  [-h] [-v] [-verbose] [-debug] [-dev name] [-o name] [-display name]
	  [-px number] [-py number] [-geometry geom] [-wplt xl,yl,xr,yr]
	  [-mar margin] [-a aspect] [-jx justx] [-jy justy] [-ori orient]
	  [-freeaspect] [-width width] [-bg color] [-ncol0 n] [-ncol1 n] [-fam]
	  [-fsiz size] [-fbeg number] [-finc number] [-fflen length] [-nopixmap]
	  [-db] [-np] [-server_name name] [-server_host name] [-server_port name]
	  [-user name]


	  Type plrender -h for a full description.

	</screen>
      </para>

      <para>
	The longer usage message goes into more detail, and is as follows:
	<screen>
	  <prompt>%</prompt> <userinput>plrender -h</userinput>

	  Usage:
	  plrender [options] [files]

	  plrender options:
	  -v                   Print out the plrender version number
	  -i name              Input filename
	  -b number            Beginning page number
	  -e number            End page number
	  -p page              Plot given page only

	  If the "-i" flag is omitted, unrecognized input will assumed to be filename
	  parameters.  Specifying "-" for the input or output filename means use stdin
	  or stdout, respectively.  See the manual for more detail.

	  PLplot options:
	  -h                   Print out this message
	  -v                   Print out the PLplot library version number
	  -verbose             Be more verbose than usual
	  -debug               Print debugging info (implies -verbose)
	  -dev name            Output device name
	  -o name              Output filename
	  -display name        X server to contact
	  -px number           Plots per page in x
	  -py number           Plots per page in y
	  -geometry geom       Window size, in pixels (e.g. -geometry 400x300)
	  -wplt xl,yl,xr,yr    Relative coordinates [0-1] of window into plot
	  -mar margin          Margin space in relative coordinates (0 to 0.5, def 0)
	  -a aspect            Page aspect ratio (def: same as output device)
	  -jx justx            Page justification in x (-0.5 to 0.5, def 0)
	  -jy justy            Page justification in y (-0.5 to 0.5, def 0)
	  -ori orient          Plot orientation (0,2=landscape, 1,3=portrait)
	  -freeaspect          Do not preserve aspect ratio on orientation swaps
	  -portrait            Sets portrait mode (both orientation and aspect ratio)
	  -width width         Sets pen width (1 &lt;= width &lt;= 10)
	  -bg color            Background color (0=black, FFFFFF=white)
	  -ncol0 n             Number of colors to allocate in cmap 0 (upper bound)
	  -ncol1 n             Number of colors to allocate in cmap 1 (upper bound)
	  -fam                 Create a family of output files
	  -fsiz size[kKmMgG]   Output family file size in MB (e.g. -fsiz 0.5G, def MB)
	  -fbeg number         First family member number on output
	  -finc number         Increment between family members
	  -fflen length        Family member number minimum field width
	  -nopixmap            Don't use pixmaps in X-based drivers
	  -db                  Double buffer X window output
	  -np                  No pause between pages
	  -server_name name    Main window name of PLplot server (tk driver)
	  -dpi dpi             Resolution, in dots per inch (e.g. -dpi 360x360)
	  -compression num     Sets compression level in supporting devices
	  -drvopt option[=value][,option[=value]]* Driver specific options
	</screen>
      </para>

      <para>
	The options are generally self explanatory (family files are explained in
	<xref linkend="familying"/>).
	Most of these options have default values, and for those that don't
	<function>plrender</function> will prompt the user.  The
	<literal>-px</literal> and <literal>-py</literal> options are
	not so useful at present, because everything is scaled down by the
	specified factor --- resulting in labels that are too small (future
	versions of <function>plrender</function> might allow changing the label size as well). 
      </para>

      <para>
	Additional options may be added in future releases.
      </para>

    </sect2>

    <sect2 id="familying">
      <title>Family File Output</title> 

      <para>
	When sending PLplot to a file, the user has the option of generating a
	<quote>family</quote> of output files for most output file drivers.
	This can be valuable when generating a large amount of output, so as to not
	strain network or printer facilities by processing extremely large single
	files.  Each family member file can be treated as a completely independent
	file.  In addition, <function>plrender</function> has the ability to process a set of
	family member files as a single logical file.
      </para>

      <para> To create a family file, one must simply call &plsfam; with the
      familying flag <literal>fam</literal> set to 1, and the desired maximum
      member size (in bytes) in <literal>bmax</literal>.  &plsfam; also allows
      you to set the current family file number.  If the current output
      driver does not support familying, there will be no effect.  This call must
      be made <emphasis>before</emphasis> calling &plstar; or &plstart;. </para>

      <para> If familying is enabled, the name given for the output file (on the
      command line, in response to the &plstar; prompt, as a &plstart; argument,
      or as the result of a call to &plsfnam;) becomes the name template for the
      family.  Thus, if you request a plmeta output file with name
      <filename>test-%n.plm</filename>, the files actually created will be
      <filename>test-1.plm</filename>, <filename>test-2.plm</filename>, and so on,
      where <filename>%n</filename> indicates where the member number is replaced.
      If there is no <filename>%n</filename>, then the output file becomes the
      stem name and the created files will be like
      <filename>test.plm.1</filename>, <filename>test.plm.2</filename>, and so on.
      A new file is automatically started once the byte limit for the current file
      is passed, but not until the next page break. One may insure a new file at
      every page break by making the byte limit small enough.  Alternatively, if
      the byte limit is large you can still insure a new file is automatically
      started after a page break if you precede the call to &pleop; with a call to
      &plfamadv;.</para>
      <para> If familying is not enabled, <filename>%n</filename> is dropped
      from the filename if that string appears anywhere in it.</para>


      <para>
	The &plgfam; routine can be used from within the user program to find
	out more about the graphics file being written.  In particular, by
	periodically checking the number of the member file currently being written
	to, one can detect when a new member file is started.  This information
	might be used in various ways; for example you could spawn a process to
	automatically plrender each metafile after it is closed (perhaps during a
	long simulation run) and send it off to be printed. 
      </para>

      <para> <function>plrender</function> has several options for dealing with
      family files.  It can process a single member file
      (<function>plrender</function>  <filename>test.plm.1</filename>)
      or the entire family if given only the stem name
      (<function>plrender</function>  <filename>test.plm</filename>)
      It can also create family files on output, rendering to any
      device that supports familying, including another metafile if desired.  The
      size of member files in this case is input through the argument list, and
      defaults to 1MB if unspecified (this may be changed during the PLplot
      installation, however). <function>plrender</function> can also create a
      single output file from a familied input metafile. </para>

    </sect2>

    <sect2 id="interactive-devices">
      <title>Interactive Output Devices</title> 

      <para>
	Here we shall discuss briefly some of the more common interactive output
	devices.  
      </para>

      <para>
	Many popular terminals or terminal emulators at present have a
	facility for switching between text and graphics <quote>screens</quote>.
	This includes the xterm emulator under X-windows, vt100's with
	Retrographics, and numerous emulators for microcomputers which have a dual
	vt100/tek4010 emulation capability.  On these devices, it is possible to
	switch between the text and graphics screens by surrounding your PLplot
	calls by calls to &plgra; and &pltext;.  This will allow your diagnostic and
	informational code output to not interfere with your graphical output.
      </para>

      <para>
	At present, only the xterm driver supports switching between text
	and graphics screens.  The escape sequences as sent by the xterm driver
	are fairly standard, however, and have worked correctly on most other
	popular vt100/tek4010 emulators we've tried.
      </para>

      <para>
	When using the xterm driver, hitting a RETURN will advance and clear the
	page.  If indeed running from an xterm, you may resize, move, cover and
	uncover the window.  The behavior of the X-window driver is quite different,
	however.  First, it is much faster, as there is no tty-like handshaking
	going on.  Second, a mouse click is used to advance and clear the page,
	rather than a RETURN.
      </para>

      <para>
	On a tektronix 4014 compatible device, you may preview tektronix output
	files via the <function>pltek</function> utility.
	<function>pltek</function> will let you step through the file interactively,
	skipping backward or forward if desired.  The help message for
	<function>pltek</function> is as follows:

	<screen>
	  <prompt>%</prompt> <userinput>pltek</userinput>
	  Usage: pltek filename 
	  At the prompt, the following replies are recognized:
	  h,?    Give this help message.
	  q     Quit program.
	  &lt;n>    Go to the specified page number.
	  -&lt;n>   Go back &lt;n> pages.
	  +&lt;n>   Go forward &lt;n> pages.
	  &lt;Return> Go to the next page.

	</screen>
	The output device is switched to text mode before the prompt is given,
	which causes the prompt to go to the vt102 window under xterm and
	most vt100/tek4010 emulators.
      </para>
    </sect2>

    <sect2 id="specifying-devices">
      <title>Specifying the Output Device</title>

      <para>
	The main initialization routine for PLplot is &plinit;, which sets up
	all internal data structures necessary for plotting and initializes
	the output device driver.  The output device can be a terminal, disk
	file, window system, pipe, or socket.  If the output device has not
	already been specified when &plinit; is called, the output device
	will be taken from the value of the PLPLOT_DEV environment variable.
	If this variable is not set (or is empty), a list of valid output
	devices is given and the user is prompted for a choice.  For example:
      </para>
      
      <para>
	<screen>
	  <prompt>%</prompt> <userinput>x01c</userinput>
	  
	  Plotting Options:
	  &lt; 1> xwin       X-Window (Xlib)
	  &lt; 2> tk         Tcl/TK Window
	  &lt; 3> xterm      Xterm Window
	  &lt; 4> tekt       Tektronix Terminal (4010)
	  &lt; 5> tek4107t   Tektronix Terminal (4105/4107)
	  &lt; 6> mskermit   MS-Kermit emulator
	  &lt; 7> versaterm  Versaterm vt100/tek emulator
	  &lt; 8> vlt        VLT vt100/tek emulator
	  &lt; 9> plmeta     PLPLOT Native Meta-File
	  &lt;10> tekf       Tektronix File (4010)
	  &lt;11> tek4107f   Tektronix File (4105/4107)
	  &lt;12> ps         PostScript File (monochrome)
	  &lt;13> psc        PostScript File (color)
	  &lt;14> xfig       Xfig file
	  &lt;15> ljiip      LaserJet IIp/deskjet compressed graphics
	  &lt;16> ljii       LaserJet II Bitmap File (150 dpi)
	  &lt;17> null       Null device

	  Enter device number or keyword: <!--
	  --></screen>
      </para>
      
      <para>
	Either the device number or a device keyword is accepted.  Specifying
	the device by keyword is preferable in aliases or scripts since the
	device number is dependent on the install procedure (the installer
	can choose which device drivers to include).  The device can be
	specified prior to the call to &plinit; by:

	<itemizedlist>
	  <listitem>
	    <para>
	      A call to &plsdev;.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      The <literal>-dev</literal> <replaceable>device</replaceable>
	      command line argument, if the program's command line arguments
	      are being passed to the PLplot function
	      &plparseopts;.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      The value of the <literal>PLPLOT_DEV</literal> environment
	      variable.  Note that specifying the output device via &plsdev;
	      or the <literal>-dev</literal> command line argument will
	      override the value given by the <literal>PLPLOT_DEV</literal>
	      environment variable.
	    </para>
	  </listitem>
	</itemizedlist>
	
      </para>

      <para>
	Additional start up routines &plstar; and &plstart; are available but
	these are simply front-ends to &plinit;, and should be avoided.  It
	is preferable to call &plinit; directly, along with the appropriate
	setup calls, for the greater amount of control this provides (see the
	example programs for more info).
      </para>

      <para>
	Before &plinit; is called, you may modify the number of subpages the
	output device is divided into via a call to
	<function>plssub</function>.  Subpages are useful for placing several
	graphs on a page, but all subpages are constrained to be of the same
	size.  For greater flexibility, viewports can be used (see <xref
	linkend="viewports"/> for more info on viewports).  The routine
	&pladv; is used to advance to a particular subpage or to the next
	subpage.  The screen is cleared (or a new piece of paper loaded) if a
	new subpage is requested when there are no subpages left on the
	current page.  When a page is divided into subpages, the default
	character, symbol and tick sizes are scaled inversely as the square
	root of the number of subpages in the vertical direction.  This is
	designed to improve readability of plot labels as the plot size
	shrinks.
      </para>

      <para>
	PLplot has the ability to write to multiple output streams.  An
	output stream corresponds to a single logical device to which one
	plots independent of all other streams.  The function &plsstrm; is
	used to switch between streams -- you may only write to one output
	stream at a time.  At present, an output stream is not limited by the
	type of device, however, it may not be wise to attempt opening two
	terminal devices.  An example usage for the creation of multiple
	streams is as follows:
      </para>

      <para>
	<programlisting>#include "plplot.h"

	main()
	{
	int nx = 2, ny = 2;

	plssub(nx, ny);
	plsdev("xwin");
	plinit();

	<lineannotation>plots for stream 0</lineannotation>

	plsstrm(1);
	plssub(nx, ny);
	plsdev("plmeta");
	plsfnam("tst.plm");
	plinit();

	<lineannotation>plots for stream 1</lineannotation>

	plsstrm(0);

	<lineannotation>plots for stream 0</lineannotation></programlisting>
      </para>

      <para>
	and so on, for sending output simultaneously to an X-window and a
	metafile.  The default stream corresponds to stream number zero.  At
	present, the majority of output drivers can only be used by a single
	stream (exceptions include the metafile driver and X-window driver).
	Also see example program 14 (note: only the C version is available,
	although it can be done equally well from Fortran).
      </para>

      <para>
	At the end of a plotting program, it is important to close the
	plotting device by calling &plend;.  This flushes any internal
	buffers and frees any memory that may have been allocated, for all
	open output streams.  You may call &plend1; to close the plotting
	device for the current output stream only.  Note that if PLplot is
	initialized more than once during a program to change the output
	device, an automatic call to &plend1; is made before the new device
	is opened for the given stream.
      </para>

    </sect2>
  </sect1>

  <sect1 id="FreeType-notes">
    <title>Adding FreeType Library Support to Bitmap Drivers</title>

    <para>Any bitmap driver in the PLplot family should be able to use fonts
    (TrueType and others) that are rendered by the FreeType library just as long
    as the device supports setting an individual pixel. Note that drivers
    interact with FreeType using the support routines 
    <literal>plD_FreeType_init</literal>,
    <literal>plD_render_freetype_text</literal>,
    <literal>plD_FreeType_Destroy</literal>,
    <literal>pl_set_extended_cmap0</literal>, and
    <literal>pl_RemakeFreeType_text_from_buffer</literal> that are coded in
    <filename>plfreetype.c</filename>.</para>

    <para>The use of these support routines is exemplified by the
    <filename>gd.c</filename> driver.  Here we make some notes to accompany
    this driver which should make it easier to migrate other drivers to
    use the FreeType library.  Every code fragment we mention below should be surrounded
    with a <literal>#ifdef PL_HAVE_FREETYPE...#endif</literal> to quarantine these
    fragments for systems without the FreeType library.  For interactive devices that
    need caching of text drawing, reference should also be made to
    <filename>wingcc.c</filename>.</para>

    <sect2>
      <title>Write a call back function to plot a single pixel</title>

      <para>First, write a call back function, of type
      <literal>plD_pixel_fp</literal>, which specifies how a single pixel is set
      in the current color. This can be of type static void. For example, in the
      <filename>gd.c</filename> driver it looks like this:

      <programlisting>
	void plD_pixel_gd (PLStream *pls, short x, short y)
	{
	png_Dev *dev=(png_Dev *)pls->dev;

	gdImageSetPixel(dev->im_out, x, y,dev->colour);
	}
      </programlisting>
      </para>
    </sect2>

    <sect2>
      <title>Initialize FreeType</title>

      <para>Next, we have to initialize the FreeType library. For the
      <filename>gd.c</filename> driver this is done via two separate functions due
      to the order that dependent information is initialized in the driver.</para>

      <para>The "level 1" initialization of FreeType does two things: 1) calls
      <literal>plD_FreeType_init(pls)</literal>, which in turn allocates memory to
      the pls->FT structure; and 2) stores the location of the call back routine.
      </para>

      <para>
	<programlisting>
	  void init_freetype_lv1 (PLStream *pls)
	  {
	  FT_Data *FT;

	  plD_FreeType_init(pls);

	  FT=(FT_Data *)pls->FT;
	  FT->pixel= (plD_pixel_fp)plD_pixel_gd;

	  }
	</programlisting>
      </para>

      <para>This initialization routine is called at the end of 
      <literal>plD_init_png_Dev(PLStream *pls)</literal> in the
      <filename>gd.c</filename> driver:</para>

      <para>
	<programlisting>
	  if (freetype)
	  {
	  pls->dev_text = 1; /* want to draw text */
	  init_freetype_lv1(pls);
	  FT=(FT_Data *)pls->FT;
	  FT->smooth_text=smooth_text;
	  }
	</programlisting>
      </para>

      <para><literal>"freetype"</literal> is a local variable which is parsed
      through <literal>plParseDrvOpts</literal> to determine if the user wanted
      FreeType text. In that case <literal>pls->dev_text</literal> is set to 1 to
      indicate the driver will be rendering it's own text. After that, we always
      use <literal>pls->dev_text</literal> to work out if we want FreeType or
      not.</para>

      <para>Similarly, <literal>"smooth_text"</literal> is a local variable passed
      through <literal>plParseDrvOpts</literal> to find out if the user wants
      smoothing. Since there is nothing in PLStream to track smoothing, we have to
      set the FT->smooth_text flag as well at this time.</para>

      <para>The "level 2" initialization function initializes everything else
      required for using the FreeType library but has to be called after the
      screen resolution and dpi have been set. Therefore, it is called at the end
      of <literal>plD_init_png()</literal>, where it looks like:

      <programlisting>
	if (pls->dev_text)
	{
	init_freetype_lv2(pls);
	}
      </programlisting>
      </para>

      <para>The actual function looks like this:

      <programlisting>
	static void init_freetype_lv2 (PLStream *pls)
	{
	png_Dev *dev=(png_Dev *)pls->dev;
	FT_Data *FT=(FT_Data *)pls->FT;

	FT->scale=dev->scale;
	FT->ymax=dev->pngy;
	FT->invert_y=1;

	if (FT->smooth_text==1)
	{
	FT->ncol0_org=pls->ncol0;                                   /* save a copy of the original size of ncol0 */
	FT->ncol0_xtra=NCOLOURS-(pls->ncol1+pls->ncol0);            /* work out how many free slots we have */
	FT->ncol0_width=FT->ncol0_xtra/(pls->ncol0-1);              /* find out how many different shades of anti-aliasing we can do */
	if (FT->ncol0_width>64) FT->ncol0_width=64;                 /* set a maximum number of shades */
	plscmap0n(FT->ncol0_org+(FT->ncol0_width*pls->ncol0));      /* redefine the size of cmap0 */
	/* the level manipulations are to turn off the plP_state(PLSTATE_CMAP0)
	* call in plscmap0 which (a) leads to segfaults since the GD image is
	* not defined at this point and (b) would be inefficient in any case since
	* setcmap is always called later (see plD_bop_png) to update the driver
	* color palette to be consistent with cmap0. */
	{
	PLINT level_save;
	level_save = pls->level;
	pls->level = 0;
	pl_set_extended_cmap0(pls, FT->ncol0_width, FT->ncol0_org); /* call the function to add the extra cmap0 entries and calculate stuff */
	pls->level = level_save;
	}
	}

	}
      </programlisting>
      </para>

      <para>FT->scale is a scaling factor to convert coordinates. This is used by
      the <filename>gd.c</filename> and some other drivers to scale back a larger virtual page and this
      eliminate the "hidden line removal bug". Set it to 1 if your device driver
      doesn't use any scaling.</para>

      <para>Some coordinate systems have zero on the bottom, others have zero on
      the top. FreeType does it one way, and most everything else does it the
      other. To make sure everything is working OK, we have to "flip" the
      coordinates, and to do this we need to know how big in the Y dimension the
      page is, and whether we have to invert the page or leave it alone.</para>

      <para> <itemizedlist> 
	<listitem><para>FT->ymax specifies the size of the page</para></listitem> 
	<listitem><para>FT->invert_y=1 tells us to invert the
	y-coordinates, FT->invert_y=0 will not invert the coordinates.
      </para></listitem> </itemizedlist></para>

      <para>We also do some computational gymnastics to "expand" cmap0 if the user
      wants anti-aliased text.  Basically, you have to work out how many spare
      colors there are in the driver after cmap0 and cmap1 are done, then set a
      few variables in FT to let the render know how many colors it's going to
      have at its disposal, and call plscmap0n to resize cmap0.  The call to
      <literal>pl_set_extended_cmap0</literal> does the remaining part of the
      work.  Note it essential to protect that call by the
      <literal>pls->level</literal> manipulations for the reasons stated. </para>

    </sect2>

    <sect2>
      <title>Add A Command to redraw text (interactive drivers only)</title>

      <para>Plplot only caches drawing commands, not text plotting commands, so
      for interactive devices which refresh their display by replaying the plot
      buffer, a separate function has to be called to redraw the text.  plfreetype
      knows when buffering is being used by a device driver, and will automatically
      start caching text when necessary.  To redraw this cached text, a call to
      <literal>pl_RemakeFreeType_text_from_buffer</literal> has to be added after the driver has called
      <literal>plRemakePlot</literal>.  The following example is from <filename>wingcc.c</filename>.

      <programlisting>
	if (dev->waiting==1)
	{
	plRemakePlot(pls);
	#ifdef PL_HAVE_FREETYPE
	pl_RemakeFreeType_text_from_buffer(pls);
	#endif
	}
      </programlisting>
      </para>

    </sect2>


    <sect2>
      <title>Add Function Prototypes</title>

      <para>Next, to the top of the drivers' source file add the prototype
      definitions for the functions just written.

      <programlisting>
	static void plD_pixel_gd (PLStream *pls, short x, short y);
	static void init_freetype_lv1 (PLStream *pls);
	static void init_freetype_lv2 (PLStream *pls);
      </programlisting>
      </para>

    </sect2>

    <sect2>
      <title>Add Closing functions</title>

      <para>Finally, add a <literal>plD_FreeType_Destroy(pls)</literal> entry to
      the device "tidy" function; this command deallocates memory allocated to the
      FT entry in the stream, closes the FreeType library and any open fonts. It
      is also a good idea to reset CMAP0 back to it's original size here if
      anti-aliasing was done. For example, in the <filename>gd.c</filename>
      driver, it looks like this:

      <programlisting>
	void plD_tidy_png(PLStream *pls)
	{
	fclose(pls->OutFile);

	#ifdef PL_HAVE_FREETYPE
	FT_Data *FT=(FT_Data *)pls->FT;
	plscmap0n(FT->ncol0_org);

	plD_FreeType_Destroy(pls);
	#endif

	free_mem(pls->dev);
	}

      </programlisting>
      </para>
    </sect2>
  </sect1>

  <sect1 id="viewport_window">
    <title>View Surfaces, (Sub-)Pages, Viewports and Windows</title> 

    <para>There is a whole hierarchy of coordinate systems associated with
    any PLplot graph.  At the lowest level a device provides a view surface
    (coordinates in mm's) which can be a terminal screen or a sheet of paper
    in the output device.  &plinit; or &plstar; (or &plstart;) makes that
    device view surface accessible as a page or divided up into sub-pages
    (see &plssub;) which are accessed with &pladv;.  Before a graph can be
    drawn for a subpage, the program must call appropriate routines in
    PLplot to define the viewport for the subpage and a window for the
    viewport. A viewport is a rectangular region of the
    <emphasis>subpage</emphasis> which is specified in normalized subpage
    coordinates or millimetres.  A window is a rectangular region of
    world-coordinate space which is mapped directly to its viewport. (When
    drawing a graph, the programmer usually wishes to specify the
    coordinates of the points to be plotted in terms of the values of the
    variables involved. These coordinates are called <emphasis>world
    coordinates</emphasis>, and may have any floating-point value
    representable by the computer.)</para>
    
    <para>Although the usual choice is to have one viewport per subpage, and
    one window per viewport, each subpage can have more than one (possibly
    overlapping) viewport defined, and each viewport can have more than one
    window (more than one set of world coordinates) defined.</para>

    <sect2 id="viewports">
      <title>Defining the Viewport</title>

      <para> After defining the view surface and subpage with the appropriate
      call to &plinit; or &plstar; (or &plstart;) and a call to &pladv; it
      is necessary to define the portion of this subpage which is to be used
      for plotting the graph (the viewport).  All lines and symbols (except
      for labels drawn by &plbox;, &plmtex; and &pllab;) are clipped at the
      viewport boundaries. </para>

      <para> Viewports are created within the current subpage.  If the
      division of the output device into equally sized subpages is
      inappropriate, it is best to specify only a single subpage which
      occupies the entire output device (by using &plinit; or by setting
      <literal>nx = 1</literal> and <literal>ny = 1</literal> in &plstar;
      or &plstart;), and use one of the viewport specification subroutines
      below to place the plot in the desired position on the page. </para>

      <para>
	There are four methods for specifying the viewport size, using the
	subroutines &plvpor;, &plsvpa;, &plvasp;, and &plvpas; which are
	called like this:
      </para>

      <para>
	<programlisting>    plvpor(xmin, xmax, ymin, ymax);
	plsvpa(xmin, xmax, ymin, ymax);
	plvasp(aspect);
	plvpas(xmin, xmax, ymin, ymax, aspect);</programlisting>
      </para>

      <para>
	where in the case of &plvpor; and &plvpas;, the arguments are given
	in <emphasis>normalized subpage coordinates</emphasis> which are
	defined to run from 0.0 to 1.0 along each edge of the subpage.  Thus
	for example,
      </para>
      
      <para>
	<programlisting>    plvpor(0.0, 0.5, 0.5, 1.0);</programlisting>
      </para>

      <para>
	uses the top left quarter of the current subpage.
      </para>

      <para>
	In order to get a graph of known physical size, the routine &plsvpa;
	defines the viewport in terms of absolute coordinates (millimeters)
	measured from the bottom left-hand corner of the current subpage.
	This routine should only be used when the size of the view surface is
	known, and a definite scaling is required.
      </para>

      <para>
	The routine &plvasp; gives the largest viewport with the given aspect
	ratio that fits in the current subpage (i.e. the ratio of the length
	of the y axis to that of the x axis is equal to
	<literal>aspect</literal>).  It also allocates space on the left and
	top of the viewport for labels.
      </para>

      <para>
	The routine &plvpas; gives the largest viewport with the given aspect
	ratio that fits in the specified region (specified with normalized
	subpage coordinates, as with &plvpor;).  This routine is functionally
	equivalent to &plvpor; when a <quote>natural</quote> aspect ratio is
	chosen (done by setting <literal>aspect</literal> to 0.0).  Unlike
	&plvasp;, this routine reserves no extra space at the edges for
	labels.
      </para>

      <para>
	To help the user call &plsvpa; correctly, the routine &plgspa; is
	provided which returns the positions of the extremities of the
	current subpage measured in millimeters from the bottom left-hand
	corner of the device.  Thus, if to set up a viewport with a 10.0 mm
	margin around it within the current subpage, the following sequence
	of calls may be used:
      </para>
      
      <para>
	<programlisting>    plgspa(xmin, xmax, ymin, ymax);
	plsvpa(10.0, xmax-xmin-10.0, 10.0, ymax-ymin-10.0);</programlisting>
      </para>

      <para>
	A further routine &plvsta; is available which sets up a standard
	viewport within the current subpage with suitable margins on each
	side of the viewport.  This may be used for simple graphs, as it
	leaves enough room for axis labels and a title.  This standard
	viewport is that used by &plenv; (See <xref
	linkend="standard-window"/>).
      </para>

      <para>
	Another way to get a specified aspect ratio is via the routine
	<function>plsasp</function> [not!.. fix this], which sets the global
	aspect ratio and must be called prior to &plstar;.  An aspect ratio
	of 0.0 corresponds to <quote>natural</quote> dimensions (i.e. fill
	the page); any positive value will give the specified aspect ratio.
	This scaling of plots is actually done in the driver, and so may not
	work for all output devices (note that <function>plrender</function>
	is capable of scaled aspect ratio plots to any device whether that
	device supports scaling or not).  In such scaled plots, absolute
	plotting is done in the scaled coordinate system.
      </para>

    </sect2>
    
    <sect2 id="windows">
      <title>Defining the Window</title>

      <para>
	The window must be defined after the viewport in order to map the
	world coordinate rectangle into the viewport rectangle.  The routine
	&plwind; is used to specify the rectangle in world-coordinate space.
	For example, if we wish to plot a graph showing the collector current
	I<subscript>C</subscript> as a function of the collector to emitter
	voltage V<subscript>CE</subscript> for a transistor where 0 &leq;
	I<subscript>C</subscript> &leq; 10.0&nbsp;mA and 0 &leq;
	V<subscript>CE</subscript> &leq; 12.0&nbsp;V, we would call the
	function &plwind; as follows:
      </para>
      
      <para>
	<programlisting>    plwind(0.0, 12.0, 0.0, 10.0);</programlisting>
      </para>

      <para>
	Note that each of the arguments is a floating point number, and so
	the decimal points are required.  If the order of either the X limits
	or Y limits is reversed, the corresponding axis will point in the
	opposite sense, (i.e., right to left for X and top to bottom for Y).
	The window must be defined before any calls to the routines which
	actually draw the data points.  Note however that &plwind; may also
	be called to change the window at any time.  This will affect the
	appearance of objects drawn later in the program, and is useful for
	drawing two or more graphs with different axes on the same piece of
	paper.
      </para>

    </sect2>
    
    <sect2 id="annotation">
      <title>Annotating the Viewport</title>

      <para>
	The routine &plbox; is used to specify whether a frame is drawn
	around the viewport and to control the positions of the axis
	subdivisions and numeric labels.  For our simple graph of the
	transistor characteristics, we may wish to draw a frame consisting of
	lines on all four sides of the viewport, and to place numeric labels
	along the bottom and left hand side.  We can also tell PLplot to
	choose a suitable tick interval and the number of subticks between
	the major divisions based upon the data range specified to &plwind;.
	This is done using the following statement
      </para>
      
      <para>
	<programlisting>    plbox("bcnst", 0.0, 0, "bcnstv", 0.0, 0);</programlisting>
      </para>

      <para>
	The lengths of major and minor ticks on the axes are set up by the
	routines &plsmaj; and &plsmin;.
      </para>

      <para>
	Another routine &pllab; provides for text labels for the bottom, left
	hand side and top of the viewport.  These labels are not clipped,
	even though they lie outside the viewport (but they are clipped at
	the subpage boundaries).  &pllab; actually calls the more general
	routine &plmtex; which can be used for plotting labels at any point
	relative to the viewport.  For our example, we may use
      </para>
      
      <para>
	<programlisting>    pllab("V#dCE#u (Volts)", "I#dC#u (mA)", "TRANSISTOR CHARACTERISTICS");</programlisting>
      </para>

      <para>
	Note that <literal>#d</literal> and <literal>#u</literal> are escape
	sequences (see <xref linkend="escape-sequences"/>) which allow
	subscripts and superscripts to be used in text.  They are described
	more fully later in this chapter.
      </para>

      <para>
	The appearance of axis labels may be further altered by auxiliary
	calls to &plprec;, &plschr;, &plsxax;, &plsyax;, and &plszax;.  The
	routine &plprec; is used to set the number of decimal places
	precision for axis labels, while &plschr; modifies the heights of
	characters used for the axis and graph labels.  Routines &plsxax;,
	&plsyax;, and &plszax; are used to modify the
	<literal>digmax</literal> setting for each axis, which affects how
	floating point labels are formatted.
      </para>

      <para>
	The <literal>digmax</literal> variable represents the maximum field
	width for the numeric labels on an axis (ignored if less than one).
	If the numeric labels as generated by PLplot exceed this width, then
	PLplot automatically switches to floating point representation.  In
	this case the exponent will be placed at the top left for a vertical
	axis on the left, top right for a vertical axis on the right, and
	bottom right for a horizontal axis.
      </para>

      <para>
	For example, let's suppose that we have set <literal>digmax =
	5</literal> via &plsyax;, and for our plot a label is generated at
	<literal>y = 0.0000478</literal>.  In this case the actual field
	width is longer than <literal>digmax</literal>, so PLplot switches to
	floating point.  In this representation, the label is printed as
	simply 4.78 with the 10<superscript>-5</superscript> exponent placed
	separately.
      </para>

      <para>
	The determination of maximum length (i.e. <literal>digmax</literal>)
	for fixed point quantities is complicated by the fact that long fixed
	point representations look much worse than the same sized floating
	point representation.  Further, a fixed point number with magnitude
	much less than one will actually gain in precision when written as
	floating point.  There is some compensation for this effect built
	into PLplot, thus the internal representation for number of digits
	kept (<literal>digfix</literal>) may not always match the user's
	specification (via <literal>digmax</literal>).  However, it will
	always be true that <literal>digfix &leq; digmax</literal>.  The
	PLplot defaults are set up such that good results are usually
	obtained without user intervention.
      </para>

      <para>
	Finally, after the call to &plbox;, the user may call routines
	&plgxax;, &plgyax;, or &plgzax; to obtain information about the
	window just drawn.  This can be helpful when deciding where to put
	captions.  For example, a typical usage would be to call &plgyax; to
	get the value of <literal>digits</literal>, then offset the y axis
	caption by that amount (plus a bit more) so that the caption
	<quote>floats</quote> just to the outside of the numeric labels.
	Note that the <literal>digits</literal> value for each axis for the
	current plot is not correct until <emphasis>after</emphasis> the call
	to &plbox; is complete.
      </para>

    </sect2>
    
    <sect2 id="standard-window">
      <title>Setting up a Standard Window</title>

      <para>
	Having to call &pladv;, &plvpor;, &plwind; and &plbox; is excessively
	cumbersome for drawing simple graphs.  Subroutine &plenv; combines
	all four of these in one subroutine, using the standard viewport, and
	a limited subset of the capabilities of &plbox;.  For example, the
	graph described above could be initiated by the call:
      </para>

      <para>
	<programlisting>    plenv(0.0, 12.0, 0.0, 10.0, 0, 0);</programlisting>
      </para>

      <para>
	which is equivalent to the following series of calls:
      </para>

      <para>
	<programlisting>    pladv(0);
	plvsta();
	plwind(0.0, 12.0, 0.0, 10.0);
	plbox("bcnst", 0.0, 0, "bcnstv", 0.0, 0);</programlisting>
      </para>

    </sect2>
  </sect1>

  <sect1 id="line-attributes">
    <title>Setting Line Attributes</title>

    <para>
      The graph drawing routines may be freely mixed with those described
      in this section, allowing the user to control line color, width and
      styles.  The attributes set up by these routines apply modally, i.e,
      all subsequent objects (lines, characters and symbols) plotted until
      the next change in attributes are affected in the same way.  The only
      exception to this rule is that characters and symbols are not
      affected by a change in the line style, but are always drawn using a
      continuous line.
    </para>

    <para>
      Line color is set using the routine &plcol0;.  The argument is ignored
      for devices which can only plot in one color, although some terminals
      support line erasure by plotting in color zero.
    </para>

    <para>
      Line width is set using &plwidth;.  This option is not supported by
      all devices.
    </para>

    <para>
      Line style is set using the routine &plstyl; or &pllsty;.  A broken
      line is specified in terms of a repeated pattern consisting of marks
      (pen down) and spaces (pen up).  The arguments to this routine are
      the number of elements in the line, followed by two pointers to
      integer arrays specifying the mark and space lengths in micrometers.
      Thus a line consisting of long and short dashes of lengths 4&nbsp;mm
      and 2&nbsp;mm, separated by spaces of length 1.5&nbsp;mm is specified
      by:
    </para>

    <para>
      <programlisting>    mark[0] = 4000;
      mark[1] = 2000;
      space[0] = 1500;
      space[1] = 1500;
      plstyl(2, mark, space);</programlisting>
    </para>

    <para>
      To return to a continuous line, just call &plstyl; with first
      argument set to zero.  You can use &pllsty; to choose between 8
      different predefined styles.
    </para>

  </sect1>
  
  <sect1 id="fill-pattern">
    <title>Setting the Area Fill Pattern</title>

    <para>
      The routine &plpat; can be used to set 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 (the inclination should be
      between -900 and 900).  Thus to specify an area fill pattern
      consisting of horizontal lines spaced 2&nbsp;mm apart use:
    </para>
    
    <para>
      <programlisting>    *inc = 0;
      *del = 2000;
      plpat(1, inc, del);</programlisting>
    </para>

    <para>
      To set up a symmetrical crosshatch pattern with lines directed 30
      degrees above and below the horizontal and spaced 1.5&nbsp;mm apart
      use:
    </para>

    <para>
      <programlisting>    *inc = 300;
      *(inc+1) = -300;
      *del = 1500;
      *(del+1) = 1500;
      plpat(2, inc, del);</programlisting>
    </para>

    <para>
      The routine &plpsty; can be used to select from 1 of 8 predefined
      patterns.
    </para>

    <para>
      The area fill routines also use the current line style, width and
      colors to give a virtually infinite number of different patterns.
    </para>

  </sect1>
  
  <sect1 id="color">
    <title>Setting Color</title>

    <para> Normally, color is used for all drivers and devices that support
    it within PLplot subject to the condition that the user has the option
    of globally turning off the color (and subsequently turning it on again
    if so desired) using &plscolor;. </para>

    <para> The PLplot color model allows the user to set the current
    color from a wide range of colors using two distinct color maps.
    Color map0 (discussed in <xref linkend="color-map-0"/>) has discrete
    colors with no particular order and is most suited to coloring the
    background, axes, lines, and labels, and color map1 (discussed in
    <xref linkend="color-map-1"/>) has continuously changing colors and is
    most suited to plots (see <xref linkend="contour-plots"/>) in which
    data values are represented by colors.  Setting the background color
    is a special case that is handled exclusively by color map 0 (as
    discussed in <xref linkend="color-map-0"/>).  The user can change the
    current color (as opposed to the background color) at any point in the
    plot by selecting any of the colors from either color map 0 or 1 using
    calls to &plcol0; or &plcol1;. When the current color is changed all
    subsequent drawing actions will utilize the new color until it is
    changed again.
</para>

    <sect2 id="color-map-0">
      <title>Color Map0</title>

      <para> Color map0 is most suited to coloring the background, axes,
      lines, and labels.  Generally, the default color map0 palette of 16
      colors is used. (<filename>examples/c/x02c.c</filename> illustrates
      these colors.) The default background color is taken from the index 0
      color which is black by default.  The default foreground color is red.
      </para>

      <para> There are a number of options for changing the default red on
      black colors.  The user may set the index 0 background color using the
      command-line <literal>bg</literal> parameter or by calling &plscolbg;
      (or &plscol0; with a 0 index) <emphasis>before</emphasis> &plinit;.
      During the course of the plot, the user can change the foreground color
      as often as desired using &plcol0; to select the index of the desired
      color. </para>

      <para> For more advanced use it is possible to define an arbitrary map0
      palette of colors. The user may set the number of colors in the map0
      palette using the command-line <literal>ncol0</literal> parameter or by
      calling &plscmap0n;.  &plscol0; sets the RGB value of the given index
      which must be less than the maximum number of colors (which is set by
      default, by command line, by &plscmap0n;, or even by &plscmap0;).
      Alternatively, &plscmap0; sets up the entire map0 color palette. For
      all these ways of defining the map0 palette any number of colors are
      allowed in any order, but it is not guaranteed that the individual
      drivers will actually be able to use more than 16 colors. </para>

    </sect2>
    <sect2 id="color-map-1">
      <title>Color Map1</title>

      <para> Color map1 is most suited to plots (see <xref
      linkend="contour-plots"/>) in which data values are represented by
      colors. The data are scaled to the input map1 range of floating point
      numbers between 0. and 1. which in turn are mapped (using &plcol1;) to
      colors using a default or user-specified map1 color transformation.  Thus,
      there are calls to &plcol1; from within the code for &plshade; (see
      <filename>src/plshade.c</filename>) and &plsurf3d; (see
      <filename>src/plot3d.c</filename>) to give a continuous range of
      color corresponding to the data being plotted. In addition &plcol1; can
      be used to specify the foreground color using the map1 continuous color
      palette (see the commented out section of
      <filename>examples/c/x12c.c</filename> which gives an example of this
      for a histogram), but normally &plcol0; is a better tool for this job
      (see <xref linkend="color-map-0"/>) since discrete colors often give
      a better-looking result. </para>

      <para> For more advanced use it is possible to define an arbitrary map1
      palette of colors. The user may set the number of colors in this palette
      using the command-line <literal>ncol1</literal> parameter or by calling
      &plscmap1n;.  Furthermore, &plscmap1l; can be used to set the map1 color
      palette using linear interpolation between control points specified in
      either RGB or HLS space.</para>

      <para> There is a one-to-one correspondence between RGB and HLS color
      spaces.  RGB space is characterized by three 8-bit unsigned integers
      corresponding to the intensity of the red, green, and blue colors. Thus,
      in hexadecimal notation with the 3 bytes concatenated together the RGB
      values of FF0000, FFFF00, 00FF00, 00FFFF, 0000FF, FF00FF, 000000, and
      FFFFFF correspond to red, yellow, green, cyan, blue, magenta, black, and
      white. </para>

      <para> HLS (hue, lightness, and saturation) space is often conceptually
      easier to use than RGB space.  One useful way to visualize HLS space is
      as a volume made up by two cones with their bases joined at the
      <quote>equator</quote>.  A given RGB point corresponds to HLS point
      somewhere on or inside the double cones, and vice versa. The hue
      corresponds to the <quote>longitude</quote> of the point with 0, 60,
      120, 180, 240, and 300 degrees corresponding to red, yellow, green,
      cyan, blue, and magenta. The lightness corresponds to the distance along
      the axis of the figure of a perpendicular dropped from the HLS point to
      the axis. This values ranges from 0 at the <quote>south pole</quote> to
      1 at the <quote>north pole</quote>.  The saturation corresponds to the
      distance of the HLS point from the axis with the on-axis value being 0
      and the surface value being 1. Full saturation corresponds to full color
      while reducing the saturation (moving toward the axis of the HLS figure)
      mixes more gray into the color until at zero saturation on the axis of
      the figure you have only shades of gray with the variation of lightness
      along the axis corresponding to a gray scale. </para>

      <para> Here are some C-code fragments which use &plscmap1l; to set the
      map1 color palette. This first example illustrates how to set up a
      gray-scale palette using linear interpolation in RGB space.

      <programlisting>    i[0] = 0.;
      i[1] = 1.;
      /* RGB are rescaled to the range from 0 to 1. for input to plscmap1l.*/
      r[0] = 0.;
      r[1] = 1.;
      g[0] = 0.;
      g[1] = 1.;
      b[0] = 0.;
      b[1] = 1.;
      plscmap1l(1, 2, i, r, g, b, NULL);</programlisting>
      </para>

      <para> This second example illustrates doing the same thing in HLS
      space.

      <programlisting>    i[0] = 0.;
      i[1] = 1.;
      /* Hue does not matter for zero saturation.*/
      h[0] = 0.;
      h[1] = 0.;
      /* Lightness varies through its full range.*/
      l[0] = 0.;
      l[1] = 1.;
      /* Saturation is zero for a gray scale.*/
      s[0] = 0.;
      s[1] = 0.;
      /* Note the first argument which specifies HLS space.*/
      plscmap1l(0, 2, i, h, l, s, NULL);</programlisting>
      </para>

      <para> This final example using &plscmap1l; illustrates how the default
      map1 color palette is set with just 4 control points (taken from
      <filename>src/plctrl.c</filename>).

      <programlisting>/*--------------------------------------------------------------------------*\
      * plcmap1_def()
      *
      * Initializes color map 1.
      *
      * The default initialization uses 4 control points in HLS space, the two
      * inner ones being very close to one of the vertices of the HLS double
      * cone.  The vertex used (black or white) is chosen to be the closer to
      * the background color.  If you don't like these settings you can always
      * initialize it yourself.
      \*--------------------------------------------------------------------------*/

      static void
      plcmap1_def(void)
      {
      PLFLT i[4], h[4], l[4], s[4], vertex = 0.;

      /* Positions of control points */

      i[0] = 0;		/* left boundary */
      i[1] = 0.45;	/* just before center */
      i[2] = 0.55;	/* just after center */
      i[3] = 1;		/* right boundary */

      /* For center control points, pick black or white, whichever is closer to bg */
      /* Be careful to pick just short of top or bottom else hue info is lost */

      if (plsc->cmap0 != NULL)
      vertex = ((float) plsc->cmap0[0].r +
      (float) plsc->cmap0[0].g +
      (float) plsc->cmap0[0].b) / 3. / 255.;

      if (vertex &lt; 0.5)
      vertex = 0.01;
      else
      vertex = 0.99;

      /* Set hue */

      h[0] = 260;		/* low: blue-violet */
      h[1] = 260;		/* only change as we go over vertex */
      h[2] = 0;		/* high: red */
      h[3] = 0;		/* keep fixed */

      /* Set lightness */

      l[0] = 0.5;		/* low */
      l[1] = vertex;	/* bg */
      l[2] = vertex;	/* bg */
      l[3] = 0.5;		/* high */

      /* Set saturation -- keep at maximum */

      s[0] = 1;
      s[1] = 1;
      s[2] = 1;
      s[3] = 1;

      c_plscmap1l(0, 4, i, h, l, s, NULL);
      }</programlisting> 
      </para>

      <para> Finally, &plscmap1; is an additional method of setting the map1
      color palette directly using RGB space.  No interpolation is used with
      &plscmap1; so it is the programmer's responsibility to make sure that
      the colors vary smoothly.  Here is an example of the method taken from
      <filename>examples/c/x08c.c</filename> which sets (yet again) the
      gray-scale color palette.

      <programlisting>    for (i=0;i&lt;n_col;i++)
      rr[i] = gg[i] = bb[i] = i*256/n_col;
      plscmap1(rr,gg,bb,n_col);</programlisting> 
      </para>

    </sect2>
  </sect1>
  
  <sect1 id="characters">
    <title>Setting Character Attributes</title>

    <para>
      Plplot uses two separate font systems to display characters. The
      traditional system uses Hershey fonts which are available for all
      device drivers, while the recently introduced unicode system is
      currently available only for the ps, psc, png, jpeg, and gif devices.
      For details on how to enable the unicode font system for additional
      device drivers using the FreeType library, see 
      <xref linkend="FreeType-notes"/>.
    </para>

    <sect2 id="hersheyfont">
      <title>Hershey fonts</title>

      <para>
	There are two Hershey font character sets included with PLplot.
	These are known
	as the standard and extended character sets.  The
	standard character set is a subset of the extended set.  It contains
	177 characters including the ascii characters in a normal style font,
	the Greek alphabet and several plotter symbols.  The extended
	character set contains almost 1000 characters, including four font
	styles, and several math, musical and plotter symbols.
      </para>

      <para>
	The extended character set is loaded into memory automatically when
	&plstar; or &plstart; is called.  The standard character set is
	loaded by calling &plfontld;.  The extended character set requires
	about 50 KBytes of memory, versus about 5 KBytes for the standard
	set.  &plfontld; can be used to switch between the extended and
	standard sets (one set is unloaded before the next is loaded).
	&plfontld; can be called before &plstar;.
      </para>

      <para>
	When the extended character set is loaded there are four different
	font styles to choose from.  In this case, the routine &plfont; sets
	up the default Hershey font for all character strings.  It may be overridden
	for any portion of a string by using an escape sequence within the
	text, as described below.  This routine has no effect when the
	standard font set is loaded.  The default font (1) is simple and
	fastest to draw; the others are useful for presentation plots on a
	high-resolution device.
      </para>

      <para>
	The font codes are interpreted as follows:

	<itemizedlist>
	  <listitem>
	    <para>
	      <literal>font = 1</literal>: normal (sans-serif) font
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <literal>font = 2</literal>: roman (serif) font
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <literal>font = 3</literal>: italic font
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <literal>font = 4</literal>: script font
	    </para>
	  </listitem>
	</itemizedlist>
      </para>
    </sect2>

    <sect2 id="unicodefont">
      <title>Unicode fonts</title>
      <para>
	The advantages of the unicode fonts over the more traditional PLplot
	Hershey fonts are the availability of many additional glyphs
	(including mathematical symbols and glyphs from other than
	western-European languages) and much better display of characters on
	computer screens using anti-aliasing and hinting.  Unicode fonts are
	obtained by specifying a command-line option of -drvopt text for
	the devices (currently ps, psc, png, jpeg, gif, and wingcc) 
	where it has been implemented.
      </para>
      <para>
	For the ps and psc devices, there is a fixed relationship between the
	FCI (font characterization integer, see <xref linkend="fci"/>) 
	and the actual Type 1
	fonts that are being used.  This fixed relationship is specified in
	the Type1Lookup array in include/plfci.h.  This array maps the
	font-family attributes of sans-serif, serif, monotype, script, and
	symbol to the standard postscript font families called Helvetica,
	Times-Roman, Courier, Times-Roman, and Symbol.  (There is no script
	font family amongst the 35 standard Type 1 postscript fonts so that is
	why we map the font-family attribute of script to Times-Roman.)
	Similarly, this array maps the font-style attributes of upright,
	italic or oblique and the font-weight attributes of medium or bold to
	the appropriate variety of the Helvetica, Times-Roman, Courier,
	and Symbol font families that are part of the 
	35 standard Type 1 postscript fonts.  These standard postscript fonts
	are normally installed on a user's system using the gsfonts package.
      </para>

      <para>
	For the devices handled by the FreeType library (currently png, jpeg,
	and gif) there is a configurable relationship between the FCI (font
	characterization integer, see <xref linkend="fci"/>) 
	and the TrueType fonts that are actually used.  
      </para>
      <para>
	The TrueType fonts corresponding to the 30 possible
	valid FCIs can be specified using cmake options. The defaults for the
        30 cmake variables PL_FREETYPE_FONT[_MODIFIER] (where FONT is one of 
        MONO, SANS, SCRIPT, SERIF or SYMBOL and the optional MODIFIER is one
	of BOLD, BOLD_ITALIC, BOLD_OBLIQUE, ITALIC or OBLIQUE) are documented 
	in cmake/modules/freetype.cmake. On Windows these defaults use standard
	Windows fonts. On all other platforms defaults
	are taken from fonts available from the ttf-freefont font
	package.  We recommend this font package because it has a rather
	complete set of glyphs for most unicode blocks.  (We also recommend
	the gucharmap application for determining other unicode font
	possibilities on your system that are available via the FreeType
	library.)
      </para>
      <para>
	For all systems, the 30 possible TrueType fonts can be specified at run
	time using the following environment variables:
	<itemizedlist>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SANS_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SERIF_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_MONO_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SCRIPT_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SYMBOL_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SANS_ITALIC_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SERIF_ITALIC_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_MONO_ITALIC_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SCRIPT_ITALIC_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SYMBOL_ITALIC_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SANS_OBLIQUE_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SERIF_OBLIQUE_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_MONO_OBLIQUE_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SCRIPT_OBLIQUE_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SYMBOL_OBLIQUE_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SANS_BOLD_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SERIF_BOLD_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_MONO_BOLD_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SCRIPT_BOLD_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SYMBOL_BOLD_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SANS_BOLD_ITALIC_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SERIF_BOLD_ITALIC_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_MONO_BOLD_ITALIC_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SCRIPT_BOLD_ITALIC_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SYMBOL_BOLD_ITALIC_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SANS_BOLD_OBLIQUE_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SERIF_BOLD_OBLIQUE_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_MONO_BOLD_OBLIQUE_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SCRIPT_BOLD_OBLIQUE_FONT
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PLPLOT_FREETYPE_SYMBOL_BOLD_OBLIQUE_FONT
	    </para>
	  </listitem>
	</itemizedlist>
	On Unix/Linux systems if these environment variables are not specified
	with an absolute path starting with "/", then the absolute path is
	specified by the cmake variable PL_FREETYPE_FONT_PATH or at
	run time with the environment variable PLPLOT_FREETYPE_FONT_DIR.
      </para>
    </sect2>

    <sect2 id="fci">
      <title>FCI</title>
      <para>
	We specify the properties of unicode fonts with the FCI (font
	characterization integer).  The FCI is a 32-bit unsigned integer whose
	most significant hexadecimal digit is marked with an 0x8 (0x80000000
	is ORed with the FCI value to mark it) to distinguish it from a unicode
	(UCS4) integer (whose maximum value 0x7fffffff). Users obtain the
	current FCI by calling &plgfci; and store a new FCI to be used at the
	start of each subsequent string using &plsfci;. Independent
	hexadecimal values within the FCI are characterized by the hexdigit
	and hexpower.  The hexpower is defined as the power of 16 or number of
	hexadecimal places to the left of the "decimal place" in the FCI 
	where the hexdigit is stored. The interpretation of the hexdigit and
	hexpower values in the FCI are given in <xref linkend="fci-table"/>.
      </para>
      <table frame="all" id="fci-table">
	<title>FCI interpretation</title>
	<tgroup cols="7" align="center">
	  <tbody valign="top">
	    <row>
	      <entry></entry>
	      <entry>hexdigit --&gt;</entry>
	      <entry>0</entry>
	      <entry>1</entry>
	      <entry>2</entry>
	      <entry>3</entry>
	      <entry>4</entry>
	    </row>
	    <row>
	      <entry>Font attribute</entry>
	      <entry>hexpower</entry>
	      <entry></entry>
	      <entry></entry>
	      <entry></entry>
	      <entry></entry>
	      <entry></entry>
	    </row>
	    <row>
	      <entry>font-family</entry>
	      <entry>0</entry>
	      <entry>sans-serif</entry>
	      <entry>serif</entry>
	      <entry>monospace</entry>
	      <entry>script</entry>
	      <entry>symbol</entry>
	    </row>
	    <row>
	      <entry>font-style</entry>
	      <entry>1</entry>
	      <entry>upright</entry>
	      <entry>italic</entry>
	      <entry>oblique</entry>
	      <entry></entry>
	      <entry></entry>
	    </row>
	    <row>
	      <entry>font-weight</entry>
	      <entry>2</entry>
	      <entry>medium</entry>
	      <entry>bold</entry>
	      <entry></entry>
	      <entry></entry>
	      <entry></entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>
      <para>
	Note the maximum value of hexdigit is 7 and the maximum value of
	hexpower is 6 so there is substantial room for expansion of this
	scheme.  On the other hand, since each font attribute is independent
	of the rest, what is implemented now gives us a maximum of 30
	different font possibilities which is probably more than enough for
	most plotting purposes.
      </para>
    </sect2>

    <sect2 id="escape-sequences">
      <title>Escape sequences in text</title>

      <para>
	The routines which draw text all allow you to include escape
	sequences in the text to be plotted.  These are character sequences
	that are interpreted as instructions to change fonts, draw
	superscripts and subscripts, draw non-ASCII (e.g. Greek), and so on.
	All escape sequences start with a number symbol
	(<literal>#</literal>) by default.  Some language interfaces have
	the capability of changing this default, but we will assume
	(<literal>#</literal>) in the remaining documentation of the escape
	sequences.
      </para>

      <para>
	The following escape sequences are defined:

	<itemizedlist>
	  <listitem>
	    <para>
	      <literal>#u</literal>: move up to the superscript position
	      (ended with <literal>#d</literal>)
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <literal>#d</literal>: move down to subscript position
	      (ended with <literal>#u</literal>)
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <literal>#b</literal>: backspace (to allow overprinting)
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <literal>##</literal>: number symbol
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <literal>#+</literal>: toggle overline mode
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <literal>#-</literal>: toggle underline mode
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <literal>#gx</literal>: Greek letter corresponding to Roman
	      letter <literal>x</literal> (see below)
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <literal>#fn</literal>: switch to normal (sans-serif) font
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <literal>#fr</literal>: switch to Roman (serif) font
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <literal>#fi</literal>: switch to italic font
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <literal>#fs</literal>: switch to script font
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <literal>#(nnn)</literal>: Hershey character nnn (1 to 4
	      decimal digits) 
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <literal>#[nnn]</literal>: unicode character nnn (nnn can
	      be decimal or hexadecimal [e.g., starting with 0x]) (UNICODE ONLY).
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <literal>#&lt;0x8nnnnnnn&gt;</literal>: absolute FCI to be used to
	      change fonts in mid-string.  (nnnnnnn must be exactly 7
	      digits). (UNICODE ONLY).
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <literal>#&lt;0xmn&gt;</literal>: change just one attribute
	      of the FCI in mid-string where m is the hexdigit and n is
	      the hexpower.  If more than two digits are given (so long
	      as the eighth digit does not mark this as an absolute FCI, see
	      above) they
	      are ignored. (UNICODE ONLY).
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <literal>#&lt;FCI COMMAND STRING/&gt;</literal>: the FCI COMMAND
	      STRING is currently one of "sans-serif", "serif", "monospace",
	      "script", "symbol", "upright", "italic", "oblique" "medium",
	      or "bold" (without the surrounding quotes).  These FCI
	      COMMAND STRINGS change one attribute of the FCI according to
	      their name. (UNICODE ONLY).
	    </para>
	  </listitem>
	</itemizedlist>
      </para>

      <para>
	Sections of text can have an underline or overline appended.  For
	example, the string S̅(f̲r̲e̲q̲) is obtained by specifying
	<literal>"#+S#+(#-freq#-)"</literal>. 
      </para>

      <para>
	Greek letters are obtained by <literal>#g</literal> followed by a
	Roman letter.  <xref linkend="greek"/> shows how these letters map
	into Greek characters.
      </para>

      <table frame="all" id="greek">
	<title>Roman Characters Corresponding to Greek Characters</title>
	<tgroup align="center" cols="13">
	  <colspec align="center" colnum="1" colwidth="2*"/>
	  <tbody valign="top">
	    <row>
	      <entry>Roman</entry>
	      <entry>A</entry>
	      <entry>B</entry>
	      <entry>G</entry>
	      <entry>D</entry>
	      <entry>E</entry>
	      <entry>Z</entry>
	      <entry>Y</entry>
	      <entry>H</entry>
	      <entry>I</entry>
	      <entry>K</entry>
	      <entry>L</entry>
	      <entry>M</entry>
	    </row>
	    <row>
	      <entry>Greek</entry>
	      <entry>&Alpha;</entry>
	      <entry>&Beta;</entry>
	      <entry>&Gamma;</entry>
	      <entry>&Delta;</entry>
	      <entry>&Epsilon;</entry>
	      <entry>&Zeta;</entry>
	      <entry>&Eta;</entry>
	      <entry>&Theta;</entry>
	      <entry>&Iota;</entry>
	      <entry>&Kappa;</entry>
	      <entry>&Lambda;</entry>
	      <entry>&Mu;</entry>
	    </row>
	  </tbody>
	</tgroup>
	<tgroup align="center" cols="13">
	  <colspec align="center" colnum="1" colwidth="2*"/>
	  <tbody>
	    <row>
	      <entry>Roman</entry>
	      <entry>N</entry>
	      <entry>C</entry>
	      <entry>O</entry>
	      <entry>P</entry>
	      <entry>R</entry>
	      <entry>S</entry>
	      <entry>T</entry>
	      <entry>U</entry>
	      <entry>F</entry>
	      <entry>X</entry>
	      <entry>Q</entry>
	      <entry>W</entry>
	    </row>
	    <row>
	      <entry>Greek</entry>
	      <entry>&Nu;</entry>
	      <entry>&Xi;</entry>
	      <entry>&Omicron;</entry>
	      <entry>&Pi;</entry>
	      <entry>&Rho;</entry>
	      <entry>&Sigma;</entry>
	      <entry>&Tau;</entry>
	      <entry>&Upsilon;</entry>
	      <entry>&Phi;</entry>
	      <entry>&Chi;</entry>
	      <entry>&Psi;</entry>
	      <entry>&Omega;</entry>
	    </row>
	  </tbody>
	</tgroup>
	<tgroup align="center" cols="13">
	  <colspec align="center" colnum="1" colwidth="2*"/>
	  <tbody>
	    <row>
	      <entry>Roman</entry>
	      <entry>a</entry>
	      <entry>b</entry>
	      <entry>g</entry>
	      <entry>d</entry>
	      <entry>e</entry>
	      <entry>z</entry>
	      <entry>y</entry>
	      <entry>h</entry>
	      <entry>i</entry>
	      <entry>k</entry>
	      <entry>l</entry>
	      <entry>m</entry>
	    </row>
	    <row>
	      <entry>Greek</entry>
	      <entry>&alpha;</entry>
	      <entry>&beta;</entry>
	      <entry>&gamma;</entry>
	      <entry>&delta;</entry>
	      <entry>&epsilon;</entry>
	      <entry>&zeta;</entry>
	      <entry>&eta;</entry>
	      <entry>&theta;</entry>
	      <entry>&iota;</entry>
	      <entry>&kappa;</entry>
	      <entry>&lambda;</entry>
	      <entry>&mu;</entry>
	    </row>
	  </tbody>
	</tgroup>
	<tgroup align="center" cols="13">
	  <colspec align="center" colnum="1" colwidth="2*"/>
	  <tbody>
	    <row>
	      <entry>Roman</entry>
	      <entry>n</entry>
	      <entry>c</entry>
	      <entry>o</entry>
	      <entry>p</entry>
	      <entry>r</entry>
	      <entry>s</entry>
	      <entry>t</entry>
	      <entry>u</entry>
	      <entry>f</entry>
	      <entry>x</entry>
	      <entry>q</entry>
	      <entry>w</entry>
	    </row>
	    <row>
	      <entry>Greek</entry>
	      <entry>&nu;</entry>
	      <entry>&xi;</entry>
	      <entry>&omicron;</entry>
	      <entry>&pi;</entry>
	      <entry>&rho;</entry>
	      <entry>&sigma;</entry>
	      <entry>&tau;</entry>
	      <entry>&upsilon;</entry>
	      <entry>&phi;</entry>
	      <entry>&chi;</entry>
	      <entry>&psi;</entry>
	      <entry>&omega;</entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>
      
      <para>
	The escape sequences <literal>#fn</literal>, <literal>#fr</literal>,
	<literal>#fi</literal>, <literal>#fs</literal>, and 
	<literal>#(nnn)</literal> are designed for the four Hershey fonts, but
	an effort has been made to allow some limited forward compatibility so
	these escape sequences have a reasonable result when unicode
	fonts are being used.  However, for maximum flexibility when using
	unicode fonts, these 5 escape sequences should be replaced by using
	the 4 escape sequences <literal>#[nnn]</literal>,
	<literal>#&lt;0x8nnnnnnn&gt;</literal>,
	<literal>#&lt;0xmn&gt;</literal>, or <literal>#&lt;FCI COMMAND
	STRING/&gt;</literal> as appropriate.
      </para>

      <para>
	It should be emphasized that the unicode escape sequences
	above only work properly for modern unicode-aware devices such as the
	svg device or the very large set of cairo and qt devices.  And for
	those devices the alternative of simply specifying the unicode symbols
	using UTF-8 encoding of PLplot input strings is much more convenient
	for users than using the above escape sequences.  For example, we
        use UTF-8 strings rather than escape sequences in example 24
	to render the word "Peace" in several different languages.
      </para>

      <table frame="all" id="peace">
	<title>The word "peace" expressed in several different languages in example 24 using UTF-8</title>
	<tgroup align="center" cols="2">
	  <colspec align="center" colnum="1" colwidth="2*"/>
	  <tbody valign="top">
	    <row>
	      <entry>Hebrew</entry>
	      <entry>שלום</entry>
	    </row>
	    <row>
	      <entry>French</entry>
	      <entry>Paix</entry>
	    </row>
	    <row>
	      <entry>Kurdish</entry>
	      <entry>Hasîtî</entry>
	    </row>
	    <row>
	      <entry>English</entry>
	      <entry>Peace</entry>
	    </row>
	    <row>
	      <entry>Korean</entry>
	      <entry>평화</entry>
	    </row>
	    <row>
	      <entry>Turkish</entry>
	      <entry>Barış</entry>
	    </row>
	    <row>
	      <entry>Hindi</entry>
	      <entry>शांति</entry>
	    </row>
	    <row>
	      <entry>German</entry>
	      <entry>Friede</entry>
	    </row>
	    <row>
	      <entry>Arabic</entry>
	      <entry>ﺳﻼم</entry>
	    </row>
	    <row>
	      <entry>Mandarin</entry>
	      <entry>和平</entry>
	    </row>
	    <row>
	      <entry>Russian</entry>
	      <entry>Мир</entry>
	    </row>
	    <row>
	      <entry>Spanish</entry>
	      <entry>Paz</entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>

      <para>
	For unicode-aware devices it is possible as well to specify
	mathematical glyphs (such as ∂, ∇, ∑, ∫, and ∰) using UTF-8 encoding
	of PLplot input strings.  A typical input method in this case is
	simply to cut and paste the desired mathematical glyph from, e.g.,
	gucharmap to source code being edited by a unicode-aware editor such
	as emacs.  Such input methods may be conveniently used, for example,
	to specify the very wide range of mathematical symbols that are
	typically desired for scentific plots.
      </para>

    </sect2>
    
    <sect2 id="character-size">
      <title>Character size adjustment</title>

      <para>
	The routine &plschr; is used to set up the size of subsequent
	characters drawn.  The actual height of a character is the product of
	the default character size and a scaling factor.  If no call is made
	to &plschr;, the default character size is set up depending on the
	number of subpages defined in the call to &plstar; or &plstart;, and
	the scale is set to 1.0.  Under normal circumstances, it is
	recommended that the user does not alter the default height, but
	simply use the scale parameter.  This can be done by calling &plschr;
	with <literal>def = 0.0</literal> and <literal>scale</literal> set to
	the desired multiple of the default height.  If the default height is
	to be changed, <literal>def</literal> is set to the new default
	height in millimeters, and the new character height is again set to
	<literal>def</literal> multiplied by <literal>scale</literal>.
      </para>

      <para>
	The routine &plssym; sets up the size of all subsequent characters drawn
	by calls to &plpoin; and &plsym;.  It operates analogously to
	&plschr; as described above.
      </para>

    </sect2>
  </sect1>

  <sect1 id="tri-d-plots">
    <title>Three Dimensional Surface Plots</title>

    <para>
      PLplot includes routines that will represent a single-valued function
      of two variables as a surface.  In this section, we shall assume that
      the function to be plotted is <literal>Z[X][Y]</literal>, where
      <literal>Z</literal> represents the dependent variable and
      <literal>X</literal> and <literal>Y</literal> represent the
      independent variables.
    </para>

    <para>
      As usual, we would like to refer to a three dimensional point
      <literal>(X, Y, Z)</literal> in terms of some meaningful
      user-specified coordinate system.  These are called
      <emphasis>three-dimensional world coordinates</emphasis>.  We need to
      specify the ranges of these coordinates, so that the entire surface is
      contained within the cuboid defined by <literal>xmin</literal> &lt;
      <literal>x</literal> &lt; <literal>xmax</literal>,
      <literal>ymin</literal> &lt; <literal>y</literal> &lt;
      <literal>ymax</literal>, and <literal>zmin</literal> &lt;
      <literal>z</literal> &lt; <literal>zmax</literal>.  Typically, we
      shall want to view the surface from a variety of angles, and to
      facilitate this, a two-stage mapping of the enclosing cuboid is
      performed.  Firstly, it is mapped into another cuboid called the
      <emphasis>normalized box</emphasis> whose size must also be specified
      by the user, and secondly this normalized box is viewed from a
      particular azimuth and elevation so that it can be projected onto the
      two-dimensional window.
    </para>

    <para>
      This two-stage transformation process allows considerable flexibility
      in specifying how the surface is depicted.  The lengths of the sides
      of the normalized box are independent of the world coordinate ranges
      of each of the variables, making it possible to use
      <quote>reasonable</quote> viewing angles even if the ranges of the
      world coordinates on the axes are very different.  The size of the
      normalized box is determined essentially by the size of the
      two-dimensional window into which it is to be mapped.  The normalized
      box is centered about the origin in the <literal>x</literal> and
      <literal>y</literal> directions, but rests on the plane <literal>z =
      0</literal>.  It is viewed by an observer located at altitude
      <literal>alt</literal> and azimuth <literal>az</literal>, where both
      angles are measured in degrees.  The altitude should be restricted to
      the range zero to ninety degrees for proper operation, and represents
      the viewing angle above the xy plane.  The azimuth is defined so that
      when <literal>az = 0</literal>, the observer sees the xz plane face
      on, and as the angle is increased, the observer moves clockwise
      around the box as viewed from above the xy plane.  The azimuth can
      take on any value.
    </para>

    <para>
      The first step in drawing a surface plot is to decide on the size of
      the two-dimensional window and the normalized box.  For example, we
      could choose the normalized box to have sides of length
    </para>

    <para>
      <programlisting>    basex = 2.0;
      basey = 4.0;
      height = 3.0;</programlisting>
    </para>

    <para>
      A reasonable range for the x coordinate of the two-dimensional window
      is -2.5 to +2.5, since the length of the diagonal across the base of
      the normalized box is
      sqrt(2<superscript>2</superscript>+4<superscript>2</superscript>) =
      2&nbsp;sqrt(5), which fits into this coordinate range.  A reasonable
      range for the y coordinate of the two dimensional window in this case
      is -2.5 to +4, as the the projection of the normalized box lies in
      this range for the allowed range of viewing angles.
    </para>

    <para>
      The routine &plwind; or &plenv; is used in the usual way to establish
      the size of the two-dimensional window.  The routine &plw3d; must
      then be called to establish the range of the three dimensional world
      coordinates, the size of the normalized box and the viewing angles.
      After calling &plw3d;, the actual surface is drawn by a call to
      &plot3d;.
    </para>

    <para>
      For example, if the three-dimensional world-coordinate ranges are
      -10.0 &leq; <literal>x</literal> &leq; 10.0, -3.0 &leq;
      <literal>y</literal> &leq; +7.0, and 0.0 &leq; <literal>z</literal>
      &leq; 8.0, we could use the following statements:
    </para>
    
    <para>
      <programlisting>    xmin2d = -2.5;
      xmax2d =  2.5;
      ymin2d = -2.5;
      ymax2d =  4.0;
      plenv(xmin2d, xmax2d, ymin2d, ymax2d, 0, -2);
      basex = 2.0;
      basey = 4.0;
      height = 3.0;
      xmin = -10.0;
      xmax = 10.0;
      ymin = -3.0;
      ymax = 7.0;
      zmin = 0.0;
      zmax = 8.0;
      alt = 45.0;
      az = 30.0;
      side = 1;
      plw3d(basex, basey, height, xmin, xmax, ymin, ymax, zmin, zmax, alt, az);
      plot3d(x, y, z, nx, ny, opt, side);</programlisting>
    </para>

    <para>
      The values of the function are stored in a two-dimensional array
      <literal>z[][]</literal> where the array element
      <literal>z[i][j]</literal> contains the value of the function at the
      point x<subscript>i</subscript>, y<subscript>j</subscript>.  (The
      two-dimensional array <literal>z</literal> is a vectored array
      instead of a fixed size array.  <literal>z</literal> points to an
      array of pointers which each point to a row of the matrix.)  Note
      that the values of the independent variables
      x<subscript>i</subscript> and y<subscript>j</subscript> do not need
      to be equally spaced, but they must lie on a rectangular grid.  Thus
      two further arrays <literal>x[nx]</literal> and
      <literal>y[ny]</literal> are required as arguments to &plot3d; to
      specify the values of the independent variables.  The values in the
      arrays x and y must be strictly increasing with the index.  The
      argument <literal>opt</literal> specifies how the surface is
      outlined.  If <literal>opt = 1</literal>, a line is drawn
      representing z as a function of x for each value of y, if
      <literal>opt = 2</literal>, a line is drawn representing z as a
      function of y for each value of x, and if <literal>opt = 3</literal>,
      a net of lines is drawn.  The first two options may be preferable if
      one of the independent variables is to be regarded as a parameter,
      whilst the third is better for getting an overall picture of the
      surface.  If side is equal to one then sides are drawn on the figure
      so that the graph doesn't appear to float.
    </para>

    <para>
      The routine &plmesh; is similar to &plot3d;, except that it is used
      for drawing mesh plots.  Mesh plots allow you to see both the top and
      bottom sides of a surface mesh, while 3D plots allow you to see the
      top side only (like looking at a solid object).  The side option is
      not available with &plmesh;.
    </para>

    <para>
      Labelling a three-dimensional or mesh plot is somewhat more
      complicated than a two dimensional plot due to the need for skewing
      the characters in the label so that they are parallel to the
      coordinate axes.  The routine &plbox3; thus combines the functions of
      box drawing and labelling.
    </para>
    
  </sect1>
  
  <sect1 id="contour-plots">
    <title>Contour and Shade Plots</title>
    
    <para>
      Several routines are available in PLplot which perform a contour or
      shade plot of data stored in a two-dimensional array.  The contourer
      uses a contour following algorithm so that it is possible to
      use non-continuous line styles.  Further, one may specify arbitrary
      coordinate mappings from array indices to world coordinates, such as
      for contours in a polar coordinate system.  In this case it is best
      to draw the distinction between the C and Fortran 95
      interfaces so these are handled in turn.
    </para>
    
    <sect2 id="contour-plots-c">
      <title>Contour Plots from C</title>

      <para>
	&plcont; is the routine callable from C for plotting contours.
	This routine has the form:
      </para>

      <para>
	<funcsynopsis>
	  <funcprototype>
	    <funcdef>
	      <function>plcont</function>
	    </funcdef>
	    <paramdef><parameter>z</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>
	where <literal>z</literal> is the two-dimensional array of size
	<literal>nx</literal> by <literal>ny</literal> containing samples
	of the function to be contoured.  (<literal>z</literal> is a
	vectored two-dimensional array as described in the previous
	section.  It is <emphasis>not</emphasis> a fixed-size
	two-dimensional array.) The parameters <literal>kx</literal>,
	<literal>lx</literal>, <literal>ky</literal> and
	<literal>ly</literal> specify the portion of <literal>z</literal>
	that is to be considered.  The array <literal>clevel</literal> of
	length <literal>nlevel</literal> is a list of the desired contour
	levels.
      </para>

      <para>
	The path of each contour is initially computed in terms of the
	values of the array indices which range from <literal>0</literal>
	to <literal>nx-1</literal> in the first index and from
	<literal>0</literal> to <literal>ny-1</literal> in the second
	index.  Before these can be drawn in the current window (see <xref
	linkend="windows"/>), it is necessary to convert from these array
	indices into world coordinates.  This is done by passing a pointer
	<literal>pltr</literal> to a user-defined transformation function 
	to &plcont;.  For C use of &plcont; (and &plshade;, see next subsection) 
	we have included directly in
	the PLplot library the following transformation routines:
	&pltr0; (identity transformation or you can
	enter a NULL argument to get the same effect); &pltr1;
	(linear interpolation in singly dimensioned coordinate arrays);
	and  &pltr2; (linear interpolation in doubly dimensioned coordinate
	arrays).  Examples of the use of these transformation 
	routines are given in <filename>examples/c/x09c.c</filename>,
	<filename>examples/c/x14c.c</filename>, and
	<filename>examples/c/x16c.c</filename>.  These same three examples
	also demonstrate a user-defined transformation function 
	<literal>mypltr</literal> which is capable of 
	arbitrary translation, rotation, and/or shear. By defining other
	transformation subroutines, it is possible to draw contours wrapped
	around polar grids etc.
      </para>

    </sect2>
    
    <sect2 id="shade-plots-c">
      <title>Shade Plots from C</title>
      <para>
	NEEDS DOCUMENTATION.  Follow the plshade and plshades usage in
	<filename>examples/c/x??c.c</filename>.
      </para>
    </sect2>
    
    <sect2 id="contour-plots-f95">
      <title>Contour Plots from the Fortran 95 interface</title>
      <para>
	NEEDS DOCUMENTATION.  Follow the plcont usage (with a variety
	of overloaded forms available with different arguments) in 
	<filename>examples/f95/x??f.f90</filename>.
      </para>
    </sect2>
    
    <sect2 id="shade-plots-f95">
      <title>Shade Plots from the Fortran 95 interface</title>
      <para>
	NEEDS DOCUMENTATION.  Follow the plshade and plshades usage 
	(with a variety
	of overloaded forms available with different arguments) in
	<filename>examples/f95/x??f.f90</filename>.
      </para>
    </sect2>
    
  </sect1>

  <sect1 id="legends">
    <title>Legends and color bars</title>
    <para>
      The &pllegend; and &plcolorbar; routines are available in PLplot to
      provide users with the capability of visually annotating their plots
      with a legend (a series of patterned boxes, lines, or symbols with
      associated explanatory UTF-8 text) or a color bar (an annotated
      subplot representing a continuous range of colors within the main
      plot and typically identifying certain colors with certain numerical
      values using an axis). &pllegend; is useful for visually annotating
      most two-dimensional plots.  See standard examples 4 and 26 for some
      examples.  &plcolorbar; is especially useful for annotating continuous
      shade plots generated by &plshades;.  See standard example 16 for an
      example.
    </para>

    <para>
      The &pllegend; and &plcolorbar; routines provide the users complete
      and convenient control of the size and position of the results on the
      plot and also return size data that makes it straightforward to stack
      different legend or colorbar results together on the plot (see
      standard example 33 for an example of this capability).  Furthermore,
      the &pllegend; and &plcolorbar; routines provide the user with many
      different style possibilities for the results.  Because of all these
      features, &pllegend; and &plcolorbar; have an extensive argument list.
      So we recommend first-time users of &pllegend; and &plcolorbar; use
      examples 4, 16, and 26 as a tutorial on how to use these PLplot
      capabilities in a simple way, and for more advanced use we recommend
      that users study the &pllegend; and &plcolorbar; documentation and
      also example 33 which attempts to exercise most capabilities of these
      two PLplot functions.
    </para>
  </sect1>
    
</chapter>
