Re: Do you recognize these modules?

[Noah Lavine <noah.b.lavine@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 1232 bytes --]

Hello all,

I'm sorry to miss 2.0.6 by only a few days, but I have turned this
documentation into some patches. Here they are; I think they are ready
to apply to stable-2.0.

The first patch is just a quick note that SRFI-2 has another name. The
second patch is the big one: it imports most of the documentation from
Thien-Thi's patch. The third one just changes the (ice-9 hcons)
documentation a bit because I thought it flowed more nicely that way,
and the fourth patch commits a modified version of the (ice-9
string-fun) documentation. It had to be changed because it documented
an old interface to substring/shared which Guile doesn't seem to
support any more.

What do you think?

Noah

On Fri, May 25, 2012 at 1:02 PM, Thien-Thi Nguyen <ttn@gnuvola.org> wrote:
> () Andy Wingo <wingo@pobox.com>
> () Fri, 25 May 2012 14:48:19 +0200
>
>    You interested in submitting this as a patches to Guile?
>
> Not really.  The documentation is necessarily Guile 1.4-specific,
> requiring reconciliation in both content and style for best 1.8+
> fit.  I think Noah Lavine is in a better position to do that work,
> so i defer to his initiative, including commit strategy.
>
> (Fancy-sounding but fundamentally lame excuse ends here.)
>

