From: "Ludovic Courtès" <ludo@gnu.org>
To: lloda <lloda@sarc.name>
Cc: 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: Mon, 23 Jan 2023 23:13:00 +0100 [thread overview]
Message-ID: <87h6wgzyqb.fsf@gnu.org> (raw)
In-Reply-To: <A85CEA01-8397-4758-B197-ED2CEF5F0698@sarc.name> (lloda@sarc.name's message of "Fri, 20 Jan 2023 18:37:48 +0100")
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.)
> +++ 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})
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.
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 22:13 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 [this message]
2023-01-23 23:28 ` lloda
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=87h6wgzyqb.fsf@gnu.org \
--to=ludo@gnu.org \
--cc=guile-devel@gnu.org \
--cc=lassi@lassi.io \
--cc=linus.bjornstam@veryfast.biz \
--cc=lloda@sarc.name \
/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).