doc: Document high-level bindings.

1 files changed, 28 insertions, 0 deletions

diff --git a/doc/drmaa.texi b/doc/drmaa.texi
index 1146725..58a22c6 100644
--- a/doc/drmaa.texi
+++ b/doc/drmaa.texi
@@ -50,6 +50,7 @@ This document describes Guile DRMAA version @value{VERSION}.
 * Introduction::                Why Guile DRMAA?
 * Installation::                How do I install it?
 * Low-level bindings::          Bindings that closely wrap the library procedures.
+* High-level bindings::         Friendlier ``Schemey'' bindings that use the low-level bindings.
 @end menu
 
 @c *********************************************************************
@@ -91,4 +92,31 @@ first and then perform the above steps.
 
 @include low.texi
 
+@c *********************************************************************
+@node High-level bindings
+@chapter High-level bindings
+@cindex (drmaa v1 high)
+
+The high-level bindings in @code{(drmaa v1 high)} re-export most of
+the low-level bindings, but also add a couple of convenient macros and
+wrappers.
+
+Most importantly, it provides the GOOPS constructor
+@code{job-template} to generate managed values of type
+@code{<job-template>}.  This type checks and transforms its arguments,
+allocates an opaque low-level job template value and destroys it on
+errors, and even handles conversion of some attributes by replacing
+them with native specifications where possible.
+
+The macro @code{with-job-template} ensures that the job template is
+destroyed when it is no longer needed, i.e. when the body of the
+procedure has been evaluated.  The convenience procedures
+@code{run-job} and @code{run-bulk-job} wrap their low-level
+equivalents with this macro.
+
+The macro @code{with-drmaa-session} initializes the DRMAA session with
+the low-level @code{init-session!}, runs its body within the session,
+and then exits the session with @code{exit-session!}.
+
+
 @bye