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

[Drew Adams]

> > AFAICT, none of the questions raised here have been 
> > answered, and the original bug is still there.
> >
> >
> > The doc string of `version-regexp-alist' refers to the
> > `version-list-*' functions, saying to consult their doc, so they
> > cannot be said be "internal".
> >
> > And the doc string of `version-to-list' refers to that of
> > `version-regexp-alist'.
> >
> > Nothing has been specified (no mapping), to help an Emacs-Lisp
> > programmer use these various functions.
> 
> Really? 
> You have to be more specific about what's confusing you.

I was pretty darn specific about the non-specificity of this doc and what is
missing.

As I said:

> > The doc string of `version-regexp-alist' refers to the
> > `version-list-*' functions, saying to consult their doc, so they
> > cannot be said to be "internal".

And as I said about those referenced `version-list-*' functions:

> Examples are given, but no real explanation.  If the elements must be
> integers, say so.  And say what a negative integer means.

And as I said about `version-regexp-alist' and `version-to-list':

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

And:

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

> It is sufficient to describe this thoroughly in one doc string, if you
> then link to that doc string from the other doc strings.  So far,
> however, the info necessary to understand this feature is lacking,
> especially regarding the use and meaning of negative integers.

And as I said about the `version* (non-list) functions:

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

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

Enough details for you?  That describes some of the interface/API info about
these functions that is missing, and it includes some of the questions a user of
these functions will have.