This is an interface to PLplot (http://plplot.sourceforge.net/) for the
Objective Caml language.

* REQUIREMENTS
- OCaml (currently tested with 4.0.1 and later, but earlier versions may work.)

- camlidl

* FILES
This is a list of the files which make up the OCaml bindings, along with a
description of their purpose.

- plplot_h:
  - This is a simplified version of include/plplot.h

- touchup.ml:
  - This script processes plplot_h to add some annotations to make the file
    ready for use with camlidl.

N.B. the above two files are used to indirectly generate plplot_h.inc on Linux
as follows:

Use the CMake option -DGENERATE_PLPLOT_H_INC=ON, and build the target
check_plplot_h.inc.  That target uses the above two files to generate
bindings/ocaml/generated_plplot_h.inc in the build tree, and compares
that result with bindings/ocaml/plplot_h.inc in the source tree.
If those two files differ, the check_plplot_h.in target will fail, and
you should look carefully at the differences to make sure they are what
is desired from your change(s) to plplot_h and/or touchup.ml.  Assuming
the changes are the desired ones, copy
bindings/ocaml/generated_plplot_h.in in the build tree to bindings/ocaml/plplot_h.in
which will make this target succeed until the next change to plplot_h
and/or touchup.ml.

Code generation (used in the CMake build system to automatically generate code):

- plplot_h.inc:
  - This is a simplified and annotated version of include/plplot.h, generated
    by touchup.ml, which contains camlidl-ready definitions of most of the
    PLplot functions.

- plplot_core.idl:
  - This file (which includes plotplot_h.inc) contains the definitions of all
    of the functions and data types required to generate OCaml bindings for
    the C PLplot API.  camlidl uses this file to produce the C and OCaml code
    required to interface with the core PLplot API.

Hand-written source code (used in the CMake build system):

- plplot_impl.c:
  - This file contains C stubs for functions which are not currently handled
    correctly by camlidl.  This includes functions which take callbacks and
    void pointers as arguments.

- plplot.ml:
  - This file contains the OCaml-specific interface to PLplot as well as the
    core PLplot API.

- plplot.mli:
  - This file contains the Plplot OCaml module interface definition and
    ocamldoc comments.

Misc:

- META.cmake (processed by CMake to produce META)
  - A findlib-compatible META-file.  The PLplot OCaml bindings can be used
    with findlib (ocamlfind and the OCaml toplevel).  Please see the OCaml
    section of the PLplot documentation for more information on using findlib
    with the OCaml PLplot bindings.

- README
  - This file.

* NOTES

Changes to the above files are typically required when implementing additional
PLplot API.  For example, I recently added plsurf3dl to the OCaml binding.
That addition required the following changes:

- Update plplot_h to describe the C API of the added routine.

- Update touchup.ml to handle the unique index arguments of that function.
  It turned out that there is some bug in touchup.ml so I could not do
  that by adding a stanza to manual_function_attributes, but adding
  a stanza to the list in the parameter_attributes function did the
  job.

- Update plplot_h.inc using the procedure described above.

- Update plplot.mli to describe the OCaml module interface definition
  of the added routine.  If you forget to do this or there is
  some inconsistency in how you describe the interface definition,
  then attempting to build the plplot_ocaml target will error out
  with a fairly good description of the inconsistency.
