<?xml version='1.0' encoding='UTF-8'?>
<!-- -*-  mode: nxml -*- --><!--
    ada.xml: "Ada Language" chapter

Copyright (C) 2008-2010 Jerry Bauck

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.
--><!-- Note to self: Uncomment these lines when editing with Serna or XMLmind
     or whatever, a validity check doesn't always fail. --><!-- This document was created with Syntext Serna Free. -->
<chapter id="ada">
  <title>Ada Language</title>
  <para>This document describes the Ada bindings to the PLplot technical
  plotting software, how to obtain the necessary software components, and how
  to use them together.</para>
  <sect1 id="ada_overview">
    <title>Overview</title>
    <para>The Ada bindings for PLplot provide a way for Ada programmers to
    access the powerful PLplot technical plotting facilities directly from Ada
    programs while working completely in Ada; the Ada programmer never needs
    to know or worry that PLplot itself is written in another language.</para>
    <para>There are a thin binding and two thick bindings provided. The thin
    binding presents the application programming interface (API) in a form
    very similar to the C API, although in 100% Ada. The thick bindings
    present the API in a form to which Ada programmers will be more accustomed
    and add some ease-of-use features. It is expected that the thick bindings
    will be preferred.</para>
  </sect1>
  <sect1 id="ada_bindings">
    <title>The Bindings</title>
    <para>The bindings are a re-expression and extension of the C-language API
    and as such are a kind of abstract layer between the user&apos;s code and the
    PLplot binary library. Additionally, there are a few capabilities not in
    the official API but nonetheless which are available to the C programmer
    which are included in the bindings and thus are directly available to the
    Ada programmer.</para>
    <para>The thin binding is a layer between the thick bindings and the
    underlying C code. It is mainly a programming convenience for the
    developer of the bindings; this is a common implementation for foreign
    language bindings and for the most part, the user can ignore it.</para>
    <para>There are two thick bindings provided for the convenience of the
    user. Either may be used and they both provide exactly the same
    functionality. The thick bindings are the user&apos;s main concern with
    programming for PLplot.</para>
    <sect2 id="ada_thin">
      <title>Thin Binding</title>
      <para>The thin binding, in the files <literal>plplotthin.ads</literal>
      and <literal>plplotthin.adb</literal>, is mostly a direct and obvious
      mapping of the C application programming interface (API) to Ada. Thus,
      for example, where a C program such as <literal>plcol0</literal>
      requires a single integer argument, there is a corresponding Ada program
      also called <literal>plcol0</literal> which also requires a single
      integer argument. (<literal>plcol0</literal> happens to set the drawing
      color using a number which is associated with a set of colors.) Various
      constants from the C API are also included here. Numeric types as
      defined in PLplot are associated with numeric types in Ada in the thin
      binding by use of Ada&apos;s type system. Thus, the thin binding refers to
      the PLplot-centric type <literal>PLFLT</literal> for floating-point
      types while the thick binding uses the usual Ada type
      <literal>Long_Float</literal>.</para>
      <para>Many of the comments from the C source header file (similar in
      purpose to an Ada specification file) have been retained in the thin
      binding, even when they are no longer make sense. These might be pruned at
      some point to facilitate reading the Ada source.</para>
      <para>Also included in the thin binding are some other declarations
      which help the Ada binding to mesh well with C by emulating certain data
      structures which are needed in some rather specialized usages as well as
      providing certain subprogram pointer types.</para>
      <para>The Ada programmer working with either of the thick bindings will
      have to refer to the thin binding relatively rarely, if ever, and mainly
      to examine the subroutine pointer declarations and the several variant
      record types which are used mostly for contour and three-dimensional
      plots. However, some of these have been <literal>subtype</literal>-ed or
      <literal>renames</literal>-ed in the thick bindings so even less
      reference to the thin binding will be necessary. The goal is to put
      everything of interest to the user in the thick bindings and the user
      need not bother with the thin binding.</para>
    </sect2>
    <sect2 id="ada_thick">
      <title>The Thick Bindings</title>
      <para>The thick bindings provide most of the information that the Ada
      programmer needs. Normally, only one of the two thick bindings would be
      used per user program but it should be possible to include both but that
      scenario would be unusual.</para>
      <para>There are three main aspects of the thick bindings: providing an
      alternative access to the PLplot API, extending the PLplot functionality
      with some easy-to-use features, and overlaying Ada data structures and
      types.</para>
      <para>In the first aspect, the thick bindings provide a fully Ada
      interface to the entire PLplot library. Packages are
      <literal>with</literal>-ed and <literal>use</literal>-d as normal Ada
      code. Ada arrays can be passed as usual, not requiring the array length
      or start or end indices to be passed separately. All necessary Ada types
      are made to match the underlying C types exactly.</para>
      <para>The second aspect of the thick bindings is to provide some
      simplified ways to get a lot of plotting done with only one or two
      subroutine calls. For example, a single call to Simple_Plot can display
      from one to five &quot;<emphasis>y</emphasis>&apos;s&quot; as a function of a single
      &quot;<emphasis>x</emphasis>&quot; with default plot appearances chosen to suit
      many situations. Other simple plotters are available for
      three-dimensional and contour plots. Manipulating PLplot&apos;s colors is
      similarly made easy and some default color schemes are provided.</para>
      <para>The third main aspect of the thick binding is to use Ada data
      structures and Ada&apos;s type system extensively to reduce the chances of
      inappropriate actions. For example, Ada arrays are used throughout (as
      opposed to C&apos;s
      pointer-plus-offset-while-carrying-along-the-size-separately approach).
      Quantities which have natural range limits are
      <literal>subtype</literal>-d to reflect those constraints. The hope is
      that program errors will result in more-familiar Ada compilation or
      run-time errors rather than error reports from the PLplot library or no
      reports at all. However, there remain a few instances where the typing
      could be improved and PLplot errors will still be reported from time to
      time.</para>
      <para>Both the specification and body for the standard thick (and thin)
      binding contain the C subroutine name as a comment line immediately
      above the Ada procedure declaration; this should help in making the
      associations between &quot;Ada&quot; names and &quot;PLplot&quot; names. Also, the
      subroutine-specific comments from the C API have been retained
      verbatim.</para>
    </sect2>
    <sect2 id="ada_thick_enhanced">
      <title>Standard Thick Binding Using Enhanced Names</title>
      <para>The distinguishing feature of this thick binding (the &quot;standard&quot;
      binding) is to provide more descriptive names for PLplot subroutines,
      variables, constants, arguments, and other objects. Most Ada programmers
      will be more comfortable using these names. For example, in the C API as
      well as the thin Ada binding and the other thick Ada binding, the
      procedure <literal>plcol0(1)</literal> sets the drawing color to red. In
      the standard thick binding, the same thing is accomplished by writing
      <literal>Set_Pen_Color(Red)</literal>. The Ada program may just as well
      write <literal>Set_Pen_Color(1)</literal> since the binding merely sets
      a constant <literal>Red</literal> to be equal to the integer
      <literal>1</literal>. Many such numeric constants from the C API are
      given names in this thick binding. These renamed integers are discussed
      more fully in Section 7.2.</para>
      <para>The disadvantage of this renaming is that it makes referring to
      the PLplot documentation somewhat awkward. There might be, at some time,
      a utility for easing this problem by providing an HTML file with links
      so that a &quot;normal&quot; PLplot name can be linked to the &quot;Ada&quot; name along
      with the appropriate entry in the Ada specification, as well as another
      HTML file with links from the &quot;Ada&quot; name directly to the PLplot web page
      that documents that name. It might also be possible to provide an
      alternate version of the documentation with the enhanced names used.
      (The developer of the bindings has a sed file prepared which makes most
      of the subroutine-name substitutions.) However, this thick binding
      retains the original C subprogram names as comments immediately above
      the function or procedure name in the code listing so it is relatively
      easy to locate the relevant item in the PLplot documentation.</para>
      <para>One simple rule applies in reading the PLplot API documentation:
      the argument names are in the same order in Ada as in the PLplot
      documentation (the names are different) except that all array lengths
      are eliminated. The PLplot documentation, for each subroutine, shows a
      &quot;redacted&quot; version which should be correct for Ada as well as other
      languages which have proper arrays.</para>
      <para>The standard bindings are in the Ada files
      <literal>plplot.ads</literal> and <literal>plplot.adb</literal>.</para>
    </sect2>
    <sect2 id="ada_thick_traditional">
      <title>Thick Binding Using Traditional Names</title>
      <para>This thick binding provides exactly the same functionality as the
      standard thick binding but retains the original names as used in the C
      code and the PLplot documentation.</para>
      <para>The traditional bindings are in the Ada files
      <literal>plplot_traditional.ads</literal> and
      <literal>plplot_traditional.adb</literal>.</para>
    </sect2>
  </sect1>
  <sect1 id="ada_examples">
    <title>The Examples</title>
    <para>An important part of the Ada bindings is the examples, some 33 of
    which demonstrate how to use many of the features of the PLplot package.
    These examples also serve as a test bed for the bindings in Ada and other
    languages by checking the Postscript files that are generated by each
    example against those generated by the C versions. These examples have
    been completely re-written in Ada (but retain a C flavor in the names that
    are given to objects). All of the Ada examples generate exactly the same
    Postscript as the C versions, Examples 14 and 17 excepted since those
    operate interactively and don&apos;t (normally) make Postscript. Two versions
    of each example are available, one calling the standard binding and the
    other the traditional binding. (In development, a sed script does almost
    all of the conversion automatically.)</para>
  </sect1>
  <sect1 id="ada_obtaining">
    <title>Obtaining the Software</title>
    <para>There are three software components that you will need: an Ada
    compiler, the PLplot library, and the Ada bindings.</para>
    <sect2 id="ada_obtaining_ada">
      <title>Obtaining an Ada compiler</title>
      <para>You will need an Ada compiler in order to use the Ada PLplot
      bindings. There are several compilers available. Here, we will focus on
      the free, open source compiler that is included with the GNU Compiler
      Collection, (gcc) which is at the center of much of the open source
      software movement. The gcc Ada compiler is known as GNAT, for GNU NYU
      Ada Translator, where NYU stands for New York University. (Although GNAT
      was originally developed at NYU, it has for many years been developed
      and supported commercially by AdaCore with academic and pro versions
      available.)</para>
      <para>Your computer may already have GNAT installed, or you can download
      it from <ulink url="http://gcc.gnu.org/">gcc.gnu.org</ulink>. Another
      route to obtaining GNAT is from the AdaCore page, <ulink url="https://libre2.adacore.com/">libre2.adacore.com</ulink>. There are
      versions for many operating systems and processors including Apple&apos;s OS
      X or its open source version Darwin, Linux, and Windows. The gcc and
      AdaCore versions differ in their licenses. Download the version that you
      need and follow the installation instructions.</para>
    </sect2>
    <sect2 id="ada_obtaining_plplot">
      <title>Download and install PLplot</title>
      <para>PLplot can be downloaded from the PLplot project page at <ulink url="http://sourceforge.net/projects/plplot">sourceforge.net</ulink>.
      Follow the installation instructions after downloading. The installation
      process requires that your computer has CMake installed. OS X users can
      try installing PLplot in its entirety from MacPorts. The advantage of
      using MacPorts is that all installation dependencies are automatically
      installed for you.</para>
    </sect2>
    <sect2 id="ada_obtaining_bindings">
      <title>The Ada bindings to PLplot</title>
      <para>The third major software component is the bindings themselves;
      they are included with the PLplot software itself.</para>
      <para>The bindings themselves are six Ada source files named (using GNAT
      filename extensions) <literal>plplot.ads</literal>,
      <literal>plplot.adb</literal>,
      <literal>plplot_traditional.ads</literal>,
      <literal>plplot_traditional.adb</literal>,
      <literal>plplothin.ads</literal>, and <literal>plplotthin.adb</literal>.
      There are two additional files, <literal>plplot_auxiliary.ads</literal>
      and <literal>plplot_auxiliary.adb</literal> which will be discussed
      later, in Section 9.</para>
    </sect2>
  </sect1>
  <sect1 id="ada_howto">
    <title>How to use the Ada bindings</title>
    <sect2 id="ada_95_2005">
      <title>Ada 95 versus Ada 2005</title>
      <para>The bindings will work for either Ada 95 or Ada 2005 but there is
      a slightly subtle point regarding the use and declaration of vectors and
      matrices. The package <literal>PLplot_Auxiliary</literal> declares the
      types</para>
      <programlisting>
    type Real_Vector is array (Integer range &lt;&gt;) of Long_Float;
    type Real_Matrix is array (Integer range &lt;&gt;, Integer range &lt;&gt;) of Long_Float;
