[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Add internal definitions to derived forms

From: Ludovic Courtès
Subject: Re: Add internal definitions to derived forms
Date: Mon, 23 Jan 2023 23:13:00 +0100
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/28.2 (gnu/linux)

Hi Daniel,

Chiming in late in the discussion…

lloda <> skribis:

> From 7aea299373f7370f31c9701035260ad412763724 Mon Sep 17 00:00:00 2001
> From: Daniel Llorens <>
> 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.

What about:
s/Fix documentation…/doc: Document multiple-value returns in let, cond, etc./

(That would clarify what’s being fixed.)

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

That’s not a great index entry because there’s no context.  Maybe:

  @cindex body, of a @code{let} expression


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

“Lambda-like body” is not defined; I guess it’s “lambda-like” in the
wrt. to local ‘define’, but it’s not “lambda-like” for the more crucial
aspect of defining a procedure, so I’d avoid that phrase.  WDYT?

Also, @ref in the middle of sentences may render poorly in Info (info
"(texinfo) @ref").  I’d suggest “(@pxref{Whatever})” at the end of the
sentence or proposition.

>  Each @code{cond}-clause must look like this:
>  @lisp
> -(@var{test} @var{body} @dots{})
> +(@var{test} @var{body})

I think removing dots is incorrect here because it suggests, according
to the typographic conventions used in the document, that there can only
be a single 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})


>  and the last @var{clause} may have the form
>  @lisp
> -(else @var{expr1} @var{body} @dots{})
> +(else @var{body})


> -@deffn {library syntax} receive formals expr body @dots{}
> +@deffn {library syntax} receive formals expr body


Otherwise LGTM; it’s certainly an improvement to have multiple-value
returns properly documented!


reply via email to

[Prev in Thread] Current Thread [Next in Thread]