Do you recognize these modules?

Do you recognize these modules?

[Noah Lavine]

Hello all,

I was inspired by a recent post about (ice-9 occam-channel) to take a
look and see what modules don't have documentation. I've only looked
at the (ice-9 ...) modules so far, but there are a lot of them. (I
checked for documentation by going to the top-level info node for
Guile documentation in Emacs and searching the manual for any mention
of the module.)

I am happy to add documentation for some of these modules, but I'd
like to ask first to see if anyone on this list knows what they do. I
think this is also the time to ask if we want to remove some of these
modules instead of documenting them (especially (ice-9 lineio)). One
nice thing I learned in this project is that Guile has a lot of cool
data structures and algorithms built in. I think it would be great if
they were discoverable too.

Here are some notes I made as I went through ice-9/*.scm. Does anyone
know anything about these modules?

(ice-9 and-let-star) not documented (but also available as srfi-2?)

(ice-9 binary-ports) not really documented except by brief mention
under "R6RS I/O Ports"

(ice-9 calling) not documented at all.

(ice-9 channel) not documented at all.

(ice-9 command-line) not documented at all.

(ice-9 common-list) not documented at all.

(ice-9 control): shift* and reset* need documentation.

(ice-9 documentation) not documented at all.

(ice-9 expect): all but expect and expect-strings need documentation.

(ice-9 gap-buffer) not documented at all. is this module related to
Elisp support?

(ice-9 hcons) not documented at all.

(ice-9 lineio) not documented at all. but a comment in that module
says that it should be removed eventually. maybe the time is now?

(ice-9 list) not documented at all.

(ice-9 ls) not documented at all.

(ice-9 mapping) not documented at all.

(ice-9 match): everything except match needs documentation.

(ice-9 null) not documented at all. but maybe it's not supposed to be.

(ice-9 occam-channel) not documented at all.

(ice-9 poe) not documented at all.

(ice-9 poll) not documented at all.

(ice-9 popen): port/pid-table needs documentation.

(ice-9 runq): not documented at all.

(ice-9 safe-r5rs): not documented at all.

(ice-9 safe): not documented at all.

(ice-9 save-stack): not documented at all.

(ice-9 scm-style-repl): not documented at all.

(ice-9 serialize): not documented at all.

(ice-9 session): not documented at all.

(ice-9 stack-catch): not documented at all.

(ice-9 string-fun): not documented at all.

(ice-9 threads): the *par* procedures need documentation.

(ice-9 time): not documented at all.

(ice-9 top-repl): not documented at all.

(ice-9 weak-vector): not documented at all.

Thanks,
Noah

Re: Do you recognize these modules?

[Thien-Thi Nguyen]

() Noah Lavine <noah.b.lavine@gmail.com>
() Tue, 1 May 2012 18:26:28 -0400

   Does anyone know anything about these modules?

Some of these modules are in Guile 1.4.x, and thus documented.
See <http://www.gnuvola.org/software/guile/doc/>, specifically
the module index, and the parent dir for source.

Re: Do you recognize these modules?

[Noah Lavine]

Thanks a lot! I will definitely look at that.

Unfortunately, it looks like the changes for these do not have
copyright assigned to the FSF, so we can't use them directly. Is that
correct?

Also, I hope this isn't a sensitive topic, but why is there a
semi-friendly fork of Guile 1.4? Are there things that you want to
accomplish that Guile 2.0 can't do? Or maybe you want complete
compatibility with Guile 1.4 - even so, why fork?

Thanks,
Noah

On Tue, May 1, 2012 at 7:22 PM, Thien-Thi Nguyen <ttn@gnuvola.org> wrote:
> () Noah Lavine <noah.b.lavine@gmail.com>
> () Tue, 1 May 2012 18:26:28 -0400
>
>   Does anyone know anything about these modules?
>
> Some of these modules are in Guile 1.4.x, and thus documented.
> See <http://www.gnuvola.org/software/guile/doc/>, specifically
> the module index, and the parent dir for source.

Re: Do you recognize these modules?

[Thien-Thi Nguyen]

() Noah Lavine <noah.b.lavine@gmail.com>
() Wed, 2 May 2012 11:26:22 -0400

   Unfortunately, it looks like the changes for these do not have
   copyright assigned to the FSF, so we can't use them directly.
   Is that correct?

Partially (details below).

   Also, I hope this isn't a sensitive topic, but why is there a
   semi-friendly fork of Guile 1.4? Are there things that you want
   to accomplish that Guile 2.0 can't do? Or maybe you want
   complete compatibility with Guile 1.4 - even so, why fork?

It's not sensitive, but it's not a short answer, either...

[maudlin recollections snipped -- i will publish these separately.]

The short answer is that the fork (from 2001 or so) was a reaction
to losing repo write privs.  Now that i have regained them, i am
interested in merging back the relevant bits, w/ copyright notice
modified to the proper FSF standards.  Details up to you...

I see from another post you have decided to rewrite, due to my
delayed response.  Sorry about that.  I anticipate my ability to
keep up in the foreseeable future to be likewise limited, so if
you're still interested, please let me know what i must do to get
these bits in-tree and useful to you (and others) as a basis for
further maintenance (kind of a one-shot mass-transfer).

Thanks for taking care of 1.8, btw -- i am sure i'm not alone in
appreciating this work.

Re: Do you recognize these modules?

[Noah Lavine]

Hello,

> The short answer is that the fork (from 2001 or so) was a reaction
> to losing repo write privs.  Now that i have regained them, i am
> interested in merging back the relevant bits, w/ copyright notice
> modified to the proper FSF standards.  Details up to you...

That sounds great to me!

> I see from another post you have decided to rewrite, due to my
> delayed response.  Sorry about that.  I anticipate my ability to
> keep up in the foreseeable future to be likewise limited, so if
> you're still interested, please let me know what i must do to get
> these bits in-tree and useful to you (and others) as a basis for
> further maintenance (kind of a one-shot mass-transfer).

Luckily, I haven't actually started the rewrite, because I also have
limited time to work on this. So I'm very glad to hear that you're
interested in transfering them. If you are the only author of the
pieces, then I think the transfer is simple - you put the FSF
copyright notice at the top, and you're done. (Assuming the code works
correctly on Guile 2.0. But the best way to check that is by running
tests.) But Andy and Ludo are the real authorities on this.

> Thanks for taking care of 1.8, btw -- i am sure i'm not alone in
> appreciating this work.

I'm happy to.

Thanks a lot,
Noah

Re: Do you recognize these modules?

[David Kastrup]

Noah Lavine <noah.b.lavine@gmail.com> writes:

> Hello,
>
>> The short answer is that the fork (from 2001 or so) was a reaction
>> to losing repo write privs.  Now that i have regained them, i am
>> interested in merging back the relevant bits, w/ copyright notice
>> modified to the proper FSF standards.  Details up to you...
>
> That sounds great to me!
>
>> I see from another post you have decided to rewrite, due to my
>> delayed response.  Sorry about that.  I anticipate my ability to
>> keep up in the foreseeable future to be likewise limited, so if
>> you're still interested, please let me know what i must do to get
>> these bits in-tree and useful to you (and others) as a basis for
>> further maintenance (kind of a one-shot mass-transfer).
>
> Luckily, I haven't actually started the rewrite, because I also have
> limited time to work on this. So I'm very glad to hear that you're
> interested in transfering them. If you are the only author of the
> pieces, then I think the transfer is simple - you put the FSF
> copyright notice at the top, and you're done.

Uh no.  You can't just assign copyright to somebody without asking them,
much like you can't just assign parentship to somebody without asking
them.

Since Thien-Thi Nguyen assigned copyright to GOOPS and general changes
to future changes to GUILE to the FSF in 2000 already, it is more or
less a matter of him checking in the changes or otherwise contributing
them in a manner making clear that the contribution is intentional.
Matching copyright headers are obviously a good indicator for that.

-- 
David Kastrup

Re: Do you recognize these modules?

[Noah Lavine]

>> Luckily, I haven't actually started the rewrite, because I also have
>> limited time to work on this. So I'm very glad to hear that you're
>> interested in transfering them. If you are the only author of the
>> pieces, then I think the transfer is simple - you put the FSF
>> copyright notice at the top, and you're done.
>
> Uh no.  You can't just assign copyright to somebody without asking them,
> much like you can't just assign parentship to somebody without asking
> them.

Yes, this was specific to this situation, because I thought that he
had already signed a copyright assignment form. I don't mean this as a
general statement of when you can make changes to Guile.

> Since Thien-Thi Nguyen assigned copyright to GOOPS and general changes
> to future changes to GUILE to the FSF in 2000 already, it is more or
> less a matter of him checking in the changes or otherwise contributing
> them in a manner making clear that the contribution is intentional.
> Matching copyright headers are obviously a good indicator for that.

Ah, so he would have to either check them in himself or send them as
patches to the list, correct? (In addition to the assignment.)

Noah

Re: Do you recognize these modules?

[David Kastrup]

Noah Lavine <noah.b.lavine@gmail.com> writes:

>>> Luckily, I haven't actually started the rewrite, because I also have
>>> limited time to work on this. So I'm very glad to hear that you're
>>> interested in transfering them. If you are the only author of the
>>> pieces, then I think the transfer is simple - you put the FSF
>>> copyright notice at the top, and you're done.
>>
>> Uh no.  You can't just assign copyright to somebody without asking them,
>> much like you can't just assign parentship to somebody without asking
>> them.
>
> Yes, this was specific to this situation, because I thought that he
> had already signed a copyright assignment form. I don't mean this as a
> general statement of when you can make changes to Guile.
>
>> Since Thien-Thi Nguyen assigned copyright to GOOPS and general changes
>> to future changes to GUILE to the FSF in 2000 already, it is more or
>> less a matter of him checking in the changes or otherwise contributing
>> them in a manner making clear that the contribution is intentional.
>> Matching copyright headers are obviously a good indicator for that.
>
> Ah, so he would have to either check them in himself or send them as
> patches to the list, correct? (In addition to the assignment.)

The assignment is the formal part.  The rest is just a matter of making
sure that "but I never intended you to take _that_" does not come up.
So it is always safer if a contributor _gives_ stuff himself (or
designates them) rather than if someone else _takes_ it from him on the
assumption that this was intended to be taken.

Like if you have a contract for buying a horse.  If you take it from the
barn and later the owner says "You took the halter!  I did not sell the
halter!" that's a worse situation to be in rather than if he handed you
the horse including halter, even though the halter is not in the
contract.

Frankly, in the given situation I should be rather surprised if there
was potential for misunderstandings.  It does look like both the intent
to contribute as well as the compass of the contribution are quite
well-understood.

-- 
David Kastrup

Re: Do you recognize these modules?

[Ludovic Courtès]

Hi Thien-Thi,

It would be great if you could help with documenting these modules.

What do you think about copying the doc for these modules from 1.4 to
1.8/2.0?  Would you be willing to transfer copyright to the FSF for
that?

If Noah is OK to help with the actual transfer of the doc bits, then I
guess we’re almost all set.  :-)

Thanks,
Ludo’.

Re: Do you recognize these modules?

[Thien-Thi Nguyen]

() ludo@gnu.org (Ludovic Courtès)
() Mon, 14 May 2012 14:44:17 +0200

   What do you think about copying the doc for these modules from
   1.4 to 1.8/2.0?  Would you be willing to transfer copyright to
   the FSF for that?

Sure (see other reply to Noah).

   If Noah is OK to help with the actual transfer of the doc bits,
   then I guess we’re almost all set.  :-)

1.4 snarfs comments from .scm files for interpolation in template
files to create the final texinfo, but i'm almost certain you
don't need/want that flow, but would rather have the final
texinfo.  Is that correct?

Also, i can either add a file to branch_release-1-8 (exercising
my regained write privs :-D), or post it.  What's best?

Re: Do you recognize these modules?

[Noah Lavine]

Hello,

>   If Noah is OK to help with the actual transfer of the doc bits,
>   then I guess we’re almost all set.  :-)
>
> 1.4 snarfs comments from .scm files for interpolation in template
> files to create the final texinfo, but i'm almost certain you
> don't need/want that flow, but would rather have the final
> texinfo.  Is that correct?

That's probably true, but I am curious about how you do this - Guile
1.4 and earlier apparently have a different documentation-snarfing
format than Guile 1.6 and later. We just had a conversation about
moving away from ours because it doesn't lead to well-written texinfo
files, but maybe yours is more flexible.

Noah

Re: Do you recognize these modules?

[Andy Wingo]

Heya TTN,

Great to have your hack-power here.

On Mon 14 May 2012 19:00, Thien-Thi Nguyen <ttn@gnuvola.org> writes:

> Also, i can either add a file to branch_release-1-8 (exercising
> my regained write privs :-D), or post it.  What's best?

2.0 is the current stable branch, so any changes should go there first.
If it's a build fix or some other fix related to forward-compatibility
with 2.0, it can go on 1.8 as well.  We should avoid adding interfaces
to 1.8, though.

When in doubt, it's best (and much appreciated) to mail the list.  If no
one responds in a few days, go ahead and push it of course.

Does that sound sensible to you?

Cheers,

Andy
-- 
http://wingolog.org/

Re: Do you recognize these modules?

[Thien-Thi Nguyen]

() Andy Wingo <wingo@pobox.com>
() Tue, 15 May 2012 22:14:31 +0200

   2.0 is the current stable branch, so any changes should go
   there first.  If it's a build fix or some other fix related to
   forward-compatibility with 2.0, it can go on 1.8 as well.  We
   should avoid adding interfaces to 1.8, though.

   When in doubt, it's best (and much appreciated) to mail the list.
   If no one responds in a few days, go ahead and push it of course.

   Does that sound sensible to you?

Yes, thanks for explaining.

To avoid mishap (for this particular task), i've published a tarball:

  http://www.gnuvola.org/software/guile/doc-xfer-2012-05-25.tar.xz

It contains documentation for 17 ice-9 modules, plus some macros
(see README).  I hope it can be useful for Guile 1.8+ maintenance.

Re: Do you recognize these modules?

[Andy Wingo]

On Fri 25 May 2012 10:53, Thien-Thi Nguyen <ttn@gnuvola.org> writes:

>   http://www.gnuvola.org/software/guile/doc-xfer-2012-05-25.tar.xz
>
> It contains documentation for 17 ice-9 modules, plus some macros
> (see README).  I hope it can be useful for Guile 1.8+ maintenance.

Super!

You interested in submitting this as a patches to Guile?  If you are
familiar with git, you would just commit them, then use git-format-patch
to attach them to a mail.  It's the easiest way to get review :)

Regards,

Andy
-- 
http://wingolog.org/

Re: Do you recognize these modules?

[Thien-Thi Nguyen]

() 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.)

Re: Do you recognize these modules?

[Noah Lavine]

[-- 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

Re: Do you recognize these modules?

[Thien-Thi Nguyen]

() Noah Lavine <noah.b.lavine@gmail.com>
() Tue, 10 Jul 2012 23:02:29 -0400

   What do you think?

WRT style, the texi imported from 1.4 is littered w/
‘@twerpdoc’, ‘@twerpmacdoc’ and ‘@twerpcommentary’
comments.  IWBN to filter them before committing.

WRT content, IIRC 1.4.x (ice-9 calling) was re{designed,written}
so its documentation should not be imported w/o thorough review.
E.g., 1.4 has and 1.8 lacks ‘save-bindings-excursion’.  There are
probably various other skewings (mostly additions, one hopes) in
other modules, which need to be reconciled at some point, as well.
(Maybe you know all this and are planning to make these changes in
another patch set -- in that case, no worries, sorry for the noise!)

Re: Do you recognize these modules?

[Andy Wingo]

On Wed 11 Jul 2012 05:02, Noah Lavine <noah.b.lavine@gmail.com> writes:

> 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.

Cool.  I applied the first one.  When applying the rest, I got:

    /home/wingo/src/guile/doc/ref//lineio.texi:12: Prev reference to nonexistent node `Double-Key Hash Tables' (perhaps incorrect sectioning?).
    /home/wingo/src/guile/doc/ref//hcons.texi:12: `Eq? Hash Consing' has no Up field (perhaps incorrect sectioning?).
    /home/wingo/src/guile/doc/ref//gap-buffer.texi:12: Next reference to nonexistent node `Double-Key Hash Tables' (perhaps incorrect sectioning?).
    /home/wingo/src/guile/doc/ref//guile.texi:375: Menu reference to nonexistent node `Double-Key Hash Tables' (perhaps incorrect sectioning?).
    /home/wingo/src/guile/doc/ref//hcons.texi:12: warning: unreferenced node `Eq? Hash Consing'.
    makeinfo: Removing output file `guile.info' due to errors; use --force to preserve.
    make[4]: *** [guile.info] Error 1

As Thien-Thi suggests, it's probably good to filter out the
@twerpcommentary etcetera in your next patches.

Cheers,

Andy
-- 
http://wingolog.org/

Re: Do you recognize these modules?

[Noah Lavine]

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

Ooops, I think those errors are because I forgot to commit my changes
to guile.texi for patches 3 and 4. Here are updated versions. (I
believe the second patch from earlier should work.)

I will make another patch to clean out the @twerpcommentary lines.

Noah

On Wed, Jul 11, 2012 at 6:44 AM, Andy Wingo <wingo@pobox.com> wrote:
> On Wed 11 Jul 2012 05:02, Noah Lavine <noah.b.lavine@gmail.com> writes:
>
>> 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.
>
> Cool.  I applied the first one.  When applying the rest, I got:
>
>     /home/wingo/src/guile/doc/ref//lineio.texi:12: Prev reference to nonexistent node `Double-Key Hash Tables' (perhaps incorrect sectioning?).
>     /home/wingo/src/guile/doc/ref//hcons.texi:12: `Eq? Hash Consing' has no Up field (perhaps incorrect sectioning?).
>     /home/wingo/src/guile/doc/ref//gap-buffer.texi:12: Next reference to nonexistent node `Double-Key Hash Tables' (perhaps incorrect sectioning?).
>     /home/wingo/src/guile/doc/ref//guile.texi:375: Menu reference to nonexistent node `Double-Key Hash Tables' (perhaps incorrect sectioning?).
>     /home/wingo/src/guile/doc/ref//hcons.texi:12: warning: unreferenced node `Eq? Hash Consing'.
>     makeinfo: Removing output file `guile.info' due to errors; use --force to preserve.
>     make[4]: *** [guile.info] Error 1
>
> As Thien-Thi suggests, it's probably good to filter out the
> @twerpcommentary etcetera in your next patches.
>
> Cheers,
>
> Andy
> --
> http://wingolog.org/

[-- Attachment #2: 0001-Documentation-style-change.patch --]
[-- Type: application/octet-stream, Size: 2076 bytes --]

From 98344e7d0abe8fb5ebf12e25ee9b6736ba39e385 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 1/2] Documentation style change

 * doc/ref/hcons.texi: change section name.
 * doc/ref/guile.texi: update menu.
---
 doc/ref/guile.texi |    2 +-
 doc/ref/hcons.texi |   21 ++++++++-------------
 2 files changed, 9 insertions(+), 14 deletions(-)

diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
index ccb522f..dff6886 100644
--- a/doc/ref/guile.texi
+++ b/doc/ref/guile.texi
@@ -372,7 +372,7 @@ available through both Scheme and C interfaces.
 * 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.
+* Eq? Hash Consing::            Hash tables whose keys are pairs.
 * Buffered Line IO::            Like @code{read-line}, but buffered.
 * Bindings Browsing::           Browsing the module hierarchy.
 * New Hash Mappings::           New hash mappings.
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 #3: 0002-Document-ice-9-string-fun.patch --]
[-- Type: application/octet-stream, Size: 6417 bytes --]

From 357d5bb9941997e34cb26f50a3b3fdde484e5802 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 2/2] Document (ice-9 string-fun)

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

 Based on documentation contributed by Thien-Thi Nguyen.
---
 doc/ref/Makefile.am     |    1 +
 doc/ref/guile.texi      |    2 +
 doc/ref/string-fun.texi |  139 +++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 142 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/guile.texi b/doc/ref/guile.texi
index dff6886..92453f3 100644
--- a/doc/ref/guile.texi
+++ b/doc/ref/guile.texi
@@ -379,6 +379,7 @@ available through both Scheme and C interfaces.
 * Memoization::                 Procedures that remember their outputs.
 * Alternate Pipes::             Another interface to pipes.
 * Run Queues::                  For parallel execution.
+* String Utilities::            Searching and splitting strings.
 * Preloaded Modules for Interactive Sessions::
 * Lazy Catch::                  Catch without unwinding.
 * Higher level thread procedures::
@@ -409,6 +410,7 @@ available through both Scheme and C interfaces.
 @include poe.texi
 @include popen.texi
 @include runq.texi
+@include string-fun.texi
 @include session.texi
 @include stack-catch.texi
 @include 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

Re: Do you recognize these modules?

[Noah Lavine]

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

And here is a patch to remove all of the @twerp* comments. But did you
mean that I should remove them in the same patches that import the
documentation? I thought it was easier to do it separately, but I
could probably do it that way too.

Noah

On Wed, Jul 11, 2012 at 11:20 AM, Noah Lavine <noah.b.lavine@gmail.com> wrote:
> Ooops, I think those errors are because I forgot to commit my changes
> to guile.texi for patches 3 and 4. Here are updated versions. (I
> believe the second patch from earlier should work.)
>
> I will make another patch to clean out the @twerpcommentary lines.
>
> Noah
>
> On Wed, Jul 11, 2012 at 6:44 AM, Andy Wingo <wingo@pobox.com> wrote:
>> On Wed 11 Jul 2012 05:02, Noah Lavine <noah.b.lavine@gmail.com> writes:
>>
>>> 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.
>>
>> Cool.  I applied the first one.  When applying the rest, I got:
>>
>>     /home/wingo/src/guile/doc/ref//lineio.texi:12: Prev reference to nonexistent node `Double-Key Hash Tables' (perhaps incorrect sectioning?).
>>     /home/wingo/src/guile/doc/ref//hcons.texi:12: `Eq? Hash Consing' has no Up field (perhaps incorrect sectioning?).
>>     /home/wingo/src/guile/doc/ref//gap-buffer.texi:12: Next reference to nonexistent node `Double-Key Hash Tables' (perhaps incorrect sectioning?).
>>     /home/wingo/src/guile/doc/ref//guile.texi:375: Menu reference to nonexistent node `Double-Key Hash Tables' (perhaps incorrect sectioning?).
>>     /home/wingo/src/guile/doc/ref//hcons.texi:12: warning: unreferenced node `Eq? Hash Consing'.
>>     makeinfo: Removing output file `guile.info' due to errors; use --force to preserve.
>>     make[4]: *** [guile.info] Error 1
>>
>> As Thien-Thi suggests, it's probably good to filter out the
>> @twerpcommentary etcetera in your next patches.
>>
>> Cheers,
>>
>> Andy
>> --
>> http://wingolog.org/

[-- Attachment #2: 0001-Remove-twerp-comments-in-documentation.patch --]
[-- Type: application/octet-stream, Size: 41804 bytes --]

From e17d08b83e753a772ee4f6a126c6919e09b02f21 Mon Sep 17 00:00:00 2001
From: Noah Lavine <noah.b.lavine@gmail.com>
Date: Wed, 11 Jul 2012 13:55:45 -0400
Subject: [PATCH] Remove @twerp comments in documentation

 * 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/string-fun.texi:
 * doc/ref/threads.texi: remove @twerp comments. They seem to have
 been generated by an old documentation system.
---
 doc/ref/calling.texi     |   26 +++-------
 doc/ref/common-list.texi |   72 ++++++++++--------------------
 doc/ref/gap-buffer.texi  |  112 +++++++++++++--------------------------------
 doc/ref/hcons.texi       |   25 +++-------
 doc/ref/lineio.texi      |   11 +---
 doc/ref/ls.texi          |   14 ++----
 doc/ref/mapping.texi     |   17 ++-----
 doc/ref/poe.texi         |    6 +--
 doc/ref/popen.texi       |   10 +---
 doc/ref/runq.texi        |   23 +++-------
 doc/ref/session.texi     |   25 +++--------
 doc/ref/stack-catch.texi |    4 --
 doc/ref/string-fun.texi  |    2 -
 doc/ref/threads.texi     |   10 ----
 14 files changed, 99 insertions(+), 258 deletions(-)

diff --git a/doc/ref/calling.texi b/doc/ref/calling.texi
index 172f744..ec6b229 100644
--- a/doc/ref/calling.texi
+++ b/doc/ref/calling.texi
@@ -18,8 +18,6 @@ To make use of idiomatic calling-convention macros, evaluate the form:
 (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
@@ -39,8 +37,7 @@ then restores the values.  These operations form the three branches of a
   (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
@@ -65,8 +62,7 @@ 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
@@ -114,13 +110,11 @@ These calling sequences supports two handy idioms:
   (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
@@ -134,8 +128,7 @@ like:
 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
@@ -148,8 +141,7 @@ symbols naming bindings in the caller of
 
 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
@@ -176,14 +168,12 @@ 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:
diff --git a/doc/ref/common-list.texi b/doc/ref/common-list.texi
index 2741c53..03648db 100644
--- a/doc/ref/common-list.texi
+++ b/doc/ref/common-list.texi
@@ -22,43 +22,36 @@ for Guile.  To load it:
 
 @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
@@ -67,100 +60,83 @@ 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
diff --git a/doc/ref/gap-buffer.texi b/doc/ref/gap-buffer.texi
index 363550c..3273075 100644
--- a/doc/ref/gap-buffer.texi
+++ b/doc/ref/gap-buffer.texi
@@ -18,7 +18,6 @@ To load support for efficient insert/delete operations on strings:
 (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
@@ -66,21 +65,17 @@ 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.
@@ -93,74 +88,60 @@ 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.
@@ -169,8 +150,7 @@ 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
@@ -178,13 +158,11 @@ In @var{gb}, delete @var{count} characters from point, forward if
 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
@@ -193,26 +171,21 @@ is empty).
 
 @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
@@ -222,15 +195,13 @@ 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.
@@ -239,8 +210,6 @@ If point reaches the beginning or end of buffer, it stops there.
 
 @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.
@@ -248,16 +217,14 @@ 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
@@ -265,8 +232,7 @@ 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
@@ -274,8 +240,7 @@ 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.
@@ -286,8 +251,7 @@ 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.
@@ -297,8 +261,7 @@ 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.
@@ -313,8 +276,7 @@ Optional fourth argument is repeat count--search for successive occurrences.
 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
@@ -334,48 +296,40 @@ Leave point at end of replacement text.
 
 @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
diff --git a/doc/ref/hcons.texi b/doc/ref/hcons.texi
index 273a871..fd5c7be 100644
--- a/doc/ref/hcons.texi
+++ b/doc/ref/hcons.texi
@@ -23,50 +23,41 @@ To use eq?-hash consers, evaluate
 (use-modules (ice-9 hcons))
 @end smalllisp
 
-@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
@@ -76,8 +67,6 @@ same as the latter two args of @code{hashq-cons}.
 
 @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,
diff --git a/doc/ref/lineio.texi b/doc/ref/lineio.texi
index 1d15494..f7b96b4 100644
--- a/doc/ref/lineio.texi
+++ b/doc/ref/lineio.texi
@@ -33,14 +33,11 @@ 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}.
 
@@ -48,14 +45,12 @@ 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
diff --git a/doc/ref/ls.texi b/doc/ref/ls.texi
index 7fe5e2d..9fb4bae 100644
--- a/doc/ref/ls.texi
+++ b/doc/ref/ls.texi
@@ -25,21 +25,17 @@ this hierarchy, evaluate the form:
 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.
 
@@ -56,13 +52,11 @@ return a list:
  ...)
 @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
diff --git a/doc/ref/mapping.texi b/doc/ref/mapping.texi
index 5bcf9a0..a398290 100644
--- a/doc/ref/mapping.texi
+++ b/doc/ref/mapping.texi
@@ -18,8 +18,6 @@ To create and use new hash table mappings, evaluate the form:
 (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}.
 
@@ -45,33 +43,28 @@ The mapping object prints using hash notation:
 @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}.
diff --git a/doc/ref/poe.texi b/doc/ref/poe.texi
index 5c377e9..66ef9f8 100644
--- a/doc/ref/poe.texi
+++ b/doc/ref/poe.texi
@@ -21,7 +21,6 @@ To make use of the memoization facilities, evaluate the form:
 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
@@ -34,15 +33,12 @@ 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
diff --git a/doc/ref/popen.texi b/doc/ref/popen.texi
index 3203d88..a210fea 100644
--- a/doc/ref/popen.texi
+++ b/doc/ref/popen.texi
@@ -21,8 +21,7 @@ module:
 @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
@@ -30,21 +29,16 @@ 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},
diff --git a/doc/ref/runq.texi b/doc/ref/runq.texi
index f66e2c4..1388090 100644
--- a/doc/ref/runq.texi
+++ b/doc/ref/runq.texi
@@ -19,8 +19,6 @@ computations, evaluate the form:
 (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
@@ -45,10 +43,7 @@ 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
@@ -75,14 +70,12 @@ Empty the runq.
 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.
@@ -92,8 +85,7 @@ 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.
@@ -109,8 +101,7 @@ 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}.
 
@@ -122,13 +113,11 @@ 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}.
diff --git a/doc/ref/session.texi b/doc/ref/session.texi
index d59e790..ae3f6db 100644
--- a/doc/ref/session.texi
+++ b/doc/ref/session.texi
@@ -29,14 +29,11 @@ however, you can load them explicitly with the expression:
 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,
@@ -54,19 +51,15 @@ 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.
 
@@ -89,25 +82,19 @@ Fourth arg FOLDER is one of
   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
index 196268c..8020e89 100644
--- a/doc/ref/stack-catch.texi
+++ b/doc/ref/stack-catch.texi
@@ -19,8 +19,6 @@ 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
@@ -106,8 +104,6 @@ available after evaluating the form:
 (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
diff --git a/doc/ref/string-fun.texi b/doc/ref/string-fun.texi
index 9a70738..cca6688 100644
--- a/doc/ref/string-fun.texi
+++ b/doc/ref/string-fun.texi
@@ -21,8 +21,6 @@ shared substring capability.  These are available by evaluating:
 (use-modules (ice-9 string-fun))
 @end lisp
 
-@c @twerpcommentary (verbatim (ice-9 string-fun))
-
 This module provides the following procedures:
 
 @verbatim
diff --git a/doc/ref/threads.texi b/doc/ref/threads.texi
index f225239..1933028 100644
--- a/doc/ref/threads.texi
+++ b/doc/ref/threads.texi
@@ -21,8 +21,6 @@ Higher level thread procedures are available by evaluating:
 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}
@@ -36,31 +34,23 @@ 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}.
-- 
1.7.6

Re: Do you recognize these modules?

[Noah Lavine]

Any objections if I apply these patches soon? I'd like to get them off
of my to do list.

Thanks,
Noah

On Wed, Jul 11, 2012 at 1:59 PM, Noah Lavine <noah.b.lavine@gmail.com> wrote:
> And here is a patch to remove all of the @twerp* comments. But did you
> mean that I should remove them in the same patches that import the
> documentation? I thought it was easier to do it separately, but I
> could probably do it that way too.
>
> Noah
>
> On Wed, Jul 11, 2012 at 11:20 AM, Noah Lavine <noah.b.lavine@gmail.com> wrote:
>> Ooops, I think those errors are because I forgot to commit my changes
>> to guile.texi for patches 3 and 4. Here are updated versions. (I
>> believe the second patch from earlier should work.)
>>
>> I will make another patch to clean out the @twerpcommentary lines.
>>
>> Noah
>>
>> On Wed, Jul 11, 2012 at 6:44 AM, Andy Wingo <wingo@pobox.com> wrote:
>>> On Wed 11 Jul 2012 05:02, Noah Lavine <noah.b.lavine@gmail.com> writes:
>>>
>>>> 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.
>>>
>>> Cool.  I applied the first one.  When applying the rest, I got:
>>>
>>>     /home/wingo/src/guile/doc/ref//lineio.texi:12: Prev reference to nonexistent node `Double-Key Hash Tables' (perhaps incorrect sectioning?).
>>>     /home/wingo/src/guile/doc/ref//hcons.texi:12: `Eq? Hash Consing' has no Up field (perhaps incorrect sectioning?).
>>>     /home/wingo/src/guile/doc/ref//gap-buffer.texi:12: Next reference to nonexistent node `Double-Key Hash Tables' (perhaps incorrect sectioning?).
>>>     /home/wingo/src/guile/doc/ref//guile.texi:375: Menu reference to nonexistent node `Double-Key Hash Tables' (perhaps incorrect sectioning?).
>>>     /home/wingo/src/guile/doc/ref//hcons.texi:12: warning: unreferenced node `Eq? Hash Consing'.
>>>     makeinfo: Removing output file `guile.info' due to errors; use --force to preserve.
>>>     make[4]: *** [guile.info] Error 1
>>>
>>> As Thien-Thi suggests, it's probably good to filter out the
>>> @twerpcommentary etcetera in your next patches.
>>>
>>> Cheers,
>>>
>>> Andy
>>> --
>>> http://wingolog.org/

Re: Do you recognize these modules?

[Ludovic Courtès]

Hi Noah!

Noah Lavine <noah.b.lavine@gmail.com> skribis:

> Any objections if I apply these patches soon? I'd like to get them off
> of my to do list.

Presumably, yes.  Could you post the latest version of the patch here
(the previous broke the manual, IIUC)?

Thanks!

Ludo’.

Re: Do you recognize these modules?

[Thien-Thi Nguyen]

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

() Andy Wingo <wingo@pobox.com>
() Tue, 15 May 2012 22:14:31 +0200

   2.0 is the current stable branch, so any changes should go
   there first.  If it's a build fix or some other fix related to
   forward-compatibility with 2.0, it can go on 1.8 as well.  We
   should avoid adding interfaces to 1.8, though.

   When in doubt, it's best (and much appreciated) to mail the
   list.  If no one responds in a few days, go ahead and push it
   of course.

   Does that sound sensible to you?

Yes, thanks for the guidelines.  I hope to pop enough stacks to
get back to Guile (proper) hacking this year.  Fingers crossed...

-- 
Thien-Thi Nguyen
GPG key: 4C807502

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]