Various manual updates, including syncing with stable branch.

doc/ref/ChangeLog

@@ -1,3 +1,14 @@
+2002-03-27  Neil Jerram  <neil@ossau.uklinux.net>
+
+	* scheme-compound.texi (List Searching): Remove docs for
+	`scm_sloppy_mem*', which no longer exist.
+
+2002-03-24  Neil Jerram  <neil@ossau.uklinux.net>
+
+	* guile.texi (Top), intro.texi (What is Guile?, The Basic Guile
+	Package): Use @ifnottex instead of @ifinfo, so that HTML
+	generation works correctly.
+
 2002-03-24  Marius Vollmer  <mvo@zagadka.ping.de>
 
 	* tools.texi: Updated to reflect changes to the guile-snarf tool.

doc/ref/guile.texi

@@ -121,7 +121,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.15 2002-03-16 13:51:03 ossau Exp $
+@subtitle $Id: guile.texi,v 1.16 2002-03-27 21:55:31 ossau Exp $
 @subtitle For use with Guile @value{VERSION}
 
 @c AUTHORS
@@ -208,7 +208,7 @@ by Free Software Foundation.
 @c Where to find Guile examples.
 @set example-dir doc/examples
 
-@ifinfo
+@ifnottex
 @node Top, Guile License, (dir), (dir)
 @top The Guile Reference Manual
 
@@ -218,7 +218,7 @@ and interesting ways.
 
 This Info file contains edition @value{MANUAL_EDITION} of the reference
 manual, corresponding to Guile version @value{VERSION}.
-@end ifinfo
+@end ifnottex
 
 @menu
 Preface

doc/ref/intro.texi

@@ -8,9 +8,9 @@ described in the
 @tex
 Revised$^5$
 @end tex
-@ifinfo
+@ifnottex
 Revised^5
-@end ifinfo
+@end ifnottex
 Report on the Algorithmic Language Scheme (usually known as R5RS),
 providing clean and general data and control structures.  Guile goes
 beyond the rather austere language presented in R5RS, extending it with
@@ -899,9 +899,9 @@ known as R5RS, or the
 @iftex
 ``Revised$^5$ Report on the Algorithmic Language Scheme'',
 @end iftex
-@ifinfo
+@ifnottex
 ``Revised^5 Report on the Algorithmic Language Scheme'',
-@end ifinfo
+@end ifnottex
 we have included the report in the Guile distribution;
 @xref{Top, , Introduction, r5rs, Revised(5) Report on the Algorithmic
 Language Scheme}.

doc/ref/scheme-compound.texi

@@ -27,8 +27,6 @@ values can be looked up within them.
 @section Pairs
 @tpindex Pairs
 
-@c FIXME::martin: Review me!
-
 Pairs are used to combine two Scheme objects into one compound object.
 Hence the name: A pair stores a pair of objects.
 
@@ -133,8 +131,6 @@ by @code{set-cdr!} is unspecified.
 @section Lists
 @tpindex Lists
 
-@c FIXME::martin: Review me!
-
 A very important data type in Scheme---as well as in all other Lisp
 dialects---is the data type @dfn{list}.@footnote{Strictly speaking,
 Scheme does not have a real datatype @dfn{list}.  Lists are made up of
@@ -173,8 +169,6 @@ or a pair which has a list in its cdr.
 @node List Syntax
 @subsection List Read Syntax
 
-@c FIXME::martin: Review me!
-
 The syntax for lists is an opening parentheses, then all the elements of
 the list (separated by whitespace) and finally a closing
 parentheses.@footnote{Note that there is no separation character between
@@ -208,8 +202,6 @@ applications (@pxref{Simple Invocation}).
 @node List Predicates
 @subsection List Predicates
 
-@c FIXME::martin: Review me!
-
 Often it is useful to test whether a given Scheme object is a list or
 not.  List-processing procedures could use this information to test
 whether their input is valid, or they could do different things
@@ -279,8 +271,6 @@ use the procedure @code{copy-tree} (@pxref{Copying}).
 @node List Selection
 @subsection List Selection
 
-@c FIXME::martin: Review me!
-
 These procedures are used to get some information about a list, or to
 retrieve one or more elements of a list.
 
@@ -323,8 +313,6 @@ return it.
 @node Append/Reverse
 @subsection Append and Reverse
 
-@c FIXME::martin: Review me!
-
 @code{append} and @code{append!} are used to concatenate two or more
 lists in order to form a new list.  @code{reverse} and @code{reverse!}
 return lists with the same elements as their arguments, but in reverse
@@ -463,8 +451,6 @@ Like @code{delete!}, but only deletes the first occurrence of
 @node List Searching
 @subsection List Searching
 
-@c FIXME::martin: Review me!
-
 The following procedures search lists for particular elements.  They use
 different comparison predicates for comparing list elements with the
 object to be searched.  When they fail, they return @code{#f}, otherwise
@@ -504,33 +490,10 @@ the non-empty lists returned by @code{(list-tail @var{lst}
 empty list) is returned.
 @end deffn
 
-[FIXME: Is there any reason to have the `sloppy' functions available at
-high level at all?  Maybe these docs should be relegated to a "Guile
-Internals" node or something. -twp]
-
-@deffn {Scheme Procedure} sloppy-memq x lst
-This procedure behaves like @code{memq}, but does no type or error checking.
-Its use is recommended only in writing Guile internals,
-not for high-level Scheme programs.
-@end deffn
-
-@deffn {Scheme Procedure} sloppy-memv x lst
-This procedure behaves like @code{memv}, but does no type or error checking.
-Its use is recommended only in writing Guile internals,
-not for high-level Scheme programs.
-@end deffn
-
-@deffn {Scheme Procedure} sloppy-member x lst
-This procedure behaves like @code{member}, but does no type or error checking.
-Its use is recommended only in writing Guile internals,
-not for high-level Scheme programs.
-@end deffn
 
 @node List Mapping
 @subsection List Mapping
 
