* bug#20625: 25.0.50; doc of `define-error` is incorrect
@ 2015-05-21 21:04 Drew Adams
2015-05-23 10:17 ` Eli Zaretskii
2016-04-30 19:25 ` Lars Ingebrigtsen
0 siblings, 2 replies; 9+ messages in thread
From: Drew Adams @ 2015-05-21 21:04 UTC (permalink / raw)
To: 20625
From `C-h f':
(define-error NAME MESSAGE &optional PARENT)
Define NAME as a new error signal.
MESSAGE is a string that will be output to the echo area if such an error
is signaled without being caught by a `condition-case'.
PARENT is either a signal or a list of signals from which it inherits.
Defaults to `error'.
No, MESSAGE is not necessarily a string. It is a required argument, but
the code explicitly makes use of the case where it is nil. And existing
code delivered with Emacs (e.g. bookmark.el) makes use of a nil MESSAGE.
That case should be documented.
The doc in the manual has the same bug (node Error Symbols). MESSAGE is
*not* necessarily a string.
In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
of 2014-10-20 on LEG570
Bzr revision: 118168 rgm@gnu.org-20141020195941-icp42t8ttcnud09g
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
`configure --enable-checking=yes,glyphs CPPFLAGS=-DGLYPH_DEBUG=1'
^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#20625: 25.0.50; doc of `define-error` is incorrect
2015-05-21 21:04 bug#20625: 25.0.50; doc of `define-error` is incorrect Drew Adams
@ 2015-05-23 10:17 ` Eli Zaretskii
2016-04-30 19:25 ` Lars Ingebrigtsen
1 sibling, 0 replies; 9+ messages in thread
From: Eli Zaretskii @ 2015-05-23 10:17 UTC (permalink / raw)
To: Drew Adams; +Cc: 20625
> Date: Thu, 21 May 2015 14:04:31 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
>
> >From `C-h f':
>
> (define-error NAME MESSAGE &optional PARENT)
>
> Define NAME as a new error signal.
> MESSAGE is a string that will be output to the echo area if such an error
> is signaled without being caught by a `condition-case'.
> PARENT is either a signal or a list of signals from which it inherits.
> Defaults to `error'.
>
> No, MESSAGE is not necessarily a string. It is a required argument, but
> the code explicitly makes use of the case where it is nil. And existing
> code delivered with Emacs (e.g. bookmark.el) makes use of a nil MESSAGE.
> That case should be documented.
AFAICS, users of this property will yield strange messages if MESSAGE
is nil. So shouldn't we at least advise that it's a string?
Also, what exactly is the purpose of bookmark.el's using nil there?
^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#20625: 25.0.50; doc of `define-error` is incorrect
[not found] ` <<83382n38et.fsf@gnu.org>
@ 2015-05-23 14:48 ` Drew Adams
2015-05-23 14:57 ` Eli Zaretskii
2015-05-23 16:15 ` Stefan Monnier
0 siblings, 2 replies; 9+ messages in thread
From: Drew Adams @ 2015-05-23 14:48 UTC (permalink / raw)
To: Eli Zaretskii, Drew Adams; +Cc: 20625
> > MESSAGE is not necessarily a string. It is a requiredargument,
> > but the code explicitly makes use of the case where it is nil.
> > And existing code delivered with Emacs (e.g. bookmark.el) makes
> > use of a nil MESSAGE. That case should be documented.
>
> AFAICS, users of this property will yield strange messages if
> MESSAGE is nil. So shouldn't we at least advise that it's a string?
>
> Also, what exactly is the purpose of bookmark.el's using nil there?
I'm no expert in this, and I wasn't the one who changed bookmark.el
(in 24.4) to use `define-error'.
But it seems that what is meant is that `bookmark-errors' is being
declared to be an error condition, but with no definition: no
message and no parent (other than the default, `error').
This is the Emacs 24.3 code:
(put 'bookmark-error-no-filename
'error-conditions
'(error bookmark-errors bookmark-error-no-filename))
(put 'bookmark-error-no-filename
'error-message
"Bookmark has no associated file (or directory)")
And this is the 24.4+ code:
(define-error 'bookmark-errors nil)
(define-error 'bookmark-error-no-filename
"Bookmark has no associated file (or directory)"
'bookmark-errors)
In both cases, `bookmark-errors' is presumably being declared
as an error condition, but it is not defined in any way. It
is presumably there to provide a more general category than
`bookmark-error-no-filename'. That makes sense to me.
If my interpretation is correct, then something like that
explanation should be added to the doc, I think. Before
`define-error', things were clear enough with the doc for
property `error-conditions'. It seems that the doc for
`define-error' should cover the same cases.
I believe that means that with nil MESSAGE, property
`error-conditions' is applied (using MESSAGE), and property
`error-message' is not (absent or nil value).
In fact, I think that the right change would be not only
to say what nil MESSAGE means but to make MESSAGE an
&optional parameter.
^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#20625: 25.0.50; doc of `define-error` is incorrect
2015-05-23 14:48 ` Drew Adams
@ 2015-05-23 14:57 ` Eli Zaretskii
2015-05-23 16:15 ` Stefan Monnier
1 sibling, 0 replies; 9+ messages in thread
From: Eli Zaretskii @ 2015-05-23 14:57 UTC (permalink / raw)
To: Drew Adams; +Cc: 20625
> Date: Sat, 23 May 2015 07:48:46 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 20625@debbugs.gnu.org
>
> > > MESSAGE is not necessarily a string. It is a requiredargument,
> > > but the code explicitly makes use of the case where it is nil.
> > > And existing code delivered with Emacs (e.g. bookmark.el) makes
> > > use of a nil MESSAGE. That case should be documented.
> >
> > AFAICS, users of this property will yield strange messages if
> > MESSAGE is nil. So shouldn't we at least advise that it's a string?
> >
> > Also, what exactly is the purpose of bookmark.el's using nil there?
>
> I'm no expert in this, and I wasn't the one who changed bookmark.el
> (in 24.4) to use `define-error'.
>
> But it seems that what is meant is that `bookmark-errors' is being
> declared to be an error condition, but with no definition: no
> message and no parent (other than the default, `error').
>
> This is the Emacs 24.3 code:
>
> (put 'bookmark-error-no-filename
> 'error-conditions
> '(error bookmark-errors bookmark-error-no-filename))
> (put 'bookmark-error-no-filename
> 'error-message
> "Bookmark has no associated file (or directory)")
>
> And this is the 24.4+ code:
>
> (define-error 'bookmark-errors nil)
> (define-error 'bookmark-error-no-filename
> "Bookmark has no associated file (or directory)"
> 'bookmark-errors)
>
> In both cases, `bookmark-errors' is presumably being declared
> as an error condition, but it is not defined in any way. It
> is presumably there to provide a more general category than
> `bookmark-error-no-filename'. That makes sense to me.
I've grepped all the uses of 'error-message property in the Emacs
sources, and I only see uses that expect the value to be a string.
> If my interpretation is correct, then something like that
> explanation should be added to the doc, I think. Before
> `define-error', things were clear enough with the doc for
> property `error-conditions'. It seems that the doc for
> `define-error' should cover the same cases.
>
> I believe that means that with nil MESSAGE, property
> `error-conditions' is applied (using MESSAGE), and property
> `error-message' is not (absent or nil value).
>
> In fact, I think that the right change would be not only
> to say what nil MESSAGE means but to make MESSAGE an
> &optional parameter.
I cannot describe in the docs something I don't understand. I hope
someone who will would either fix the docs or post here what it means
for that property to have a nil value, and then I can put that in the
docs.
^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#20625: 25.0.50; doc of `define-error` is incorrect
[not found] ` <<83oalb1gvn.fsf@gnu.org>
@ 2015-05-23 16:02 ` Drew Adams
0 siblings, 0 replies; 9+ messages in thread
From: Drew Adams @ 2015-05-23 16:02 UTC (permalink / raw)
To: Eli Zaretskii, Drew Adams; +Cc: 20625
> I've grepped all the uses of 'error-message property in the Emacs
> sources, and I only see uses that expect the value to be a string.
What can I say, beyond what I said? I don't think that is really
relevant. A nil value means (I think) precisely that an error
condition is declared that has no associated message string. The
fact that no code makes use of such an error condition doesn't
mean anything significant, IMO.
IIUC, the use of `bookmark-errors' with a nil value in bookmark.el
is precisely the same as its use of `bookmark-errors' with
`error-condition' prior to Emacs 24.4. It declares, even if it
does not define an error message for, an error condition that
is more general than `bookmark-error-no-filename'.
It tells programmers who might define their own bookmark errors
to have them, like `bookmark-error-no-filename', inherit from
condition `bookmark-errors'. That seems reasonable to me. But
of course it is not necessary - users can just have their new
bookmark errors inherit from `error'.
Now you could argue that the presence of `bookmark-errors' in
bookmark.el prior to Emacs 24.4 was a mistake. That is the
same argument as saying that its presence now is a mistake.
But if you suppose that it is a good idea to predefine a general
error class for bookmark code, then I don't see why doing so
using `define-error' is any less meaningful/reasonable than
doing so using property `error-conditions' directly.
> I cannot describe in the docs something I don't understand. I hope
> someone who will would either fix the docs or post here what it
> means for that property to have a nil value, and then I can put
> that in the docs.
I tried to explain the meaning, as I understand it. Perhaps
the person who changed the Emacs 24.3 bookmark.el code to use
`define-error', or the person who introduced `define-error' to
Emacs 24.4, can confirm what I said or otherwise weigh in here.
Meanwhile, perhaps you could consider mentioning that the
MESSAGE value can be nil. (This doc bug would remain open, as
long as what nil means is not described, but at least the type
of MESSAGE would not be incorrectly specified). And perhaps
you could consider making parameter MESSAGE optional (since,
in effect, it is).
^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#20625: 25.0.50; doc of `define-error` is incorrect
2015-05-23 14:48 ` Drew Adams
2015-05-23 14:57 ` Eli Zaretskii
@ 2015-05-23 16:15 ` Stefan Monnier
2015-05-23 16:22 ` Drew Adams
1 sibling, 1 reply; 9+ messages in thread
From: Stefan Monnier @ 2015-05-23 16:15 UTC (permalink / raw)
To: Drew Adams; +Cc: 20625
> In fact, I think that the right change would be not only
> to say what nil MESSAGE means but to make MESSAGE an
> &optional parameter.
I disagree. The bookmark.el code is just a historical accident.
Stefan
^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#20625: 25.0.50; doc of `define-error` is incorrect
2015-05-23 16:15 ` Stefan Monnier
@ 2015-05-23 16:22 ` Drew Adams
0 siblings, 0 replies; 9+ messages in thread
From: Drew Adams @ 2015-05-23 16:22 UTC (permalink / raw)
To: Stefan Monnier; +Cc: 20625
> > In fact, I think that the right change would be not only
> > to say what nil MESSAGE means but to make MESSAGE an
> > &optional parameter.
>
> I disagree. The bookmark.el code is just a historical accident.
Then please remove it. Either this is an intended feature
or it is not. If you don't want `define-error` to provide
exactly the same thing that you can get by using property
`error-conditions' directly, then leave its definition and
doc as they are, but change the `bookmark.el' code back to
using `error-conditions' directly, so any code that expects
error condition `bookmark-errors' to be available will not
be surprised. Or remove it from bookmark.el altogether,
if you don't care about such backward compatibility. Or
provide a MESSAGE arg for the definition of `bookmark-errors'.
One way or another, the doc and behavior should match, and
bookmark.el should be made coherent with both.
^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#20625: 25.0.50; doc of `define-error` is incorrect
2015-05-21 21:04 bug#20625: 25.0.50; doc of `define-error` is incorrect Drew Adams
2015-05-23 10:17 ` Eli Zaretskii
@ 2016-04-30 19:25 ` Lars Ingebrigtsen
2016-04-30 19:42 ` Drew Adams
1 sibling, 1 reply; 9+ messages in thread
From: Lars Ingebrigtsen @ 2016-04-30 19:25 UTC (permalink / raw)
To: Drew Adams; +Cc: 20625
Drew Adams <drew.adams@oracle.com> writes:
>>From `C-h f':
>
> (define-error NAME MESSAGE &optional PARENT)
>
> Define NAME as a new error signal.
> MESSAGE is a string that will be output to the echo area if such an error
> is signaled without being caught by a `condition-case'.
> PARENT is either a signal or a list of signals from which it inherits.
> Defaults to `error'.
>
> No, MESSAGE is not necessarily a string. It is a required argument, but
> the code explicitly makes use of the case where it is nil. And existing
> code delivered with Emacs (e.g. bookmark.el) makes use of a nil MESSAGE.
> That case should be documented.
The function doesn't error out if MESSAGE isn't a string, but it still
shouldn't be. So I don't think that's a bug.
Feel free to submit a new bug report for bookmark.el not supplying a
string.
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog: http://lars.ingebrigtsen.no
^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#20625: 25.0.50; doc of `define-error` is incorrect
2016-04-30 19:25 ` Lars Ingebrigtsen
@ 2016-04-30 19:42 ` Drew Adams
0 siblings, 0 replies; 9+ messages in thread
From: Drew Adams @ 2016-04-30 19:42 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: 20625
> > No, MESSAGE is not necessarily a string. It is a required argument, but
> > the code explicitly makes use of the case where it is nil. And existing
> > code delivered with Emacs (e.g. bookmark.el) makes use of a nil MESSAGE.
> > That case should be documented.
>
> The function doesn't error out if MESSAGE isn't a string, but it still
> shouldn't be. So I don't think that's a bug.
>
> Feel free to submit a new bug report for bookmark.el not supplying a
> string.
I think it is too bad that `define-error', which was intended to
be a friendly wrapper around using `error-conditions' directly,
will no longer do all that the latter does. But so be it.
Bug #23408 reported, for bookmark.el. Users who wrote
similar code, expecting `define-error' to be like using
`error-conditions', will need to likewise change their
code.
^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2016-04-30 19:42 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2015-05-21 21:04 bug#20625: 25.0.50; doc of `define-error` is incorrect Drew Adams
2015-05-23 10:17 ` Eli Zaretskii
2016-04-30 19:25 ` Lars Ingebrigtsen
2016-04-30 19:42 ` Drew Adams
[not found] <<b9eb3f53-8dec-4157-8a96-7634274687ac@default>
[not found] ` <<83382n38et.fsf@gnu.org>
2015-05-23 14:48 ` Drew Adams
2015-05-23 14:57 ` Eli Zaretskii
2015-05-23 16:15 ` Stefan Monnier
2015-05-23 16:22 ` Drew Adams
[not found] <<10eb5733-c84c-491d-86ca-2d6a05b80e7d@default>
[not found] ` <<83oalb1gvn.fsf@gnu.org>
2015-05-23 16:02 ` Drew Adams
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).