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

["Drew Adams" <drew.adams@oracle.com>]

> > Is BODY repeated?
> 
> Yes.

Then there are multiple BODYs, which Eli denies.

And in that case, the accompanying text is incorrect and misleading, since it
speaks as if there is only one body (which Eli says is in fact the case).

You cannot have it both ways.  If BODY represents a sexp that can be repeated,
then there is not only one body that contains all of the sexps following TAG.
If BODY represents all of the sexps that follow tag, spliced in, then BODY is
not repeated.

Read the thread - this has all been gone over.


There are essentially two alternative solutions:

1. Use `...' to mean repetition of what it follows, as in the rest of the world.
And change BODY to FORM, in order not to mislead.  Then (catch TAG FORM...) says
exactly what it means: zero or more FORMs follow TAG.

2. Introduce an Emacs-only interpretation of `...' which means that what it
follows is a list to be spliced in.  In this case, postfix `...' is equivalent
to infix `.' (dot notation) and to a &rest parameter spec.


#2 is what Eli says that `...' means in Emacs syntax descriptions.  That is
unusual, but a legitimate choice.  Then (catch TAG BODY...) says that BODY is a
list of somethings (the accompanying text would say forms) that are spliced in.
So in (catch 'foo (a) (b) 42) the body is ((a) (b) 42).  The body is an implicit
`progn'.  BODY is a &rest parameter for `catch'.

If #2 is chosen, then the doc must explain the `...' notation somewhere. (It
should explain that notation in any case, but especially in the case where it
has an unconventional and unusual interpretation.)


#1 is my preference, because it is easier on readers and easier in terms of doc
maintenance.  It is consistent with what one finds outside Emacs.

What is a BUG is to use #2 with no explanation of the unusual syntax convention.