-@c FIXME::martin: Review me!
-
 List processing is very convenient in Scheme because the process of
 iterating over the elements of a list can be highly abstracted.  The
 procedures in this section are the most basic iterating procedures for
@@ -893,7 +856,7 @@ The field holds a Scheme value and is GC protected.  When a structure is
 created with this type of field, the field is initialized to refer to
 the structure's own handle.  This kind of field is mainly useful when
 mixing Scheme and C code in which the C code may need to compute a
-structure's handle given only the address of its malloc-ed data.
+structure's handle given only the address of its malloc'd data.
 @end itemize
 
 
@@ -1713,19 +1676,19 @@ because association lists are so useful, Guile also provides specific
 procedures for manipulating them.
 
 @menu
-* Alist Key Equality::          
+* Alist Key Equality::
-* Adding or Setting Alist Entries::  
+* Adding or Setting Alist Entries::
-* Retrieving Alist Entries::    
+* Retrieving Alist Entries::
-* Removing Alist Entries::      
+* Removing Alist Entries::
-* Sloppy Alist Functions::      
+* Sloppy Alist Functions::
-* Alist Example::               
+* Alist Example::
 @end menu
 
 @node Alist Key Equality
 @subsubsection Alist Key Equality
 
 All of Guile's dedicated association list procedures, apart from
-@code{acons}, come in three flavors, depending on the level of equality
+@code{acons}, come in three flavours, depending on the level of equality
 that is required to decide whether an existing key in the association
 list is the same as the key that the procedure call uses to identify the
 required entry.
@@ -1864,7 +1827,7 @@ function is @emph{not} destructive; @var{alist} is not modified.
 @deffnx {C Function} scm_assq_set_x (alist, key, val)
 @deffnx {C Function} scm_assv_set_x (alist, key, val)
 @deffnx {C Function} scm_assoc_set_x (alist, key, val)
-Re-associate @var{key} in @var{alist} with @var{value}: find any existing
+Reassociate @var{key} in @var{alist} with @var{value}: find any existing
 @var{alist} entry for @var{key} and associate it with the new
 @var{value}.  If @var{alist} does not contain an entry for @var{key},
 add a new one.  Return the (possibly new) alist.

doc/ref/scheme-data.texi

@@ -3,7 +3,7 @@
 @chapter Simple Generic Data Types
 
 This chapter describes those of Guile's simple data types which are
