bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Drew Adams]

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@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'

bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@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/

bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Drew Adams]

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

bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@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/

bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Drew Adams <drew.adams@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.

bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Lars Ingebrigtsen]

Stefan Kangas <stefan@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

bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Drew Adams]

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

bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Stefan Kangas]

Drew Adams <drew.adams@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".

bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 587 bytes --]

tags 15809 + patch
thanks

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Stefan Kangas <stefan@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?

[-- Attachment #2: 0001-New-type-natnum-for-defcustom.patch --]
[-- Type: text/x-diff, Size: 1984 bytes --]

From 7313d60a163b66af039efc69046e4df4dff21457 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Sat, 25 Sep 2021 01:15:49 +0200
Subject: [PATCH 1/2] New :type natnum for defcustom

* lisp/wid-edit.el (natnum): New widget type.  (Bug#15809)
* doc/lispref/customize.texi (Simple Types): Document it.
---
 doc/lispref/customize.texi | 3 +++
 etc/NEWS                   | 5 +++++
 lisp/wid-edit.el           | 7 +++++++
 3 files changed, 15 insertions(+)

diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index bc35982c17..b93b8bc015 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -594,6 +594,9 @@ Simple Types
 @item integer
 The value must be an integer.
 
+@item natnum
+The value must be a nonnegative integer.
+
 @item number
 The value must be a number (floating point or integer).
 
diff --git a/etc/NEWS b/etc/NEWS
index c266dddafa..b2e7331517 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -3724,6 +3724,11 @@ instead of only becoming available after doing (for instance)
 ---
 ** ':safe' settings in 'defcustom' are now propagated to the loaddefs files.
 
++++
+** New ':type' for 'defcustom' for nonnegative integers.
+The new 'natnum' type can be used for options that should be
+nonnegative integers.
+
 +++
 ** ERT can now output more verbose test failure reports.
 If the 'EMACS_TEST_VERBOSE' environment variable is set, failure
diff --git a/lisp/wid-edit.el b/lisp/wid-edit.el
index ab358da7e3..72353b9190 100644
--- a/lisp/wid-edit.el
+++ b/lisp/wid-edit.el
@@ -3644,6 +3644,13 @@ 'integer
   :type-error "This field should contain an integer"
   :match-alternatives '(integerp))
 
+(define-widget 'natnum 'restricted-sexp
+  "A nonnegative integer."
+  :tag "Integer (positive)"
+  :value 0
+  :type-error "This field should contain a nonnegative integer"
+  :match-alternatives '(natnump))
+
 (define-widget 'number 'restricted-sexp
   "A number (floating point or integer)."
   :tag "Number"
-- 
2.30.2


[-- Attachment #3: 0002-Set-type-of-suggest-key-bindings-to-natnum.patch --]
[-- Type: text/x-diff, Size: 838 bytes --]

From 95127f0d7441999c78e4c4e9ab8217757148e5c9 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Sat, 25 Sep 2021 01:25:47 +0200
Subject: [PATCH 2/2] Set :type of suggest-key-bindings to natnum

* lisp/simple.el (suggest-key-bindings): Set :type to
natnum.  (Bug#15809)
---
 lisp/simple.el | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lisp/simple.el b/lisp/simple.el
index 298e3ea5ee..dd480396f6 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -2144,7 +2144,7 @@ suggest-key-bindings
 \\[execute-extended-command] for all commands that have them."
   :group 'keyboard
   :type '(choice (const :tag "off" nil)
-                 (integer :tag "time" 2)
+                 (natnum :tag "time" 2)
                  (other :tag "on")))
 
 (defcustom extended-command-suggest-shorter t
-- 
2.30.2

bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Lars Ingebrigtsen]

Stefan Kangas <stefan@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

bug#15809: [External] : Re: bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Drew Adams]

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

bug#15809: [External] : Re: bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Drew Adams]

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

bug#15809: [External] : Re: bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Drew Adams]

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

bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Stefan Kangas]

Lars Ingebrigtsen <larsi@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.

bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Lars Ingebrigtsen]

Stefan Kangas <stefan@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

bug#15809: [External] : Re: bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Stefan Kangas]

Drew Adams <drew.adams@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.

bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Stefan Kangas]

tags 15809 fixed
close 15809 28.1
thanks

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Stefan Kangas <stefan@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.

bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Mattias Engdegård]

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

bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Mattias Engdegård]

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

bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Stefan Kangas]

Mattias Engdegård <mattiase@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

bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Mattias Engdegård]

25 sep. 2021 kl. 15.00 skrev Stefan Kangas <stefan@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.

bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Stefan Kangas]

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

> 25 sep. 2021 kl. 15.00 skrev Stefan Kangas <stefan@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.  :-)

bug#15809: [External] : Re: bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Drew Adams]

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

bug#15809: [External] : Re: bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Stefan Kangas]

Drew Adams <drew.adams@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'.

bug#15809: [External] : Re: bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> Date: Sat, 25 Sep 2021 15:22:00 +0000
> Cc: "15809@debbugs.gnu.org" <15809@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.

bug#15809: 24.3.50; wrong defcustom type for `suggest-key-bindings'

[Mattias Engdegård]

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