[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#6018: 23.1.96; doc of version(-list)*
From: |
Drew Adams |
Subject: |
bug#6018: 23.1.96; doc of version(-list)* |
Date: |
Wed, 13 Jul 2011 19:51:15 -0700 |
> > 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.
bug#6018: 23.1.96; doc of version(-list)*, Stefan Monnier, 2011/07/16