-primarily are used for their role as items of generic data.  By
+primarily used for their role as items of generic data.  By
 @dfn{simple} we mean data types that are not primarily used as
 containers to hold other data --- i.e. pairs, lists, vectors and so on.
 For the documentation of such @dfn{compound} data types, see
@@ -193,8 +193,7 @@ discover whether the value is any of the supported numerical types.
 
 @deffn {Scheme Procedure} number? obj
 @deffnx {C Function} scm_number_p (obj)
-Return @code{#t} if @var{obj} is any kind of number, @code{#f} else.
+Return @code{#t} if @var{obj} is any kind of number, else @code{#f}.
-@findex number?
 @end deffn
 
 For example:
@@ -265,7 +264,7 @@ completely invisible to the Scheme level programmer.
 
 @deffn {Scheme Procedure} integer? x
 @deffnx {C Function} scm_integer_p (x)
-Return @code{#t} if @var{x} is an integer number, @code{#f} else.
+Return @code{#t} if @var{x} is an integer number, else @code{#f}.
 
 @lisp
 (integer? 487)
@@ -329,11 +328,10 @@ with those that are already implemented.
 
 @deffn {Scheme Procedure} real? obj
 @deffnx {C Function} scm_real_p (obj)
-Return @code{#t} if @var{obj} is a real number, @code{#f} else.
+Return @code{#t} if @var{obj} is a real number, else @code{#f}.
 Note that the sets of integer and rational values form subsets
 of the set of real numbers, so the predicate will also be fulfilled
 if @var{obj} is an integer number or a rational number.
-@findex real?
 @end deffn
 
 @deffn {Scheme Procedure} rational? x
@@ -1464,6 +1462,7 @@ called with string containing unusual characters.
 * String Searching::            Searching in strings.
 * Alphabetic Case Mapping::     Convert the alphabetic case of strings.
 * Appending Strings::           Appending strings to form a new string.
+* String Miscellanea::          Miscellaneous string procedures.
 @end menu
 
 @node String Syntax
@@ -1859,6 +1858,19 @@ concatenation of the given strings, @var{args}.
 @end deffn
 
 
+@node String Miscellanea
+@subsection String Miscellanea
+
+This section contains all remaining string procedures.
+
+@deffn {Scheme Procedure} string-ci->symbol str
+@deffnx {C Function} scm_string_ci_to_symbol (str)
+Return the symbol whose name is @var{str}.  @var{str} is
+converted to lowercase before the conversion is done, if Guile
+is currently reading symbols case-insensitively.
+@end deffn
+
+
 @node Regular Expressions
 @section Regular Expressions
 @tpindex Regular expressions
@@ -2262,6 +2274,7 @@ objects @i{per se}.
 @menu
 * Symbol Read Syntax::          Extended read syntax for symbols.
 * Symbol Primitives::           Operations related to symbols.
+* Symbol Tables::               Collecting symbols into obarrays.
 * Symbol Discrete::             Using symbols as discrete values.
 * Symbol Props::                Function slots and property lists.
 * Symbol Uninterned::           Uninterned symbols.
@@ -2271,7 +2284,7 @@ objects @i{per se}.
 @node Symbol Read Syntax
 @subsection Extended Read Syntax for Symbols
 
-The read syntax for symbols is a sequence of letters, digits, and
+The read syntax for a symbol is a sequence of letters, digits, and
 @dfn{extended alphabetic characters}, beginning with a character that
 cannot begin a number.  In addition, the special cases of @code{+},
 @code{-}, and @code{...} are read as symbols even though numbers can
@@ -2281,7 +2294,7 @@ Extended alphabetic characters may be used within identifiers as if
 they were letters.  The set of extended alphabetic characters is:
 
 @example
-! $ % & * + - . / : < = > ? @@ ^ _ ~ 
+! $ % & * + - . / : < = > ? @@ ^ _ ~
 @end example
 
 In addition to the standard read syntax defined above (which is taken
@@ -2348,8 +2361,8 @@ standard case is lower case:
 (eq? 'mISSISSIppi 'mississippi) @result{} #t
 (string->symbol "mISSISSIppi") @result{} @r{the symbol with name "mISSISSIppi"}
 (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f
-(eq? 'JollyWog
+(eq? 'LolliPop
-  (string->symbol (symbol->string 'JollyWog))) @result{} #t
+  (string->symbol (symbol->string 'LolliPop))) @result{} #t
 (string=? "K. Harper, M.D."
   (symbol->string
     (string->symbol "K. Harper, M.D."))) @result{}#t
@@ -2391,10 +2404,17 @@ standard case is lower case:
 @end lisp
 @end deffn
 
-@deffn {Scheme Procedure} symbol-hash symbol
+@node Symbol Tables
-@deffnx {C Function} scm_symbol_hash (symbol)
+@subsection Symbol Tables
-Return a hash value for @var{symbol}.
+
-@end deffn
+@c FIXME::martin: Are all these procedures still relevant?
+
+Guile symbol tables are hash tables.  Each hash table, also called an
+@dfn{obarray} (for `object array'), is a vector of association lists.
+Each entry in the alists is a pair (@var{SYMBOL} . @var{VALUE}).  To
+@dfn{intern} a symbol in a symbol table means to return its
+(@var{SYMBOL} . @var{VALUE}) pair, adding a new entry to the symbol
+table (with an undefined value) if none is yet present.
 
 @deffn {Scheme Procedure} gensym [prefix]
 @deffnx {C Function} scm_gensym (prefix)
@@ -2405,6 +2425,12 @@ is increased by 1 at each call. There is no provision for
 resetting the counter.
 @end deffn
 
+@vgone{gentemp,1.6}
+@vgone{intern-symbol,1.6}
+@vgone{string->obarray-symbol,1.6}
+@vgone{symbol-binding,1.6}
+@vgone{symbol-bound?,1.6}
+
 
 @node Symbol Discrete
 @subsection Using Symbols as Discrete Values
@@ -2434,6 +2460,17 @@ Return the contents of @var{symbol}'s @dfn{function slot}.
 Change the binding of @var{symbol}'s function slot.
 @end deffn
 
+@deffn {Scheme Procedure} symbol-hash symbol
+@deffnx {C Function} scm_symbol_hash (symbol)
+Return a hash value for @var{symbol}.
+@end deffn
+
+@deffn {Scheme Procedure} symbol-interned? obarray string
+@deffnx {C Function} scm_symbol_interned_p (obarray, string)
+Return @code{#t} if @var{obarray} contains a symbol with name
+@var{string}, and @code{#f} otherwise.
+@end deffn
+
 @deffn {Scheme Procedure} symbol-pref symbol
 @deffnx {C Function} scm_symbol_pref (symbol)
 Return the @dfn{property list} currently associated with @var{symbol}.
@@ -2444,6 +2481,10 @@ Return the @dfn{property list} currently associated with @var{symbol}.
 Change the binding of @var{symbol}'s property slot.
 @end deffn
 
+@vgone{symbol-set!,1.6}
+@vgone{unintern-symbol,1.6}
+
+
 @node Symbol Uninterned
 @subsection Uninterned Symbols
 
@@ -2465,14 +2506,14 @@ just returns that symbol.  When not, a new symbol with the name is
 created and entered into the table so that it can be found later.
 
 Sometimes you might want to create a symbol that is guaranteed `fresh',
-i.e., a symbol that did not exist previously.  You might also want to
+i.e. a symbol that did not exist previously.  You might also want to
 somehow guarantee that no one else will ever unintentionally stumble
 across your symbol in the future.  These properties of a symbol are
 often needed when generating code during macro expansion.  When
 introducing new temporary variables, you want to guarantee that they
-don't conflict with variables in other peoples code.
+don't conflict with variables in other people's code.
 
-The simplest way to arrange for this is to create a new symbol and to
+The simplest way to arrange for this is to create a new symbol but
 not enter it into the global table of all symbols.  That way, no one
 will ever get access to your symbol by chance.  Symbols that are not in
 the table are called @dfn{uninterned}.  Of course, symbols that
@@ -2531,6 +2572,7 @@ foo-3
 
 @end lisp
 
+
 @node Keywords
 @section Keywords
 @tpindex Keywords
@@ -2717,8 +2759,6 @@ ABORT: (unbound-variable)
 @node Keyword Procedures
 @subsection Keyword Procedures
 
-@c FIXME::martin: Review me!
-
 The following procedures can be used for converting symbols to keywords
 and back.