From b2c0e9f9856fef10ff761ca5ab0f3b7675e84c52 Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Sat, 8 Jul 2017 09:42:25 -0700
Subject: doc: subdivide FFI-related functions

* txr.1: The functions and macros in FFI are divided into
logical groups with own section headings.
---
 txr.1 | 34 +++++++++++++++++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/txr.1 b/txr.1
index e82c47d9..95571c12 100644
--- a/txr.1
+++ b/txr.1
@@ -55951,7 +55951,10 @@ printf("hello, %s\en", name)
 .cble
 requires a different descriptor.
 
-.SS* Foreign Function Functions and Macros
+.SS* Foreign Function Type API
+
+This group of functions comprises the basic interface to the \*(TL's FFI
+type system module.
 
 .coNP Function @ ffi-type-compile
 .synb
@@ -56439,6 +56442,12 @@ or
   (ffi-elemtype (ffi (ptr int))) -> #<ffi-type int>
 .cble
 
+.SS* Foreign Function Macro Language
+
+This group of macros provides a higher-level language for working with
+FFI types and defining foreign function bindings. The macros are implemented
+using the Foreign Function Type API described in the previous section.
+
 .coNP Macro @ with-dyn-lib
 .synb
 .mets (with-dyn-lib < lib-expr << body-form *)
@@ -56963,6 +56972,8 @@ following equivalence holds:
   (ffi expr)  <-->  (ffi-type-compile 'expr)
 .cble
 
+.SS* Zero-filled Struct Initialization
+
 .coNP Function @ make-zstruct
 .synb
 .mets (make-zstruct < type >> { slot-sym << init-value }*)
@@ -57085,6 +57096,13 @@ the following results are observed:
   (znew foo b 42) -> #S(foo a #<cptr bar: 0> b 42 c nil)
 .cble
 
+.SS* Foreign Unions
+
+The following group of functions provides the means for working
+with foreign unions, in conjunction with the
+.code union
+FFI type.
+
 .coNP Function @ make-union
 .synb
 .mets (make-union < type >> [ initval <> [ member ]])
@@ -57255,6 +57273,13 @@ an argument, in cases when the callback has updated the Lisp
 object corresponding to a union member, and that change needs
 to be propagated to the foreign caller.
 
+.SS* Buffer Functions
+
+Functions in this area provide a way to perform conversion between
+Lisp objects and foreign representation to and from objects of the
+.code buf
+type.
+
 .coNP Functions @ ffi-put and @ ffi-put-into
 .synb
 .mets (ffi-put < obj << type )
@@ -57398,6 +57423,13 @@ in order to extract the return value of foreign function
 calls, and by the FFI callback mechanism to extract the
 arguments coming into a callback.
 
+.SS* Foreign Arrays
+
+Functions in this area provide a means for working with
+foreign arrays, in connection with the FFI
+.code carray
+type.
+
 .coNP Functions @ carray-vec and @ carray-list
 .synb
 .mets (carray-vec < vec < type <> [ null-term-p ])
-- 
cgit v1.2.3