[-- Attachment #2: 0001-Document-ice-9-and-let-star.patch --]
[-- Type: application/octet-stream, Size: 860 bytes --]

From 2039833f381aa6f56d9285e9db1a849751b590d0 Mon Sep 17 00:00:00 2001
From: Noah Lavine <noah.b.lavine@gmail.com>
Date: Sat, 30 Jun 2012 08:42:44 -0400
Subject: [PATCH 1/4] Document (ice-9 and-let-star)

* doc/ref/srfi-modules.texi: note that (srfi srfi-2) is the same as
  (ice-9 and-let-star).
---
 doc/ref/srfi-modules.texi |    6 ++++++
 1 files changed, 6 insertions(+), 0 deletions(-)

diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi
index fdc316f..7e7d658 100644
--- a/doc/ref/srfi-modules.texi
+++ b/doc/ref/srfi-modules.texi
@@ -1237,6 +1237,12 @@ The following syntax can be obtained with
 (use-modules (srfi srfi-2))
 @end lisp
 
+or alternatively
+
+@lisp
+(use-modules (ice-9 and-let-star))
+@end lisp
+
 @deffn {library syntax} and-let* (clause @dots{}) body @dots{}
 A combination of @code{and} and @code{let*}.
 
-- 
1.7.6


[-- Attachment #3: 0002-Import-documentation-from-Guile-1.4.patch --]
[-- Type: application/octet-stream, Size: 68605 bytes --]

From 3215a785c1b825b8e0964cdbb83d0e48f2a657a7 Mon Sep 17 00:00:00 2001
From: Noah Lavine <noah.b.lavine@gmail.com>
Date: Tue, 10 Jul 2012 20:42:53 -0400
Subject: [PATCH 2/4] Import documentation from Guile 1.4

Thanks to Thien-Thi Nguyen for contributing it.

 * doc/ref/Makefile.am: update Makefile
 * doc/ref/guile.texi: add sections to manual
 * doc/ref/calling.texi:
 * doc/ref/common-list.texi:
 * doc/ref/gap-buffer.texi:
 * doc/ref/hcons.texi:
 * doc/ref/lineio.texi:
 * doc/ref/ls.texi:
 * doc/ref/mapping.texi:
 * doc/ref/poe.texi:
 * doc/ref/popen.texi:
 * doc/ref/runq.texi:
 * doc/ref/session.texi:
 * doc/ref/stack-catch.texi:
 * doc/ref/threads.texi: add files
---
 doc/ref/Makefile.am      |   13 ++
 doc/ref/calling.texi     |  210 +++++++++++++++++++++++++
 doc/ref/common-list.texi |  168 ++++++++++++++++++++
 doc/ref/gap-buffer.texi  |  387 ++++++++++++++++++++++++++++++++++++++++++++++
 doc/ref/guile.texi       |   27 ++++
 doc/ref/hcons.texi       |   95 +++++++++++
 doc/ref/lineio.texi      |   66 ++++++++
 doc/ref/ls.texi          |   75 +++++++++
 doc/ref/mapping.texi     |   80 ++++++++++
 doc/ref/poe.texi         |   53 +++++++
 doc/ref/popen.texi       |   54 +++++++
 doc/ref/runq.texi        |  137 ++++++++++++++++
 doc/ref/session.texi     |  113 ++++++++++++++
 doc/ref/stack-catch.texi |  135 ++++++++++++++++
 doc/ref/threads.texi     |   71 +++++++++
 15 files changed, 1684 insertions(+), 0 deletions(-)
 create mode 100644 doc/ref/calling.texi
 create mode 100644 doc/ref/common-list.texi
 create mode 100644 doc/ref/gap-buffer.texi
 create mode 100644 doc/ref/hcons.texi
 create mode 100644 doc/ref/lineio.texi
 create mode 100644 doc/ref/ls.texi
 create mode 100644 doc/ref/mapping.texi
 create mode 100644 doc/ref/poe.texi
 create mode 100644 doc/ref/popen.texi
 create mode 100644 doc/ref/runq.texi
 create mode 100644 doc/ref/session.texi
 create mode 100644 doc/ref/stack-catch.texi
 create mode 100644 doc/ref/threads.texi

diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am
index abe9cb9..f86a831 100644
--- a/doc/ref/Makefile.am
+++ b/doc/ref/Makefile.am
@@ -61,6 +61,19 @@ guile_TEXINFOS = preface.texi			\
 		 posix.texi			\
 		 web.texi			\
 		 expect.texi			\
+		 calling.texi			\
+		 common-list.texi		\
+		 gap-buffer.texi		\
+		 hcons.texi			\
+		 lineio.texi			\
+		 ls.texi			\
+		 mapping.texi			\
+		 poe.texi			\
+		 popen.texi			\
+		 runq.texi			\
+		 session.texi			\
+		 stack-catch.texi		\
+		 threads.texi			\
 		 scsh.texi			\
 		 sxml-match.texi		\
 		 scheme-scripts.texi		\
diff --git a/doc/ref/calling.texi b/doc/ref/calling.texi
new file mode 100644
index 0000000..172f744
--- /dev/null
+++ b/doc/ref/calling.texi
@@ -0,0 +1,210 @@
+@c calling.texi
+
+@c Copyright (C) 2012 Free Software Foundation, Inc.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+@c copy of the license is included in the section entitled ``GNU Free
+@c Documentation License.''
+
+@node Conventional Calling
+@section Conventional Calling
+
+To make use of idiomatic calling-convention macros, evaluate the form:
+
+@smalllisp
+(use-modules (ice-9 calling))
+@end smalllisp
+
+@c @twerpmacdoc (save-bindings-excursion)
+@c ../../ice-9/calling.doc
+@deffn {Scheme Macro} save-bindings-excursion vars [body...]
+Expand to a form that saves the values for each binding named in
+@var{vars}, a list of unevaluated symbols naming bindings in the
+@code{save-bindings-excursion} caller, evaluates the @var{body} forms,
+then restores the values.  These operations form the three branches of a
+@code{dynamic-wind}.  Here is an example:
+
+@example
+(define a 42)
+(define c 99)
+(define (chk!) (write-line (list #:a a #:c c)))
+
+(save-bindings-excursion (a c)
+  (chk!)
+  (set! a 0)
+  (set! c -1)
+  (chk!))
+@end example
+@end deffn
+@c @twerpmacdoc (with-excursion-function)
+@c ../../ice-9/calling.doc
+@deffn {Scheme Macro} with-excursion-function vars collect
+Expand to an application of @var{collect} to an excursion proc @var{ex}.
+@var{ex} takes one argument, a thunk, which forms the middle branch of a
+@code{dynamic-wind}.  In the first branch, @var{ex} saves the values of
+@var{vars}, a list of unevaluated symbols naming bindings in the
+@code{with-excursion-function} caller.  In the third branch, @var{ex}
+restores these values.  Here is an example that shows how to use this
+macro:
+
+@example
+(with-excursion-function
+  (a c) (lambda (ex)
+          (ex (lambda ()
+                (chk!)
+                (set! a 0)
+                (set! c -1)
+                (chk!)))))
+@end example
+
+In this example, @var{collect} is an anonymous procedure, and the
+excursion proc is named @code{ex}.  Note that this is functionally
+equivalent to the one for @code{save-bindings-excursion} (with setup
+definitions elided).
+@end deffn
+@c @twerpmacdoc (with-getter-and-setter)
+@c ../../ice-9/calling.doc
+@deffn {Scheme Macro} with-getter-and-setter vars collect
+Expand to an application of @var{collect} to @var{getter} and @var{setter}
+procs for @var{vars}, an unevaluated list of symbols naming bindings in
+the caller of @code{with-getter-and-setter}.  The call looks like:
+
+@example
+(collect getter setter)
+@end example
+
+@var{getter} and @var{setter} are procedures used to access or modify
+@var{vars}.  @var{setter}, called with keywords arguments, modifies the
+named values.  For example, if @code{foo} and @code{bar} are among
+@var{vars}, then:
+
+@example
+(setter #:foo 1 #:bar 2)
+===
+(begin (set! foo 1) (set! bar 2))
+@end example
+
+@var{getter}, called with just keywords, returns a list of the
+corresponding values.  To continue the above example:
+
+@example
+(getter #:foo #:bar)
+@result{} (1 2)
+@end example
+
+@var{getter}, called with no arguments, returns a list of all accepted
+keywords and the corresponding values.  To continue the above example,
+with the additional stipulation that @code{foo} and @code{bar} are
+the @emph{only} names in @var{vars}:
+
+@example
+(getter)
+@result{} (#:foo 1 #:bar 2)
+@end example
+
+These calling sequences supports two handy idioms:
+
+@example
+(apply setter (getter))              ;; save and restore
+
+(apply-to-args (getter #:foo #:bar)  ;; fetch and bind
+  (lambda (foo bar) ....))
+@end example
+@end deffn
+@c @twerpmacdoc (with-getter)
+@c ../../ice-9/calling.doc
+@deffn {Scheme Macro} with-getter vars collect
+Like @code{with-getter-and-setter} but collect only @var{getter}.
+@end deffn
+@c @twerpmacdoc (with-delegating-getter-and-setter)
+@c ../../ice-9/calling.doc
+@deffn {Scheme Macro} with-delegating-getter-and-setter vars sub-g sub-s collect
+Expand to an application of @var{collect} to @var{getter} and @var{setter}
+procs for @var{vars}, an unevaluated list of symbols naming bindings in
+the caller of @code{with-delegating-getter-and-setter}.  The call looks
+like:
+
+@example
+(collect getter setter)
+@end example
+
+If given a name not in @var{vars}, @var{getter} and @var{setter} call
+@var{sub-g} and @var{sub-s}, respectively.
+@end deffn
+@c @twerpmacdoc (with-excursion-getter-and-setter)
+@c ../../ice-9/calling.doc
+@deffn {Scheme Macro} with-excursion-getter-and-setter vars collect
+Expand to an application of @var{collect} to excursion proc @var{ex},
+@var{getter} and @var{setter} procs for @var{vars}, an unevaluated list of
+symbols naming bindings in the caller of
+@code{with-excursion-getter-and-setter}.  The call looks like:
+
+@example
+(collect excursion getter setter)
+@end example
+
+See @code{with-excursion-function} and @code{with-getter-and-setter}.
+@end deffn
+@c @twerpmacdoc (with-configuration-getter-and-setter)
+@c ../../ice-9/calling.doc
+@deffn {Scheme Macro} with-configuration-getter-and-setter vars-etc collect
+Expand to an application of @var{collect} to @var{getter} and @var{setter}
+procs for @var{vars-etc}, a list of binding specifiers for bindings
+visible in the caller of @code{with-configuration-getter-and-setter}.  The
+call looks like:
+
+@example
+(collect getter setter)
+@end example
+
+@var{getter} and @var{setter} can trigger arbitrary computation, according
+to the binding specifier, which has the form:
+
+@example
+(name [getter-hook [setter-hook]])
+@end example
+
+Both hook elements are evaluated; @var{name} is not.
+Either hook may be #f or a procedure.
+
+@var{getter-hook} is a thunk that returns a value for the corresponding
+name.  If omitted (or #f is passed), use the normal value of @code{name}.
+
+@var{setter-hook} is a procedure of one argument that accepts a new value
+for @var{name}.  If omitted, @var{name} is simply updated with @code{set!}.
+@end deffn
+@c @twerpmacdoc (with-delegating-configuration-getter-and-setter)
+@c ../../ice-9/calling.doc
+@deffn {Scheme Macro} with-delegating-configuration-getter-and-setter vars-etc sub-g sub-s collect
+Like @code{with-delegating-getter-and-setter} but using @var{vars-etc}
+as with @code{with-configuration-getter-and-setter}.
+@end deffn
+@c @twerpmacdoc (let-with-configuration-getter-and-setter)
+@c ../../ice-9/calling.doc
+@deffn {Scheme Macro} let-with-configuration-getter-and-setter vars-etc collect
+Like @code{with-configuration-getter-and-setter}
+except that each element of @var{vars-etc} is:
+
+@example
+(name initial-value getter-hook setter-hook)
+@end example
+
+Also, this macro introduces an additional lexical binding for each
+of the names in @code{vars-etc}.  It is short-hand for:
+
+@example
+(let ((<var1> initial-value-1)
+      (<var2> initial-value-2)
+       ...)
+ (with-configuration-getter-and-setter
+    ((<var1> v1-get v1-set)
+     (<var2> v2-get v2-set)
+     ...)
+   collect))
+@end example
+@end deffn
+
+@c calling.texi ends here
diff --git a/doc/ref/common-list.texi b/doc/ref/common-list.texi
new file mode 100644
index 0000000..2741c53
--- /dev/null
+++ b/doc/ref/common-list.texi
@@ -0,0 +1,168 @@
+@c common-list.texi
+
+@c Copyright (C) 2012 Free Software Foundation, Inc.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+@c copy of the license is included in the section entitled ``GNU Free
+@c Documentation License.''
+
+@node Common List Operations
+@c @chapter Common List Operations
+@section Common List Operations
+
+This module provides an implementation of Common Lisp list functions
+for Guile.  To load it:
+
+@example
+(use-modules (ice-9 common-list))
+@end example
+
+@xref{SRFI-1}, for another list library.
+
+@c @twerpdoc (adjoin)
+@c ../../ice-9/common-list.doc
+@deffn {Scheme Procedure} adjoin e l
+Return list L, possibly with element E added if it is not already in L.
+@end deffn
+@c @twerpdoc (union)
+@c ../../ice-9/common-list.doc
+@deffn {Scheme Procedure} union l1 l2
+Return a new list that is the union of L1 and L2.
+Elements that occur in both lists occur only once in
+the result list.
+@end deffn
+@c @twerpdoc (intersection)
+@c ../../ice-9/common-list.doc
+@deffn {Scheme Procedure} intersection l1 l2
+Return a new list that is the intersection of L1 and L2.
+Only elements that occur in both lists occur in the result list.
+@end deffn
+@c @twerpdoc (set-difference)
+@c ../../ice-9/common-list.doc
+@deffn {Scheme Procedure} set-difference l1 l2
+Return elements from list L1 that are not in list L2.
+@end deffn
+@c @twerpdoc (reduce-init)
+@c ../../ice-9/common-list.doc
+@deffn {Scheme Procedure} reduce-init p init l
+Same as `reduce' except it implicitly inserts INIT at the start of L.
+@end deffn
+@c @twerpdoc (reduce)
+@c ../../srfi/srfi-1.doc
+@deffn {Scheme Procedure} reduce f ridentity lst
+@code{reduce} is a variant of @code{fold}.  If @var{lst} is
+@code{()}, @var{ridentity} is returned.  Otherwise, @code{(fold (car
+@var{lst}) (cdr @var{lst}))} is returned.
+@end deffn
+@c @twerpdoc (some)
+@c ../../ice-9/common-list.doc
+@deffn {Scheme Procedure} some pred l [rest...]
+PRED is a boolean function of as many arguments as there are list
+arguments to `some', i.e., L plus any optional arguments.  PRED is
+applied to successive elements of the list arguments in order.  As soon
+as one of these applications returns a true value, return that value.
+If no application returns a true value, return #f.
+All the lists should have the same length.
+@end deffn
+@c @twerpdoc (every)
+@c ../../srfi/srfi-1.doc
+@deffn {Scheme Procedure} every pred ls [lists...]
+Apply @var{pred} across the lists and return a true value if the
+predicate returns true for every of the list elements(s); return
+@code{#f} otherwise.  The true value returned is always the result of
+the final successful application of @var{pred}.
+@end deffn
+@c @twerpdoc (notany)
+@c ../../ice-9/common-list.doc
+@deffn {Scheme Procedure} notany pred [ls...]
+Return #t iff every application of PRED to L, etc., returns #f.
+Analogous to some but returns #t if no application of PRED returns a
+true value or #f as soon as any one does.
+@end deffn
+@c @twerpdoc (notevery)
+@c ../../ice-9/common-list.doc
+@deffn {Scheme Procedure} notevery pred [ls...]
+Return #t iff there is an application of PRED to L, etc., that returns #f.
+Analogous to some but returns #t as soon as an application of PRED returns #f,
+or #f otherwise.
+@end deffn
+@c @twerpdoc (count-if)
+@c ../../ice-9/common-list.doc
+@deffn {Scheme Procedure} count-if pred l
+Return the number of elements in L for which (PRED element) returns true.
+@end deffn
+@c @twerpdoc (find-if)
+@c ../../ice-9/common-list.doc
+@deffn {Scheme Procedure} find-if pred l
+Search for the first element in L for which (PRED element) returns true.
+If found, return that element, otherwise return #f.
+@end deffn
+@c @twerpdoc (member-if)
+@c ../../ice-9/common-list.doc
+@deffn {Scheme Procedure} member-if pred l
+Return the first sublist of L for whose car PRED is true.
+@end deffn
+@c @twerpdoc (remove-if)
+@c ../../ice-9/common-list.doc
+@deffn {Scheme Procedure} remove-if pred l
+Remove all elements from L where (PRED element) is true.
+Return everything that's left.
+@end deffn
+@c @twerpdoc (remove-if-not)
+@c ../../ice-9/common-list.doc
+@deffn {Scheme Procedure} remove-if-not pred l
+Remove all elements from L where (PRED element) is #f.
+Return everything that's left.
+@end deffn
+@c @twerpdoc (delete-if!)
+@c ../../ice-9/common-list.doc
+@deffn {Scheme Procedure} delete-if! pred l
+Destructive version of `remove-if'.
+@end deffn
+@c @twerpdoc (delete-if-not!)
+@c ../../ice-9/common-list.doc
+@deffn {Scheme Procedure} delete-if-not! pred l
+Destructive version of `remove-if-not'.
+@end deffn
+@c @twerpdoc (butlast)
+@c ../../ice-9/common-list.doc
+@deffn {Scheme Procedure} butlast lst n
+Return all but the last N elements of LST.
+@end deffn
+@c @twerpdoc (and?)
+@c ../../ice-9/common-list.doc
+@deffn {Scheme Procedure} and? [args...]
+Return #t iff all of ARGS are true.
+@end deffn
+@c @twerpdoc (or?)
+@c ../../ice-9/common-list.doc
+@deffn {Scheme Procedure} or? [args...]
+Return #t iff any of ARGS is true.
+@end deffn
+@c @twerpdoc (has-duplicates?)
+@c ../../ice-9/common-list.doc
+@deffn {Scheme Procedure} has-duplicates? lst
+Return #t iff 2 members of LST are equal?, else #f.
+@end deffn
+@c @twerpdoc (pick)
+@c ../../ice-9/common-list.doc
+@deffn {Scheme Procedure} pick p l
+Apply P to each element of L, returning a list of elts
+for which P returns a non-#f value.
+@end deffn
+@c @twerpdoc (pick-mappings)
+@c ../../ice-9/common-list.doc
+@deffn {Scheme Procedure} pick-mappings p l
+Apply P to each element of L, returning a list of the
+non-#f return values of P.
+@end deffn
+@c @twerpdoc (uniq)
+@c ../../ice-9/common-list.doc
+@deffn {Scheme Procedure} uniq l
+Return a list containing elements of L, with duplicates removed.
+@end deffn
+
+@c common-list.texi ends here
diff --git a/doc/ref/gap-buffer.texi b/doc/ref/gap-buffer.texi
new file mode 100644
index 0000000..363550c
--- /dev/null
+++ b/doc/ref/gap-buffer.texi
@@ -0,0 +1,387 @@
+@c gap-buffer.texi
+
+@c Copyright (C) 2012 Free Software Foundation, Inc.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+@c copy of the license is included in the section entitled ``GNU Free
+@c Documentation License.''
+
+@node Gap Buffer
+@section A String Supporting Efficient Insert/Delete
+
+To load support for efficient insert/delete operations on strings:
+
+@lisp
+(use-modules (ice-9 gap-buffer))
+@end lisp
+
+@c @twerpcommentary (verbatim (ice-9 gap-buffer))
+@verbatim
+A gap buffer is a structure that models a string but allows relatively
+efficient insertion of text somewhere in the middle.  The insertion
+location is called `point' with minimum value 1, and a maximum value the
+length of the string (which is not fixed).
+
+Specifically, we allocate a continuous buffer of characters that is
+composed of the BEFORE, the GAP and the AFTER (reading L->R), like so:
+
+                         +--- POINT
+                         v
+   +--------------------+--------------------+--------------------+
+   |       BEFORE       |        GAP         |       AFTER        |
+   +--------------------+--------------------+--------------------+
+
+    <----- bef-sz ----->|<----- gap-sz ----->|<----- aft-sz ----->
+
+    <-------------------|       usr-sz       |------------------->
+
+    <-------------------------- all-sz -------------------------->
+
+This diagram also shows how the different sizes are computed, and the
+location of POINT.  Note that the user-visible buffer size `usr-sz' does
+NOT include the GAP, while the allocation `all-sz' DOES.
+
+The consequence of this arrangement is that "moving point" is simply a
+matter of kicking characters across the GAP, while insertion can be viewed
+as filling up the gap, increasing `bef-sz' and decreasing `gap-sz'.  When
+`gap-sz' falls below some threshold, we reallocate with a larger `all-sz'.
+
+In the implementation, we actually keep track of the AFTER start offset
+`aft-ofs' since it is used more often than `gap-sz'.  In fact, most of the
+variables in the diagram are for conceptualization only.
+
+A gap buffer port is a "soft port" that wraps a gap buffer.
+
+(The term and concept of "gap buffer" are borrowed from Emacs.  We will
+gladly return them when libemacs.so is available. ;-)
+
+A gap-buffer object has the following printed representation:
+
+#<gap-buffer GAP-SIZE/ALLOC-SIZE:POINT-MIN:POINT:POINT-MAX>
+
+with all fields (GAP-SIZE, ALLOC-SIZE, MINT-MIN, POINT, and POINT-MAX)
+integers, and everything else as shown here.
+@end verbatim
+
+@c @twerpdoc (gb?)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb? object
+Return #t iff @var{object} is a gap buffer object.
+@end deffn
+@c @twerpdoc (make-gap-buffer)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} make-gap-buffer [init]
+Return a new gap buffer.  Optional arg @var{init} is either a port
+to read from; a string, used to initialize the buffer contents;
+or an integer specifying the memory allocation (in bytes) requested.
+Point is left at the maximum position.
+@end deffn
+@c @twerpdoc (gb-toggle-read-only)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-toggle-read-only gb [arg]
+Change whether @var{gb} is read-only.
+With arg, set read-only iff arg is positive.
+@end deffn
+
+Implementation note: significant performance gains for non-munging operations
+are possible when the gap-buffer is in read-only mode.  This is primarily
+because in read-only mode, the gap can be reduced to zero, resulting in less
+wasteful data motion.
+
+@subsection querying
+
+@c @twerpdoc (gb-point)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-point gb
+Return the position of point in @var{gb}.
+This is an integer starting with 1 (one).
+@end deffn
+@c @twerpdoc (gb-point-min)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-point-min gb
+Return the minimum position possible for point in @var{gb}.
+At this time, this value is always 1 (one).
+@end deffn
+@c @twerpdoc (gb-point-max)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-point-max gb
+Return the maximum position possible for point in @var{gb}.
+This value can be changed by inserting text into the buffer,
+and is limited by Guile's string implementation.
+@end deffn
+@c @twerpdoc (gb-char-after)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-char-after gb [pos...]
+Return char after @var{pos}, or #f if there is no char there.
+If @var{pos} is not specified, it defaults to point.
+@end deffn
+@c @twerpdoc (gb-char-before)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-char-before gb [pos...]
+Return char before @var{pos}, or #f if there is no char there.
+If @var{pos} is not specified, it defaults to point.
+@end deffn
+@c @twerpdoc (gb-bolp)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-bolp gb
+Return #t if point in @var{gb} is at the beginning of a line.
+@end deffn
+@c @twerpdoc (gb-eolp)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-eolp gb
+Return #t if point in @var{gb} is at the end of a line.
+@end deffn
+@c @twerpdoc (gb-bobp)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-bobp gb
+Return #t if point is at the beginning of @var{gb}.
+@end deffn
+@c @twerpdoc (gb-eobp)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-eobp gb
+Return #t if point is at the end of @var{gb}.
+@end deffn
+
+@subsection munging
+
+@c @twerpdoc (gb-insert-string!)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-insert-string! gb string
+Insert into @var{gb} a @var{string}, moving point forward as well as
+increasing the value that would be returned by @code{gb-point-max}.
+@end deffn
+@c @twerpdoc (gb-insert-char!)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-insert-char! gb char
+Insert into @var{gb} a single @var{char}, moving point forward as well as
+increasing the value that would be returned by @code{gb-point-max}.
+@end deffn
+@c @twerpdoc (gb-insert)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-insert gb [args...]
+Insert the arguments at point.
+If an arg is a gap-buffer, insert its contents.
+If an arg is a pair, insert a string made by applying @code{write} to it.
+If an arg is a number, insert the result of @code{number->string}.
+Other types accepted: char, string, symbol.
+Point moves forward to end up after the inserted text.
+@end deffn
+@c @twerpdoc (gb-delete-char!)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-delete-char! gb count
+In @var{gb}, delete @var{count} characters from point, forward if
+@var{count} is positive, backward if @var{count} is negative.  (If
+@var{count} is zero, do nothing.)  Deleting backwards moves point
+backwards.  Deleting forwards or backwards decreases the value that would
+be returned by @code{gb-point-max}.
+@end deffn
+@c @twerpdoc (gb-delete-region)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-delete-region gb beg end
+Delete text between @var{beg} and @var{end}.
+@end deffn
+@c @twerpdoc (gb-erase!)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-erase! gb
+Completely erase @var{gb}.  Point is left at the minimum position possible
+(which happens to be also the maximum position possible since the buffer
+is empty).
+@end deffn
+
+@subsection moving
+
+@c @twerpdoc (gb-goto-char)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-goto-char gb new-point
+In @var{gb}, move point to @var{new-point} and return it.  If
+@var{new-point} is outside the minimum and maximum positions possible, it
+is adjusted to the the nearest boundary (however, the return value is
+@var{new-point} unchanged).
+@end deffn
+@c @twerpdoc (gb-forward-char)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-forward-char gb n
+In gap-buffer @var{gb}, move point forward @var{n} characters.
+@end deffn
+@c @twerpdoc (gb-backward-char)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-backward-char gb n
+In gap-buffer @var{gb}, move point backward @var{n} characters.
+@end deffn
+@c @twerpdoc (gb-forward-line)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-forward-line gb [n...]
+In gap-buffer @var{gb}, move point @var{n} lines forward (backward if
+@var{n} is negative).  Precisely, if point is on line @code{I}, move to the
+start of line @code{I + N}.  If there isn't room, go as far as possible (no
+error).  Return the count of lines left to move.  If moving forward, that
+is @var{n} - number of lines moved; if backward, @var{n} + number moved.
+With positive @var{n}, a non-empty line at the end counts as one line
+successfully moved (for the return value).
+@end deffn
+@c @twerpdoc (gb-beginning-of-line)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-beginning-of-line gb [n...]
+In gap-buffer @var{gb}, move point to beginning of current line.
+With argument @var{n} not #f or 1, move forward @var{n} - 1 lines first.
+If point reaches the beginning or end of buffer, it stops there.
+@end deffn
+@c @twerpdoc (gb-end-of-line)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-end-of-line gb [n...]
+In gap-buffer @var{gb}, move point to end of current line.
+With argument @var{n} not #f or 1, move forward @var{n} - 1 lines first.
+If point reaches the beginning or end of buffer, it stops there.
+@end deffn
+
+@subsection search (and replace)
+
+@c @twerpdoc (gb-match-string)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-match-string gb n
+Return string of text matched by last search.
+@var{n} specifies which parenthesized expression in the last regexp.
+Value is #f if @var{n}th pair didn't match, or there were less than
+@var{n} pairs.  Zero means the entire text matched by the whole regexp
+or whole string.
+@end deffn
+@c @twerpdoc (gb-looking-at)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-looking-at gb re-str
+Return #t if text after point matches regular expression @var{re-str}.
+This function modifies the match data that @code{gb-match-beginning},
+@code{gb-match-end} and @code{gb-match-data} access; save and restore
+the match data if you want to preserve them.
+@end deffn
+@c @twerpdoc (gb-match-beginning)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-match-beginning [n]
+Return position of start of text matched by last search.
+@var{subexp}, a number, specifies which parenthesized expression
+in the last regexp.  Value is #f if @var{subexp}th pair didn't match,
+or there were less than @var{subexp} pairs.  Zero means the entire text
+matched by the whole regexp.
+@end deffn
+@c @twerpdoc (gb-match-end)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-match-end [n]
+Return position of end of text matched by last search.
+@var{subexp}, a number, specifies which parenthesized expression in the
+last regexp.  Value is nil if @var{subexp}th pair didn't match, or there
+were less than @var{subexp} pairs.  Zero means the entire text matched by
+the whole regexp.
+@end deffn
+@c @twerpdoc (gb-search-forward)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-search-forward string [bound [noerror [count]]]
+Search forward from point for @var{string}.
+Set point to the end of the occurrence found, and return point.
+An optional second argument bounds the search; it is a buffer position.
+The match found must not extend after that position.  #f is equivalent
+  to (point-max).
+Optional third argument, if #t, means if fail just return #f (no error).
+  If not #f and not #t, move to limit of search and return #f.
+Optional fourth argument is repeat count--search for successive occurrences.
+@end deffn
+@c @twerpdoc (gb-search-backward)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-search-backward string [bound [noerror [repeat]]]
+Search backward from point for @var{string}.
+Set point to the beginning of the occurrence found, and return point.
+An optional second argument bounds the search; it is a buffer position.
+The match found must not extend before that position.
+Optional third argument, if t, means if fail just return nil (no error).
+ If not nil and not t, position at limit of search and return nil.
+Optional fourth argument is repeat count--search for successive occurrences.
+@end deffn
+@c @twerpdoc (gb-re-search-forward)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-re-search-forward regexp [bound [noerror [repeat]]]
+Search forward from point for regular expression @var{regexp}.
+Set point to the end of the occurrence found, and return point.
+An optional second argument bounds the search; it is a buffer position.
+The match found must not extend after that position.
+Optional third argument, if #t, means if fail just return #f (no error).
+  If not #f and not #t, move to limit of search and return #f.
+Optional fourth argument is repeat count--search for successive occurrences.
+
+@var{regexp} may be a string, or compiled regular expression made with
+@code{make-regexp}, in which case, it is the caller's decision whether or
+not to include the flag @code{regexp/newline} (normally used when
+@var{regexp} is a string to compile it internally).
+@end deffn
+@c @twerpdoc (gb-replace-match)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-replace-match newtext [IGNORED [literal]]
+Replace text matched by last search with @var{newtext}.
+The second arg is optional and ignored (for now -- in the
+future it may specify case handling a la Emacs).
+
+If third arg @var{literal} is non-#f, insert @var{newtext} literally.
+Otherwise treat @code{\} as special:
+@example
+  `\&' in NEWTEXT means substitute original matched text.
+  `\N' means substitute what matched the Nth `(...)'.
+       If Nth parens didn't match, substitute nothing.
+  `\\' means insert one `\'.
+@end example
+
+Leave point at end of replacement text.
+@end deffn
+
+@subsection misc
+
+@c @twerpdoc (gb->port!)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb->port! gb port [beg [end]]
+Send the contents of @var{gb} to the output @var{port}.
+Optional args @var{beg} and @var{end} specify a region to send.
+Point does not move.
+@end deffn
+@c @twerpdoc (gb->string)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb->string gb
+Return a new string representing the text of @var{gb}.
+Point does not move.
+@end deffn
+@c @twerpdoc (gb->substring)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb->substring gb start end
+Return the region of @var{gb} from @var{start} to @var{end} as a string.
+@end deffn
+@c @twerpdoc (gb-filter!)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-filter! gb string-proc
+Pass the string representing the text of @var{gb} to @var{string-proc} and
+use its return value to completely replace the contents of @var{gb}.
+Point is left at the maximum position.
+@end deffn
+@c @twerpdoc (gb->lines)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb->lines gb
+Return a list of strings representing the lines of text of @var{gb}.
+Newlines are automatically removed.  A buffer with N newlines results
+in a list of length N+1.  Point does not move.
+@end deffn
+@c @twerpdoc (gb-filter-lines!)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} gb-filter-lines! gb lines-proc
+Pass the list of strings representing the lines of text of @var{gb} to
+@var{lines-proc} and use its return value (another list of strings) to
+completely replace the contents of @var{gb}.  Newlines are automatically
+removed and added back.  Point is left at the maximum position.
+@end deffn
+@c @twerpdoc (make-gap-buffer-port)
+@c ../../ice-9/gap-buffer.doc
+@deffn {Scheme Procedure} make-gap-buffer-port gb
+Return a "soft port" on @var{gb} that supports the write-character,
+write-string and read-character operations (flush-output and close-port
+are not supported).  All operations move point forward.  Additionally,
+writing operations increase the value that would be returned by
+@code{gb-point-max}.
+@end deffn
+
+@c gap-buffer.texi ends here
diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
index c3da0c3..ccb522f 100644
--- a/doc/ref/guile.texi
+++ b/doc/ref/guile.texi
@@ -369,6 +369,19 @@ available through both Scheme and C interfaces.
 * Buffered Input::              Ports made from a reader function.
 * Expect::			Controlling interactive programs with Guile.
 * sxml-match::                  Pattern matching of SXML.
+* Conventional Calling::        Calling procedures with conventional interfaces.
+* Common List Operations::      List procedures from Common Lisp.
+* Gap Buffer::                  Strings with fast insertion/deletion.
+* Double-Key Hash Tables::      Two-way maps.
+* Buffered Line IO::            Like @code{read-line}, but buffered.
+* Bindings Browsing::           Browsing the module hierarchy.
+* New Hash Mappings::           New hash mappings.
+* Memoization::                 Procedures that remember their outputs.
+* Alternate Pipes::             Another interface to pipes.
+* Run Queues::                  For parallel execution.
+* Preloaded Modules for Interactive Sessions::
+* Lazy Catch::                  Catch without unwinding.
+* Higher level thread procedures::
 * The Scheme shell (scsh)::     Using scsh interfaces in Guile.
 @end menu
 
@@ -386,6 +399,20 @@ available through both Scheme and C interfaces.
 @c XXX: Would be nicer if it were close to the (sxml simple) documentation.
 @include sxml-match.texi
 
+@include calling.texi
+@include common-list.texi
+@include gap-buffer.texi
+@include hcons.texi
+@include lineio.texi
+@include ls.texi
+@include mapping.texi
+@include poe.texi
+@include popen.texi
+@include runq.texi
+@include session.texi
+@include stack-catch.texi
+@include threads.texi
+
 @include scsh.texi
 
 @node Standard Library
diff --git a/doc/ref/hcons.texi b/doc/ref/hcons.texi
new file mode 100644
index 0000000..1fc3613
--- /dev/null
+++ b/doc/ref/hcons.texi
@@ -0,0 +1,95 @@
+@c hcons.texi
+
+@c Copyright (C) 2012 Free Software Foundation, Inc.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+@c copy of the license is included in the section entitled ``GNU Free
+@c Documentation License.''
+
+@node Double-Key Hash Tables
+@section Double-Key Hash Tables
+
+To use double-key hash tables, evaluate the form:
+
+@smalllisp
+(use-modules (ice-9 hcons))
+@end smalllisp
+
+@c @twerpcommentary (verbatim (ice-9 hcons))
+@c @verbatim
+Eq? hash-consing
+
+A hash conser maintains a private universe of pairs s.t. if
+two cons calls pass eq? arguments, the pairs returned are eq?.
+
+A hash conser does not contribute life to the pairs it returns.
+@c @end verbatim
+
+@c @twerpdoc (hashq-cons-hash)
+@c ../../ice-9/hcons.doc
+@deffn {Scheme Procedure} hashq-cons-hash pair n
+Return the hash of @var{pair} modulo @var{n}.
+Use an @code{eq?} hash of the @sc{car} and
+@sc{cdr} of @var{pair} for the computation.
+@end deffn
+@c @twerpdoc (hashq-cons-assoc)
+@c ../../ice-9/hcons.doc
+@deffn {Scheme Procedure} hashq-cons-assoc key alist
+Return the first element in @var{alist} whose @sc{car} and @sc{cdr} are
+@code{eq?} to that of the pair @var{key}.  Return #f if no match exists.
+@end deffn
+@c @twerpdoc (hashq-cons-get-handle)
+@c ../../ice-9/hcons.doc
+@deffn {Scheme Procedure} hashq-cons-get-handle table key
+Return the handle from hash @var{table} whose @sc{car} and @sc{cdr}
+are @code{eq?} to that of the pair @var{key}.
+@end deffn
+@c @twerpdoc (hashq-cons-create-handle!)
+@c ../../ice-9/hcons.doc
+@deffn {Scheme Procedure} hashq-cons-create-handle! table key init
+Create a handle in hash @var{table} for pair @var{key} and
+store the initial value @var{init} there.  Return the handle.
+@end deffn
+@c @twerpdoc (hashq-cons-ref)
+@c ../../ice-9/hcons.doc
+@deffn {Scheme Procedure} hashq-cons-ref table key
+Return the value associated with pair @var{key} in hash @var{table},
+or #f if @var{key} is not to be found.
+@end deffn
+@c @twerpdoc (hashq-cons-set!)
+@c ../../ice-9/hcons.doc
+@deffn {Scheme Procedure} hashq-cons-set! table key val
+In hash @var{table}, associate with pair @var{key} the value @var{val}.
+@end deffn
+@c @twerpdoc (hashq-cons)
+@c ../../ice-9/hcons.doc
+@deffn {Scheme Procedure} hashq-cons table a d
+Add to hash @var{table} an entry for the double-key @var{a} and
+@var{d}.  The associated value is #f.  Return the combined key (pair).
+@end deffn
+@c @twerpdoc (hashq-conser)
+@c ../../ice-9/hcons.doc
+@deffn {Scheme Procedure} hashq-conser hash-tab-or-size
+Return a procedure that does @code{hashq-cons} on @var{hash-tab-or-size}.
+If @var{hash-tab-or-size} is a number, allocate and a hash table of that
+size and use it.  The procedure takes two args, @var{a} and @var{d}, the
+same as the latter two args of @code{hashq-cons}.
+@end deffn
+
+@c [The following proc really doesn't belong here. --ttn]
+
+@c @twerpdoc (make-gc-buffer)
+@c ../../ice-9/hcons.doc
+@deffn {Scheme Procedure} make-gc-buffer n
+Construct a private ring (circular list) of @var{n} elements and return a
+procedure @var{proc} that updates it.  @var{proc} takes one argument,
+@var{next}, which is added to the ring and also returned.  An element added
+in this way remains referenced for the next @code{@var{n} @minus{} 1}
+invocations of @var{proc}.  To ``clear'' the ring, consecutively call
+@var{proc} with arg #f at least @var{n} times.
+@end deffn
+
+@c hcons.texi ends here
diff --git a/doc/ref/lineio.texi b/doc/ref/lineio.texi
new file mode 100644
index 0000000..1d15494
--- /dev/null
+++ b/doc/ref/lineio.texi
@@ -0,0 +1,66 @@
+@c lineio.texi
+
+@c Copyright (C) 2012 Free Software Foundation, Inc.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+@c copy of the license is included in the section entitled ``GNU Free
+@c Documentation License.''
+
+@node Buffered Line IO
+@section Buffered Variant
+
+You can use a buffered variant of @code{read-line} by evaluating:
+
+@smalllisp
+(use-modules (ice-9 lineio))
+@end smalllisp
+
+This module provides a procedure to create
+a @dfn{line-buffering input port}, a related predicate,
+and two procedures to read a line from the port or push a line
+back onto the stream.
+
+Note: The implementation of @code{unread-string} is kind of limited; it
+doesn't interact properly with unread-char, or any of the other port reading
+functions.  Only @code{read-string} will get you back the things that
+@code{unread-string} accepts.
+
+Normally a "line" is all characters up to and including a newline.  If lines
+are put back using @code{unread-string}, they can be broken arbitrarily --
+that is, @code{read-string} returns strings passed to @code{unread-string} (or
+shared substrings of them).
+
+@c @twerpdoc (lineio-port?)
+@c ../../ice-9/lineio.doc
+@deffn {Scheme Procedure} lineio-port? port
+Return #t iff @var{port} is a port capable of handling
+@code{read-string} and @code{unread-string}.
+@end deffn
+@c @twerpdoc (make-line-buffering-input-port)
+@c ../../ice-9/lineio.doc
+@deffn {Scheme Procedure} make-line-buffering-input-port underlying-port
+Return a wrapper port for @var{underlying-port}.
+
+The wrapper port buffers characters read from @var{underlying-port}
+internally, and parcels them out via calls to @code{read-char},
+@code{read-string} and @code{unread-string}.
+@end deffn
+@c @twerpdoc (read-string)
+@c ../../ice-9/lineio.doc
+@deffn {Scheme Procedure} read-string line-buffering-input-port
+Read a line from @var{line-buffering-input-port}.
+Return it as a string, ending with newline.
+@end deffn
+@c @twerpdoc (unread-string)
+@c ../../ice-9/lineio.doc
+@deffn {Scheme Procedure} unread-string str line-buffering-input-port
+Return string @var{str} to @var{line-buffering-input-port}.
+A subsequent call to @code{read-string} or @code{read-char} from
+this port will retrieve this string or its first character, respectively,
+before consulting the underlying port.
+@end deffn
+
+@c lineio.texi ends here
diff --git a/doc/ref/ls.texi b/doc/ref/ls.texi
new file mode 100644
index 0000000..7fe5e2d
--- /dev/null
+++ b/doc/ref/ls.texi
@@ -0,0 +1,75 @@
+@c ls.texi
+
+@c Copyright (C) 2012 Free Software Foundation, Inc.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+@c copy of the license is included in the section entitled ``GNU Free
+@c Documentation License.''
+
+@node Bindings Browsing
+@section Bindings Browsing
+
+You can think of the module system's hierarchical namespace as analogous
+to that of a (modernish) filesystem.  Whereas a filesystem has directories,
+subdirectores and files, the module system has modules, bindings resolving to
+nested modules, and bindings resolving to ordinary Scheme values.  To browse
+this hierarchy, evaluate the form:
+
+@smalllisp
+(use-modules (ice-9 ls))
+@end smalllisp
+
+This provides several procedures that are roughly akin to the unixoid ls(1)
+command, hence the name.
+
+@c @twerpdoc (local-definitions-in)
+@c ../../ice-9/ls.doc
+@deffn {Scheme Procedure} local-definitions-in root names
+Return a list of names defined locally in the named subdirectory of
+@var{root}.
+@end deffn
+@c @twerpdoc (definitions-in)
+@c ../../ice-9/ls.doc
+@deffn {Scheme Procedure} definitions-in root names
+Return a list of all names defined in the named subdirectory of
+@var{root}.  The list includes all locally defined names as well as
+all names inherited from a member of a use-list.
+@end deffn
+@c @twerpdoc (ls)
+@c ../../ice-9/ls.doc
+@deffn {Scheme Procedure} ls [various-refs...]
+With no arguments, return a list of definitions in the current module.
+
+With just one argument, interpret that argument as the name of a
+subdirectory of the current module and return a list of names defined
+there.
+
+With more than one argument, still compute subdirectory lists, but
+return a list:
+
+@smalllisp
+((<subdir-name> . <names-defined-there>)
+ (<subdir-name> . <names-defined-there>)
+ ...)
+@end smalllisp
+@end deffn
+@c @twerpdoc (lls)
+@c ../../ice-9/ls.doc
+@deffn {Scheme Procedure} lls [various-refs...]
+Analogous to @code{ls}, but with local definitions only.
+@end deffn
+@c @twerpdoc (recursive-local-define)
+@c ../../ice-9/ls.doc
+@deffn {Scheme Procedure} recursive-local-define name value
+Define @var{name} to have value @var{value}.
+@var{name} is a list of symbols, the last one being the
+binding name and the all previous ones being elements of the
+module name.
+@end deffn
+
+@c [Some examples here would be nice. --ttn]
+
+@c ls.texi ends here
diff --git a/doc/ref/mapping.texi b/doc/ref/mapping.texi
new file mode 100644
index 0000000..5bcf9a0
--- /dev/null
+++ b/doc/ref/mapping.texi
@@ -0,0 +1,80 @@
+@c mapping.texi
+
+@c Copyright (C) 2012 Free Software Foundation, Inc.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+@c copy of the license is included in the section entitled ``GNU Free
+@c Documentation License.''
+
+@node New Hash Mappings
+@section New Hash Mappings
+
+To create and use new hash table mappings, evaluate the form:
+
+@smalllisp
+(use-modules (ice-9 mapping))
+@end smalllisp
+
+@c @twerpdoc (hash-table-mapping)
+@c ../../ice-9/mapping.doc
+@deffn {Scheme Procedure} hash-table-mapping [options...]
+Return a mapping object, configured by @var{options}.
+
+@var{options} are alternating keywords and values, passed to
+@code{make-hash-table}.  Two keywords are handled specially:
+
+@table @code
+@item #:hash2 @var{hash2}
+@var{hash2} is a procedure that takes two arguments, a key and an integer
+@var{n}.  It should return an integer modulo @var{n}.  If unspecified, the
+default is @code{hash}.
+
+@item #:equal @var{equal}
+@var{equal} is a procedure that takes two arguments and returns non-#f
+if they are considered to represent the same key.  If unspecified, the
+default is @code{equal?}.
+@end table
+
+The mapping object prints using hash notation:
+
+@example
+(hash-table-mapping #:size 3 #:equal string-ci=?)
+@result{} #<mapping hash/string-ci=? 3 4022fcf8>
+@end example
+@end deffn
+@c @twerpdoc (mapping-get-handle)
+@c ../../ice-9/mapping.doc
+@deffn {Scheme Procedure} mapping-get-handle map key
+Return the handle from mapping @var{map} for @var{key}, or #f
+if @var{key} is not in @var{map}.
+@end deffn
+@c @twerpdoc (mapping-create-handle!)
+@c ../../ice-9/mapping.doc
+@deffn {Scheme Procedure} mapping-create-handle! map key [default]
+Return the handle from mapping @var{map} for @var{key}, or if
+@var{key} is not in @var{map}, create a new handle with value
+@var{default} and return the new handle.
+@end deffn
+@c @twerpdoc (mapping-remove!)
+@c ../../ice-9/mapping.doc
+@deffn {Scheme Procedure} mapping-remove! map key
+Remove @var{key} and its associated value from mappping @var{map}.
+Return the handle.
+@end deffn
+@c @twerpdoc (mapping-ref)
+@c ../../ice-9/mapping.doc
+@deffn {Scheme Procedure} mapping-ref map key [default]
+Return the value associated with @var{key} in mapping @var{map},
+or @var{default} if there is no such association.
+@end deffn
+@c @twerpdoc (mapping-set!)
+@c ../../ice-9/mapping.doc
+@deffn {Scheme Procedure} mapping-set! map key val
+Associate @var{key} with @var{val} in mapping @var{map}.
+Return @var{val}.
+@end deffn
+
+@c mapping.texi end here
diff --git a/doc/ref/poe.texi b/doc/ref/poe.texi
new file mode 100644
index 0000000..5c377e9
--- /dev/null
+++ b/doc/ref/poe.texi
@@ -0,0 +1,53 @@
+@c poe.texi
+
+@c Copyright (C) 2012 Free Software Foundation, Inc.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+@c copy of the license is included in the section entitled ``GNU Free
+@c Documentation License.''
+
+@node Memoization
+@section Memoization
+
+To make use of the memoization facilities, evaluate the form:
+
+@smalllisp
+(use-modules (ice-9 poe))
+@end smalllisp
+
+This provides two ``purity of essence'' [insert actual Vonnegut allusion here,
+someday, or not] procedures for memoizing @dfn{pure functions}.
+
+@c @twerpcommentary (include (ice-9 poe))
+A pure function (of some sort) is characterized by two equality
+relations: one on argument lists and one on return values.
+A pure function is one that when applied to equal arguments lists
+yields equal results.
+
+If the equality relationship on return values can be @code{eq?}, it may
+make sense to cache values returned by the function.  Choosing the right
+equality relation on arguments is tricky.
+
+The simplest case of pure functions are those in which results
+are only certainly @code{eq?} if all of the arguments are.
+
+@c @twerpdoc (pure-funcq)
+@c ../../ice-9/poe.doc
+@deffn {Scheme Procedure} pure-funcq base
+Return a procedure @var{pf} that wraps procedure @var{base}, associating
+the arg list of each call to @var{pf} to its return value in a globally
+shared (but bounded nonetheless) table.
+@end deffn
+@c @twerpdoc (perfect-funcq)
+@c ../../ice-9/poe.doc
+@deffn {Scheme Procedure} perfect-funcq size base
+Return a procedure @var{pf} that wraps procedure @var{base}, associating
+the arg list of each call to @var{pf} to its return value in a private
+table of roughly @var{size} elements.  Thus: ``A pure funq may sometimes
+forget its past but a perfect funcq never does.''
+@end deffn
+
+@c poe.texi ends here
diff --git a/doc/ref/popen.texi b/doc/ref/popen.texi
new file mode 100644
index 0000000..3203d88
--- /dev/null
+++ b/doc/ref/popen.texi
@@ -0,0 +1,54 @@
+@c popen.texi
+
+@c Copyright (C) 2012 Free Software Foundation, Inc.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+@c copy of the license is included in the section entitled ``GNU Free
+@c Documentation License.''
+
+@node Alternate Pipes
+@section Alternate Pipes
+
+The following procedures provide an interface to the @code{popen} and
+@code{pclose} system routines.  The code is in a separate "popen"
+module:
+
+@smalllisp
+(use-modules (ice-9 popen))
+@end smalllisp
+
+@findex popen
+@c @twerpdoc (open-pipe)
+@c ../../ice-9/popen.doc
+@deffn {Scheme Procedure} open-pipe command mode
+Execute the shell command @var{command} (a string) in a subprocess.
+A pipe to the process is created and returned.  @var{modes} specifies
+whether an input or output pipe to the process is created: it should
+be the value of @code{OPEN_READ} or @code{OPEN_WRITE}.
+@end deffn
+
+@c @twerpdoc (open-input-pipe)
+@c ../../ice-9/popen.doc
+@deffn {Scheme Procedure} open-input-pipe command
+Equivalent to @code{open-pipe} with mode @code{OPEN_READ}.
+@end deffn
+
+@c @twerpdoc (open-output-pipe)
+@c ../../ice-9/popen.doc
+@deffn {Scheme Procedure} open-output-pipe command
+Equivalent to @code{open-pipe} with mode @code{OPEN_WRITE}.
+@end deffn
+
+@findex pclose
+@c @twerpdoc (close-pipe)
+@c ../../ice-9/popen.doc
+@deffn {Scheme Procedure} close-pipe p
+Close the pipe created by @code{open-pipe}, wait for the process
+to terminate, and return its status value.  @xref{Processes, waitpid},
+for information on how to interpret this value.
+@end deffn
+
+@c popen.texi ends here
diff --git a/doc/ref/runq.texi b/doc/ref/runq.texi
new file mode 100644
index 0000000..f66e2c4
--- /dev/null
+++ b/doc/ref/runq.texi
@@ -0,0 +1,137 @@
+@c runq.texi
+
+@c Copyright (C) 2012 Free Software Foundation, Inc.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+@c copy of the license is included in the section entitled ``GNU Free
+@c Documentation License.''
+
+@node Run Queues
+@section Run Queues
+
+To use a special kind of queue (@pxref{Queues}) for scheduling parallel
+computations, evaluate the form:
+
+@smalllisp
+(use-modules (ice-9 runq))
+@end smalllisp
+
+@c @twerpcommentary (verbatim (ice-9 runq))
+@verbatim
+One way to schedule parallel computations in a serial environment is
+to explicitly divide each task up into small, finite execution time,
+strips.  Then you interleave the execution of strips from various
+tasks to achieve a kind of parallelism.  Runqs are a handy data
+structure for this style of programming.
+
+We use thunks (nullary procedures) and lists of thunks to represent
+strips.  By convention, the return value of a strip-thunk must either
+be another strip or the value #f.
+
+A runq is a procedure that manages a queue of strips.  Called with no
+arguments, it processes one strip from the queue.  Called with
+arguments, the arguments form a control message for the queue.  The
+first argument is a symbol which is the message selector.
+
+A strip is processed this way: If the strip is a thunk, the thunk is
+called -- if it returns a strip, that strip is added back to the
+queue.  To process a strip which is a list of thunks, the CAR of that
+list is called.  After a call to that CAR, there are 0, 1, or 2 strips
+-- perhaps one returned by the thunk, and perhaps the CDR of the
+original strip if that strip has 2+ elements.  The runq puts whichever
+of these strips exist back on the queue.  (The exact order in which
+strips are put back on the queue determines the scheduling behavior of
+a particular queue -- it's a parameter.)
+@end verbatim
+
+@c @twerpdoc (runq-control)
+@c ../../ice-9/runq.doc
+@deffn {Scheme Procedure} runq-control q msg [args...]
+For runq @var{q}, process in the default way the control
+message @var{msg} (a symbol) and its @var{args}.  These
+messages are recognized:
+
+@table @code
+@item add!
+@itemx enqueue!
+Enqueue @var{args} as strips.
+
+@item push!
+Add @var{args} as strips to the front of the queue.
+
+@item empty?
+Return #t iff the runq is empty.
+
+@item length
+Return the number of strips in the runq.
+
+@item kill!
+Empty the runq.
+@end table
+
+Signal error for any other message, with key @code{not-understood}
+and two arguments @var{msg} and @var{args}.
+@end deffn
+@c @twerpdoc (make-void-runq)
+@c ../../ice-9/runq.doc
+@deffn {Scheme Procedure} make-void-runq
+Return a runq that discards all messages except @code{length},
+for which it returns 0.
+@end deffn
+@c @twerpdoc (make-fair-runq)
+@c ../../ice-9/runq.doc
+@deffn {Scheme Procedure} make-fair-runq
+Return a runq procedure.
+Called with no arguments, the procedure processes one strip from the queue.
+Called with arguments, it uses @code{runq-control}.
+
+In a fair runq, if a strip returns a new strip @code{X}, that is added
+to the end of the queue, meaning it will be the last to execute
+of all the remaining strips.
+@end deffn
+@c @twerpdoc (make-exclusive-runq)
+@c ../../ice-9/runq.doc
+@deffn {Scheme Procedure} make-exclusive-runq
+Return a runq procedure.
+Called with no arguments, the procedure processes one strip from the queue.
+Called with arguments, it uses @code{runq-control}.
+
+In an exclusive runq, if a strip @code{W} returns a new strip @code{X},
+@code{X} is added to the front of the queue, meaning it will be the next to
+execute of all the remaining procedures.
+
+An exception to this occurs if @code{W} was the @sc{car} of a list of
+strips.  In that case, after @code{X} is pushed onto the front of the
+queue, the @sc{cdr} of the list of strips is pushed in front of that (if
+the @sc{cdr} is not empty).  This way, the rest of the thunks in the list
+that contained @code{W} have priority over @code{X}.
+@end deffn
+@c @twerpdoc (make-subordinate-runq-to)
+@c ../../ice-9/runq.doc
+@deffn {Scheme Procedure} make-subordinate-runq-to superior basic-inferior
+Return a runq proxy for the runq @var{basic-inferior}.
+
+The proxy watches for operations on @var{basic-inferior} that cause
+a transition from a queue length of 0 to a non-zero length and
+vice versa.   While @var{basic-inferior} is not empty,
+the proxy installs a task on the @var{superior} runq.  Each strip
+of that task processes @code{N} strips from @var{basic-inferior} where
+@code{N} is the length of @var{basic-inferior} when the proxy
+strip is entered.  [Countless scheduling variations are possible.]
+@end deffn
+@c @twerpdoc (strip-sequence)
+@c ../../ice-9/runq.doc
+@deffn {Scheme Procedure} strip-sequence [strips...]
+Return a new strip which is the concatenation of @var{strips}.
+@end deffn
+@c @twerpdoc (fair-strip-subtask)
+@c ../../ice-9/runq.doc
+@deffn {Scheme Procedure} fair-strip-subtask [initial-strips...]
+Return a new strip which is the synchronous, fair,
+parallel execution of the @var{initial-strips}.
+@end deffn
+
+@c runq.texi ends here
diff --git a/doc/ref/session.texi b/doc/ref/session.texi
new file mode 100644
index 0000000..d59e790
--- /dev/null
+++ b/doc/ref/session.texi
@@ -0,0 +1,113 @@
+@c session.texi
+
+@c Copyright (C) 2012 Free Software Foundation, Inc.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+@c copy of the license is included in the section entitled ``GNU Free
+@c Documentation License.''
+
+@node Preloaded Modules for Interactive Sessions
+@section Preloaded Modules for Interactive Sessions
+
+For convenience, several modules pre-loaded for interactive sessions
+(@pxref{Running Guile Interactively}).  Primarily, the module @code{(ice-9
+session)} provides procedures to extend @code{%load-path}, access
+documentation, search for symbol names, etc., useful for exploration.
+Other modules are not documented at this time.
+
+Because these modules are preloaded, you do not need to do anything
+special to use them during an interactive session.  For scripts,
+however, you can load them explicitly with the expression:
+
+@smalllisp
+(use-modules (ice-9 session))
+@end smalllisp
+
+The rest of this section describes the procedures and macros available
+by loading module @code{(ice-9 sesssion)}.
+
+@c @twerpdoc (add-to-load-path!)
+@c ../../ice-9/session.doc
+@deffn {Scheme Procedure} add-to-load-path! directory [append?]
+Add @var{directory} to @code{%load-path}, if it is not already there.
+Add at the beginning, unless optional arg @var{append?} is non-#f.
+@end deffn
+@c @twerpdoc (set-fancy-repl-prompt!)
+@c ../../ice-9/session.doc
+@deffn {Scheme Procedure} set-fancy-repl-prompt! format-string
+Set the repl prompt based on @var{format-string}.
+Each character in @var{format-string} stands for itself,
+with the exception of the following tilde escapes:
+
+@table @code
+@item ~M
+Stands for the ``current module''.
+@end table
+@end deffn
+
+@c FIXME: guile-tools read-scheme-source does not grok `procedure->syntax'.
+@deffn {Scheme Macro} help [args...]
+Display various forms of help depending on @var{args}, or a
+detailed description of @code{help} usage if given no args.
+@end deffn
+
+@c @twerpdoc (apropos)
+@c ../../ice-9/session.doc
+@deffn {Scheme Procedure} apropos rgx [options...]
+Search for bindings matching @var{rgx}, a regular expression string.
+@var{options} are symbols: @code{full}, @code{shadow}, @code{value}.
+@end deffn
+@c @twerpdoc (apropos-internal)
+@c ../../ice-9/session.doc
+@deffn {Scheme Procedure} apropos-internal rgx
+Return a list of accessible variable names for @var{rgx}.
+@end deffn
+@c @twerpdoc (apropos-fold)
+@c ../../ice-9/session.doc
+@deffn {Scheme Procedure} apropos-fold proc init rgx folder
+Fold PROCEDURE over bindings matching third arg REGEXP.
+
+Result is
+
+@example
+  (PROCEDURE MODULE1 NAME1 VALUE1
+    (PROCEDURE MODULE2 NAME2 VALUE2
+      ...
+      (PROCEDURE MODULEn NAMEn VALUEn INIT)))
+@end example
+
+where INIT is the second arg to `apropos-fold'.
+
+Fourth arg FOLDER is one of
+
+@example
+  (apropos-fold-accessible MODULE) ;fold over bindings accessible in MODULE
+  apropos-fold-exported            ;fold over all exported bindings
+  apropos-fold-all                 ;fold over all bindings
+@end example
+@end deffn
+@c @twerpdoc (apropos-fold-accessible)
+@c ../../ice-9/session.doc
+@deffn {Scheme Procedure} apropos-fold-accessible module
+FIXME: Docs incomplete.
+@end deffn
+@c + @twerpdoc (apropos-fold-exported)
+@c + @twerpdoc (apropos-fold-all)
+@c @twerpdoc (source)
+@c ../../ice-9/session.doc
+@deffn {Scheme Procedure} source obj
+Return the source code for @var{obj}, a procedure or macro.
+The source code is an acyclic structured expression (tree of symbols, etc).
+If @var{obj} does not have source code associated with it, return #f.
+@end deffn
+@c @twerpdoc (arity)
+@c ../../ice-9/session.doc
+@deffn {Scheme Procedure} arity proc
+Display the arity of procedure @var{proc}.
+@end deffn
+@c + @twerpdoc (system-module)
+
+@c session.texi ends here
diff --git a/doc/ref/stack-catch.texi b/doc/ref/stack-catch.texi
new file mode 100644
index 0000000..196268c
--- /dev/null
+++ b/doc/ref/stack-catch.texi
@@ -0,0 +1,135 @@
+@c stack-catch.texi
+
+@c Copyright (C) 2012 Free Software Foundation, Inc.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+@c copy of the license is included in the section entitled ``GNU Free
+@c Documentation License.''
+
+@node Lazy Catch
+@section Catch Without Unwinding
+
+A @dfn{lazy catch} is used in the same way as a normal @code{catch},
+with @var{key}, @var{thunk} and @var{handler} arguments specifying the
+exception type, normal case code and handler procedure, but differs in
+one important respect: the handler procedure is executed without
+unwinding the call stack from the context of the @code{throw} expression
+that caused the handler to be invoked.
+
+@c @twerpdoc (lazy-catch (C scm_lazy_catch))
+@c ../../libguile/throw.doc
+@deffn {Scheme Procedure} lazy-catch tag thunk handler
+@deffnx {C Function} scm_lazy_catch (tag, thunk, handler)
+Behave like @code{catch}, except that the stack is
+not unwound before invoking @var{handler}.
+The @var{handler} procedure is not allowed to return;
+it must throw to another catch, or otherwise exit non-locally.
+@end deffn
+
+Typically, @var{handler} should save any desired state associated with
+the stack at the point where the corresponding @code{throw} occurred,
+and then throw an exception itself --- usually the same exception as the
+one it caught.  If @var{handler} is invoked and does @emph{not} throw an
+exception, Guile itself throws an exception with key @code{misc-error}.
+
+Not unwinding the stack means that throwing an exception that is caught
+by a @code{lazy-catch} is @emph{almost} equivalent to calling the
+@code{lazy-catch}'s handler inline instead of each @code{throw}, and
+then omitting the surrounding @code{lazy-catch}.  In other words,
+
+@lisp
+(lazy-catch 'key
+  (lambda () @dots{} (throw 'key args @dots{}) @dots{})
+  handler)
+@end lisp
+
+@noindent
+is @emph{almost} equivalent to
+
+@lisp
+((lambda () @dots{} (handler 'key args @dots{}) @dots{}))
+@end lisp
+
+@noindent
+But why only @emph{almost}?  The difference is that with
+@code{lazy-catch} (as with normal @code{catch}), the dynamic context is
+unwound back to just outside the @code{lazy-catch} expression before
+invoking the handler.  (For an introduction to what is meant by dynamic
+context, @xref{Dynamic Wind}.)
+
+Then, when the handler @emph{itself} throws an exception, that exception
+must be caught by some kind of @code{catch} (including perhaps another
+@code{lazy-catch}) higher up the call stack.
+
+The dynamic context also includes @code{with-fluids} blocks @xref{Fluids
+and Dynamic States}, so the effect of unwinding the dynamic context can
+also be seen in fluid variable values.  This is illustrated by the
+following code, in which the normal case thunk uses @code{with-fluids}
+to temporarily change the value of a fluid:
+
+@lisp
+(define f (make-fluid))
+(fluid-set! f "top level value")
+
+(define (handler . args)
+  (cons (fluid-ref f) args))
+
+(lazy-catch 'foo
+            (lambda ()
+              (with-fluids ((f "local value"))
+                (throw 'foo)))
+            handler)
+@result{} ("top level value" foo)
+
+((lambda ()
+   (with-fluids ((f "local value"))
+     (handler 'foo))))
+@result{} ("local value" foo)
+@end lisp
+
+@noindent
+In the @code{lazy-catch} version, the unwinding of dynamic context
+restores @code{f} to its value outside the @code{with-fluids} block
+before the handler is invoked, so the handler's @code{(fluid-ref f)}
+returns the external value.
+
+@code{lazy-catch} is useful because it permits the implementation of
+debuggers and other reflective programming tools that need to access the
+state of the call stack at the exact point where an exception or an
+error is thrown.  For an example of this, see @code{stack-catch} below,
+available after evaluating the form:
+
+@lisp
+(use-modules (ice-9 stack-catch))
+@end lisp
+
+@c @twerpdoc (stack-catch)
+@c ../../ice-9/stack-catch.doc
+@deffn {Scheme Procedure} stack-catch key thunk handler
+Like @code{catch}, invoke @var{thunk} in the dynamic context of
+@var{handler} for exceptions matching @var{key}, but also save the
+current stack state in the @code{the-last-stack} fluid, for the purpose
+of debugging or re-throwing of an error.  If thunk throws to the
+symbol @var{key}, then @var{handler} is invoked this way:
+
+@example
+(handler key args ...)
+@end example
+
+@var{key} is a symbol or #t.
+
+@var{thunk} takes no arguments.  If @var{thunk} returns normally, that
+is the return value of @code{catch}.
+
+Handler is invoked outside the scope of its own @code{catch}.  If
+@var{handler} again throws to the same key, a new handler from further
+up the call chain is invoked.
+
+If the key is @code{#t}, then a throw to @emph{any} symbol will match
+this call to @code{catch}."
+@end deffn
+
+@c stack-catch.texi ends here
diff --git a/doc/ref/threads.texi b/doc/ref/threads.texi
new file mode 100644
index 0000000..f225239
--- /dev/null
+++ b/doc/ref/threads.texi
@@ -0,0 +1,71 @@
+@c threads.texi
+
+@c Copyright (C) 2012 Free Software Foundation, Inc.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+@c copy of the license is included in the section entitled ``GNU Free
+@c Documentation License.''
+
+@node Higher level thread procedures
+@section Higher level thread procedures
+
+Higher level thread procedures are available by evaluating:
+
+@smalllisp
+(use-modules (ice-9 threads))
+@end smalllisp
+
+The following procedures and macros provide standardized
+thread creation and mutex interaction.
+
+@c @twerpdoc (%thread-handler)
+@c ../../ice-9/threads.doc
+@deffn {Scheme Procedure} %thread-handler tag [args...]
+This procedure is specified as the standard error-handler for
+@code{make-thread} and @code{begin-thread}.  If the number of @var{args}
+is three or more, use @code{display-error}, otherwise display a message
+"uncaught throw to @var{tag}".  All output is sent to the port specified
+by @code{current-error-port}.
+
+Before display, global var @code{the-last-stack} is set to @code{#f}
+and signals are unmasked with @code{unmask-signals}.
+
+@c [FIXME: Why distinguish based on number of args?!  Cue voodoo music here.]
+@end deffn
+
+@c @twerpmacdoc (make-thread)
+@c ../../ice-9/threads.doc
+@deffn {Scheme Macro} make-thread proc [args...]
+Apply @var{proc} to @var{args} in a new thread formed by
+@code{call-with-new-thread} using @code{%thread-handler} as the error
+handler.
+@end deffn
+
+@c @twerpmacdoc (begin-thread)
+@c ../../ice-9/threads.doc
+@deffn {Scheme Macro} begin-thread first [rest...]
+Evaluate forms @var{first} and @var{rest} in a new thread formed by
+@code{call-with-new-thread} using @code{%thread-handler} as the error
+handler.
+@end deffn
+
+@c @twerpmacdoc (with-mutex)
+@c ../../ice-9/threads.doc
+@deffn {Scheme Macro} with-mutex m [body...]
+Lock mutex @var{m}, evaluate @var{body}, and then unlock @var{m}.
+These sub-operations form the branches of a @code{dynamic-wind}.
+@end deffn
+
+@c @twerpmacdoc (monitor)
+@c ../../ice-9/threads.doc
+@deffn {Scheme Macro} monitor first [rest...]
+Evaluate forms @var{first} and @var{rest} under a newly created
+anonymous mutex, using @code{with-mutex}.
+
+@c [FIXME: Is there any way to access the mutex?]
+@end deffn
+
+@c threads.texi ends here
-- 
1.7.6


[-- Attachment #4: 0003-Documentation-style-change.patch --]
[-- Type: application/octet-stream, Size: 1289 bytes --]

From 4b5ef148edee64d8083173f2f34e4c37e9eac8d4 Mon Sep 17 00:00:00 2001
From: Noah Lavine <noah.b.lavine@gmail.com>
Date: Tue, 10 Jul 2012 21:01:25 -0400
Subject: [PATCH 3/4] Documentation style change

 * doc/ref/hcons.texi: change section name.
---
 doc/ref/hcons.texi |   21 ++++++++-------------
 1 files changed, 8 insertions(+), 13 deletions(-)

diff --git a/doc/ref/hcons.texi b/doc/ref/hcons.texi
index 1fc3613..273a871 100644
--- a/doc/ref/hcons.texi
+++ b/doc/ref/hcons.texi
@@ -9,24 +9,19 @@
 @c copy of the license is included in the section entitled ``GNU Free
 @c Documentation License.''
 
-@node Double-Key Hash Tables
-@section Double-Key Hash Tables
-
-To use double-key hash tables, evaluate the form:
-
-@smalllisp
-(use-modules (ice-9 hcons))
-@end smalllisp
-
-@c @twerpcommentary (verbatim (ice-9 hcons))
-@c @verbatim
-Eq? hash-consing
+@node Eq? Hash Consing
+@section Eq? Hash Consing
 
 A hash conser maintains a private universe of pairs s.t. if
 two cons calls pass eq? arguments, the pairs returned are eq?.
 
 A hash conser does not contribute life to the pairs it returns.
-@c @end verbatim
+
+To use eq?-hash consers, evaluate
+
+@smalllisp
+(use-modules (ice-9 hcons))
+@end smalllisp
 
 @c @twerpdoc (hashq-cons-hash)
 @c ../../ice-9/hcons.doc
-- 
1.7.6


[-- Attachment #5: 0004-Document-ice-9-string-fun.patch --]
[-- Type: application/octet-stream, Size: 5519 bytes --]

From 2e1835d9df5ca93981471fc848001dab0cb9d5a6 Mon Sep 17 00:00:00 2001
From: Noah Lavine <noah.b.lavine@gmail.com>
Date: Tue, 10 Jul 2012 21:02:15 -0400
Subject: [PATCH 4/4] Document (ice-9 string-fun)

 * doc/ref/string-fun.texi: add documentation.
 * doc/ref/Makefile.am: update Makefile.

Based on documentation contributed by Thien-Thi Nguyen.
---
 doc/ref/Makefile.am     |    1 +
 doc/ref/string-fun.texi |  139 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 140 insertions(+), 0 deletions(-)
 create mode 100644 doc/ref/string-fun.texi

diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am
index f86a831..5524ab6 100644
--- a/doc/ref/Makefile.am
+++ b/doc/ref/Makefile.am
@@ -71,6 +71,7 @@ guile_TEXINFOS = preface.texi			\
 		 poe.texi			\
 		 popen.texi			\
 		 runq.texi			\
+		 string-fun.texi		\
 		 session.texi			\
 		 stack-catch.texi		\
 		 threads.texi			\
diff --git a/doc/ref/string-fun.texi b/doc/ref/string-fun.texi
new file mode 100644
index 0000000..9a70738
--- /dev/null
+++ b/doc/ref/string-fun.texi
@@ -0,0 +1,139 @@
+@c string-fun.texi
+
+@c Copyright (C) 2012 Free Software Foundation, Inc.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+@c copy of the license is included in the section entitled ``GNU Free
+@c Documentation License.''
+
+@node String Utilities
+@section String Utilities
+@cindex string utilities
+@cindex strings
+
+Guile provides a convenient set of procedures that take advantage of the
+shared substring capability.  These are available by evaluating:
+
+@lisp
+(use-modules (ice-9 string-fun))
+@end lisp
+
+@c @twerpcommentary (verbatim (ice-9 string-fun))
+
+This module provides the following procedures:
+
+@verbatim
+ (split-after-char char str ret)
+ (split-before-char char str ret)
+ (split-discarding-char char str ret)
+ (split-after-char-last char str ret)
+ (split-before-char-last char str ret)
+ (split-discarding-char-last char str ret)
+ (split-before-predicate pred str ret)
+ (split-after-predicate pred str ret)
+ (split-discarding-predicate pred str ret)
+ (separate-fields-discarding-char ch str ret)
+ (separate-fields-after-char ch str ret)
+ (separate-fields-before-char ch str ret)
+ ((string-prefix-predicate pred?) prefix str)
+ (string-prefix=? prefix str)
+ (sans-surrounding-whitespace s)
+ (sans-trailing-whitespace s)
+ (sans-leading-whitespace s)
+ (sans-final-newline str)
+ (has-trailing-newline? str)
+@end verbatim
+
+@subsection Dividing Strings Into Fields
+
+The names of these functions are very regular.
+Here is a grammar of a call to one of these:
+
+@verbatim
+  <string-function-invocation>
+  := (<action>-<seperator-disposition>-<seperator-determination>
+               <seperator-param> <str> <ret>)
+
+<str>    = the string
+
+<ret>    = The continuation.  String functions generally return
+           multiple values by passing them to this procedure.
+
+<action> =    split
+            | separate-fields
+
+ "split" means to divide a string into two parts.
+ <ret> will be called with two arguments.
+
+ "separate-fields" means to divide a string into as many parts as
+ possible.  <ret> will be called with however many fields are found.
+
+<seperator-disposition> =      before
+                             | after
+                             | discarding
+
+ "before" means to leave the seperator attached to
+ the beginning of the field to its right.
+
+ "after" means to leave the seperator attached to
+ the end of the field to its left.
+
+ "discarding" means to discard seperators.
+
+ Other dispositions might be handy.  For example, "isolate"
+ could mean to treat the separator as a field unto itself.
+
+<seperator-determination> =    char
+                             | predicate
+
+ "char" means to use a particular character as field seperator.
+ "predicate" means to check each character using a particular predicate.
+
+ Other determinations might be handy.  For example, "character-set-member".
+
+<seperator-param> = A parameter that completes the meaning of the
+                    determinations.  For example, if the determination
+                    is "char", then this parameter says which character.
+                    If it is "predicate", the parameter is the predicate.
+
+For example:
+
+ (separate-fields-discarding-char #\, "foo, bar, baz, , bat" list)
+ => ("foo" " bar" " baz" " " " bat")
+
+ (split-after-char #\- 'an-example-of-split list)
+ => ("an-" "example-of-split")
+@end verbatim
+
+As an alternative to using a determination "predicate", or to trying to
+do anything complicated with these functions, consider using regular
+expressions.
+
+
+@subsection String Prefix Predicates
+
+Very simple:
+
+@lisp
+(define-public ((string-prefix-predicate pred?) prefix str)
+ (and (<= (string-length prefix) (string-length str))
+       (pred? prefix (make-shared-substring str 0 (string-length prefix)))))
+
+(define-public string-prefix=? (string-prefix-predicate string=?))
+@end lisp
+
+@subsection Strippers
+
+@verbatim
+<stripper> = sans-<removable-part>
+
+<removable-part> =     surrounding-whitespace
+                     | trailing-whitespace
+                     | leading-whitespace
+                     | final-newline
+@end verbatim
+
+@c string-fun.texi ends here
-- 
1.7.6