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

[Drew Adams]

> I was thinking of modifying the docs to say `catch TAG BODY' and
> explaining in the text that BODY can be one or more forms.
> 
> The problem with the period is that it could be misunderstood to mean
> that a period must be present in the catch form at this point, which
> is false.

I agree that the (A . B) notation is probably not the best one to use for this
kind of thing.  I just mentioned it to point out (a) that that is what is
involved in the notation you are using and your interpretation of it: splicing,
and (b) we do in fact use (A . B) notation at some places in our doc (but more
for Lisp lists regarded as data structures, not lists regarded as sexps to be
evaled).

The syntax for something like (catch TAG . BODY) is commonly written not that
way but the way the Common Lisp doc writes it: not in terms of BODY but in terms
of what can follow TAG: zero or more forms (sexps).  As I said, they write the
syntax this way:

 (catch TAG {FORM}*)

In the Oracle docs (FWIW) we use a form of BNF.  We would write it this way:

 (catch TAG FORM...)

The ellipsis indicates that a FORM can be repeated any number of times,
including zero times.

How does that differ from the Emacs (catch TAG BODY...)?  It doesn't!  Which is
why I wrote this bug report.  It is the text that accompanied that syntax
description that didn't fit with it.  Using BODY instead of FORM, and then
speaking as if "body" referred not to an arbitrary individual sexp that can be
repeated but collectively to everything that follows TAG is, IMO,
inconsistent/misleading.

But your reply indicated that you viewed `BODY...' collectively as the "body"
(not BODY as the "body"), so `BODY...' for you (Emacs) is a kind of splice
notation.

You objected to my interpretation of the syntax description as indicating
repetitions of BODY, and my complaint that what was repeated was not a "body".
You made it clear that there was only one "body", corresponding to only one
`BODY...' (which is not a repetition of BODY).

I agreed that your way of looking at it is OK, but in that case, the `BODY...'
syntax needs to be defined for readers.  And since it looks just like the more
common syntax description where X... means repetitions of X, some readers are
bound to be confused.

That's were we left the discussion.  If you now say that you are open to looking
for another syntax to use, then I would return to my initial suggestion (but I
won't argue that it is the only good approach): use `...' to mean repetitions of
whatever it follows, in this case a sexp, and thus write (catch TAG FORM...).
Introducing a grouping syntax operator (e.g. braces: {}), so the scope of the
ellipsis can be controlled - e.g. (A B {C D}... E...) meaning that C D repeats
and E repeats.

Anyway, I think we understand each other now and I don't want to annoy you about
this anymore.  I'll be glad to give feedback on whatever you propose or come up
with, if you want.  Otherwise, I leave it up to you to decide what should be
done.  I've already said that I think things are a bit unclear to readers as
they stand now (even if they are not incorrect), so I hope that something
clearer is used.  But I won't push it.

Thanks for considering this.