* Split the Data Types chapter into two; plus a few other smaller changes.

doc/ref/ChangeLog

@@ -1,5 +1,9 @@
 2001-12-01  Neil Jerram  <neil@ossau.uklinux.net>
 
+	* scheme-data.texi (Hooks): Moved into scheme-utility.texi.
+
+	* Makefile.am (guile_TEXINFOS): Added scheme-compound.texi.
+
 	* scheme-data.texi (Variables): Node moved to modules chapter.
 	(Symbol Read Syntax): New node, with syntax-related material taken
 	from old Symbols node.
@@ -8,6 +12,10 @@
 	(Symbol Props): Renamed from `Symbol Tables'.
 	(Symbols): General review, improvements and additional material
 	throughout this section.
+	(Other Data Types): New material: links to object types documented
+	elsewhere.  Also renamed node to `Other Types'.
+	(Data Types): Split into two: `Simple Data Types' and `Compound
+	Data Types'.  Introductory blurbs rewritten accordingly.
 
 	* guile.texi: Updated Notes comment.
 

doc/ref/Makefile.am

@@ -32,7 +32,8 @@ guile_TEXINFOS = preface.texi intro.texi program.texi scheme-intro.texi \
 	scheme-reading.texi scheme-indices.texi slib.texi posix.texi \
 	expect.texi scsh.texi tcltk.texi scripts.texi gh.texi scm.texi \
 	debugging.texi indices.texi script-getopt.texi data-rep.texi \
-	extend.texi repl-modules.texi srfi-modules.texi misc-modules.texi
+	extend.texi repl-modules.texi srfi-modules.texi misc-modules.texi \
+	scheme-compound.texi
 
 ETAGS_ARGS = $(info_TEXINFOS) $(guile_TEXINFOS)
 

doc/ref/debugging.texi

@@ -105,11 +105,13 @@ Since the tail call is effectively optimized to a @code{goto} statement,
 there is no need for Guile to create a new stack frame for each
 iteration.  Using @code{trace} here helps us see why this is so.
  
+
 @node Backtrace
-@appendixsec Backtrace
+@section Backtrace
+
 
 @node Stacks and Frames
-@appendixsec Stacks and Frames
+@section Stacks and Frames
 
 When a running program is interrupted, usually upon reaching an error or
 breakpoint, its state is represented by a @dfn{stack} of suspended

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.7 2001-12-01 15:53:04 ossau Exp $
+@subtitle $Id: guile.texi,v 1.8 2001-12-01 21:48:30 ossau Exp $
 @subtitle For use with Guile @value{VERSION}
 
 @c AUTHORS
@@ -225,7 +225,8 @@ Part II: Programming with Guile
 Part III: Guile API Reference
 
 * Reference Intro::             Introduction to the Guile API reference.
-* Data Types::                  Data types for generic use.
+* Simple Data Types::           Numbers, strings, booleans and so on.
+* Compound Data Types::         Data types for holding other data.
 * Procedures and Macros::       Procedures and macros.
 * Utility Functions::           General utility functions.
 * Binding Constructs::          Definitions and variable bindings.
@@ -306,6 +307,7 @@ options available.
 @unnumbered Part III: Guile API Reference
 
 @include scheme-data.texi
+@include scheme-compound.texi
 @include scheme-procedures.texi
 @include scheme-utility.texi
 @include scheme-binding.texi

doc/ref/scheme-utility.texi

@@ -6,15 +6,16 @@
 
 This chapter contains information about procedures which are not cleanly
 tied to a specific data type.  Because of their wide range of
