bug#6018: 23.1.96; doc of version(-list)*

[Drew Adams]

> > There is no explanation (spec) of the elements in the 
> > *-list functions.
> 
> They are internal functions.  Perhaps we should say that explicitly in
> the doc strings.

I don't see why they should be internal functions.

> The doc strings that should be reviewed are those for version<,
> version=, and version<=.  They are the ``entry points'' to this group
> of functions.  The rest are internal subroutines.

1. Why? Why wouldn't they be useful to users?

2. Wrt the version* (non-list) functions, great energy is spent describing the
treatment of trailing zeros and alpha strings, but nothing is said about the
comparison of strings with digits other than zero. And that's arguably the most
important and most up for grabs.

And again, even for zeros and alpha strings, the "explanation" is only via
examples. At least say something about what kind of string comparison is done:
alphabetic for non-digits, describe the comparison of digit strings, mention
case-insensitivity etc.

Think about the different ways that file names that contain digits are sometimes
sorted. Think about how that has often confused the hell out of users
(especially Windows's notorious order).

Give users a clear understanding of just what the numeric ordering is that we
use.

> > There is a little more info in the doc strings of 
> > `version-regexp-alist' and `version-to-list', but again,
> > there are only examples, no explanation.  Please describe
> > the _mapping_ between parts of version strings (e.g. the
> > sub regexps "pre", "beta", "alpha" etc.) and negative
> > integers as list elements.
> 
> What description is needed, given that you can see the value?

A few examples do not define a mapping. At most, they define it partially.

What does a negative integer mean? Which regexps are mapped to negative
integers? Which of them correspond to which negative integers? etc. (It's not
obvious that "pre" would follow "beta", for instance.) 

What do the various alpha regexp patterns ("pre" etc.) mean? There are only 3
predefined alpha regexp patterns. Please say what they mean.

Also, we don't say what the "priority" means for version-regexp-alist. What does
it mean for a particular alist entry to have a "priority" of -3?

A spec, IOW.