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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <6591@debbugs.gnu.org>
> Date: Fri, 9 Jul 2010 12:36:53 -0700
> 
> > > 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.

Really?  Then what's this about:

> > > "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.

"only one such sexp is allowed" -- what can be more clear?

> You're missing the point.

Probably because you didn't succeed explaining it.

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

BODY is by definition everything that follows TAG.  That's it.  Saying
that there are multiple BODYs breaks the model on which the entire
description is built.

> 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.

Sorry, I cannot parse all this.  Maybe you are saying what I just said
above, maybe not.  At least I hope that I made myself clear.

>  "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?

There's only one, so no ambiguity here.

> And it's incorrect.  The forms within a BODY are not necessarily
> evaled in textual order.

Example, please.

> Is "the last body form" the last form in a BODY or the last BODY as a whole?

The former.  More accurately, "the last form in _the_ BODY", although
doc strings traditionally omit "the", in effect treating arguments as
proper names.

> A BODY is a "form", and it is also composed of forms.

Yes, but what's the problem here?  A list can also be composed of
lists, but that doesn't yet mean it's not a list.

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

There's only one BODY.

> > 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.

Unfortunately, that doesn't clarify anything.  You got my poor self
tangled in the web of "body", "BODYs", "forms", etc.  Help me out.

> I do not care what wording you choose, but please fix the problem.

It would help to understand what is "the problem".  Maybe instead of
talking abstractions you could give a couple of examples that either
follow the documentation but are incorrect, or contradict the docs
while being correct.  Then show how these mistakes are related to
possible misreadings of the docs.

> I _suggest_ that you not even use the term "BODY" when multiple such critters
> are allowed

There's only one BODY, by definition.

> 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.

You seem to use a different definition of BODY.  Maybe that's your
problem; don't.

> 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.

There's only one BODY.  It consists of one or more forms.

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

Exactly.

> Dommage.

Why? because it doesn't coincide with your notion of BODY?  That's not
a reason good enough to change large portions of the docs.

> Use the term that way, if you want. The point is to then speak about
> "body"/"BODY" consistently.

Please show where do you see inconsistency in the documentation.

> You cannot use the term to mean both (a) the set of
> all sexps BODY... and (b) a single sexp, BODY, within that set.

Where do we do that in the docs?

> 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).

The former.

Is this issue (using the phrase "BODY form") the only problem with the
doc string, or are there others?

> 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).

Sorry, I don't see the contradiction.  Again, an example (using
`catch', not just any isolated sexp) would help to make the discussion
more productive.

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

Maybe this _consistency_ means that the problem is elsewhere, not in
the use of BODY.  Maybe you are reasoning in terms that are different
from what the Emacs documentation uses.  Please try to understand
where's that difference come from.

> It should say "the value of the last BODY".

There's only one BODY.

> if you mean the body of the `let', which can be considered all that
> follows the declarations, then the statement is true

Yes, that's what the documentation meant.

> 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.

BODY _is_ "the body".

> My advice is to steer away from "body form" and "BODY" and try to clear things
> up a bit.

Clear up what?  You still didn't explain the problem, at least not in
terms that I can understand, although I'm already after my first
coffee this morning.

> 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.

But that's the problem: I don't see these possible misreadings.
Please help me realize what they are.  Again, examples might help.