-applications, they are collected in a @dfn{utlity} chapter.
+applications, they are collected in a @dfn{utility} chapter.
 
 @menu
 * Equality::                    When are two values `the same'?
 * Property Lists::              Managing metainformation about Scheme objects.
-* Primitive Properties::        A modern low-level interface to object properties.
+* Primitive Properties::        A modern interface to object properties.
 * Sorting::                     Sort utility procedures.
 * Copying::                     Copying deep structures.
 * General Conversion::          Converting objects to strings.
+* Hooks::                       User-customizable event lists.
 @end menu
 
 
@@ -308,6 +309,148 @@ argument @var{printer} (default: @code{write}).
 @end deffn
 
 
+@node Hooks
+@section Hooks
+@tpindex Hooks
+
+@c FIXME::martin: Review me!
+
+A hook is basically a list of procedures to be called at well defined
+points in time.  Hooks are used internally for several debugging
+facilities, but they can be used in user code, too.
+
+Hooks are created with @code{make-hook}, then procedures can be added to
+a hook with @code{add-hook!} or removed with @code{remove-hook!} or
+@code{reset-hook!}.  The procedures stored in a hook can be invoked with
+@code{run-hook}.
+
+@menu
+* Hook Examples::               Hook usage by example.
+* Hook Reference::              Reference of all hook procedures.
+@end menu
+
+@node Hook Examples
+@subsection Hook Examples
+
+Hook usage is shown by some examples in this section.  First, we will
+define a hook of arity 2 --- that is, the procedures stored in the hook
+will have to accept two arguments.
+
+@lisp
+(define hook (make-hook 2))
+hook
+@result{} #<hook 2 40286c90>
+@end lisp
+
+Now we are ready to add some procedures to the newly created hook with
+@code{add-hook!}.  In the following example, two procedures are added,
+which print different messages and do different things with their
+arguments.  When the procedures have been added, we can invoke them
+using @code{run-hook}.
+
+@lisp
+(add-hook! hook (lambda (x y) 
+                    (display "Foo: ") 
+                    (display (+ x y)) 
+                    (newline)))
+(add-hook! hook (lambda (x y) 
+                    (display "Bar: ") 
+                    (display (* x y)) 
+                    (newline)))
+(run-hook hook 3 4)
+@print{} Bar: 12
+@print{} Foo: 7
+@end lisp
+
+Note that the procedures are called in reverse order than they were
+added.  This can be changed by providing the optional third argument
+on the second call to @code{add-hook!}.
+
+@lisp
+(add-hook! hook (lambda (x y) 
+                    (display "Foo: ") 
+                    (display (+ x y)) 
+                    (newline)))
+(add-hook! hook (lambda (x y) 
+                    (display "Bar: ") 
+                    (display (* x y)) 
+                    (newline)) 
+                    #t)   ; @r{<- Change here!}
+(run-hook hook 3 4)
+@print{} Foo: 7
+@print{} Bar: 12
+@end lisp
+
+@node Hook Reference
+@subsection Hook Reference
+
+When a hook is created with @code{make-hook}, you can supply the arity
+of the procedures which can be added to the hook.  The arity defaults to
+zero.  All procedures of a hook must have the same arity, and when the
+procedures are invoked using @code{run-hook}, the number of arguments
+must match the arity of the procedures.
+
+The order in which procedures are added to a hook matters.  If the third
+parameter to @var{add-hook!} is omitted or is equal to @code{#f}, the
+procedure is added in front of the procedures which might already be on
+that hook, otherwise the procedure is added at the end.  The procedures
+are always called from first to last when they are invoked via
+@code{run-hook}.
+
+When calling @code{hook->list}, the procedures in the resulting list are
+in the same order as they would have been called by @code{run-hook}.
+
+@deffn {Scheme Procedure} make-hook [n_args]
+@deffnx {C Function} scm_make_hook (n_args)
+Create a hook for storing procedure of arity @var{n_args}.
+@var{n_args} defaults to zero.  The returned value is a hook
+object to be used with the other hook procedures.
+@end deffn
+
+@deffn {Scheme Procedure} hook? x
+@deffnx {C Function} scm_hook_p (x)
+Return @code{#t} if @var{x} is a hook, @code{#f} otherwise.
+@end deffn
+
+@deffn {Scheme Procedure} hook-empty? hook
+@deffnx {C Function} scm_hook_empty_p (hook)
+Return @code{#t} if @var{hook} is an empty hook, @code{#f}
+otherwise.
+@end deffn
+
+@deffn {Scheme Procedure} add-hook! hook proc [append_p]
+@deffnx {C Function} scm_add_hook_x (hook, proc, append_p)
+Add the procedure @var{proc} to the hook @var{hook}. The
+procedure is added to the end if @var{append_p} is true,
+otherwise it is added to the front.  The return value of this
+procedure is not specified.
+@end deffn
+
+@deffn {Scheme Procedure} remove-hook! hook proc
+@deffnx {C Function} scm_remove_hook_x (hook, proc)
+Remove the procedure @var{proc} from the hook @var{hook}.  The
+return value of this procedure is not specified.
+@end deffn
+
+@deffn {Scheme Procedure} reset-hook! hook
+@deffnx {C Function} scm_reset_hook_x (hook)
+Remove all procedures from the hook @var{hook}.  The return
+value of this procedure is not specified.
+@end deffn
+
+@deffn {Scheme Procedure} run-hook hook . args
+@deffnx {C Function} scm_run_hook (hook, args)
+Apply all procedures from the hook @var{hook} to the arguments
+@var{args}.  The order of the procedure application is first to
+last.  The return value of this procedure is not specified.
+@end deffn
+
+@deffn {Scheme Procedure} hook->list hook
+@deffnx {C Function} scm_hook_to_list (hook)
+Convert the procedure list of @var{hook} to a list.
+@end deffn
+
+
 @c Local Variables:
 @c TeX-master: "guile.texi"
 @c End: