GNU bug report logs - #15809
24.3.50; wrong defcustom type for `suggest-key-bindings'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 15809 in the body.
You can then email your comments to 15809 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.3.50; wrong defcustom type for `suggest-key-bindings'
Date: Tue, 5 Nov 2013 07:30:37 -0800 (PST)

Instead of `integer' the `choice' should use `number' (and the code
should then ignore negative values) or `restricted-sexp' with a test
that the time be non-negative.

See the comment by phils here:
http://stackoverflow.com/a/19782939/729907

In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
 of 2013-10-19 on LEG570
Bzr revision: 114715 rgm <at> gnu.org-20131019023520-s8mwtib7xcx9e05w
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking 'CFLAGS=-O0 -g3' CPPFLAGS=-DGLYPH_DEBUG=1'

Message #8 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 15809 <at> debbugs.gnu.org
Subject: Re: bug#15809: 24.3.50;
 wrong defcustom type for `suggest-key-bindings'
Date: Fri, 07 Feb 2014 19:36:29 -0800

Drew Adams <drew.adams <at> oracle.com> writes:

> Instead of `integer' the `choice' should use `number' (and the code
> should then ignore negative values) or `restricted-sexp' with a test
> that the time be non-negative.

Or to be more general, perhaps there should be a custom interval type?  Like

(integer :minimum 1)

?

Or just `natnum'?

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #11 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 15809 <at> debbugs.gnu.org
Subject: RE: bug#15809: 24.3.50; wrong defcustom type for
 `suggest-key-bindings'
Date: Sat, 8 Feb 2014 18:14:42 -0800 (PST)

> > Instead of `integer' the `choice' should use `number' (and the
> > code should then ignore negative values) or `restricted-sexp'
> > with a test that the time be non-negative.
> 
> Or to be more general, perhaps there should be a custom interval
> type?  Like (integer :minimum 1)
> Or just `natnum'?

That's what `restricted-sexp' is for.  In this case it is a simple
expression.

(And what you suggest is not more general but less general than
`restricted-sexp'.  But that's OK too.)

Message #14 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 15809 <at> debbugs.gnu.org
Subject: Re: bug#15809: 24.3.50;
 wrong defcustom type for `suggest-key-bindings'
Date: Tue, 11 Feb 2014 03:47:04 -0800

Drew Adams <drew.adams <at> oracle.com> writes:

>> > Instead of `integer' the `choice' should use `number' (and the
>> > code should then ignore negative values) or `restricted-sexp'
>> > with a test that the time be non-negative.
>> 
>> Or to be more general, perhaps there should be a custom interval
>> type?  Like (integer :minimum 1)
>> Or just `natnum'?
>
> That's what `restricted-sexp' is for.  In this case it is a simple
> expression.

`restricted-sexp' is too general.  We'd lose type info.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #17 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 15809 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#15809: 24.3.50;
 wrong defcustom type for `suggest-key-bindings'
Date: Wed, 28 Oct 2020 00:50:10 -0700

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Drew Adams <drew.adams <at> oracle.com> writes:
>
>> Instead of `integer' the `choice' should use `number' (and the code
>> should then ignore negative values) or `restricted-sexp' with a test
>> that the time be non-negative.
>
> Or to be more general, perhaps there should be a custom interval type?  Like
>
> (integer :minimum 1)
>
> ?
>
> Or just `natnum'?

natnum sounds like it could be generally useful, yes.  We have plenty of
customizable things that should never be negative.

Message #20 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 15809 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#15809: 24.3.50; wrong defcustom type for
 `suggest-key-bindings'
Date: Wed, 28 Oct 2020 09:00:28 +0100

Stefan Kangas <stefan <at> marxist.se> writes:

>> Or to be more general, perhaps there should be a custom interval type?  Like
>>
>> (integer :minimum 1)
>>
>> ?
>>
>> Or just `natnum'?
>
> natnum sounds like it could be generally useful, yes.  We have plenty of
> customizable things that should never be negative.

Yeah, that's the most common numerical restriction (by far), and the few
variables that are numbers with other ranges can be done with a
defcustom predicate.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #23 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>, Stefan Kangas <stefan <at> marxist.se>
Cc: 15809 <at> debbugs.gnu.org
Subject: RE: bug#15809: 24.3.50; wrong defcustom type for
 `suggest-key-bindings'
Date: Wed, 28 Oct 2020 07:25:57 -0700 (PDT)

FWIW, "natural number", like "whole number", unfortunately
has two different meanings, 1... and 0..., depending on
who is talking.

https://en.wikipedia.org/wiki/Natural_number

Emacs has predicate `natnump', with alias `wholenump',
meaning 0...  So the doc for a defcustom type that
mentions "natural number" had better make clear which is
meant.  It can do that by mentioning predicate `natnump'. 

Message #26 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: Lars Ingebrigtsen <larsi <at> gnus.org>, 15809 <at> debbugs.gnu.org
Subject: Re: bug#15809: 24.3.50;
 wrong defcustom type for `suggest-key-bindings'
Date: Fri, 24 Sep 2021 16:32:21 -0700

Drew Adams <drew.adams <at> oracle.com> writes:

> FWIW, "natural number", like "whole number", unfortunately
> has two different meanings, 1... and 0..., depending on
> who is talking.
>
> https://en.wikipedia.org/wiki/Natural_number
>
> Emacs has predicate `natnump', with alias `wholenump',
> meaning 0...  So the doc for a defcustom type that
> mentions "natural number" had better make clear which is
> meant.  It can do that by mentioning predicate `natnump'.

The docstring of `natnump' defines it as "a nonnegative integer".

Message #29 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 15809 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#15809: 24.3.50;
 wrong defcustom type for `suggest-key-bindings'
Date: Fri, 24 Sep 2021 16:34:38 -0700

[Message part 1 (text/plain, inline)]

tags 15809 + patch
thanks

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Stefan Kangas <stefan <at> marxist.se> writes:
>
>>> Or to be more general, perhaps there should be a custom interval type?  Like
>>>
>>> (integer :minimum 1)
>>>
>>> ?
>>>
>>> Or just `natnum'?
>>
>> natnum sounds like it could be generally useful, yes.  We have plenty of
>> customizable things that should never be negative.
>
> Yeah, that's the most common numerical restriction (by far), and the few
> variables that are numbers with other ranges can be done with a
> defcustom predicate.

How about the attached?

[0001-New-type-natnum-for-defcustom.patch (text/x-diff, attachment)]

[0002-Set-type-of-suggest-key-bindings-to-natnum.patch (text/x-diff, attachment)]

Message #34 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 15809 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#15809: 24.3.50; wrong defcustom type for
 `suggest-key-bindings'
Date: Sat, 25 Sep 2021 03:09:19 +0200

Stefan Kangas <stefan <at> marxist.se> writes:

> How about the attached?

Looks good to me, except this detail:

> +(define-widget 'natnum 'restricted-sexp
> +  "A nonnegative integer."
> +  :tag "Integer (positive)"

In the tag here, that's a bit confusing.  Why not just say "Integer
(zero or larger)"?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #37 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>, Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: "15809 <at> debbugs.gnu.org" <15809 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#15809: 24.3.50; wrong defcustom type for
 `suggest-key-bindings'
Date: Sat, 25 Sep 2021 01:24:50 +0000

> How about the attached?

In some cases you say "must", in other cases you say "should".

As a :type restriction, on its own, the word to use is "must".

Of course, a :type can combine `natnum' with other type
clauses, so "should" _might_ in some cases, apply to the
resulting :type spec.

I suggest we stick to saying just what `natnum' itself does.
It _requires_ the value to be a nonnegative integer - no
"should be".

You could say that one can always assign an option a value
that doesn't match its :type spec.  So in practice, there's
no solid enforcement of the law.  Still, the law says the
value must be a nonnegative integer, regardless of whether
there are ways to escape enforcement.  It's the law that
gets written as the rule. ;-)

Message #40 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>, Stefan Kangas <stefan <at> marxist.se>
Cc: "15809 <at> debbugs.gnu.org" <15809 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#15809: 24.3.50; wrong defcustom type for
 `suggest-key-bindings'
Date: Sat, 25 Sep 2021 01:29:41 +0000

> > +(define-widget 'natnum 'restricted-sexp
> > +  "A nonnegative integer."
> > +  :tag "Integer (positive)"
> 
> In the tag here, that's a bit confusing.  Why not just say "Integer
> (zero or larger)"?

"Nonnegative integer" is the conventional and clear
way to say that.

We often (I do, at least), speak about a nonnegative
or nonpositive numeric prefix arg, for instance.

Message #43 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Lars Ingebrigtsen <larsi <at> gnus.org>,
 "15809 <at> debbugs.gnu.org" <15809 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#15809: 24.3.50; wrong defcustom type for
 `suggest-key-bindings'
Date: Sat, 25 Sep 2021 01:50:25 +0000

> > FWIW, "natural number", like "whole number", unfortunately
> > has two different meanings, 1... and 0..., depending on
> > who is talking.
> >
> >
> https://urldefense.com/v3/__https://en.wikipedia.org/wiki/Natural_numbe
> r__;!!ACWV5N9M2RV99hQ!YF8_QIyGvA34pZcXQ5IY8wSQQwrUUykjIfLCvd5eidW2mRgqe
> d8BnAbe2sG274Mx$
> >
> > Emacs has predicate `natnump', with alias `wholenump',
> > meaning 0...  So the doc for a defcustom type that
> > mentions "natural number" had better make clear which is
> > meant.  It can do that by mentioning predicate `natnump'.
> 
> The docstring of `natnump' defines it as "a nonnegative integer".

Which is why one fix is to mention `natnump'.  But
that makes a reader check the doc string of `natnump'.

It's about "the doc for a defcustom type that mentions
'natural number'".  It's the defcustom type that needs
the doc love.  The doc of `natnump' is OK already.

Message #46 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 15809 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#15809: 24.3.50;
 wrong defcustom type for `suggest-key-bindings'
Date: Fri, 24 Sep 2021 18:54:43 -0700

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

>> +(define-widget 'natnum 'restricted-sexp
>> +  "A nonnegative integer."
>> +  :tag "Integer (positive)"
>
> In the tag here, that's a bit confusing.  Why not just say "Integer
> (zero or larger)"?

I believe this is the preferred way to say it, for example that's what
we do in `natnump', and Wikipedia says:

    [...] the standard ISO 80000-2,[4][a] begin the natural numbers with
    0, corresponding to the non-negative integers 0, 1, 2, 3, ...,

But I don't feel very strongly about it; either way seems clear to me.

Message #49 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 15809 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#15809: 24.3.50; wrong defcustom type for
 `suggest-key-bindings'
Date: Sat, 25 Sep 2021 04:06:32 +0200

Stefan Kangas <stefan <at> marxist.se> writes:

> I believe this is the preferred way to say it, for example that's what
> we do in `natnump', and Wikipedia says:
>
>     [...] the standard ISO 80000-2,[4][a] begin the natural numbers with
>     0, corresponding to the non-negative integers 0, 1, 2, 3, ...,
>
> But I don't feel very strongly about it; either way seems clear to me.

Yeah, same here.  So please go ahead and push; if anybody wants to tweak
the strings here, that can be done afterwards.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #52 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Drew Adams <drew.adams <at> oracle.com>, Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: "15809 <at> debbugs.gnu.org" <15809 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#15809: 24.3.50;
 wrong defcustom type for `suggest-key-bindings'
Date: Fri, 24 Sep 2021 19:25:56 -0700

Drew Adams <drew.adams <at> oracle.com> writes:

>> How about the attached?
>
> In some cases you say "must", in other cases you say "should".

This inconsistency is there in the documentation already, compare:

  :type-error "This field should contain an integer"

With:

 @item integer
 The value must be an integer.

Sorting it out seems beyond the scope of this bug report.  If we even
need to do anything about it.

> You could say that one can always assign an option a value
> that doesn't match its :type spec.  So in practice, there's
> no solid enforcement of the law.  Still, the law says the
> value must be a nonnegative integer, regardless of whether
> there are ways to escape enforcement.  It's the law that
> gets written as the rule. ;-)

I basically agree, but we use "must" and "should" interchangeably all
over Emacs.  In context, they mean more or less the same thing.

Message #55 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 15809 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#15809: 24.3.50;
 wrong defcustom type for `suggest-key-bindings'
Date: Fri, 24 Sep 2021 19:43:29 -0700

tags 15809 fixed
close 15809 28.1
thanks

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Stefan Kangas <stefan <at> marxist.se> writes:
>
>> I believe this is the preferred way to say it, for example that's what
>> we do in `natnump', and Wikipedia says:
>>
>>     [...] the standard ISO 80000-2,[4][a] begin the natural numbers with
>>     0, corresponding to the non-negative integers 0, 1, 2, 3, ...,
>>
>> But I don't feel very strongly about it; either way seems clear to me.
>
> Yeah, same here.  So please go ahead and push; if anybody wants to tweak
> the strings here, that can be done afterwards.

OK, thanks.  Now pushed to master as commit f1071bf08e.

Message #64 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Mattias Engdegård <mattiase <at> acm.org>
To: 15809 <at> debbugs.gnu.org
Subject: Re: bug#15809: 24.3.50; wrong defcustom type for
 `suggest-key-bindings' 
Date: Sat, 25 Sep 2021 12:50:36 +0200

This is a test to find out why mails sent to debbugs sometimes just disappear.
Please ignore, unless you are an admin!

Message #67 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Mattias Engdegård <mattiase <at> acm.org>
To: 15809 <at> debbugs.gnu.org
Subject: Re: bug#15809: 24.3.50; wrong defcustom type for
 `suggest-key-bindings' 
Date: Sat, 25 Sep 2021 12:57:37 +0200

[ Resent to debugs only, because my previous attempt was eaten by a grue.
  Sorry if you get this twice or not at all.
  A modern Emacs bug tracker cannot arrive soon enough! ]

> (define-widget 'natnum 'restricted-sexp
>  "A nonnegative integer."
>  :tag "Integer (positive)"

Sorry, but this is just wrong. 0 is not a positive integer. If nobody fixes this then I will.

And regarding whether natural numbers include zero, the answer is that yes, they do. The notion that they don't is antiquated; today 0 is assumed to be included by default unless otherwise stated or hinted in the notation. Let's not spread some silly 19th century bickering about something that was settled long ago.

Message #70 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Mattias Engdegård <mattiase <at> acm.org>
Cc: Lars Ingebrigtsen <larsi <at> gnus.org>, 15809 <at> debbugs.gnu.org,
 Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#15809: 24.3.50;
 wrong defcustom type for `suggest-key-bindings'
Date: Sat, 25 Sep 2021 06:00:20 -0700

Mattias Engdegård <mattiase <at> acm.org> writes:

>> (define-widget 'natnum 'restricted-sexp
>>   "A nonnegative integer."
>>   :tag "Integer (positive)"
>
> Sorry, but this is just wrong. 0 is not a positive integer.

The text does not say that zero is positive.

Feel free to improve it, but I don't think the terminology "nonnegative"
is unusual or incorrect.  For example, here is the definition of
"nonnegative integer" from Wolfram MathWorld:

    Nonnegative Integer

    An integer that is either 0 or positive, i.e., a member of the set
    ℤ^* = {0} ∪ ℤ^+, where Ζ-+ denotes the positive integers.

    SEE ALSO: Negative Integer, Nonpositive Integer, Positive Integer, Z-*

    https://mathworld.wolfram.com/NonnegativeInteger.html

Message #73 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Mattias Engdegård <mattiase <at> acm.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Lars Ingebrigtsen <larsi <at> gnus.org>, 15809 <at> debbugs.gnu.org,
 Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#15809: 24.3.50; wrong defcustom type for
 `suggest-key-bindings'
Date: Sat, 25 Sep 2021 15:07:33 +0200

25 sep. 2021 kl. 15.00 skrev Stefan Kangas <stefan <at> marxist.se>:

>>> (define-widget 'natnum 'restricted-sexp
>>>  "A nonnegative integer."
>>>  :tag "Integer (positive)"
>> 
>> Sorry, but this is just wrong. 0 is not a positive integer.
> 
> The text does not say that zero is positive.

Actually the tag text does.

> Feel free to improve it, but I don't think the terminology "nonnegative"
> is unusual or incorrect.

It's fine! But "Integer (positive)" isn't, if we are talking about something that can be zero.

What about "Integer (nonnegative)", "Integer (positive or zero)", or something else?

And please accept my apologies about the somewhat unfriendly tone of my original message. I'm really very happy with the change otherwise.

Message #76 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Mattias Engdegård <mattiase <at> acm.org>
Cc: Lars Ingebrigtsen <larsi <at> gnus.org>, 15809 <at> debbugs.gnu.org,
 Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#15809: 24.3.50;
 wrong defcustom type for `suggest-key-bindings'
Date: Sat, 25 Sep 2021 07:53:57 -0700

Mattias Engdegård <mattiase <at> acm.org> writes:

> 25 sep. 2021 kl. 15.00 skrev Stefan Kangas <stefan <at> marxist.se>:
>
>>>> (define-widget 'natnum 'restricted-sexp
>>>>  "A nonnegative integer."
>>>>  :tag "Integer (positive)"
>>>
>>> Sorry, but this is just wrong. 0 is not a positive integer.
>>
>> The text does not say that zero is positive.
>
> Actually the tag text does.

Well spotted, thanks!  That is completely wrong, yes.

> What about "Integer (nonnegative)", "Integer (positive or zero)", or
> something else?

Both sound good to me.  The second one doesn't just repeat what is
already said in the other text, so I slightly prefer that one.  Feel
free to install whichever you like better (or tell me to do it if that's
easier).

> And please accept my apologies about the somewhat unfriendly tone of
> my original message. I'm really very happy with the change otherwise.

No reason to apologize.  I was mostly wondering what was the reason for
all the commotion, but now I can see why.  :-)

Message #79 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>, Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: "15809 <at> debbugs.gnu.org" <15809 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#15809: 24.3.50; wrong defcustom type for
 `suggest-key-bindings'
Date: Sat, 25 Sep 2021 15:22:00 +0000

> >> How about the attached?
> >
> > In some cases you say "must", in other cases you say "should".
> 
> This inconsistency is there in the documentation already, compare:
>   :type-error "This field should contain an integer"
> With:
>  @item integer
>  The value must be an integer.
> 
> Sorting it out seems beyond the scope of this bug report.  If we even
> need to do anything about it.

(FWIW)

I'm not asking that you fix this throughout Emacs.
I'm asking you to DTRT for this bug fix, i.e., for
this defcustom.

> > You could say that one can always assign an option a value
> > that doesn't match its :type spec.  So in practice, there's
> > no solid enforcement of the law.  Still, the law says the
> > value must be a nonnegative integer, regardless of whether
> > there are ways to escape enforcement.  It's the law that
> > gets written as the rule. ;-)
> 
> I basically agree, but we use "must" and "should" interchangeably all
> over Emacs.  In context, they mean more or less the same thing.

Just because there are bugs elsewhere is no reason
to create new, similar bugs.

There's a real, big difference between "must" and
"should".  And in general "should" is a weasel word
and "should" ;-) be avoided in technical doc.

