Re: Add internal definitions to derived forms

[lloda <lloda@sarc.name>]

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



> On 19 Jan 2023, at 18:54, lloda <lloda@sarc.name> wrote:
> 
> Attached a patch that applies after yours and refers to the explanation of bodies elsewhere in the manual. Wdyt?

Second version, fixes text for the same type of body for other forms.

Regards

  Daniel


[-- Attachment #2: 0002-Fix-documentation-for-forms-taking-lambda-like-bodie.patch --]
[-- Type: application/octet-stream, Size: 7680 bytes --]

From 7aea299373f7370f31c9701035260ad412763724 Mon Sep 17 00:00:00 2001
From: Daniel Llorens <lloda@sarc.name>
Date: Thu, 19 Jan 2023 16:23:29 +0100
Subject: [PATCH 2/2] Fix documentation for forms taking lambda-like bodies

* doc/ref/api-control.texi (Conditionals): Use 'body' in the syntax
  description of when, unless, cond, case.
* doc/ref/api-binding.texi (Local Bindings): Normalize description of
  body return values.
  (Multiple values): Normalize use of 'body' and description of body
  return values.
---
 doc/ref/api-binding.texi |  6 +++--
 doc/ref/api-control.texi | 51 +++++++++++++++++++---------------------
 2 files changed, 28 insertions(+), 29 deletions(-)

diff --git a/doc/ref/api-binding.texi b/doc/ref/api-binding.texi
index 60f034a0e..2fa1366d2 100644
--- a/doc/ref/api-binding.texi
+++ b/doc/ref/api-binding.texi
@@ -128,6 +128,8 @@ expressions has a few properties which are well worth knowing.
 
 The most basic local binding construct is @code{let}.
 
+@cindex body
+
 @deffn syntax let bindings body
 @var{bindings} has the form
 
@@ -151,8 +153,8 @@ New storage is allocated for the @var{variables}.
 The values of the @var{init} expressions are stored into the variables.
 
 @item
-The expressions in @var{body} are evaluated in order, and the value of
-the last expression is returned as the value of the @code{let}
+The expressions in @var{body} are evaluated in order, and the values of
+the last expression are returned as the result of the @code{let}
 expression.
 @end itemize
 
diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi
index ece6a6020..d04ec49b6 100644
--- a/doc/ref/api-control.texi
+++ b/doc/ref/api-control.texi
@@ -47,8 +47,8 @@ output port, then display a newline.  We use @code{begin} to form a
 compound expression out of this sequence of sub-expressions.
 
 @deffn syntax begin expr @dots{}
-The expression(s) are evaluated in left-to-right order and the value of
-the last expression is returned as the value of the
+The expression(s) are evaluated in left-to-right order and the values of
+the last expression are returned as the result of the
 @code{begin}-expression.  This expression type is used when the
 expressions before the last one are evaluated for their side effects.
 @end deffn
@@ -117,7 +117,7 @@ abuses the @code{begin} form for these two tasks.
 
 Guile provides three syntactic constructs for conditional evaluation.
 @code{if} is the normal if-then-else expression (with an optional else
-branch), @code{cond} is a conditional expression with multiple branches
+branch), @code{cond} is a conditional expression with multiple branches,
 and @code{case} branches if an expression has one of a set of constant
 values.
 
@@ -141,14 +141,14 @@ expression.  (By convention, we use the word @dfn{statement} to refer to
 an expression that is evaluated for effect, not for value).
 
 In such a case, it is considered more clear to express these intentions
-with these special forms, @code{when} and @code{unless}.  As an added
-bonus, these forms accept multiple statements to evaluate, which are
-implicitly wrapped in a @code{begin}.
+with the special forms @code{when} and @code{unless}.  As an added
+bonus, these forms take a @ref{Local Bindings,lambda-like body}, which can
+contain @ref{Internal Definitions,internal definitions} and multiple statements
+to evaluate.
 
