--- cffi-sys-spec.texinfo~	2005-11-09 09:23:07.000000000 -0600
+++ cffi-sys-spec.texinfo	2005-12-19 12:55:21.000000000 -0600
@@ -2,7 +2,6 @@
 @c %**start of header??
 @setfilename cffi-sys.info
 @settitle CFFI-SYS Interface Specification
-@c %**end of header
 
 @c Show types in the same index as the functions.
 @synindex tp fn
@@ -22,17 +21,22 @@
 The above copyright notice and this permission notice shall be
 included in all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
-HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
-DEALINGS IN THE SOFTWARE.
+@sc{The software is provided ``as is'', without warranty of any kind,
+express or implied, including but not limited to the warranties of
+merchantability, fitness for a particular purpose and
+noninfringement.  In no event shall the authors or copyright
+holders be liable for any claim, damages or other liability,
+whether in an action of contract, tort or otherwise, arising from,
+out of or in connection with the software or the use or other
+dealings in the software.}
 @end quotation
 @end copying
 
+@macro impnote {text}
+@emph{Implementor's note: \text\}
+@end macro
+@c %**end of header
+
 @titlepage
 @title CFFI-SYS Interface Specification
 @c @subtitle Version X.X
@@ -60,17 +64,18 @@
 * Memory Access::               
 * Foreign Function Calling::    
 * Loading Foreign Libraries::   
+* Foreign Globals::             
 * Symbol Index::                
 @end menu
 
 @node Introduction
 @chapter Introduction
 
-CFFI, the Common Foreign Function Interface, purports to be a portable
-foreign function interface for Common Lisp.
+@acronym{CFFI}, the Common Foreign Function Interface, purports to be
+a portable foreign function interface for Common Lisp.
 
-This specification defines a set of low-level primitives that
-must be defined for each Lisp implementation supported by CFFI.
+This specification defines a set of low-level primitives that must be
+defined for each Lisp implementation supported by @acronym{CFFI}.
 These operators are defined in the @code{CFFI-SYS} package.
 
 The @code{CFFI} package uses the @code{CFFI-SYS} interface
@@ -79,76 +84,67 @@
 defining foreign function calls, and automatic conversion of
 foreign function arguments to/from Lisp types.
 
-@subheading Naming Convention
+Please note the following conventions that apply to everything in
+@code{CFFI-SYS}:
+
+@itemize @bullet
+@item
+Functions in @code{CFFI-SYS} that are low-level versions of functions
+exported from the @code{CFFI} package begin with a leading
+percent-sign (eg. @code{%mem-ref}).
+
+@item
+Where ``foreign type'' is mentioned as the kind of an argument, the
+meaning is restricted to that subset of all foreign types defined in
+@ref{Built-In Foreign Types}.  Support for higher-level types is
+always defined in terms of those lower-level types in @code{CFFI}
+proper.
+@end itemize
 
-@noindent
-Functions in @code{CFFI-SYS} that are low-level versions of
-functions exported from the @code{CFFI} package begin with a
-leading percent-sign (eg. @code{%mem-ref}).
 
 @node Built-In Foreign Types
 @chapter Built-In Foreign Types
 
 @deftp {Foreign Type} :char
-@end deftp
-@deftp {Foreign Type} :unsigned-char
-@end deftp
-@deftp {Foreign Type} :short
-@end deftp
-@deftp {Foreign Type} :unsigned-short
-@end deftp
-@deftp {Foreign Type} :int
-@end deftp
-@deftp {Foreign Type} :unsigned-int
-@end deftp
-@deftp {Foreign Type} :long
-@end deftp
-@deftp {Foreign Type} :unsigned-long
-@end deftp
-@deftp {Foreign Type} :long-long
-@end deftp
-@deftp {Foreign Type} :unsigned-long-long
+@deftpx {Foreign Type} :unsigned-char
+@deftpx {Foreign Type} :short
+@deftpx {Foreign Type} :unsigned-short
+@deftpx {Foreign Type} :int
+@deftpx {Foreign Type} :unsigned-int
+@deftpx {Foreign Type} :long
+@deftpx {Foreign Type} :unsigned-long
+@deftpx {Foreign Type} :long-long
+@deftpx {Foreign Type} :unsigned-long-long
 These types correspond to the native C integer types according to the
 ABI of the system the Lisp implementation is compiled against.
 @end deftp
 
 @deftp {Foreign Type} :int8
-@end deftp
-@deftp {Foreign Type} :uint8
-@end deftp
-@deftp {Foreign Type} :int16
-@end deftp
-@deftp {Foreign Type} :uint16
-@end deftp
-@deftp {Foreign Type} :int32
-@end deftp
-@deftp {Foreign Type} :uint32
-@end deftp
-@deftp {Foreign Type} :int64
-@end deftp
-@deftp {Foreign Type} :uint64
+@deftpx {Foreign Type} :uint8
+@deftpx {Foreign Type} :int16
+@deftpx {Foreign Type} :uint16
+@deftpx {Foreign Type} :int32
+@deftpx {Foreign Type} :uint32
+@deftpx {Foreign Type} :int64
+@deftpx {Foreign Type} :uint64
 Foreign integer types of specific sizes, corresponding to the C types
 defined in @code{stdint.h}.
 @end deftp
 
 @deftp {Foreign Type} :size
-@end deftp
-@deftp {Foreign Type} :ssize
-@end deftp
-@deftp {Foreign Type} :ptrdiff
-@end deftp
-@deftp {Foreign Type} :time
+@deftpx {Foreign Type} :ssize
+@deftpx {Foreign Type} :ptrdiff
+@deftpx {Foreign Type} :time
 Foreign integer types corresponding to the standard C types (without
 the @code{_t} suffix).
 @end deftp
 
-@emph{I'm sure there are more of these that could be useful, let's
+@impnote{I'm sure there are more of these that could be useful, let's
 add any types that can't be defined portably to this list as
 necessary.}
 
 @deftp {Foreign Type} :float
-@end deftp
-@deftp {Foreign Type} :double
+@deftpx {Foreign Type} :double
 The @code{:float} type represents a C @code{float} and a Lisp
 @code{single-float}. @code{:double} represents a C @code{double} and a
 Lisp @code{double-float}.
@@ -167,18 +163,18 @@
 @node Operations on Foreign Types
 @chapter Operations on Built-in Foreign Types
 
-@defun %foreign-type-size type => size
-Return the @code{size}, in bytes, of objects having foreign type
-@code{type}. An error is signalled if @code{type} is not a known
+@defun %foreign-type-size type @result{} size
+Return the @var{size}, in bytes, of objects having foreign type
+@var{type}. An error is signalled if @var{type} is not a known
 built-in foreign type.
 @end defun
 
-@defun %foreign-type-alignment type => alignment
+@defun %foreign-type-alignment type @result{} alignment
 Return the default alignment in bytes for structure members of foreign
-type @code{type}. An error is signalled if @code{type} is not a known
+type @var{type}. An error is signalled if @var{type} is not a known
 built-in foreign type.
 
-@emph{Maybe this should take an optional keyword argument specifying an
+@impnote{Maybe this should take an optional keyword argument specifying an
 alternate alignment system, eg. :mac68k for 68000-compatible alignment
 on Darwin.}
 @end defun
@@ -187,39 +183,47 @@
 @node Basic Pointer Operations
 @chapter Basic Pointer Operations
 
-@defun pointerp ptr => boolean
-Return true if @code{ptr} is a foreign pointer.
+@defun pointerp ptr @result{} boolean
+Return true if @var{ptr} is a foreign pointer.
 @end defun
 
-@defun null-ptr => pointer
+@defun null-pointer @result{} pointer
 Return a null foreign pointer.
 @end defun
 
-@defun null-ptr-p ptr => boolean
-Return true if @code{ptr} is a null foreign pointer.
+@defun null-pointer-p ptr @result{} boolean
+Return true if @var{ptr} is a null foreign pointer.
+@end defun
+
+@defun make-pointer address @result{} pointer
+Return a pointer corresponding to the numeric integer @var{address}.
+@end defun
+
+@defun inc-pointer ptr offset @result{} pointer
+Return the result of numerically incrementing @var{ptr} by @var{offset}.
 @end defun
 
 
 @node Foreign Memory Allocation
 @chapter Foreign Memory Allocation
 
-@defun foreign-alloc size => pointer
-Allocate @code{size} bytes of foreign-addressable memory and return
-a @code{pointer} to the allocated block. An implementation-specific
+@defun foreign-alloc size @result{} pointer
+Allocate @var{size} bytes of foreign-addressable memory and return
+a @var{pointer} to the allocated block. An implementation-specific
 error is signalled if the memory cannot be allocated.
 @end defun
 
-@defun foreign-free ptr => unspecified
-Free a pointer @code{ptr} allocated by @code{foreign-alloc}. The
-results are undefined if @code{ptr} is used after being freed.
+@defun foreign-free ptr @result{} unspecified
+Free a pointer @var{ptr} allocated by @code{foreign-alloc}. The
+results are undefined if @var{ptr} is used after being freed.
 @end defun
 
-@defmac with-foreign-ptr (var size &optional size-var) &body body
-Bind @code{var} to a pointer to @code{size} bytes of
-foreign-accessible memory during @code{body}.  Both @code{ptr} and the
+@defmac with-foreign-pointer (var size &optional size-var) &body body
+Bind @var{var} to a pointer to @var{size} bytes of
+foreign-accessible memory during @var{body}.  Both @var{ptr} and the
 memory block it points to have dynamic extent and may be stack
-allocated if supported by the implementation. If @code{size-var} is
-supplied, it will be bound to @code{size} during @code{body}.
+allocated if supported by the implementation. If @var{size-var} is
+supplied, it will be bound to @var{size} during @var{body}.
 @end defmac
 
 
@@ -227,17 +231,17 @@
 @chapter Memory Access
 
 @deffn {Accessor} %mem-ref ptr type &optional offset
-Dereference a pointer @code{offset} bytes from @code{ptr} to an object
+Dereference a pointer @var{offset} bytes from @var{ptr} to an object
 for reading (or writing when used with @code{setf}) of built-in type
-@code{type}.
+@var{type}.
 @end deffn
 
-@subsubheading Example:
+@heading Example
 
 @lisp
-;; An impratical example, since 'time' returns the time as well,
-;; but it demonstrates %MEM-REF. Better (simple) examples wanted!
-(with-foreign-ptr (p (foreign-type-size :time))
+;; @r{An impractical example, since @code{time} returns the time as well,}
+;; @r{but it demonstrates @code{%mem-ref}. Better (simple) examples wanted!}
+(with-foreign-pointer (p (foreign-type-size :time))
   (foreign-funcall "time" :pointer p :time)
   (%mem-ref p :time))
 @end lisp
@@ -246,31 +250,34 @@
 @node Foreign Function Calling
 @chapter Foreign Function Calling
 
-@defmac %foreign-funcall name @{arg-type arg@}* &optional result-type => object
-Invoke a foreign function called @code{name}, which may be mangled
-depending on the ABI of the system (eg. adding leading underscore for
-Darwin).
-
-The remaining arguments are pairs of foreign types and their values,
-followed by the return type of the function, assumed to be
-@code{:void} if not supplied.
-
-@emph{This wording is pretty awkward, rewrite this description.}
+@defmac %foreign-funcall name @{arg-type arg@}* &optional result-type @result{} object
+@defmacx %foreign-funcall-pointer ptr @{arg-type arg@}* &optional result-type @result{} object
+Invoke a foreign function called @var{name} in the foreign source code.
+
+Each @var{arg-type} is a foreign type specifier, followed by
+@var{arg}, Lisp data to be converted to foreign data of type
+@var{arg-type}.  @var{result-type} is the foreign type of the
+function's return value, and is assumed to be @code{:void} if not
+supplied.
+
+@code{%foreign-funcall-pointer} takes a pointer @var{ptr} to the
+function, as returned by @code{foreign-symbol-pointer}, rather than a
+string @var{name}.
 @end defmac
 
-@subsubheading Examples:
+@heading Examples
 
 @lisp
-;; Calling a standard C library function:
-(%foreign-funcall "sqrtf" :float 16.0 :float) => 4.0
+;; @r{Calling a standard C library function:}
+(%foreign-funcall "sqrtf" :float 16.0 :float) @result{} 4.0
 @end lisp
 
 @lisp
-;; Dynamic allocation of a buffer and passing to a function:
+;; @r{Dynamic allocation of a buffer and passing to a function:}
 (with-foreign-ptr (buf 255 buf-size)
   (%foreign-funcall "gethostname" :pointer buf :size buf-size :int)
-  ;; Convert BUF to a Lisp string using MAKE-STRING and %MEM-REF or
-  ;; a portable CFFI function such as CFFI:LISP-STRING-FROM-FOREIGN.
+  ;; @r{Convert @var{buf} to a Lisp string using @code{make-string} and @code{%mem-ref} or}
+  ;; @r{a portable CFFI function such as @code{cffi:lisp-string-from-foreign}.}
 )
 @end lisp
 
@@ -278,15 +285,25 @@
 @node Loading Foreign Libraries
 @chapter Loading Foreign Libraries
 
-@defun %load-foreign-library name => unspecified
-Loads the foreign shared library @code{name}.
+@defun %load-foreign-library name @result{} unspecified
+Load the foreign shared library @var{name}.
 
-@emph{There is a lot of behavior to decide here.  Currently I lean
+@impnote{There is a lot of behavior to decide here.  Currently I lean
 toward not requiring NAME to be a full path to the library so
 we can search the system library directories (maybe even get
 LD_LIBRARY_PATH from the environment) as necessary.}
 @end defun
 
+
+@node Foreign Globals
+@chapter Foreign Globals
+
+@defun foreign-symbol-pointer name kind @result{} pointer
+Return a pointer to a foreign symbol @var{name}. @var{kind} is one of
+@code{:code} or @code{:data}, and is ignored on some platforms.
+@end defun
+
+
 @node Symbol Index
 @unnumbered Symbol Index
 @printindex fn
