bug#5744: 23.1.92; doc string of `version<' etc.

bug#5744: 23.1.92; doc string of `version<' etc.

[Drew Adams]

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

bug#5744: 23.1.92; doc string of `version<' etc.

[Štěpán Němec]

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

bug#5744: 23.1.92; doc string of `version<' etc.

[Drew Adams]

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

bug#5744: 23.1.92; doc string of `version<' etc.

[Štěpán Němec]

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

bug#5744: 23.1.92; doc string of `version<' etc.

[Drew Adams]

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

bug#5744: 23.1.92; doc string of `version<' etc.

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Sat, 20 Mar 2010 11:10:10 -0700
> Cc: 5744@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.

bug#5744: 23.1.92; doc string of `version<' etc.

[Drew Adams]

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

bug#5744: 23.1.92; doc string of `version<' etc.

[Jason Rumney]

Eli Zaretskii <eliz@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).

bug#5744: 23.1.92; doc string of `version<' etc.

[Eli Zaretskii]

> From: Jason Rumney <jasonr@gnu.org>
> Cc: Drew Adams <drew.adams@oracle.com>,  stepnem@gmail.com,  5744@debbugs.gnu.org
> Date: Sun, 21 Mar 2010 09:12:11 +0800
> 
> Eli Zaretskii <eliz@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.

bug#5744: 23.1.92; doc string of `version<' etc.

[Drew Adams]

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

bug#5744: 23.1.92; doc string of `version<' etc.

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <stepnem@gmail.com>, <5744@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.

bug#5744: 23.1.92; doc string of `version<' etc.

[Drew Adams]

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

bug#5744: 23.1.92; doc string of `version<' etc.

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <stepnem@gmail.com>, <5744@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@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@math.s.chiba-u.ac.jp>
             Nick Roberts  <nickrob@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)))