In the case of :type, there's no ambiguity or room
for waffling (except what I mentioned - if you use
the Customize UI there's no room at all).  The right
word to use for this is "must".

Message #82 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Mattias Engdegård <mattiase <at> acm.org>, Stefan Kangas
 <stefan <at> marxist.se>
Cc: Lars Ingebrigtsen <larsi <at> gnus.org>,
 "15809 <at> debbugs.gnu.org" <15809 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#15809: 24.3.50; wrong defcustom type for
 `suggest-key-bindings' 
Date: Sat, 25 Sep 2021 15:24:48 +0000

> > (define-widget 'natnum 'restricted-sexp
> >   "A nonnegative integer."
> >   :tag "Integer (positive)"
> 
> Sorry, but this is just wrong. 0 is not a positive integer. If nobody
> fixes this then I will.

100% agreement that "positive" is wrong - it does
not apply to 0.

> And regarding whether natural numbers include zero, the answer is that
> yes, they do. The notion that they don't is antiquated; today 0 is
> assumed to be included by default unless otherwise stated or hinted in
> the notation. Let's not spread some silly 19th century bickering about
> something that was settled long ago.

It's not about what is current or appropriate in
math etc.  It's about providing doc that leaves
less room for confusion.  And yes, "natural number"
is understood differently by different people,
unfortunately.  It's not hard to be clear, here.
"Nonnegative integer" is short, clear, unambiguous.

Message #85 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>, Mattias Engdegård
 <mattiase <at> acm.org>
Cc: Lars Ingebrigtsen <larsi <at> gnus.org>,
 "15809 <at> debbugs.gnu.org" <15809 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#15809: 24.3.50; wrong defcustom type for
 `suggest-key-bindings'
Date: Sat, 25 Sep 2021 15:31:46 +0000

> >> (define-widget 'natnum 'restricted-sexp
> >>   "A nonnegative integer."
> >>   :tag "Integer (positive)"
> >
> > Sorry, but this is just wrong. 0 is not a positive integer.
> 
> The text does not say that zero is positive.

The doc string doesn't, but the tag appears to.
The tag should anyway say what the field is for,
not (usually) what its type is.

If you do add indication of the type to the tag
(i.e., in addition to the field description -
what the field is for / means), then please use
what you have in the doc string.

The field value must be a nonnegative integer.
It need not be a positive integer.

Message #88 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Drew Adams <drew.adams <at> oracle.com>, Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: "15809 <at> debbugs.gnu.org" <15809 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#15809: 24.3.50;
 wrong defcustom type for `suggest-key-bindings'
Date: Sat, 25 Sep 2021 08:56:42 -0700

Drew Adams <drew.adams <at> oracle.com> writes:

> I'm not asking that you fix this throughout Emacs.
> I'm asking you to DTRT for this bug fix, i.e., for
> this defcustom.

I think in the context of this bug report, TRT is to do nothing, as we
have the convention that "should" and "must" is the same all over Emacs.
Unless we decide that "should" is generally to be avoided, there is
nothing to do.

> There's a real, big difference between "must" and
> "should".  And in general "should" is a weasel word
> and "should" ;-) be avoided in technical doc.

My suggestion is to report this as a separate bug.  If we would decide
to do anything, I think it would be most productive to do it in the form
of an amendment to `(elisp) Documentation Tips'.

Message #91 received at 15809 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 15809 <at> debbugs.gnu.org, larsi <at> gnus.org, stefan <at> marxist.se
Subject: Re: bug#15809: [External] : Re: bug#15809: 24.3.50;
 wrong defcustom type for `suggest-key-bindings'
Date: Sat, 25 Sep 2021 19:01:16 +0300

> From: Drew Adams <drew.adams <at> oracle.com>
> Date: Sat, 25 Sep 2021 15:22:00 +0000
> Cc: "15809 <at> debbugs.gnu.org" <15809 <at> debbugs.gnu.org>
> 
> There's a real, big difference between "must" and
> "should".  And in general "should" is a weasel word
> and "should" ;-) be avoided in technical doc.

True for documents that specify formal requirements.  Which our
documentation isn't.  So this is an unnecessary complication, and we
shouldn't be bothered by it.

Message #96 received at 15809-done <at> debbugs.gnu.org (full text, mbox):

From: Mattias Engdegård <mattiase <at> acm.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Lars Ingebrigtsen <larsi <at> gnus.org>, 15809-done <at> debbugs.gnu.org,
 Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#15809: 24.3.50; wrong defcustom type for
 `suggest-key-bindings' 
Date: Sat, 25 Sep 2021 20:32:04 +0200

> Both sound good to me.  The second one doesn't just repeat what is
> already said in the other text, so I slightly prefer that one.

Then that's what it will be. Thank you, pushed and closed.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.