[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Add internal definitions to derived forms
|
From: |
lloda |
|
Subject: |
Re: Add internal definitions to derived forms |
|
Date: |
Tue, 24 Jan 2023 00:28:10 +0100 |
Hi Ludovic,
> On 23 Jan 2023, at 23:13, Ludovic Courtès <ludo@gnu.org> wrote:
>
> Hi Daniel,
>
> Chiming in late in the discussion…
>
> lloda <lloda@sarc.name> skribis:
>
>> 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.
>
> What about:
> s/Fix documentation…/doc: Document multiple-value returns in let, cond, etc./
> ?
>
> (That would clarify what’s being fixed.)
Ok.
>
>> +++ 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
>
> ?
Ok. I think the word is only used in this sense in the manual, but it might too
generic to be used alone.
>> +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?
Yes, I thought lambda-like was a tad distracting, so I went with 'body' alone...
> 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.
Ok.
>> 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})
>
> Ditto.
>
>> and the last @var{clause} may have the form
>>
>> @lisp
>> -(else @var{expr1} @var{body} @dots{})
>> +(else @var{body})
>
> Ditto.
>
>> -@deffn {library syntax} receive formals expr body @dots{}
>> +@deffn {library syntax} receive formals expr body
>
> Likewise.
This was actually the main thing I wanted to fix in this patch. Linus' patch
had ‘body ...’ but that clearly means ‘zero or more bodies’, which doesn't work
because there's exactly one ‘body’. I.e. ‘body’ isn't an expression that is
tagged ‘body’, it's, well, a ‘body’.
The Scheme reports use one ‘<body>’ and no dots in all these definitions. See
also the definition of let in the linked section ‘Local Bindings’, which again
uses ‘body’ and no dots. I hoped that section would count as definition of
‘body’, and the section on ‘Internal Definitions’ explains precisely what can
go into ‘body’, so I linked to that as well. I see that isn't clear enough.
Maybe ‘body’ should be explicitly defined in one of these sections?
> Otherwise LGTM; it’s certainly an improvement to have multiple-value
> returns properly documented!
>
> Thanks,
> Ludo’.