This is an interface to PLplot (http://plplot.org/) 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.inc 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.inc in the build tree to
bindings/ocaml/plplot_h.inc 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 the
  OCaml binding 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.  For example, this includes functions
  which take callbacks and void pointers as arguments.

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

- plplot.ml:
  This file contains an OCaml-specific interface to parts of the OCaml
  binding for the C PLplot API.  For example, higher level wrappers
  for the OCaml API for pllegend and plcolorbar are implemented here.
  This is a work-in-progress by Hez for those interested in a native
  OCaml look for plotting, but it is not a file where changes need to
  be made when introducing new API in order to get our standard OCaml
  examples to work correctly (i.e., give the same results as the
  corresponding C examples).

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.  There are two broad categories to consider
here.

1. PLplot API that can be generated by camlidl using plplot_h and
touchup.ml

This category is the vast majority of PLplot API.  In this category 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 for the
  benefit of camlidl.

- 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.

2. PLplot API that cannot be generated by camlidl (e.g., if the
function arguments include a callback function.)  In this category I
recently added plmapline, plmapstring, plmaptex, and plmapfill
following what had previously been done for plmap.  Those additions
required the following changes:

- Update plplot_impl.c to add these additional plmap* variants.

- Update plplot_core.idl to add these additional plmap* variants

To follow up with adding PLplot API in either category 1. or 2. the following change
is required:

- Update plplot.mli to describe the OCaml module interface definition
  of the added routine(s).  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.