doc: Add documentation of low level bindings.

* doc/snarf.scm: New file.
* Makefile.am (EXTRA_DIST): Add it.
(doc/low.texi): New target.
(drmaa_TEXINFOS): New definition.
(CLEANFILES): Add generated doc/low.texi.
* doc/drmaa.texi: Include doc/low.texi.

3 files changed, 118 insertions, 1 deletions

diff --git a/Makefile.am b/Makefile.am
index ee467f0..9696eda 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -24,7 +24,7 @@ nobase_go_DATA = $(GOBJECTS)
 guile_install_go_files = install-nobase_goDATA
 $(guile_install_go_files): install-nobase_modDATA
 
-EXTRA_DIST = $(SOURCES) $(NOCOMP_SOURCES) drmaa/v1/ffi.ffi
+EXTRA_DIST = $(SOURCES) $(NOCOMP_SOURCES) drmaa/v1/ffi.ffi doc/snarf.scm
 GUILE_WARNINGS = -Wunbound-variable -Warity-mismatch -Wformat
 SUFFIXES = .scm .go .ffi
 .scm.go:
@@ -56,7 +56,12 @@ AM_SCM_LOG_FLAGS = --no-auto-compile -L "$(top_srcdir)"
 
 AM_TESTS_ENVIRONMENT = abs_top_srcdir="$(abs_top_srcdir)"
 
+
+doc/low.texi: drmaa/v1/low.go
+	$(AM_V_GEN)$(top_builddir)/pre-inst-env $(GUILE) doc/snarf.scm
+
 info_TEXINFOS = doc/drmaa.texi
+drmaa_TEXINFOS = doc/low.texi
 dvi: # Don't build dvi docs
 
 EXTRA_DIST += README.org \
@@ -92,6 +97,7 @@ clean-go:
 .NOTPARALLEL:
 
 CLEANFILES =					\
+  doc/low.texi					\
   drmaa/v1/ffi.scm				\
   $(GOBJECTS)					\
   $(TESTS:tests/%.scm=%.log)
diff --git a/doc/drmaa.texi b/doc/drmaa.texi
index 494adc1..1146725 100644
--- a/doc/drmaa.texi
+++ b/doc/drmaa.texi
@@ -49,6 +49,7 @@ This document describes Guile DRMAA version @value{VERSION}.
 @menu
 * Introduction::                Why Guile DRMAA?
 * Installation::                How do I install it?
+* Low-level bindings::          Bindings that closely wrap the library procedures.
 @end menu
 
 @c *********************************************************************
@@ -84,4 +85,10 @@ If you want to build the sources from the source repository you need to
 bootstrap the build system first.  Run the @code{bootstrap.sh} script
 first and then perform the above steps.
 
+@c *********************************************************************
+@node Low-level bindings
+@chapter Low-level bindings
+
+@include low.texi
+
 @bye
diff --git a/doc/snarf.scm b/doc/snarf.scm
new file mode 100644
index 0000000..5dd2f7d
--- /dev/null
+++ b/doc/snarf.scm
@@ -0,0 +1,104 @@
+;;; Copyright © 2021 Ricardo Wurmus <rekado@elephly.net>
+;;;
+;;; This program is free software; you can redistribute it and/or modify it
+;;; under the terms of the GNU General Public License as published by
+;;; the Free Software Foundation; either version 3 of the License, or (at
+;;; your option) any later version.
+;;;
+;;; This program is distributed in the hope that it will be useful, but
+;;; WITHOUT ANY WARRANTY; without even the implied warranty of
+;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;;; GNU General Public License for more details.
+;;;
+;;; You should have received a copy of the GNU General Public License
+;;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+;;;; Commentary:
+;;;
+;;; This script extracts docstrings from a module and spits out a
+;;; TexInfo file.
+;;;
+;;;; Code:
+
+(use-modules (ice-9 match)
+             (ice-9 session))
+
+(define (arguments->string proc)
+  (match (procedure-arguments proc)
+    ((('required . req-names)
+      ('optional . opt-names)
+      ('keyword . kw-names)
+      ('allow-other-keys? . any)
+      ('rest . rest))
+     (string-join
+      (list
+       (format #false "~{@var{~a}~^ ~}" req-names)
+       (format #false "~:[[~{@var{~a}~^ ~}]~;~]" (null? opt-names) opt-names)
+       (format #false "~:[[~{@var{~a}~^ ~}]~;~]" (null? kw-names) (map car kw-names))
+       (format #false "~@[@var{~a} ...~]" rest))))))
+
+(define (fancy-docstring proc known-procedures)
+  (define arguments
+    (match (procedure-arguments proc)
+      ((('required . req-names)
+        ('optional . opt-names)
+        ('keyword . kw-names)
+        ('allow-other-keys? . any)
+        ('rest . rest))
+       (let ((kws (map (compose keyword->symbol car)
+                       kw-names)))
+         (map symbol->string
+              (append req-names opt-names kws
+                      (if rest (list rest) '())))))))
+  (define (argument? word)
+    (member (string-downcase word) arguments))
+  (define* (maybe-wrap word #:optional (trail ""))
+    (let ((word* (string-drop-right word (string-length trail))))
+      (if (or (member word* '("#TRUE" "#FALSE" "*"))
+              (member word* known-procedures)
+              (argument? word*))
+          (string-append "@var{" (string-downcase word*) "}" trail)
+          (string-append word* trail))))
+  (let ((words (string-tokenize (procedure-documentation proc))))
+    (string-join (map (lambda (word)
+                        (cond
+                         ((string-suffix? "." word)
+                          (maybe-wrap word "."))
+                         ((string-suffix? "," word)
+                          (maybe-wrap word ","))
+                         ((string-suffix? ";" word)
+                          (maybe-wrap word ";"))
+                         (else
+                          (maybe-wrap word))))
+                      words))))
+
+(define (docs module)
+  (define known-procedures
+    (module-map (lambda (sym var)
+                  (string-upcase (symbol->string sym)))
+                (resolve-interface module)))
+  (let ((unsorted
+         (module-map
+          (lambda (sym var)
+            (let ((proc (variable-ref var)))
+              (cons sym (format #false
+                                "\
+@cindex ~a
+@deffn {Scheme Procedure} ~a ~a
+~a
+@end deffn
+" sym sym
+                                (arguments->string proc)
+                                (fancy-docstring proc known-procedures)))))
+          (resolve-interface module))))
+    (sort unsorted (lambda (a b)
+                     (string< (symbol->string (car a))
+                              (symbol->string (car b)))))))
+
+(with-output-to-file "doc/low.texi"
+  (lambda ()
+    (for-each (match-lambda
+                ((sym . doc)
+                 (display doc)
+                 (newline)))
+              (docs '(drmaa v1 low)))))