* Various small manual improvements.

doc/ref/ChangeLog

@@ -1,3 +1,16 @@
+2001-12-07  Neil Jerram  <neil@ossau.uklinux.net>
+
+	* scm.texi (Guile API): Renamed from `Scheme Primitives' and
+	broadened so that this chapter discusses the Guile API as a whole.
+
+	* program.texi (Available Functionality): Revise so that text
+	reads better.
+
+	* guile.texi (Programming Intro): New introductory text.
+
+	* scheme-ideas.texi (Definition): Reorder reference bullets in
+	ascending page number order.
+
 2001-12-04  Martin Grabmueller  <mg@glug.org>
 
 	* scheme-procedures.texi (Optional Arguments): Typo fix: wither ->

doc/ref/guile.texi

@@ -94,7 +94,7 @@ by the Free Software Foundation.
 @sp 10
 @comment The title is printed in a large font.
 @title Guile Reference Manual
-@subtitle $Id: guile.texi,v 1.8 2001-12-01 21:48:30 ossau Exp $
+@subtitle $Id: guile.texi,v 1.9 2001-12-07 17:08:19 ossau Exp $
 @subtitle For use with Guile @value{VERSION}
 
 @c AUTHORS
@@ -216,7 +216,7 @@ Part II: Programming with Guile
 * Guile Scripting::             How to write Guile scripts.
 * Command Line Handling::       Command line options and arguments.
 * Libguile Intro::              Using Guile as an extension language.
-* Scheme Primitives::           Writing Scheme primitives in C.
+* Guile API::                   Overview of the Guile API.
 * Data Representation::         Data representation in Guile.
 * GH::                          The deprecated GH interface.
 * Debugger User Interface::
@@ -285,7 +285,7 @@ guidelines and tips for @emph{how} to program in Guile, and to document
 the tools that are available to help you with your programming.  For
 detailed reference information on the variables, functions etc. that
 make up Guile's application programming interface (API), please refer to
-Part III (@pxref{Reference Intro,,Part III: Programming with Guile}).
+Part III (@pxref{Reference Intro,,Part III --- Guile API Reference}).
 
 We begin in the first chapter of this part by looking at the programming
 options available.
@@ -306,6 +306,11 @@ options available.
 @node Reference Intro
 @unnumbered Part III: Guile API Reference
 
+Guile provides an application programming interface (@dfn{API}) to
+developers in two core languages: Scheme and C.  This part of the manual
+contains reference documentation for all of the functionality that is
+available through both Scheme and C interfaces.
+
 @include scheme-data.texi
 @include scheme-compound.texi
 @include scheme-procedures.texi

doc/ref/intro.texi

@@ -1,4 +1,4 @@
-@c $Id: intro.texi,v 1.4 2001-11-16 15:04:16 ossau Exp $
+@c $Id: intro.texi,v 1.5 2001-12-07 17:08:19 ossau Exp $
 
 
 @page
@@ -352,7 +352,7 @@ with Guile on a typical POSIX system.
 
 Parts III and IV of this manual describe the C functions Guile provides.
 Furthermore, any Scheme function described in this manual as a
-``Primitive'' is also callable from C; see @ref{Scheme Primitives}.
+``Primitive'' is also callable from C; see @ref{Primitives}.
 
 The header file @code{<libguile.h>} provides declarations for all of
 Guile's functions and constants.  You should @code{#include} it at the

doc/ref/program.texi

@@ -83,24 +83,18 @@ is growing quickly and already includes such useful examples as
 Scheme, and @code{(database postgres)}, which provides SQL access to a
 Postgres database.
 
-In practice, therefore, it is quite feasible that your application can
+Given the growing collection of pre-existing modules, it is quite
-be implemented by combining together a selection of pre-existing modules
+feasible that your application could be implemented by combining a
-with new application code written in Scheme, and approach may
+selection of these modules together with new application code written in
-suffice for the application that you want to write.
+Scheme.
 
-If it does not suffice, because the functionality that your application
+If this approach is not enough, because the functionality that your
-needs is not already available in this form (and assuming that it's
+application needs is not already available in this form, or because it
-impossible or unacceptable for performance reasons to write the new
+is impossible or unacceptable (e.g. for performance reasons) to write
-functionality in Scheme), you will need to write some C code.
+the new functionality in Scheme, you will need to write some C code.  If
-
+the required function is already available in C (e.g. in a library), all
-@itemize @bullet
+you need is a little glue to connect it to the world of Guile.  If not,
-@item
+you need both to write the basic code and to plumb it into Guile.
-If the required function is already written (e.g. in a library), you
-only need a little glue to connect it to the world of Guile.
-
-@item
-If not, you need to write the basic code as well.
-@end itemize
 
 In either case, two general considerations are important.  Firstly, what
 is the interface by which the functionality is presented to the Scheme

doc/ref/scheme-ideas.texi

@@ -177,12 +177,6 @@ about those missing pieces immediately by jumping ahead to the following
 references.
 
 @itemize @bullet
-@item
-@xref{Internal Definitions}, to read about using @code{define} other
-than at top level in a Scheme program, including a discussion of when it
-works to use @code{define} rather than @code{set!} to change the value
-of an existing variable.
-
 @item
 @ref{Lambda Alternatives}, to read about an alternative form of the
 @code{define} syntax that can be used when defining new procedures.
@@ -191,6 +185,12 @@ of an existing variable.
 @ref{Procedures with Setters}, to read about an alternative form of the
 @code{set!} syntax that helps with changing a single value in the depths
 of a compound data structure.)
+
+@item
+@xref{Internal Definitions}, to read about using @code{define} other
+than at top level in a Scheme program, including a discussion of when it
+works to use @code{define} rather than @code{set!} to change the value
+of an existing variable.
 @end itemize
 
 
@@ -384,7 +384,7 @@ this:
 @end lisp
 
 @noindent
-This is a valid procedure invocation expression, whose result is the
+This is a valid procedure invocation expression, and its result is the
 string @code{"Name=FSF:Address=Cambridge"}.
 
 It it more common, though, to store the procedure value in a variable ---
@@ -756,9 +756,9 @@ answers yes.
 
 If the outermost @code{(if @dots{})} expression here was a procedure
 invocation expression, the expression @code{(delete-file file)}, whose
-effect is to actually delete a file, would already have been executed
+side effect is to actually delete a file, would already have been
-before the @code{if} procedure even got invoked!  Clearly this is no use
+evaluated before the @code{if} procedure even got invoked!  Clearly this
---- the whole point of an @code{if} expression is that the
+is no use --- the whole point of an @code{if} expression is that the
 @dfn{consequent} expression is only evaluated if the condition of the
 @code{if} expression is ``true''.
 
@@ -815,21 +815,14 @@ expressions, simply so that you will recognize common special syntax
 when you see it.  For a full description of each of these syntaxes,
 follow the appropriate reference.
 
-@code{if} and @code{cond} (@pxref{if cond case}) provide conditional
-evaluation of argument expressions depending on whether one or more
-conditions evaluate to ``true'' or ``false''.
-
-@code{case} (@pxref{if cond case}) provides conditional evaluation of
-argument expressions depending on whether a variable has one of a
-specified group of values.
-
-@code{define} (REFFIXME) is used to create a new variable and set its
-initial value.
-
-@code{set!} (REFFIXME) is used to modify an existing variable's value.
-
 @code{lambda} (@pxref{Lambda}) is used to construct procedure objects.
 
+@code{define} (@pxref{Top Level}) is used to create a new variable and
+set its initial value.
+
+@code{set!} (@pxref{Top Level}) is used to modify an existing variable's
+value.
+
 @code{let}, @code{let*} and @code{letrec} (@pxref{Local Bindings})
 create an inner lexical environment for the evaluation of a sequence of
 expressions, in which a specified set of local variables is bound to the
@@ -842,6 +835,14 @@ same as a procedure which returns its last argument, because the
 evaluation of a procedure invocation expression does not guarantee to
 evaluate the arguments in order.
 
+@code{if} and @code{cond} (@pxref{if cond case}) provide conditional
+evaluation of argument expressions depending on whether one or more
+conditions evaluate to ``true'' or ``false''.
+
+@code{case} (@pxref{if cond case}) provides conditional evaluation of
+argument expressions depending on whether a variable has one of a
+specified group of values.
+
 @code{and} (@pxref{and or}) executes a sequence of expressions in order
 until either there are no expressions left, or one of them evaluates to
 ``false''.
@@ -1312,12 +1313,12 @@ It can only be accessed indirectly via @code{get-balance} or
 -25
 @end lisp
 
-A detail here is that the @code{get-balance} and @code{deposit}
+An important detail here is that the @code{get-balance} and
-variables must be set up by @code{define}ing them at top level and then
+@code{deposit} variables must be set up by @code{define}ing them at top
-@code{set!}ing their values inside the @code{let} body.  Using
+level and then @code{set!}ing their values inside the @code{let} body.
-@code{define} within the @code{let} body would not work: this would
+Using @code{define} within the @code{let} body would not work: this
-create variable bindings within the local @code{let} environment that
+would create variable bindings within the local @code{let} environment
-would not be accessible at top level.
+that would not be accessible at top level.
 
 
 @node Callback Closure

doc/ref/scm.texi

@@ -1,8 +1,58 @@
 @page
-@node Scheme Primitives
+@node Guile API
+@chapter Overview of the Guile API
+
+Guile's application programming interface (@dfn{API}) makes
+functionality available that an application developer can use in either
+C or Scheme programming.  The interface consists of @dfn{elements} that
+may be macros, functions or variables in C, and procedures, variables,
+syntax or other types of object in Scheme.  Broadly speaking, the
+interface as a whole can be divided into three groups.
+
+@enumerate
+@item
+Elements that are available equivalently as C functions or Scheme
+procedures.
+
+@item
+Elements that are only available as macros, functions or variables for C
+programming.
+
+@item
+Elements that are only available as procedures or other objects in
+Scheme.
+@end enumerate
+
+Functions/procedures in the first group are often known as
+@dfn{primitives}, @dfn{subrs} or @dfn{builtins}.  An example is the
+@code{assq} Scheme procedure, which is also available as @code{scm_assq}
+in C.
+
+Elements in the second and third groups exist because they provide
+additional language-specific benefits in either Scheme or C.  Examples
+are the C macro @code{SCM_CONSP}, which is faster and more convenient in
+C programming than the primitive @code{scm_pair_p}, and the
+procedure-with-setter @code{make-object-property}, which provides a
+more convenient property handling interface in Scheme than the
+primitives on which it is based.
+
+@menu
+* Primitives::                  Identical function for Scheme and C.
+* C Only::                      Elements only available in C.
+* Scheme Only::                 Elements only available in Scheme.
+@end menu
+
+
+@node Primitives
+@section Identical Function in both Scheme and C
+
+They form the majority of the API, and allow both C and Scheme
+programmers to perform identical operations.
+
+@c @node Scheme Primitives
 @c @chapter Writing Scheme primitives in C
 @c - according to the menu in guile.texi - NJ 2001/1/26
-@chapter Relationship between Scheme and C functions
+@c @chapter Relationship between Scheme and C functions
 
 @c Chapter contents contributed by Thien-Thi Nguyen <ttn@gnu.org>.
 
@@ -19,8 +69,9 @@ the convention for passing non-required arguments to this function.
 @c * Exceptions to the regularity::
 @end menu
 
+
 @node Transforming Scheme name to C name
-@section Transforming Scheme name to C name
+@subsection Transforming Scheme name to C name
 
 Normally, the name of a C function can be derived given its Scheme name,
 using some simple textual transformations:
@@ -93,11 +144,23 @@ Prefix arg non-nil means use \"gh_\" prefix, otherwise use \"scm_\" prefix."
   (insert (if use-gh "gh_" "scm_") name))
 @end example
 
+
 @node Structuring argument lists for C functions
-@section Structuring argument lists for C functions
+@subsection Structuring argument lists for C functions
 
 The C function's arguments will be all of the Scheme procedure's
 argumements, both required and optional; if the Scheme procedure takes a
 ``rest'' argument, that will be a final argument to the C function.  The
 C function's arguments, as well as its return type, will be @code{SCM}.
 
+
+@node C Only
+@section Elements Available Only in C
+
+For C this is usually a matter of better performance (e.g. the
+@code{SCM_CONSP} macro) or of accepting C language types rather than the
+generic @code{SCM}.
+
+
+@node Scheme Only
+@section Elements Available Only in Scheme