* guile.texi: Commented out menu entry and inclusion of Tcl/Tk

stuff.

	* indices.texi: Users are advised to look under C and Scheme
	names, xref to transformation rules added.

	* intro.texi, scheme-modules.texi, scheme-ideas.texi,
	scheme-evaluation.texi, scheme-data.texi, scheme-procedures.texi:
	Fixed most REFFIXMEs.

	* srfi-modules.texi (About SRFI Usage): New node.
	(SRFI-0): Extended.
	Fixed all REFFIXMEs.

doc/ChangeLog

@@ -1,3 +1,19 @@
+2001-05-23  Martin Grabmueller  <mgrabmue@cs.tu-berlin.de>
+
+	* guile.texi: Commented out menu entry and inclusion of Tcl/Tk
+	stuff.
+
+	* indices.texi: Users are advised to look under C and Scheme
+	names, xref to transformation rules added.
+
+	* intro.texi, scheme-modules.texi, scheme-ideas.texi,
+	scheme-evaluation.texi, scheme-data.texi, scheme-procedures.texi:
+	Fixed most REFFIXMEs.
+
+	* srfi-modules.texi (About SRFI Usage): New node.
+	(SRFI-0): Extended.
+	Fixed all REFFIXMEs.
+
 2001-05-19  Neil Jerram  <neil@ossau.uklinux.net>
 
 	* posix.texi (Networking): Split existing material into new nodes

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.9 2001-05-14 21:37:51 mgrabmue Exp $
+@subtitle $Id: guile.texi,v 1.10 2001-05-23 17:24:49 mgrabmue Exp $
 @subtitle For use with Guile @value{VERSION}
 @include AUTHORS
 
@@ -177,7 +177,7 @@ Part III: Guile Modules
 	add-on, so maybe it shouldn't be documented here
 	(though it is nice to have a link from here to the
 	Guile-scsh manual, if one exists).
-* Tcl/Tk Interface::
+@c * Tcl/Tk Interface::
 
 Part IV: Guile Scripting
 
@@ -255,7 +255,7 @@ Indices
 @include repl-modules.texi
 @include expect.texi
 @include scsh.texi
-@include tcltk.texi
+@c @include tcltk.texi
 
 @c Guile as an scripting language
 @iftex

doc/indices.texi

@@ -1,22 +1,40 @@
 @node Concept Index
 @unnumbered Concept Index
+
+This index contains concepts, keywords and non-Schemey names for several
+features, to make it easier to locate the desired sections.
+
 @printindex cp
 
 
 @node Procedure Index
 @unnumbered Procedure Index
+
+@c FIXME::martin: Review me!
+
 This is an alphabetical list of all the procedures and macros in Guile.
-[[Remind people to look for functions under their Scheme names as well
+
-as their C names.]]
+When looking for a particular procedure, please look under its Scheme
+name as well as under its C name.  The C name can be constructed from
+the Scheme names by a simple transformation described in the section
+@xref{Transforming Scheme name to C name}.
+
 @printindex fn
 
 
 @node Variable Index
 @unnumbered Variable Index
+
+@c FIXME::martin: Review me!
+
 This is an alphabetical list of all the important variables and
 constants in Guile.
-[[Remind people to look for variables under their Scheme names as well
+
-as their C names.]]
+When looking for a particular variable or constant, please look under
+its Scheme name as well as under its C name.  The C name can be
+constructed from the Scheme names by a simple transformation described
+in the section @xref{Transforming Scheme name to C name}.
+
 @printindex vr
 
 
@@ -25,7 +43,9 @@ as their C names.]]
 @c spurious makeinfo errors.
 @node Type Index
 @unnumbered Type Index
+
 This is an alphabetical list of all the important data types defined in
 the Guile Programmers Manual.
+
 @printindex tp
 

doc/intro.texi

@@ -1,4 +1,4 @@
-@c $Id: intro.texi,v 1.9 2001-05-16 18:08:12 mgrabmue Exp $
+@c $Id: intro.texi,v 1.10 2001-05-23 17:24:49 mgrabmue Exp $
 
 @page
 @node What is Guile?
@@ -686,7 +686,7 @@ usual for your operating system, and it will additionally look into the
 directories listed in the @code{LTDL_LIBRRAY_PATH} environment variable.
 
 To see how these Guile extensions via shared libraries relate to the
-module system, see below REFFIXME.
+module system, see below @xref{Intro to Modules and Extensions}.
 
 @node Guile Modules
 @section Guile Modules

doc/scheme-data.texi

@@ -1614,9 +1614,10 @@ y
 @subsection String Comparison
 
 The procedures in this section are similar to the character ordering
