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

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

[Drew Adams]

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'
 

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Fri, 9 Jul 2010 08:52:05 -0700
> Cc: 
> 
> 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.

> 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?

IMO, it doesn't make sense to talk about "BODYs", since the whole
doc string doesn't make sense then.

And please don't argue: this is my opinion, and we don't have to
agree.

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

[Drew Adams]

> > 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.

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

[MON KEY]

,----
| 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.
`----

Given that the Emacs Lisp dialect is described as being derived from
Maclisp and being a Lisp2 in some respects resembles Common Lisp the
following excerpts may of interest/relevance:

----

Following from the Pitmanual "Sunday Morning Edition"
The Revised Maclisp Manual Page A-5
:SOURCE (URL `http://maclisp.info/pitmanual/contro.html#5.13.3')

CATCH	Special Form	(CATCH form  [tag])

CATCH is an archaic (destined to become obsolete) special form for
doing structured non-local exits. See documentation on its
replacement, *CATCH.

CATCH forms can be translated to *CATCH as follows:

    old 	new
    (CATCH form tag) 	(*CATCH 'tag form)
    (CATCH form) 	(*CATCH NIL form).

Historically, (CATCH form) evolved to handle the fact that programmers
were using

    (ERRSET (...(ERR)...))

to accomplish non-local returns since there was once no other way to
get that functionality. CATCH and THROW were introduced so that
programmers could write

    (CATCH (...(THROW val)...))

instead where there was really no error condition. However, it was
found that confusion would often result using unlabelled CATCH/THROW
because an unlablled CATCH could catch a throw it hadn't intended
to. This is why named CATCH was invented. It is strongly recommended,
therefore, that if you are re-writing (CATCH form) to a *CATCH
according to the above rules, you also go to the extra trouble to
choose some tag. This is not as easy because it involves changing
related THROW's in the same module to all use the same tag (and
perhaps other CATCH's, or even some *THROW's and/or *CATCH's), but
it'll enhance the reliability of your code quite a lot.

See also: *CATCH, CATCH-BARRIER, CATCHALL, THROW, ERRSET
THROW	Special Form	(THROW form [tag])

THROW is an archaic (destined to become obsolete) special form. See
documentation on its replacement, *THROW.

THROW forms can be translated to *THROW as follows:

    old 	new
    (THROW form tag) 	(*THROW 'tag form).
    (THROW form) 	(*THROW NIL form).

See also: *THROW, CATCH, ERR

;;; ==============================
Following from an unofficial version of dpans3-texi of
ANSI Common Lisp:

catch (Special Operator)

Syntax:

 -- Special Form: catch TAG {form}* → {result}*

Arguments and Values:

TAG--a catch tag; evaluated.

FORMS--an implicit progn.

RESULTS--if the FORMS exit normally, the values returned by the FORMS;
if a throw occurs to the TAG, the values that are thrown.

Description:

‘catch’ is used as the destination of a non-local control transfer by
‘throw’.  TAGS are used to find the ‘catch’ to which a ‘throw’ is
transferring control.  ‘(catch 'foo form)’ catches a ‘(throw 'foo
form)’ but not a ‘(throw 'bar form)’.

The order of execution of ‘catch’ follows:

  1. TAG is evaluated.  It serves as the name of the ‘catch’.

  2. FORMS are then evaluated as an implicit ‘progn’, and the results
     of the last FORM are returned unless a ‘throw’ occurs.

  3. If a ‘throw’ occurs during the execution of one of the FORMS,
     control is transferred  to the ‘catch’ form whose TAG is ‘eq’ to
     the tag argument of the ‘throw’ and which is the most recently
     established ‘catch’ with that TAG.  No further evaluation of FORMS
     occurs.

  4. The TAG established by ‘catch’ is disestablished just before the
     results are returned.

If during the execution of one of the FORMS, a ‘throw’ is executed
whose tag is ‘eq’ to the ‘catch’ tag, then the values specified by the
‘throw’ are returned as the result of the dynamically most recently
established ‘catch’ form with that tag.

The mechanism for ‘catch’ and ‘throw’ works even if ‘throw’ is not
within the lexical scope of ‘catch’.  ‘throw’ must occur within the
dynamic extent of the evaluation of the body of a ‘catch’ with a
corresponding TAG.

Examples:

 (catch 'dummy-tag 1 2 (throw 'dummy-tag 3) 4) → 3
 (catch 'dummy-tag 1 2 3 4) → 4
 (defun throw-back (tag) (throw tag t)) → THROW-BACK
 (catch 'dummy-tag (throw-back 'dummy-tag) 2) → T

 ;; Contrast behavior of this example with corresponding example of BLOCK.
 (catch 'c
   (flet ((c1 () (throw 'c 1)))
     (catch 'c (c1) (print 'unreachable))
     2)) → 2

Exceptional Situations:

An error of type ‘control-error’ is signaled if ‘throw’ is done when
there is no suitable ‘catch’ TAG.

See Also:

throw

Notes:

It is customary for symbols to be used as TAGS, but any object is
permitted.  However, numbers should not be used because the comparison
is done using ‘eq’.

‘catch’ differs from ‘block’ in that ‘catch’ tags have dynamic scope
while ‘block’ names have lexical scope.

--
throw (Special Operator)

Syntax:

 -- Special Form: throw tag result-form →|

Arguments and Values:

TAG--a catch tag; evaluated.

RESULT-FORM--a form; evaluated as described below.

Description:

‘throw’ causes a non-local control transfer to a ‘catch’ whose tag is
‘eq’ to TAG.

TAG is evaluated first to produce an object called the throw tag; then
RESULT-FORM is evaluated, and its results are saved. If the RESULT-FORM
produces multiple values, then all the values are saved.  The most
recent outstanding ‘catch’ whose TAG is ‘eq’ to the throw tag is
exited; the saved results are returned as the value or values of
‘catch’.

The transfer of control initiated by ‘throw’ is performed as described
in Section 5.2.

Examples:

 (catch 'result
    (setq i 0 j 0)
    (loop (incf j 3) (incf i)
          (if (= i 3) (throw 'result (values i j))))) → 3, 9

 (catch nil
   (unwind-protect (throw nil 1)
     (throw nil 2))) → 2

The consequences of the following are undefined because the ‘catch’ of
‘b’ is passed over by the first ‘throw’, hence portable programs must
assume that its dynamic extent is terminated.  The binding of the catch
tag is not yet disestablished and therefore it is the target of the
second ‘throw’.

 (catch 'a
   (catch 'b
     (unwind-protect (throw 'a 1)
       (throw 'b 2))))

The following prints "‘The inner catch returns :SECOND-THROW’" and then
returns ‘:outer-catch’.

 (catch 'foo
         (format t "The inner catch returns ~s.~%"
                 (catch 'foo
                     (unwind-protect (throw 'foo :first-throw)
                         (throw 'foo :second-throw))))
         :outer-catch)
▷ The inner catch returns :SECOND-THROW
→ :OUTER-CATCH

Exceptional Situations:

If there is no outstanding catch tag that matches the throw tag, no
unwinding of the stack is performed, and an error of type
‘control-error’ is signaled.  When the error is signaled, the dynamic
environment is that which was in force at the point of the ‘throw’.

See Also:

block, catch, return-from, unwind-protect

Notes:

‘catch’ and ‘throw’ are normally used when the exit point must have
dynamic scope (e.g., the ‘throw’ is not lexically enclosed by the
‘catch’), while ‘block’ and ‘return’ are used when lexical scope is
sufficient.

--
/s_P\

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> 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.

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

[Drew Adams]

> 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.

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <6591@debbugs.gnu.org>
> Date: Sat, 10 Jul 2010 07:14:14 -0700
> 
> > 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.
                                          ^^^
Why the period?

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

[Drew Adams]

> > Ah! Then the syntax should be (catch TAG . BODY) or similar.
>                                           ^^^
> Why the period?

Same reason as your special `BODY...' syntax.  It means _splice in_ the list
BODY.  Or if you like, it means that BODY is the cdr of the sexp as a list.  Or
if you like, it is equivalent to ,@BODY in backquote syntax.

You cannot write just (catch TAG BODY).  There must be some indication (`.',
`...' or other) to distinguish normal substitution for a placeholder from
splicing substitution for a placeholder.  Substitution for TAG is treated
differently from substitution for BODY.

But are you just playing/kidding here? or arguing?  What's the point?  I'm sure
that you understand the syntax (A . B) in Lisp and in our docs.  I assume you
are trying to make some point, but I fail to see it.

Perhaps you simply want to hint that (A B...) is a notation that means the same
thing as (A . B).  If so, fine.

However:

1. I do not think the `...' syntax is described/defined anywhere in the doc.

2. More importantly (since it is anyway easy to miss such a definition), `...'
has a different meaning typically/commonly, so our interpretation (syntax
convention) of `...' can easily mislead and confuse.  Readers will tend to think
that BODY... means zero (or one) or more repetitions of BODY.  (Which is just
what I originally thought it was trying to say.)

So the syntax descriptors for catch, let, and progn are NOT incorrect, after
all.  It is the syntax convention that we've chosen that is misleading.  We are
entitled to any convention we like, as long as it is rigorous and we use it
consistently (which I'm not questioning now).  But it make sense not to use a
convention that can be easily mistaken for a different convention that is more
commonly used.  `...' commonly means repetition of whatever it follows, and
there is no repetition of BODY here (there is only one body).

You decide.

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <6591@debbugs.gnu.org>
> Date: Sat, 10 Jul 2010 08:44:47 -0700
> 
> > > Ah! Then the syntax should be (catch TAG . BODY) or similar.
> >                                           ^^^
> > Why the period?
> 
> Same reason as your special `BODY...' syntax.  It means _splice in_ the list
> BODY.  Or if you like, it means that BODY is the cdr of the sexp as a list.  Or
> if you like, it is equivalent to ,@BODY in backquote syntax.
> 
> You cannot write just (catch TAG BODY).  There must be some indication (`.',
> `...' or other) to distinguish normal substitution for a placeholder from
> splicing substitution for a placeholder.  Substitution for TAG is treated
> differently from substitution for BODY.
> 
> But are you just playing/kidding here? or arguing?  What's the point?  I'm sure
> that you understand the syntax (A . B) in Lisp and in our docs.  I assume you
> are trying to make some point, but I fail to see it.

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.

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

[Drew Adams]

> 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.

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <6591@debbugs.gnu.org>
> Date: Sat, 10 Jul 2010 21:21:04 -0700
> 
> 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.

Using FORM... is okay, but will need more extensive changes, so I'd
rather not do it.  I'd like to simply remove the dots after BODY, and
explain in the text that BODY can consist of one or more forms.

Does anyone see any reason why keeping the dots in BODY... will have
some didactical importance?  Richard? Stefan? Yidong?

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

[Štěpán Němec]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: "Drew Adams" <drew.adams@oracle.com>
>> Cc: <6591@debbugs.gnu.org>
>> Date: Sat, 10 Jul 2010 21:21:04 -0700
>> 
>> 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.
>
> Using FORM... is okay, but will need more extensive changes, so I'd
> rather not do it.  I'd like to simply remove the dots after BODY, and
> explain in the text that BODY can consist of one or more forms.
>
> Does anyone see any reason why keeping the dots in BODY... will have
> some didactical importance?  Richard? Stefan? Yidong?

Well, just look at `when' -- ISTM it has the very same "problem" as
discussed here. And it's probably not the only one/two.

Štěpán

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

[Eli Zaretskii]

> From: =?utf-8?B?xaB0xJtww6FuIE7Em21lYw==?= <stepnem@gmail.com>
> Cc: Drew Adams <drew.adams@oracle.com>,  6591@debbugs.gnu.org,  Richard Stallman <rms@gnu.org>
> Date: Sun, 11 Jul 2010 10:14:47 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Using FORM... is okay, but will need more extensive changes, so I'd
> > rather not do it.  I'd like to simply remove the dots after BODY, and
> > explain in the text that BODY can consist of one or more forms.
> >
> > Does anyone see any reason why keeping the dots in BODY... will have
> > some didactical importance?  Richard? Stefan? Yidong?
> 
> Well, just look at `when' -- ISTM it has the very same "problem" as
> discussed here. And it's probably not the only one/two.

Sorry, I don't get your point.  Sure, there are places in the manual
that use "FORM...", but that doesn't necessarily mean it's the only
possible way of describing that.  "BODY..." is used in quite a few
places as well, and I was only talking about those.

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

[Štěpán Němec]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: =?utf-8?B?xaB0xJtww6FuIE7Em21lYw==?= <stepnem@gmail.com>
>> Cc: Drew Adams <drew.adams@oracle.com>, 6591@debbugs.gnu.org, Richard
> Stallman <rms@gnu.org>
>> Date: Sun, 11 Jul 2010 10:14:47 +0200
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> > Using FORM... is okay, but will need more extensive changes, so I'd
>> > rather not do it.  I'd like to simply remove the dots after BODY, and
>> > explain in the text that BODY can consist of one or more forms.
>> >
>> > Does anyone see any reason why keeping the dots in BODY... will have
>> > some didactical importance?  Richard? Stefan? Yidong?
>> 
>> Well, just look at `when' -- ISTM it has the very same "problem" as
>> discussed here. And it's probably not the only one/two.
>
> Sorry, I don't get your point.  Sure, there are places in the manual
> that use "FORM...", but that doesn't necessarily mean it's the only
> possible way of describing that.  "BODY..." is used in quite a few
> places as well, and I was only talking about those.

You were asking about BODY...
`when' uses BODY..., and IMO in `when' `BODY...' means the very same
thing as in `catch' (i.e., "any number of forms"), which you're now
apparently about to change.

Štěpán

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

[Eli Zaretskii]

> From: Štěpán Němec <stepnem@gmail.com>
> Cc: 6591@debbugs.gnu.org,  rms@gnu.org
> Date: Sun, 11 Jul 2010 12:59:38 +0200
> 
> >> Well, just look at `when' -- ISTM it has the very same "problem" as
> >> discussed here. And it's probably not the only one/two.
> >
> > Sorry, I don't get your point.  Sure, there are places in the manual
> > that use "FORM...", but that doesn't necessarily mean it's the only
> > possible way of describing that.  "BODY..." is used in quite a few
> > places as well, and I was only talking about those.
> 
> You were asking about BODY...
> `when' uses BODY..., and IMO in `when' `BODY...' means the very same
> thing as in `catch' (i.e., "any number of forms"), which you're now
> apparently about to change.

I think you are using an old version of the ELisp manual.  The latest
one on the trunk doesn't use BODY...  That's why I misunderstood your
point.

But yes, I know that `catch' is not the only one that uses BODY... and
I intended to change them all.

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

[Štěpán Němec]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Štěpán Němec <stepnem@gmail.com>
>> Cc: 6591@debbugs.gnu.org,  rms@gnu.org
>> Date: Sun, 11 Jul 2010 12:59:38 +0200
>> 
>> >> Well, just look at `when' -- ISTM it has the very same "problem" as
>> >> discussed here. And it's probably not the only one/two.
>> >
>> > Sorry, I don't get your point.  Sure, there are places in the manual
>> > that use "FORM...", but that doesn't necessarily mean it's the only
>> > possible way of describing that.  "BODY..." is used in quite a few
>> > places as well, and I was only talking about those.
>> 
>> You were asking about BODY...
>> `when' uses BODY..., and IMO in `when' `BODY...' means the very same
>> thing as in `catch' (i.e., "any number of forms"), which you're now
>> apparently about to change.
>
> I think you are using an old version of the ELisp manual.  The latest
> one on the trunk doesn't use BODY...  That's why I misunderstood your
> point.

(describe-function 'when)

> But yes, I know that `catch' is not the only one that uses BODY... and
> I intended to change them all.

I just hope you're not going to change them to `BODY' instead of
`BODY...', as that would mean

(when (condition)
  (a single form))

`FORM...' would seem more clear, but I don't really care that much.


Štěpán

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

[Eli Zaretskii]

> From: Štěpán Němec <stepnem@gmail.com>
> Cc: 6591@debbugs.gnu.org,  rms@gnu.org
> Date: Sun, 11 Jul 2010 15:44:34 +0200
> 
> I just hope you're not going to change them to `BODY' instead of
> `BODY...', as that would mean
> 
> (when (condition)
>   (a single form))

??? Whatever gave you the idea that BODY is only one form?

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

[Andreas Schwab]

Eli Zaretskii <eliz@gnu.org> writes:

> ??? Whatever gave you the idea that BODY is only one form?

BODY is a single form, BODY... is a sequence of forms.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Drew Adams]

> > 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.
> 
> Using FORM... is okay, but will need more extensive changes, so I'd
> rather not do it.  I'd like to simply remove the dots after BODY, and
> explain in the text that BODY can consist of one or more forms.

AND that list of forms is SPLICED IN.  That's the important part that needs to
be made clear if you take your approach.

IOW, reading what you just wrote, a reader will assume that BODY might be (A B
C) when what you meant was A B C.  E.g. this is not valid: (catch 'foo ((setq a
b) (terpri) (set-buffer z))).  But it follows your description fine: "BODY can
consist of one or more forms".

We will agree to disagree on this one.

IMO, readers will not be helped, and doc maintenance will be increased in the
long run, by doing what you suggest.  There is a mismatch between what someone
sees in the syntax description, (catch TAG BODY), and what the surrounding text
needs to say in order to explain that syntax.

A user sees TAG and BODY directly, and naturally supposes that each is a
placeholder and the kind of thing substitutable for each placeholder is the same
or similar.

The text needs (at *each* occurrence of this phenomenon) to explain that this is
not the case: TAG is replaceable by a sexp, BODY is replaceable by a list of
sexps, but the list is spliced in.

It's easy enough to say that in `(A B C)' A is a placeholder for a function
symbol, B for an integer and C for any sexp (or whatever) - the types of the
placeholders are straightforward.  It is not so easy to explain that BODY in
(catch TAG BODY) is a list of sexps but that list has no surrounding parens etc.

It's your call, but in the long run what you propose will lead to more complex,
confusing doc and increased doc maintenance.  That will help neither reader nor
writer.

> Does anyone see any reason why keeping the dots in BODY... will have
> some didactical importance?  Richard? Stefan? Yidong?

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

[Drew Adams]

> > ??? Whatever gave you the idea that BODY is only one form?
> 
> BODY is a single form, BODY... is a sequence of forms.

You two have just circled 'round to the beginning of this thread.  QED.

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

[Chong Yidong]

Eli Zaretskii <eliz@gnu.org> writes:

> Using FORM... is okay, but will need more extensive changes, so I'd
> rather not do it.  I'd like to simply remove the dots after BODY, and
> explain in the text that BODY can consist of one or more forms.
>
> Does anyone see any reason why keeping the dots in BODY... will have
> some didactical importance?  Richard? Stefan? Yidong?

The dots are important, because BODY normally implies one single form.
We are somewhat abusing notation by using `BODY...' to denote one or
more forms, but the convention is well-established and easy to grasp,
and there are no better alternatives.

I suggest doing everywhere what the `progn' documentation does, and
refer to BODY as "BODY forms".

  (progn BODY...)

  Eval BODY forms sequentially and return value of last one.

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

[Drew Adams]

> The dots are important, because BODY normally implies one single form.
> We are somewhat abusing notation by using `BODY...' to denote one or
> more forms, but the convention is well-established and easy to grasp,
> and there are no better alternatives.

No better alternative?  Did you read the thread?  What about doing what the rest
of the world does: (catch TAG FORM...)?

Then if you really need to talk about the "body" for some reason, just say that
the body is everything that follows TAG or it is the collection of forms or some
such.  No need to use "body" in the syntax description.  (And no real need to
even mention the body.)

> I suggest doing everywhere what the `progn' documentation does, and
> refer to BODY as "BODY forms".
> 
>   (progn BODY...)
>   Eval BODY forms sequentially and return value of last one.

Same problem - see the start of the thread.

What does "BODY forms" refer to: (1) a set of BODYs, each of which is a Lisp
form, or (2) the set of Lisp forms that comprise a BODY.  The term "BODY forms"
is ambiguous.  It can mean the forms that make up BODY or a list of forms each
of which is a BODY.

And what does `...' signify here: repetition of what it follows (i.e. repetition
of BODY), as in the rest of the world, or a special Emacs-only syntax where
`BODY...' is taken as a single token that is replaced by splicing in a list of
Lisp forms?

(progn FORM...) is much clearer.  Users can parse it in the usual way: FORM is
replaceable by a Lisp form, and `FORM...' simply means a repetition of Lisp
forms.

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

[Chong Yidong]

"Drew Adams" <drew.adams@oracle.com> writes:

>> The dots are important, because BODY normally implies one single form.
>> We are somewhat abusing notation by using `BODY...' to denote one or
>> more forms, but the convention is well-established and easy to grasp,
>> and there are no better alternatives.
>
> No better alternative?  Did you read the thread?  What about doing
> what the rest of the world does: (catch TAG FORM...)?

Either BODY... or FORM... seems fine by me.  It seems clearer to use
BODY... and refer to "BODY forms" in the text, than to use FORM... and
refer to "each FORM" in the text.  But it is a marginal difference, and
I don't think anyone gets confused in practice.

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

[Eli Zaretskii]

> From: Andreas Schwab <schwab@linux-m68k.org>
> Cc: =?utf-8?B?xaB0xJtww6FuIE7Em21lYw==?= <stepnem@gmail.com>,
>   6591@debbugs.gnu.org,  rms@gnu.org
> Date: Sun, 11 Jul 2010 17:26:03 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > ??? Whatever gave you the idea that BODY is only one form?
> 
> BODY is a single form, BODY... is a sequence of forms.

BODY is whatever follows TAG, till the closing parenthesis.  That's
why it is called "body".  If we would like to say "form", we would do
just that.

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <6591@debbugs.gnu.org>, "'Richard Stallman'" <rms@gnu.org>
> Date: Sun, 11 Jul 2010 08:33:34 -0700
> 
> IMO, readers will not be helped, and doc maintenance will be increased in the
> long run, by doing what you suggest.

OK, I give up.  Someone else will have to do something with this bug
report.

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

[Drew Adams]

> >> The dots are important, because BODY normally implies one 
> >> single form.  We are somewhat abusing notation by using
> >> `BODY...' to denote one or more forms, but the convention
> >> is well-established and easy to grasp,
> >> and there are no better alternatives.
> >
> > No better alternative?  Did you read the thread?  What about doing
> > what the rest of the world does: (catch TAG FORM...)?
> 
> Either BODY... or FORM... seems fine by me.  It seems clearer to use
> BODY... and refer to "BODY forms" in the text, than to use FORM... and
> refer to "each FORM" in the text.  But it is a marginal difference,

You are missing the point, but I won't beat a dead horse.  I explained myself
clearly, I think, for anyone who is willing and able to read.

> and I don't think anyone gets confused in practice.

If you read the thread, then you should not think that.  _I_ got confused in
practice, which is why I filed the bug report.

I could not remember whether `catch' allows multiple sexps after the tag (i.e.
has an implicit `progn'), so I consulted the doc, which I found misleading and
confusing.[*]

IOW, just to find out whether I needed to use an explicit `progn' after the tag
in order to eval multiple sexps, I landed in a doc morass where `BODY...' does
not in fact mean repetitions of BODY as it does in the rest of the known
universe.

For further clarity, I grepped the Emacs Lisp sources for examples, and I found
_only_ uses of `catch' with a _single_ sexp.  That added to my confusion.  And
when I finally figured that an implicit `progn' was used, the exclusive use of
only one sexp in our source code suggested to me that perhaps some Emacs
developers might also have been confused and so never tried using more than one
sexp.


[* I sometimes forget such things.  One that I keep coming back to is
`unwind-protect', which does _not_ protect multiple sexps (you need to use an
explicit `progn' if you want to do that).  

Note, BTW, that in MacLisp the syntax was `(catch FORM TAG)', where _only one_
sexp was allowed.  Note too that the MacLisp doc for `*catch' (which replaced
`catch') shows its syntax as `(*catch tagspec . body)' - note the use of dot
notation in a syntax description. http://maclisp.info/pitmanual/contro.html]

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

[Andreas Schwab]

"Drew Adams" <drew.adams@oracle.com> writes:

> No better alternative?  Did you read the thread?  What about doing what the rest
> of the world does: (catch TAG FORM...)?

Just because you spell the body form does not make it any different
form.  The ellipses is already unambigous.

> What does "BODY forms" refer to: (1) a set of BODYs, each of which is a Lisp
> form, or (2) the set of Lisp forms that comprise a BODY.  The term "BODY forms"
> is ambiguous.  It can mean the forms that make up BODY or a list of forms each
> of which is a BODY.

This is _not_ a list, it is a repeated argument, not matter how you name
the parameter.  If it were a list it would be a single parameter.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Drew Adams]

> > No better alternative?  Did you read the thread?  What 
> > about doing what the rest of the world does: (catch TAG FORM...)?
> 
> Just because you spell the body form does not make it any different
> form.  The ellipses is already unambigous.

Please read the thread.  Ellipsis commonly means that whatever it follows can be
repeated.  The body is not repeated.

[Ditto for `*' (same as `...').
Common Lisp writes this as (catch TAG {FORM}*), which is clear.]

This convention for `...', no matter how common, should also be stated in the
docs, of course.  I gave the Oracle docs as an example, and this convention is
clearly spelled out there.

> > What does "BODY forms" refer to: (1) a set of BODYs, each 
> > of which is a Lisp form, or (2) the set of Lisp forms that
> > comprise a BODY.  The term "BODY forms" is ambiguous.  It
> > can mean the forms that make up BODY or a list of forms each
> > of which is a BODY.
> 
> This is _not_ a list,

What is not a list - what is "this"?

> it is a repeated argument,

Bzzzzt!  No, sorry, but thanks for playing.  What argument is repeated?  BODY?
Eli says no.  What is repeated (repeatable) is the FORM that actually is an
argument (and which does not appear in the syntax description).  `BODY...' is
not an argument (according to Eli).  BODY is not an argument (according to Eli).
BODY cannot be repeated (according to Eli). [Where "according to Eli" means my
understanding of what he wrote.]

> not matter how you name the parameter.

What parameter?  BODY is not an (ordinary) parameter.
`BODY...' is not a parameter.

BODY would be a &rest parameter, if we expressed it that way (which I suggested
as one possibility).  Other than that, it is _not_ an ordinary parameter.

[MacLisp writes (*catch TAGSPEC . BODY), which is clear, even if not
conventional outside the Lisp world.]

But in (catch TAG BODY...) BODY is not a placeholder, and `...' does not mean
repetition of BODY.  Instead, `BODY...' is a single token standing for a list of
forms that is spliced in to produce an implicit `progn'.

So "it is a repeated argument, no matter how you name the parameter" is wrong on
at least two counts.

> If it were a list it would be a single parameter.

See above.

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

[Andreas Schwab]

There are arguments that are passed to functions and special forms, and
parameters that are placeholders in the definitions of them.  You seem
to be mixing them up a lot.  A parameter either matches a single
argument, or multiple ones (if followed by an ellipsis).  It doesn't
matter in any way how the parameter is called in this process.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Drew Adams]

> A parameter either matches a single argument, or multiple
> ones (if followed by an ellipsis).

The latter is a &rest parameter, as I said.

(And no one is confusing actual args with formal parameters.  The fact that you
state the contrary indicates that you have either not read or have not
understood the thread.)

And it's legitimate for Emacs to define the `...' syntax as indicating a &rest
parameter, but _that convention needs to be STATED in the doc_.

And it is not a great convention to choose, because it flies in the face of the
common use of `...' in syntax descriptions (in the rest of the universe), in
which `...' means repetition of what it follows.

Which brings us back to the start of the thread.

Emacs _can_ choose to exceptionally use `...' to mean a &rest parameter, but;

1. That unusual convention needs to be spelled out in the doc.

2. We will anyway confuse some readers who do not happen to read that
explanation of this exceptional use of `...'.  They will assume the usual
interpretation of `...' as repetition.

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

[Andreas Schwab]

"Drew Adams" <drew.adams@oracle.com> writes:

> which `...' means repetition of what it follows.

Which fits perfectly.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Chong Yidong]

Andreas Schwab <schwab@linux-m68k.org> writes:

> "Drew Adams" <drew.adams@oracle.com> writes:
>
>> which `...' means repetition of what it follows.
>
> Which fits perfectly.

Precisely; this is a nit we don't have to pick.

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

[Drew Adams]

> > which `...' means repetition of what it follows.
> 
> Which fits perfectly.

Repetition of what it follows.
           ^^^^^^^^^^^^^^^^^^

What does `...' follow?  BODY.
Is BODY repeated?        No.

For Emacs, `...' does not mean repetition of what it follows (per what Eli has
said).  Instead, it means that what it follows is a &rest parameter.

For Emacs, (X BODY...) means the same as (X &rest BODY) and (X . BODY).

Which, as I said, is a legitimate, if unwise and unusual, choice.
It just needs to be spelled out in the doc.

Read the thread.  I'm not going to repeat everything that has been said.

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

[Tim X]

Štěpán Němec <stepnem@gmail.com> writes:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>>> From: Štěpán Němec <stepnem@gmail.com>
>>> Cc: 6591@debbugs.gnu.org,  rms@gnu.org
>>> Date: Sun, 11 Jul 2010 12:59:38 +0200
>>> 
>>> >> Well, just look at `when' -- ISTM it has the very same "problem" as
>>> >> discussed here. And it's probably not the only one/two.
>>> >
>>> > Sorry, I don't get your point.  Sure, there are places in the manual
>>> > that use "FORM...", but that doesn't necessarily mean it's the only
>>> > possible way of describing that.  "BODY..." is used in quite a few
>>> > places as well, and I was only talking about those.
>>> 
>>> You were asking about BODY...
>>> `when' uses BODY..., and IMO in `when' `BODY...' means the very same
>>> thing as in `catch' (i.e., "any number of forms"), which you're now
>>> apparently about to change.
>>
>> I think you are using an old version of the ELisp manual.  The latest
>> one on the trunk doesn't use BODY...  That's why I misunderstood your
>> point.
>
> (describe-function 'when)
>
>> But yes, I know that `catch' is not the only one that uses BODY... and
>> I intended to change them all.
>
> I just hope you're not going to change them to `BODY' instead of
> `BODY...', as that would mean
>
> (when (condition)
>   (a single form))
>
> `FORM...' would seem more clear, but I don't really care that much.
>
>

But I thought that was what the discussion was about i.e. 

BODY == FORM.....

but 

BODY... is equal to multiple 'bodies' which is not what is meant. 

I prefer BODY rather than BODY..., but think the CL FORM* is the clearer
when you want to indicate one or more forms.

Tim


-- 
tcross (at) rapttech dot com dot au

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

[Tim X]

Andreas Schwab <schwab@linux-m68k.org> writes:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>> ??? Whatever gave you the idea that BODY is only one form?
>
> BODY is a single form, BODY... is a sequence of forms.
>

but isn't body one or more forms. If not, what is the point of BODY
rather than just FORM and FORM.... or FORM*???

Tim


-- 
tcross (at) rapttech dot com dot au

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

[Andreas Schwab]

"Drew Adams" <drew.adams@oracle.com> writes:

> Is BODY repeated?

Yes.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Drew Adams]

> > Is BODY repeated?
> 
> Yes.

Then there are multiple BODYs, which Eli denies.

And in that case, the accompanying text is incorrect and misleading, since it
speaks as if there is only one body (which Eli says is in fact the case).

You cannot have it both ways.  If BODY represents a sexp that can be repeated,
then there is not only one body that contains all of the sexps following TAG.
If BODY represents all of the sexps that follow tag, spliced in, then BODY is
not repeated.

Read the thread - this has all been gone over.


There are essentially two alternative solutions:

1. Use `...' to mean repetition of what it follows, as in the rest of the world.
And change BODY to FORM, in order not to mislead.  Then (catch TAG FORM...) says
exactly what it means: zero or more FORMs follow TAG.

2. Introduce an Emacs-only interpretation of `...' which means that what it
follows is a list to be spliced in.  In this case, postfix `...' is equivalent
to infix `.' (dot notation) and to a &rest parameter spec.


#2 is what Eli says that `...' means in Emacs syntax descriptions.  That is
unusual, but a legitimate choice.  Then (catch TAG BODY...) says that BODY is a
list of somethings (the accompanying text would say forms) that are spliced in.
So in (catch 'foo (a) (b) 42) the body is ((a) (b) 42).  The body is an implicit
`progn'.  BODY is a &rest parameter for `catch'.

If #2 is chosen, then the doc must explain the `...' notation somewhere. (It
should explain that notation in any case, but especially in the case where it
has an unconventional and unusual interpretation.)


#1 is my preference, because it is easier on readers and easier in terms of doc
maintenance.  It is consistent with what one finds outside Emacs.

What is a BUG is to use #2 with no explanation of the unusual syntax convention.

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

[Andreas Schwab]

There are multiple arguments all matched by the parameter.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Drew Adams]

> There are multiple arguments all matched by the parameter.

Yes, so?  It is a &rest parameter.
How shall we convey that in the doc?
That is the question.

`...' typically signifies repetition of what it follows.  If `...' follows BODY,
then that (normally) means repetition of BODY - which is not what we mean in
Emacs (there is only one body).

Repetition of arguments, yes.  And those arguments are sexps, not BODYs.  A
single &rest parameter BODY, yes.  And that BODY is not a sexp - it is a list of
sexps that is spliced in.

It's not about actual args vs parameters.  It's about describing the syntax
unambiguously, whether you describe args or parameters.

But you and Eli do not agree about `...' apparently.  For him `...' does not
signify repetition; it means that BODY is a &rest parameter - hence we can
legitimately speak of only a single BODY.

You cannot have it both ways.  Either BODY is the list of what follows TAG,
spliced in, or BODY represents a single sexp (Lisp form) and is repeatable.  In
the latter case, BODY should be called FORM or SEXP, because the word "body"
suggests there is only one.

In the former case, `...' coincides with common practice.  In the latter choice
it does not.  In either case we need to spell out the syntax convention that we
use, somewhere in the doc - that is missing AFAICT.  In the latter choice it is
especially important to do that, since our convention does not fit what readers
see elsewhere.

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

[Andreas Schwab]

BODY... or FORM... or SEXP... or whatever you call it matches the
arguments that follow TAG.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Drew Adams]

> BODY... or FORM... or SEXP... or whatever you call it matches the
> arguments that follow TAG.

OK, that's also Eli's interpretation of `...'.
In that case, BODY is _not_ repeated (repeatable).
And in that case, FORM... or SEXP... would not be appropriate.
The body is not a sexp.

This interpretation of `...' is unconventional, atypical.  Outside Emacs, `...'
typically means repetition of what it follows - in this case BODY.  It's fine
for Emacs to have an unusual syntax convention, but it needs to be documented.

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

[Andreas Schwab]

BODY... repeatedly matches all the arguments folling TAG.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Drew Adams]

> BODY... repeatedly matches all the arguments folling TAG.

Irrelevant - just word play.

The point is that `...' typically means, when describing syntax, that whatever
it follows can be repeated.  That is, it is legitimate _syntax_ to repeat any
number of whatevers.  Whether `...' means zero or more or one or more is up for
grabs.  In the Oracle docs it means zero or more, so when one or more is meant
you write `X X...', not `X...'.


And as I mentioned, _if_ there is a need to specify the scope of a `...' then we
will need to introduce a grouping construct.  Braces are sometimes used for this
(e.g. in both Oracle and Common Lisp doc - Oracle just uses a form of BNF).

E.g. `X {A B}...' means X followed by zero or more occurrences of `A B' (A
followed by B).

We might have no need for such grouping - dunno.  If we do, and _if_ we also
sometimes use braces literally in the syntax (which I doubt), then we would also
need a way to distinguish braces as syntax symbols (meta) from literal braces.
I doubt that we need this either.  I'm just mentioning that it is part of the
machinery needed in general to specify repetition: just what is it that is
repeatable.

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: "'Chong Yidong'" <cyd@stupidchicken.com>, "'Eli Zaretskii'" <eliz@gnu.org>,
>         <6591@debbugs.gnu.org>, "'Richard Stallman'" <rms@gnu.org>
> Date: Mon, 12 Jul 2010 09:01:25 -0700
> 
> But you and Eli do not agree about `...' apparently.  For him `...' does not
> signify repetition

That's not true.  I simply wanted to remove the dots.

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

[Andreas Schwab]

"Drew Adams" <drew.adams@oracle.com> writes:

> The point is that `...' typically means, when describing syntax, that whatever
> it follows can be repeated.

Which is exactly what it does.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Drew Adams]

> > But you and Eli do not agree about `...' apparently.  For 
> > him `...' does not signify repetition
> 
> That's not true.  I simply wanted to remove the dots.

Careful.  "Signify repetition" of what?  I was speaking of signifying repetition
of _what it follows_.

You made it clear that BODY is not repeated, that `...' does _not_ signify that
what it follows (in this case BODY) is repeatable.

You said, "Saying that there are multiple BODYs breaks the model".  And that
sounds good to me - there is only one body, we have agreed.

Read carefully what I wrote.  This is about whether postfix `...' means that
_what it follows_ is repeatable, not whether BODY or `BODY...' might somehow
signify that _something_ is repeatable - something _other than_ BODY itself.

It's a _syntax_ description.  `...' must apply to something (or to some things)
that is (are) present in the same syntax description.  If it does not apply to
BODY, then what does it apply to?

For most of the world, `X...' suggests that X can be repeated.  You made it
clear that `BODY...' does not mean that BODY itself can be repeated (there can
be only one BODY).

You have chosen to omit the _something_ that is repeatable from the syntax
description and describe it only in the accompanying text, which says that BODY
is one or more forms.  Nothing wrong with that.

But in that case `...' does not signify repetition of anything in the syntax
description.  It is the _accompanying text_ that says that BODY is a repetition
of Lisp forms.  The syntax description can only be said to indicate that if we
explain that `X...' stands for a spliced-in list of Lisp forms.  That (unusual)
definition of `...' is missing from the doc.

That's the choice: how to use `...' - what it should mean.  I'm OK with your
position that it should indicate a &rest parameter, IOW that it should be a
postfix version of `.' (dotted pair operator).  That is not the same as saying
that it signifies repetition of what it follows (in the syntax description).

But (a) that convention needs to be described somewhere and (b) it is not the
typical convention for `...' in syntax descriptions, so we need to take care
here and there to make it clear.

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

[Drew Adams]

> > The point is that `...' typically means, when describing 
> > syntax, that whatever it follows can be repeated.
> 
> Which is exactly what it does.

So your position is that BODY itself can be repeated.  That contradicts Eli's
position (and mine) that there is only one body.

And in that case, the text that accompanies the syntax description does not fit,
since it too speaks of "the body".

A. If BODY can be repeated (your position), then there can be more than one
BODY.

B. If BODY cannot be repeated, so there is only one BODY, then `BODY...' does
not signify repetition of BODY.  So `...' does not signify that whatever it
follows can be repeated.

You've made your choice for A.  Yet you want to claim that `...' still signifies
repetition of what it follows, BODY.  Think again.

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

[Andreas Schwab]

There is no contradiction.  The ellipsis means exactly what it is
supposed to do.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Drew Adams]

> There is no contradiction.  The ellipsis means exactly what it is
> supposed to do.

Ah, refuge behind vagueness.

Yes, of course you're right.  The ellipsis means exactly what it is supposed to
mean.  Carry on; tout va tres bien, Mme La Marquise.

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

[Drew Adams]

> But I thought that was what the discussion was about i.e. 
> BODY == FORM.....
> but BODY... is equal to multiple 'bodies' which is not
> what is meant. 
> 
> I prefer BODY rather than BODY..., but think the CL FORM* is 
> the clearer when you want to indicate one or more forms.

Caveat: I haven't been following this thread lately (guess I gave up), so I
might be misunderstanding what is said here.

If I understand correctly, then yes, that is what this bug report is about (I
filed it).  And yes, the Common Lisp doc is *much* clearer in this regard.  For
one thing, it actually _defines_ the syntax constructs it uses.

But I don't think the point of this bug report will ever be successfully
communicated to those who are in a position to fix this.

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

[Chong Yidong]

I've read the relevant docstring and Elisp entry, and estimate the
chance of reader confusion at zero.  Let's not pick this particular nit.