From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs Subject: bug#6591: 24.0.50; incorrect doc for `catch' Date: Fri, 9 Jul 2010 12:36:53 -0700 Message-ID: <5500EFEE9A854408ABF0FE400497FE2D@us.oracle.com> References: <831vbcbl7n.fsf@gnu.org> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: dough.gmane.org 1278705618 27126 80.91.229.12 (9 Jul 2010 20:00:18 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Fri, 9 Jul 2010 20:00:18 +0000 (UTC) Cc: 6591@debbugs.gnu.org To: "'Eli Zaretskii'" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Jul 09 22:00:15 2010 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1OXJk4-0004o5-Oi for geb-bug-gnu-emacs@m.gmane.org; Fri, 09 Jul 2010 22:00:13 +0200 Original-Received: from localhost ([127.0.0.1]:58253 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OXJk4-0004EU-4t for geb-bug-gnu-emacs@m.gmane.org; Fri, 09 Jul 2010 16:00:12 -0400 Original-Received: from [140.186.70.92] (port=41485 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OXJjx-0004DJ-Gy for bug-gnu-emacs@gnu.org; Fri, 09 Jul 2010 16:00:06 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OXJjs-0006I6-Tr for bug-gnu-emacs@gnu.org; Fri, 09 Jul 2010 16:00:02 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:42845) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OXJjs-0006Hx-Op for bug-gnu-emacs@gnu.org; Fri, 09 Jul 2010 16:00:00 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1OXJOc-0006mO-Fz; Fri, 09 Jul 2010 15:38:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 09 Jul 2010 19:38:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 6591 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 6591-submit@debbugs.gnu.org id=B6591.127870422926047 (code B ref 6591); Fri, 09 Jul 2010 19:38:02 +0000 Original-Received: (at 6591) by debbugs.gnu.org; 9 Jul 2010 19:37:09 +0000 Original-Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OXJNj-0006m2-WF for submit@debbugs.gnu.org; Fri, 09 Jul 2010 15:37:08 -0400 Original-Received: from rcsinet10.oracle.com ([148.87.113.121]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OXJNg-0006lg-Nt for 6591@debbugs.gnu.org; Fri, 09 Jul 2010 15:37:05 -0400 Original-Received: from acsinet15.oracle.com (acsinet15.oracle.com [141.146.126.227]) by rcsinet10.oracle.com (Switch-3.4.2/Switch-3.4.2) with ESMTP id o69JavHF019066 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Fri, 9 Jul 2010 19:36:59 GMT Original-Received: from acsmt353.oracle.com (acsmt353.oracle.com [141.146.40.153]) by acsinet15.oracle.com (Switch-3.4.2/Switch-3.4.1) with ESMTP id o69D6qu1025282; Fri, 9 Jul 2010 19:36:56 GMT Original-Received: from abhmt017.oracle.com by acsmt354.oracle.com with ESMTP id 393503801278704214; Fri, 09 Jul 2010 12:36:54 -0700 Original-Received: from dradamslap1 (/10.175.236.134) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Fri, 09 Jul 2010 12:36:54 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <831vbcbl7n.fsf@gnu.org> Thread-Index: Acsfjw4/ovU1biKpS9q0LwkcMa7QpwAALiOA X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5931 X-Source-IP: acsmt353.oracle.com [141.146.40.153] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A0B020A.4C377A59.00F8:SCFMA4539814,ss=1,fgs=0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Fri, 09 Jul 2010 15:38:02 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:38324 Archived-At: > > 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. > > No, ``forms of BODY'' is correct. No one said that BODY can contain > only one sexp. No one, including me. You're missing the point. Each BODY here can contain 8 million sexps. But there is not necessarily only one BODY. And a BODY here is not an implicit `progn'. A BODY here is not just a list of sexps that are evaled and whose value is the value of the last sexp in the list. A BODY here is an arbitrary sexp. The value of each BODY is just its value as a sexp. The BODY value is not the value of the last sexp contained within the BODY. Any BODY _could_ be an explicit `progn', which contains sexps that are evaled in sequence and whose value is the value of the last one. But that "value of the last one" part then comes from the meaning of `progn', not from BODY being an arbitrary sexp. You cannot write (catch 'foo ((setq a b) (+ 1 4))), which is (catch TAG BODY) with a single BODY that contains two sexps. A BODY is not an implicit `progn'. The value of any BODY in BODY... is simply its value as a sexp (evaled). It is not the (value of the) last form in THE body that is returned. Unless you meant the "body" of the (catch...) - that is everything that follows TAG, and not one BODY in BODY.... But if you say "body" you imply (at least suggest) that you are referring to a BODY. It is the (value of the) last BODY among the list of bodies that is returned. > > 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. > > What's the difference? Body as form, not form within body. If you want to speak about a form (the last one) within BODY, then you need to also state which BODY you mean in BODY.... "Last body form" is ambiguous. Does it mean the last BODY in BODY... or the last sexp within (some) BODY? Make clear that you are talking about one BODY among the possibly multiple bodies: the last BODY. The description is not consistent and clear. In particular, this part: "With the return point in effect, `catch' evaluates the forms of the BODY in textual order. If the forms execute normally (without error or nonlocal exit) the value of the last body form is returned from the `catch'." "The forms of the BODY" is problematic - which BODY? And it's incorrect. The forms within a BODY are not necessarily evaled in textual order. Is "the last body form" the last form in a BODY or the last BODY as a whole? A BODY is a "form", and it is also composed of forms. Be clear which you mean at each point in the text. Saying "evaluates _each_ BODY" instead of "evaluates the forms of _the_ BODY" would be a big first improvement. I do not care what exact wording you use. The point is that the text is not clear as is. > IMO, it doesn't make sense to talk about "BODYs", since the whole > doc string doesn't make sense then. I do _not_ suggest to use the term "BODYs". See above for clarification. I do not care what wording you choose, but please fix the problem. > And please don't argue: this is my opinion, and we don't have to > agree. Can we agree about the _problem_? If you see the problem, then I'll leave it up to you what wording you want for the solution. I _suggest_ that you not even use the term "BODY" when multiple such critters are allowed, because "body" typically refers to _the_ main part (not parts) of something. A `progn' has a single body (composed of multiple sexps/forms). Likewise a `let', an HTML page, etc. [Common Lisp doc shows (progn FORM*), not (progn BODY*). Likewise, its syntax for `let' etc. AFAICT, it is only the Emacs Lisp doc that uses the weird convention of BODY...] This use of "BODY" has tripped up the language of the Emacs doc: We speak of the last form in the body, where by "the body" we really mean the whole BODY..., not any single BODY. But I see now that you've (we've) done the same thing for `progn', `let', etc. Dommage. I suggest changing BODY to FORM or SEXP for all cases where we currently have "BODY...". But that part of my report is only a (minor) _suggestion_. I have no big problem with your using "BODY" in this way, even though the word suggests something different from what is meant. Use the term that way, if you want. The point is to then speak about "body"/"BODY" consistently. You cannot use the term to mean both (a) the set of all sexps BODY... and (b) a single sexp, BODY, within that set. The real problem is not the word "body" - if you use it consistently. It is the ambiguity in speaking about "BODY form" etc. It is not sufficiently clear when you mean a form within a BODY or BODY itself (it is a form). A second problem is giving the impression that the value of a BODY is the value of the last form within it. That is incorrect. No BODY here is an implicit `progn'. Each is an ordinary sexp, and its value is determined normally. The value of the ordinary sexp (+ 2 5) is 7, not 5 (which is the value of the last sexp within it). The doc string of `let' has the same problem: "The value of the last form in BODY is returned." It should say "the value of the last BODY". Each BODY is a sexp, and none of those sexps are implicit `progn's. `let' itself has an implicit `progn', and if you mean the body of the `let', which can be considered all that follows the declarations, then the statement is true: it does return the value of the last form in the body (in that sense). But not 'the last form in BODY", because BODY is just one of the sexps in the body. My advice is to steer away from "body form" and "BODY" and try to clear things up a bit. Reread the doc text _trying_ to look for possible misreadings. If you recognize the problem then I'm sure you'll do a fine job of fixing it. Thanks.