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