From f993203de1fd1bb88f5e327e58c63892da1f8767 Mon Sep 17 00:00:00 2001
From: Matt Birkholz <matt@birchwood-abbey.net>
Date: Fri, 4 Nov 2016 23:12:40 -0700
Subject: [PATCH] Update documentation for values, call-with-values.

---
 doc/ref-manual/procedures.texi | 33 ++++++++++++++++++---------------
 1 file changed, 18 insertions(+), 15 deletions(-)

diff --git a/doc/ref-manual/procedures.texi b/doc/ref-manual/procedures.texi
index f5f609261..d63793d88 100644
--- a/doc/ref-manual/procedures.texi
+++ b/doc/ref-manual/procedures.texi
@@ -448,26 +448,29 @@ extent of a call to @var{before} or @var{after} is undefined.
 
 The following two procedures support multiple values.
 
-@deffn procedure call-with-values thunk procedure
+@deffn procedure values object @dots{}
+Returns multiple values.  The continuation in effect when this procedure
+is called must accept as many values as there are @var{object}s.
+@end deffn
+
+@deffn procedure call-with-values producer consumer
 @cindex multiple values, from procedure
 @cindex values, multiple
-@var{Thunk} must be a procedure of no arguments, and @var{procedure}
-must be a procedure.  @var{Thunk} is invoked with a continuation that
-expects to receive multiple values; specifically, the continuation
-expects to receive the same number of values that @var{procedure}
-accepts as arguments.  @var{Thunk} must return multiple values using the
-@code{values} procedure.  Then @var{procedure} is called with the
-multiple values as its arguments.  The result yielded by @var{procedure}
-is returned as the result of @code{call-with-values}.
-@end deffn
 
-@deffn procedure values object @dots{}
-Returns multiple values.  The continuation in effect when this procedure
-is called must be a multiple-value continuation that was created by
-@code{call-with-values}.  Furthermore it must accept as many values as
-there are @var{object}s.
+Calls @var{producer} with no arguments and a continuation that, when
+passed some values, calls @var{consumer} with those values as
+arguments.  The continuation for the call to @var{consumer} is the
+continuation of the call to @code{call-with-values}.
 @end deffn
 
+@example
+(call-with-values (lambda () (values 4 5))
+                  (lambda (a b) b))     @result{} 5
+@end example
+@example
+(call-with-values * -)                  @result{} -1
+@end example
+
 @node Application Hooks, Generic Dispatch, Continuations, Procedures
 @section Application Hooks
 
-- 
2.25.1