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: Sat, 10 Jul 2010 07:14:14 -0700 Message-ID: References: <831vbcbl7n.fsf@gnu.org> <5500EFEE9A854408ABF0FE400497FE2D@us.oracle.com> <83tyo7aiay.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 1278772252 21130 80.91.229.12 (10 Jul 2010 14:30:52 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Sat, 10 Jul 2010 14:30:52 +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 Sat Jul 10 16:30:50 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 1OXb4f-000607-O6 for geb-bug-gnu-emacs@m.gmane.org; Sat, 10 Jul 2010 16:30:44 +0200 Original-Received: from localhost ([127.0.0.1]:50656 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OXb4c-0002ux-Oj for geb-bug-gnu-emacs@m.gmane.org; Sat, 10 Jul 2010 10:30:34 -0400 Original-Received: from [140.186.70.92] (port=58412 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OXb4C-0002kq-Bg for bug-gnu-emacs@gnu.org; Sat, 10 Jul 2010 10:30:13 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OXb4A-0006pn-J9 for bug-gnu-emacs@gnu.org; Sat, 10 Jul 2010 10:30:08 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:52236) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OXb4A-0006pj-GY for bug-gnu-emacs@gnu.org; Sat, 10 Jul 2010 10:30:06 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1OXaqY-0006Z2-59; Sat, 10 Jul 2010 10:16: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: Sat, 10 Jul 2010 14:16: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.127877130625225 (code B ref 6591); Sat, 10 Jul 2010 14:16:02 +0000 Original-Received: (at 6591) by debbugs.gnu.org; 10 Jul 2010 14:15:06 +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 1OXape-0006Yo-AP for submit@debbugs.gnu.org; Sat, 10 Jul 2010 10:15:06 -0400 Original-Received: from rcsinet10.oracle.com ([148.87.113.121]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OXapc-0006YE-Bj for 6591@debbugs.gnu.org; Sat, 10 Jul 2010 10:15: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 o6AEExRN013140 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sat, 10 Jul 2010 14:15:01 GMT Original-Received: from acsmt354.oracle.com (acsmt354.oracle.com [141.146.40.154]) by acsinet15.oracle.com (Switch-3.4.2/Switch-3.4.1) with ESMTP id o6AEEvif031898; Sat, 10 Jul 2010 14:14:58 GMT Original-Received: from abhmt019.oracle.com by acsmt353.oracle.com with ESMTP id 394654591278771253; Sat, 10 Jul 2010 07:14:13 -0700 Original-Received: from dradamslap1 (/141.144.160.29) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sat, 10 Jul 2010 07:14:12 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <83tyo7aiay.fsf@gnu.org> Thread-Index: AcsgBKdc96qo5GAET/WeI5wcb/qyKAALcNRQ X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5931 X-Source-IP: acsmt354.oracle.com [141.146.40.154] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090204.4C388063.01C9:SCFMA4539814,ss=1,fgs=0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Sat, 10 Jul 2010 10:16: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:38342 Archived-At: > 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. Ah! Then the syntax should be (catch TAG . BODY) or similar. When you write BODY... that indicates (at least to me, that catch and TAG can be followed by zero or more BODY sexps (or possibly one or more, depending on how the syntax description convention is defined). That's the point. BODY is a placeholder, presumably - whatever might be substitutable for it. BODY... is not a placeholder, presumably, but is a way of indicating that whatever is substituted for BODY can be repeated any number of times. At least that's the normal/typical way to express these things. The convention you use means that neither BODY nor BODY... is a placeholder for a Lisp form. > > "The forms of the BODY" is problematic - which BODY? > > There's only one, so no ambiguity here. The syntax BODY... does not suggest, to me, that there can be only one BODY. > > And it's incorrect. The forms within a BODY are not necessarily > > evaled in textual order. > > Example, please. If BODY is an arbitrary sexp, as I was assuming was indicated by BODY..., then choose the sexp you like that is not evaled in textual order. The typical sexp with args that are themselves sexps with args will be evaled in applicative order (innermost, left to right), which is depth-first, not necessarily "textual" order. But this is irrelevant now that you've said that BODY represents everything that follows TAG. In that case there is no problem, other than the poor choice of a syntax description method. When Common Lisp writes (catch TAG FORM*) that is clear and corresponds to typical ways to write such things. FORM is a Lisp form, and there can be any number (zero or more) such forms. > > 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. I think (now) that that is also the definition you are using. You are now saying that BODY is everything that follows TAG. That is what I was saying the word "body" suggests also, so I think we are agreed about that, at least. My problem was with (my assumption of) BODY being a placeholder and BODY... meaning zero or more occurrences of BODY. I was assuming that BODY... was the equivalent of BODY* in, say, the Common Lisp syntax description. What you are saying now means that BODY is not a placeholder for a sexp (form), and BODY... does not mean repetitions of BODY (there is only one), but rather BODY... is a placeholder for a list of sexps that are then _spliced_ in. IOW, (catch TAG . X), where X is the special placeholder `BODY...'. That's not an ordinary placeholder; that's not conventional syntax description. Hence my misunderstanding. > There's only one BODY. It consists of one or more forms. Yes, well that is not clear from the syntax description method you use, IMO. It is not a conventional method. Is it defined/described anywhere? > 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. We apparently have the same notion of "body". It is the syntax representation that is not clear. It might be well-defined and consistent, but it is not what one usually encounters. "There is one body." OK, but it is composed of zero or more sexps, and to indicate that fact you've chosen the unusual syntax `BODY...'. The "one body" does not correspond to BODY but to BODY..., and a reader must know that BODY is not a sexp (a form) and neither is BODY..., but that BODY... is a list of sexps (forms) that is _spliced_ in. The typical way to indicate this kind of thing is just (catch TAG FORM*), where TAG and FORM are placeholders for sexps and * means zero or more repetitions (so catch followed by a TAG, followed by zero or more FORMs. And then if you want to refer to the "body" as everything following TAG, just say that. > > 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). > > The former. > > Is this issue (using the phrase "BODY form") the only problem with the > doc string, or are there others? The doc only (manual and doc strings). At the very least, the unusual syntax convention X... needs to be spelled out somewhere. Perhaps it is, and I missed it. I looked, for example, in node Conventions of the Elisp manual (and its subnodes). In any case, you can imagine that it would be easy to miss such an explanation, wherever it might be. That's why it's important to use more conventional descriptions (BNF, railroad diagrams, etc.). It is NOT unusual to use `...' in a syntax description. But it typically means that the element it follows can be repeated (zero or one being the minimum, depending on the system). In the syntax descriptions you/we use, BODY... does not mean that BODY is repeated. And BODY is not even substitutable by a sexp - it is not substitutable at all. It is BODY... as a unit that is substitutable, and it too is not substitutable by a sexp (Lisp form) but by a (possibly empty) list of forms, and the substitution is then _spliced_ in. That is NOT a typical syntax description method. Using `...' but giving it a different meaning from the usual sows confusion. Note, BTW, that elsewhere in the doc and code comments we write this kind of thing as (A . B), not as (A B...) - at least when it comes to Lisp sexps. So some readers are already familiar with that syntax. I think (do you agree?) that we at least understand each other now.