-predicates (REFFIXME), but are defined on character sequences.  They all
+predicates (@pxref{Characters}), but are defined on character sequences.
-return @code{#t} on success and @code{#f} on failure.  The predicates
+They all return @code{#t} on success and @code{#f} on failure.  The
-ending in @code{-ci} ignore the character case when comparing strings.
+predicates ending in @code{-ci} ignore the character case when comparing
+strings.
 
 
 @rnindex string=?
@@ -2536,7 +2537,7 @@ one of the constructor procedures @code{make-variable} or
 @code{make-undefined-variable} or retrieved by @code{builtin-variable}.
 
 First-class variables are especially useful for interacting with the
-current module system (REFFIXME).
+current module system (@pxref{The Guile module system}).
 
 @deffn primitive builtin-variable name
 Return the built-in variable with the name @var{name}.
@@ -2967,7 +2968,7 @@ up a list.  An example will clear that up:
 
 This example also shows that lists have to be quoted (REFFIXME) when
 written, because they would otherwise be mistakingly taken as procedure
-applications (REFFIXME).
+applications (@pxref{Simple Invocation}).
 
 
 @node List Predicates
@@ -3028,7 +3029,7 @@ that modifying the elements of the new list also modyfies the elements
 of the old list.  On the other hand, applying procedures like
 @code{set-cdr!} or @code{delv!} to the new list will not alter the old
 list.  If you also need to copy the list elements (making a deep copy),
-use the procedure @code{copy-tree} (REFFIXME).
+use the procedure @code{copy-tree} (@pxref{Copying}).
 
 @node List Selection
 @subsection List Selection
@@ -4896,8 +4897,9 @@ elements of @var{vector}.
 
 @subsection Vector Modification
 
-A vector created by any of the vector constructor procedures (REFFIXME)
+A vector created by any of the vector constructor procedures
-documented above can be modified using the following procedures.
+(@pxref{Vectors}) documented above can be modified using the
+following procedures.
 
 According to R5RS, using any of these procedures on literally entered
 vectors is an error, because these vectors are considered to be

doc/scheme-evaluation.texi

@@ -72,10 +72,10 @@ another comment type for multiline comments, called @dfn{block
 comments}.  This type of comment begins with the character sequence
 @code{#!} and ends with the characters @code{!#}, which must appear on a
 line of their own.  These comments are compatible with the block
-comments in the Scheme Shell @file{scsh} (REFFIXME).  The characters
+comments in the Scheme Shell @file{scsh} (@pxref{The Scheme shell
-@code{#!} were chosen because they are the magic characters used in
+(scsh)}).  The characters @code{#!} were chosen because they are the
-shell scripts for indicating that the name of the program for executing
+magic characters used in shell scripts for indicating that the name of
-the script follows on the same line.
+the program for executing the script follows on the same line.
 
 Thus a Guile script often starts like this.
 
@@ -85,7 +85,7 @@ Thus a Guile script often starts like this.
 @end lisp
 
 More details on Guile scripting can be found in the scripting section
-(REFFIXME).
+(@pxref{Guile Scripting}).
 
 
 @node Case Sensitivity
@@ -105,7 +105,7 @@ are the same in R5RS Scheme, but are different in Guile.
 
 It is possible to turn off case sensitivity in Guile by setting the
 reader option @code{case-insensitive}.  More on reader options can be
-found at (REFFIXME).
+found at (@pxref{Reader options}).
 
 @lisp
 (read-enable 'case-insensitive)

doc/scheme-modules.texi

@@ -394,38 +394,38 @@ Mikael Djurfeldt's source-level debugging support for Guile
 Guile's support for multi threaded execution (@pxref{Scheduling}).
 
 @item (ice-9 rdelim)
-Line- and character-delimited input (REFFIXME).
+Line- and character-delimited input (@pxref{Line/Delimited}).
 
 @item (ice-9 documentation)
 Online documentation (REFFIXME).
 
 @item (srfi srfi-2)
-Support for @code{and-let*} (REFFIXME).
+Support for @code{and-let*} (@pxref{SRFI-2}).
 
 @item (srfi srfi-6)
-Support for some additional string port procedures (REFFIXME).
+Support for some additional string port procedures (@pxref{SRFI-6}).
 
 @item (srfi srfi-8)
-Multiple-value handling with @code{receive} (REFFIXME).
+Multiple-value handling with @code{receive} (@pxref{SRFI-8}).
 
 @item (srfi srfi-9)
-Record definition with @code{define-record-type} (REFFIXME).
+Record definition with @code{define-record-type} (@pxref{SRFI-9}).
 
 @item (srfi srfi-10)
-Read hash extension @code{#,()} (REFFIXME).
+Read hash extension @code{#,()} (@pxref{SRFI-10}).
 
 @item (srfi srfi-11)
 Multiple-value handling with @code{let-values} and @code{let-values*}
-(REFFIXME).
+(@pxref{SRFI-11}).
 
 @item (srfi srfi-13)
-String library (REFFIXME).
+String library (@pxref{SRFI-13}).
 
 @item (srfi srfi-14)
-Character-set library (REFFIXME).
+Character-set library (@pxref{SRFI-14}).
 
 @item (srfi srfi-17)
-Getter-with-setter support (REFFIXME).
+Getter-with-setter support (@pxref{SRFI-17}).
 
 @item (ice-9 slib)
 This module contains hooks for using Aubrey Jaffer's portable Scheme

doc/scheme-procedures.texi

@@ -1,779 +0,0 @@
-@page
-@node Procedures and Macros
-@chapter Procedures and Macros
-
-@menu
-* Lambda::                      Basic procedure creation using lambda.
-* Optional Arguments::          Handling keyword, optional and rest arguments.
-* Procedure Properties::        Procedure properties and metainformation.
-* Procedures with Setters::     Procedures with setters.
-* Macros::                      Lisp style macro definitions.
-* Syntax Rules::                Support for R5RS @code{syntax-rules}.
-* Syntax Case::                 Support for the @code{syntax-case} system.
-* Internal Macros::             Guile's internal representation.
-@end menu
-
-
-@node Lambda
-@section Lambda: Basic Procedure Creation
-
-@c FIXME::martin: Review me!
-
-A @code{lambda} expression evaluates to a procedure.  The environment
-which is in effect when a @code{lambda} expression is evaluated is
-enclosed in the newly created procedure, this is referred to as a
-@dfn{closure} (@pxref{About Closure}).
-
-When a procedure created by @code{lambda} is called with some actual
-arguments, the environment enclosed in the procedure is extended by
-binding the variables named in the formal argument list to new locations
-and storing the actual arguments into these locations.  Then the body of
-the @code{lambda} expression is evaluation sequentially.  The result of
-the last expression in the procedure body is then the result of the
-procedure invocation.
-
-The following examples will show how procedures can be created using
-@code{lambda}, and what you can do with these procedures.
-
-@lisp
-(lambda (x) (+ x x))       @result{} @r{a procedure}
-((lambda (x) (+ x x)) 4)   @result{} 8
-@end lisp
-
-The fact that the environment in effect when creating a procedure is
-enclosed in the procedure is shown with this example:
-
-@lisp
-(define add4
-  (let ((x 4))
-    (lambda (y) (+ x y))))
-(add4 6)                   @result{} 10
-@end lisp
-
-
-@deffn syntax lambda formals body
-@var{formals} should be a formal argument list as described in the
-following table.
-
-@table @code
-@item (@var{variable1} @dots{})
-The procedure takes a fixed number of arguments; when the procedure is
-called, the arguments will be stored into the newly created location for
-the formal variables.
-@item @var{variable}
-The procedure takes any number of arguments; when the procedure is
-called, the sequence of actual arguments will converted into a list and
-stored into the newly created location for the formal variable.
-@item (@var{variable1} @dots{} @var{variablen} . @var{variablen+1})
-If a space-delimited period precedes the last variable, then the
-procedure takes @var{n} or more variablesm where @var{n} is the number
-of formal arguments before the period.  There must be at least one
-argument before the period.  The first @var{n} actual arguments will be
-stored into the newly allocated locations for the first @var{n} formal
-arguments and the sequence of the remaining actual arguments is
-converted into a list and the stored into the location for the last
-formal argument.  If there are exactly @var{n} actual arguments, the
-empty list is stored into the location of the last formal argument.
-@end table
-
-@var{body} is a sequence of Scheme expressions which are evaluated in
-order when the procedure is invoked.
-@end deffn
-
-
-@node Optional Arguments
-@section Optional Arguments
-
-@c FIXME::martin: Review me!
-
-Scheme procedures, as defined in R5RS, can wither handle a fixed number
-of actual arguments, or a fixed number of actual arguments followed by
-arbitrarily many additional arguments.  Writing procedures of variable
-arity can be useful, but unfortunately, the syntactic means for handling
-argument lists of varying length is a bit inconvenient.  It is possible
-to give names to the fixed number of argument, but the remaining
-(optional) arguments can be only referenced as a list of values
-(@pxref{Lambda}).
-
-Guile comes with the module @code{(ice-9 optargs)}, which makes using
-optional arguments much more convenient.  In addition, this module
-provides syntax for handling keywords in argument lists
-(@pxref{Keywords}).
-
-Before using any of the procedures or macros defined in this section,
-you have to load the module @code{(ice-9 optargs)} with the statement:
-
-@lisp
-(use-modules (ice-9 optargs))
-@end lisp
-
-@menu
-* let-optional Reference::      Locally binding optional arguments.
-* let-keywords Reference::      Locally binding keywords arguments.
-* lambda* Reference::           Creating advanced argument handling procedures.
-* define* Reference::           Defining procedures and macros.
-@end menu
-
-
-@node let-optional Reference
-@subsection let-optional Reference
-
-@c FIXME::martin: Review me!
-
-The syntax @code{let-optional} and @code{let-optional*} are for
-destructuring rest argument lists and giving names to the various list
-elements.  @code{let-optional} binds all variables simultaneously, while
-@code{let-optional*} binds them sequentially, consistent with @code{let}
-and @code{let*} (REFFIXME).
-
-@deffn {libary syntax} let-optional rest-arg (binding @dots{}) expr @dots{}
-@deffnx {library syntax} let-optional* rest-arg (binding @dots{}) expr @dots{}
-These two macros give you an optional argument interface that is very
-@dfn{Schemey} and introduces no fancy syntax. They are compatible with
-the scsh macros of the same name, but are slightly extended. Each of
-@var{binding} may be of one of the forms @var{var} or @code{(@var{var}
-@var{default-value})}. @var{rest-arg} should be the rest-argument of the
-procedures these are used from.  The items in @var{rest-arg} are
-sequentially bound to the variable names are given. When @var{rest-arg}
-runs out, the remaining vars are bound either to the default values or
-left unbound if no default value was specified. @var{rest-arg} remains
-bound to whatever may have been left of @var{rest-arg}.
-
-After binding the variables, the expressions @var{expr} @dots{} are
-evaluated in order.
-@end deffn
-
-
-@node let-keywords Reference
-@subsection let-keywords Reference
-
-@c FIXME::martin: Review me!
-
-@code{let-keywords} and @code{let-keywords*} are used for extracting
-values from argument lists which use keywords instead of argument
-position for binding local variables to argument values.
-
-@code{let-keywords} binds all variables simultaneously, while
-@code{let-keywords*} binds them sequentially, consistent with @code{let}
-and @code{let*} (REFFIXME).
-
-@deffn {library syntax} let-keywords rest-arg allow-other-keys? (binding @dots{})  expr @dots{}
-@deffnx {library syntax} let-keywords rest-arg allow-other-keys? (binding @dots{})  expr @dots{}
-These macros pick out keyword arguments from @var{rest-arg}, but do not
-modify it.  This is consistent at least with Common Lisp, which
-duplicates keyword arguments in the rest argument. More explanation of what
-keyword arguments in a lambda list look like can be found below in
-the documentation for @code{lambda*}
- (@pxref{lambda* Reference}).  @var{binding}s can have the same form as
-for @code{let-optional}. If @var{allow-other-keys?} is false, an error
-will be thrown if anything that looks like a keyword argument but does
-not match a known keyword parameter will result in an error.
-
-After binding the variables, the expressions @var{expr} @dots{} are
-evaluated in order.
-@end deffn
-
-
-@node lambda* Reference
-@subsection lambda* Reference
-
-@c FIXME::martin: Review me!
-
-When using optional and keyword argument lists, using @code{lambda} for
-creating procedures and using @code{let-optional} or @code{let-keywords}
-is a bit lengthy.  Therefore, @code{lambda*} is provided, which combines
-the features of those macros into a single convenient syntax.
-
-For quick reference, here is the syntax of the formal argument list for
-@code{lambda*} (brackets are used to indicate grouping only):
-
-@example
-ext-param-list ::= [identifier]* [#:optional [ext-var-decl]+]?
-  [#:key [ext-var-decl]+ [#:allow-other-keys]?]?
-  [[#:rest identifier]|[. identifier]]?
-
-ext-var-decl ::= identifier | ( identifier expression )
-@end example
-
-The characters `*', `+' and `?' are not to be taken literally; they mean
-respectively, zero or more occurences, one or more occurences, and one
-or zero occurences.
-
-@deffn {library syntax} lambda* formals body
-@code{lambda*} creates a procedure that takes optional arguments. These
-are specified by putting them inside brackets at the end of the
-paramater list, but before any dotted rest argument. For example,
-
-@lisp
-(lambda* (a b #:optional c d . e) '())
-@end lisp
-
-creates a procedure with fixed arguments @var{a} and @var{b}, optional
-arguments @var{c} and @var{d}, and rest argument @var{e}. If the
-optional arguments are omitted in a call, the variables for them are
-unbound in the procedure. This can be checked with the @code{bound?}
-macro (documented below).
-
-@code{lambda*} can also take keyword arguments. For example, a procedure
-defined like this:
-
-@lisp
-(lambda* (#:key xyzzy larch) '())
-@end lisp
-
-can be called with any of the argument lists @code{(#:xyzzy 11)}
-@code{(#:larch 13)} @code{(#:larch 42 #:xyzzy 19)} @code{()}. Whichever
-arguments are given as keywords are bound to values.
-
-Optional and keyword arguments can also be given default values
-which they take on when they are not present in a call, by giving a
-two-item list in place of an optional argument, for example in:
-
-@lisp
-(lambda* (foo #:optional (bar 42) #:key (baz 73))
-     (list foo bar baz))
-@end lisp
-
-@var{foo} is a fixed argument, @var{bar} is an optional argument with
-default value 42, and baz is a keyword argument with default value 73.
-Default value expressions are not evaluated unless they are needed and
-until the procedure is called.
-
-@code{lambda*} also supports two more special parameter list keywords.
-
-@code{lambda*}-defined procedures now throw an error by default if a
-keyword other than one of those specified is found in the actual
-passed arguments. However, specifying @code{#:allow-other-keys}
-immediately after the keyword argument declarations restores the
-previous behavior of ignoring unknown keywords.  @code{lambda*} also now
-guarantees that if the same keyword is passed more than once, the
-last one passed is the one that takes effect. For example,
-
-@lisp
-((lambda* (#:key (heads 0) (tails 0)) (display (list heads tails)))
-    #:heads 37 #:tails 42 #:heads 99)
-@end lisp
-
-would result in (99 47) being displayed.
-
-@code{#:rest} is also now provided as a synonym for the dotted syntax
-rest argument. The argument lists @code{(a . b)} and @code{(a #:rest b)}
-are equivalent in all respects to @code{lambda*}. This is provided for
-more similarity to DSSSL, MIT-Scheme and Kawa among others, as well as
-for refugees from other Lisp dialects.
-@end deffn
-
-@deffn {library syntax} bound? variable
-Check if a variable is bound in the current environment.
-
-The procedure @code{defined?} doesn't quite cut it as it stands, since
-it only checks bindings in the top-level environment, not those in local
-scope only.
-@end deffn
-
-
-@node define* Reference
-@subsection define* Reference
-
-@c FIXME::martin: Review me!
-
-Just like @code{define} has a shorthand notation for defining procedures
-(@pxref{Lambda Alternatives}), @code{define*} is provided as an
-abbreviation of the combination of @code{define} and @code{lambda*}.
-
-@code{define*-public} is the @code{lambda*} version of
-@code{define-public}; @code{defmacro*} and @code{defmacro*-public} exist
-for defining macros with the improved argument list handling
-possibilities.  The @code{-public} versions not only define the
-procedures/macros, but also export them from the current module.
-
-@deffn {library syntax} define* formals body
-@deffnx {library syntax} define*-public formals body
-@code{define*} and @code{define*-public} support optional arguments with
-a similar syntax to @code{lambda*}. They also support arbitrary-depth
-currying, just like Guile's define. Some examples:
-
-@lisp
-(define* (x y #:optional a (z 3) #:key w . u)
-   (display (list y z u)))
-@end lisp
-defines a procedure @code{x} with a fixed argument @var{y}, an optional
-agument @var{a}, another optional argument @var{z} with default value 3,
-a keyword argument @var{w}, and a rest argument @var{u}.
-
-@lisp
-(define-public* ((foo #:optional bar) #:optional baz) '())
-@end lisp
-
-This illustrates currying. A procedure @code{foo} is defined, which,
-when called with an optional argument @var{bar}, returns a procedure
-that takes an optional argument @var{baz}.
-
-Of course, @code{define*[-public]} also supports @code{#:rest} and
-@code{#:allow-other-keys} in the same way as @code{lambda*}.
-@end deffn
-
-@deffn {library syntax} defmacro* name formals body
-@deffnx {library syntax} defmacro*-public name formals body
-These are just like @code{defmacro} and @code{defmacro-public} except that they
-take @code{lambda*}-style extended paramter lists, where @code{#:optional},
-@code{#:key}, @code{#:allow-other-keys} and @code{#:rest} are allowed with the usual
-semantics. Here is an example of a macro with an optional argument:
-
-@lisp
-(defmacro* transmorgify (a #:optional b)
-    (a 1))
-@end lisp
-@end deffn
-
-
-@node Procedure Properties
-@section Procedure Properties and Metainformation
-
-@c FIXME::martin: Review me!
-
-Procedures always have attached the environment in which they were
-created and information about how to apply them to actual arguments.  In
-addition to that, properties and metainformation can be stored with
-procedures.  The procedures in this section can be used to test whether
-a given procedure satisfies a condition; and to access and set a
-procedure's property.
-
-The first group of procedures are predicates to test whether a Scheme
-object is a procedure, or a special procedure, respectively.
-@code{procedure?} is the most general predicates, it returns @code{#t}
-for any kind of procedure.  @code{closure?} does not return @code{#t}
-for primitive procedures, and @code{thunk?} only returns @code{#t} for
-procedures which do not accept any arguments.
-@c FIXME::martin: thunk? returns true for `id'.  What's wrong here?
-
-@rnindex procedure?
-@deffn primitive procedure? obj
-Return @code{#t} if @var{obj} is a procedure.
-@end deffn
-
-@deffn primitive closure? obj
-Return @code{#t} if @var{obj} is a closure.
-@end deffn
-
-@deffn primitive thunk? obj
-Return @code{#t} if @var{obj} is a thunk.
-@end deffn
-
-@c FIXME::martin: Is that true?
-@cindex procedure properties
-Procedure properties are general properties to be attached to
-procedures.  These can be the name of a procedure or other relevant
-information, such as debug hints.
-
-@deffn primitive procedure-properties proc
-Return @var{obj}'s property list.
-@end deffn
-
-@deffn primitive procedure-property p k
-Return the property of @var{obj} with name @var{key}.
-@end deffn
-
-@deffn primitive set-procedure-properties! proc new_val
-Set @var{obj}'s property list to @var{alist}.
-@end deffn
-
-@deffn primitive set-procedure-property! p k v
-In @var{obj}'s property list, set the property named @var{key} to
-@var{value}.
-@end deffn
-
-@cindex procedure documentation
-Documentation for a procedure can be accessed with the procedure
-@code{procedure-documentation}.
-
-@deffn primitive procedure-documentation proc
-Return the documentation string associated with @code{proc}.  By
-convention, if a procedure contains more than one expression and the
-first expression is a string constant, that string is assumed to contain
-documentation for that procedure.
-@end deffn
-
-@cindex source properties
-@c FIXME::martin: Is the following true?
-Source properties are properties which are related to the source code of
-a procedure, such as the line and column numbers, the file name etc.
-
-@deffn primitive set-source-properties! obj plist
-Install the association list @var{plist} as the source property
-list for @var{obj}.
-@end deffn
-
-@deffn primitive set-source-property! obj key datum
-Set the source property of object @var{obj}, which is specified by
-@var{key} to @var{datum}.  Normally, the key will be a symbol.
-@end deffn
-
-@deffn primitive source-properties obj
-Return the source property association list of @var{obj}.
-@end deffn
-
-
-@deffn primitive source-property obj key
-Return the source property specified by @var{key} from
-@var{obj}'s source property list.
-@end deffn
-
-
-@node Procedures with Setters
-@section Procedures with Setters
-
-@c FIXME::martin: Review me!
-
-@c FIXME::martin: Document `operator struct'.
-
-@cindex procedure with setter
-@cindex setter
-A @dfn{procedure with setter} is a special kind of procedure which
-normally behaves like any accesor procedure, that is a procedure which
-accesses a data structure.  The difference is that this kind of
-procedure has a so-called @dfn{setter} attached, which is a procedure
-for storing something into a data structure.
-
-Procedures with setters are treated specially when the procedure appears
-in the special form @code{set!} (REFFIXME).  How it works is best shown
-by example.
-
-Suppose we have a procedure called @code{foo-ref}, which accepts two
-arguments, a value of type @code{foo} and an integer.  The procedure
-returns the value stored at the given index in the @code{foo} object.
-Let @code{f} be a variable containing such a @code{foo} data
-structure.@footnote{Working definitions would be:
-@lisp
-(define foo-ref vector-ref)
-(define foo-set! vector-set!)
-(define f (make-vector 2 #f))
-@end lisp
-}
-
-@lisp
-(foo-ref f 0)       @result{} bar
-(foo-ref f 1)       @result{} braz
-@end lisp
-
-Also suppose that a corresponding setter procedure called
-@code{foo-set!} does exist.
-
-@lisp
-(foo-set! f 0 'bla)
-(foo-ref f 0)       @result{} bla
-@end lisp
-
-Now we could create a new procedure called @code{foo}, which is a
-procedure with setter, by calling @code{make-procedure-with-setter} with
-the accessor and setter procedures @code{foo-ref} and @code{foo-set!}.
-Let us call this new procedure @code{foo}.
-
-@lisp
-(define foo (make-procedure-with-setter foo-ref foo-set!))
-@end lisp
-
-@code{foo} can from now an be used to either read from the data
-structure stored in @code{f}, or to write into the structure.
-
-@lisp
-(set! (foo f 0) 'dum)
-(foo f 0)          @result{} dum
-@end lisp
-
-@deffn primitive make-procedure-with-setter procedure setter
-Create a new procedure which behaves like @var{procedure}, but
-with the associated setter @var{setter}.
-@end deffn
-
-@deffn primitive procedure-with-setter? obj
-Return @code{#t} if @var{obj} is a procedure with an
-associated setter procedure.
-@end deffn
-
-@deffn primitive procedure proc
-Return the procedure of @var{proc}, which must be either a
-procedure with setter, or an operator struct.
-@end deffn
-
-@deffn primitive setter proc
-Return the setter of @var{proc}, which must be either a procedure with
-setter or an operator struct.
-@end deffn
-
-
-@node Macros
-@section Lisp Style Macro Definitions
-
-@cindex macros
-@cindex transformation
-Macros are objects which cause the expression that they appear in to be
-transformed in some way @emph{before} being evaluated.  In expressions
-that are intended for macro transformation, the identifier that names
-the relevant macro must appear as the first element, like this:
-
-@lisp
-(@var{macro-name} @var{macro-args} @dots{})
-@end lisp
-
-In Lisp-like languages, the traditional way to define macros is very
-similar to procedure definitions.  The key differences are that the
-macro definition body should return a list that describes the
-transformed expression, and that the definition is marked as a macro
-definition (rather than a procedure definition) by the use of a
-different definition keyword: in Lisp, @code{defmacro} rather than
-@code{defun}, and in Scheme, @code{define-macro} rather than
-@code{define}.
-
-@fnindex defmacro
-@fnindex define-macro
-Guile supports this style of macro definition using both @code{defmacro}
-and @code{define-macro}.  The only difference between them is how the
-macro name and arguments are grouped together in the definition:
-
-@lisp
-(defmacro @var{name} (@var{args} @dots{}) @var{body} @dots{})
-@end lisp
-
-@noindent
-is the same as
-
-@lisp
-(define-macro (@var{name} @var{args} @dots{}) @var{body} @dots{})
-@end lisp
-
-@noindent
-The difference is analogous to the corresponding difference between
-Lisp's @code{defun} and Scheme's @code{define}.
-
-@code{false-if-exception}, from the @file{boot-9.scm} file in the Guile
-distribution, is a good example of macro definition using
-@code{defmacro}:
-
-@lisp
-(defmacro false-if-exception (expr)
-  `(catch #t
-          (lambda () ,expr)
-          (lambda args #f)))
-@end lisp
-
-@noindent
-The effect of this definition is that expressions beginning with the
-identifier @code{false-if-exception} are automatically transformed into
-a @code{catch} expression following the macro definition specification.
-For example:
-
-@lisp
-(false-if-exception (open-input-file "may-not-exist"))
-@equiv{}
-(catch #t
-       (lambda () (open-input-file "may-not-exist"))
-       (lambda args #f))
-@end lisp
-
-
-@node Syntax Rules
-@section The R5RS @code{syntax-rules} System
-
-R5RS defines an alternative system for macro and syntax transformations
-using the keywords @code{define-syntax}, @code{let-syntax},
-@code{letrec-syntax} and @code{syntax-rules}.
-
-The main difference between the R5RS system and the traditional macros
-of the previous section is how the transformation is specified.  In
-R5RS, rather than permitting a macro definition to return an arbitrary
-expression, the transformation is specified in a pattern language that
-
-@itemize @bullet
-@item
-does not require complicated quoting and extraction of components of the
-source expression using @code{caddr} etc.
-
-@item
-is designed such that the bindings associated with identifiers in the
-transformed expression are well defined, and such that it is impossible
-for the transformed expression to construct new identifiers.
-@end itemize
-
-@noindent
-The last point is commonly referred to as being @dfn{hygienic}: the R5RS
-@code{syntax-case} system provides @dfn{hygienic macros}.
-
-For example, the R5RS pattern language for the @code{false-if-exception}
-example of the previous section looks like this:
-
-@lisp
-(syntax-rules ()
-  ((_ expr)
-   (catch #t
-          (lambda () expr)
-          (lambda args #f))))
-@end lisp
-
-In Guile, the @code{syntax-rules} system is provided by the @code{(ice-9
-syncase)} module.  To make these facilities available in your code,
-include the expression @code{(use-modules (ice-9 syncase))} or
-@code{(use-syntax (ice-9 syncase))} (@pxref{Using Guile Modules})
-before the first usage of @code{define-syntax} etc.  If you are writing
-a Scheme module, you can alternatively use one of the keywords
-@code{#:use-module} and @code{#:use-syntax} in your @code{define-module}
-declaration (@pxref{Creating Guile Modules}).
-
-@menu
-* Pattern Language::            The @code{syntax-rules} pattern language.
-* Define-Syntax::               Top level syntax definitions.
-* Let-Syntax::                  Local syntax definitions.
-@end menu
-
-
-@node Pattern Language
-@subsection The @code{syntax-rules} Pattern Language
-
-
-@node Define-Syntax
-@subsection Top Level Syntax Definitions
-
-define-syntax:  The gist is
-
-  (define-syntax <keyword> <transformer-spec>)
-
-makes the <keyword> into a macro so that
-
-  (<keyword> ...)
-
-expands at _compile_ or _read_ time (i.e. before any
-evaluation begins) into some expression that is
-given by the <transformer-spec>.
-
-
-@node Let-Syntax
-@subsection Local Syntax Definitions
-
-
-@node Syntax Case
-@section Support for the @code{syntax-case} System
-
-
-
-@node Internal Macros
-@section Internal Representation of Macros and Syntax
-
-Internally, Guile uses three different flavours of macros.  The three
-flavours are called @dfn{acro} (or @dfn{syntax}), @dfn{macro} and
-@dfn{mmacro}.
-
-Given the expression
-
-@lisp
-(foo @dots{})
-@end lisp
-
-@noindent
-with @code{foo} being some flavour of macro, one of the following things
-will happen when the expression is evaluated.
-
-@itemize @bullet
-@item
-When @code{foo} has been defined to be an @dfn{acro}, the procedure used
-in the acro definition of @code{foo} is passed the whole expression and
-the current lexical environment, and whatever that procedure returns is
-the value of evaluating the expression.  You can think of this a
-procedure that receives its argument as an unevaluated expression.
-
-@item
-When @code{foo} has been defined to be a @dfn{macro}, the procedure used
-in the macro definition of @code{foo} is passed the whole expression and
-the current lexical environment, and whatever that procedure returns is
-evaluated again.  That is, the procedure should return a valid Scheme
-expression.
-
-@item
-When @code{foo} has been defined to be a @dfn{mmacro}, the procedure
-used in the mmacro definition of `foo' is passed the whole expression
-and the current lexical environment, and whatever that procedure returns
-replaces the original expression.  Evaluation then starts over from the
-new expression that has just been returned.
-@end itemize
-
-The key difference between a @dfn{macro} and a @dfn{mmacro} is that the
-expression returned by a @dfn{mmacro} procedure is remembered (or
-@dfn{memoized}) so that the expansion does not need to be done again
-next time the containing code is evaluated.
-
-The primitives @code{procedure->syntax}, @code{procedure->macro} and
-@code{procedure->memoizing-macro} are used to construct acros, macros
-and mmacros respectively.  However, if you do not have a very special
-reason to use one of these primitives, you should avoid them: they are
-very specific to Guile's current implementation and therefore likely to
-change.  Use @code{defmacro}, @code{define-macro} (@pxref{Macros}) or
-@code{define-syntax} (@pxref{Syntax Rules}) instead.  (In low level
-terms, @code{defmacro}, @code{define-macro} and @code{define-syntax} are
-all implemented as mmacros.)
-
-@deffn primitive procedure->syntax code
-Return a macro which, when a symbol defined to this value appears as the
-first symbol in an expression, returns the result of applying @var{code}
-to the expression and the environment.
-@end deffn
-
-@deffn primitive procedure->macro code
-Return a macro which, when a symbol defined to this value appears as the
-first symbol in an expression, evaluates the result of applying
-@var{code} to the expression and the environment.  For example:
-
-@lisp
-(define trace
-  (procedure->macro
-    (lambda (x env)
-      `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))
-
-(trace @i{foo})
-@equiv{}
-(set! @i{foo} (tracef @i{foo} '@i{foo})).
-@end lisp
-@end deffn
-
-@deffn primitive procedure->memoizing-macro code
-Return a macro which, when a symbol defined to this value appears as the
-first symbol in an expression, evaluates the result of applying
-@var{code} to the expression and the environment.
-@code{procedure->memoizing-macro} is the same as
-@code{procedure->macro}, except that the expression returned by
-@var{code} replaces the original macro expression in the memoized form
-of the containing code.
-@end deffn
-
-In the following primitives, @dfn{acro} flavour macros are referred to
-as @dfn{syntax transformers}.
-
-@deffn primitive macro? obj
-Return @code{#t} if @var{obj} is a regular macro, a memoizing macro or a
-syntax transformer.
-@end deffn
-
-@deffn primitive macro-type m
-Return one of the symbols @code{syntax}, @code{macro} or
-@code{macro!}, depending on whether @var{m} is a syntax
-transformer, a regular macro, or a memoizing macro,
-respectively.  If @var{m} is not a macro, @code{#f} is
-returned.
-@end deffn
-
-@deffn primitive macro-name m
-Return the name of the macro @var{m}.
-@end deffn
-
-@deffn primitive macro-transformer m
-Return the transformer of the macro @var{m}.
-@end deffn
-
-@deffn primitive cons-source xorig x y
-Create and return a new pair whose car and cdr are @var{x} and @var{y}.
-Any source properties associated with @var{xorig} are also associated
-with the new pair.
-@end deffn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:

doc/srfi-modules.texi

@@ -1,6 +1,6 @@
 @page
 @node SRFI Support
-@chapter Various SRFI Support Modules
+@chapter SRFI Support Modules
 
 SRFI is an acronym for Scheme Request For Implementation.  The SRFI
 documents define a lot of syntactic and procedure extensions to standard
@@ -13,6 +13,7 @@ get the relevant SRFI documents from the SRFI home page
 @url{http://srfi.schemers.org}.
 
 @menu
+* About SRFI Usage::            What to know about Guile's SRFI support.
 * SRFI-0::                      cond-expand
 * SRFI-2::                      and-let*.
 * SRFI-6::                      Basic String Ports.
@@ -27,6 +28,40 @@ get the relevant SRFI documents from the SRFI home page
 @end menu
 
 
+@node About SRFI Usage
+@section About SRFI Usage
+
+@c FIXME::martin: Review me!
+
+SRFI support in Guile is currently implemented partly in the core
+library, and partly as add-on modules.  That means that some SRFIs are
+automatically available when the interpreter is started, whereas the
+other SRFIs require you to use the appropriate support module
+explicitly.  
+
+There are several reasons for this inconsistency.  First, the feature
+checking syntactic form @code{cond-expand} (@pxref{SRFI-0}) must be
+available immediately, because it must be there when the user wants to
+check for the Scheme implementation, that is, before she can know that
+it is safe to use @code{use-modules} to load SRFI support modules.  The
+second reason is that some features defined in SRFIs had been
+implemented in Guile before the developers started to add SRFI
+implementations as modules (for example SRFI-6 (@pxref{SRFI-6})).  In
+the future, it is possible that SRFIs in the core library might be
+factored out into separate modules, requiring explicit module loading
+when they are needed.  So you should be prepared to have to use
+@code{use-modules} someday in the future to access SRFI-6 bindings.  If
+you want, you can do that already.  We have included the module
+@code{(srfi srfi-6)} in the distribution, which currently does nothing,
+but ensures that you can write future-safe code.
+
+Generally, support for a specific SRFI is made available by using
+modules named @code{(srfi srfi-@var{number})}, where @var{number} is the
+number of the SRFI needed.  Another possibility is to use the command
+line option @code{--use-srfi}, which will load the necessary modules
+automatically (@pxref{Invoking Guile}).
+
+
 @node SRFI-0
 @section SRFI-0 - cond-expand
 
@@ -78,6 +113,8 @@ If the feature requirement is the keyword @code{else} and it is the last
 clause, it is satisfied if no prior clause matched.
 @end itemize
 
+If no clause is satisfied, an error is signalled.
+
 Since @code{cond-expand} is needed to tell what a Scheme implementation
 provides, it must be accessible without using any
 implementation-dependant operations, such as @code{use-modules} in
@@ -85,11 +122,13 @@ Guile.  Thus, it is not necessary to use any module to get access to
 this form.
 
 Currently, the feature identifiers @code{guile}, @code{r5rs} and
-@code{srfi-0} are supported.  The other SRFIs are not in that list,
+@code{srfi-0} are supported.  The other SRFIs are not in that list by
-because the SRFI modules must be explicitly used before their exported
+default, because the SRFI modules must be explicitly used before their
-bindings can be used.  So if a Scheme program wishes to detect whether
+exported bindings can be used.  
-SRFI-8 is supported in the running implementation, code similar to this
+
-may be needed:
+So if a Scheme program wishes to use SRFI-8, it has two possibilities:
+First, it can check whether the running Scheme implementation is Guile,
+and if it is, it can use the appropriate module:
 
 @lisp
 (cond-expand
@@ -100,6 +139,23 @@ may be needed:
   ;; otherwise fail.
 @end lisp
 
+The other possibility is to use the @code{--use-srfi} command line
+option when invoking Guile (@pxref{Invoking Guile}).  When you do that,
+the specified SRFI support modules will be loaded and add their feature
+identifier to the list of symbols checked by @code{cond-expand}.
+
+So, if you invoke Guile like this:
+
+@example
+$ guile --use-srfi=8
+@end example
+
+the following snippet will expand to @code{'hooray}.
+
+@lisp
+(cond-expand (srfi-8 'hooray))
+@end lisp
+
 
 @node SRFI-2
 @section SRFI-2 - and-let*
@@ -154,7 +210,7 @@ procedures easier.  It is documented in @xref{Multiple Values}.
 
 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
+procedures (@pxref{Records}).  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.
@@ -242,8 +298,8 @@ read in.  The result of @var{proc} is returned by the Scheme reader.
 
 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
+@code{let} and @code{let*} (@pxref{Local Bindings}), but they support
-values returned by multiple-valued expressions.
+binding of the values returned by multiple-valued expressions.
 
 Write @code{(use-modules (srfi srfi-11))} to make the bindings
 available.
@@ -272,7 +328,8 @@ In this section, we will describe all procedures defined in SRFI-13
 Note that only the procedures from SRFI-13 are documented here which are
 not already contained in Guile.  For procedures not documented here
 please refer to the relevant chapters in the Guile Reference Manual, for
-example the documentation of strings and string procedures (REFFIXME).
+example the documentation of strings and string procedures
+(@pxref{Strings}).
 
 All of the procedures defined in SRFI-13, which are not already included
 in the Guile core library, are implemented in the module @code{(srfi
@@ -387,7 +444,8 @@ produce the corresponding string element.  The order in which
 The procedure @code{string->list} is extended by SRFI-13, that is why it
 is included in @code{(srfi srfi-13)}.  The other procedures are new.
 The Guile core already contains the procedure @code{list->string} for
-converting a list of characters into a string (REFFIXME).
+converting a list of characters into a string (@pxref{List/String
+Conversion}).
 
 @deffn primitive string->list str [start end]
 Convert the string @var{str} into a list of characters.
@@ -436,7 +494,8 @@ These procedures are called @dfn{selectors}, because they access
 information about the string or select pieces of a given string.
 
 Additional selector procedures are documented in the Strings section
-(REFFIXME), like @code{string-length} or @code{string-ref}.
+(@pxref{String Selection}), like @code{string-length} or
+@code{string-ref}.
 
 @code{string-copy} is also available in core Guile, but this version
 accepts additional start/end indices.
@@ -512,7 +571,8 @@ trimmed.
 The procedure @code{string-fill!} is extended from R5RS because it
 accepts optional start/end indices.  This bindings shadows the procedure
 of the same name in the Guile core.  The second modification procedure
-@code{string-set!} is documented in the Strings section (REFFIXME).
+@code{string-set!} is documented in the Strings section (@pxref{String
+Modification}).
 
 @deffn primitive string-fill! str chr [start end]
 Stores @var{chr} in every element of the given @var{str} and
@@ -943,9 +1003,10 @@ guile>
 @node SRFI-14 Character Set Data Type
 @subsection Character Set Data Type
 
-The data type @dfn{charset} implements sets of characters (REFFIXME).
+The data type @dfn{charset} implements sets of characters
-Because the internal representation of character sets is not visible to
+(@pxref{Characters}).  Because the internal representation of character
-the user, a lot of procedures for handling them are provided.
+sets is not visible to the user, a lot of procedures for handling them
+are provided.
 
 Character sets can be created, extended, tested for the membership of a
 characters and be compared to other character sets.
@@ -1327,8 +1388,8 @@ EBNF grammar.
 The value returned by a @code{case-lambda} form is a procedure which
 matches the number of actual arguments against the formals in the
 various clauses, in order.  @dfn{Formals} means a formal argument list
-just like with @code{lambda} (REFFIXME). The first matching clause is
+just like with @code{lambda} (@pxref{Lambda}). The first matching clause
-selected, the corresponding values from the actual parameter list are
+is selected, the corresponding values from the actual parameter list are
 bound to the variable names in the clauses and the body of the clause is
 evaluated.  If no clause matches, an error is signalled.
 
@@ -1382,3 +1443,4 @@ the setter of a procedure.  In fact, @code{(set!  (setter @var{proc})
 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.
+