* srfi-13-14.texi: Added @bullet to various @itemize lists.

* srfi-modules.texi (SRFI Support): New file and chapter.

	* Makefile.am (guile_TEXINFOS): Added repl-modules.texi and
	srfi-modules.texi.

	* guile.texi (Top): New menu entries for the new chapters.
	(Top): @includes for the new chapters.
	(Top): New menu entry for `SRFI Support', @include for
	`srfi-modules.texi'.

	* repl-modules.texi: New file.
	(Readline Support): New chapter for (ice-9 readline).
	(Value History): New chapter for (ice-9 history).

doc/ChangeLog

@@ -1,3 +1,21 @@
+2001-05-02  Martin Grabmueller  <mgrabmue@cs.tu-berlin.de>
+
+	* srfi-13-14.texi: Added @bullet to various @itemize lists.
+
+	* srfi-modules.texi (SRFI Support): New file and chapter.
+
+	* Makefile.am (guile_TEXINFOS): Added repl-modules.texi and
+	srfi-modules.texi.
+
+	* guile.texi (Top): New menu entries for the new chapters.
+	(Top): @includes for the new chapters.
+	(Top): New menu entry for `SRFI Support', @include for
+	`srfi-modules.texi'.
+
+	* repl-modules.texi: New file.
+	(Readline Support): New chapter for (ice-9 readline).
+	(Value History): New chapter for (ice-9 history).
+
 2001-05-02  Martin Grabmueller  <mgrabmue@cs.tu-berlin.de>
 
 	* scheme-modules.texi (Dynamic Libraries): Renamed from `Dynamic

doc/Makefile.am

@@ -35,7 +35,8 @@ guile_TEXINFOS = preface.texi intro.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 \
 	appendices.texi indices.texi script-getopt.texi data-rep.texi \
-	extend.texi srfi-13-14.texi AUTHORS
+	extend.texi srfi-13-14.texi repl-modules.texi srfi-modules.texi \
+	AUTHORS
 
 guile_tut_TEXINFOS = guile-tut.texi AUTHORS
 

doc/guile.texi

@@ -80,7 +80,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-04-28 23:38:52 ossau Exp $
+@subtitle $Id: guile.texi,v 1.8 2001-05-02 21:50:15 mgrabmue Exp $
 @subtitle For use with Guile @value{VERSION}
 @include AUTHORS
 
@@ -168,7 +168,10 @@ Part III: Guile Modules
 
 * SLIB::                        Using the SLIB Scheme library.
 * POSIX::                       POSIX system calls and networking.
+* SRFI Support::                Support for various SRFIs.
 * SRFI-13/14::                  String library and character set library.
+* Readline Support::            Module for using the readline library.
+* Value History::               Maintaining a value history in the REPL.
 * Expect::			Controlling interactive programs with Guile.
 * The Scheme shell (scsh)::
 	The SCSH compatibility module has been made an
@@ -249,7 +252,9 @@ Indices
 
 @include slib.texi
 @include posix.texi
+@include srfi-modules.texi
 @include srfi-13-14.texi
+@include repl-modules.texi
 @include expect.texi
 @include scsh.texi
 @include tcltk.texi

doc/repl-modules.texi

@@ -0,0 +1,79 @@
+@node Readline Support
+@chapter Readline Support
+
+@c FIXME::martin: Review me!
+
+@cindex readline
+@cindex command line history
+Guile comes with an interface module to the readline library.  This
+makes interactive use much more convenient, because of the command--line
+editing features of readline.  Using @code{(ice-9 readline)}, you can
+navigate through the current input line with the cursor keys, retrieve
+older command lines from the input history and even search through the
+history entries.
+
+The module is not loaded by default and so has to be loaded and
+activated explicitly.  This is done with two simple lines of code:
+
+@lisp
+(use-modules (ice-9 readline))
+(activate-readline)
+@end lisp
+
+The first line will load the necessary code, and the second will
+activate readline's features for the REPL.  If you plan to use this
+module often, you should save these to lines to your @file{.guile}
+personal startup file.
+
+You will notice that the REPL's behaviour changes a bit when you have
+loaded the readline module.  For examle, when you press Enter before
+typing in the closing parentheses of a list, you will see the
+@dfn{continuation} prompt, three dots: @code{...}  This gives you a nice
+visual feedback when trying to match parentheses.  To make this even
+easier, @dfn{bouncing parentheses} are implemented.  That means that
+when you type in a closing parentheses, the cursor will jump to the
+corresponding opening paren for a short time, making it trivial to make
+them match.
+
+Once the readline module is activated, all lines entered interactively
+will be stored in a history and can be recalled later using the
+cursor-up and -down keys.  Readline also understands the Emacs keys for
+navigating through the command line and history.
+
+When you quit your Guile session by evaluating @code{(quit)} or pressing
+Ctrl-D, the history will be saved to the file @file{.guile_history} and
+read in when you start Guile for the next time.  Thus you can start a
+new Guile session and still have the (probably long--winded) definition
+expressions available.
+
+
+@node Value History
+@chapter Value History
+
+@c FIXME::martin: Review me!
+
+@cindex value history
+Another module which makes command line usage more convenient is
+@code{(ice-9 history)}.  This module will change the REPL so that each
+value which is evaluated and printed will be remembered under a name
+constructed from the dollar character (@code{$}) and the number of the
+evaluated expression.
+
+Consider an example session.
+
+@example
+guile> (use-modules (ice-9 history))
+guile> 1
+$1 = 1
+guile> (+ $1 $1)
+$2 = 2
+guile> (* $2 $2)
+$3 = 4
+@end example
+
+After loading the value history module @code{(ice-9 history)}, one
+(trivial) expression is evaluated.  The result is stored into the
+variable @code{$1}.  This fact is indicated by the output @code{$1 = },
+which is also caused by @code{(ice-9 history)}.  In the next line, this
+variable is used two times, to produce the value @code{$2}, which in
+turn is used in the calculation for @code{$3}.

doc/srfi-modules.texi

@@ -0,0 +1,183 @@
+@node SRFI Support
+@chapter Various SRFI Support Modules
+
+In addition to the string and character--set libraries --- documented in
+the next chapter --- Guile has support for a number of SRFIs.  This
+chapter gives an overview over the available SRFIs and some usage hints.
+For complete documentation, we advise you to get the relevant SRFI
+documents from the SRFI home page @url{http://srfi.schemers.org}.
+
+@menu
+* SRFI-2::                      and-let*.
+* SRFI-6::                      Basic String Ports.
+* SRFI-8::                      receive.
+* SRFI-9::                      define-record-type.
+* SRFI-10::                     Hash--Comma Reader Extension.
+* SRFI-11::                     let-values and let-values*.
+* SRFI-17::                     Generalized set!
+@end menu
+
+
+@node SRFI-2
+@section SRFI-2 -- and-let*
+
+The syntactic form @code{and-let*} combines the conditional evaluation
+form @code{and} with the binding form @var{let*}.  Each argument
+expression will be evaluated sequentially, bound to a variable (if a
+variable name is given), but only as long as no expression returns
+the false value @code{#f}.
+
+Use @code{(use-modules (srfi srfi-2)} to access this syntax form.
+
+
+@node SRFI-6
+@section SRFI-6 -- Basic String Ports
+
+SRFI-6 defines the procedures @code{open-input-string},
+@code{open-output-string} and @code{get-output-string}.  These
+procedures are included in the Guile core, so using this module does not
+make any difference at the moment.  But it is possible that support for
+SRFI-6 will be factored out of the core library in the future, so using
+this module does not hurt, after all.
+
+@node SRFI-8
+@section SRFI-8 -- receive
+
+@code{receive} is a syntax for making the handling of multiple--value
+procedures easier.  It is documented in @xref{Multiple Values}.
+
+
+@node SRFI-9
+@section SRFI-9 -- define-record-type
+
+This is the SRFI way for defining record types.  The Guile
+implementation is a layer above Guile's normal record construction
+procedures (REFFIXME).  The nice thing about this kind of record
+definition method is that no new names are implicitly created, all
+constructor, accessor and predicates are explicitly given.  This reduces
+the risk of variable capture.
+
+The syntax of a record type definition is:
+
+@example
+<record type definition>
+  -> (define-record-type <type name>
+       (<constructor name> <field tag> ...)
+       <predicate name>
+       <field spec> ...)
+<field spec> -> (<field tag> <accessor name>)
+             -> (<field tag> <accessor name> <modifier name>)
+<field tag>  -> <identifier>
+<... name>   -> <identifier>
+@end example
+
+Usage example:
+
+@example
+guile> (use-modules (srfi srfi-9))
+guile> (define-record-type :foo (make-foo x) foo? 
+                           (x get-x) (y get-y set-y!))
+guile> (define f (make-foo 1))
+guile> f
+#<:foo x: 1 y: #f>
+guile> (get-x f)
+1
+guile> (set-y! f 2)
+2
+guile> (get-y f)
+2
+guile> f
+#<:foo x: 1 y: 2>
+guile> (foo? f)
+#t
+guile> (foo? 1)
+#f
+@end example
+
+
+@node SRFI-10
+@section SRFI-10 -- Hash--Comma Reader Extension
+
+@cindex hash--comma
+@cindex #,()
+The module @code{(srfi srfi-10)} implements the syntax extension
+@code{#,()}, also called hash-comma, which is defined in SRFI-10.
+
+The support for SRFI-10 consists of the procedure
+@code{define-reader-ctor} for defining new reader constructors and the
+read syntax form
+
+@example
+#,(@var{ctor} @var{datum} ...)
+@end example
+
+where @var{ctor} must be a symbol for which a read constructor was
+defined previouly, using @code{define-reader-ctor}.
+
+Example:
+
+@lisp
+(define-reader-ctor 'file open-input-file)
+(define f '#,(file "/etc/passwd"))
+(read-line f)
+@result{}
+"root:x:0:0:root:/root:/bin/bash"
+@end lisp
+
+Please note the quote before the @code{#,(file ...)} expression.  This
+is necessary because ports are not self-evaluating in Guile.
+
+@deffn procedure define-reader-ctor symbol proc
+Define @var{proc} as the reader constructor for hash--comma forms with a
+tag @var{symbol}.  @var{proc} will be applied to the datum(s) following
+the tag in the hash--comma expression after the complete form has been
+read in.  The result of @var{proc} is returned by the Scheme reader.
+@end deffn
+
+
+@node SRFI-11
+@section SRFI-11 -- let-values
+
+This module implements the binding forms for multiple values
+@code{let-values} and @code{let-values*}.  These forms are similar to
+@code{let} and @code{let*} (REFFIXME), but they support binding of the
+values returned by multiple--valued expressions.
+
+Write @code{(use-modules (srfi srfi-11))} to make the bindings
+available.
+
+@lisp
+(let-values (((x y) (values 1 2))
+             ((z f) (values 3 4)))
+   (+ x y z f))
+@result{}
+10
+@end lisp
+
+@code{let-values} performs all bindings simultaneously, which means that
+no expression in the binding clauses may refer to variables bound in the
+same clause list.  @code{let-values*}, on the other hand, performs the
+bindings sequentially, just like @code{let*} does for single--valued
+expressions.
+
+
+@node SRFI-17
+@section SRFI-17 -- Generalized set!
+
+This is an implementation of SRFI-17: Generalized set!
+
+It exports the Guile procedure @code{make-procedure-with-setter} under
+the SRFI name @code{getter-with-setter} and exports the standard
+procedures @code{car}, @code{cdr}, @dots{}, @code{cdddr},
+@code{string-ref} and @code{vector-ref} as procedures with setters, as
+required by the SRFI.
+
+SRFI-17 was heavily criticized during its discussion period but it was
+finalized anyway.  One issue was its concept of globally associating
+setter @dfn{properties} with (procedure) values, which is non-Schemy.
+For this reason, this implementation chooses not to provide a way to set
+the setter of a procedure.  In fact, @code{(set!  (setter @var{proc})
+@var{setter})} signals an error.  The only way to attach a setter to a
+procedure is to create a new object (a @dfn{procedure with setter}) via
+the @code{getter-with-setter} procedure. This procedure is also
+specified in the SRFI.  Using it avoids the described problems.