GNU bug report logs -
#5744
23.1.92; doc string of `version<' etc.
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 5744 in the body.
You can then email your comments to 5744 AT debbugs.gnu.org in the normal way.
Toggle the display of automated, internal messages from the tracker.
Report forwarded
to
owner <at> debbugs.gnu.org, bug-gnu-emacs <at> gnu.org:
bug#5744; Package
emacs.
(Sat, 20 Mar 2010 15:00:03 GMT)
Full text and
rfc822 format available.
Acknowledgement sent
to
"Drew Adams" <drew.adams <at> oracle.com>:
New bug report received and forwarded. Copy sent to
bug-gnu-emacs <at> gnu.org.
(Sat, 20 Mar 2010 15:00:04 GMT)
Full text and
rfc822 format available.
Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):
1. Change "lesser than" to "less than".
2. Say explicitly that V1 and V2 are strings. Say in fact that they are strings
of the format returned by variable `emacs-version'.
Information forwarded
to
owner <at> debbugs.gnu.org, bug-gnu-emacs <at> gnu.org:
bug#5744; Package
emacs.
(Sat, 20 Mar 2010 17:44:02 GMT)
Full text and
rfc822 format available.
Message #8 received at 5744 <at> debbugs.gnu.org (full text, mbox):
"Drew Adams" <drew.adams <at> oracle.com> writes:
> 1. Change "lesser than" to "less than".
"Lesser" seems completely fine to me, but I'm not a native speaker.
>
> 2. Say explicitly that V1 and V2 are strings.
I think that's clear from the docstring, but more clarity never hurts, yes.
> Say in fact that they are strings of the format returned by variable
> `emacs-version'.
That would be misleading at best IMHO.
The function accepts a far wider set of arguments.
Also note that you would most probably want to change docstrings of
the whole family of the version functions to stay consistent.
Information forwarded
to
owner <at> debbugs.gnu.org, bug-gnu-emacs <at> gnu.org:
bug#5744; Package
emacs.
(Sat, 20 Mar 2010 18:11:02 GMT)
Full text and
rfc822 format available.
Message #11 received at 5744 <at> debbugs.gnu.org (full text, mbox):
> > 1. Change "lesser than" to "less than".
>
> "Lesser" seems completely fine to me, but I'm not a native speaker.
That's why it seems completely fine to you. It's not English. ;-)
"less than" is correct; "lesser than" is not correct.
> > 2. Say explicitly that V1 and V2 are strings.
>
> I think that's clear from the docstring, but more clarity
> never hurts, yes.
>
> > Say in fact that they are strings of the format returned by variable
> > `emacs-version'.
>
> That would be misleading at best IMHO.
> The function accepts a far wider set of arguments.
Oh really? Then all the more reason to explicitly specify the accepted formats
(completely).
You cannot use a function reliably if you don't know what kinds of arguments it
handles.
> Also note that you would most probably want to change docstrings of
> the whole family of the version functions to stay consistent.
Of course. That's why I wrote "`version<' ETC." in the subject line.
Also:
3. Specifically state the ordering rule. Wrt alphabetical comparison, don't just
give an example, state that letters are compared alphabetically (and state
whether that's case-sensitive).
4. Mention at least one of these version-comparison functions in the Elisp
manual, node `Version Info'.
Information forwarded
to
owner <at> debbugs.gnu.org, bug-gnu-emacs <at> gnu.org:
bug#5744; Package
emacs.
(Sat, 20 Mar 2010 19:51:01 GMT)
Full text and
rfc822 format available.
Message #14 received at 5744 <at> debbugs.gnu.org (full text, mbox):
"Drew Adams" <drew.adams <at> oracle.com> writes:
>> > 1. Change "lesser than" to "less than".
>>
>> "Lesser" seems completely fine to me, but I'm not a native speaker.
>
> That's why it seems completely fine to you. It's not English. ;-)
> "less than" is correct; "lesser than" is not correct.
Right, I see it now -- "lesser" is fine, but not with "than". Thank you.
>
>> > 2. Say explicitly that V1 and V2 are strings.
>>
>> I think that's clear from the docstring, but more clarity
>> never hurts, yes.
>>
>> > Say in fact that they are strings of the format returned by variable
>> > `emacs-version'.
>>
>> That would be misleading at best IMHO.
>> The function accepts a far wider set of arguments.
>
> Oh really? Then all the more reason to explicitly specify the accepted formats
> (completely).
> You cannot use a function reliably if you don't know what kinds of arguments
> it handles.
The actual behaviour depends on values of a few variables. See the doc
strings for `version-regexp-alist', `version-to-list' and
`version-separator'.
Perhaps pointing to them (and fixing the typos) in all the
version-related functions would be a solution?
>
>> Also note that you would most probably want to change docstrings of
>> the whole family of the version functions to stay consistent.
>
> Of course. That's why I wrote "`version<' ETC." in the subject line.
Indeed, I noticed that only after having replied, I'm sorry.
Štěpán
> Also:
>
> 3. Specifically state the ordering rule. Wrt alphabetical comparison, don't
> just
> give an example, state that letters are compared alphabetically (and state
> whether that's case-sensitive).
>
> 4. Mention at least one of these version-comparison functions in the Elisp
> manual, node `Version Info'.
Information forwarded
to
owner <at> debbugs.gnu.org, bug-gnu-emacs <at> gnu.org:
bug#5744; Package
emacs.
(Sat, 20 Mar 2010 19:57:02 GMT)
Full text and
rfc822 format available.
Message #17 received at 5744 <at> debbugs.gnu.org (full text, mbox):
> The actual behaviour depends on values of a few variables. See the doc
> strings for `version-regexp-alist', `version-to-list' and
> `version-separator'.
>
> Perhaps pointing to them (and fixing the typos) in all the
> version-related functions would be a solution?
Yes. If there is a one of them that covers everything (e.g. by linking to the
others), then it would be enough to link to just that one. But if the reader
needs to understand all 3 variables in order to understand the acceptable
formats, then we should link to all 3.
> >> Also note that you would most probably want to change docstrings of
> >> the whole family of the version functions to stay consistent.
> >
> > Of course. That's why I wrote "`version<' ETC." in the subject line.
>
> Indeed, I noticed that only after having replied, I'm sorry.
No problem. Admittedly, it wasn't very obvious.
Information forwarded
to
owner <at> debbugs.gnu.org, bug-gnu-emacs <at> gnu.org:
bug#5744; Package
emacs.
(Sat, 20 Mar 2010 20:47:01 GMT)
Full text and
rfc822 format available.
Message #20 received at 5744 <at> debbugs.gnu.org (full text, mbox):
> From: "Drew Adams" <drew.adams <at> oracle.com>
> Date: Sat, 20 Mar 2010 11:10:10 -0700
> Cc: 5744 <at> debbugs.gnu.org
>
> > > 1. Change "lesser than" to "less than".
> >
> > "Lesser" seems completely fine to me, but I'm not a native speaker.
>
> That's why it seems completely fine to you. It's not English. ;-)
> "less than" is correct; "lesser than" is not correct.
With versions, it might be better to use "older" and "newer" instead.
Information forwarded
to
owner <at> debbugs.gnu.org, bug-gnu-emacs <at> gnu.org:
bug#5744; Package
emacs.
(Sat, 20 Mar 2010 21:13:02 GMT)
Full text and
rfc822 format available.
Message #23 received at 5744 <at> debbugs.gnu.org (full text, mbox):
> With versions, it might be better to use "older" and "newer" instead.
Good point.
(And the rest of the doc string will (should) make clear just what string
comparison is involved, as already discussed.)
Information forwarded
to
owner <at> debbugs.gnu.org, bug-gnu-emacs <at> gnu.org:
bug#5744; Package
emacs.
(Sun, 21 Mar 2010 01:13:01 GMT)
Full text and
rfc822 format available.
Message #26 received at 5744 <at> debbugs.gnu.org (full text, mbox):
Eli Zaretskii <eliz <at> gnu.org> writes:
> With versions, it might be better to use "older" and "newer" instead.
I don't think it is possible to come up with an algorithm for that.
There may be maintainence branches still running after a new major
release (eg gcc 4.3.4 is newer than 4.4.1, despite being a lower
version).
Information forwarded
to
owner <at> debbugs.gnu.org, bug-gnu-emacs <at> gnu.org:
bug#5744; Package
emacs.
(Sun, 21 Mar 2010 04:13:01 GMT)
Full text and
rfc822 format available.
Message #29 received at 5744 <at> debbugs.gnu.org (full text, mbox):
> From: Jason Rumney <jasonr <at> gnu.org>
> Cc: Drew Adams <drew.adams <at> oracle.com>, stepnem <at> gmail.com, 5744 <at> debbugs.gnu.org
> Date: Sun, 21 Mar 2010 09:12:11 +0800
>
> Eli Zaretskii <eliz <at> gnu.org> writes:
>
> > With versions, it might be better to use "older" and "newer" instead.
>
> I don't think it is possible to come up with an algorithm for that.
I didn't suggest to change the existing algorithm, only the doc
string.
> There may be maintainence branches still running after a new major
> release (eg gcc 4.3.4 is newer than 4.4.1, despite being a lower
> version).
I didn't mean "newer" by its release date. 4.4.1 is "newer" than
4.3.4, no matter what their release dates are.
Maybe "lower" and "higher" is indeed a better terminology. Or maybe
we should use both, to drive the point home.
Information forwarded
to
owner <at> debbugs.gnu.org, bug-gnu-emacs <at> gnu.org:
bug#5744; Package
emacs.
(Sun, 21 Mar 2010 05:20:03 GMT)
Full text and
rfc822 format available.
Message #32 received at 5744 <at> debbugs.gnu.org (full text, mbox):
> > > With versions, it might be better to use "older" and
> > > "newer" instead.
> >
> > I don't think it is possible to come up with an algorithm for that.
>
> I didn't suggest to change the existing algorithm, only the doc
> string.
>
> > There may be maintainence branches still running after a new major
> > release (eg gcc 4.3.4 is newer than 4.4.1, despite being a lower
> > version).
>
> I didn't mean "newer" by its release date. 4.4.1 is "newer" than
> 4.3.4, no matter what their release dates are.
>
> Maybe "lower" and "higher" is indeed a better terminology. Or maybe
> we should use both, to drive the point home.
It's not the names that are as important as communicating what they stand for.
I, for instance, don't yet know what exactly is meant. Why the date of 4.3.4
might be later than 4.4.1, even though the latter is "newer".
Try explaining it (the concepts) first, in simple terms. Then the words (good
names) will come.
Information forwarded
to
owner <at> debbugs.gnu.org, bug-gnu-emacs <at> gnu.org:
bug#5744; Package
emacs.
(Sun, 21 Mar 2010 18:01:02 GMT)
Full text and
rfc822 format available.
Message #35 received at 5744 <at> debbugs.gnu.org (full text, mbox):
> From: "Drew Adams" <drew.adams <at> oracle.com>
> Cc: <stepnem <at> gmail.com>, <5744 <at> debbugs.gnu.org>
> Date: Sat, 20 Mar 2010 22:18:01 -0700
>
> It's not the names that are as important as communicating what they stand for.
The best terminology is the one that doesn't need explaining, because
it speaks for itself.
> I, for instance, don't yet know what exactly is meant. Why the date of 4.3.4
> might be later than 4.4.1, even though the latter is "newer".
If the 4.3 branch and the 4.4 branch are developed in parallel in some
project, the chronological order between releases from the two
branches is unpredictable.
> Try explaining it (the concepts) first, in simple terms. Then the words (good
> names) will come.
These functions compare version strings in their numerical order, with
some heuristics sprinkled on top. It's not easy to explain that in
simple words, especially since the heuristics can be customized.
Finding words that explain themselves will go a long way towards
resolving this difficulty.
Information forwarded
to
owner <at> debbugs.gnu.org, bug-gnu-emacs <at> gnu.org:
bug#5744; Package
emacs.
(Sun, 21 Mar 2010 18:48:02 GMT)
Full text and
rfc822 format available.
Message #38 received at 5744 <at> debbugs.gnu.org (full text, mbox):
> > It's not the names that are as important as communicating
> > what they stand for.
>
> The best terminology is the one that doesn't need explaining, because
> it speaks for itself.
Obviously. My point was about _finding_ that best terminology.
So far, it's not clear (at least to me) what the behavior is, so suggesting
names is driven partly by ignorance (at least on my part).
You suggested "newer", and then it was pointed out that that was misleading,
since the behavior doesn't correspond to release date. Then you suggested
"higher", but there might be problems with that also, and that doesn't by itself
convey any sense of newness.
If you, who are familiar with the actual behavior, want to just come up with
names on your own, fine - go for it.
But if you want some help, then first express what the comparison _is_, and then
perhaps some of us who are not familiar with the behavior can help you in your
quest for the best terminology.
This technique is nothing new. It is used by those involved with requirements
analysis, documentation, "knowledge acquisition", specification, and other
fields taht involve description and naming.
(That includes much in the domain of software engineering, but it doesn't follow
that all developers take the time to think through the concepts before coming up
with names.)
Yes, the terms in which you think of the concepts do make a difference, I agree.
But you have to start somewhere.
> > I, for instance, don't yet know what exactly is meant. Why
> > the date of 4.3.4 might be later than 4.4.1, even though the
> > latter is "newer".
>
> If the 4.3 branch and the 4.4 branch are developed in parallel in some
> project, the chronological order between releases from the two
> branches is unpredictable.
Got it.
> > Try explaining it (the concepts) first, in simple terms.
> > Then the words (good names) will come.
>
> These functions compare version strings in their numerical order,
If it is close to a numerical order (e.g. one of the most familiar numerical
orderings) then "greater than" is probably the best first approximation of what
the comparison is.
> with some heuristics sprinkled on top. It's not easy to explain that in
> simple words, especially since the heuristics can be customized.
If no info about the heuristics is given - no explanation of how a familiar
numerical ordering is modified by them, then stick with "greater than" or a
similar term that suggests numerical order.
If the numerical order used is similar to something like Dewey-decimal ordering,
then it might help to mention that too. I don't know whether that is the case -
I'm just mentioning that that is a particular kind of dotted numerical order
that many people are familiar with. If this is similar to that, then that
similarity could be mentioned as an aid to understanding - if it helps.
> Finding words that explain themselves will go a long way towards
> resolving this difficulty.
Of course. And vice versa.
With or without the best words, however, the specific behavior (nature of the
ordering) needs to be described to users at some point, somewhere.
It need not all be described in the doc string of a comparison predicate, but
that doc string should at least point to a place where it is described clearly
and completely. That place (or those places) might be the doc string(s) of the
customization option(s) you refer to, for example.
So far in this thread, all that's been described is a numerical order modified
somehow by unspecified heuristics. With only that to go on, I'd suggest sticking
with "greater than".
Severity set to 'minor' from 'normal'
Request was from
Glenn Morris <rgm <at> gnu.org>
to
control <at> debbugs.gnu.org.
(Mon, 22 Mar 2010 21:32:02 GMT)
Full text and
rfc822 format available.
Reply sent
to
Eli Zaretskii <eliz <at> gnu.org>:
You have taken responsibility.
(Sat, 27 Mar 2010 12:39:02 GMT)
Full text and
rfc822 format available.
Notification sent
to
"Drew Adams" <drew.adams <at> oracle.com>:
bug acknowledged by developer.
(Sat, 27 Mar 2010 12:39:02 GMT)
Full text and
rfc822 format available.
Message #45 received at 5744-done <at> debbugs.gnu.org (full text, mbox):
> From: "Drew Adams" <drew.adams <at> oracle.com>
> Cc: <stepnem <at> gmail.com>, <5744 <at> debbugs.gnu.org>
> Date: Sat, 20 Mar 2010 14:12:18 -0700
>
> > With versions, it might be better to use "older" and "newer" instead.
>
> Good point.
>
> (And the rest of the doc string will (should) make clear just what string
> comparison is involved, as already discussed.)
Fixed (on the Emacs-23 branch) with this patch:
=== modified file 'lisp/ChangeLog'
--- lisp/ChangeLog 2010-03-26 08:58:41 +0000
+++ lisp/ChangeLog 2010-03-27 12:31:04 +0000
@@ -1,3 +1,10 @@
+2010-03-27 Eli Zaretskii <eliz <at> gnu.org>
+
+ * subr.el (version-regexp-alist, version-to-list)
+ (version-list-<, version-list-=, version-list-<=)
+ (version-list-not-zero, version<, version<=, version=): Doc fix.
+ (Bug#5744).
+
2010-03-26 YAMAMOTO Mitsuharu <mituharu <at> math.s.chiba-u.ac.jp>
Nick Roberts <nickrob <at> snap.net.nz>
=== modified file 'lisp/subr.el'
--- lisp/subr.el 2010-03-03 03:58:26 +0000
+++ lisp/subr.el 2010-03-27 12:31:04 +0000
@@ -3573,11 +3573,11 @@ Usually the separator is \".\", but it c
("^[-_+ ]cvs$" . -3) ; treat "1.2.3-CVS" as alpha release
("^[-_+ ]?b\\(eta\\)?$" . -2)
("^[-_+ ]?\\(pre\\|rc\\)$" . -1))
- "*Specify association between non-numeric version part and a priority.
+ "*Specify association between non-numeric version and its priority.
This association is used to handle version string like \"1.0pre2\",
\"0.9alpha1\", etc. It's used by `version-to-list' (which see) to convert the
-non-numeric part to an integer. For example:
+non-numeric part of a version string to an integer. For example:
String Version Integer List Version
\"1.0pre2\" (1 0 -1 2)
@@ -3595,15 +3595,15 @@ Each element has the following form:
Where:
REGEXP regexp used to match non-numeric part of a version string.
- It should begin with a `^' anchor and end with a `$' to
+ It should begin with the `^' anchor and end with a `$' to
prevent false hits. Letter-case is ignored while matching
REGEXP.
-PRIORITY negative integer which indicate the non-numeric priority.")
+PRIORITY a negative integer specifying non-numeric priority of REGEXP.")
(defun version-to-list (ver)
- "Convert version string VER into an integer list.
+ "Convert version string VER into a list of integers.
The version syntax is given by the following EBNF:
@@ -3617,17 +3617,17 @@ The version syntax is given by the follo
The NUMBER part is optional if SEPARATOR is a match for an element
in `version-regexp-alist'.
-As an example of valid version syntax:
+Examples of valid version syntax:
1.0pre2 1.0.7.5 22.8beta3 0.9alpha1 6.9.30Beta
-As an example of invalid version syntax:
+Examples of invalid version syntax:
1.0prepre2 1.0..7.5 22.8X3 alpha3.2 .5
-As an example of version convertion:
+Examples of version conversion:
- String Version Integer List Version
+ Version String Version as a List of Integers
\"1.0.7.5\" (1 0 7 5)
\"1.0pre2\" (1 0 -1 2)
\"1.0PRE2\" (1 0 -1 2)
@@ -3673,12 +3673,12 @@ See documentation for `version-separator
(defun version-list-< (l1 l2)
- "Return t if integer list L1 is lesser than L2.
+ "Return t if L1, a list specification of a version, is lower than L2.
-Note that integer list (1) is equal to (1 0), (1 0 0), (1 0 0 0),
-etc. That is, the trailing zeroes are irrelevant. Also, integer
-list (1) is greater than (1 -1) which is greater than (1 -2)
-which is greater than (1 -3)."
+Note that a version specified by the list (1) is equal to (1 0),
+\(1 0 0), (1 0 0 0), etc. That is, the trailing zeros are insignificant.
+Also, a version given by the list (1) is higher than (1 -1), which in
+turn is higher than (1 -2), which is higher than (1 -3)."
(while (and l1 l2 (= (car l1) (car l2)))
(setq l1 (cdr l1)
l2 (cdr l2)))
@@ -3694,12 +3694,12 @@ which is greater than (1 -3)."
(defun version-list-= (l1 l2)
- "Return t if integer list L1 is equal to L2.
+ "Return t if L1, a list specification of a version, is equal to L2.
-Note that integer list (1) is equal to (1 0), (1 0 0), (1 0 0 0),
-etc. That is, the trailing zeroes are irrelevant. Also, integer
-list (1) is greater than (1 -1) which is greater than (1 -2)
-which is greater than (1 -3)."
+Note that a version specified by the list (1) is equal to (1 0),
+\(1 0 0), (1 0 0 0), etc. That is, the trailing zeros are insignificant.
+Also, a version given by the list (1) is higher than (1 -1), which in
+turn is higher than (1 -2), which is higher than (1 -3)."
(while (and l1 l2 (= (car l1) (car l2)))
(setq l1 (cdr l1)
l2 (cdr l2)))
@@ -3715,7 +3715,7 @@ which is greater than (1 -3)."
(defun version-list-<= (l1 l2)
- "Return t if integer list L1 is lesser than or equal to L2.
+ "Return t if L1, a list specification of a version, is lower or equal to L2.
Note that integer list (1) is equal to (1 0), (1 0 0), (1 0 0 0),
etc. That is, the trailing zeroes are irrelevant. Also, integer
@@ -3735,9 +3735,9 @@ which is greater than (1 -3)."
(t (<= 0 (version-list-not-zero l2)))))
(defun version-list-not-zero (lst)
- "Return the first non-zero element of integer list LST.
+ "Return the first non-zero element of LST, which is a list of integers.
-If all LST elements are zeroes or LST is nil, return zero."
+If all LST elements are zeros or LST is nil, return zero."
(while (and lst (zerop (car lst)))
(setq lst (cdr lst)))
(if lst
@@ -3747,31 +3747,31 @@ If all LST elements are zeroes or LST is
(defun version< (v1 v2)
- "Return t if version V1 is lesser than V2.
+ "Return t if version V1 is lower (older) than V2.
Note that version string \"1\" is equal to \"1.0\", \"1.0.0\", \"1.0.0.0\",
-etc. That is, the trailing \".0\"s are irrelevant. Also, version string \"1\"
-is greater than \"1pre\" which is greater than \"1beta\" which is greater than
-\"1alpha\"."
+etc. That is, the trailing \".0\"s are insignificant. Also, version
+string \"1\" is higher (newer) than \"1pre\", which is higher than \"1beta\",
+which is higher than \"1alpha\"."
(version-list-< (version-to-list v1) (version-to-list v2)))
(defun version<= (v1 v2)
- "Return t if version V1 is lesser than or equal to V2.
+ "Return t if version V1 is lower (older) than or equal to V2.
Note that version string \"1\" is equal to \"1.0\", \"1.0.0\", \"1.0.0.0\",
-etc. That is, the trailing \".0\"s are irrelevant. Also, version string \"1\"
-is greater than \"1pre\" which is greater than \"1beta\" which is greater than
-\"1alpha\"."
+etc. That is, the trailing \".0\"s are insignificant.. Also, version
+string \"1\" is higher (newer) than \"1pre\", which is higher than \"1beta\",
+which is higher than \"1alpha\"."
(version-list-<= (version-to-list v1) (version-to-list v2)))
(defun version= (v1 v2)
"Return t if version V1 is equal to V2.
Note that version string \"1\" is equal to \"1.0\", \"1.0.0\", \"1.0.0.0\",
-etc. That is, the trailing \".0\"s are irrelevant. Also, version string \"1\"
-is greater than \"1pre\" which is greater than \"1beta\" which is greater than
-\"1alpha\"."
+etc. That is, the trailing \".0\"s are insignificant.. Also, version
+string \"1\" is higher (newer) than \"1pre\", which is higher than \"1beta\",
+which is higher than \"1alpha\"."
(version-list-= (version-to-list v1) (version-to-list v2)))
bug archived.
Request was from
Debbugs Internal Request <help-debbugs <at> gnu.org>
to
internal_control <at> debbugs.gnu.org.
(Sun, 25 Apr 2010 11:24:03 GMT)
Full text and
rfc822 format available.
This bug report was last modified 15 years and 59 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.