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

Copyright (C) 1994  Geoffrey Furnish and Maurice LeBrun
Copyright (C) 1999-2017 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>We describe advanced use of PLplot in this chapter which
  includes many cross-references to elements of our <link
  linkend="API">common (C) API</link> that use PLplot C types such as
  &PLFLT; and &PLINT;.  For full documentation of all PLplot C types see
  <link linkend="plplot-types">here</link>.  The best way to learn how
  to use our common API for the language of your choice is to look at
  <ulink url="&PLplot-website;/examples.php">our standard set of
  examples</ulink>.  For additional language documentation you should
  consult the various chapters in <xref linkend="part_bindings"/> as
  well.</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>x00c -h</userinput>
Usage:
        examples/c/x00c [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/position specified as in X, e.g., 400x300, 400x300-100+200, +100-200, etc.
    -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,1,2,3=landscape,portrait,seascape,upside-down)
    -freeaspect          Allow aspect ratio to adjust to orientation swaps
    -portrait            Sets portrait mode (both orientation and aspect ratio)
    -width width         Sets pen width (0 &lt;= width)
    -bg color            Background color (FF0000=opaque red, 0000FF_0.1=blue with alpha of 0.1)
    -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 (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
    -cmap0 file name     Initializes color table 0 from a cmap0.pal format file in one of standard PLplot paths.
    -cmap1 file name     Initializes color table 1 from a cmap1.pal format file in one of standard PLplot paths.
    -locale              Use locale environment (e.g., LC_ALL, LC_NUMERIC, or LANG) to set LC_NUMERIC locale (which affects decimal point separator).
    -eofill              For the case where the boundary of the filled region is self-intersecting, use the even-odd fill rule rather than the default nonzero fill rule.
    -drvopt option[=value][,option[=value]]* Driver specific options
    -mfo PLplot metafile name Write the plot to the specified PLplot metafile
    -mfi PLplot metafile name Read the specified PLplot metafile

All parameters must be white-space delimited.  Some options are driver
dependent.  Please see the PLplot reference document for more detail.
      </screen>
    </para>

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

    <para>
      Some options 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="file-drivers"/> and <xref linkend="interactive-drivers"/>.
    </para>

  </sect1>

  <sect1 id="devices">
    <title>Devices</title>
    <para>
      PLplot implements a set of device drivers which support a wide
      variety of devices.  Each driver is required to implement a small set
      of low-level graphics primitives such as initialization, line draw,
      and page advance for each device it supports.  In addition a driver
      can implement higher-level features such as rendering unicode text.
      Thus a driver may be simple or complex depending on the driver
      capabilities that are implemented.
    </para>

    <para>
      The list of available devices is determined at configuration
      time by our CMake-based build system based on what device drivers are
      possible and what devices are enabled by default for a given platform.
      Most users just accept that default list of devices, but it is also
      possible for users to modify the list of enabled devices in any way
      they like.  For example, they could use
      <literal>-DPLD_svg=OFF</literal> to exclude just the svg device from
      the default list; they could use <literal>-DDEFAULT_NO_DEVICES=ON
      -DPLD_svg=ON</literal> to enable just the svg device (say if they were
      interested just in that device and they wanted to save some
      configuration and build time); or they could use
      <literal>-DDEFAULT_ALL_DEVICES=ON -DPLD_svg=OFF</literal> to enable
      all devices other than svg.  Note, however, extreme caution should be
      used with <literal>-DDEFAULT_ALL_DEVICES=ON</literal> since the result
      is often one of the "disabled by default" devices below gets enabled
      which is almost always problematic since those devices are typically
      unmaintained, deprecated, or just being developed which means they
      might not even build or if they do build, they might not run properly.
    </para>

    <para>
      Most PLplot devices can be classified as either &features-noninteractive; file devices
      or &features-interactive; devices.  The available file devices are tabulated in <xref
      linkend="tab_dev1"/> while the available interactive devices are
      tabulated in <xref linkend="tab_dev2"/>.

      <table frame="none" id="tab_dev1">
	<title>PLplot File Devices</title>
	<tgroup cols="4" align="center" colsep="1" rowsep="1">
	  <colspec colwidth="1*"/>
	  <colspec colwidth="1*"/>
	  <colspec colwidth="1*"/>
	  <colspec colwidth="1*"/>
	  <thead>
	    <row><entry>Description</entry><entry>Keyword</entry><entry>Source code</entry><entry>Default?</entry></row>
	  </thead>
	  <tbody>
	    <row><entry>PDF (cairo)</entry><entry>pdfcairo</entry><entry>cairo.c</entry><entry>Yes</entry></row>
	    <row><entry>PNG (cairo)</entry><entry>pngcairo</entry><entry>cairo.c</entry><entry>Yes</entry></row>
	    <row><entry>PostScript (cairo)</entry><entry>pscairo</entry><entry>cairo.c</entry><entry>Yes</entry></row>
	    <row><entry>Encapsulated PostScript (cairo)</entry><entry>epscairo</entry><entry>cairo.c</entry><entry>Yes</entry></row>
	    <row><entry>SVG (cairo)</entry><entry>epscairo</entry><entry>cairo.c</entry><entry>Yes</entry></row>
	    <row><entry>CGM</entry><entry>cgm</entry><entry>cgm.c</entry><entry>No</entry></row>
	    <row><entry>Encapsulated PostScript (Qt)</entry><entry>epsqt</entry><entry>qt.cpp</entry><entry>Yes</entry></row>
	    <row><entry>PDF (Qt)</entry><entry>pdfqt</entry><entry>qt.cpp</entry><entry>Yes</entry></row>
	    <row><entry>BMP (Qt)</entry><entry>bmpqt</entry><entry>qt.cpp</entry><entry>Yes</entry></row>
	    <row><entry>JPEG (Qt)</entry><entry>jpgqt</entry><entry>qt.cpp</entry><entry>Yes</entry></row>
	    <row><entry>PNG (Qt)</entry><entry>pngqt</entry><entry>qt.cpp</entry><entry>Yes</entry></row>
	    <row><entry>PPM (Qt)</entry><entry>ppmqt</entry><entry>qt.cpp</entry><entry>Yes</entry></row>
	    <row><entry>TIFF (Qt)</entry><entry>tiffqt</entry><entry>qt.cpp</entry><entry>Yes</entry></row>
	    <row><entry>SVG (Qt)</entry><entry>svgqt</entry><entry>qt.cpp</entry><entry>Yes</entry></row>
	    <row><entry>PNG (GD)</entry><entry>png</entry><entry>gd.c</entry><entry>No</entry></row>
	    <row><entry>JPEG (GD)</entry><entry>jpeg</entry><entry>gd.c</entry><entry>No</entry></row>
	    <row><entry>GIF (GD)</entry><entry>gif</entry><entry>gd.c</entry><entry>No</entry></row>
	    <row><entry>PDF (Haru)</entry><entry>pdf</entry><entry>pdf.c</entry><entry>Yes</entry></row>
	    <row><entry>PLplot Native Meta-File</entry><entry>plmeta</entry><entry>plmeta.c</entry><entry>No</entry></row>
	    <row><entry>PostScript (monochrome)</entry><entry>ps</entry><entry>ps.c</entry><entry>Yes</entry></row>
	    <row><entry>PostScript (color)</entry><entry>psc</entry><entry>ps.c</entry><entry>Yes</entry></row>
	    <row><entry>PostScript (monochrome), (LASi)</entry><entry>psttf</entry><entry>psttf.cc</entry><entry>Yes</entry></row>
	    <row><entry>PostScript (color), (LASi)</entry><entry>psttfc</entry><entry>psttf.cc.c</entry><entry>Yes</entry></row>
	    <row><entry>SVG</entry><entry>svg</entry><entry>svg.c</entry><entry>Yes</entry></row>
	    <row><entry>XFig</entry><entry>xfig</entry><entry>xfig.c</entry></row>
	  </tbody>
	</tgroup>
      </table>
      <table frame="none" id="tab_dev2">
	<title>PLplot Interactive Devices</title>
	<tgroup cols="4" align="center" colsep="1" rowsep="1">
	  <colspec colwidth="1*"/>
	  <colspec colwidth="1*"/>
	  <colspec colwidth="1*"/>
	  <colspec colwidth="1*"/>
	  <thead>
	    <row><entry>Device</entry><entry>Keyword</entry><entry>Source Code</entry><entry>Default?</entry></row>
	  </thead>
	  <tbody>
	    <row><entry>Aquaterm</entry><entry>aqt</entry><entry>aqt.c</entry><entry>Yes</entry></row>
	    <row><entry>X (cairo)</entry><entry>xcairo</entry><entry>cairo.c</entry><entry>Yes</entry></row>
	    <row><entry>Windows (cairo)</entry><entry>wincairo</entry><entry>cairo.c</entry><entry>Yes</entry></row>
	    <row><entry>X or Windows (Qt)</entry><entry>qtwidget</entry><entry>qt.cpp</entry><entry>Yes</entry></row>
	    <row><entry>X</entry><entry>xwin</entry><entry>xwin.c</entry><entry>Yes</entry></row>
	    <row><entry>Tcl/Tk </entry><entry>tk</entry><entry>tk.c</entry><entry>Yes</entry></row>
	    <row><entry>New Tcl/Tk</entry><entry>ntk</entry><entry>ntk.c</entry><entry>Yes</entry></row>
	    <row><entry>Windows</entry><entry>wingcc</entry><entry>wingcc.c</entry><entry>Yes</entry></row>
	    <row><entry>wxWidgets</entry><entry>wxwidgets</entry><entry>wxwidgets*.cpp</entry><entry></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="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.
      </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 an svg output file with name
      <filename>test-%n.svg</filename>, the files actually created will be
      <filename>test-1.svg</filename>, <filename>test-2.svg</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
      <filename>test.svg.1</filename>, <filename>test.svg.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.
      </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> ps         PostScript File (monochrome)
	  &lt; 4> psc        PostScript File (color)
	  &lt; 5> xfig       Fig file
	  &lt; 6> null       Null device
	  &lt; 7> ntk        New tk driver
	  &lt; 8> tkwin      New tk driver
	  &lt; 9> mem        User-supplied memory device
	  &lt;10> wxwidgets  wxWidgets Driver
	  &lt;11> psttf      PostScript File (monochrome)
	  &lt;12> psttfc     PostScript File (color)
	  &lt;13> svg        Scalable Vector Graphics (SVG 1.1)
	  &lt;14> pdf        Portable Document Format PDF
	  &lt;15> bmpqt      Qt Windows bitmap driver
	  &lt;16> jpgqt      Qt jpg driver
	  &lt;17> pngqt      Qt png driver
	  &lt;18> ppmqt      Qt ppm driver
	  &lt;19> tiffqt     Qt tiff driver
	  &lt;20> svgqt      Qt SVG driver
	  &lt;21> qtwidget   Qt Widget
	  &lt;22> epsqt      Qt EPS driver
	  &lt;23> pdfqt      Qt PDF driver
	  &lt;24> extqt      External Qt driver
	  &lt;25> memqt      Memory Qt driver
	  &lt;26> xcairo     Cairo X Windows Driver
	  &lt;27> pdfcairo   Cairo PDF Driver
	  &lt;28> pscairo    Cairo PS Driver
	  &lt;29> epscairo   Cairo EPS Driver
	  &lt;30> svgcairo   Cairo SVG Driver
	  &lt;31> pngcairo   Cairo PNG Driver
	  &lt;32> memcairo   Cairo Memory Driver
	  &lt;33> extcairo   Cairo External Context Driver

	  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
	<ulink url="&PLplot-website;/examples.php">our standard examples</ulink>
	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.  For any of our supported languages
	<ulink url="&PLplot-website;/examples.php?demo=14">our standard
	example 14</ulink> demonstrates of how to use multiple output streams
	where the same device is used for both streams, but, of course,
	different devices can be used for different streams as well.
      </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>N.B. this FreeType approach is officially deprecated
    because of its inherent font-selection issues (fonts must be specified
    by filename) and because it only supports left-to-right layout (i.e.,
    there is no support for complex text layout languages).  Specialized
    libraries or system services that automatically find the best system
    font to render the given (unicode) glyph and which support complex
    text layout should be used instead.  Those possibilities include
    <ulink url="https://www.qt.io/">Qt</ulink> (available on all platforms
    and used by our qt device driver), the pango/cairo subset of the
    <ulink url="https://www.gtk.org/">GTK+ suite of libraries</ulink>
    (available on all platforms and used directly by our cairo device
    driver and indirectly by our psttf device driver), <ulink
    url="https://en.wikipedia.org/wiki/Uniscribe">Uniscribe</ulink>
    (available only on Windows for Windows 2000 and later), and <ulink
    url="https://en.wikipedia.org/wiki/DirectWrite">DirectWrite</ulink>
    (available only on Windows for Windows 7 and later).  Currently the
    wingcc and gd device drivers are the only ones that depend on the
    FreeType approach described here.  Because of the limitations of this
    approach we have plans to update wingcc to use either Uniscribe or
    DirectWrite, and once those plans are realized we will likely retire
    the gd device driver (currently deprecated because of the limitations
    of the current approach) and also retire this Freetype
    approach.</para>
  </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>
	The routines &plvpor;, &plsvpa;, &plvasp;, &plvpas;, and
	&plvsta; may be used to specify the limits of the viewport within the
	current subpage.  The &plvpor; routine specifies the viewport limits
	in normalized subpage coordinates. The &plsvpa; routine (often used in
	conjunction with the &plgspa; routine which returns the physical
	limits of the current subpage) specifies the viewport limits in
	physical coordinates.  The routine &plvasp; specifies the largest
	viewport with the given aspect ratio that fits in the current subpage
	while allowing for a standard margins on each side of the viewport.
	The routine &plvpas; specifies the largest viewport with the given
	aspect ratio that fits in a region that is specified by normalized
	subpage coordinates as with &plvpor;.  (The routine &plvpas;
	is functionally equivalent to &plvpor; when the specified aspect ratio
	is set to zero.)  The &plvsta; routine specifies the largest viewport
	that fits in the current subpage while allowing for a standard margins
	on each side of the viewport.  This standard viewport is that used by
	&plenv; (See <xref linkend="standard-window"/>).
      </para>
    </sect2>

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

      <para>
	The routine &plwind; is used to map the world coordinate
	rectangle into the viewport rectangle.  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 viewport.
      </para>
    </sect2>

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

      <para>
	The routine &plbox; is used to specify how much (if any) of
	the frame is drawn around the viewport and to control the positions of
	the axis subdivisions and numeric labels.  In addition, non-default
	lengths of major and minor ticks on the axes may be set up by calls to
	the routines &plsmaj; and &plsmin;.
      </para>

      <para>
	The routine &pllab; is used to specify 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.
      </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
	cumbersome for drawing simple graphs so as an alternative we have
	implemented &plenv; that combines all four of these capabilities in
	one routine using the standard viewport and a limited subset of the
	capabilities of &plbox;.
      </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 vectors (dropped for the
      redacted API) and integer <parameter>mark</parameter> and
      <parameter>space</parameter> vectors which contain 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 <parameter>mark</parameter>
      vector elements of 4000 and 2000, and <parameter>space</parameter>
      vector elements of 1500 and 1500.  To return to a continuous line,
      just call &plstyl; with vectors with no elements.  You can also use
      &pllsty; to choose between 8 different predefined line styles.
    </para>
  </sect1>

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

    <para>The routine &plpsty; may be used to select either a solid
    fill or from 1 of 8 predefined area line fill patterns. Additional
    area line fill patterns using one or two sets of parallel lines at
    arbitrary inclinations and spacings can be specified with the routine
    &plpat; The (redacted) arguments to this routine are the integer
    <parameter>inc</parameter> and <parameter>del</parameter> vectors
    specifying the inclinations in tenths of a degree and the spacing in
    micrometers of the pattern(s).  Thus to specify an area line fill
    pattern consisting of horizontal lines spaced 2&nbsp;mm apart the
    <parameter>inc</parameter> vector should have single element set to 0,
    and the <parameter>del</parameter> vector should have a single element
    set to 2000.  And to specify an area line fill pattern consisting of a
    symmetrical crosshatch with lines directed 30 degrees above and below
    the horizontal and spaced 1.5&nbsp;mm apart, the
    <parameter>inc</parameter> vector should contain the elements 300 and
    -300, and the <parameter>del</parameter> vector should contain the
    elements 1500 and 1500.</para>

    <para>N.B. Solid fills use the current (semitransparent) color
    and line fills use the current line style, width, and
    (semitransparent) color.  The result is PLplot users have a large
    choice of different fill 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 (called cmap0 and discussed in <xref
    linkend="color-map-0"/>) has discrete colors arranged in no particular
    order with regard to color index and is most suited to coloring
    discrete elements of the plot.  Color map1 (called cmap1 and discussed
    in <xref linkend="color-map-1"/>) has colors which are a continuous
    function of color index and is most suited to coloring continuous
    elements of the plot. The user can change the current color (as
    opposed to the background color which is a special case that is
    discussed in <xref linkend="color-map-0"/>) at any point in the PLplot
    commands that are used to create a given plot by selecting any of the
    colors from either cmap0 or cmap1 using calls to &plcol0; or
    &plcol1;. When the current color is changed all subsequent drawing
    actions will utilize that 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 discrete elements of
      the plot such as the background, axes, lines, and labels.  The cmap0
      palette colors are stored using <ulink
      url="https://en.wikipedia.org/wiki/RGBA_color_space">RGBA</ulink>
      (i.e., red, green, blue, and alpha transparency) components (although
      some drivers ignore the alpha transparency data and simply render
      opaque colors corresponding to the semitransparent ones).  In the
      discussion that follows all references to cmap0 API functions with a
      trailing "a" in their names (e.g., &plscol0a;) refers to setting RGBA
      semitransparent colors while the equivalent function (e.g., &plscol0;)
      without the trailing "a" in the name refers to setting RGB colors with
      an assumed opaque alpha transparency of 1.0.</para>

      <para>Page 1 of <ulink
      url="&PLplot-website;/examples.php?demo=02">our standard example
      02</ulink> illustrates the default 16 colors in the cmap0 palette.
      The background color is a special case to be discussed below, and the
      current color of discrete elements of the plot other than the
      background may be specified by cmap0 index (or cmap1 index, see <xref
      linkend="color-map-1"/>).  The cmap0 index is 1 by default (and
      corresponds to opaque red for the default cmap0 palette), but during
      the course of plotting a page, the user can change that current color
      as often as desired using &plcol0; to select the desired cmap0 color
      index from the cmap0 color palette in existence at the time.</para>

      <para>The advanced cmap0 use case includes a number of methods
      for changing the cmap0 color palette.  It is possible to update one
      index of the cmap0 palette using &plscol0a; or &plscol0;, define a
      complete cmap0 palette with an arbitrary number of colors using
      &plscmap0a; or &plscmap0;, or read in a complete cmap0 palette from a
      special cmap0 palette file with the command-line
      <literal>cmap0</literal> parameter or by calling &plspal0;.  Our
      standard examples <ulink
      url="&PLplot-website;/examples.php?demo=04">04</ulink>, <ulink
      url="&PLplot-website;/examples.php?demo=19">19</ulink>, <ulink
      url="&PLplot-website;/examples.php?demo=26">26</ulink>, <ulink
      url="&PLplot-website;/examples.php?demo=30">30</ulink>, <ulink
      url="&PLplot-website;/examples.php?demo=31">31</ulink>, and <ulink
      url="&PLplot-website;/examples.php?demo=33">33</ulink> illustrate how
      to use &plscol0a; and &plscol0;.  Our standard examples <ulink
      url="&PLplot-website;/examples.php?demo=02">02</ulink>, <ulink
      url="&PLplot-website;/examples.php?demo=24">24</ulink>, and <ulink
      url="&PLplot-website;/examples.php?demo=30">30</ulink> illustrate how
      to use &plscmap0a; and &plscmap0;.  Although the user can define and
      use any cmap0 palette file they like, predefined cmap0 palette files
      are given in <filename>data/cmap0*.pal</filename> within the source
      tree and installed in
      <filename>&lt;install-prefix&gt;/share/plplot&Project-Version;/cmap0*.pal</filename>
      in the install tree.  By default the cmap0 palette is set using the
      predefined <filename>cmap0_default.pal</filename> file, but <ulink
      url="&PLplot-website;/examples.php?demo=16">our standard example
      16</ulink> demonstrates use of a number of our other predefined cmap0
      palette files in the various pages of that example.  Many of the above
      commands indirectly set the number of cmap0 colors, but it is also
      possible for the user to specify that number directly with the
      command-line <literal>ncol0</literal> parameter or by calling
      &plscmap0n;. For all methods of defining the cmap0 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
      (although most drivers do support more than 16 colors).</para>

      <para>The background color (which always corresponds to index 0
      of the cmap0 palette) is a special case that must be discussed
      separately.  The default cmap0 palette index 0 corresponds to opaque
      black so by default the background is that color.  However, the user
      may set that background color to something else by using the
      command-line <literal>bg</literal> parameter, by calling &plscolbga;
      or &plscolbg;, or by calling &plscol0a; or &plscol0; with a 0 index.
      In addition, the background color is implicitly set when the whole
      cmap0 color palette (including index 0) is changed with one of the
      methods above.  However, since the background is painted at the start
      of each page any of these methods of changing the background color
      must be done <emphasis>before</emphasis> that page start.  Note that
      although our long-term goal is for each device driver that honors
      semitransparent colors will also honor semitransparent background
      requests from users the current status is only a few drivers (e.g.,
      the svg device driver) do that and the rest fall back to replacing the
      requested semitransparent background with the equivalent opaque
      background.</para>

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

      <para>Color map1 is most suited to coloring elements of plots in
      which continuous data values are represented by a continuous range of
      colors.  The cmap1 palette colors are stored using <ulink
      url="https://en.wikipedia.org/wiki/RGBA_color_space">RGBA</ulink>
      (i.e., red, green, blue, and alpha transparency) components (although
      some drivers ignore the alpha transparency data and simply render the
      opaque colors corresponding to the requested semitransparent color).
      In the discussion that follows all references to cmap1 API functions
      with a trailing "a" in their names (e.g., &plscmap1la;) refers to
      setting RGBA semitransparent colors, while the equivalent function
      (e.g., &plscmap1l;) without the trailing "a" in the name refers to
      setting RGB colors with an assumed opaque alpha transparency of 1.0.
      The cmap1 index is a floating-point number whose default range is
      0.0-1.0, but to set and get that range use &plscmap1_range; and
      &plgcmap1_range;.</para>

      <para>Page 4 of <ulink
      url="&PLplot-website;/examples.php?demo=16">our standard example
      16</ulink> illustrates use of our default cmap1 palette to represent
      continuous data values as a continuous range of colors using
      &plshades;.  For this case and also other PLplot API (e.g.,
      &plsurf3d;) where continuous data are being plotted, the range of
      continuous data are scaled to the cmap1 color index range which in
      turn are mapped internally using &plcol1; to continuous colors using
      the cmap1 color palette.  In addition, during the course of plotting a
      page, the user can change the current color used for discrete objects
      as often as desired by directly calling &plcol1; to select the desired
      cmap1 color index from the cmap1 color palette in existence at the
      time.  However, use of &plcol0; and the cmap0 palette (see <xref
      linkend="color-map-0"/>) to set the current color for discrete objects
      is more usual.</para>

      <para>The advanced cmap1 use case includes a number of methods
      of changing the cmap1 palette.  It is possible to define a complete
      cmap1 palette by using &plscmap1la; or &plscmap1l; (where linear
      interpolation between control points of given alpha transparency and
      either RGB or HLS color assures the palette is a continuous function
      of its index); by using &plscmap1a; or &plscmap1; (where it is the
      user's responsibility to makes sure that palette is a continuous
      function of its index); or by reading in a complete cmap1 palette from
      a special cmap1 palette file with the command-line
      <literal>cmap1</literal> parameter or by calling &plspal1;.  Our
      standard examples <ulink
      url="&PLplot-website;/examples.php?demo=08">08</ulink>, <ulink
      url="&PLplot-website;/examples.php?demo=11">11</ulink>, <ulink
      url="&PLplot-website;/examples.php?demo=12">12</ulink>, <ulink
      url="&PLplot-website;/examples.php?demo=15">15</ulink>, <ulink
      url="&PLplot-website;/examples.php?demo=20">20</ulink>, <ulink
      url="&PLplot-website;/examples.php?demo=21">21</ulink>, and <ulink
      url="&PLplot-website;/examples.php?demo=30">30</ulink> illustrate how
      to use &plscmap1la; and &plscmap1l;.  Our standard example <ulink
      url="&PLplot-website;/examples.php?demo=31">31</ulink> illustrates how
      to use &plscmap1a; and &plscmap1; (which are rarely used because of
      the continuity concern).  Although the user can define and use any
      cmap1 palette file they like, predefined cmap1 palette files are given
      in <filename>data/cmap1*.pal</filename> within the source tree and
      installed in
      <filename>&lt;install-prefix&gt;/share/plplot&Project-Version;/cmap1*.pal</filename>
      in the install tree.  By default the cmap1 palette is set using the
      predefined <filename>cmap1_default.pal</filename> file, but <ulink
      url="&PLplot-website;/examples.php?demo=16">our standard example
      16</ulink> demonstrates use of a number of our other predefined cmap1
      palette files in the various pages of that example.  The default
      number of cmap1 colors is 128 which supplies sufficient sampling of
      the continuous cmap1 palette for most purposes, but that number can be
      set to other values with the command-line <literal>ncol1</literal>
      parameter or by calling &plscmap1n;.  (That number is also updated by
      calls to the rarely used &plscmap1a; or &plscmap1;.)</para>

      <para>There is a one-to-one correspondence between <ulink
      url="https://en.wikipedia.org/wiki/RGB_color_model">RGB</ulink> and
      <ulink url="https://en.wikipedia.org/wiki/HLS_color_space">HLS</ulink>
      color spaces.  Plplot provides &plrgbhls; to convert from RGB to HLS
      and &plhlsrgb; to convert from HLS to RGB.</para>

      <para>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>
    </sect2>
  </sect1>

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

    <para>
      Plplot uses two separate font systems to display characters. The
      Hershey font system gives access to Hershey fonts that come with
      PLplot.  All of our older devices and most of our modern devices allow
      use of the Hershey font system.  The unicode font system gives access
      to unicode-aware system fonts.  Some of our older devices and most of
      our modern devices allow use of the unicode font system.  The
      advantages of the unicode font system over the Hershey font system are
      discussed in <xref linkend="unicodefont"/>.
    </para>

    <sect2 id="hersheyfont">
      <title>Hershey font system</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 PLplot is initialized.  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 in <xref
	linkend="escape-sequences"/>.  For the Hershey font
	system (but not the unicode font system, see below) this routine has
	no practical 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 font system</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); support of complex text layout languages
	for a substantial subset (see <xref linkend="svg_device_driver"/> and
	<xref linkend="psttf_cairo_qt_wxwidgets_device_drivers"/>) of the
	devices that support the Unicode font system; and much better display
	of characters on computer screens using anti-aliasing and hinting.
      </para>
      <para>
	The unicode font system can use font specification methods
	that were designed for the Hershey fonts to specify the unicode font.
	For this case &plfont; internally calls &plsfci; using four different
	FCI values to choose unicode font attributes similar to the 4 kinds of
	Hershey fonts, and the corresponding Hershey text escape-sequences
	(see <xref linkend="escape-sequences"/>) designed to override the
	Hershey font selection are treated similarly.  However, for the
	unicode font system the preferred and much more flexible methods of
	specifying the unicode font are calling the &plsfci;
	routine, calling the &plsfont; routine which provides a
	user-friendly interface to &plsfci;, or using unicode text
	escape-sequences to override unicode font attributes in the middle of
	strings (see <xref linkend="fci"/>).
      </para>

      <sect3 id="ps_device_driver">
	<title>The ps device driver</title>
	<para>
	  The ps and psc devices that are implemented with the ps
	  device driver are only unicode-aware in a technical sense because they
	  use a fixed relationship between the FCI (font characterization
	  integer, see <xref linkend="fci"/>) and the actual Type 1 system fonts
	  that are being used which unlike typical TTF system fonts have
	  extremely limited glyphs available. This fixed relationship is
	  specified in the Type1Lookup array in include/plfci.h.  This array
	  maps the FCI 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 FCI font-style
	  attributes of upright, italic or oblique and the FCI 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 fonts are
	  normally available on all platforms (e.g., with the gsfonts package on
	  Linux systems).
	</para>
      </sect3>

      <sect3 id="gd_wingcc_device_drivers">
	<title>The gd and wingcc device drivers</title>
	<para>
	  For the png, jpeg, and gif devices (implemented with the gd
	  device driver) and the wingcc device (implemented with the wingcc
	  device driver), the deprecated plfreetype approach is used for accessing
	  unicode-aware system fonts.  This approach is deprecated because of its
	  two major drawbacks.  (1)
	  text layout is only left-to-right so that complex text layout
	  languages (such as those used in <ulink
	  url="&PLplot-website;/examples.php?demo=24">our standard example
	  24</ulink>) are not correctly rendered.  (2) System fonts are only
	  accessed by file name rather than using the fontconfig approach or
	  something similar to select the best system font to render the given
	  unicode glyph.  Because of this latter drawback a configurable
	  relationship must be established between the FCI (font
	  characterization integer, see <xref linkend="fci"/>) and the TrueType
	  font name that is actually used for rendering a unicode glyph.  This
	  can be a considerable inconvenience for the user if they want to
	  specify anything other than a default set of font names.
	</para>
	<para>
	  The TrueType font names 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 font files. On all other platforms default font file names
	  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 platforms, the 30 possible TrueType font files 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>
      </sect3>
      <sect3 id="svg_device_driver">
	<title>The svg device driver</title>
	<para>
	  The svg device (which is implemented with the svg device
	  driver) is a device that implements the unicode font method by mapping
	  FCI attributes (see <xref linkend="fci"/>) to corresponding
	  combinations of the SVG attributes font-family, font-style, and
	  font-weight.  Since these attributes are generic ones, (e.g., FCI
	  font-family "sans-serif", "serif", "monospace", "script", and "symbol"
	  correspond to SVG font-family "sans-serif", "serif", "mono-space",
	  "cursive", and "sans-serif") the SVG viewer applications that render
	  the SVG files produced by the svg device have a large degree of
	  freedom within these generic guidelines for choosing which system font
	  to use to render a given unicode glyph.  Note that unlike devices that
	  use the plfreetype approach (see <xref
	  linkend="gd_wingcc_device_drivers"/>) this device requires no user
	  intervention to set up the correct mapping between FCI and font, and
	  complex text layout languages are rendered correctly (assuming the SVG
	  viewer does that).
	</para>
      </sect3>
      <sect3 id="psttf_cairo_qt_wxwidgets_device_drivers">
	<title>The psttf, cairo, qt, and wxwidgets device drivers</title>
	<para>
	  The large number of unicode-aware devices that are implemented by the
	  psttf, cairo, qt, and wxwidgets device drivers implement the unicode
	  font method using PLplot FCI values (see <xref linkend="fci"/>) to
	  characterize the generic fonts that are needed by the associated
	  libLASi (psttf), pango/cairo (cairo), Qt (qt), and wxWidgets
	  (wxwidgets) library dependencies of these device drivers. Note that
	  unlike devices that use the plfreetype approach (see <xref
	  linkend="gd_wingcc_device_drivers"/>) these devices require no
	  user intervention to set up the correct mapping between FCI and font, and
	  complex text layout languages are rendered correctly (assuming the
	  associated library dependency of the device driver does that).
	</para>
      </sect3>
    </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 set (by ORing 0x80000000 with the
	FCI value) to distinguish it from a unicode (UCS4) integer
	(whose maximum value is 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;. The FCI contains three independent
	hexadecimal values corresponding to font family, font-style, and font
	weight.  These three values can also be obtained and set in a user-friendly
	way using &plgfont; and &plsfont;.  These values are also
	characterized by "hexdigit" (defined as the actual hexadecimal value
	used for one of the hexadecimal digits) and "hexpower" (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 Hershey escape
	sequences should be replaced by using the 4 unicode escape sequences
	<literal>#&lt;0x8nnnnnnn&gt;</literal>,
	<literal>#&lt;0xmn&gt;</literal>, <literal>#&lt;FCI COMMAND
	STRING/&gt;</literal>, and <literal>#[nnn]</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 and wxwidgets devices or the very large set of cairo and qt
	devices.  And for those devices the alternative of directly specifying
	the unicode symbols using UTF-8 encoding of PLplot input strings is
	much more convenient for users than using the above
	<literal>#[nnn]</literal> type of escape sequence.  For example, we
	use UTF-8 strings rather than escape sequences in <ulink
	url="&PLplot-website;/examples.php?demo=24">our standard example
	24</ulink> 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 scientific 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 Plots</title>
    <para>PLplot includes three-dimensional plot routines that plot
    functions of the two independent variables <literal>x</literal> and
    <literal>y</literal> in a variety of ways (see <xref
    linkend="surface-plots"/>, <xref linkend="contour-plots"/>, <xref
    linkend="shade-plots"/>, <xref linkend="image-plots"/>, and <xref
    linkend="vector-plots"/>).</para>
    <sect2 id="surface-plots">
      <title>Surface Plots</title>

      <para>PLplot provides the routines &plmesh;, &plmeshc;,
      &plot3d;, &plot3dc;, &plot3dcl;, &plsurf3d;, &plsurf3dl; and &plfill3;
      to plot the projection of a 3D surface on an existing 2D window.  Our
      standard examples <ulink
      url="&PLplot-website;/examples.php?demo=08">08</ulink>, <ulink
      url="&PLplot-website;/examples.php?demo=11">11</ulink>, <ulink
      url="&PLplot-website;/examples.php?demo=15">15</ulink>, <ulink
      url="&PLplot-website;/examples.php?demo=21">21</ulink>, and <ulink
      url="&PLplot-website;/examples.php?demo=28">28</ulink> illustrate how
      these routines are used.</para>

      <para>In all cases the transformations required to plot the
      projection of a 3D surface on a 2D window are configured by &plw3d;
      and are done to a rectangular cuboid enclosing the 3D surface which
      has its limits expressed in 3D world coordinates and also normalized
      3D coordinates (used for interpreting the altitude and azimuth of the
      viewing angle).  This representation of the transformation process
      allows considerable flexibility in specifying how the surface is
      depicted.  The lengths of the sides of the normalized rectangular
      cuboid are independent of the 3D world coordinate ranges of each of
      the variables, making it possible to use <quote>reasonable</quote>
      viewing angles even if the ranges of the 3D world coordinates on the
      axes are very different.  The size of the normalized rectangular
      cuboid is determined essentially by the size of the two-dimensional
      window into which it is to be mapped.  The normalized cuboid is
      centered about its 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 of the normalized cuboid.  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 normalized cuboid as viewed from
      above the xy plane.  The azimuth can take on any value.  In the above
      list of examples, we have chosen x and y world-coordinate ranges near
      (-1.0-1.0) for the 2D window, and x, y, z sizes of the normalized
      cuboid near (1., 1., 1.), and users will likely want to adopt similar
      values as well.</para>
    </sect2>

    <sect2 id="contour-plots">
      <title>Contour Plots</title>

      <para>PLplot provides the &plcont; routine for generating
      contour plots and our standard examples <ulink
      url="&PLplot-website;/examples.php?demo=09">08</ulink>, <ulink
      url="&PLplot-website;/examples.php?demo=14">14</ulink>, <ulink
      url="&PLplot-website;/examples.php?demo=16">16</ulink>, and <ulink
      url="&PLplot-website;/examples.php?demo=22">22</ulink> illustrate how
      this routine is used.  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.</para>

      <para>The path of each contour is initially computed in terms of
      the values of the indices of the matrix that holds the data to be
      contoured.  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 transformation is normally done
      by a callback function which is supplied as an argument to &plcont;.
      For C use of &plcont; we have included directly in the PLplot library
      the following transformation callback routines: &pltr0; (identity
      transformation); &pltr1; (linear interpolation in singly dimensioned
      coordinate arrays); and &pltr2; (linear interpolation in doubly
      dimensioned coordinate arrays), but other callbacks can be used for
      the C case instead.  The above list of examples illustrates how this
      callback argument and associated transformation from index arguments to
      world coordinates is implemented in each of our supported
      languages.</para>
    </sect2>

    <sect2 id="shade-plots">
      <title>Shade plots</title>
      <para>PLplot provides the &plshade; and &plshades; routines for
      generating shade plots and our standard examples <ulink
      url="&PLplot-website;/examples.php?demo=15">15</ulink>, <ulink
      url="&PLplot-website;/examples.php?demo=16">16</ulink>, <ulink
      url="&PLplot-website;/examples.php?demo=21">21</ulink>, and <ulink
      url="&PLplot-website;/examples.php?demo=22">22</ulink> illustrate how
      those routines are used including how the needed transformation from
      index arguments to world coordinates is implemented in each of
      our supported languages.</para>
    </sect2>
    <sect2 id="image-plots">
      <title>Image plots</title>
      <para>PLplot provides the &plimage; and &plimagefr; routines for
      generating images plots and our standard example <ulink
      url="&PLplot-website;/examples.php?demo=20">20</ulink> illustrates how
      those routines are used including how the needed transformation from
      index arguments to world coordinates is implemented in each of
      our supported languages.</para>
    </sect2>
    <sect2 id="vector-plots">
      <title>Vector plots</title>
      <para>PLplot provides the &plvect; routine for
      generating vector plots and our standard example <ulink
      url="&PLplot-website;/examples.php?demo=22">22</ulink> illustrates how
      that routine is used including how the needed transformation from
      index arguments to world coordinates is implemented in each of
      our supported languages.  In addition that routine shows
      how to call &plsvect; to set the arrow style for vector plots.</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 our standard examples <ulink
      url="&PLplot-website;/examples.php?demo=04">04</ulink> and<ulink
      url="&PLplot-website;/examples.php?demo=26">26</ulink> for some
      examples.  &plcolorbar; is especially useful for annotating continuous
      shade plots generated by &plshades;.  See <ulink
      url="&PLplot-website;/examples.php?demo=16">our standard example 16</ulink>, 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 <ulink
      url="&PLplot-website;/examples.php?demo=33">our standard example
      33</ulink> 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
      our standard examples <ulink
      url="&PLplot-website;/examples.php?demo=04">04</ulink>, <ulink
      url="&PLplot-website;/examples.php?demo=16">16</ulink>, and <ulink
      url="&PLplot-website;/examples.php?demo=26">26</ulink> as a tutorial
      on how to use these PLplot capabilities in a simple way, and for more
      advanced use we recommend studying the &pllegend; and &plcolorbar;
      documentation and also <ulink
      url="&PLplot-website;/examples.php?demo=33">our standard example
      33</ulink> which attempts to exercise most capabilities of these two
      PLplot functions.
    </para>
  </sect1>

</chapter>
