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

["Drew Adams" <drew.adams@oracle.com>]

> > > > 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".
> 
> That doc string no longer refers to anything but version-to-list.

I was going by the description of the bug fix in this thread, which didn't
mention that.

> And version-regexp-alist is itself an internal variable, so this is
> not an evidence to the effect you want it to be.  The doc string of
> version-regexp-alist is for developers of this group of functions, not
> for users of their advertised APIs.

Really?  What about these parts of the doc string of `version-to-list':

1. "SEPARATOR ::= `version-separator' (which see)
	       `version-regexp-alist' (which see)."

2. "The NUMBER part is optional if SEPARATOR is a match for an element
in `version-regexp-alist'."

3. "See documentation for `version-separator' and `version-regexp-alist'."

What, anywhere, indicates that `version-regexp-alist' is "internal"?  All
indications point to the contrary.

Or are you now claiming that `version-to-list' is also internal, like you
claimed for `version-list*'?  It was you who placed an internal/external line in
the sand here, pointing out that `v-r-alist' now refers only to `v-to-list' and
no longer to `v-list*' (because "internal").

> > 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.
> 
> You mean, it isn't obviously clear that 3 is greater than 2 and less
> than 4?  It needs to be documented in a doc string?

A digit is not a string of digits.  And as you know full well (or should know),
there are various ways to order strings of digits.

One need look no further than the "interesting" way MS Windows (e.g. Windows
Explorer) sorts file names that contain digits: "google windows explorer file
name sort order".  Don't you think we should specify how strings containing
digits are ordered?  It's not about 3 > 2.

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

Yes, please see above.

How are strings containing digits compared?  What about case sensitivity?  Does
`case-fold-search' affect that or not?  Especially if the comparison is simple
(e.g. orthographic/alphabetical order), it is simple to state what it is.

For the rest - if you have removed all mention of everything you designate as
"internal" from the doc of what you designate as not internal, then that part of
the bug could be considered fixed.  Fixed by sleight of hand, perhaps, but
fixed.

If there remain non-internal things whose doc is incompletely specified (see
above), then that doc would remain to be fixed.