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

From: "Drew Adams" <[email-masked]>
Date: Fri, 9 Jul 2010 08:52:05 -0700

Both in the doc string and the Elisp manual the doc for `catch' is
wrong, or at best misleading.
 
The syntax is given as (catch TAG BODY...).  But the description refers
to BODY as if there were only one BODY, and it refers to "the forms of
the BODY", by which it probably means to refer to the BODYs, that is,
the BODY items in the list (BODY...).
 
"BODY" is anyway the wrong term to use here, as it suggests (even if it
does not imply) that only one such sexp is allowed.  But more
importantly, it is incorrect to refer to "the forms of the BODY" when
what is really meant is the list of BODYs.
 
When the doc says "the value of the last body form is returned" it
really means that the value of the last BODY sexp is returned - not the
last form in BODY.  (In this case, the wording would not be so bad, if
the rest of the passage were correct and clear - and if BODY were
uppercase.)
 
If you grep the Emacs Lisp sources, you will find very few uses (none?)
of `catch' where there is more than one BODY sexp.  Dunno if this might
partly be a result of confusion over the syntax.  Probably not.  But it
wouldn't hurt to clarify the doc, making it clear that you can have any
number of sexps after TAG, and that the value of the last such sexp is
returned if no throw occurs.
 
And do not call these sexps "bodies" - there is typically only one
"body" in a Lisp form.  You might speak of the "body" of a `progn', a
`let', or a `catch', but you should not call each of the sexps in such a
body "BODY".  Together, the sexps in a `progn' form its body, but each
is not individually a BODY.
 
In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2010-06-28 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4) --no-opt --cflags -Ic:/xpm/include'