</programlisting>
      <para>These declarations mimic exactly the declarations described in
      Annex G.3, Vector and Matrix Manipulation, of the Ada 2005 reference
      manual when the generic package therein described is specialized for
      <literal>Long_Float</literal>. The reason for this approach is to avoid
      requiring the user program to <literal>with</literal>
      <literal>Ada.Numerics.Long_Real_Arrays</literal> simply to gain access
      to these types and in the process require linking to the BLAS and LAPACK
      numerical libraries.</para>
      <para>Ada 2005 introduced an annex G.3 which formally defines vector and
      matrix support to Ada, along with some common mathematical operations on
      those types. (This feature is a specific to vectors and matrices and
      extends the usual array apparatus.) The Ada PLplot user has a choice on how
      to deal with this. The default, as described in
      <literal>PLplot_Auxiliary.ads</literal>,
      has <literal>Real_Vector</literal> and <literal>Real_Matrix</literal>
      declared therein, separate from the Ada 2005 declarations. This allows the
      widest compatibility and does not require an Ada 2005 compiler. However,
      many users will want to gain the benefit of the built-in declarations of
      2005. This is easily done: Read the short comments in
      <literal>PLplot_Auxiliary.ads</literal> on how to comment-out two lines and
      uncomment three lines. Either configuration will compile correctly, but
      depending on the Cmake configuration to expose a 2005 compiler in the later
      case. (Note that at some points in the documentation, Ada 2005 is referred
      to as Ada 2007, including some Cmake flags.)</para>
      <para>This policy was changed in SVN version 11153. Before this, the
      type of compiler (Ada 95 or Ada 2005) had to be specified at the time
      that PLplot was built, and in the case of Ada 2005, the BLAS and LAPACK
      libraries had to be present and were subsequently linked.</para>
    </sect2>
    <sect2 id="ada_gnat_nongnat">
      <title>GNAT versus non-GNAT</title>
      <para>The bindings were made using the GNAT compiler and there is a
      slight dependence on that compiler. Specifically, the
      <literal>Unrestricted_Access</literal> attribute of GNAT was used in
      making the function <literal>Matrix_To_Pointers</literal> in
      <literal>plplotthin.adb</literal> and in a few callbacks.
      <literal>Matrix_To_Pointers</literal> is called whenever an Ada matrix
      (2D array) is passed to a PLplot subroutine. For more about
      <literal>Unrestricted_Access attribute</literal>, see Implementation
      Defined Attributes in the GNAT Reference Manual. This dependency
      shouldn&apos;t be difficult to remove by either incorporating the GNAT code
      which implements it, by following the TO-DO comment near the function
      definition in <literal>plplotthin.adb</literal>, or by providing the
      proper aliasing.</para>
      <para>Another GNAT dependency is used to parse command line arguments in
      a C-like way.</para>
      <para>Pragma Warnings (Off, &quot;some text&quot;) and Pragma Warnings (On, &quot;some
      text&quot;) are used in the bindings to suppress warnings about a particular
      method used to interface with C code. These pragmas are also used in
      Ada Examples 21 to suppress a particular warning. Pragma Warnings is a
      GNAT extension. Non-GNAT usage could simply remove these pragmas with
      the resulting warnings ignored as they are benign.</para>
      <para>Most of the GNAT dependencies can be found by searching the source
      code for &quot;<literal>GNAT</literal>&quot;,
      &quot;<literal>Unrestricted_Access</literal> and <literal>Pragma Warnings</literal>.&quot;</para>
      <para>The GNAT dependence, though slight, will no doubt frustrate users
      of other Ada compilers. We welcome comments from those users, especially
      comments with specific suggestions on how to remove any GNAT-specific
      usages.</para>
    </sect2>
    <sect2 id="ada_sample_project">
      <title>Sample command line project</title>
      <para>It is instructive to present a simple example that can be compiled
      and run from the command line. Although this example is specific to one
      installation, it should be fairly straightforward to adapt it to another
      installation. Toward that end, it is helpful to understand the PLplot
      lingo of &quot;build directory&quot; and &quot;installation directory.&quot;</para>
      <para>Here is a simple program that will generate a plot of part of a
      parabola.</para>
      <programlisting>
 with
    PLplot_Auxiliary,
    PLplot;
 use
    PLplot_Auxiliary,
    PLplot;
 procedure Simple_Example is
    x, y : Real_Vector(-10 .. 10);
 begin
    for i in x&apos;range loop 
       x(i) := Long_Float(i);
       y(i) := x(i)**2;
    end loop;
    Initialize_PLplot; -- Call this only once.
    Simple_Plot(x, y); -- Make the plot.
    End_PLplot;        -- Call this only once.
 end Simple_Example;
      </programlisting>
      <para>Next is a bash script that will compile, bind, and link it. It is
      installation-specific in that paths to the GNAT compiler, PLplot
      libraries, and BLAS (Basic Linear Algebra System) and LAPACK (Linear
      Algebra Package) are hard-coded. You will have to adjust the paths to
      fit your installation. Some Linux installations which have GNAT 4.3 or
      later (Ada 2005) pre-installed might have already set the paths to the
      BLAS and LAPACK libraries.</para>
      <para>(Note that the G.3 Annex of Ada 2005, in the GNAT version, depends
      heavily on BLAS and LAPACK. These packages are tried-and-true packages
      that are available from several places in either C or Fortran versions.
      The present example is specific to OS X which has both C and Fortran
      versions pre-installed.)</para>
      <programlisting>
 #!/bin/bash
 /usr/local/ada-4.3/bin/gnatmake simple_example.adb \
 -aI/usr/local/plplot_build_dir/bindings/ada \
 -aL/usr/local/plplot_build_dir/bindings/ada/CMakeFiles/plplotadad.dir \
 -largs \
 /usr/local/plplot/lib/libplplotd.dylib \
 /Developer/SDKs/MacOSX10.4u.sdk/usr/lib/libblas.dylib \
 /Developer/SDKs/MacOSX10.4u.sdk/usr/lib/liblapack.dylib
      </programlisting>
      <para>The resulting binary program can be run by typing
      <command>./simple_example</command></para>
    </sect2>
  </sect1>
  <sect1 id="ada_unique">
    <title>Unique Features of the Ada bindings</title>
    <para>The Ada bindings have been augmented with a number of features which
    are intended to simplify the use of PLplot. They include high-level
    features for simplified plotting (such as easy foreground-background
    control, a collection of &quot;simple plotters,&quot; and easy color map
    manipulations), integer options which have been given meaningful names,
    and a few other focused additions. Many users will find that they can do
    most of their work using the &quot;simple plotters&quot;.</para>
    <sect2 id="ada_high_level">
      <title>High-level features for simplified plotting</title>
      <sect3 id="ada_foreground_background">
        <title>Foreground-background control</title>
        <sect4 id="ada_draw_bw">
          <title>Draw_On_Black, Draw_On_White</title>
          <para>The default for PLplot is to draw its graphics on a black
          background. A white background can be used instead with
          <literal>Draw_On_White</literal> or reset to the original mode with
          <literal>Draw_On_Black</literal>. Each of these manipulates color
          map 0 by swapping black and white so that e.g.with
          <literal>Draw_On_White</literal>, formerly white lines on a black
          background automatically become black lines on a white
          background.</para>
        </sect4>
      </sect3>
      <sect3 id="ada_simple_plotters">
        <title>Simple Plotters</title>
        <para>Several high-level but flexible plotters are available and more
        might be added in the future. It is expected that many users will find
        that these high-level routines are adequate for most of their
        day-to-day plotting.</para>
        <sect4 id="ada_multiple_pairs">
          <title>Multiplot_Pairs</title>
          <para>Plot up to five <emphasis>x-y</emphasis> pairs with easy
          labelling, coloring, line width and styles, justification, and
          zooming.</para>
        </sect4>
        <sect4 id="ada_simple_plot">
          <title>Simple_Plot</title>
          <para>Plot up to five <emphasis>y</emphasis>&apos;s against a single
          <emphasis>x</emphasis> with easy labelling and automatic line colors
          and styles.</para>
        </sect4>
        <sect4 id="ada_simple_plot_logx">
          <title>Simple_Plot_Log_X</title>
          <para>Same as <literal>Simple_Plot</literal> but with logarithmic
          <emphasis>x</emphasis>-axis.</para>
        </sect4>
        <sect4 id="ada_simple_plot_logy">
          <title>Simple_Plot_Log_Y</title>
          <para>Same as <literal>Simple_Plot</literal> but with logarithmic
          <emphasis>y</emphasis>-axis.</para>
        </sect4>
        <sect4 id="ada_simple_plot_logxy">
          <title>Simple_Plot_Log_XY</title>
          <para>Same as <literal>Simple_Plot</literal> but with logarithmic
          <emphasis>x</emphasis>- and <emphasis>y</emphasis>-axes.</para>
        </sect4>
        <sect4 id="ada_simple_plot_pairs">
          <title>Simple_Plot_Pairs</title>
          <para>Plot up to five <emphasis>x</emphasis>-<emphasis>y</emphasis>
          pairs with easy labelling and automatic line colors and
          styles.</para>
        </sect4>
        <sect4 id="ada_single_plot">
          <title>Single_Plot</title>
          <para>Plot a single <emphasis>x</emphasis>-<emphasis>y</emphasis>
          pair with flexible labels, axis styles, colors, line width and
          style, justification, and zooming.</para>
        </sect4>
        <sect4 id="ada_simple_contour">
          <title>Simple_Contour</title>
          <para>Make a contour plot with labels</para>
        </sect4>
        <sect4 id="ada_simple_mesh">
          <title>Simple_Mesh_3D</title>
          <para>Easy 3D mesh plot with labels, zooming, and perspective
          controls</para>
        </sect4>
        <sect4 id="ada_simple_surface_3d">
          <title>Simple_Surface_3D</title>
          <para>Easy 3D surface plot with labels, zooming, and perspective
          controls</para>
        </sect4>
      </sect3>
      <sect3 id="ada_simple_color">
        <title>Simple color map manipulations</title>
        <para>PLplot provides extensive manipulation and control of two
        separate color maps, color map 0 and color map 1. The Ada binding
        makes basic manipulations easier and also adds facilities for making
        snapshots of color map 0 so that any state of the map can easily be
        restored later. An initial snapshot is taken when the package is
        initialized so that the default color settings can always be restored
        after having been changed.</para>
        <para>Another set of features lets the user reset the 16 individual
        colors in color map 0 after a color definition has been changed. It is
        important to note that while <literal>Set_Pen_Color(Red)</literal>
        (<literal>plcol0</literal> in the traditional binding) normally does
        what it says, <literal>Red</literal> simply has the value
        <literal>1</literal>. If the user changes the color map so that
        <literal>1</literal> corresponds to another color, then
        <literal>Set_Pen_Color(Red)</literal> will draw in that color instead
        of red. To always assure that red is drawn even if the color map has
        been changed for integer <literal>1</literal>, use
        <literal>Set_Pen_Color(Reset_Red)</literal> instead. These 16 &quot;reset&quot;
        functions return the appropriate default integer for the specified
        color but also reset that slot in the color table so that a subsequent
        call such as <literal>Set_Pen_Color(Red)</literal> will also cause
        drawing in red.</para>
        <para>Color map 1 also gets a easy-to-use makeover for Ada users.
        There are several pre-built color themes that are useful for quickly
        making surface and mesh plots,
        <literal>Color_Themes_For_Map_1_Type</literal>. These color themes can
        be quickly applied with
        <literal>Quick_Set_Color_Map_1</literal>.</para>
        <para>Miscellaneous other Ada features include a pre-built mask
        function for <literal>Shade_Regions</literal> that does no masking;
        perhaps the most useful purpose is to provide a template for writing
        mask functions that do mask. And there is a handy function for
        calculating the contour levels for making contour plots.</para>
        <itemizedlist>
          <listitem>
            <para>Color table snapshots</para>
            <para><literal>Make_Snapshot_Of_Color_Map_0</literal></para>
            <para><literal>Restore_Snapshot_Of_Color_Map_0</literal></para>
            <para><literal>Restore_Default_Snapshot_Of_Color_Map_0</literal></para>
          </listitem>
          <listitem>
            <para>Color resetting functions for the 16 colors of color map
            0</para>
            <para><literal>Reset_Black, Reset_Red, ..., Reset_White</literal></para>
          </listitem>
          <listitem>
            <para>Easy manipulation of color map 1</para>
            <para>Pre-built color themes for color map 1:
            <literal>Color_Themes_For_Map_1_Type</literal></para>
            <para>Quick application of pre-built color themes:
            <literal>Quick_Set_Color_Map_1</literal></para>
          </listitem>
          <listitem>
            <para>Other features</para>
            <para>A pre-built mask function for
            <literal>Shade_Regions</literal> that does no masking:
            <literal>Mask_Function_No_Mask</literal></para>
            <para>An easy way to calculate an array of contour levels for
            contour plots: <literal>Calculate_Contour_Levels</literal></para>
          </listitem>
        </itemizedlist>
      </sect3>
    </sect2>
    <sect2 id="ada_integer_options">
      <title>Integer Options Given Ada Names</title>
      <para>The C version of PLplot uses a number of integers to mean specific
      things. Unfortunately, the meaning is lost when it it consigned to being
      a mere integer with no name. The Ada binding partially rectifies this
      situation by giving names to these integer constants. The integer can
      still be used if desired. (A more complete and safer rectification would
      use enumerated types.)</para>
      <para>Below is a listing of at least the contexts in which these
      &quot;re-namings&quot; have been applied. In some cases the entire range of values
      is listed, but if there are more than about four such values for each
      context, only a sampling is given.</para>
      <para><emphasis role="bold"> Instances</emphasis></para>
      <para><itemizedlist>
          <listitem>
            <para>Colors: Plot_Color_Type</para>
            <para><literal> 0</literal> is Black, <literal>1</literal> is Red,
            etc</para>
          </listitem>
          <listitem>
            <para>Justification for plots:
            <literal>Justification_Type</literal></para>
            <para><literal>User_Justified</literal></para>
            <para><literal>Not_Justified</literal></para>
            <para><literal>Justified</literal></para>
            <para><literal>Justified_Square_Box</literal></para>
          </listitem>
          <listitem>
            <para>Axis styles: <literal>Axis_Style_Type</literal></para>
            <para><literal>Linear_Major_Grid</literal></para>
            <para><literal>Linear_Minor_Grid</literal></para>
            <para>etc.</para>
          </listitem>
          <listitem>
            <para>Font styles: <literal>Font_Style_Type</literal></para>
            <para><literal>Normal_Font</literal></para>
            <para><literal>Roman_Font</literal></para>
            <para><literal>Italic_Font</literal></para>
            <para><literal>Script_Font</literal></para>
          </listitem>
          <listitem>
            <para>Character sets: <literal>Character_Set_Type</literal></para>
            <para><literal>Standard_Character_Set</literal></para>
            <para><literal>Extended_Character_Set</literal></para>
          </listitem>
          <listitem>
            <para>Plot orientation: <literal>Orientation_Type</literal></para>
            <para><literal>Landscape</literal></para>
            <para><literal>Portrait</literal></para>
          </listitem>
          <listitem>
            <para>Modes for parsing command line arguments:
            <literal>Parse_Mode_Type</literal></para>
            <para>E.g. <literal>PL_PARSE_PARTIAL</literal></para>
          </listitem>
          <listitem>
            <para>Descriptions of map outlines (continents, states, etc.):
            <literal>Map_Type</literal></para>
            <para><literal>Continents</literal></para>
            <para><literal>USA_and_States</literal></para>
            <para><literal>Continents_and_Countries</literal></para>
            <para><literal>USA_States_and_Continents</literal></para>
          </listitem>
          <listitem>
            <para>Various style and view options for 3D and surface
            plots</para>
            <para>E.g. <literal>Lines_Parallel_To_X</literal></para>
          </listitem>
          <listitem>
            <para>Kind of gridding algorithm for interpolating 2D data to a
            grid: <literal>Gridding_Algorithm_Type</literal></para>
            <para>E.g.
            <literal>Grid_Bivariate_Cubic_Spline_Approximation</literal></para>
          </listitem>
          <listitem>
            <para>Flags for histogram style</para>
            <para>E.g. <literal>Histogram_Default</literal></para>
          </listitem>
          <listitem>
            <para>Flags for histogram binning</para>
            <para>E.g. <literal>Bin_Default</literal></para>
          </listitem>
          <listitem>
            <para>Names for color space models</para>
            <para>Hue, Lightness, Saturation: <literal>HLS</literal></para>
            <para>Red, Green, Blue: <literal>RGB</literal></para>
          </listitem>
        </itemizedlist></para>
    </sect2>
    <sect2 id="ada_one_offs">
      <title>One-offs</title>
      <para>To provide convenient string handling in a fashion that is
      familiar to Ada programmers, function versions which return a
      <literal>String</literal> type are provided of
      <literal>Get_Device_Name</literal>,
      <literal>Get_Version_Number</literal>, and
      <literal>Get_Output_File_Name</literal> (<literal>plgdev</literal>,
      <literal>plgver</literal>, and <literal>plgfnam</literal> in the
      traditional binding). These functions replace the procedure-style
      subprograms that are described in the C API documentation.</para>
      <para>Overloaded <literal>Set_Line_Style</literal>
      (<literal>plstyl</literal> in the traditional binding) with a version
      that takes a single argument,
      <literal>Default_Continuous_Line</literal>. This replaces the awkward
      situation of calling the normal versions of these procedures with unused
      arguments simply to set the line style to the default, continuous,
      line.</para>
      <para>The contour plotter <literal>Contour_Plot_Irregular_Data</literal>
      (<literal>plfcont</literal> in the traditional binding) is provided for
      making contour plots from irregularly spaced data. This feature is not
      documented in the PLplot API documentation.</para>
      <para>The custom label function <literal>Set_Custom_Label</literal>
      (<literal>plslabelfunc</literal> in the traditional binding) can be
      called with null arguments to revert to using the default labelling
      scheme. Alternately, an Ada-only procedure with no arguments,
      <literal>Use_Default_Labels</literal>, is provided. See Ada example 19
      (<literal>x19a.adb</literal> or <literal>xthick19a.adb</literal>) for a
      usage example.</para>
      <para>The custom coordinate transform setter,
      <literal>Set_Custom_Coordinate_Transform</literal>,
      (<literal>plstransform</literal> in the traditional binding) can be
      called with null arguments to clear any previous custom coordinate
      transforms that the user has set, thus reverting to the default
      coordinate transform. Alternately, an Ada-only procedure with no
      arguments, <literal>Clear_Custom_Coordinate_Transform</literal>, is
      provided. See Ada example 19 (<literal>x19a.adb</literal> or
      <literal>xthick19a.adb</literal>) for a usage example.</para>
      <para>The procedure <literal>Set_Arrow_Style_For_Vector_Plots</literal>
      (<literal>plsvect</literal> in the traditional binding) normally is called
      to define the shape of an arrow in vector plots. However, calling it with
      null pointer arguments (<literal>System.Null_Address</literal>)  in place
      of the <literal>Real_Vector</literal> arrays and <literal>False</literal>
      for the <literal>Fill_Arrow</literal> argument causes the arrow shape to
      be reset to the default shape; this is implemented in Ada as an overloaded
      procedure in order to be consistent with the C API but is rather awkward.
      So there are two additional procedures that are added for the convenience
      of Ada programmers: Reset_Vector_Arrow_Style and plsvect, both without
      arguments, both available in both bindings, and the latter an overload of
      the normal arrow-setting procedure.</para>
    </sect2>
  </sect1>
  <sect1 id="ada_c_flavor">
    <title>Parts That Retain a C Flavor</title>
    <para>There remains at least one area in the Ada bindings which is still
    affected by the C underpinnings. This might be cleaned up in future
    versions. There might be other residual C influence as well.</para>
    <sect2>
      <title>Map-drawing</title>
      <para><literal>plmapform</literal> as called by
      <literal>Draw_Latitude_Longitude</literal> (<literal>plmap</literal>)
      and <literal>Draw_Latitude_Longitude</literal>
      (<literal>plmeridians</literal>)</para>
      <para>This is the only place in the PLplot bindings where a C subprogram
      calls an Ada subprogram while passing an array. If the array is
      unconstrained, there is no guarantee that it will work because C has no
      way of telling Ada what offset to use for the beginning of the array.
      But passing a constrained array is acceptable with the downside that the
      array size must be fixed within the bindings as being large enough to
      handle any situation; currently, it is sized as <literal>0 .. 2000</literal>. See Example 19 for how this is handled in by the user
      program. The constrained array is called
      <literal>Map_Form_Constrained_Array</literal>.</para>
    </sect2>
  </sect1>
  <sect1 id="ada_known_variances">
    <title>Known Variances</title>
    <sect2>
      <title>Documentation</title>
      <para>In numerous places in the documentation, a feature is listed or
      described as &quot;C only.&quot; Many of these features are actually available in
      Ada. For example, in <literal>Contour_Plot</literal>
      (<literal>plcont</literal> in the traditional binding), the
      transformation from array indices to world coordinates is mentioned as
      &quot;C only&quot; but is actually available in Ada.</para>
    </sect2>
    <sect2>
      <title>API</title>
      <para>The C documentation for <literal>plscmap1l</literal>,
      (<literal>Set_Color_Map_1_Piecewise</literal> in the thick binding) and
      <literal>plscmap1la</literal>
      (<literal>Set_Color_Map_1_Piecewise_And_Alpha</literal> in the thick
      binding) states that if the last argument is a null pointer, the
      behavior is as though a proper-length array of all
      <literal>False</literal> values was passed. In Ada, these procedures are
      overloaded to allow a last argument that can be either an array of
      Boolean or a value of the enumerated type <literal>type Alt_Hue_Path_Type is (Alt_Hue_Path_None, Alt_Hue_Path_All)</literal>.</para>
    </sect2>
  </sect1>
  <sect1 id="ada_compilation_notes">
    <title>Compilation notes</title>
    <sect2>
      <title>Ada 95 Versus Ada 2005</title>
      <para>As discussed in Section 6.1, the bindings are made to work with
      Ada 95 and Ada 2005, but special steps need to be taken in order to
      access the numerical capabilities of Ada 2005 to the extent that vectors
      and arrays of the type defined in the Ada Reference Manual Annex G.3 are
      required to be passed to PLplot routines.</para>
    </sect2>
    <sect2>
      <title>GNAT Dependence</title>
      <para>There is a slight but significant dependence on the GNAT version
      of Ada. This is discussed more fully in Section 6.2</para>
    </sect2>
    <sect2>
      <title>PLplot_Auxiliary</title>
      <para>The bindings include files <literal>PLplot_Auxiliary.ads</literal>
      and <literal>PLplot_Auxiliary.adb</literal>. These files are currently
      used to provide a few convenience subprograms that are used in the
      examples. However, they are also associated with the above-mentioned
      facility to easily accommodate accessing the G.3 Annex vector-matrix
      manipulation facilities. If not for the desire for this easy &quot;switching&quot;
      ability, the <literal>PLplot_Auxiliary</literal> package could be
      removed from the <literal>with</literal> parts of the other binding
      files. Even so, it could be still removed with minor modifications to
      the <literal>with</literal> portions of the other binding files. But due
      to the other functions provided therein, they would still need to be
      referenced by most of the Ada examples.</para>
    </sect2>
  </sect1>
  <sect1 id="ada_apple_notes">
    <title>Notes for Apple Macintosh OS X users</title>
    <para>The following comments apply to users of Apple Macintosh computers
    which run OS X. OS X users may use Apple&apos;s free integrated development
    environment (IDE) or may prefer other methods such as using a favorite
    editor and building from the command line.</para>
    <para>OS X users should be aware that an excellent graphical terminal
    program is available and is highly recommended. It is called AquaTerm and
    is a full Cocoa program with window control. Performing a cut operation
    places a PDF of the front window on the clipboard, a convenience when
    working with other graphics or word processing programs.</para>
    <sect2>
      <title>Using Apple&apos;s Xcode IDE</title>
      <para>The Macintosh Ada community has made a plug-in for Apple&apos;s free
      Xcode integrated development environment (IDE) that makes programming
      Ada in Xcode possible. The plug-in is included with the compiler that is
      available at <ulink url="http://www.macada.org/">www.macada.org</ulink>.
      Since Xcode is based on gcc, it is possible to work in the various gcc
      languages as well as to incorporate binaries such as the PLplot
      library.</para>
      <para>In order to make an Xcode project, drag-and-drop source files and
      the PLplot library file to the Groups &amp; Files pane of an Ada
      project. There are a few idiosyncrasies that you may encounter so make
      sure to contact the very friendly Macintosh Ada mailing list at <ulink url="http://www.macada.org/">www.macada.org</ulink> or study the FAQ at
      that same site if you have any difficulties.</para>
      <para>[This plug-in still works for some older versions of Xcode but not
   for newer versions, as of 2013.]</para>
    </sect2>
    <sect2>
      <title>AquaTerm</title>
      <para>AquaTerm is a display option available on Macintosh computers
      using OS X and is supported by PLplot. It is a native Cocoa graphics
      &quot;terminal&quot; that is highly recommended. All output is antialiased and is
      easily cut-and-pasted in OS X&apos;s native PDF format. Get it <ulink url="http://sourceforge.net/projects/aquaterm/files">here</ulink>.
      It can also be installed from either the <ulink url="http://fink.thetis.ig42.org/">Fink</ulink> or <ulink url="http://www.macports.org/">MacPorts</ulink>
      projects.</para>
    </sect2>
    <sect2>
      <title>X11</title>
      <para>Apple supplies the X11 windowing system that is popular on some
      other Unix and Linux operations systems. Formerly it was available as part
      of the Developer Tools but as of OS X 10.8 it is a separate installation.
      All PLplot programs made with the Ada bindings will run on X11. In fact,
      some types of interactivity such as Example 17 will not run on
      Apple&apos;s Terminal.app and should be run on X11 (or
      some other output device such as TCL/TK).</para>
    </sect2>
    <sect2>
      <title>GNAT for OS X</title>
      <para>A web site for OS X users is at <ulink url="http://www.macada.org/macada/Welcome.html">www.macada.org</ulink>. 
      Although rather dated, the mailing list is still active. Assistance can be
      found at other places on the web including the usenet comp.lang.ada.</para>
    </sect2>
  </sect1>
</chapter>
