From: lloda <lloda@sarc.name>
To: "Ludovic Courtès" <ludo@gnu.org>
Cc: "guile-devel@gnu.org" <guile-devel@gnu.org>,
"Linus Björnstam" <linus.bjornstam@veryfast.biz>,
"Lassi Kortela" <lassi@lassi.io>
Subject: Re: Add internal definitions to derived forms
Date: Tue, 24 Jan 2023 00:28:10 +0100 [thread overview]
Message-ID: <588FD427-B3C2-4946-83E9-74978E2D3C62@sarc.name> (raw)
In-Reply-To: <87h6wgzyqb.fsf@gnu.org>
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’.
next prev parent reply other threads:[~2023-01-23 23:28 UTC|newest]
Thread overview: 22+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-11-09 15:32 Add internal definitions to derived forms Linus Björnstam
2022-11-09 15:46 ` Damien Mattei
2022-11-17 7:25 ` lloda
2022-11-18 9:04 ` Linus Björnstam
2022-11-18 9:27 ` Lassi Kortela
2022-11-18 9:50 ` Linus Björnstam
2022-11-18 10:22 ` Lassi Kortela
2022-11-18 12:53 ` Linus Björnstam
2022-11-18 13:18 ` Lassi Kortela
2023-01-19 17:54 ` lloda
2023-01-20 17:37 ` lloda
2023-01-23 22:13 ` Ludovic Courtès
2023-01-23 23:28 ` lloda [this message]
2023-01-24 7:33 ` Linus Björnstam
2023-01-24 9:02 ` Ludovic Courtès
2023-01-24 17:59 ` lloda
2023-01-25 10:33 ` Ludovic Courtès
2023-01-25 15:09 ` Ludovic Courtès
2023-01-25 15:38 ` Greg Troxel
2023-01-25 21:38 ` Linus Björnstam
2023-01-25 21:06 ` Linus Björnstam
2023-02-02 11:17 ` lloda
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/guile/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=588FD427-B3C2-4946-83E9-74978E2D3C62@sarc.name \
--to=lloda@sarc.name \
--cc=guile-devel@gnu.org \
--cc=lassi@lassi.io \
--cc=linus.bjornstam@veryfast.biz \
--cc=ludo@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).