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

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

[Drew Adams]

The new version<, version-list* etc. functions are not sufficiently
documented.
 
There is no explanation (spec) of the elements in the *-list functions.
Examples are given, but no real explanation.  If the elements must be
integers, say so.  And say what a negative integer means.
 
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.
 
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.
 

In GNU Emacs 23.1.96.1 (i386-mingw-nt5.1.2600)
 of 2010-04-20 on G41R2F1
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --no-opt --cflags -Ic:/xpm/include'
 

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Fri, 23 Apr 2010 12:04:59 -0700
> Cc: 
> 
> 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.

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.

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

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. 

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

[Lars Magne Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

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

The doc strings to these functions look fine to me, so I'm closing this
report.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

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

[Drew Adams]

> The doc strings to these functions look fine to me, so I'm 
> closing this report.

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.

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

[Chong Yidong]

"Drew Adams" <drew.adams@oracle.com> writes:

>> The doc strings to these functions look fine to me, so I'm closing
>> this report.
>
> 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?  I looked again at the docstrings of version-to-list and
version-regexp-alist, and it seems pretty clear to me.  Even if an Emacs
Lisp programmer is ignorant of what an EBNF is, it's pretty obvious from
the context what the docstring is talking about.

You have to be more specific about what's confusing you.

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.

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: "'Lars Magne Ingebrigtsen'" <larsi@gnus.org>,
>         "'Eli Zaretskii'" <eliz@gnu.org>, <6018@debbugs.gnu.org>
> Date: Wed, 13 Jul 2011 19:51:15 -0700
> 
> > 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.

You were bikeshedding, as usual.

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

That doc string no longer refers to anything but version-to-list.

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.

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

Please explain where is the current doc string insufficient.  What you
did was express general consideration, not specific confusion points.
Please make a point of giving specific practical use cases where a doc
string leaves you in the dark regarding the outcome of a specific test
that uses the advertised API for Lisp programs.

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

See above: unless you show a specific use case where this mapping
needs to be documented in the doc string, your arguments are nil and
void.

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

See above: why do you need that documented?  I submit you don't.

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

Nothing of interest to you (unless you read the code, in which case it
should be obvious).  This is an implementation detail.

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

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?

> > 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: give us a use case.  At least one.

> > Give users a clear understanding of just what the numeric 
> > ordering is that we use.
> 
> Enough details for you?

No, see above.  You wrote a lot, but all of it is irrelevant.

All the _real_ issues with these doc strings were taken care of, back
when you submitted this bug report.  All that's left is bikeshedding.

> That describes some of the interface/API info about these functions
> that is missing

You didn't show a single issue with the _advertised_ API that
indicates that some info is missing.

> and it includes some of the questions a user of these functions will
> have.

A user called Drew, perhaps.  Because he insists on having internal
functions and implementation details be documented as if they were
advertised APIs.

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

[Drew Adams]

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

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <cyd@stupidchicken.com>, <larsi@gnus.org>, <6018@debbugs.gnu.org>
> Date: Thu, 14 Jul 2011 07:05:57 -0700
> 
> > 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':

Irrelevant, see below.

> Or are you now claiming that `version-to-list' is also internal, like you
> claimed for `version-list*'?

Of course!

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

But the default (and TRT) order is well known, especially in the
context of version numbers.  They are called "numbers" for a reason.

> How are strings containing digits compared?

As one expects.  We don't document where Sun rises this morning,
either.

> What about case sensitivity?

Ditto.

> Does `case-fold-search' affect that or not?

Ditto.

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

[Lars Magne Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> How are strings containing digits compared?
>
> As one expects.  We don't document where Sun rises this morning,
> either.
>
>> What about case sensitivity?
>
> Ditto.
>
>> Does `case-fold-search' affect that or not?
>
> Ditto.

So I'm closing this report again.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

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

[Stefan Monnier]

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

"internal" means you shouldn't call them or rely on their existence.
It doesn't mean "we want to hide them as much as possible".

But just like the code of version-<foo> can call those internal
functions, their docstrings can refer to those internal functions's
docstrings (as long as those references are kept uptodate when the
internal functions change, of course).


        Stefan