From: <ai...@us...> - 2008-09-10 17:20:06
|
Revision: 8767 http://plplot.svn.sourceforge.net/plplot/?rev=8767&view=rev Author: airwin Date: 2008-09-10 17:20:16 +0000 (Wed, 10 Sep 2008) Log Message: ----------- Minimal changes (i.e., book ==> chapter) necessary to integrate this Ada documentation into our PLplot documentation. Remove PLplot description section which is not appropriate since that done elsewhere in this PLplot documentation. Modified Paths: -------------- trunk/doc/docbook/src/ada.xml Modified: trunk/doc/docbook/src/ada.xml =================================================================== --- trunk/doc/docbook/src/ada.xml 2008-09-10 09:07:24 UTC (rev 8766) +++ trunk/doc/docbook/src/ada.xml 2008-09-10 17:20:16 UTC (rev 8767) @@ -1,5 +1,37 @@ -<?xml version='1.0'?> - <!DOCTYPE book> +<!-- -*- mode: nxml -*- --> +<!-- + ada.xml: "Ada Language" chapter + +Copyright (C) 2008 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. +--> + <!-- This document was converted from RTF source: By r2net 6.2.22 @@ -41,9 +73,8 @@ RootElement=book --> - <book> -<title>README.xml</title> -<preface></preface> + <chapter> +<title>Ada Language</title> <!-- 1:'Normal' --><para><emphasis role="bold">Ada Bindings for the PLplot Plotting Package</emphasis></para> <para><emphasis role="bold"> </emphasis></para> @@ -59,18 +90,6 @@ <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> <orderedlist numeration="arabic" continuation="restarts" spacing="normal"> -<listitem><para><emphasis role="bold">About PLplot</emphasis></para></listitem> -</orderedlist> -<!-- 10:'Normal' --><para> PLplot is a general purpose technical plotting package that can be accessed directly by the user's own program without first writing the data to be plotted to disk. The package is marked by speed, convenience, breadth, and flexibility.</para> -<para> The PLplot project is one of the most active on SourceForge, typically in the 99th percentile for activity.</para> -<para> The following is taken from the PLplot web site at <ulink url="http://plplot.sourceforge.net/">plplot.sourceforge.net</ulink>:</para> -<para> "PLplot is a library of functions that are useful for making scientific plots.</para> -<para> "PLplot can be used from within compiled languages such as C, C++, FORTRAN and Java, and interactively from interpreted languages such as Octave, Python, Perl and Tcl.</para> -<para> "The PLplot library can be used to create standard x-y plots, semilog plots, log-log plots, contour plots, 3D surface plots, mesh plots, bar charts and pie charts. Multiple graphs (of the same or different sizes) may be placed on a single page with multiple lines in each graph.</para> -<para> "A variety of output file devices such as Postscript, png, jpeg and others, as well as interactive devices such as xwin, tk, xterm and Tektronics devices are supported. New devices can be easily added by writing a small number of device dependent routines.</para> -<para> "There are almost 2000 characters in the extended character set. This includes four different fonts, the Greek alphabet and a host of mathematical, musical, and other symbols. Some devices supports its own way of dealing with text, such as the Postscript driver, or the png and jpeg drivers that uses the Freetype library."</para> - -<orderedlist numeration="arabic" continuation="restarts" spacing="normal"> <listitem><para><emphasis role="bold">The Bindings</emphasis></para></listitem> </orderedlist> <!-- 19:'Normal' --><para><emphasis role="bold"> </emphasis>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'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> @@ -303,4 +322,4 @@ <para>Author: Jerry Bauck</para> <para>© 2008 Jerry Bauck</para> <para>Distributed as part of the PLplot plotting software</para> -</book> +</chapter> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <ai...@us...> - 2008-09-10 17:31:06
|
Revision: 8769 http://plplot.svn.sourceforge.net/plplot/?rev=8769&view=rev Author: airwin Date: 2008-09-10 17:31:17 +0000 (Wed, 10 Sep 2008) Log Message: ----------- Remove description of how this file was generated because it will be hand-edited from now on. Indentation changes to conform to emacs docbook formatting. Modified Paths: -------------- trunk/doc/docbook/src/ada.xml Modified: trunk/doc/docbook/src/ada.xml =================================================================== --- trunk/doc/docbook/src/ada.xml 2008-09-10 17:22:11 UTC (rev 8768) +++ trunk/doc/docbook/src/ada.xml 2008-09-10 17:31:17 UTC (rev 8769) @@ -32,294 +32,254 @@ EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. --> - <!-- -This document was converted from RTF source: -By r2net 6.2.22 -Translation:docbook.trn Revision: 1.53 Revision: 1.157 -See http://www.logictran.com -Filename:/Users/jerrybauck/Documents/Programs/Ada/Code/Bindings/PLplot/Documentation for Ada bindings to PLplot/README.rtf -OutFileName:/Users/jerrybauck/Documents/Programs/Ada/Code/Bindings/PLplot/Documentation for Ada bindings to PLplot/README.xml -Application Directory:/Users/jerrybauck/Desktop/DOWNLOADS/R2Net Desktop -Subject: -Author: -Operator: -Document Comments: -Version Comments: -Comments: -Keywords: -Translation Date:09/09/2008 -Translation Time:23:09:53 -Translation Platform:Unix -Number of Output files:1 -This File:/Users/jerrybauck/Documents/Programs/Ada/Code/Bindings/PLplot/Documentation for Ada bindings to PLplot/README.xml -percentCallback=10 -ImageExt=jpg -createOutputFolder=0 -outputFolder=/Users/jerrybauck/Documents/Programs/Ada/Code/Bindings/PLplot/Documentation for Ada bindings to PLplot -outfilename=/Users/jerrybauck/Documents/Programs/Ada/Code/Bindings/PLplot/Documentation for Ada bindings to PLplot/README.html -createImageFolder=0 -GenIndex=1 -CopyLinkedImages=1 -CSS=1 -XHTML=1 -HTML=4 -PreserveSpaces=1 -NavLinks=auto -NavImagePath= -trnfile=docbook.trn -DocBookSystem= -DocBookPublic= -charset=UTF-8 -RootElement=book ---> - <chapter> -<title>Ada Language</title> -<!-- 1:'Normal' --><para><emphasis role="bold">Ada Bindings for the PLplot Plotting Package</emphasis></para> -<para><emphasis role="bold"> </emphasis></para> +<chapter> + <title>Ada Language</title> + <!-- 1:'Normal' --><para><emphasis role="bold">Ada Bindings for the PLplot Plotting Package</emphasis></para> + <para><emphasis role="bold"> </emphasis></para> -<orderedlist numeration="arabic" continuation="restarts" spacing="normal"> -<listitem><para><emphasis role="bold">About the This Document</emphasis></para></listitem> -</orderedlist> -<!-- 5:'Normal' --><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> + <orderedlist numeration="arabic" continuation="restarts" spacing="normal"> + <listitem><para><emphasis role="bold">About the This Document</emphasis></para></listitem> + </orderedlist> + <!-- 5:'Normal' --><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> -<orderedlist numeration="arabic" continuation="restarts" spacing="normal"> -<listitem><para><emphasis role="bold">Overview</emphasis></para></listitem> -</orderedlist> -<!-- 7:'Normal' --><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> + <orderedlist numeration="arabic" continuation="restarts" spacing="normal"> + <listitem><para><emphasis role="bold">Overview</emphasis></para></listitem> + </orderedlist> + <!-- 7:'Normal' --><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> -<orderedlist numeration="arabic" continuation="restarts" spacing="normal"> -<listitem><para><emphasis role="bold">The Bindings</emphasis></para></listitem> -</orderedlist> -<!-- 19:'Normal' --><para><emphasis role="bold"> </emphasis>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'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's main concern with programming for PLplot.</para> -<para><emphasis role="bold"> 4.1 Thin Binding</emphasis></para> -<para> The thin binding, in the files plplotthin.ads and plplotthin.adb, 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 plcol0 requires a single integer argument, there is a corresponding Ada program also called plcol0 which also requires a single integer argument. (plcol0 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's type system. Thus, the thin binding refers to the PLplot-centric type PLFLT for floating-point types while the thick binding uses the usual Ada type Long_Float.</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 sensical. 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 subtype-ed or renames-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 with the thin binding.</para> -<para><emphasis role="bold"> 4.2 The Thick Bindings</emphasis></para> -<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 with-ed and use-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 "<emphasis>y</emphasis>'s" as a function of a single "<emphasis>x</emphasis>" with default plot appearances chosen to suit many situations. Other simple plotters are available for three-dimensional and contour plots. Manipulating PLplot'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's type system extensively to reduce the chances of inappropriate actions. For example, Ada arrays are used throughout (as opposed to C's pointer-plus-offset-while-carrying-along-the-size-separately approach). Quantities which have natural range limits are subtype-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 "Ada" names and "PLplot" names. Also, the subroutine-specific comments from the C API have been retained verbatim.</para> -<para><emphasis role="bold"> 4.3 Standard Thick Binding Using Enhanced Names</emphasis></para> -<para> The distinguishing feature of this thick binding (the "standard" 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 plcol0(1) sets the drawing color to red. In the standard thick binding, the same thing is accomplished by writing Set_Color(Red). The Ada program may just as well write Set_Color(1) since the binding merely sets a constant Red to be equal to the integer 1. 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 "normal" PLplot name can be linked to the "Ada" name along with the appropriate entry in the Ada specification, as well as another HTML file with links from the "Ada" 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 "redacted" 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 plplot.ads and plplot.adb.</para> -<para><emphasis role="bold"> 4.4 Thick Binding Using Traditional Names</emphasis></para> -<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 plplot_traditional.ads and plplot_traditional.adb.</para> -<para><emphasis role="bold"> 4.5 Examples</emphasis></para> -<para><emphasis role="bold"> </emphasis>An important part of the Ada bindings is the examples, some 30 of which demonstrate how to use many of the features of the PLplot package. These examples also serve as a testbed 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'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> + <orderedlist numeration="arabic" continuation="restarts" spacing="normal"> + <listitem><para><emphasis role="bold">The Bindings</emphasis></para></listitem> + </orderedlist> + <!-- 19:'Normal' --><para><emphasis role="bold"> </emphasis>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'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's main concern with programming for PLplot.</para> + <para><emphasis role="bold"> 4.1 Thin Binding</emphasis></para> + <para> The thin binding, in the files plplotthin.ads and plplotthin.adb, 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 plcol0 requires a single integer argument, there is a corresponding Ada program also called plcol0 which also requires a single integer argument. (plcol0 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's type system. Thus, the thin binding refers to the PLplot-centric type PLFLT for floating-point types while the thick binding uses the usual Ada type Long_Float.</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 sensical. 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 subtype-ed or renames-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 with the thin binding.</para> + <para><emphasis role="bold"> 4.2 The Thick Bindings</emphasis></para> + <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 with-ed and use-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 "<emphasis>y</emphasis>'s" as a function of a single "<emphasis>x</emphasis>" with default plot appearances chosen to suit many situations. Other simple plotters are available for three-dimensional and contour plots. Manipulating PLplot'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's type system extensively to reduce the chances of inappropriate actions. For example, Ada arrays are used throughout (as opposed to C's pointer-plus-offset-while-carrying-along-the-size-separately approach). Quantities which have natural range limits are subtype-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 "Ada" names and "PLplot" names. Also, the subroutine-specific comments from the C API have been retained verbatim.</para> + <para><emphasis role="bold"> 4.3 Standard Thick Binding Using Enhanced Names</emphasis></para> + <para> The distinguishing feature of this thick binding (the "standard" 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 plcol0(1) sets the drawing color to red. In the standard thick binding, the same thing is accomplished by writing Set_Color(Red). The Ada program may just as well write Set_Color(1) since the binding merely sets a constant Red to be equal to the integer 1. 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 "normal" PLplot name can be linked to the "Ada" name along with the appropriate entry in the Ada specification, as well as another HTML file with links from the "Ada" 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 "redacted" 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 plplot.ads and plplot.adb.</para> + <para><emphasis role="bold"> 4.4 Thick Binding Using Traditional Names</emphasis></para> + <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 plplot_traditional.ads and plplot_traditional.adb.</para> + <para><emphasis role="bold"> 4.5 Examples</emphasis></para> + <para><emphasis role="bold"> </emphasis>An important part of the Ada bindings is the examples, some 30 of which demonstrate how to use many of the features of the PLplot package. These examples also serve as a testbed 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'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> -<orderedlist numeration="arabic" continuation="restarts" spacing="normal"> -<listitem><para><emphasis role="bold">Obtaining the Software</emphasis></para></listitem> -</orderedlist> -<!-- 45:'Normal' --><para> There are three software components that you will need: an Ada compiler, the PLplot library, and the Ada bindings.</para> -<para><emphasis role="bold"> 5.1 Obtaining an Ada compiler</emphasis></para> -<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'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> -<para><emphasis role="bold"> 5.2 Download and install PLplot</emphasis></para> -<para> PLplot can be downloaded from the PLplot home page at <ulink url="http://sourceforge.net/projects/plplot">sourceforge.net—plplot</ulink>. Follow the installation instructions after downloading. The installation process is more involved than other open source software and requires that your computer has cmake installed. OS X users can try installing PLplot in its entirety from MacPorts but that activity is not officially supported by the PLplot developers. The advantage of using MacPorts is that all installation dependencies are automatically installed for you.</para> -<para><emphasis role="bold"> 5.3 Download the Ada bindings to PLplot</emphasis></para> -<para> The third major software component is the bindings themselves. Since they are currently included with the PLplot software itself, there is no need to download them from another place.</para> -<para> The bindings themselves are six Ada source files named (using GNAT filename extensions) plplot.ads, plplot.adb, plplot_traditional.ads, plplot_traditional.adb, plplothin.ads, plplotthin.adb. There are two additional files, plplot_auxiliary.ads and plplot_auxililary.adb which will be discussed later, in Section 9. These can be stored somewhere on your system's search paths for easy access.</para> + <orderedlist numeration="arabic" continuation="restarts" spacing="normal"> + <listitem><para><emphasis role="bold">Obtaining the Software</emphasis></para></listitem> + </orderedlist> + <!-- 45:'Normal' --><para> There are three software components that you will need: an Ada compiler, the PLplot library, and the Ada bindings.</para> + <para><emphasis role="bold"> 5.1 Obtaining an Ada compiler</emphasis></para> + <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'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> + <para><emphasis role="bold"> 5.2 Download and install PLplot</emphasis></para> + <para> PLplot can be downloaded from the PLplot home page at <ulink url="http://sourceforge.net/projects/plplot">sourceforge.net—plplot</ulink>. Follow the installation instructions after downloading. The installation process is more involved than other open source software and requires that your computer has cmake installed. OS X users can try installing PLplot in its entirety from MacPorts but that activity is not officially supported by the PLplot developers. The advantage of using MacPorts is that all installation dependencies are automatically installed for you.</para> + <para><emphasis role="bold"> 5.3 Download the Ada bindings to PLplot</emphasis></para> + <para> The third major software component is the bindings themselves. Since they are currently included with the PLplot software itself, there is no need to download them from another place.</para> + <para> The bindings themselves are six Ada source files named (using GNAT filename extensions) plplot.ads, plplot.adb, plplot_traditional.ads, plplot_traditional.adb, plplothin.ads, plplotthin.adb. There are two additional files, plplot_auxiliary.ads and plplot_auxililary.adb which will be discussed later, in Section 9. These can be stored somewhere on your system's search paths for easy access.</para> -<orderedlist numeration="arabic" continuation="restarts" spacing="normal"> -<listitem><para><emphasis role="bold">How to use the Ada bindings</emphasis></para></listitem> -</orderedlist> -<!-- 55:'Normal' --><para><emphasis role="bold"> 6.1 Ada 95 versus Ada 2005</emphasis></para> -<para> The bindings will work for either Ada 95 or Ada 2005. The only difference that concerns PLplot users is that Ada 2005, in Annex G.3, provides declarations for real-valued vectors and matrices (along with some other functionality). These declarations make available type Real_Vector and type Real_Matrix.</para> -<para> The installation process for PLplot requires you to select Ada 95 or Ada 2005. After that, the correct bindings are generated automatically depending on your choice. The differences are very minor: If Ada 2005, the type declarations provided according to Annex G.3 are used; if Ada 95, similar type declarations are provided. For the most part, you don't need to think about this much. However, see Section 9, Compilation Notes, if you are using Ada 95 and need to declare vectors or matrices. The design goal in either case is to encourage users to use Real_Vector and Real_Matrix since these are the "official" versions of these entities as of Ada 2005. Someone using objects based on these type definitions in Ada 95 in their PLplot programs should expect their programs to work without modification if they should switch to Ada 2005.</para> -<para><emphasis role="bold"> 6.2 GNAT versus non-GNAT</emphasis></para> -<para> The bindings were made using the GNAT compiler and there is a slight dependence on that compiler. Specifically, the Unrestricted_Access attribute of GNAT was used in making the function Matrix_To_Pointers in plplotthin.adb and in a few callbacks. Matrix_To_Pointers is called whenever an Ada matrix (2D array) is passed to a PLplot subroutine. For more about Unrestricted_Access attribute, see Implementation Defined Attributes in the GNAT Reference Manual. This dependency shouldn'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 plplotthin.adb, 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> Most of the GNAT dependencies can be found by searching the source code for "GNAT" and "Unrestricted_Access."</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> -<para><emphasis role="bold"> 6.3 Sample command line project</emphasis></para> -<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 "build directory" and "installation directory."</para> -<para> Here is a simple program that will generate a plot of part of a parabola.</para> -<para> with</para> -<para> PLplot_Auxiliary,</para> -<para> PLplot;</para> -<para>use</para> -<para> PLplot_Auxiliary,</para> -<para> PLplot;</para> -<para>procedure Simple_Example is</para> -<para> x, y : Real_Vector(-10 .. 10);</para> -<para>begin</para> -<para> for i in x'range loop </para> -<para> x(i) := Long_Float(i);</para> -<para> y(i) := x(i)**2;</para> -<para> end loop;</para> -<para> Initialize_PLplot; -- Call this only once.</para> -<para> Simple_Plot(x, y); -- Make the plot.</para> -<para> End_PLplot; -- Call this only once.</para> -<para>end Simple_Example;</para> -<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 them pre-installed.)</para> -<para> </para> -<para>#!/bin/bash</para> -<para>/usr/local/ada-4.3/bin/gnatmake simple_example.adb \</para> -<para>-aI/usr/local/plplot_build_dir/bindings/ada \</para> -<para>-aL/usr/local/plplot_build_dir/bindings/ada/CMakeFiles/plplotadad.dir \</para> -<para>-largs \</para> -<para>/usr/local/plplot/lib/libplplotd.dylib \</para> -<para>/Developer/SDKs/MacOSX10.4u.sdk/usr/lib/libblas.dylib \</para> -<para>/Developer/SDKs/MacOSX10.4u.sdk/usr/lib/liblapack.dylib</para> -<para> Beware of inadvertent line wraps in the above code.</para> -<para> The resulting binary program can be run by typing</para> -<para> ./simple_example</para> + <orderedlist numeration="arabic" continuation="restarts" spacing="normal"> + <listitem><para><emphasis role="bold">How to use the Ada bindings</emphasis></para></listitem> + </orderedlist> + <!-- 55:'Normal' --><para><emphasis role="bold"> 6.1 Ada 95 versus Ada 2005</emphasis></para> + <para> The bindings will work for either Ada 95 or Ada 2005. The only difference that concerns PLplot users is that Ada 2005, in Annex G.3, provides declarations for real-valued vectors and matrices (along with some other functionality). These declarations make available type Real_Vector and type Real_Matrix.</para> + <para> The installation process for PLplot requires you to select Ada 95 or Ada 2005. After that, the correct bindings are generated automatically depending on your choice. The differences are very minor: If Ada 2005, the type declarations provided according to Annex G.3 are used; if Ada 95, similar type declarations are provided. For the most part, you don't need to think about this much. However, see Section 9, Compilation Notes, if you are using Ada 95 and need to declare vectors or matrices. The design goal in either case is to encourage users to use Real_Vector and Real_Matrix since these are the "official" versions of these entities as of Ada 2005. Someone using objects based on these type definitions in Ada 95 in their PLplot programs should expect their programs to work without modification if they should switch to Ada 2005.</para> + <para><emphasis role="bold"> 6.2 GNAT versus non-GNAT</emphasis></para> + <para> The bindings were made using the GNAT compiler and there is a slight dependence on that compiler. Specifically, the Unrestricted_Access attribute of GNAT was used in making the function Matrix_To_Pointers in plplotthin.adb and in a few callbacks. Matrix_To_Pointers is called whenever an Ada matrix (2D array) is passed to a PLplot subroutine. For more about Unrestricted_Access attribute, see Implementation Defined Attributes in the GNAT Reference Manual. This dependency shouldn'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 plplotthin.adb, 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> Most of the GNAT dependencies can be found by searching the source code for "GNAT" and "Unrestricted_Access."</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> + <para><emphasis role="bold"> 6.3 Sample command line project</emphasis></para> + <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 "build directory" and "installation directory."</para> + <para> Here is a simple program that will generate a plot of part of a parabola.</para> + <para> with</para> + <para> PLplot_Auxiliary,</para> + <para> PLplot;</para> + <para>use</para> + <para> PLplot_Auxiliary,</para> + <para> PLplot;</para> + <para>procedure Simple_Example is</para> + <para> x, y : Real_Vector(-10 .. 10);</para> + <para>begin</para> + <para> for i in x'range loop </para> + <para> x(i) := Long_Float(i);</para> + <para> y(i) := x(i)**2;</para> + <para> end loop;</para> + <para> Initialize_PLplot; -- Call this only once.</para> + <para> Simple_Plot(x, y); -- Make the plot.</para> + <para> End_PLplot; -- Call this only once.</para> + <para>end Simple_Example;</para> + <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 them pre-installed.)</para> + <para> </para> + <para>#!/bin/bash</para> + <para>/usr/local/ada-4.3/bin/gnatmake simple_example.adb \</para> + <para>-aI/usr/local/plplot_build_dir/bindings/ada \</para> + <para>-aL/usr/local/plplot_build_dir/bindings/ada/CMakeFiles/plplotadad.dir \</para> + <para>-largs \</para> + <para>/usr/local/plplot/lib/libplplotd.dylib \</para> + <para>/Developer/SDKs/MacOSX10.4u.sdk/usr/lib/libblas.dylib \</para> + <para>/Developer/SDKs/MacOSX10.4u.sdk/usr/lib/liblapack.dylib</para> + <para> Beware of inadvertent line wraps in the above code.</para> + <para> The resulting binary program can be run by typing</para> + <para> ./simple_example</para> -<orderedlist numeration="arabic" continuation="restarts" spacing="normal"> -<listitem><para><emphasis role="bold">Unique Features of the Ada bindings</emphasis></para></listitem> -</orderedlist> -<!-- 102:'Normal' --><para><emphasis role="bold"> </emphasis>The Ada bindings have been augmented with a number of features that are not present in other languages which work with PLplot. These features are intended to greatly simplify the use of PLplot; many users will find that they can do most of their work using these "Simple" plotters. Also included are facilities for easily manipulating the PLplot color tables</para> -<para><emphasis role="bold"> 7.1 High-level features for simplified plotting</emphasis></para> -<para><emphasis role="bold"> Foreground-background control</emphasis></para> -<para> Draw_On_Black, Draw_On_White</para> -<para> The default for PLplot is to draw its graphics on a black background. A white background can be used instead with Draw_On_White or reset to the original mode with Draw_On_Black. Each of these manipulates color map 0 by swapping black and white so that e.g.with Draw_On_White, formerly white lines on a black background autotmatically become black lines on a white background.</para> -<para> <emphasis role="bold">Simple Plotters</emphasis></para> -<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> -<para> Multiplot_Pairs</para> -<para> Plot up to five x-y pairs with easy labeling, coloring, line width and styles, justification, and zooming.</para> -<para> Simple_Plot</para> -<para> Plot up to five <emphasis>y</emphasis>'s against a single <emphasis>x</emphasis> with easy labeling and automatic line colors and styles.</para> -<para> Simple_Plot_Log_X</para> -<para> Same as Simple_Plot but with logarithmic <emphasis>x</emphasis>-axis.</para> -<para> Simple_Plot_Log_Y</para> -<para> Same as Simple_Plot but with logarithmic <emphasis>y</emphasis>-axis.</para> -<para> Simple_Plot_Log_XY</para> -<para> Same as Simple_Plot but with logarithmic <emphasis>x</emphasis>- and <emphasis>y</emphasis>-axes.</para> -<para> Simple_Plot_Pairs</para> -<para> Plot up to five <emphasis>x</emphasis>–<emphasis>y</emphasis> pairs with easy labeling and automatic line colors and styles.</para> -<para> Single_Plot</para> -<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> -<para> Simple_Contour</para> -<para> Make a contour plot with labels</para> -<para> Simple_Mesh_3D</para> -<para> Easy 3D mesh plot with labels, zooming, and perspective controls</para> -<para> Simple_Surface_3D</para> -<para> Easy 3D surface plot with labels, zooming, and perspective controls</para> -<para> <emphasis role="bold">Simple color map manipulations</emphasis></para> -<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 easlily 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 Set_Pen_Color(Red) (plcol0 in the traditional binding) normally does what it says, Red simply has the value 1. If the user changes the color map so that 1 corresponds to another color, then Set_Pen_Color(Red) 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 1, use Set_Pen_Color(Reset_Red) instead. These 16 "reset" 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 Set_Pen_Color(Red) 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, Color_Themes_For_Map_1_Type. These color themes can be quickly applied with Quick_Set_Color_Map_1.</para> -<para> Miscellaneous other Ada features include a pre-built mask function for Shade_Regions 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> -<para> Color table snapshots</para> -<para> Make_Snapshot_Of_Color_Map_0</para> -<para> Restore_Snapshot_Of_Color_Map_0</para> -<para> Restore_Default_Snapshot_Of_Color_Map_0</para> -<para> Color resetting functions for the 16 colors of color map 0</para> -<para> Reset_Black, Reset_Red, … Reset_White</para> -<para> Easy manipulation of color map 1</para> -<para> Pre-built color themes for color map 1: Color_Themes_For_Map_1_Type</para> -<para> Quick application of pre-built color themes: Quick_Set_Color_Map_1</para> -<para> Other features</para> -<para> A pre-built mask function for Shade_Regions that does no masking: Mask_Function_No_Mask</para> -<para> An easy way to calculate an array of contour levels for contour plots: Calculate_Contour_Levels</para> -<para><emphasis role="bold"> 7.2 Integer-options Given Ada Names</emphasis></para> -<para><emphasis role="bold"> </emphasis>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 "re-namings" 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> Colors: Plot_Color_Type</para> -<para> 0 is Black, 1 is Red, etc.</para> -<para> Justification for plots: Justification_Type</para> -<para> User_Justified</para> -<para> Not_Justified</para> -<para> Justified</para> -<para> Justified_Square_Box</para> -<para> Axis styles: Axis_Style_Type</para> -<para> Linear_Major_Grid</para> -<para> Linear_Minor_Grid</para> -<para> etc.</para> -<para> Font styles: Font_Style_Type</para> -<para> Normal_Font</para> -<para> Roman_Font</para> -<para> Italic_Font</para> -<para> Script_Font</para> -<para> Character sets: Character_Set_Type</para> -<para> Standard_Character_Set</para> -<para> Extended_Character_Set</para> -<para> Plot orientation: Orientation_Type</para> -<para> Landscape</para> -<para> Portrait</para> -<para> Modes for parsing command line arguments: Parse_Mode_Type</para> -<para> E.g. PL_PARSE_PARTIAL</para> -<para> Descriptions of map outlines (continents, states, etc.): Map_Type</para> -<para> Continents</para> -<para> USA_and_States</para> -<para> Continents_and_Countries</para> -<para> USA_States_and_Continents</para> -<para> Various style and view options for 3D and surface plots</para> -<para> E.g. Lines_Parallel_To_X</para> -<para> Kind of gridding algorithm for interpolating 2D data to a grid: Gridding_Algorithm_Type</para> -<para> E.g. Grid_Bivariate_Cubic_Spline_Approximation</para> -<para> Flags for histogram style</para> -<para> E.g. Histogram_Default</para> -<para> Flags for histogram binning</para> -<para> E.g. Bin_Default</para> -<para> Names for color space models</para> -<para> Hue, Lightness, Saturation: HLS</para> -<para> Red, Green, Blue: RGB</para> -<para><emphasis role="bold"> 7.3 One-offs</emphasis></para> -<para> Convenient string handling for Get_Device_Name (plgdev in the traditional binding); a function version is provided that simplifies the string handling associated with this feature.</para> -<para> Overloaded Set_Line_Style (plstyl in the traditional binding) with a version that takes a single argument, Default_Continuous_Line. 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 Contour_Plot_Irregular_Data (plfcont 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> + <orderedlist numeration="arabic" continuation="restarts" spacing="normal"> + <listitem><para><emphasis role="bold">Unique Features of the Ada bindings</emphasis></para></listitem> + </orderedlist> + <!-- 102:'Normal' --><para><emphasis role="bold"> </emphasis>The Ada bindings have been augmented with a number of features that are not present in other languages which work with PLplot. These features are intended to greatly simplify the use of PLplot; many users will find that they can do most of their work using these "Simple" plotters. Also included are facilities for easily manipulating the PLplot color tables</para> + <para><emphasis role="bold"> 7.1 High-level features for simplified plotting</emphasis></para> + <para><emphasis role="bold"> Foreground-background control</emphasis></para> + <para> Draw_On_Black, Draw_On_White</para> + <para> The default for PLplot is to draw its graphics on a black background. A white background can be used instead with Draw_On_White or reset to the original mode with Draw_On_Black. Each of these manipulates color map 0 by swapping black and white so that e.g.with Draw_On_White, formerly white lines on a black background autotmatically become black lines on a white background.</para> + <para> <emphasis role="bold">Simple Plotters</emphasis></para> + <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> + <para> Multiplot_Pairs</para> + <para> Plot up to five x-y pairs with easy labeling, coloring, line width and styles, justification, and zooming.</para> + <para> Simple_Plot</para> + <para> Plot up to five <emphasis>y</emphasis>'s against a single <emphasis>x</emphasis> with easy labeling and automatic line colors and styles.</para> + <para> Simple_Plot_Log_X</para> + <para> Same as Simple_Plot but with logarithmic <emphasis>x</emphasis>-axis.</para> + <para> Simple_Plot_Log_Y</para> + <para> Same as Simple_Plot but with logarithmic <emphasis>y</emphasis>-axis.</para> + <para> Simple_Plot_Log_XY</para> + <para> Same as Simple_Plot but with logarithmic <emphasis>x</emphasis>- and <emphasis>y</emphasis>-axes.</para> + <para> Simple_Plot_Pairs</para> + <para> Plot up to five <emphasis>x</emphasis>–<emphasis>y</emphasis> pairs with easy labeling and automatic line colors and styles.</para> + <para> Single_Plot</para> + <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> + <para> Simple_Contour</para> + <para> Make a contour plot with labels</para> + <para> Simple_Mesh_3D</para> + <para> Easy 3D mesh plot with labels, zooming, and perspective controls</para> + <para> Simple_Surface_3D</para> + <para> Easy 3D surface plot with labels, zooming, and perspective controls</para> + <para> <emphasis role="bold">Simple color map manipulations</emphasis></para> + <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 easlily 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 Set_Pen_Color(Red) (plcol0 in the traditional binding) normally does what it says, Red simply has the value 1. If the user changes the color map so that 1 corresponds to another color, then Set_Pen_Color(Red) 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 1, use Set_Pen_Color(Reset_Red) instead. These 16 "reset" 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 Set_Pen_Color(Red) 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, Color_Themes_For_Map_1_Type. These color themes can be quickly applied with Quick_Set_Color_Map_1.</para> + <para> Miscellaneous other Ada features include a pre-built mask function for Shade_Regions 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> + <para> Color table snapshots</para> + <para> Make_Snapshot_Of_Color_Map_0</para> + <para> Restore_Snapshot_Of_Color_Map_0</para> + <para> Restore_Default_Snapshot_Of_Color_Map_0</para> + <para> Color resetting functions for the 16 colors of color map 0</para> + <para> Reset_Black, Reset_Red, … Reset_White</para> + <para> Easy manipulation of color map 1</para> + <para> Pre-built color themes for color map 1: Color_Themes_For_Map_1_Type</para> + <para> Quick application of pre-built color themes: Quick_Set_Color_Map_1</para> + <para> Other features</para> + <para> A pre-built mask function for Shade_Regions that does no masking: Mask_Function_No_Mask</para> + <para> An easy way to calculate an array of contour levels for contour plots: Calculate_Contour_Levels</para> + <para><emphasis role="bold"> 7.2 Integer-options Given Ada Names</emphasis></para> + <para><emphasis role="bold"> </emphasis>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 "re-namings" 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> Colors: Plot_Color_Type</para> + <para> 0 is Black, 1 is Red, etc.</para> + <para> Justification for plots: Justification_Type</para> + <para> User_Justified</para> + <para> Not_Justified</para> + <para> Justified</para> + <para> Justified_Square_Box</para> + <para> Axis styles: Axis_Style_Type</para> + <para> Linear_Major_Grid</para> + <para> Linear_Minor_Grid</para> + <para> etc.</para> + <para> Font styles: Font_Style_Type</para> + <para> Normal_Font</para> + <para> Roman_Font</para> + <para> Italic_Font</para> + <para> Script_Font</para> + <para> Character sets: Character_Set_Type</para> + <para> Standard_Character_Set</para> + <para> Extended_Character_Set</para> + <para> Plot orientation: Orientation_Type</para> + <para> Landscape</para> + <para> Portrait</para> + <para> Modes for parsing command line arguments: Parse_Mode_Type</para> + <para> E.g. PL_PARSE_PARTIAL</para> + <para> Descriptions of map outlines (continents, states, etc.): Map_Type</para> + <para> Continents</para> + <para> USA_and_States</para> + <para> Continents_and_Countries</para> + <para> USA_States_and_Continents</para> + <para> Various style and view options for 3D and surface plots</para> + <para> E.g. Lines_Parallel_To_X</para> + <para> Kind of gridding algorithm for interpolating 2D data to a grid: Gridding_Algorithm_Type</para> + <para> E.g. Grid_Bivariate_Cubic_Spline_Approximation</para> + <para> Flags for histogram style</para> + <para> E.g. Histogram_Default</para> + <para> Flags for histogram binning</para> + <para> E.g. Bin_Default</para> + <para> Names for color space models</para> + <para> Hue, Lightness, Saturation: HLS</para> + <para> Red, Green, Blue: RGB</para> + <para><emphasis role="bold"> 7.3 One-offs</emphasis></para> + <para> Convenient string handling for Get_Device_Name (plgdev in the traditional binding); a function version is provided that simplifies the string handling associated with this feature.</para> + <para> Overloaded Set_Line_Style (plstyl in the traditional binding) with a version that takes a single argument, Default_Continuous_Line. 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 Contour_Plot_Irregular_Data (plfcont 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> -<orderedlist numeration="arabic" continuation="restarts" spacing="normal"> -<listitem><para><emphasis role="bold">Parts That Retain a C Flavor</emphasis></para></listitem> -</orderedlist> -<!-- 195:'Normal' --><para><emphasis role="bold"> </emphasis>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> -<para><emphasis role="bold"> 8.1 Map-drawing</emphasis></para> -<para> plmapform as called by Draw_Latitude_Longitude (plmap) and Draw_Latitude_Longitude (plmeridians)</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 0 .. 2000. See Example 19 for how this is handled in by the user program. The constrained array is called Map_Form_Constrained_Array.</para> + <orderedlist numeration="arabic" continuation="restarts" spacing="normal"> + <listitem><para><emphasis role="bold">Parts That Retain a C Flavor</emphasis></para></listitem> + </orderedlist> + <!-- 195:'Normal' --><para><emphasis role="bold"> </emphasis>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> + <para><emphasis role="bold"> 8.1 Map-drawing</emphasis></para> + <para> plmapform as called by Draw_Latitude_Longitude (plmap) and Draw_Latitude_Longitude (plmeridians)</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 fo... [truncated message content] |
From: <ai...@us...> - 2008-09-10 20:38:25
|
Revision: 8770 http://plplot.svn.sourceforge.net/plplot/?rev=8770&view=rev Author: airwin Date: 2008-09-10 20:38:35 +0000 (Wed, 10 Sep 2008) Log Message: ----------- Move to sections style like the rest of PLplot docbook documentation. Modified Paths: -------------- trunk/doc/docbook/src/ada.xml Modified: trunk/doc/docbook/src/ada.xml =================================================================== --- trunk/doc/docbook/src/ada.xml 2008-09-10 17:31:17 UTC (rev 8769) +++ trunk/doc/docbook/src/ada.xml 2008-09-10 20:38:35 UTC (rev 8770) @@ -33,253 +33,298 @@ --> -<chapter> +<chapter id="ada"> <title>Ada Language</title> - <!-- 1:'Normal' --><para><emphasis role="bold">Ada Bindings for the PLplot Plotting Package</emphasis></para> - <para><emphasis role="bold"> </emphasis></para> + <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> - <orderedlist numeration="arabic" continuation="restarts" spacing="normal"> - <listitem><para><emphasis role="bold">About the This Document</emphasis></para></listitem> - </orderedlist> - <!-- 5:'Normal' --><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"> - <orderedlist numeration="arabic" continuation="restarts" spacing="normal"> - <listitem><para><emphasis role="bold">Overview</emphasis></para></listitem> - </orderedlist> - <!-- 7:'Normal' --><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> + <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'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's main concern with programming for PLplot.</para> + <sect2 id="ada_thin"> + <title>Thin Binding</title> + <para> The thin binding, in the files plplotthin.ads and plplotthin.adb, 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 plcol0 requires a single integer argument, there is a corresponding Ada program also called plcol0 which also requires a single integer argument. (plcol0 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's type system. Thus, the thin binding refers to the PLplot-centric type PLFLT for floating-point types while the thick binding uses the usual Ada type Long_Float.</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 sensical. 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 subtype-ed or renames-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 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 with-ed and use-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 "<emphasis>y</emphasis>'s" as a function of a single "<emphasis>x</emphasis>" with default plot appearances chosen to suit many situations. Other simple plotters are available for three-dimensional and contour plots. Manipulating PLplot'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's type system extensively to reduce the chances of inappropriate actions. For example, Ada arrays are used throughout (as opposed to C's pointer-plus-offset-while-carrying-along-the-size-separately approach). Quantities which have natural range limits are subtype-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 "Ada" names and "PLplot" 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 "standard" 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 plcol0(1) sets the drawing color to red. In the standard thick binding, the same thing is accomplished by writing Set_Color(Red). The Ada program may just as well write Set_Color(1) since the binding merely sets a constant Red to be equal to the integer 1. 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 "normal" PLplot name can be linked to the "Ada" name along with the appropriate entry in the Ada specification, as well as another HTML file with links from the "Ada" 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 "redacted" 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 plplot.ads and plplot.adb.</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 plplot_traditional.ads and plplot_traditional.adb.</para> + </sect2> + </sect1> + <sect1 id="ada_examples"> + <title> The Examples</title> + <para> An important part of the Ada bindings is the examples, some 30 of which demonstrate how to use many of the features of the PLplot package. These examples also serve as a testbed 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'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'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 home page at <ulink url="http://sourceforge.net/projects/plplot">sourceforge.net—plplot</ulink>. Follow the installation instructions after downloading. The installation process is more involved than other open source software and requires that your computer has cmake installed. OS X users can try installing PLplot in its entirety from MacPorts but that activity is not officially supported by the PLplot developers. The advantage of using MacPorts is that all installation dependencies are automatically installed for you.</para> + </sect2> + <sect2 id="ada_obtaining_bindings"> + <title>Download the Ada bindings to PLplot</title> + <para> The third major software component is the bindings themselves. Since they are currently included with the PLplot software itself, there is no need to download them from another place.</para> + <para> The bindings themselves are six Ada source files named (using GNAT filename extensions) plplot.ads, plplot.adb, plplot_traditional.ads, plplot_traditional.adb, plplothin.ads, plplotthin.adb. There are two additional files, plplot_auxiliary.ads and plplot_auxililary.adb which will be discussed later, in Section 9. These can be stored somewhere on your system's search paths for easy access.</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. The only difference that concerns PLplot users is that Ada 2005, in Annex G.3, provides declarations for real-valued vectors and matrices (along with some other functionality). These declarations make available type Real_Vector and type Real_Matrix.</para> + <para> The installation process for PLplot requires you to select Ada 95 or Ada 2005. After that, the correct bindings are generated automatically depending on your choice. The differences are very minor: If Ada 2005, the type declarations provided according to Annex G.3 are used; if Ada 95, similar type declarations are provided. For the most part, you don't need to think about this much. However, see Section 9, Compilation Notes, if you are using Ada 95 and need to declare vectors or matrices. The design goal in either case is to encourage users to use Real_Vector and Real_Matrix since these are the "official" versions of these entities as of Ada 2005. Someone using objects based on these type definitions in Ada 95 in their PLplot programs should expect their programs to work without modification if they should switch to Ada 2005.</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 Unrestricted_Access attribute of GNAT was used in making the function Matrix_To_Pointers in plplotthin.adb and in a few callbacks. Matrix_To_Pointers is called whenever an Ada matrix (2D array) is passed to a PLplot subroutine. For more about Unrestricted_Access attribute, see Implementation Defined Attributes in the GNAT Reference Manual. This dependency shouldn'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 plplotthin.adb, 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> Most of the GNAT dependencies can be found by searching the source code for "GNAT" and "Unrestricted_Access."</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 "build directory" and "installation directory."</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'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 them 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> - <orderedlist numeration="arabic" continuation="restarts" spacing="normal"> - <listitem><para><emphasis role="bold">The Bindings</emphasis></para></listitem> - </orderedlist> - <!-- 19:'Normal' --><para><emphasis role="bold"> </emphasis>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'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's main concern with programming for PLplot.</para> - <para><emphasis role="bold"> 4.1 Thin Binding</emphasis></para> - <para> The thin binding, in the files plplotthin.ads and plplotthin.adb, 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 plcol0 requires a single integer argument, there is a corresponding Ada program also called plcol0 which also requires a single integer argument. (plcol0 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's type system. Thus, the thin binding refers to the PLplot-centric type PLFLT for floating-point types while the thick binding uses the usual Ada type Long_Float.</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 sensical. 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 subtype-ed or renames-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 with the thin binding.</para> - <para><emphasis role="bold"> 4.2 The Thick Bindings</emphasis></para> - <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 with-ed and use-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 "<emphasis>y</emphasis>'s" as a function of a single "<emphasis>x</emphasis>" with default plot appearances chosen to suit many situations. Other simple plotters are available for three-dimensional and contour plots. Manipulating PLplot'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's type system extensively to reduce the chances of inappropriate actions. For example, Ada arrays are used throughout (as opposed to C's pointer-plus-offset-while-carrying-along-the-size-separately approach). Quantities which have natural range limits are subtype-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 "Ada" names and "PLplot" names. Also, the subroutine-specific comments from the C API have been retained verbatim.</para> - <para><emphasis role="bold"> 4.3 Standard Thick Binding Using Enhanced Names</emphasis></para> - <para> The distinguishing feature of this thick binding (the "standard" 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 plcol0(1) sets the drawing color to red. In the standard thick binding, the same thing is accomplished by writing Set_Color(Red). The Ada program may just as well write Set_Color(1) since the binding merely sets a constant Red to be equal to the integer 1. 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 "normal" PLplot name can be linked to the "Ada" name along with the appropriate entry in the Ada specification, as well as another HTML file with links from the "Ada" 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 "redacted" 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 plplot.ads and plplot.adb.</para> - <para><emphasis role="bold"> 4.4 Thick Binding Using Traditional Names</emphasis></para> - <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 plplot_traditional.ads and plplot_traditional.adb.</para> - <para><emphasis role="bold"> 4.5 Examples</emphasis></para> - <para><emphasis role="bold"> </emphasis>An important part of the Ada bindings is the examples, some 30 of which demonstrate how to use many of the features of the PLplot package. These examples also serve as a testbed 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'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> + </sect2> + </sect1> - <orderedlist numeration="arabic" continuation="restarts" spacing="normal"> - <listitem><para><emphasis role="bold">Obtaining the Software</emphasis></para></listitem> - </orderedlist> - <!-- 45:'Normal' --><para> There are three software components that you will need: an Ada compiler, the PLplot library, and the Ada bindings.</para> - <para><emphasis role="bold"> 5.1 Obtaining an Ada compiler</emphasis></para> - <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'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> - <para><emphasis role="bold"> 5.2 Download and install PLplot</emphasis></para> - <para> PLplot can be downloaded from the PLplot home page at <ulink url="http://sourceforge.net/projects/plplot">sourceforge.net—plplot</ulink>. Follow the installation instructions after downloading. The installation process is more involved than other open source software and requires that your computer has cmake installed. OS X users can try installing PLplot in its entirety from MacPorts but that activity is not officially supported by the PLplot developers. The advantage of using MacPorts is that all installation dependencies are automatically installed for you.</para> - <para><emphasis role="bold"> 5.3 Download the Ada bindings to PLplot</emphasis></para> - <para> The third major software component is the bindings themselves. Since they are currently included with the PLplot software itself, there is no need to download them from another place.</para> - <para> The bindings themselves are six Ada source files named (using GNAT filename extensions) plplot.ads, plplot.adb, plplot_traditional.ads, plplot_traditional.adb, plplothin.ads, plplotthin.adb. There are two additional files, plplot_auxiliary.ads and plplot_auxililary.adb which will be discussed later, in Section 9. These can be stored somewhere on your system's search paths for easy access.</para> + <sect1 id="ada_unique"> + <title>Unique Features of the Ada bindings</title> + <para>The Ada bindings have been augmented with a number of features that are not present in other languages which work with PLplot. These features are intended to greatly simplify the use of PLplot; many users will find that they can do most of their work using these "Simple" plotters. Also included are facilities for easily manipulating the PLplot color tables</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 Draw_On_White or reset to the original mode with Draw_On_Black. Each of these manipulates color map 0 by swapping black and white so that e.g.with Draw_On_White, formerly white lines on a black background autotmatically 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 x-y pairs with easy labeling, 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>'s against a single <emphasis>x</emphasis> with easy labeling and automatic line colors and styles.</para> + </sect4> + <sect4 id="ada_simple_plot_logx"> + <title> Simple_Plot_Log_X</title> + <para> Same as Simple_Plot but with logarithmic <emphasis>x</emphasis>-axis.</para> + </sect4> + <sect4 id="ada_simple_plot_logy"> + <title>Simple_Plot_Log_Y</title> + <para> Same as Simple_Plot but with logarithmic <emphasis>y</emphasis>-axis.</para> + </sect4> + <sect4 id="ada_simple_plot_logxy"> + <title>Simple_Plot_Log_XY</title> + <para> Same as Simple_Plot 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 labeling 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 easlily 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 Set_Pen_Color(Red) (plcol0 in the traditional binding) normally does what it says, Red simply has the value 1. If the user changes the color map so that 1 corresponds to another color, then Set_Pen_Color(Red) 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 1, use Set_Pen_Color(Reset_Red) instead. These 16 "reset" 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 Set_Pen_Color(Red) 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, Color_Themes_For_Map_1_Type. These color themes can be quickly applied with Quick_Set_Color_Map_1.</para> + <para> Miscellaneous other Ada features include a pre-built mask function for Shade_Regions 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> + <para> Color table snapshots</para> + <para> Make_Snapshot_Of_Color_Map_0</para> + <para> Restore_Snapshot_Of_Color_Map_0</para> + <para> Restore_Default_Snapshot_Of_Color_Map_0</para> + <para> Color resetting functions for the 16 colors of color map 0</para> + <para> Reset_Black, Reset_Red, … Reset_White</para> + <para> Easy manipulation of color map 1</para> + <para> Pre-built color themes for color map 1: Color_Themes_For_Map_1_Type</para> + <para> Quick application of pre-built color themes: Quick_Set_Color_Map_1</para> + <para> Other features</para> + <para> A pre-built mask function for Shade_Regions that does no masking: Mask_Function_No_Mask</para> + <para> An easy way to calculate an array of contour levels for contour plots: Calculate_Contour_Levels</para> + </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 "re-namings" 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> Colors: Plot_Color_Type</para> + <para> 0 is Black, 1 is Red, etc.</para> + <para> Justification for plots: Justification_Type</para> + <para> User_Justified</para> + <para> Not_Justified</para> + <para> Justified</para> + <para> Justified_Square_Box</para> + <para> Axis styles: Axis_Style_Type</para> + <para> Linear_Major_Grid</para> + <para> Linear_Minor_Grid</para> + <para> etc.</para> + <para> Font styles: Font_Style_Type</para> + <para> Normal_Font</para> + <para> Roman_Font</para> + <para> Italic_Font</para> + <para> Script_Font</para> + <para> Character sets: Character_Set_Type</para> + <para> Standard_Character_Set</para> + <para> Extended_Character_Set</para> + <para> Plot orientation: Orientation_Type</para> + <para> Landscape</para> + <para> Portrait</para> + <para> Modes for parsing command line arguments: Parse_Mode_Type</para> + <para> E.g. PL_PARSE_PARTIAL</para> + <para> Descriptions of map outlines (continents, states, etc.): Map_Type</para> + <para> Continents</para> + <para> USA_and_States</para> + <para> Continents_and_Countries</para> + <para> USA_States_and_Continents</para> + <para> Various style and view options for 3D and surface plots</para> + <para> E.g. Lines_Parallel_To_X</para> + <para> Kind of gridding algorithm for interpolating 2D data to a grid: Gridding_Algorithm_Type</para> + <para> E.g. Grid_Bivariate_Cubic_Spline_Approximation</para> + <para> Flags for histogram style</para> + <para> E.g. Histogram_Default</para> + <para> Flags for histogram binning</para> + <para> E.g. Bin_Default</para> + <para> Names for color space models</para> + <para> Hue, Lightness, Saturation: HLS</para> + <para> Red, Green, Blue: RGB</para> + </sect2> + <sect2 id="ada_one_offs"> + <title>One-offs</title> + <para> Convenient string handling for Get_Device_Name (plgdev in the traditional binding); a function version is provided that simplifies the string handling associated with this feature.</para> + <para> Overloaded Set_Line_Style (plstyl in the traditional binding) with a version that takes a single argument, Default_Continuous_Line. 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 Contour_Plot_Irregular_Data (plfcont 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> + </sect2> + </sect1> + <sect1 id="ada_c_flavor"> + <title>Parts That Retain a C Flavor</title> + <!-- 195:'Normal' --><para><emphasis role="bold"> </emphasis>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> + <para><emphasis role="bold"> 8.1 Map-drawing</emphasis></para> + <para> plmapform as called by Draw_Latitude_Longitude (plmap) and Draw_Latitude_Longitude (plmeridians)</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 0 .. 2000. See Example 19 for how this is handled in by the user program. The constrained array is called Map_Form_Constrained_Array.</para> - <orderedlist numeration="arabic" continuation="restarts" spacing="normal"> - <listitem><para><emphasis role="bold">How to use the Ada bindings</emphasis></para></listitem> - </orderedlist> - <!-- 55:'Normal' --><para><emphasis role="bold"> 6.1 Ada 95 versus Ada 2005</emphasis></para> - <para> The bindings will work for either Ada 95 or Ada 2005. The only difference that concerns PLplot users is that Ada 2005, in Annex G.3, provides declarations for real-valued vectors and matrices (along with some other functionality). These declarations make available type Real_Vector and type Real_Matrix.</para> - <para> The installation process for PLplot requires you to select Ada 95 or Ada 2005. After that, the correct bindings are generated automatically depending on your choice. The differences are very minor: If Ada 2005, the type declarations provided according to Annex G.3 are used; if Ada 95, similar type declarations are provided. For the most part, you don't need to think about this much. However, see Section 9, Compilation Notes, if you are using Ada 95 and need to declare vectors or matrices. The design goal in either case is to encourage users to use Real_Vector and Real_Matrix since these are the "official" versions of these entities as of Ada 2005. Someone using objects based on these type definitions in Ada 95 in their PLplot programs should expect their programs to work without modification if they should switch to Ada 2005.</para> - <para><emphasis role="bold"> 6.2 GNAT versus non-GNAT</emphasis></para> - <para> The bindings were made using the GNAT compiler and there is a slight dependence on that compiler. Specifically, the Unrestricted_Access attribute of GNAT was used in making the function Matrix_To_Pointers in plplotthin.adb and in a few callbacks. Matrix_To_Pointers is called whenever an Ada matrix (2D array) is passed to a PLplot subroutine. For more about Unrestricted_Access attribute, see Implementation Defined Attributes in the GNAT Reference Manual. This dependency shouldn'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 plplotthin.adb, 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> Most of the GNAT dependencies can be found by searching the source code for "GNAT" and "Unrestricted_Access."</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> - <para><emphasis role="bold"> 6.3 Sample command line project</emphasis></para> - <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 "build directory" and "installation directory."</para> - <para> Here is a simple program that will generate a plot of part of a parabola.</para> - <para> with</para> - <para> PLplot_Auxiliary,</para> - <para> PLplot;</para> - <para>use</para> - <para> PLplot_Auxiliary,</para> - <para> PLplot;</para> - <para>procedure Simple_Example is</para> - <para> x, y : Real_Vector(-10 .. 10);</para> - <para>begin</para> - <para> for i in x'range loop </para> - <para> x(i) := Long_Float(i);</para> - <para> y(i) := x(i)**2;</para> - <para> end loop;</para> - <para> Initialize_PLplot; -- Call this only once.</para> - <para> Simple_Plot(x, y); -- Make the plot.</para> - <para> End_PLplot; -- Call this only once.</para> - <para>end Simple_Example;</para> - <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 them pre-installed.)</para> - <para> </para> - <para>#!/bin/bash</para> - <para>/usr/local/ada-4.3/bin/gnatmake simple_example.adb \</para> - <para>-aI/usr/local/plplot_build_dir/bindings/ada \</para> - <para>-aL/usr/local/plplot_build_dir/bindings/ada/CMakeFiles/plplotadad.dir \</para> - <para>-largs \</para> - <para>/usr/local/plplot/lib/libplplotd.dylib \</para> - <para>/Developer/SDKs/MacOSX10.4u.sdk/usr/lib/libblas.dylib \</para> - <para>/Developer/SDKs/MacOSX10.4u.sdk/usr/lib/liblapack.dylib</para> - <para> Beware of inadvertent line wraps in the above code.</para> - <para> The resulting binary program can be run by typing</para> - <para> ./simple_example</para> + </sect1> + <sect1 id="ada_known_issues"> + <title>Known Issues</title> + <!-- 200:'Normal' --><para><emphasis role="bold"> 9.1 Stripchart labelling</emphasis></para> + <para> In Example 17, all of the stripchart labels are the same regardless of the fact that the calling program sets them to be different. This is likely to affect user programs in the same manner.</para> + <para><emphasis role="bold"> 9.2 Documentation</emphasis></para> + <para> In numerous places in the documentation, a feature is listed or described as "C only." Many of these features are actually available in Ada. For example, in Contour_Plot (plcont in the traditional binding), the transformation from array indices to world coordinates is mentioned as "C only" but is actually available in Ada.</para> - <orderedlist numeration="arabic" continuation="restarts" spacing="normal"> - <listitem><para><emphasis role="bold">Unique Features of the Ada bindings</emphasis></para></listitem> - </orderedlist> - <!-- 102:'Normal' --><para><emphasis role="bold"> </emphasis>The Ada bindings have been augmented with a number of features that are not present in other languages which work with PLplot. These features are intended to greatly simplify the use of PLplot; many users will find that they can do most of their work using these "Simple" plotters. Also included are facilities for easily manipulating the PLplot color tables</para> - <para><emphasis role="bold"> 7.1 High-level features for simplified plotting</emphasis></para> - <para><emphasis role="bold"> Foreground-background control</emphasis></para> - <para> Draw_On_Black, Draw_On_White</para> - <para> The default for PLplot is to draw its graphics on a black background. A white background can be used instead with Draw_On_White or reset to the original mode with Draw_On_Black. Each of these manipulates color map 0 by swapping black and white so that e.g.with Draw_On_White, formerly white lines on a black background autotmatically become black lines on a white background.</para> - <para> <emphasis role="bold">Simple Plotters</emphasis></para> - <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> - <para> Multiplot_Pairs</para> - <para> Plot up to five x-y pairs with easy labeling, coloring, line width and styles, justification, and zooming.</para> - <para> Simple_Plot</para> - <para> Plot up to five <emphasis>y</emphasis>'s against a single <emphasis>x</emphasis> with easy labeling and automatic line colors and styles.</para> - <para> Simple_Plot_Log_X</para> - <para> Same as Simple_Plot but with logarithmic <emphasis>x</emphasis>-axis.</para> - <para> Simple_Plot_Log_Y</para> - <para> Same as Simple_Plot but with logarithmic <emphasis>y</emphasis>-axis.</para> - <para> Simple_Plot_Log_XY</para> - <para> Same as Simple_Plot but with logarithmic <emphasis>x</emphasis>- and <emphasis>y</emphasis>-axes.</para> - <para> Simple_Plot_Pairs</para> - <para> Plot up to five <emphasis>x</emphasis>–<emphasis>y</emphasis> pairs with easy labeling and automatic line colors and styles.</para> - <para> Single_Plot</para> - <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> - <para> Simple_Contour</para> - <para> Make a contour plot with labels</para> - <para> Simple_Mesh_3D</para> - <para> Easy 3D mesh plot with labels, zooming, and perspective controls</para> - <para> Simple_Surface_3D</para> - <para> Easy 3D surface plot with labels, zooming, and perspective controls</para> - <para> <emphasis role="bold">Simple color map manipulations</emphasis></para> - <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 easlily 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 Set_Pen_Color(Red) (plcol0 in the traditional binding) normally does what it says, Red simply has the value 1. If the user changes the color map so that 1 corresponds to another color, then Set_Pen_Color(Red) 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 1, use Set_Pen_Color(Reset_Red) instead. These 16 "reset" 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 Set_Pen_Color(Red) 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, Color_Themes_For_Map_1_Type. These color themes can be quickly applied with Quick_Set_Color_Map_1.</para> - <para> Miscellaneous other Ada features include a pre-built mask function for Shade_Regions 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> - <para> Color table snapshots</para> - <para> Make_Snapshot_Of_Color_Map_0</para> - <para> Restore_Snapshot_Of_Color_Map_0</para> - <para> Restore_Default_Snapshot_Of_Color_Map_0</para> - <para> Color resetting functions for the 16 colors of color map 0</para> - <para> Reset_Black, Reset_Red, … Reset_White</para> - <para> Easy manipulation of color map 1</para> - <para> Pre-built color themes for color map 1: Color_Themes_For_Map_1_Type</para> - <para> Quick application of pre-built color themes: Quick_Set_Color_Map_1</para> - <para> Other features</para> - <para> A pre-built mask function for Shade_Regions that does no masking: Mask_Function_No_Mask</para> - <para> An easy way to calculate an array of contour levels for contour plots: Calculate_Contour_Levels</para> - <para><emphasis role="bold"> 7.2 Integer-options Given Ada Names</emphasis></para> - <para><emphasis role="bold"> </emphasis>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 "re-namings" 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> Colors: Plot_Color_Type</para> - <para> 0 is Black, 1 is Red, etc.</para> - <para> Justification for plots: Justification_Type</para> - <para> User_Justified</para> - <para> Not_Justified</para> - <para> Justified</para> - <para> Justified_Square_Box</para> - <para> Axis styles: Axis_Style_Type</para> - <para> Linear_Major_Grid</para> - <para> Linear_Minor_Grid</para> - <para> etc.</para> - <para> Font styles: Font_Style_Type</para> - <para> Normal_Font</para> - <para> Roman_Font</para> - <para> Italic_Font</para> - <para> Script_Font</para> - <para> Character sets: Character_Set_Type</para> - <para> Standard_Character_Set</para> - <para> Extended_Character_Set</para> - <para> Plot orientation: Orientation_Type</para> - <para> Landscape</para> - <para> Portrait</para> - <para> Modes for parsing command line arguments: Parse_Mode_Type</para> - <para> E.g. PL_PARSE_PARTIAL</para> - <para> Descriptions of map outlines (continents, states, etc.): Map_Type</para> - <para> Continents</para> - <para> USA_and_States</para> - <para> Continents_and_Countries</para> - <para> USA_States_and_Continents</para> - <para> Various style and view options for 3D and surface plots</para> - <para> E.g. Lines_Parallel_To_X</para> - <para> Kind of gridding algorithm for interpolating 2D data to a grid: Gridding_Algorithm_Type</para> - <para> E.g. Grid_Bivariate_Cubic_Spline_Approximation</para> - <para> Flags for histogram style</para> - <para> E.g. Histogram_Default</para> - <para> Flags for histogram binning</para> - <para> E.g. Bin_Default</para> - <para> Names for color space models</para> - <para> Hue, Lightness, Saturation: HLS</para> - <para> Red, Green, Blue: RGB</para> - <para><emphasis role="bold"> 7.3 One-offs</emphasis></para> - <para> Convenient string handling for Get_Device_Name (plgdev in the traditional binding); a function version is provided that simplifies the string handling associated with this feature.</para> - <para> Overloaded Set_Line_Style (plstyl in the traditional binding) with a version that takes a single argument, Default_Continuous_Line. 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 Contour_Plot_Irregular_Data (plfcont 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> + </sect1> + <sect1 id="ada_compilation_notes"> + <title>Compilation notes</title> + <!-- 205:'Normal' --><para><emphasis role="bold"> 10.1 Ada 95 Versus Ada 2005</emphasis></para> + <para> As discussed in Section 6.1, the bindings are made to work with Ada 95 but to also take advantage of the Annex G.3 (vector-matrix) features of Ada 2005. Actually, this adaptation takes place during the PLplot build process when DHAVE_ADA_2007=OFF or DHAVE_ADA_2007=ON is chosen; the appropriate binding source files are generated automatically. User programs will work with either compiler type without modification.</para> + <para><emphasis role="bold"> 10.2 GNAT Dependence</emphasis></para> + <para> There is a slight but significant dependence on the GNAT version of Ada. This is discussed more fully in Section 6.2</para> + <para><emphasis role="bold"> 10.3 Compiler Warnings</emphasis></para> + <para> During normal compilation of the Ada bindings, approximately a dozen warnings are generated, in pairs, of the following form:</para> + <para> bar.adb:46: warning: type of argument "foo" is unconstrained array</para> + <para> bar.adb:46: warning: foreign caller must pass bounds explicitly</para> + <para> These are normal and an unavoidable consequence of some of the callback routines interacting with the underlying C code.</para> + <para><emphasis role="bold"> 10.4 PLplot_Auxiliary</emphasis></para> + <para> The bindings include files PLplot_Auxiliary.ads and PLplot_Auxiliary.adb. These files are currently used to provide a few convenience subprograms that are used in the examples. However, they are also very tightly associated with the above-mentioned facility to... [truncated message content] |
From: <jb...@us...> - 2008-12-05 22:04:03
|
Revision: 9046 http://plplot.svn.sourceforge.net/plplot/?rev=9046&view=rev Author: jbauck Date: 2008-12-05 21:33:58 +0000 (Fri, 05 Dec 2008) Log Message: ----------- Repair most of the formatting that got hosed when converting from my original source document to docbook. Modified Paths: -------------- trunk/doc/docbook/src/ada.xml Modified: trunk/doc/docbook/src/ada.xml =================================================================== --- trunk/doc/docbook/src/ada.xml 2008-12-05 20:44:03 UTC (rev 9045) +++ trunk/doc/docbook/src/ada.xml 2008-12-05 21:33:58 UTC (rev 9046) @@ -50,31 +50,31 @@ <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's main concern with programming for PLplot.</para> <sect2 id="ada_thin"> <title>Thin Binding</title> - <para> The thin binding, in the files plplotthin.ads and plplotthin.adb, 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 plcol0 requires a single integer argument, there is a corresponding Ada program also called plcol0 which also requires a single integer argument. (plcol0 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's type system. Thus, the thin binding refers to the PLplot-centric type PLFLT for floating-point types while the thick binding uses the usual Ada type Long_Float.</para> + <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'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 sensical. 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 subtype-ed or renames-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 with the thin binding.</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 with-ed and use-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> 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 "<emphasis>y</emphasis>'s" as a function of a single "<emphasis>x</emphasis>" with default plot appearances chosen to suit many situations. Other simple plotters are available for three-dimensional and contour plots. Manipulating PLplot'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's type system extensively to reduce the chances of inappropriate actions. For example, Ada arrays are used throughout (as opposed to C's pointer-plus-offset-while-carrying-along-the-size-separately approach). Quantities which have natural range limits are subtype-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> The third main aspect of the thick binding is to use Ada data structures and Ada's type system extensively to reduce the chances of inappropriate actions. For example, Ada arrays are used throughout (as opposed to C'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 "Ada" names and "PLplot" 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 "standard" 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 plcol0(1) sets the drawing color to red. In the standard thick binding, the same thing is accomplished by writing Set_Color(Red). The Ada program may just as well write Set_Color(1) since the binding merely sets a constant Red to be equal to the integer 1. 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 distinguishing feature of this thick binding (the "standard" 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_Color(Red)</literal>. The Ada program may just as well write <literal>Set_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 "normal" PLplot name can be linked to the "Ada" name along with the appropriate entry in the Ada specification, as well as another HTML file with links from the "Ada" 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 "redacted" 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 plplot.ads and plplot.adb.</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 plplot_traditional.ads and plplot_traditional.adb.</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"> @@ -96,7 +96,7 @@ <sect2 id="ada_obtaining_bindings"> <title>Download the Ada bindings to PLplot</title> <para> The third major software component is the bindings themselves. Since they are currently included with the PLplot software itself, there is no need to download them from another place.</para> - <para> The bindings themselves are six Ada source files named (using GNAT filename extensions) plplot.ads, plplot.adb, plplot_traditional.ads, plplot_traditional.adb, plplothin.ads, plplotthin.adb. There are two additional files, plplot_auxiliary.ads and plplot_auxililary.adb which will be discussed later, in Section 9. These can be stored somewhere on your system's search paths for easy access.</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_auxililary.adb</literal> which will be discussed later, in Section 9. These can be stored somewhere on your system's search paths for easy access.</para> </sect2> </sect1> <sect1 id="ada_howto"> @@ -104,13 +104,13 @@ <sect2 id="ada_95_2005"> <title>Ada 95 versus Ada 2005</title> <para> The bindings will work for either Ada 95 or Ada 2005. The only difference that concerns PLplot users is that Ada 2005, in Annex G.3, provides declarations for real-valued vectors and matrices (along with some other functionality). These declarations make available type Real_Vector and type Real_Matrix.</para> - <para> The installation process for PLplot requires you to select Ada 95 or Ada 2005. After that, the correct bindings are generated automatically depending on your choice. The differences are very minor: If Ada 2005, the type declarations provided according to Annex G.3 are used; if Ada 95, similar type declarations are provided. For the most part, you don't need to think about this much. However, see Section 9, Compilation Notes, if you are using Ada 95 and need to declare vectors or matrices. The design goal in either case is to encourage users to use Real_Vector and Real_Matrix since these are the "official" versions of these entities as of Ada 2005. Someone using objects based on these type definitions in Ada 95 in their PLplot programs should expect their programs to work without modification if they should switch to Ada 2005.</para> + <para> The installation process for PLplot requires you to select Ada 95 or Ada 2005. After that, the correct bindings are generated automatically depending on your choice. The differences are very minor: If Ada 2005, the type declarations provided according to Annex G.3 are used; if Ada 95, similar type declarations are provided explicitly in the bindingss. For the most part, you don't need to think about this much. However, see Section 9, Compilation Notes, if you are using Ada 95 and need to declare vectors or matrices. The design goal in either case is to encourage users to use Real_Vector and Real_Matrix since these are the "official" versions of these entities as of Ada 2005. Someone using objects based on these type definitions in Ada 95 in their PLplot programs should expect their programs to work without modification if they should switch to Ada 2005.</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 Unrestricted_Access attribute of GNAT was used in making the function Matrix_To_Pointers in plplotthin.adb and in a few callbacks. Matrix_To_Pointers is called whenever an Ada matrix (2D array) is passed to a PLplot subroutine. For more about Unrestricted_Access attribute, see Implementation Defined Attributes in the GNAT Reference Manual. This dependency shouldn'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 plplotthin.adb, or by providing the proper aliasing.</para> + <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'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> Most of the GNAT dependencies can be found by searching the source code for "GNAT" and "Unrestricted_Access."</para> + <para> Most of the GNAT dependencies can be found by searching the source code for "<literal>GNAT</literal>" and "<literal>Unrestricted_Access</literal>."</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"> @@ -119,25 +119,25 @@ <para> Here is a simple program that will generate a plot of part of a parabola.</para> <programlisting> with - PLplot_Auxiliary, - PLplot; + PLplot_Auxiliary, + PLplot; use - PLplot_Auxiliary, - PLplot; + PLplot_Auxiliary, + PLplot; procedure Simple_Example is - x, y : Real_Vector(-10 .. 10); + x, y : Real_Vector(-10 .. 10); begin - for i in x'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. + for i in x'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 them pre-installed.)</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 \ @@ -162,7 +162,7 @@ <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 Draw_On_White or reset to the original mode with Draw_On_Black. Each of these manipulates color map 0 by swapping black and white so that e.g.with Draw_On_White, formerly white lines on a black background autotmatically become black lines on a white background.</para> + <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 autotmatically become black lines on a white background.</para> </sect4> </sect3> <sect3 id="ada_simple_plotters"> @@ -170,7 +170,7 @@ <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 x-y pairs with easy labeling, coloring, line width and styles, justification, and zooming.</para> + <para> Plot up to five <emphasis>x-y</emphasis> pairs with easy labeling, coloring, line width and styles, justification, and zooming.</para> </sect4> <sect4 id="ada_simple_plot"> <title>Simple_Plot</title> @@ -178,15 +178,15 @@ </sect4> <sect4 id="ada_simple_plot_logx"> <title> Simple_Plot_Log_X</title> - <para> Same as Simple_Plot but with logarithmic <emphasis>x</emphasis>-axis.</para> + <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 Simple_Plot but with logarithmic <emphasis>y</emphasis>-axis.</para> + <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 Simple_Plot but with logarithmic <emphasis>x</emphasis>- and <emphasis>y</emphasis>-axes.</para> + <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> @@ -212,21 +212,21 @@ <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 easlily 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 Set_Pen_Color(Red) (plcol0 in the traditional binding) normally does what it says, Red simply has the value 1. If the user changes the color map so that 1 corresponds to another color, then Set_Pen_Color(Red) 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 1, use Set_Pen_Color(Reset_Red) instead. These 16 "reset" 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 Set_Pen_Color(Red) 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, Color_Themes_For_Map_1_Type. These color themes can be quickly applied with Quick_Set_Color_Map_1.</para> - <para> Miscellaneous other Ada features include a pre-built mask function for Shade_Regions 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> + <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 "reset" 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> <para> Color table snapshots</para> - <para> Make_Snapshot_Of_Color_Map_0</para> - <para> Restore_Snapshot_Of_Color_Map_0</para> - <para> Restore_Default_Snapshot_Of_Color_Map_0</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> <para> Color resetting functions for the 16 colors of color map 0</para> - <para> Reset_Black, Reset_Red, … Reset_White</para> + <para> <literal>Reset_Black, Reset_Red, … Reset_White</literal></para> <para> Easy manipulation of color map 1</para> - <para> Pre-built color themes for color map 1: Color_Themes_For_Map_1_Type</para> - <para> Quick application of pre-built color themes: Quick_Set_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> <para> Other features</para> - <para> A pre-built mask function for Shade_Regions that does no masking: Mask_Function_No_Mask</para> - <para> An easy way to calculate an array of contour levels for contour plots: Calculate_Contour_Levels</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> </sect3> </sect2> <sect2 id="ada_integer_options"> @@ -235,59 +235,59 @@ <para> Below is a listing of at least the contexts in which these "re-namings" 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> Colors: Plot_Color_Type</para> - <para> 0 is Black, 1 is Red, etc.</para> - <para> Justification for plots: Justification_Type</para> - <para> User_Justified</para> - <para> Not_Justified</para> - <para> Justified</para> - <para> Justified_Square_Box</para> - <para> Axis styles: Axis_Style_Type</para> - <para> Linear_Major_Grid</para> - <para> Linear_Minor_Grid</para> - <para> etc.</para> - <para> Font styles: Font_Style_Type</para> - <para> Normal_Font</para> - <para> Roman_Font</para> - <para> Italic_Font</para> - <para> Script_Font</para> - <para> Character sets: Character_Set_Type</para> - <para> Standard_Character_Set</para> - <para> Extended_Character_Set</para> - <para> Plot orientation: Orientation_Type</para> - <para> Landscape</para> - <para> Portrait</para> - <para> Modes for parsing command line arguments: Parse_Mode_Type</para> - <para> E.g. PL_PARSE_PARTIAL</para> - <para> Descriptions of map outlines (continents, states, etc.): Map_Type</para> - <para> Continents</para> - <para> USA_and_States</para> - <para> Continents_and_Countries</para> - <para> USA_States_and_Continents</para> + <para> <literal>0</literal> is Black, <literal>1</literal> is Red, etc.</para> + <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> + <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> + <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> + <para> Character sets: <literal>Character_Set_Type</literal></para> + <para> <literal>Standard_Character_Set</literal></para> + <para> <literal>Extended_Character_Set</literal></para> + <para> Plot orientation: <literal>Orientation_Type</literal></para> + <para> <literal>Landscape</literal></para> + <para> <literal>Portrait</literal></para> + <para> Modes for parsing command line arguments: <literal>Parse_Mode_Type</literal></para> + <para> E.g. <literal>PL_PARSE_PARTIAL</literal></para> + <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> <para> Various style and view options for 3D and surface plots</para> - <para> E.g. Lines_Parallel_To_X</para> - <para> Kind of gridding algorithm for interpolating 2D data to a grid: Gridding_Algorithm_Type</para> - <para> E.g. Grid_Bivariate_Cubic_Spline_Approximation</para> + <para> E.g. <literal>Lines_Parallel_To_X</literal></para> + <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> <para> Flags for histogram style</para> - <para> E.g. Histogram_Default</para> + <para> E.g. <literal>Histogram_Default</literal></para> <para> Flags for histogram binning</para> - <para> E.g. Bin_Default</para> + <para> E.g. <literal>Bin_Default</literal></para> <para> Names for color space models</para> - <para> Hue, Lightness, Saturation: HLS</para> - <para> Red, Green, Blue: RGB</para> + <para> Hue, Lightness, Saturation: <literal>HLS</literal></para> + <para> Red, Green, Blue: <literal>RGB</literal></para> </sect2> <sect2 id="ada_one_offs"> <title>One-offs</title> - <para> Convenient string handling for Get_Device_Name (plgdev in the traditional binding); a function version is provided that simplifies the string handling associated with this feature.</para> - <para> Overloaded Set_Line_Style (plstyl in the traditional binding) with a version that takes a single argument, Default_Continuous_Line. 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 Contour_Plot_Irregular_Data (plfcont 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> Convenient string handling for Get_Device_Name (<literal>plgdev</literal> in the traditional binding); a function version is provided that simplifies the string handling associated with this feature.</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> </sect2> </sect1> <sect1 id="ada_c_flavor"> <title>Parts That Retain a C Flavor</title> <!-- 195:'Normal' --><para><emphasis role="bold"> </emphasis>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> <para><emphasis role="bold"> 8.1 Map-drawing</emphasis></para> - <para> plmapform as called by Draw_Latitude_Longitude (plmap) and Draw_Latitude_Longitude (plmeridians)</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 0 .. 2000. See Example 19 for how this is handled in by the user program. The constrained array is called Map_Form_Constrained_Array.</para> + <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> </sect1> <sect1 id="ada_known_issues"> @@ -295,22 +295,22 @@ <!-- 200:'Normal' --><para><emphasis role="bold"> 9.1 Stripchart labelling</emphasis></para> <para> In Example 17, all of the stripchart labels are the same regardless of the fact that the calling program sets them to be different. This is likely to affect user programs in the same manner.</para> <para><emphasis role="bold"> 9.2 Documentation</emphasis></para> - <para> In numerous places in the documentation, a feature is listed or described as "C only." Many of these features are actually available in Ada. For example, in Contour_Plot (plcont in the traditional binding), the transformation from array indices to world coordinates is mentioned as "C only" but is actually available in Ada.</para> + <para> In numerous places in the documentation, a feature is listed or described as "C only." 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 "C only" but is actually available in Ada.</para> </sect1> <sect1 id="ada_compilation_notes"> <title>Compilation notes</title> <!-- 205:'Normal' --><para><emphasis role="bold"> 10.1 Ada 95 Versus Ada 2005</emphasis></para> - <para> As discussed in Section 6.1, the bindings are made to work with Ada 95 but to also take advantage of the Annex G.3 (vector-matrix) features of Ada 2005. Actually, this adaptation takes place during the PLplot build process when DHAVE_ADA_2007=OFF or DHAVE_ADA_2007=ON is chosen; the appropriate binding source files are generated automatically. User programs will work with either compiler type without modification.</para> + <para> As discussed in Section 6.1, the bindings are made to work with Ada 95 but to also take advantage of the Annex G.3 (vector-matrix) features of Ada 2005. Actually, this adaptation takes place during the PLplot build process when <literal>DHAVE_ADA_2007=OFF</literal> or <literal>DHAVE_ADA_2007=ON</literal> is chosen; the appropriate binding source files are generated automatically. User programs will work with either compiler type without modification.</para> <para><emphasis role="bold"> 10.2 GNAT Dependence</emphasis></para> <para> There is a slight but significant dependence on the GNAT version of Ada. This is discussed more fully in Section 6.2</para> <para><emphasis role="bold"> 10.3 Compiler Warnings</emphasis></para> <para> During normal compilation of the Ada bindings, approximately a dozen warnings are generated, in pairs, of the following form:</para> - <para> bar.adb:46: warning: type of argument "foo" is unconstrained array</para> - <para> bar.adb:46: warning: foreign caller must pass bounds explicitly</para> + <para> <literal>bar.adb:46: warning: type of argument "foo" is unconstrained array</literal></para> + <para> <literal>bar.adb:46: warning: foreign caller must pass bounds explicitly</literal></para> <para> These are normal and an unavoidable consequence of some of the callback routines interacting with the underlying C code.</para> <para><emphasis role="bold"> 10.4 PLplot_Auxiliary</emphasis></para> - <para> The bindings include files PLplot_Auxiliary.ads and PLplot_Auxiliary.adb. These files are currently used to provide a few convenience subprograms that are used in the examples. However, they are also very tightly associated with the above-mentioned facility to accommodate either Ada 95 or Ada 2005 compilers. The current situation is such that if the user is using an Ada 95 compiler <emphasis>and</emphasis> requires the Real_Vector or Real_Matrix type definitions, then he/she should with PLplot_Auxiliary. If in doubt, PLplot_Auxiliary can always be with-ed without harm. In the future, this confusion might be removed and the need for PLplot_Auxiliary removed. (However, user programs that with it should still work without change.)</para> + <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 very tightly associated with the above-mentioned facility to accommodate either Ada 95 or Ada 2005 compilers. The current situation is such that if the user is using an Ada 95 compiler <emphasis>and</emphasis> requires the Real_Vector or Real_Matrix type definitions, then he/she should <literal>with</literal> <literal>PLplot_Auxiliary</literal>. If in doubt, <literal>PLplot_Auxiliary</literal> can always be <literal>with</literal>-ed without harm. In the future, this confusion might be removed and the need for <literal>PLplot_Auxiliary</literal> removed. (However, user programs that with it should still work without change.)</para> </sect1> <sect1 id="ada_apple_notes"> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <jb...@us...> - 2009-01-02 23:02:09
|
Revision: 9247 http://plplot.svn.sourceforge.net/plplot/?rev=9247&view=rev Author: jbauck Date: 2009-01-02 23:01:57 +0000 (Fri, 02 Jan 2009) Log Message: ----------- Update Ada docbook chapter with note on use of GNAT-specific Pragma Warnings. Also, clean up further hosed formatting. Modified Paths: -------------- trunk/doc/docbook/src/ada.xml Modified: trunk/doc/docbook/src/ada.xml =================================================================== --- trunk/doc/docbook/src/ada.xml 2009-01-02 11:43:47 UTC (rev 9246) +++ trunk/doc/docbook/src/ada.xml 2009-01-02 23:01:57 UTC (rev 9247) @@ -110,7 +110,8 @@ <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'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> Most of the GNAT dependencies can be found by searching the source code for "<literal>GNAT</literal>" and "<literal>Unrestricted_Access</literal>."</para> + <para> Pragma Warnings (Off, "some text") and Pragma Warnings (On, "some text") are used in the bindings to suppress warnings about a particular method used to intereface with C code. These pragmas are also used in Ada Exaamples 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 "<literal>GNAT</literal>", "<literal>Unrestricted_Access</literal> and <literal>Pragma Warnings</literal>."</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"> @@ -167,7 +168,7 @@ </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> + <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 labeling, coloring, line width and styles, justification, and zooming.</para> @@ -215,18 +216,18 @@ <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 "reset" 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> - <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> - <para> Color resetting functions for the 16 colors of color map 0</para> - <para> <literal>Reset_Black, Reset_Red, … Reset_White</literal></para> - <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> - <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> + <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> + <para> Color resetting functions for the 16 colors of color map 0</para> + <para><literal> Reset_Black, Reset_Red, … Reset_White</literal></para> + <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> + <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> </sect3> </sect2> <sect2 id="ada_integer_options"> @@ -234,46 +235,46 @@ <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 "re-namings" 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> Colors: Plot_Color_Type</para> - <para> <literal>0</literal> is Black, <literal>1</literal> is Red, etc.</para> - <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> - <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> - <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> - <para> Character sets: <literal>Character_Set_Type</literal></para> - <para> <literal>Standard_Character_Set</literal></para> - <para> <literal>Extended_Character_Set</literal></para> - <para> Plot orientation: <literal>Orientation_Type</literal></para> - <para> <literal>Landscape</literal></para> - <para> <literal>Portrait</literal></para> - <para> Modes for parsing command line arguments: <literal>Parse_Mode_Type</literal></para> - <para> E.g. <literal>PL_PARSE_PARTIAL</literal></para> - <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> - <para> Various style and view options for 3D and surface plots</para> - <para> E.g. <literal>Lines_Parallel_To_X</literal></para> - <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> - <para> Flags for histogram style</para> - <para> E.g. <literal>Histogram_Default</literal></para> - <para> Flags for histogram binning</para> - <para> E.g. <literal>Bin_Default</literal></para> - <para> Names for color space models</para> - <para> Hue, Lightness, Saturation: <literal>HLS</literal></para> - <para> Red, Green, Blue: <literal>RGB</literal></para> + <para> Colors: Plot_Color_Type</para> + <para> <literal> 0</literal> is Black, <literal>1</literal> is Red, etc.</para> + <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> + <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> + <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> + <para> Character sets: <literal>Character_Set_Type</literal></para> + <para><literal> Standard_Character_Set</literal></para> + <para><literal> Extended_Character_Set</literal></para> + <para> Plot orientation: <literal>Orientation_Type</literal></para> + <para><literal> Landscape</literal></para> + <para><literal> Portrait</literal></para> + <para> Modes for parsing command line arguments: <literal>Parse_Mode_Type</literal></para> + <para> E.g. <literal>PL_PARSE_PARTIAL</literal></para> + <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> + <para> Various style and view options for 3D and surface plots</para> + <para> E.g. <literal>Lines_Parallel_To_X</literal></para> + <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> + <para> Flags for histogram style</para> + <para> E.g. <literal>Histogram_Default</literal></para> + <para> Flags for histogram binning</para> + <para> E.g. <literal>Bin_Default</literal></para> + <para> Names for color space models</para> + <para> Hue, Lightness, Saturation: <literal>HLS</literal></para> + <para> Red, Green, Blue: <literal>RGB</literal></para> </sect2> <sect2 id="ada_one_offs"> <title>One-offs</title> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <jb...@us...> - 2009-01-14 08:13:46
|
Revision: 9301 http://plplot.svn.sourceforge.net/plplot/?rev=9301&view=rev Author: jbauck Date: 2009-01-14 08:13:41 +0000 (Wed, 14 Jan 2009) Log Message: ----------- Update Ada docs. Modified Paths: -------------- trunk/doc/docbook/src/ada.xml Modified: trunk/doc/docbook/src/ada.xml =================================================================== --- trunk/doc/docbook/src/ada.xml 2009-01-14 05:59:01 UTC (rev 9300) +++ trunk/doc/docbook/src/ada.xml 2009-01-14 08:13:41 UTC (rev 9301) @@ -298,7 +298,7 @@ <para><emphasis role="bold"> 9.2 Documentation</emphasis></para> <para> In numerous places in the documentation, a feature is listed or described as "C only." 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 "C only" but is actually available in Ada.</para> <para><emphasis role="bold"> 9.3 API</emphasis></para> - <para> The C documentation for <literal>plscmap1l</literal> (<literal>Set_Color_Map_1_Piecewise</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, the last parameter should always be an array of Boolean of the same length as the other array arguments.</para> + <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>(Reverse_Hue_None, Reverse_Hue_All)</literal>.</para> </sect1> <sect1 id="ada_compilation_notes"> <title>Compilation notes</title> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <jb...@us...> - 2010-06-04 01:07:23
|
Revision: 11052 http://plplot.svn.sourceforge.net/plplot/?rev=11052&view=rev Author: jbauck Date: 2010-06-04 01:07:14 +0000 (Fri, 04 Jun 2010) Log Message: ----------- Update Ada documentation. Modified Paths: -------------- trunk/doc/docbook/src/ada.xml Modified: trunk/doc/docbook/src/ada.xml =================================================================== --- trunk/doc/docbook/src/ada.xml 2010-06-03 23:52:13 UTC (rev 11051) +++ trunk/doc/docbook/src/ada.xml 2010-06-04 01:07:14 UTC (rev 11052) @@ -1,8 +1,8 @@ -<!-- -*- mode: nxml -*- --> -<!-- +<?xml version='1.0' encoding='UTF-8'?> +<!-- -*- mode: nxml -*- --><!-- ada.xml: "Ada Language" chapter -Copyright (C) 2008 Jerry Bauck +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 @@ -30,240 +30,233 @@ 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="ada"> +--><!-- 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> 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'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 bindings are a re-expression and extension of the C-language API and as such are a kind of abstract layer between the user'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's main concern with programming for PLplot.</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'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'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 sensical. 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> + <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'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 sensical. 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 "<emphasis>y</emphasis>'s" as a function of a single "<emphasis>x</emphasis>" with default plot appearances chosen to suit many situations. Other simple plotters are available for three-dimensional and contour plots. Manipulating PLplot'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's type system extensively to reduce the chances of inappropriate actions. For example, Ada arrays are used throughout (as opposed to C'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 "Ada" names and "PLplot" names. Also, the subroutine-specific comments from the C API have been retained verbatim.</para> + <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 "<emphasis>y</emphasis>'s" as a function of a single "<emphasis>x</emphasis>" with default plot appearances chosen to suit many situations. Other simple plotters are available for three-dimensional and contour plots. Manipulating PLplot'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's type system extensively to reduce the chances of inappropriate actions. For example, Ada arrays are used throughout (as opposed to C'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 "Ada" names and "PLplot" 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 "standard" 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 "normal" PLplot name can be linked to the "Ada" name along with the appropriate entry in the Ada specification, as well as another HTML file with links from the "Ada" 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 "redacted" 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> + <para> The distinguishing feature of this thick binding (the "standard" 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 "normal" PLplot name can be linked to the "Ada" name along with the appropriate entry in the Ada specification, as well as another HTML file with links from the "Ada" 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 "redacted" 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> + <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 30 of which demonstrate how to use many of the features of the PLplot package. These examples also serve as a testbed 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'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> + <para> An important part of the Ada bindings is the examples, some 30 of which demonstrate how to use many of the features of the PLplot package. These examples also serve as a testbed 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'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'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> + <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'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 home page at <ulink url="http://sourceforge.net/projects/plplot">sourceforge.net—plplot</ulink>. Follow the installation instructions after downloading. The installation process is more involved than other open source software and requires that your computer has cmake installed. OS X users can try installing PLplot in its entirety from MacPorts but that activity is not officially supported by the PLplot developers. The advantage of using MacPorts is that all installation dependencies are automatically installed for you.</para> + <para> PLplot can be downloaded from the PLplot home page at <ulink url="http://sourceforge.net/projects/plplot">sourceforge.net—plplot</ulink>. Follow the installation instructions after downloading. The installation process is more involved than other open source software and requires that your computer has cmake installed. OS X users can try installing PLplot in its entirety from MacPorts but that activity is not officially supported by the PLplot developers. The advantage of using MacPorts is that all installation dependencies are automatically installed for you.</para> </sect2> <sect2 id="ada_obtaining_bindings"> <title>Download the Ada bindings to PLplot</title> - <para> The third major software component is the bindings themselves. Since they are currently included with the PLplot software itself, there is no need to download them from another place.</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_auxililary.adb</literal> which will be discussed later, in Section 9. These can be stored somewhere on your system's search paths for easy access.</para> + <para> The third major software component is the bindings themselves. Since they are currently included with the PLplot software itself, there is no need to download them from another place.</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_auxililary.adb</literal> which will be discussed later, in Section 9. These can be stored somewhere on your system's search paths for easy access.</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. The only difference that concerns PLplot users is that Ada 2005, in Annex G.3, provides declarations for real-valued vectors and matrices (along with some other functionality). These declarations make available type Real_Vector and type Real_Matrix.</para> - <para> The installation process for PLplot requires you to select Ada 95 or Ada 2005. After that, the correct bindings are generated automatically depending on your choice. The differences are very minor: If Ada 2005, the type declarations provided according to Annex G.3 are used; if Ada 95, similar type declarations are provided explicitly in the bindingss. For the most part, you don't need to think about this much. However, see Section 9, Compilation Notes, if you are using Ada 95 and need to declare vectors or matrices. The design goal in either case is to encourage users to use Real_Vector and Real_Matrix since these are the "official" versions of these entities as of Ada 2005. Someone using objects based on these type definitions in Ada 95 in their PLplot programs should expect their programs to work without modification if they should switch to Ada 2005.</para> + <para> The bindings will work for either Ada 95 or Ada 2005. The only difference that concerns PLplot users is that Ada 2005, in Annex G.3, provides declarations for real-valued vectors and matrices (along with some other functionality). These declarations make available type Real_Vector and type Real_Matrix.</para> + <para> The installation process for PLplot requires you to select Ada 95 or Ada 2005. After that, the correct bindings are generated automatically depending on your choice. The differences are very minor: If Ada 2005, the type declarations provided according to Annex G.3 are used; if Ada 95, similar type declarations are provided explicitly in the bindingss. For the most part, you don't need to think about this much. However, see Section 9, Compilation Notes, if you are using Ada 95 and need to declare vectors or matrices. The design goal in either case is to encourage users to use Real_Vector and Real_Matrix since these are the "official" versions of these entities as of Ada 2005. Someone using objects based on these type definitions in Ada 95 in their PLplot programs should expect their programs to work without modification if they should switch to Ada 2005.</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'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, "some text") and Pragma Warnings (On, "some text") are used in the bindings to suppress warnings about a particular method used to intereface with C code. These pragmas are also used in Ada Exaamples 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 "<literal>GNAT</literal>", "<literal>Unrestricted_Access</literal> and <literal>Pragma Warnings</literal>."</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> + <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'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, "some text") and Pragma Warnings (On, "some text") are used in the bindings to suppress warnings about a particular method used to intereface with C code. These pragmas are also used in Ada Exaamples 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 "<literal>GNAT</literal>", "<literal>Unrestricted_Access</literal> and <literal>Pragma Warnings</literal>."</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 "build directory" and "installation directory."</para> - <para> Here is a simple program that will generate a plot of part of a parabola.</para> + <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 "build directory" and "installation directory."</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'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; + with + PLplot_Auxiliary, + PLplot; + use + PLplot_Auxiliary, + PLplot; + procedure Simple_Example is + x, y : Real_Vector(-10 .. 10); + begin + for i in x'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> + <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 + #!/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> - + <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 "simple plotters," 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 "simple plotters".</para> + <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 "simple plotters," 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 "simple plotters".</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 autotmatically become black lines on a white background.</para> - </sect4> + <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 autotmatically 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 labeling, 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>'s against a single <emphasis>x</emphasis> with easy labeling 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 labeling 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> + <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 labeling, 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>'s against a single <emphasis>x</emphasis> with easy labeling 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 labeling 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 easlily 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 "reset" 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> - <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> - <para> Color resetting functions for the 16 colors of color map 0</para> - <para><literal> Reset_Black, Reset_Red, … Reset_White</literal></para> - <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> - <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> + <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 easlily 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 "reset" 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> + <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> + <para> Color resetting functions for the 16 colors of color map 0</para> + <para><literal> Reset_Black, Reset_Red, … Reset_White</literal></para> + <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> + <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> </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 "re-namings" 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>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 "re-namings" 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> Colors: Plot_Color_Type</para> - <para> <literal> 0</literal> is Black, <literal>1</literal> is Red, etc.</para> + <para> <literal> 0</literal> is Black, <literal>1</literal> is Red, etc.</para> <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> + <para><literal> User_Justified</literal></para> + <para><literal> Not_Justified</literal></para> + <para><literal> Justified</literal></para> + <para><literal> Justified_Square_Box</literal></para> <para> Axis styles: <literal>Axis_Style_Type</literal></para> - <para><literal> Linear_Major_Grid</literal></para> - <para><literal> Linear_Minor_Grid</literal></para> + <para><literal> Linear_Major_Grid</literal></para> + <para><literal> Linear_Minor_Grid</literal></para> <para> etc.</para> <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> + <para><literal> Normal_Font</literal></para> + <para><literal> Roman_Font</literal></para> + <para><literal> Italic_Font</literal></para> + <para><literal> Script_Font</literal></para> <para> Character sets: <literal>Character_Set_Type</literal></para> - <para><literal> Standard_Character_Set</literal></para> - <para><literal> Extended_Character_Set</literal></para> + <para><literal> Standard_Character_Set</literal></para> + <para><literal> Extended_Character_Set</literal></para> <para> Plot orientation: <literal>Orientation_Type</literal></para> - <para><literal> Landscape</literal></para> - <para><literal> Portrait</literal></para> + <para><literal> Landscape</literal></para> + <para><literal> Portrait</literal></para> <para> Modes for parsing command line arguments: <literal>Parse_Mode_Type</literal></para> <para> E.g. <literal>PL_PARSE_PARTIAL</literal></para> <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> + <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> <para> Various style and view options for 3D and surface plots</para> <para> E.g. <literal>Lines_Parallel_To_X</literal></para> <para> Kind of gridding algorithm for interpolating 2D data to a grid: <literal>Gridding_Algorithm_Type</literal></para> @@ -278,50 +271,48 @@ </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> 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 labeling 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 procdure 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> </sect2> </sect1> <sect1 id="ada_c_flavor"> <title>Parts That Retain a C Flavor</title> - <!-- 195:'Normal' --><para><emphasis role="bold"> </emphasis>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> - <para><emphasis role="bold"> 8.1 Map-drawing</emphasis></para> - <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 whil... [truncated message content] |
From: <ai...@us...> - 2010-06-04 18:08:39
|
Revision: 11054 http://plplot.svn.sourceforge.net/plplot/?rev=11054&view=rev Author: airwin Date: 2010-06-04 18:08:32 +0000 (Fri, 04 Jun 2010) Log Message: ----------- Make Jerry's recent changes validate. In all cases, the validation issues involved special characters which are not acceptable to DocBook 4.5. In the horizontal ellipsis case, I converted to the equivalent unicode numerical entity. There was also a special character that looked like a hyphen that caused a lot of trouble throughout the text. In cases where it made sense, I replaced that by an ordinary ascii hyphen. In other cases (e.g. URL annotations) I just simplified the text to avoid the character. Modified Paths: -------------- trunk/doc/docbook/src/ada.xml Modified: trunk/doc/docbook/src/ada.xml =================================================================== --- trunk/doc/docbook/src/ada.xml 2010-06-04 18:02:11 UTC (rev 11053) +++ trunk/doc/docbook/src/ada.xml 2010-06-04 18:08:32 UTC (rev 11054) @@ -1,4 +1,4 @@ -<?xml version='1.0' encoding='UTF-8'?> + <!-- -*- mode: nxml -*- --><!-- ada.xml: "Ada Language" chapter @@ -30,12 +30,14 @@ 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. ---><!-- This document was created with Syntext Serna Free. --><chapter id="ada"> +--><!-- 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> 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"> @@ -86,7 +88,7 @@ </sect2> <sect2 id="ada_obtaining_plplot"> <title>Download and install PLplot</title> - <para> PLplot can be downloaded from the PLplot home page at <ulink url="http://sourceforge.net/projects/plplot">sourceforge.net—plplot</ulink>. Follow the installation instructions after downloading. The installation process is more involved than other open source software and requires that your computer has cmake installed. OS X users can try installing PLplot in its entirety from MacPorts but that activity is not officially supported by the PLplot developers. The advantage of using MacPorts is that all installation dependencies are automatically installed for you.</para> + <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 but that activity is not officially supported by the PLplot developers. The advantage of using MacPorts is that all installation dependencies are automatically installed for you.</para> </sect2> <sect2 id="ada_obtaining_bindings"> <title>Download the Ada bindings to PLplot</title> @@ -184,11 +186,11 @@ </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 labeling and automatic line colors and styles.</para> + <para> Plot up to five <emphasis>x</emphasis>-<emphasis>y</emphasis> pairs with easy labeling 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> + <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> @@ -214,7 +216,7 @@ <para><literal> Restore_Snapshot_Of_Color_Map_0</literal></para> <para><literal> Restore_Default_Snapshot_Of_Color_Map_0</literal></para> <para> Color resetting functions for the 16 colors of color map 0</para> - <para><literal> Reset_Black, Reset_Red, … Reset_White</literal></para> + <para><literal> Reset_Black, Reset_Red, …, Reset_White</literal></para> <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> @@ -225,7 +227,7 @@ </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>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 "re-namings" 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> Colors: Plot_Color_Type</para> @@ -274,8 +276,8 @@ <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 labeling 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 procdure 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 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 labeling 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 procdure 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> </sect2> </sect1> <sect1 id="ada_c_flavor"> @@ -309,10 +311,10 @@ <para> The Macintosh Ada community has made a plug-in for Apple'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 & 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><emphasis role="bold"> 11.2 A Note on AquaTerm</emphasis></para> - <para> AquaTerm is a display option available on Macintosh computers using OS X and is supported by PLplot. It is a native Cocoa graphics "terminal" that is highly recommended. All output is antialiased and is easily cut-and-pasted in OS X's native PDF format. Get it at <ulink url="http://sourceforge.net/project/showfiles.php?group_id=39915">sourceforge.net—showfiles.php</ulink>. It can also be installed from either the Fink <ulink url="http://www.finkproject.org/">www.finkproject.org</ulink> or MacPorts <ulink url="http://www.macports.org/projects.">www.macports.org—projects.</ulink> projects.</para> + <para> AquaTerm is a display option available on Macintosh computers using OS X and is supported by PLplot. It is a native Cocoa graphics "terminal" that is highly recommended. All output is antialiased and is easily cut-and-pasted in OS X's native PDF format. Get it <ulink url="http://sourceforge.net/project/showfiles.php?group_id=39915">here</ulink>. It can also be installed from either the <ulink url="http://www.finkproject.org/">Fink</ulink> or <ulink url="http://www.macports.org/projects.">MacPorts</ulink> projects.</para> <para><emphasis role="bold"> 11.3 X11</emphasis></para> <para> Apple supplies the X11 windowing system that is popular on some other Unix and Linux operations systems as part of the Developer Tools. All PLplot programs made with the Ada bindings will run on X11. In fact, some types of interactivity such as Examples 14 and 17 will not run on Apple's X11 (as of OS X 10.4 at least) and must be run on X11 (or some other output device such as TCL/TK).</para> <para><emphasis role="bold"> 11.4 GNAT for OS X</emphasis></para> - <para> Apple Macintosh users will benefit from a pre-built version of GNAT that comes packaged using the usual Apple software installer and is strongly recommended. This compiler is available for both PowerPC and Intel Macintoshes at <ulink url="http://www.macada.org/macada/Welcome.html.">www.macada.org—Welcome.html.</ulink>. This site is traditionally rather confusing but the mailing list is extremely helpful. The installer also includes an Ada-specific plug-in for Apple's Xcode IDE which is strongly recommended if you plan to work on this platform. Xcode is part of the Developer Tools and is available on the Apple system disks that also contain the operating system or it can be downloaded for free from <ulink url="http://developer.apple.com/tools/xcode/">developer.apple.com—xcode</ulink>. </para> + <para> Apple Macintosh users will benefit from a pre-built version of GNAT that comes packaged using the usual Apple software installer and is strongly recommended. This compiler is available for both PowerPC and Intel Macintoshes at <ulink url="http://www.macada.org/macada/Welcome.html.">www.macada.org</ulink>. This site is traditionally rather confusing but the mailing list is extremely helpful. The installer also includes an Ada-specific plug-in for Apple's Xcode IDE which is strongly recommended if you plan to work on this platform. Xcode is part of the Developer Tools and is available on the Apple system disks that also contain the operating system or it can be downloaded for free from <ulink url="http://developer.apple.com/tools/xcode/">here</ulink>. </para> </sect1> </chapter> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <hba...@us...> - 2010-09-16 17:44:15
|
Revision: 11190 http://plplot.svn.sourceforge.net/plplot/?rev=11190&view=rev Author: hbabcock Date: 2010-09-16 17:44:09 +0000 (Thu, 16 Sep 2010) Log Message: ----------- Change Ada documentation so that it does not crash docbook. Modified Paths: -------------- trunk/doc/docbook/src/ada.xml Modified: trunk/doc/docbook/src/ada.xml =================================================================== --- trunk/doc/docbook/src/ada.xml 2010-09-16 17:43:20 UTC (rev 11189) +++ trunk/doc/docbook/src/ada.xml 2010-09-16 17:44:09 UTC (rev 11190) @@ -102,8 +102,8 @@ <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 <>) of Long_Float; - type Real_Matrix is array (Integer range <>, Integer range <>) of Long_Float; + type Real_Vector is array (Integer range <>) of Long_Float; + type Real_Matrix is array (Integer range <>, Integer range <>) 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 numerics libraries.</para> <para>For users who wish to either attain compatibility with Ada 2005 Annex G.3 or to access its features which actually depend on BLAS and LAPACK, there are two routes. One is to build PLpot normally and then to edit <literal>PLplot_Auxiliary.ads</literal> as is indicated in that file. This is a very simple process requiring commenting two lines and uncommenting three lines. Then recompile only the Ada bindings and use the newly-created compiled files in the user project. The other way is to type-convert the <literal>Real_Vector</literal> and <literal>Real_Matrix</literal> objects in the user program so that they are compatible with the declarations of Annex G.3 when accessing the numerics functionality in that annex. (In GNAT, the relevant file is <literal>a-nlrear.ads</literal>.)</para> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <ai...@us...> - 2010-09-18 23:04:14
|
Revision: 11193 http://plplot.svn.sourceforge.net/plplot/?rev=11193&view=rev Author: airwin Date: 2010-09-18 23:04:08 +0000 (Sat, 18 Sep 2010) Log Message: ----------- Change literal > to > to be consistent with xml standards. Modified Paths: -------------- trunk/doc/docbook/src/ada.xml Modified: trunk/doc/docbook/src/ada.xml =================================================================== --- trunk/doc/docbook/src/ada.xml 2010-09-18 19:14:46 UTC (rev 11192) +++ trunk/doc/docbook/src/ada.xml 2010-09-18 23:04:08 UTC (rev 11193) @@ -102,8 +102,8 @@ <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 <>) of Long_Float; - type Real_Matrix is array (Integer range <>, Integer range <>) of Long_Float; + type Real_Vector is array (Integer range <>) of Long_Float; + type Real_Matrix is array (Integer range <>, Integer range <>) 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 numerics libraries.</para> <para>For users who wish to either attain compatibility with Ada 2005 Annex G.3 or to access its features which actually depend on BLAS and LAPACK, there are two routes. One is to build PLpot normally and then to edit <literal>PLplot_Auxiliary.ads</literal> as is indicated in that file. This is a very simple process requiring commenting two lines and uncommenting three lines. Then recompile only the Ada bindings and use the newly-created compiled files in the user project. The other way is to type-convert the <literal>Real_Vector</literal> and <literal>Real_Matrix</literal> objects in the user program so that they are compatible with the declarations of Annex G.3 when accessing the numerics functionality in that annex. (In GNAT, the relevant file is <literal>a-nlrear.ads</literal>.)</para> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <jb...@us...> - 2011-01-05 22:49:41
|
Revision: 11442 http://plplot.svn.sourceforge.net/plplot/?rev=11442&view=rev Author: jbauck Date: 2011-01-05 22:49:31 +0000 (Wed, 05 Jan 2011) Log Message: ----------- Formatting and clean-up. Modified Paths: -------------- trunk/doc/docbook/src/ada.xml Modified: trunk/doc/docbook/src/ada.xml =================================================================== --- trunk/doc/docbook/src/ada.xml 2011-01-05 08:26:42 UTC (rev 11441) +++ trunk/doc/docbook/src/ada.xml 2011-01-05 22:49:31 UTC (rev 11442) @@ -1,5 +1,6 @@ - -<!-- -*- mode: nxml -*- --><!-- +<?xml version="1.0" encoding="UTF-8"?> +<!-- -*- mode: nxml -*- --> +<!-- ada.xml: "Ada Language" chapter Copyright (C) 2008-2010 Jerry Bauck @@ -30,97 +31,372 @@ 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. ---><!-- This document was created with Syntext Serna Free. --> - +--> +<!-- +Note to self: Uncomment these lines when editing with Serna or XMLmind. +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +--> <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> + + <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> + + <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'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's main concern with programming for PLplot.</para> + + <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'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'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'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 sensical. 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> + + <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'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 sensical. 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 "<emphasis>y</emphasis>'s" as a function of a single "<emphasis>x</emphasis>" with default plot appearances chosen to suit many situations. Other simple plotters are available for three-dimensional and contour plots. Manipulating PLplot'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's type system extensively to reduce the chances of inappropriate actions. For example, Ada arrays are used throughout (as opposed to C'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 "Ada" names and "PLplot" names. Also, the subroutine-specific comments from the C API have been retained verbatim.</para> + + <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 "<emphasis>y</emphasis>'s" as a function of a single + "<emphasis>x</emphasis>" with default plot appearances chosen to suit + many situations. Other simple plotters are available for + three-dimensional and contour plots. Manipulating PLplot'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's type system extensively to reduce the chances of + inappropriate actions. For example, Ada arrays are used throughout (as + opposed to C'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 "Ada" names and "PLplot" 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 "standard" 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 "normal" PLplot name can be linked to the "Ada" name along with the appropriate entry in the Ada specification, as well as another HTML file with links from the "Ada" 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 "redacted" 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> + + <para>The distinguishing feature of this thick binding (the "standard" + 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 "normal" PLplot name can be linked to the "Ada" name along + with the appropriate entry in the Ada specification, as well as another + HTML file with links from the "Ada" 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 + "redacted" 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> + + <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 30 of which demonstrate how to use many of the features of the PLplot package. These examples also serve as a testbed 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'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> + <title>The Examples</title> + + <para>An important part of the Ada bindings is the examples, some 30 of + which demonstrate how to use many of the features of the PLplot package. + These examples also serve as a testbed 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'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> + + <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'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> + + <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'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 but that activity is not officially supported by the PLplot developers. The advantage of using MacPorts is that all installation dependencies are automatically installed for you.</para> + + <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 but that activity is + not officially supported by the PLplot developers. The advantage of + using MacPorts is that all installation dependencies are automatically + installed for you.</para> </sect2> + <sect2 id="ada_obtaining_bindings"> <title>Download the Ada bindings to PLplot</title> - <para> The third major software component is the bindings themselves. Since they are currently included with the PLplot software itself, there is no need to download them from another place.</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_auxililary.adb</literal> which will be discussed later, in Section 9. These can be stored somewhere on your system's search paths for easy access.</para> + + <para>The third major software component is the bindings themselves. + Since they are currently included with the PLplot software itself, there + is no need to download them from another place.</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_auxililary.adb</literal> which will be discussed + later, in Section 9. These can be stored somewhere on your system's + search paths for easy access.</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> + + <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 <>) of Long_Float; type Real_Matrix is array (Integer range <>, Integer range <>) 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 numerics libraries.</para> -<para>For users who wish to either attain compatibility with Ada 2005 Annex G.3 or to access its features which actually depend on BLAS and LAPACK, there are two routes. One is to build PLpot normally and then to edit <literal>PLplot_Auxiliary.ads</literal> as is indicated in that file. This is a very simple process requiring commenting two lines and uncommenting three lines. Then recompile only the Ada bindings and use the newly-created compiled files in the user project. The other way is to type-convert the <literal>Real_Vector</literal> and <literal>Real_Matrix</literal> objects in the user program so that they are compatible with the declarations of Annex G.3 when accessing the numerics functionality in that annex. (In GNAT, the relevant file is <literal>a-nlrear.ads</literal>.)</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> + + <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 + numerics libraries.</para> + + <para>For users who wish to either attain compatibility with Ada 2005 + Annex G.3 or to access its features which actually depend on BLAS and + LAPACK, there are two routes. One is to build PLpot normally and then to + edit <literal>PLplot_Auxiliary.ads</literal> as is indicated in that + file. This is a very simple process requiring commenting two lines and + uncommenting three lines. Then recompile only the Ada bindings and use + the newly-created compiled files in the user project. The other way is + to type-convert the <literal>Real_Vector</literal> and + <literal>Real_Matrix</literal> objects in the user program so that they + are compatible with the declarations of Annex G.3 when accessing the + numerics functionality in that annex. (In GNAT, the relevant file is + <literal>a-nlrear.ads</literal>.)</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'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, "some text") and Pragma Warnings (On, "some text") are used in the bindings to suppress warnings about a particular method used to intereface with C code. These pragmas are also used in Ada Exaamples 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 "<literal>GNAT</literal>", "<literal>Unrestricted_Access</literal> and <literal>Pragma Warnings</literal>."</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> + + <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'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, "some text") and Pragma Warnings (On, "some + text") are used in the bindings to suppress warnings about a particular + method used to intereface with C code. These pragmas are also used in + Ada Exaamples 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 "<literal>GNAT</literal>", + "<literal>Unrestricted_Access</literal> and <literal>Pragma + Warnings</literal>."</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 "build directory" and "installation directory."</para> - <para> Here is a simple program that will generate a plot of part of a parabola.</para> + + <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 "build directory" and "installation directory."</para> + + <para>Here is a simple program that will generate a plot of part of a + parabola.</para> + <programlisting> with PLplot_Auxiliary, @@ -131,7 +407,7 @@ procedure Simple_Example is x, y : Real_Vector(-10 .. 10); begin - for i in x'range loop + for i in x'range loop x(i) := Long_Float(i); y(i) := x(i)**2; end loop; @@ -140,8 +416,21 @@ 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> + + <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 \ @@ -152,175 +441,556 @@ /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> + + <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 "simple plotters," 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 "simple plotters".</para> + + <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 "simple plotters," 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 "simple plotters".</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 autotmatically become black lines on a white background.</para> + + <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 autotmatically 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> + + <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 labeling, coloring, line width and styles, justification, and zooming.</para> + + <para>Plot up to five <emphasis>x-y</emphasis> pairs with easy + labeling, 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>'s against a single <emphasis>x</emphasis> with easy labeling and automatic line colors and styles.</para> + + <para>Plot up to five <emphasis>y</emphasis>'s against a single + <emphasis>x</emphasis> with easy labeling 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> + <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> + + <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> + + <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 labeling and automatic line colors and styles.</para> + + <para>Plot up to five <emphasis>x</emphasis>-<emphasis>y</emphasis> + pairs with easy labeling 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> + + <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> + + <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> + + <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> + + <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 easlily 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 "reset" 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> - <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> - <para> Color resetting functions for the 16 colors of color map 0</para> - <para><literal> Reset_Black, Reset_Red, …, Reset_White</literal></para> - <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> - <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> + + <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 easlily 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 "reset" + 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 "re-namings" 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> + <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 + "re-namings" 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> Colors: Plot_Color_Type</para> - <para> <literal> 0</literal> is Black, <literal>1</literal> is Red, etc.</para> - <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> - <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> - <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> - <para> Character sets: <literal>Character_Set_Type</literal></para> - <para><literal> Standard_Character_Set</literal></para> - <para><literal> Extended_Character_Set</literal></para> - <para> Plot orientation: <literal>Orientation_Type</literal></para> - <para><literal> Landscape</literal></para> - <para><literal> Portrait</literal></para> - <para> Modes for parsing command line arguments: <literal>Parse_Mode_Type</literal></para> - <para> E.g. <literal>PL_PARSE_PARTIAL</literal></para> - <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> - <para> Various style and view options for 3D and surface plots</para> - <para> E.g. <literal>Lines_Parallel_To_X</literal></para> - <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> - <para> Flags for histogram style</para> - <para> E.g. <literal>Histogram_Default</literal></para> - <para> Flags for histogram binning</para> - <para> E.g. <literal>Bin_Default</literal></para> - <para> Names for color space models</para> - <para> Hue, Lightness, Saturation: <literal>HLS</literal></para> - <para> Red, Green, Blue: <literal>RGB</literal></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... [truncated message content] |
From: <ai...@us...> - 2011-02-21 17:20:31
|
Revision: 11573 http://plplot.svn.sourceforge.net/plplot/?rev=11573&view=rev Author: airwin Date: 2011-02-21 17:20:25 +0000 (Mon, 21 Feb 2011) Log Message: ----------- Replace odd character (probably utf8) that was causing validation errors with set of equivalent ascii characters "...," Modified Paths: -------------- trunk/doc/docbook/src/ada.xml Modified: trunk/doc/docbook/src/ada.xml =================================================================== --- trunk/doc/docbook/src/ada.xml 2011-02-21 07:39:43 UTC (rev 11572) +++ trunk/doc/docbook/src/ada.xml 2011-02-21 17:20:25 UTC (rev 11573) @@ -615,8 +615,7 @@ <para>Color resetting functions for the 16 colors of color map 0</para> - <para><literal>Reset_Black, Reset_Red, …, - Reset_White</literal></para> + <para><literal>Reset_Black, Reset_Red, ..., Reset_White</literal></para> </listitem> <listitem> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <jb...@us...> - 2012-08-15 10:18:01
|
Revision: 12215 http://plplot.svn.sourceforge.net/plplot/?rev=12215&view=rev Author: jbauck Date: 2012-08-15 10:17:55 +0000 (Wed, 15 Aug 2012) Log Message: ----------- Change Ada doc to reflect a recent minor change in the Ada binding API related to HLS access to cmap1. Modified Paths: -------------- trunk/doc/docbook/src/ada.xml Modified: trunk/doc/docbook/src/ada.xml =================================================================== --- trunk/doc/docbook/src/ada.xml 2012-08-14 22:33:21 UTC (rev 12214) +++ trunk/doc/docbook/src/ada.xml 2012-08-15 10:17:55 UTC (rev 12215) @@ -874,8 +874,8 @@ 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>(Reverse_Hue_None, - Reverse_Hue_All)</literal>.</para> + 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> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <jb...@us...> - 2013-09-25 04:35:02
|
Revision: 12527 http://sourceforge.net/p/plplot/code/12527 Author: jbauck Date: 2013-09-25 04:34:57 +0000 (Wed, 25 Sep 2013) Log Message: ----------- Update Ada docs. Modified Paths: -------------- trunk/doc/docbook/src/ada.xml Modified: trunk/doc/docbook/src/ada.xml =================================================================== --- trunk/doc/docbook/src/ada.xml 2013-09-25 02:16:25 UTC (rev 12526) +++ trunk/doc/docbook/src/ada.xml 2013-09-25 04:34:57 UTC (rev 12527) @@ -227,7 +227,7 @@ <sect1 id="ada_examples"> <title>The Examples</title> - <para>An important part of the Ada bindings is the examples, some 30 of + <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 @@ -277,18 +277,16 @@ 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 but that activity is - not officially supported by the PLplot developers. The advantage of + 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>Download the Ada bindings to PLplot</title> + <title>The Ada bindings to PLplot</title> - <para>The third major software component is the bindings themselves. - Since they are currently included with the PLplot software itself, there - is no need to download them from another place.</para> + <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>, @@ -298,8 +296,7 @@ <literal>plplothin.ads</literal>, and <literal>plplotthin.adb</literal>. There are two additional files, <literal>plplot_auxiliary.ads</literal> and <literal>plplot_auxililary.adb</literal> which will be discussed - later, in Section 9. These can be stored somewhere on your system's - search paths for easy access.</para> + later, in Section 9.</para> </sect2> </sect1> @@ -328,18 +325,22 @@ to these types and in the process require linking to the BLAS and LAPACK numerical libraries.</para> - <para>For users who wish to either attain compatibility with Ada 2005 - Annex G.3 or to access its features which actually depend on BLAS and - LAPACK, there are two routes. One is to build PLplot normally and then to - edit <literal>PLplot_Auxiliary.ads</literal> as is indicated in that - file. This is a very simple process requiring commenting two lines and - uncommenting three lines. Then recompile only the Ada bindings and use - the newly-created compiled files in the user project. The other way is - to type-convert the <literal>Real_Vector</literal> and - <literal>Real_Matrix</literal> objects in the user program so that they - are compatible with the declarations of Annex G.3 when accessing the - numerical functionality in that annex. (In GNAT, the relevant file is - <literal>a-nlrear.ads</literal>.)</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 @@ -948,6 +949,9 @@ 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> @@ -968,28 +972,21 @@ <title>X11</title> <para>Apple supplies the X11 windowing system that is popular on some - other Unix and Linux operations systems as part of the Developer Tools. + 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 Examples 14 and 17 will not run on - Apple's X11 (as of OS X 10.4 at least) and must be run on X11 (or some - other output device such as TCL/TK).</para> + some types of interactivity such as Example 17 will not run on + Apple'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>Apple Macintosh users will benefit from a pre-built version of - GNAT that comes packaged using the usual Apple software installer and is - strongly recommended. This compiler is available for both PowerPC and - Intel Macintoshes at <ulink - url="http://www.macada.org/macada/Welcome.html">www.macada.org</ulink>. - This site is traditionally rather confusing but the mailing list is - extremely helpful. The installer also includes an Ada-specific plug-in - for Apple's Xcode IDE which is strongly recommended if you plan to work - on this platform. Xcode is part of the Developer Tools and is available - on the Apple system disks that also contain the operating system or it - can be downloaded for free from <ulink - url="http://developer.apple.com/tools/xcode/">here</ulink>.</para> + <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> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <jb...@us...> - 2013-12-11 07:49:38
|
Revision: 12846 http://sourceforge.net/p/plplot/code/12846 Author: jbauck Date: 2013-12-11 07:49:35 +0000 (Wed, 11 Dec 2013) Log Message: ----------- Update Ada documentation for new arrow-resetting feature and variant Ada-specific implementations Modified Paths: -------------- trunk/doc/docbook/src/ada.xml Modified: trunk/doc/docbook/src/ada.xml =================================================================== --- trunk/doc/docbook/src/ada.xml 2013-12-11 07:26:37 UTC (rev 12845) +++ trunk/doc/docbook/src/ada.xml 2013-12-11 07:49:35 UTC (rev 12846) @@ -1,6 +1,5 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- -*- mode: nxml -*- --> -<!-- +<?xml version='1.0' encoding='UTF-8'?> +<!-- -*- mode: nxml -*- --><!-- ada.xml: "Ada Language" chapter Copyright (C) 2008-2010 Jerry Bauck @@ -31,27 +30,20 @@ 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. -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> ---> +--><!-- 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. --> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" []> <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 @@ -59,30 +51,24 @@ 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's code and the + and as such are a kind of abstract layer between the user'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's main concern with + functionality. The thick bindings are the user'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, @@ -93,21 +79,18 @@ 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's type system. Thus, the thin binding refers to + binding by use of Ada'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 @@ -118,40 +101,34 @@ 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 "<emphasis>y</emphasis>'s" as a function of a single - "<emphasis>x</emphasis>" with default plot appearances chosen to suit + from one to five "<emphasis>y</emphasis>'s" as a function of a single + "<emphasis>x</emphasis>" with default plot appearances chosen to suit many situations. Other simple plotters are available for - three-dimensional and contour plots. Manipulating PLplot's colors is + three-dimensional and contour plots. Manipulating PLplot'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's type system extensively to reduce the chances of + structures and Ada's type system extensively to reduce the chances of inappropriate actions. For example, Ada arrays are used throughout (as - opposed to C's + opposed to C'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 @@ -160,19 +137,16 @@ 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 "Ada" names and "PLplot" names. Also, the + associations between "Ada" names and "PLplot" 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 "standard" + <para>The distinguishing feature of this thick binding (the "standard" 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 @@ -185,13 +159,12 @@ <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 "normal" PLplot name can be linked to the "Ada" name along + so that a "normal" PLplot name can be linked to the "Ada" name along with the appropriate entry in the Ada specification, as well as another - HTML file with links from the "Ada" name directly to the PLplot web page + HTML file with links from the "Ada" 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 @@ -199,34 +172,27 @@ 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 - "redacted" version which should be correct for Ada as well as other + "redacted" 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 @@ -235,21 +201,17 @@ 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't (normally) make Postscript. Two versions + operate interactively and don'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 @@ -259,35 +221,27 @@ 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's OS + 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'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>. + <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>, @@ -299,23 +253,18 @@ 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 <>) of Long_Float; type Real_Matrix is array (Integer range <>, Integer range <>) 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 @@ -324,7 +273,6 @@ <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 @@ -341,16 +289,13 @@ 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 @@ -360,44 +305,35 @@ (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't be difficult to remove by either incorporating the GNAT code + shouldn'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, "some text") and Pragma Warnings (On, "some - text") are used in the bindings to suppress warnings about a particular + <para>Pragma Warnings (Off, "some text") and Pragma Warnings (On, "some + text") 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 "<literal>GNAT</literal>", - "<literal>Unrestricted_Access</literal> and <literal>Pragma - Warnings</literal>."</para> - + code for "<literal>GNAT</literal>", + "<literal>Unrestricted_Access</literal> and <literal>Pragma Warnings</literal>."</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 "build directory" and "installation directory."</para> - + lingo of "build directory" and "installation directory."</para> <para>Here is a simple program that will generate a plot of part of a parabola.</para> - <programlisting> with PLplot_Auxiliary, @@ -408,7 +344,7 @@ procedure Simple_Example is x, y : Real_Vector(-10 .. 10); begin - for i in x'range loop + for i in x'range loop x(i) := Long_Float(i); y(i) := x(i)**2; end loop; @@ -417,7 +353,6 @@ 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 @@ -425,13 +360,11 @@ 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 \ @@ -442,32 +375,25 @@ /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 "simple plotters," and easy color map + control, a collection of "simple plotters," 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 "simple plotters".</para> - + most of their work using the "simple plotters".</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 @@ -478,92 +404,68 @@ 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>'s against a single + <para>Plot up to five <emphasis>y</emphasis>'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 @@ -571,7 +473,6 @@ 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> @@ -582,203 +483,143 @@ <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 "reset" + <literal>Set_Pen_Color(Reset_Red)</literal> instead. These 16 "reset" 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 - "re-namings" have been applied. In some cases the entire range of values + "re-namings" 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 @@ -788,7 +629,6 @@ <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, @@ -796,12 +636,10 @@ 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 @@ -809,7 +647,6 @@ <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 @@ -819,54 +656,55 @@ 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 + 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 "C only." Many of these features are actually available in + described as "C only." 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 - "C only" but is actually available in Ada.</para> + "C only" 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> @@ -875,40 +713,32 @@ 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> + 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 "switching" + manipulation facilities. If not for the desire for this easy "switching" 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 @@ -917,74 +747,56 @@ 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's free integrated development + which run OS X. OS X users may use Apple'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's Xcode IDE</title> - - <para>The Macintosh Ada community has made a plug-in for Apple's free + <title>Using Apple's Xcode IDE</title> + <para>The Macintosh Ada community has made a plug-in for Apple'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 & 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 + 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> + 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 - "terminal" that is highly recommended. All output is antialiased and is - easily cut-and-pasted in OS X'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> + "terminal" that is highly recommended. All output is antialiased and is + easily cut-and-pasted in OS X'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's Terminal.app and should be run on X11 (or + Apple'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>. + <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> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <ai...@us...> - 2013-12-20 18:10:15
|
Revision: 12895 http://sourceforge.net/p/plplot/code/12895 Author: airwin Date: 2013-12-20 18:10:11 +0000 (Fri, 20 Dec 2013) Log Message: ----------- "DOCTYPE" declaration not allowed in chapters that are a subset of the whole document. The removal of this line fixed the validation error generated by "make validate". Modified Paths: -------------- trunk/doc/docbook/src/ada.xml Modified: trunk/doc/docbook/src/ada.xml =================================================================== --- trunk/doc/docbook/src/ada.xml 2013-12-20 17:44:12 UTC (rev 12894) +++ trunk/doc/docbook/src/ada.xml 2013-12-20 18:10:11 UTC (rev 12895) @@ -32,7 +32,6 @@ 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. --> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" []> <chapter id="ada"> <title>Ada Language</title> <para>This document describes the Ada bindings to the PLplot technical This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |