* preface.texi (Manual Conventions): Added description of

@result{} and @print{}.

	* scheme-data.texi (Hash Table Examples): New subsubsection.

doc/ChangeLog

@@ -1,3 +1,10 @@
+2001-06-30  Martin Grabmueller  <mgrabmue@cs.tu-berlin.de>
+
+	* preface.texi (Manual Conventions): Added description of
+	@result{} and @print{}.
+
+	* scheme-data.texi (Hash Table Examples): New subsubsection.
+	
 2001-06-30  Martin Grabmueller  <mgrabmue@cs.tu-berlin.de>
 
 	* scheme-data.texi (Hash Tables): Added docs for

doc/preface.texi

@@ -1,158 +0,0 @@
-@iftex
-@page
-@unnumbered Preface
-
-This reference manual documents Guile, GNU's Ubiquitous Intelligent
-Language for Extensions.  It describes how to use Guile in many useful
-and interesting ways.
-
-This is edition 1.0 of the reference manual, and corresponds to Guile
-version @value{VERSION}.
-@end iftex
-
-
-@iftex
-@section The Guile License
-@end iftex
-
-@ifnottex
-@node Guile License
-@chapter The Guile License
-@end ifnottex
-
-The license of Guile consists of the GNU GPL plus a special statement
-giving blanket permission to link with non-free software.  This is the
-license statement as found in any individual file that it applies to:
-
-@quotation
-This program is free software; you can redistribute it and/or modify it
-under the terms of the GNU General Public License as published by the
-Free Software Foundation; either version 2, or (at your option) any
-later version.
-
-This program is distributed in the hope that it will be useful, but
-WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-General Public License for more details.
-
-You should have received a copy of the GNU General Public License along
-with this software; see the file COPYING.  If not, write to the Free
-Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
-02111-1307 USA
-
-As a special exception, the Free Software Foundation gives permission
-for additional uses of the text contained in its release of GUILE.
-
-The exception is that, if you link the GUILE library with other files to
-produce an executable, this does not by itself cause the resulting
-executable to be covered by the GNU General Public License.  Your use of
-that executable is in no way restricted on account of linking the GUILE
-library code into it.
-
-This exception does not however invalidate any other reasons why the
-executable file might be covered by the GNU General Public License.
-
-This exception applies only to the code released by the Free Software
-Foundation under the name GUILE.  If you copy code from other Free
-Software Foundation releases into a copy of GUILE, as the General Public
-License permits, the exception does not apply to the code that you add
-in this way.  To avoid misleading anyone as to the status of such
-modified files, you must delete this exception notice from them.
-
-If you write modifications of your own for GUILE, it is your choice
-whether to permit this exception to apply to your modifications.  If you
-do not wish that, delete this exception notice.
-@end quotation
-
-
-@iftex
-@section Layout of this Manual
-@end iftex
-
-@ifnottex
-@node Manual Layout
-@chapter Layout of this Manual
-@end ifnottex
-
-This manual is divided into five parts.
-
-@strong{Part I: Introduction to Guile} provides an overview of what
-Guile is and how you can use it.  A whirlwind tour shows how Guile can
-be used interactively and as a script interpreter, how to link Guile
-into your own applications, and how to write modules of interpreted and
-compiled code for use with Guile.  All of the ideas introduced here are
-documented in full by the later parts of the manual.
-
-@strong{Part II: Guile Scheme} documents the core Scheme language and
-features that Guile implements.  Although the basis for this is the
-Scheme language described in R5RS, this part of the manual does not
-assume any prior familiarity with R5RS in particular, or with Scheme in
-general.  Basic Scheme concepts, standard aspects of the Scheme language
-and Guile extensions on top of R5RS are all documented from scratch, and
-organized by functionality rather than by the defining standards.
-
-@strong{Part III: Guile Modules} describes some important modules,
-distributed as part of the Guile distribution, that extend the
-functionality provided by the Guile Scheme core, most notably:
-
-@itemize @bullet
-@item
-the POSIX module, which provides Scheme level procedures for system and
-network programming, conforming to the POSIX standard
-
-@item
-the SLIB module, which makes Aubrey Jaffer's portable Scheme library
-available for use in Guile.
-@end itemize
-
-@strong{Part IV: Guile Scripting} documents the use of Guile as a script
-interpreter, and illustrates this with a series of examples.
-
-@strong{Part V: Extending Applications Using Guile} explains the options
-available for using Guile as a application extension language.  At the
-simpler end of the scale, an application might use Guile to define some
-application-specific primitives in C and then load an application Scheme
-file.  In this case most of the application code is written on the
-Scheme level, and uses the application-specific primitives as an
-extension to standard Scheme.  At the other end of the scale, an
-application might be predominantly written in C --- with its main
-control loop implemented in C --- but make occasional forays into Scheme
-to, say, read configuration data or run user-defined customization code.
-This part of the manual covers the complete range of application
-extension options.
-
-Finally, the appendices explain how to obtain the latest version of
-Guile, how to install it, where to find modules to work with Guile, and
-how to use the Guile debugger.
-
-
-@iftex
-@section Manual Conventions
-@end iftex
-
-@ifnottex
-@node Manual Conventions
-@chapter Conventions used in this Manual
-@end ifnottex
-
-We use some conventions in this manual.
-
-@itemize @bullet
-
-@item
-For some procedures, notably type predicates, we use @dfn{iff} to
-mean `if and only if'.  The construct is usually something like:
-`Return @var{val} iff @var{condition}', where @var{val} is usually
-`@code{#t}' or `non-@code{#f}'.  This typically means that @var{val}
-is returned if @var{condition} holds, and that @samp{#f} is returned
-otherwise.
-@cindex iff
-
-@c Add other conventions here.
-
-@end itemize
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:

doc/scheme-data.texi

@@ -4784,6 +4784,98 @@ capitals
 @subsection Hash Tables
 @tpindex Hash Tables
 
+@c FIXME::martin: Review me!
+
+Hash tables are dictionaries which offer similar functionality as
+association lists: They provide a mapping from keys to values.  The
+difference is that association lists need time linear in the size of
+elements when searching for entries, whereas hash tables can normally
+search in constant time.  The drawback is that hash tables require a
+little bit more memory, and that you can not use the normal list
+procedures (@pxref{Lists}) for working with them.
+
+@menu
+* Hash Table Examples::         Demonstration of hash table usage.
+* Hash Table Reference::        Hash table procedure descriptions.
+@end menu
+
+
+@node Hash Table Examples
+@subsubsection Hash Table Examples
+
+@c FIXME::martin: Review me!
+
+For demonstration purposes, this section gives a few usage examples of
+some hash table procedures, together with some explanation what they do.
+
+First we start by creating a new hash table with 31 slots, and
+populate it with two key/value pairs.
+
+@lisp
+(define h (make-hash-table 31))
+
+(hashq-create-handle! h 'foo "bar")
+@result{}
+(foo . "bar")
+
+(hashq-create-handle! h 'braz "zonk")
+@result{}
+(braz . "zonk")
+
+(hashq-create-handle! h 'frob #f)
+@result{}
+(frob . #f)
+@end lisp
+
+You can get the value for a given key with the procedure
+@code{hashq-ref}, but the problem with this procedure is that you
+cannot reliably determine whether a key does exists in the table.  The
+reason is that the procedure returns @code{#f} if the key is not in
+the table, but it will return the same value if the key is in the
+table and just happens to have the value @code{#f}, as you can see in
+the following examples.
+
+@lisp
+(hashq-ref h 'foo)
+@result{}
+"bar"
+
+(hashq-ref h 'frob)
+@result{}
+#f
+
+(hashq-ref h 'not-there)
+@result{}
+#f
+@end lisp
+
+Better is to use the procedure @code{hashq-get-handle}, which makes a
+distinction between the two cases.  Just like @code{assq}, this
+procedure returns a key/value-pair on success, and @code{#f} if the
+key is not found.
+
+@lisp
+(hashq-get-handle h 'foo)
+@result{}
+(foo . "bar")
+
+(hashq-get-handle h 'not-there)
+@result{}
+#f
+@end lisp
+
+There is no procedure for calculating the number of key/value-pairs in
+a hash table, but @code{hash-fold} can be used for doing exactly that.
+
+@lisp
+(hash-fold (lambda (key value seed) (+ 1 seed)) 0 h)
+@result{}
+3
+@end lisp
+
+@node Hash Table Reference
+@subsubsection Hash Table Reference
+
 Like the association list functions, the hash table functions come
 in several varieties: @code{hashq}, @code{hashv}, and @code{hash}.
 The @code{hashq} functions use @code{eq?} to determine whether two
@@ -4991,7 +5083,7 @@ The arguments to PROC are "(key value prior-result)" where key
 and value are successive pairs from the hash table TABLE, and
 prior-result is either INIT (for the first application of PROC)
 or the return value of the previous application of PROC.
-For example, @code{(hash-fold acons () tab)} will convert a hash
+For example, @code{(hash-fold acons '() tab)} will convert a hash
 table into an a-list of key-value pairs.
 @end deffn