Hi Daniel, Chiming in late in the discussion…
lloda <ll...@sarc.name> skribis: > From 7aea299373f7370f31c9701035260ad412763724 Mon Sep 17 00:00:00 2001 > From: Daniel Llorens <ll...@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’.