[Plplot-general] Notes on Ada binding (also documentation and Modula-3)

[Jerry <lan...@qw...>]

This is a continuation of an earlier thread about identifying which C  
subroutines in plplot.h return scalars, since the C syntax is  
ambiguous with respect to whether the intention is to return e.g. a  
float scalar or to pass an array of floats.

I downloaded the documentation in HTML format and made a list of  
files that begin with "pl" and which contain the word "output." (The  
Spotlight function in OS X rocks for this kind of thing.) Some of the  
hits were spurious in their use of "output" which files I ignored.

I took the API reference literally if it said that a parameter is an  
output, and made the corresponding Ada parameter say "out", rather  
than "in out" which would be allowed by a C pointer or a Pascal or  
Modula-3 "var".

The following subprograms in the Common API had output scalars which  
required special attention to make sure that Ada understands that  
some arguments are output scalars and not pointers to arrays. I've  
included a few notes that may be of interest to the documentation  
writers and to the Modula-3 binding writer. Please note that I have  
used 5.5.3 for plplot.h and 5.6.1 for the API documentation. Also,  
note that not all routines which return results begin with "plg".

plcalc_world
plgchr
plgcol0  API reference says this is 8 bits but plplot.h says integer
plgcolbg API reference says this is 8 bits but plplot.h says integer
plgcompression
plgdev Missing from Modula-3
plgdidev
plgdiori
plgdiplt
plgfam
plgfci Missing from Modula-3
plglevel
plgpage
plgriddata API description of parameter "type" is incomplete. Missing  
from Modula-3
plgspa
plgstrm
plgver Missing from Modula-3
plgvpd
plgvpw
plgxax
plgyax
plgzax
plhlsrgb Missing from Modula-3
plmkstrm
plrgbhls API description reverses "input" and "output". Missing from  
Modula-3
plstripc
plxormod



Other Notes:

plexit is listed in the API reference but does not appear in  
plplot.h. Note that I am using version 5.5.3 and the API appears to  
be for 5.6.1.

plsdev In API description, the parameter is marked as output but is  
input.

plsetopt Ditto both args (Note: not part of common API)

Jerry