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

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

> > 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.
> 
> Using FORM... is okay, but will need more extensive changes, so I'd
> rather not do it.  I'd like to simply remove the dots after BODY, and
> explain in the text that BODY can consist of one or more forms.

AND that list of forms is SPLICED IN.  That's the important part that needs to
be made clear if you take your approach.

IOW, reading what you just wrote, a reader will assume that BODY might be (A B
C) when what you meant was A B C.  E.g. this is not valid: (catch 'foo ((setq a
b) (terpri) (set-buffer z))).  But it follows your description fine: "BODY can
consist of one or more forms".

We will agree to disagree on this one.

IMO, readers will not be helped, and doc maintenance will be increased in the
long run, by doing what you suggest.  There is a mismatch between what someone
sees in the syntax description, (catch TAG BODY), and what the surrounding text
needs to say in order to explain that syntax.

A user sees TAG and BODY directly, and naturally supposes that each is a
placeholder and the kind of thing substitutable for each placeholder is the same
or similar.

The text needs (at *each* occurrence of this phenomenon) to explain that this is
not the case: TAG is replaceable by a sexp, BODY is replaceable by a list of
sexps, but the list is spliced in.

It's easy enough to say that in `(A B C)' A is a placeholder for a function
symbol, B for an integer and C for any sexp (or whatever) - the types of the
placeholders are straightforward.  It is not so easy to explain that BODY in
(catch TAG BODY) is a list of sexps but that list has no surrounding parens etc.

It's your call, but in the long run what you propose will lead to more complex,
confusing doc and increased doc maintenance.  That will help neither reader nor
writer.

> Does anyone see any reason why keeping the dots in BODY... will have
> some didactical importance?  Richard? Stefan? Yidong?