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

[Drew Adams]

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

Ah! Then the syntax should be (catch TAG . BODY) or similar.  When you write
BODY... that indicates (at least to me, that catch and TAG can be followed by
zero or more BODY sexps (or possibly one or more, depending on how the syntax
description convention is defined).

That's the point.  BODY is a placeholder, presumably - whatever might be
substitutable for it.  BODY... is not a placeholder, presumably, but is a way of
indicating that whatever is substituted for BODY can be repeated any number of
times.

At least that's the normal/typical way to express these things.  The convention
you use means that neither BODY nor BODY... is a placeholder for a Lisp form.

> > "The forms of the BODY" is problematic - which BODY?
> 
> There's only one, so no ambiguity here.

The syntax BODY... does not suggest, to me, that there can be only one BODY.

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

If BODY is an arbitrary sexp, as I was assuming was indicated by BODY..., then
choose the sexp you like that is not evaled in textual order.  The typical sexp
with args that are themselves sexps with args will be evaled in applicative
order (innermost, left to right), which is depth-first, not necessarily
"textual" order.

But this is irrelevant now that you've said that BODY represents everything that
follows TAG.  In that case there is no problem, other than the poor choice of a
syntax description method.

When Common Lisp writes (catch TAG FORM*) that is clear and corresponds to
typical ways to write such things. FORM is a Lisp form, and there can be any
number (zero or more) such forms.

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

I think (now) that that is also the definition you are using.  You are now
saying that BODY is everything that follows TAG.  That is what I was saying the
word "body" suggests also, so I think we are agreed about that, at least.

My problem was with (my assumption of) BODY being a placeholder and BODY...
meaning zero or more occurrences of BODY.  I was assuming that BODY... was the
equivalent of BODY* in, say, the Common Lisp syntax description.

What you are saying now means that BODY is not a placeholder for a sexp (form),
and BODY... does not mean repetitions of BODY (there is only one), but rather
BODY... is a placeholder for a list of sexps that are then _spliced_ in.  IOW,
(catch TAG . X), where X is the special placeholder `BODY...'.

That's not an ordinary placeholder; that's not conventional syntax description.
Hence my misunderstanding.

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

Yes, well that is not clear from the syntax description method you use, IMO.  It
is not a conventional method.  Is it defined/described anywhere?

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

We apparently have the same notion of "body".  It is the syntax representation
that is not clear.  It might be well-defined and consistent, but it is not what
one usually encounters.

"There is one body."  OK, but it is composed of zero or more sexps, and to
indicate that fact you've chosen the unusual syntax `BODY...'.

The "one body" does not correspond to BODY but to BODY..., and a reader must
know that BODY is not a sexp (a form) and neither is BODY..., but that BODY...
is a list of sexps (forms) that is _spliced_ in.

The typical way to indicate this kind of thing is just (catch TAG FORM*), where
TAG and FORM are placeholders for sexps and * means zero or more repetitions (so
catch followed by a TAG, followed by zero or more FORMs.  And then if you want
to refer to the "body" as everything following TAG, just say that.

> > 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).
> 
> The former.
> 
> Is this issue (using the phrase "BODY form") the only problem with the
> doc string, or are there others?

The doc only (manual and doc strings).

At the very least, the unusual syntax convention X... needs to be spelled out
somewhere.  Perhaps it is, and I missed it.  I looked, for example, in node
Conventions of the Elisp manual (and its subnodes).

In any case, you can imagine that it would be easy to miss such an explanation,
wherever it might be.  That's why it's important to use more conventional
descriptions (BNF, railroad diagrams, etc.).

It is NOT unusual to use `...' in a syntax description.  But it typically means
that the element it follows can be repeated (zero or one being the minimum,
depending on the system).  In the syntax descriptions you/we use, BODY... does
not mean that BODY is repeated.  And BODY is not even substitutable by a sexp -
it is not substitutable at all.

It is BODY... as a unit that is substitutable, and it too is not substitutable
by a sexp (Lisp form) but by a (possibly empty) list of forms, and the
substitution is then _spliced_ in.

That is NOT a typical syntax description method.  Using `...' but giving it a
different meaning from the usual sows confusion.

Note, BTW, that elsewhere in the doc and code comments we write this kind of
thing as (A . B), not as (A B...) - at least when it comes to Lisp sexps.  So
some readers are already familiar with that syntax.

I think (do you agree?) that we at least understand each other now.