merge from 1.8 branch

11 files changed, 400 insertions, 97 deletions

diff --git a/doc/goops/ChangeLog b/doc/goops/ChangeLog
index 22a5c82c2..b0e742b71 100644
--- a/doc/goops/ChangeLog
+++ b/doc/goops/ChangeLog
@@ -1,4 +1,4 @@
-2006-09-27  Neil Jerram  <neil@ossau.uklinux.net>
+2006-09-28  Neil Jerram  <neil@ossau.uklinux.net>
 
 	* goops.texi (Slot Options): Added example from Ludovic Courtès
 	about difference between init-value, -form and -thunk.
diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog
index 7a1883095..91a776004 100644
--- a/doc/ref/ChangeLog
+++ b/doc/ref/ChangeLog
@@ -18,6 +18,19 @@
 	(Setting and Managing Breakpoints): Update text on how to set
 	breakpoints.
 
+2006-10-05  Kevin Ryde  <user42@zip.com.au>
+
+	* misc-modules.texi (File Tree Walk): Corrections to BASE parameter
+	and symlink vs stale-symlink types in nftw.
+	* misc-modules.texi, guile.texi (Buffered Input): New section,
+	describing (ice-9 buffered-input).
+
+	* posix.texi (User Information): Clarify getpwent returns #f at end of
+	file.
+
+	* repl-modules.texi (Readline Functions): New section on how to call
+	readline from scheme code.
+
 2006-10-03  Neil Jerram  <neil@ossau.uklinux.net>
 
 	* scheme-using.texi (GDS Getting Started): Editorial updates.
@@ -39,6 +52,12 @@
 	(GDS Getting Started, How to Use GDS): Merged; editorial updates;
 	subsections reordered.
 
+2006-09-26  Kevin Ryde  <user42@zip.com.au>
+
+	* api-io.texi (Random Access): In truncate-file, tweak wording for
+	clarity, note cannot always extend file this way.
+	(Ports): File access uses LFS.
+
 2006-09-25  Neil Jerram  <neil@ossau.uklinux.net>
 
 	* scheme-using.texi (Error Handling, Interactive Debugger): Minor
@@ -51,11 +70,31 @@
 	minor improvements.  Removed doc for `trace-finish', which no
 	longer exists.
 
+2006-09-22  Kevin Ryde  <user42@zip.com.au>
+
+	* api-data.texi (Scientific): In sqrt, note it's the positive root
+	which is returned (as per R5RS).
+
 2006-09-20  Ludovic Courtès  <ludovic.courtes@laas.fr>
 
 	* api-data.texi (Standard Character Sets): Documented the
 	charset recomputation upon successful `setlocale'.
 
+2006-09-08  Kevin Ryde  <user42@zip.com.au>
+
+	* misc-modules.texi (Formatted Output): Show ":@" rather than "@:",
+	because ":@" is traditional common lisp, though either way works.
+	Break a couple of example lines to avoid overflowing DVI page width.
+
+	* scheme-debugging.texi (Debug Last Error): Line break in "Type
+	(backtrace) to get ..." which overflowed the line in both info and
+	DVI.  Reported by Percy Tiglao.
+
+2006-09-05  Kevin Ryde  <user42@zip.com.au>
+
+	* posix.texi (Network Sockets and Communication): Tweak description,
+	note not multi-threading.
+
 2006-09-04  Neil Jerram  <neil@ossau.uklinux.net>
 
 	* api-control.texi (Dynamic Wind): Doc for scm_dynwind_free.
@@ -69,6 +108,11 @@
 	* api-debug.texi (Debug on Error): Added paragraph on need to use
 	debugging evaluator.  Added text on what the Guile REPL code does.
 
+2006-08-29  Kevin Ryde  <user42@zip.com.au>
+
+	* api-control.texi (Dynamic Wind): Reformat example a bit to avoid
+	going off the right edge of the paper.  Reported by Percy Tiglao.
+
 2006-08-28  Neil Jerram  <neil@ossau.uklinux.net>
 
 	* api-debug.texi (Examining the Stack): Minor improvements to
@@ -87,6 +131,11 @@
 	(GDS Introduction): New node, containing GDS-specific introductory
 	text.
 
