bug#6591: 24.0.50; incorrect doc for `catch'

[Drew Adams]

> > to BODY as if there were only one BODY, and it refers to 
> > "the forms of the BODY", by which it probably means to
> > refer to the BODYs, that is, the BODY items in the list
> > (BODY...).
> >  
> > "BODY" is anyway the wrong term to use here, as it suggests 
> > (even if it does not imply) that only one such sexp is
> > allowed.  But more importantly, it is incorrect to refer to
> > "the forms of the BODY" when what is really meant is the
> > list of BODYs.
> 
> No, ``forms of BODY'' is correct.  No one said that BODY can contain
> only one sexp.

No one, including me.  You're missing the point.

Each BODY here can contain 8 million sexps.  But there is not necessarily only
one BODY.

And a BODY here is not an implicit `progn'.  A BODY here is not just a list of
sexps that are evaled and whose value is the value of the last sexp in the list.
A BODY here is an arbitrary sexp.  The value of each BODY is just its value as a
sexp.  The BODY value is not the value of the last sexp contained within the
BODY.

Any BODY _could_ be an explicit `progn', which contains sexps that are evaled in
sequence and whose value is the value of the last one.  But that "value of the
last one" part then comes from the meaning of `progn', not from BODY being an
arbitrary sexp.

You cannot write (catch 'foo ((setq a b) (+ 1 4))), which is (catch TAG BODY)
with a single BODY that contains two sexps.  A BODY is not an implicit `progn'.
The value of any BODY in BODY... is simply its value as a sexp (evaled).

It is not the (value of the) last form in THE body that is returned.  Unless you
meant the "body" of the (catch...) - that is everything that follows TAG, and
not one BODY in BODY....  But if you say "body" you imply (at least suggest)
that you are referring to a BODY.

It is the (value of the) last BODY among the list of bodies that is returned.

> > When the doc says "the value of the last body form is
> > returned" it really means that the value of the last
> > BODY sexp is returned - not the last form in BODY.
> 
> What's the difference?

Body as form, not form within body.  If you want to speak about a form (the last
one) within BODY, then you need to also state which BODY you mean in BODY....

"Last body form" is ambiguous.  Does it mean the last BODY in BODY... or the
last sexp within (some) BODY?  Make clear that you are talking about one BODY
among the possibly multiple bodies: the last BODY.

The description is not consistent and clear.  In particular, this part:

 "With the return point in effect, `catch' evaluates the forms of the
  BODY in textual order.  If the forms execute normally (without
  error or nonlocal exit) the value of the last body form is
  returned from the `catch'."

"The forms of the BODY" is problematic - which BODY?  And it's incorrect.  The
forms within a BODY are not necessarily evaled in textual order.

Is "the last body form" the last form in a BODY or the last BODY as a whole? A
BODY is a "form", and it is also composed of forms.  Be clear which you mean at
each point in the text.

Saying "evaluates _each_ BODY" instead of "evaluates the forms of _the_ BODY"
would be a big first improvement.

I do not care what exact wording you use.  The point is that the text is not
clear as is.

> IMO, it doesn't make sense to talk about "BODYs", since the whole
> doc string doesn't make sense then.

I do _not_ suggest to use the term "BODYs".  See above for clarification.  I do
not care what wording you choose, but please fix the problem.

> And please don't argue: this is my opinion, and we don't have to
> agree.

Can we agree about the _problem_?  If you see the problem, then I'll leave it up
to you what wording you want for the solution.

I _suggest_ that you not even use the term "BODY" when multiple such critters
are allowed, because "body" typically refers to _the_ main part (not parts) of
something.  A `progn' has a single body (composed of multiple sexps/forms).
Likewise a `let', an HTML page, etc.

[Common Lisp doc shows (progn FORM*), not (progn BODY*).  Likewise, its syntax
for `let' etc.  AFAICT, it is only the Emacs Lisp doc that uses the weird
convention of BODY...]

This use of "BODY" has tripped up the language of the Emacs doc: We speak of the
last form in the body, where by "the body" we really mean the whole BODY..., not
any single BODY.

But I see now that you've (we've) done the same thing for `progn', `let', etc.
Dommage.

I suggest changing BODY to FORM or SEXP for all cases where we currently have
"BODY...".  But that part of my report is only a (minor) _suggestion_.  I have
no big problem with your using "BODY" in this way, even though the word suggests
something different from what is meant.

Use the term that way, if you want. The point is to then speak about
"body"/"BODY" consistently.  You cannot use the term to mean both (a) the set of
all sexps BODY... and (b) a single sexp, BODY, within that set.

The real problem is not the word "body" - if you use it consistently.  It is the
ambiguity in speaking about "BODY form" etc.  It is not sufficiently clear when
you mean a form within a BODY or BODY itself (it is a form).

A second problem is giving the impression that the value of a BODY is the value
of the last form within it.  That is incorrect.  No BODY here is an implicit
`progn'.  Each is an ordinary sexp, and its value is determined normally.  The
value of the ordinary sexp (+ 2 5) is 7, not 5 (which is the value of the last
sexp within it).

The doc string of `let' has the same problem:
"The value of the last form in BODY is returned."

It should say "the value of the last BODY".  Each BODY is a sexp, and none of
those sexps are implicit `progn's.  `let' itself has an implicit `progn', and if
you mean the body of the `let', which can be considered all that follows the
declarations, then the statement is true: it does return the value of the last
form in the body (in that sense).  But not 'the last form in BODY", because BODY
is just one of the sexps in the body.

My advice is to steer away from "body form" and "BODY" and try to clear things
up a bit.  Reread the doc text _trying_ to look for possible misreadings.  If
you recognize the problem then I'm sure you'll do a fine job of fixing it.
Thanks.