From: "Drew Adams" <drew.adams@oracle.com>
To: "'Eli Zaretskii'" <eliz@gnu.org>
Cc: 6591@debbugs.gnu.org
Subject: bug#6591: 24.0.50; incorrect doc for `catch'
Date: Sat, 10 Jul 2010 21:21:04 -0700 [thread overview]
Message-ID: <38AC360676154EFF8DF9F35945B6EFAE@us.oracle.com> (raw)
In-Reply-To: <83y6djuyah.fsf@gnu.org>
> I was thinking of modifying the docs to say `catch TAG BODY' and
> explaining in the text that BODY can be one or more forms.
>
> The problem with the period is that it could be misunderstood to mean
> that a period must be present in the catch form at this point, which
> is false.
I agree that the (A . B) notation is probably not the best one to use for this
kind of thing. I just mentioned it to point out (a) that that is what is
involved in the notation you are using and your interpretation of it: splicing,
and (b) we do in fact use (A . B) notation at some places in our doc (but more
for Lisp lists regarded as data structures, not lists regarded as sexps to be
evaled).
The syntax for something like (catch TAG . BODY) is commonly written not that
way but the way the Common Lisp doc writes it: not in terms of BODY but in terms
of what can follow TAG: zero or more forms (sexps). As I said, they write the
syntax this way:
(catch TAG {FORM}*)
In the Oracle docs (FWIW) we use a form of BNF. We would write it this way:
(catch TAG FORM...)
The ellipsis indicates that a FORM can be repeated any number of times,
including zero times.
How does that differ from the Emacs (catch TAG BODY...)? It doesn't! Which is
why I wrote this bug report. It is the text that accompanied that syntax
description that didn't fit with it. Using BODY instead of FORM, and then
speaking as if "body" referred not to an arbitrary individual sexp that can be
repeated but collectively to everything that follows TAG is, IMO,
inconsistent/misleading.
But your reply indicated that you viewed `BODY...' collectively as the "body"
(not BODY as the "body"), so `BODY...' for you (Emacs) is a kind of splice
notation.
You objected to my interpretation of the syntax description as indicating
repetitions of BODY, and my complaint that what was repeated was not a "body".
You made it clear that there was only one "body", corresponding to only one
`BODY...' (which is not a repetition of BODY).
I agreed that your way of looking at it is OK, but in that case, the `BODY...'
syntax needs to be defined for readers. And since it looks just like the more
common syntax description where X... means repetitions of X, some readers are
bound to be confused.
That's were we left the discussion. 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.
Anyway, I think we understand each other now and I don't want to annoy you about
this anymore. I'll be glad to give feedback on whatever you propose or come up
with, if you want. Otherwise, I leave it up to you to decide what should be
done. I've already said that I think things are a bit unclear to readers as
they stand now (even if they are not incorrect), so I hope that something
clearer is used. But I won't push it.
Thanks for considering this.
next prev parent reply other threads:[~2010-07-11 4:21 UTC|newest]
Thread overview: 51+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-07-09 15:52 bug#6591: 24.0.50; incorrect doc for `catch' Drew Adams
2010-07-09 17:48 ` Eli Zaretskii
2010-07-09 19:36 ` Drew Adams
2010-07-10 7:48 ` Eli Zaretskii
2010-07-10 14:14 ` Drew Adams
2010-07-10 14:38 ` Eli Zaretskii
2010-07-10 15:44 ` Drew Adams
2010-07-10 15:55 ` Eli Zaretskii
2010-07-11 4:21 ` Drew Adams [this message]
2010-07-11 6:15 ` Eli Zaretskii
2010-07-11 8:14 ` Štěpán Němec
2010-07-11 9:22 ` Eli Zaretskii
2010-07-11 10:59 ` Štěpán Němec
2010-07-11 13:23 ` Eli Zaretskii
2010-07-11 13:44 ` Štěpán Němec
2010-07-11 14:00 ` Eli Zaretskii
2010-07-11 15:26 ` Andreas Schwab
2010-07-11 15:33 ` Drew Adams
2010-07-11 17:22 ` Eli Zaretskii
[not found] ` <mailman.11.1278862210.6344.bug-gnu-emacs@gnu.org>
2010-07-11 22:36 ` Tim X
[not found] ` <mailman.2.1278856813.6344.bug-gnu-emacs@gnu.org>
2010-07-11 22:34 ` Tim X
2010-12-08 15:52 ` Drew Adams
2010-12-20 12:25 ` Chong Yidong
2010-07-11 15:33 ` Drew Adams
2010-07-11 17:25 ` Eli Zaretskii
2010-07-11 16:33 ` Chong Yidong
2010-07-11 16:52 ` Drew Adams
2010-07-11 17:13 ` Chong Yidong
2010-07-11 17:58 ` Drew Adams
2010-07-11 18:14 ` Andreas Schwab
2010-07-11 19:10 ` Drew Adams
2010-07-11 19:40 ` Andreas Schwab
2010-07-11 20:07 ` Drew Adams
2010-07-11 21:22 ` Andreas Schwab
2010-07-11 21:42 ` Chong Yidong
2010-07-11 21:44 ` Drew Adams
2010-07-12 8:43 ` Andreas Schwab
2010-07-12 14:56 ` Drew Adams
2010-07-12 15:26 ` Andreas Schwab
2010-07-12 16:01 ` Drew Adams
2010-07-12 16:11 ` Andreas Schwab
2010-07-12 16:31 ` Drew Adams
2010-07-12 16:36 ` Andreas Schwab
2010-07-12 16:50 ` Drew Adams
2010-07-12 18:14 ` Andreas Schwab
2010-07-12 18:35 ` Drew Adams
2010-07-12 18:41 ` Andreas Schwab
2010-07-12 18:49 ` Drew Adams
2010-07-12 17:02 ` Eli Zaretskii
2010-07-12 18:30 ` Drew Adams
2010-07-10 5:44 ` MON KEY
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=38AC360676154EFF8DF9F35945B6EFAE@us.oracle.com \
--to=drew.adams@oracle.com \
--cc=6591@debbugs.gnu.org \
--cc=eliz@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.