-@deffn {Scheme Syntax} when test statement1 statement2 ...
-@deffnx {Scheme Syntax} unless test statement1 statement2 ...
-The actual definitions of these forms are in many ways their most clear
-documentation:
+@deffn {Scheme Syntax} when test body
+@deffnx {Scheme Syntax} unless test body
+The actual definitions of these forms may be their most clear documentation:
 
 @example
 (define-syntax-rule (when test stmt stmt* ...)
@@ -167,11 +167,10 @@ statements if @var{test} is false.
 Each @code{cond}-clause must look like this:
 
 @lisp
-(@var{test} @var{body} @dots{})
+(@var{test} @var{body})
 @end lisp
 
-where @var{test} is an arbitrary expression and @var{body} is a
-lambda-like body, or like this
+where @var{test} is an arbitrary expression, or like this
 
 @lisp
 (@var{test} => @var{expression})
@@ -180,9 +179,9 @@ lambda-like body, or like this
 where @var{expression} must evaluate to a procedure.
 
 The @var{test}s of the clauses are evaluated in order and as soon as one
-of them evaluates to a true value, the corresponding @var{expression}s
-are evaluated in order and the last value is returned as the value of
-the @code{cond}-expression.  For the @code{=>} clause type,
+of them evaluates to a true value, the corresponding @var{body} is
+evaluated to produce the result of the @code{cond}-expression.  For the
+@code{=>} clause type,
 @var{expression} is evaluated and the resulting procedure is applied to
 the value of @var{test}.  The result of this procedure application is
 then the result of the @code{cond}-expression.
@@ -209,7 +208,7 @@ procedure to the value(s) of @var{test}, in the same manner as the
 
 The @var{test} of the last @var{clause} may be the symbol @code{else}.
 Then, if none of the preceding @var{test}s is true, the
-@var{expression}s following the @code{else} are evaluated to produce the
+@var{body} following the @code{else} is evaluated to produce the
 result of the @code{cond}-expression.
 @end deffn
 
@@ -217,7 +216,7 @@ result of the @code{cond}-expression.
 @var{key} may be any expression, and the @var{clause}s must have the form
 
 @lisp
-((@var{datum1} @dots{}) @var{body} @dots{})
+((@var{datum1} @dots{}) @var{body})
 @end lisp
 
 or
@@ -229,7 +228,7 @@ or
 and the last @var{clause} may have the form
 
 @lisp
-(else @var{expr1} @var{body} @dots{})
+(else @var{body})
 @end lisp
 
 or
@@ -241,14 +240,13 @@ or
 All @var{datum}s must be distinct.  First, @var{key} is evaluated.  The
 result of this evaluation is compared against all @var{datum} values
 using @code{eqv?}.  When this comparison succeeds, the @var{body}
-following the @var{datum} is evaluated like the body of a lambda,
-returning the value of the last expression as the result of the
+following the @var{datum} is evaluated to produce the result of the
 @code{case} expression.
 
 If the @var{key} matches no @var{datum} and there is an
 @code{else}-clause, the @var{body} following the @code{else} is
-evaluated.  If there is no such clause, the result of the expression is
-unspecified.
+evaluated to produce the result of the @code{case} expression.  If there
+is no such clause, the result of the expression is unspecified.
 
 For the @code{=>} clause types, @var{expression} is evaluated and the
 resulting procedure is applied to the value of @var{key}.  The result of
@@ -970,13 +968,12 @@ same as specified by SRFI-8 (@pxref{SRFI-8}).
 (use-modules (ice-9 receive))
 @end lisp
 
-@deffn {library syntax} receive formals expr body @dots{}
+@deffn {library syntax} receive formals expr body
 Evaluate the expression @var{expr}, and bind the result values (zero
 or more) to the formal arguments in @var{formals}.  @var{formals} is a
 list of symbols, like the argument list in a @code{lambda}
-(@pxref{Lambda}).  After binding the variables, the expressions in
-@var{body} @dots{} are evaluated in order, the return value is the
-result from the last expression.
+(@pxref{Lambda}).  After binding the variables, the @var{body} is
+evaluated to produce the result of the @code{receive} expression.
 
 For example getting results from @code{partition} in SRFI-1
 (@pxref{SRFI-1}),
-- 
2.30.2