+2006-08-22  Kevin Ryde  <user42@zip.com.au>
+
+	* api-i18n.texi (Internationalization): Cross reference gettext manual
+	on plural forms.
+
 2006-08-18  Neil Jerram  <neil@ossau.uklinux.net>
 
 	* scheme-using.texi (Using Guile in Emacs): Unignore extra GDS
@@ -142,6 +191,17 @@
 	* Makefile.am (guile_TEXINFOS): Include new scheme-using.texi
 	file.
 
+2006-07-24  Kevin Ryde  <user42@zip.com.au>
+
+	* api-evaluation.texi (Fly Evaluation): Add scm_c_eval_string.
+	(Loading): Add scm_c_primitive_load.
+	Reported by Jon Wilson.
+	
+2006-06-25  Kevin Ryde  <user42@zip.com.au>
+
+	* posix.texi (Time): In tm:gmtoff, give example values, note not the
+	same as C tm_gmtoff.
+
 2006-06-16  Ludovic Courtès  <ludovic.courtes@laas.fr>
 
 	* api-utility.texi (Equality): Mentioned the behavior of `equal?'
diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi
index dbb51cf6f..11a276a13 100644
--- a/doc/ref/api-control.texi
+++ b/doc/ref/api-control.texi
@@ -1234,28 +1234,29 @@ non-locally, @var{out_guard} is called.  If the dynamic extent of
 the dynamic-wind is re-entered, @var{in_guard} is called.  Thus
 @var{in_guard} and @var{out_guard} may be called any number of
 times.
+
 @lisp
 (define x 'normal-binding)
 @result{} x
-(define a-cont  (call-with-current-continuation
-                  (lambda (escape)
-                     (let ((old-x x))
-                       (dynamic-wind
-                          ;; in-guard:
-                          ;;
-                          (lambda () (set! x 'special-binding))
-
-                          ;; thunk
-                          ;;
-                          (lambda () (display x) (newline)
-                                     (call-with-current-continuation escape)
-                                     (display x) (newline)
-                                     x)
-
-                          ;; out-guard:
-                          ;;
-                          (lambda () (set! x old-x)))))))
-
+(define a-cont
+  (call-with-current-continuation
+   (lambda (escape)
+     (let ((old-x x))
+       (dynamic-wind
+           ;; in-guard:
+           ;;
+           (lambda () (set! x 'special-binding))
+
+           ;; thunk
+           ;;
+           (lambda () (display x) (newline)
+                      (call-with-current-continuation escape)
+                      (display x) (newline)
+                      x)
+
+           ;; out-guard:
+           ;;
+           (lambda () (set! x old-x)))))))
 ;; Prints:
 special-binding
 ;; Evaluates to:
diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index 4534f8a6e..ccd34e38f 100755
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
-@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -1214,7 +1214,16 @@ including complex numbers.
 @rnindex sqrt
 @c begin (texi-doc-string "guile" "sqrt")
 @deffn {Scheme Procedure} sqrt z
-Return the square root of @var{z}.
+Return the square root of @var{z}.  Of the two possible roots
+(positive and negative), the one with the a positive real part is
+returned, or if that's zero then a positive imaginary part.  Thus,
+
+@example
+(sqrt 9.0)       @result{} 3.0
+(sqrt -9.0)      @result{} 0.0+3.0i
+(sqrt 1.0+1.0i)  @result{} 1.09868411346781+0.455089860562227i
+(sqrt -1.0-1.0i) @result{} 0.455089860562227-1.09868411346781i
+@end example
 @end deffn
 
 @rnindex expt
diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi
index 6f29f1d7c..1da13de43 100644
--- a/doc/ref/api-evaluation.texi
+++ b/doc/ref/api-evaluation.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
-@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -357,6 +357,11 @@ While the code is evaluated, the given module is made the current one.
 The current module is restored when this procedure returns.
 @end deffn
 
+@deftypefn {C Function} SCM scm_c_eval_string (const char *string)
+@code{scm_eval_string}, but taking a C string instead of an
+@code{SCM}.
+@end deftypefn
+
 @deffn {Scheme Procedure} apply proc arg1 @dots{} argN arglst
 @deffnx {C Function} scm_apply_0 (proc, arglst)
 @deffnx {C Function} scm_apply_1 (proc, arg1, arglst)
@@ -446,6 +451,11 @@ that will be called before any code is loaded.  See the
 documentation for @code{%load-hook} later in this section.
 @end deffn
 
+@deftypefn {C Function} SCM scm_c_primitive_load (const char *filename)
+@code{scm_primitive_load}, but taking a C string instead of an
+@code{SCM}.
+@end deftypefn
+
 @deffn {Scheme Procedure} primitive-load-path filename
 @deffnx {C Function} scm_primitive_load_path (filename)
 Search @code{%load-path} for the file named @var{filename} and
diff --git a/doc/ref/api-i18n.texi b/doc/ref/api-i18n.texi
index 995e27e90..63884254a 100644
--- a/doc/ref/api-i18n.texi
+++ b/doc/ref/api-i18n.texi
@@ -85,7 +85,8 @@ example,
 It's important to use @code{ngettext} rather than plain @code{gettext}
 for plurals, since the rules for singular and plural forms in English
 are not the same in other languages.  Only @code{ngettext} will allow
-translators to give correct forms.
+translators to give correct forms (@pxref{Plural forms,, Additional
+functions for plural forms, gettext, GNU @code{gettext} utilities}).
 @end deffn
 
 @deffn {Scheme Procedure} textdomain [domain]
diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index 6eb95db3d..0d30c4d2a 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -64,6 +64,10 @@ rely on that to keep it away from system limits.  An explicit call to
 If program flow makes it hard to be certain when to close then this
 may be an acceptable way to control resource usage.
 
+All file access uses the ``LFS'' large file support functions when
+available, so files bigger than 2 Gbytes (@math{2^31} bytes) can be
+read and written on a 32-bit system.
+
 @rnindex input-port?
 @deffn {Scheme Procedure} input-port? x
 @deffnx {C Function} scm_input_port_p (x)
@@ -390,14 +394,18 @@ Return an integer representing the current position of
 
 @findex truncate
 @findex ftruncate
-@deffn {Scheme Procedure} truncate-file object [length]
-@deffnx {C Function} scm_truncate_file (object, length)
-Truncates the object referred to by @var{object} to at most
-@var{length} bytes.  @var{object} can be a string containing a
-file name or an integer file descriptor or a port.
-@var{length} may be omitted if @var{object} is not a file name,
-in which case the truncation occurs at the current port
-position.  The return value is unspecified.
+@deffn {Scheme Procedure} truncate-file file [length]
+@deffnx {C Function} scm_truncate_file (file, length)
+Truncate @var{file} to @var{length} bytes.  @var{file} can be a
+filename string, a port object, or an integer file descriptor.  The
+return value is unspecified.
+
+For a port or file descriptor @var{length} can be omitted, in which
+case the file is truncated at the current position (per @code{ftell}
+above).
+
+On most systems a file can be extended by giving a length greater than
+the current size, but this is not mandatory in the POSIX standard.
 @end deffn
 
 @node Line/Delimited
diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
index 627c8cbb2..992ca28c4 100644
--- a/doc/ref/guile.texi
+++ b/doc/ref/guile.texi
@@ -137,7 +137,7 @@ x
 @comment The title is printed in a large font.
 @title Guile Reference Manual
 @subtitle Edition @value{MANUAL-EDITION}, for use with Guile @value{VERSION}
-@c @subtitle $Id: guile.texi,v 1.46 2006-08-01 21:51:12 ossau Exp $
+@c @subtitle $Id: guile.texi,v 1.47 2006-10-09 22:45:02 kryde Exp $
 
 @c See preface.texi for the list of authors
 @author The Guile Developers
@@ -347,6 +347,7 @@ available through both Scheme and C interfaces.
 * File Tree Walk::              Traversing the file system.
 * Queues::                      First-in first-out queuing.
 * Streams::                     Sequences of values.
+* Buffered Input::              Ports made from a reader function.
 * Expect::			Controlling interactive programs with Guile.
 * The Scheme shell (scsh)::     Using scsh interfaces in Guile.
 @end menu
diff --git a/doc/ref/misc-modules.texi b/doc/ref/misc-modules.texi
index f3a3c4093..db90c419a 100644
--- a/doc/ref/misc-modules.texi
+++ b/doc/ref/misc-modules.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
-@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -270,13 +270,13 @@ With no parameters output is in words as a cardinal like ``ten'', or
 @end example
 
 And also with no parameters, @nicode{~@@r} gives roman numerals and
-@nicode{~@@:r} gives old roman numerals.  In old roman numerals
+@nicode{~:@@r} gives old roman numerals.  In old roman numerals
 there's no ``subtraction'', so 9 is @nicode{VIIII} instead of
 @nicode{IX}.  In both cases only positive numbers can be output.
 
 @example
 (format #t "~@@r" 89)  @print{} LXXXIX     ;; roman
-(format #t "~@@:r" 89) @print{} LXXXVIIII  ;; old roman
+(format #t "~:@@r" 89) @print{} LXXXVIIII  ;; old roman
 @end example
 
 When a parameter is given it means numeric output in the specified
@@ -507,7 +507,7 @@ puts the padding after the sign.
 @example
 (format #f "~,,8$" -1.5)   @result{} "   -1.50"
 (format #f "~,,8:$" -1.5)  @result{} "-   1.50"
-(format #f "~,,8,'.@@:$" 3) @result{} "+...3.00"
+(format #f "~,,8,'.:@@$" 3) @result{} "+...3.00"
 @end example
 
 Note that floating point for dollar amounts is generally not a good
@@ -567,7 +567,7 @@ one, which can be convenient when printing some sort of count.
 
 @example
 (format #t "~d cat~:p" 9)   @print{} 9 cats
-(format #t "~d pupp~@@:p" 5) @print{} 5 puppies
+(format #t "~d pupp~:@@p" 5) @print{} 5 puppies
 @end example
 
 @nicode{~p} is designed for English plurals and there's no attempt to
@@ -777,14 +777,14 @@ The modifiers on @nicode{~(} control the conversion.
 @c  rest lower case.
 @c
 @item
-@nicode{~@@:(} --- upper case.
+@nicode{~:@@(} --- upper case.
 @end itemize
 
 For example,
 
 @example
 (format #t "~(Hello~)")   @print{} hello
-(format #t "~@@:(Hello~)") @print{} HELLO
+(format #t "~:@@(Hello~)") @print{} HELLO
 @end example
 
 In the future it's intended the modifiers @nicode{:} and @nicode{@@}
@@ -813,8 +813,10 @@ elements from it.  This is a convenient way to output a whole list.
 @nicode{~:@{} takes a single argument which is a list of lists, each
 of those contained lists gives the arguments for the iterated format.
 
+@c  @print{} on a new line here to avoid overflowing page width in DVI
 @example
-(format #t "~:@{~dx~d ~@}" '((1 2) (3 4) (5 6))) @print{} 1x2 3x4 5x6
+(format #t "~:@{~dx~d ~@}" '((1 2) (3 4) (5 6)))
+@print{} 1x2 3x4 5x6
 @end example
 
 @nicode{~@@@{} takes arguments directly, with each iteration
@@ -825,11 +827,13 @@ successively consuming arguments.
 (format #t "~@@@{~s=~d ~@}" "x" 1 "y" 2) @print{} "x"=1 "y"=2
 @end example
 
-@nicode{~@@:@{} takes list arguments, one argument for each iteration,
+@nicode{~:@@@{} takes list arguments, one argument for each iteration,
 using that list for the format.
 
+@c  @print{} on a new line here to avoid overflowing page width in DVI
 @example
-(format #t "~@@:@{~dx~d ~@}" '(1 2) '(3 4) '(5 6)) @print{} 1x2 3x4 5x6
+(format #t "~:@@@{~dx~d ~@}" '(1 2) '(3 4) '(5 6))
+@print{} 1x2 3x4 5x6
 @end example
 
 Iterating stops when there are no more arguments or when the
@@ -1094,27 +1098,28 @@ Walk the filesystem tree starting at @var{startname}, calling
 @var{proc} for each file and directory.  @code{nftw} has extra
 features over the basic @code{ftw} described above.
 
-Hard links and symbolic links are followed, but a file or directory is
-reported to @var{proc} only once, and skipped if seen again in another
-place.  One consequence of this is that @code{nftw} is safe against
-circular linked directory structures.
+Like @code{ftw}, hard links and symbolic links are followed.  A file
+or directory is reported to @var{proc} only once, and skipped if seen
+again in another place.  One consequence of this is that @code{nftw}
+is safe against circular linked directory structures.
 
 Each @var{proc} call is @code{(@var{proc} filename statinfo flag
-basename level)} and it should return @code{#t} to continue, or any
+base level)} and it should return @code{#t} to continue, or any
 other value to stop.
 
 @var{filename} is the item visited, being @var{startname} plus a
 further path and the name of the item.  @var{statinfo} is the return
-from @code{stat} on @var{filename} (@pxref{File System}).
-@var{basename} it the item name without any path.  @var{level} is an
-integer giving the directory nesting level, starting from 0 for the
-contents of @var{startname} (or that item itself if it's a file).
-@var{flag} is one of the following symbols,
+from @code{stat} on @var{filename} (@pxref{File System}).  @var{base}
+is an integer offset into @var{filename} which is where the basename
+for this item begins.  @var{level} is an integer giving the directory
+nesting level, starting from 0 for the contents of @var{startname} (or
+that item itself if it's a file).  @var{flag} is one of the following
+symbols,
 
 @table @code
 @item regular
-@var{filename} is a file, this includes special files like devices,
-named pipes, etc.
+@var{filename} is a file, including special files like devices, named
+pipes, etc.
 
 @item directory
 @var{filename} is a directory.
@@ -1132,19 +1137,15 @@ nothing is known about it.  @var{statinfo} is @code{#f} in this case.
 @var{filename} is a directory, but one which cannot be read and hence
 won't be recursed into.
 
-@item symlink
-@var{filename} is a dangling symbolic link.  Symbolic links are
-normally followed and their target reported, the link itself is
-reported if the target does not exist.
-
-Under the @code{physical} option described below, @code{symlink} is
-instead given for symbolic links whose target does exist.
-
 @item stale-symlink
-Under the @code{physical} option described below, this indicates
-@var{filename} is a dangling symbolic link, meaning its target does
-not exist.  Without the @code{physical} option plain @code{symlink}
-indicates this.
+@var{filename} is a dangling symbolic link.  Links are normally
+followed and their target reported, the link itself is reported if its
+target does not exist.
+
+@item symlink
+When the @code{physical} option described below is used, this
+indicates @var{filename} is a symbolic link whose target exists (and
+is not being followed).
 @end table
 
 The following optional arguments can be given to modify the way
@@ -1156,10 +1157,11 @@ takes a following integer value).
 Change to the directory containing the item before calling @var{proc}.
 When @code{nftw} returns the original current directory is restored.
 
-Under this option, generally the @var{basename} parameter should be
-used to access the item in each @var{proc} call.  The @var{filename}
-parameter still has a path as normal and this will only be valid if
-the @var{startname} directory was absolute.
+Under this option, generally the @var{base} parameter to each
+@var{proc} call should be used to pick out the base part of the
+@var{filename}.  The @var{filename} is still a path but with a changed
+directory it won't be valid (unless the @var{startname} directory was
+absolute).
 
 @item @code{depth}
 Visit files ``depth first'', meaning @var{proc} is called for the
@@ -1175,11 +1177,12 @@ Set the size of the hash table used to track items already visited.
 
 @item @code{mount}
 Don't cross a mount point, meaning only visit items on the same
-filesystem as @var{startname}.  (Ie.@: the same @code{stat:dev}.)
+filesystem as @var{startname} (ie.@: the same @code{stat:dev}).
 
 @item @code{physical}
 Don't follow symbolic links, instead report them to @var{proc} as
-@code{symlink}, and report dangling links as @code{stale-symlink}.
+@code{symlink}.  Dangling links (those whose target doesn't exist) are
+still reported as @code{stale-symlink}.
 @end table
 
 The return value from @code{nftw} is @code{#t} if it ran to
@@ -1461,6 +1464,69 @@ ends when the end of the shortest given @var{stream} is reached.
 @end defun
 
 
+@node Buffered Input
+@section Buffered Input
+@cindex Buffered input
+@cindex Line continuation
+
+The following functions are provided by
+
+@example
+(use-modules (ice-9 buffered-input))
+@end example
+
+A buffered input port allows a reader function to return chunks of
+characters which are to be handed out on reading the port.  A notion
+of further input for an application level logical expression is
+maintained too, and passed through to the reader.
+
+@defun make-buffered-input-port reader
+Create an input port which returns characters obtained from the given
+@var{reader} function.  @var{reader} is called (@var{reader} cont),
+and should return a string or an EOF object.
+
+The new port gives precisely the characters returned by @var{reader},
+nothing is added, so if any newline characters or other separators are
+desired they must come from the reader function.
+
+The @var{cont} parameter to @var{reader} is @code{#f} for initial
+input, or @code{#t} when continuing an expression.  This is an
+application level notion, set with
+@code{set-buffered-input-continuation?!} below.  If the user has
+entered a partial expression then it allows @var{reader} for instance
+to give a different prompt to show more is required.
+@end defun
+
+@defun make-line-buffered-input-port reader
+@cindex Line buffered input
+Create an input port which returns characters obtained from the
+specified @var{reader} function, similar to
+@code{make-buffered-input-port} above, but where @var{reader} is
+expected to be a line-oriented.
+
+@var{reader} is called (@var{reader} cont), and should return a string
+or an EOF object as above.  Each string is a line of input without a
+newline character, the port code inserts a newline after each string.
+@end defun
+
+@defun set-buffered-input-continuation?! port cont
+Set the input continuation flag for a given buffered input
+@var{port}.
+
+An application uses this by calling with a @var{cont} flag of
+@code{#f} when beginning to read a new logical expression.  For
+example with the Scheme @code{read} function (@pxref{Scheme Read}),
+
+@example
+(define my-port (make-buffered-input-port my-reader))
+
+(set-buffered-input-continuation?! my-port #f)
+(let ((obj (read my-port)))
+  ...
+@end example
+@end defun
+
+
 @c Local Variables:
 @c TeX-master: "guile.texi"
 @c End:
diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi
index 6a1d0f1b2..0711b9a1e 100644
--- a/doc/ref/posix.texi
+++ b/doc/ref/posix.texi
@@ -1008,8 +1008,8 @@ return value is unspecified.
 @end deffn
 
 @deffn {Scheme Procedure} getpwent
-Return the next entry in the user database, using the stream set by
-@code{setpwent}.
+Read the next entry in the user database stream.  The return is a
+passwd user object as above, or @code{#f} when no more entries.
 @end deffn
 
 @deffn {Scheme Procedure} endpwent
@@ -1170,6 +1170,13 @@ Daylight saving indicator (0 for ``no'', greater than 0 for ``yes'', less than
 @deffn {Scheme Procedure} tm:gmtoff tm
 @deffnx {Scheme Procedure} set-tm:gmtoff tm val
 Time zone offset in seconds west of @acronym{UTC} (-46800 to 43200).
+For example on East coast USA (zone @samp{EST+5}) this would be 18000
+(ie.@: @m{5\times60\times60,5*60*60}) in winter, or 14400
+(ie.@: @m{4\times60\times60,4*60*60}) during daylight savings.
+
+Note @code{tm:gmtoff} is not the same as @code{tm_gmtoff} in the C
+@code{tm} structure.  @code{tm_gmtoff} is seconds east and hence the
+negative of the value here.
 @end deffn
 @deffn {Scheme Procedure} tm:zone tm
 @deffnx {Scheme Procedure} set-tm:zone tm val
@@ -2909,32 +2916,37 @@ any unflushed buffered port data is ignored.
 
 @deffn {Scheme Procedure} recvfrom! sock str [flags [start [end]]]
 @deffnx {C Function} scm_recvfrom (sock, str, flags, start, end)
-Return data from the socket port @var{sock} and also
-information about where the data was received from.
-@var{sock} must already be bound to the address from which
-data is to be received.  @code{str}, is a string into which the
-data will be written.  The size of @var{str} limits the amount
-of data which can be received: in the case of packet protocols,
-if a packet larger than this limit is encountered then some
-data will be irrevocably lost.
+Receive data from socket port @var{sock}, returning the originating
+address as well as the data.  This function is usually for datagram
+sockets, but can be used on stream-oriented sockets too.
+
+The data received is stored in the given @var{str}, the whole string
+or just the region between the optional @var{start} and @var{end}
+positions.  The size of @var{str} limits the amount of data which can
+be received.  For datagram protocols if a packet larger than this is
+received then excess bytes are irrevocably lost.
+
+The return value is a pair.  The @code{car} is the number of bytes
+read.  The @code{cdr} is a socket address object (@pxref{Network
+Socket Address}) which is where the data came from, or @code{#f} if
+the origin is unknown.
 
 @vindex MSG_OOB
 @vindex MSG_PEEK
 @vindex MSG_DONTROUTE
-The optional @var{flags} argument is a value or bitwise OR of
-@code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
-
-The value returned is a pair: the @acronym{CAR} is the number of
-bytes read from the socket and the @acronym{CDR} an address object
-in the same form as returned by @code{accept}.  The address
-will given as @code{#f} if not available, as is usually the
-case for stream sockets.
+The optional @var{flags} argument is a or bitwise-OR (@code{logior})
+of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
 
-The @var{start} and @var{end} arguments specify a substring of
-@var{str} to which the data should be written.
+Data is read directly from the socket file descriptor, any buffered
+port data is ignored.
 
-Note that the data is read directly from the socket file
-descriptor: any unread buffered port data is ignored.
+@c  This was linux kernel 2.6.15 and glibc 2.3.6, not sure what any
+@c  specs are supposed to say about recvfrom threading.
+@c
+On a GNU/Linux system @code{recvfrom!} is not multi-threading, all
+threads stop while a @code{recvfrom!} call is in progress.  An
+application may need to use @code{select}, @code{O_NONBLOCK} or
+@code{MSG_DONTWAIT} to avoid this.
 @end deffn
 
 @deffn {Scheme Procedure} sendto sock message sockaddr [flags]
diff --git a/doc/ref/repl-modules.texi b/doc/ref/repl-modules.texi
index 45f410c3a..5f274e253 100644
--- a/doc/ref/repl-modules.texi
+++ b/doc/ref/repl-modules.texi
@@ -23,6 +23,7 @@ history entries.
 @menu
 * Loading Readline Support::    How to load readline support into Guile.
 * Readline Options::            How to modify readline's behaviour.
+* Readline Functions::          Programming with readline.
 @end menu
 
 
@@ -32,7 +33,6 @@ history entries.
 The module is not loaded by default and so has to be loaded and
 activated explicitly.  This is done with two simple lines of code:
 
-@findex activate-readline
 @lisp
 (use-modules (ice-9 readline))
 (activate-readline)
@@ -91,7 +91,7 @@ $endif
 The readline interface module can be configured in several ways to
 better suit the user's needs.  Configuration is done via the readline
 module's options interface, in a similar way to the evaluator and
-debugging options (@pxref{User level options interfaces}.)
+debugging options (@pxref{Runtime Options}).
 
 @findex readline-options
 @findex readline-enable
@@ -119,6 +119,141 @@ usage of the history file using the following call.
 The readline options interface can only be used @emph{after} loading
 the readline module, because it is defined in that module.
 
+@node Readline Functions
+@subsection Readline Functions
+
+The following functions are provided by
+
+@example
+(use-modules (ice-9 readline))
+@end example
+
+There are two ways to use readline from Scheme code, either make calls
+to @code{readline} directly to get line by line input, or use the
+readline port below with all the usual reading functions.
+
+@defun readline [prompt]
+Read a line of input from the user and return it as a string (without
+a newline at the end).  @var{prompt} is the prompt to show, or the
+default is the string set in @code{set-readline-prompt!} below.
+
+@example
+(readline "Type something: ") @result{} "hello"
+@end example
+@end defun
+
+@defun set-readline-input-port! port
+@defunx set-readline-output-port! port
+Set the input and output port the readline function should read from
+and write to.  @var{port} must be a file port (@pxref{File Ports}),
+and should usually be a terminal.
+
+The default is the @code{current-input-port} and
+@code{current-output-port} (@pxref{Default Ports}) when @code{(ice-9
+readline)} loads, which in an interactive user session means the Unix
+``standard input'' and ``standard output''.
+@end defun
+
+@subsubsection Readline Port
+
+@defun readline-port
+Return a buffered input port (@pxref{Buffered Input}) which calls the
+@code{readline} function above to get input.  This port can be used
+with all the usual reading functions (@code{read}, @code{read-char},
+etc), and the user gets the interactive editing features of readline.
+
+There's only a single readline port created.  @code{readline-port}
+creates it when first called, and on subsequent calls just returns
+what it previously made.
+@end defun
+
+@defun activate-readline
+If the @code{current-input-port} is a terminal (@pxref{Terminals and
+Ptys,, @code{isatty?}}) then enable readline for all reading from
+@code{current-input-port} (@pxref{Default Ports}) and enable readline
+features in the interactive REPL (@pxref{The REPL}).
+
+@example
+(activate-readline)
+(read-char)
+@end example
+
+@code{activate-readline} enables readline on @code{current-input-port}
+simply by a @code{set-current-input-port} to the @code{readline-port}
+above.  An application can do that directly if the extra REPL features
+that @code{activate-readline} adds are not wanted.
+@end defun
+
+@defun set-readline-prompt! prompt1 [prompt2]
+Set the prompt string to print when reading input.  This is used when
+reading through @code{readline-port}, and is also the default prompt
+for the @code{readline} function above.
+
+@var{prompt1} is the initial prompt shown.  If a user might enter an
+expression across multiple lines, then @var{prompt2} is a different
+prompt to show further input required.  In the Guile REPL for instance
+this is an ellipsis (@samp{...}).
+
+See @code{set-buffered-input-continuation?!} (@pxref{Buffered Input})
+for an application to indicate the boundaries of logical expressions
+(assuming of course an application has such a notion).
+@end defun
+
+@subsubsection Completion
+
+@defun with-readline-completion-function completer thunk
+Call @code{(@var{thunk})} with @var{completer} as the readline tab
+completion function to be used in any readline calls within that
+@var{thunk}.  @var{completer} can be @code{#f} for no completion.
+
+@var{completer} will be called as @code{(@var{completer} text state)},
+as described in (@pxref{How Completing Works,,, readline, GNU Readline
+Library}).  @var{text} is a partial word to be completed, and each
+@var{completer} call should return a possible completion string or
+@code{#f} when no more.  @var{state} is @code{#f} for the first call
+asking about a new @var{text} then @code{#t} while getting further
+completions of that @var{text}.
+
+Here's an example @var{completer} for user login names from the
+password file (@pxref{User Information}), much like readline's own
+@code{rl_username_completion_function},
+
+@example
+(define (username-completer-function text state)
+  (if (not state)
+      (setpwent))  ;; new, go to start of database
+  (let more ((pw (getpwent)))
+    (if pw
+        (if (string-prefix? text (passwd:name pw))
+            (passwd:name pw)     ;; this name matches, return it
+            (more (getpwent)))   ;; doesn't match, look at next
+        (begin
+          ;; end of database, close it and return #f
+          (endpwent)
+          #f))))
+@end example
+@end defun
+
+@defun apropos-completion-function text state
+A completion function offering completions for Guile functions and
+variables (all @code{define}s).  This is the default completion
+function.
+@c
+@c  FIXME: Cross reference the ``apropos'' stuff when it's documented.
+@c
+@end defun
+
+@defun filename-completion-function text state
+A completion function offering filename completions.  This is
+readline's @code{rl_filename_completion_function} (@pxref{Completion
+Functions,,, readline, GNU Readline Library}).
+@end defun
+
+@defun make-completion-function string-list
+Return a completion function which offers completions from the
+possibilities in @var{string-list}.  Matching is case-sensitive.
+@end defun
+
 
 @page
 @node Value History