From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#6591: 24.0.50; incorrect doc for `catch' Date: Sat, 10 Jul 2010 10:48:37 +0300 Message-ID: <83tyo7aiay.fsf@gnu.org> References: <831vbcbl7n.fsf@gnu.org> <5500EFEE9A854408ABF0FE400497FE2D@us.oracle.com> Reply-To: Eli Zaretskii NNTP-Posting-Host: lo.gmane.org X-Trace: dough.gmane.org 1278748833 25673 80.91.229.12 (10 Jul 2010 08:00:33 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Sat, 10 Jul 2010 08:00:33 +0000 (UTC) Cc: 6591@debbugs.gnu.org To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Jul 10 10:00:30 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 1OXUz4-0001NB-Rj for geb-bug-gnu-emacs@m.gmane.org; Sat, 10 Jul 2010 10:00:27 +0200 Original-Received: from localhost ([127.0.0.1]:35239 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OXUz3-0003zZ-Rm for geb-bug-gnu-emacs@m.gmane.org; Sat, 10 Jul 2010 04:00:25 -0400 Original-Received: from [140.186.70.92] (port=51553 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OXUyi-0003sW-H2 for bug-gnu-emacs@gnu.org; Sat, 10 Jul 2010 04:00:10 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OXUyg-0008Qi-Ey for bug-gnu-emacs@gnu.org; Sat, 10 Jul 2010 04:00:03 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:52447) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OXUyg-0008Qc-DQ for bug-gnu-emacs@gnu.org; Sat, 10 Jul 2010 04:00:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1OXUqv-0003Gc-Ib; Sat, 10 Jul 2010 03:52:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 10 Jul 2010 07:52:01 +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.127874827212548 (code B ref 6591); Sat, 10 Jul 2010 07:52:01 +0000 Original-Received: (at 6591) by debbugs.gnu.org; 10 Jul 2010 07:51:12 +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 1OXUq7-0003GL-T5 for submit@debbugs.gnu.org; Sat, 10 Jul 2010 03:51:12 -0400 Original-Received: from mtaout21.012.net.il ([80.179.55.169]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OXUq4-0003GG-4D for 6591@debbugs.gnu.org; Sat, 10 Jul 2010 03:51:10 -0400 Original-Received: from conversion-daemon.a-mtaout21.012.net.il by a-mtaout21.012.net.il (HyperSendmail v2007.08) id <0L5C008000A0O300@a-mtaout21.012.net.il> for 6591@debbugs.gnu.org; Sat, 10 Jul 2010 10:50:41 +0300 (IDT) Original-Received: from HOME-C4E4A596F7 ([77.127.120.144]) by a-mtaout21.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0L5C006EA0GF6D80@a-mtaout21.012.net.il>; Sat, 10 Jul 2010 10:50:41 +0300 (IDT) In-reply-to: <5500EFEE9A854408ABF0FE400497FE2D@us.oracle.com> X-012-Sender: halo1@inter.net.il X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Sat, 10 Jul 2010 03:52:01 -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:38337 Archived-At: > From: "Drew Adams" > Cc: <6591@debbugs.gnu.org> > Date: Fri, 9 Jul 2010 12:36:53 -0700 > > > > 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. Really? Then what's this about: > > > "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. "only one such sexp is allowed" -- what can be more clear? > You're missing the point. Probably because you didn't succeed explaining it. > Each BODY here can contain 8 million sexps. But there is not necessarily only > one BODY. BODY is by definition everything that follows TAG. That's it. Saying that there are multiple BODYs breaks the model on which the entire description is built. > 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. Sorry, I cannot parse all this. Maybe you are saying what I just said above, maybe not. At least I hope that I made myself clear. > "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? There's only one, so no ambiguity here. > And it's incorrect. The forms within a BODY are not necessarily > evaled in textual order. Example, please. > Is "the last body form" the last form in a BODY or the last BODY as a whole? The former. More accurately, "the last form in _the_ BODY", although doc strings traditionally omit "the", in effect treating arguments as proper names. > A BODY is a "form", and it is also composed of forms. Yes, but what's the problem here? A list can also be composed of lists, but that doesn't yet mean it's not a list. > Saying "evaluates _each_ BODY" instead of "evaluates the forms of _the_ BODY" > would be a big first improvement. There's only one BODY. > > 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. Unfortunately, that doesn't clarify anything. You got my poor self tangled in the web of "body", "BODYs", "forms", etc. Help me out. > I do not care what wording you choose, but please fix the problem. It would help to understand what is "the problem". Maybe instead of talking abstractions you could give a couple of examples that either follow the documentation but are incorrect, or contradict the docs while being correct. Then show how these mistakes are related to possible misreadings of the docs. > I _suggest_ that you not even use the term "BODY" when multiple such critters > are allowed There's only one BODY, by definition. > 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. You seem to use a different definition of BODY. Maybe that's your problem; don't. > 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. There's only one BODY. It consists of one or more forms. > But I see now that you've (we've) done the same thing for `progn', `let', etc. Exactly. > Dommage. Why? because it doesn't coincide with your notion of BODY? That's not a reason good enough to change large portions of the docs. > Use the term that way, if you want. The point is to then speak about > "body"/"BODY" consistently. Please show where do you see inconsistency in the documentation. > You cannot use the term to mean both (a) the set of > all sexps BODY... and (b) a single sexp, BODY, within that set. Where do we do that in the docs? > 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). The former. Is this issue (using the phrase "BODY form") the only problem with the doc string, or are there others? > 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). Sorry, I don't see the contradiction. Again, an example (using `catch', not just any isolated sexp) would help to make the discussion more productive. > The doc string of `let' has the same problem: > "The value of the last form in BODY is returned." Maybe this _consistency_ means that the problem is elsewhere, not in the use of BODY. Maybe you are reasoning in terms that are different from what the Emacs documentation uses. Please try to understand where's that difference come from. > It should say "the value of the last BODY". There's only one BODY. > if you mean the body of the `let', which can be considered all that > follows the declarations, then the statement is true Yes, that's what the documentation meant. > 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. BODY _is_ "the body". > My advice is to steer away from "body form" and "BODY" and try to clear things > up a bit. Clear up what? You still didn't explain the problem, at least not in terms that I can understand, although I'm already after my first coffee this morning. > 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. But that's the problem: I don't see these possible misreadings. Please help me realize what they are. Again, examples might help.