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

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

> >> The dots are important, because BODY normally implies one 
> >> single form.  We are somewhat abusing notation by using
> >> `BODY...' to denote one or more forms, but the convention
> >> is well-established and easy to grasp,
> >> and there are no better alternatives.
> >
> > No better alternative?  Did you read the thread?  What about doing
> > what the rest of the world does: (catch TAG FORM...)?
> 
> Either BODY... or FORM... seems fine by me.  It seems clearer to use
> BODY... and refer to "BODY forms" in the text, than to use FORM... and
> refer to "each FORM" in the text.  But it is a marginal difference,

You are missing the point, but I won't beat a dead horse.  I explained myself
clearly, I think, for anyone who is willing and able to read.

> and I don't think anyone gets confused in practice.

If you read the thread, then you should not think that.  _I_ got confused in
practice, which is why I filed the bug report.

I could not remember whether `catch' allows multiple sexps after the tag (i.e.
has an implicit `progn'), so I consulted the doc, which I found misleading and
confusing.[*]

IOW, just to find out whether I needed to use an explicit `progn' after the tag
in order to eval multiple sexps, I landed in a doc morass where `BODY...' does
not in fact mean repetitions of BODY as it does in the rest of the known
universe.

For further clarity, I grepped the Emacs Lisp sources for examples, and I found
_only_ uses of `catch' with a _single_ sexp.  That added to my confusion.  And
when I finally figured that an implicit `progn' was used, the exclusive use of
only one sexp in our source code suggested to me that perhaps some Emacs
developers might also have been confused and so never tried using more than one
sexp.


[* I sometimes forget such things.  One that I keep coming back to is
`unwind-protect', which does _not_ protect multiple sexps (you need to use an
explicit `progn' if you want to do that).  

Note, BTW, that in MacLisp the syntax was `(catch FORM TAG)', where _only one_
sexp was allowed.  Note too that the MacLisp doc for `*catch' (which replaced
`catch') shows its syntax as `(*catch tagspec . body)' - note the use of dot
notation in a syntax description. http://maclisp.info/pitmanual/contro.html]