[Plplot-cvs] SF.net SVN: plplot:[12527] trunk/doc/docbook/src/ada.xml

[<jb...@us...>]

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.