* bug#6018: 23.1.96; doc of version(-list)* @ 2010-04-23 19:04 Drew Adams 2010-04-23 20:39 ` Eli Zaretskii 0 siblings, 1 reply; 12+ messages in thread From: Drew Adams @ 2010-04-23 19:04 UTC (permalink / raw) To: 6018 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' ^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#6018: 23.1.96; doc of version(-list)* 2010-04-23 19:04 bug#6018: 23.1.96; doc of version(-list)* Drew Adams @ 2010-04-23 20:39 ` Eli Zaretskii 2010-04-23 21:06 ` Drew Adams 2011-07-13 18:06 ` Lars Magne Ingebrigtsen 0 siblings, 2 replies; 12+ messages in thread From: Eli Zaretskii @ 2010-04-23 20:39 UTC (permalink / raw) To: Drew Adams; +Cc: 6018 > 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? ^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#6018: 23.1.96; doc of version(-list)* 2010-04-23 20:39 ` Eli Zaretskii @ 2010-04-23 21:06 ` Drew Adams 2011-07-13 18:06 ` Lars Magne Ingebrigtsen 1 sibling, 0 replies; 12+ messages in thread From: Drew Adams @ 2010-04-23 21:06 UTC (permalink / raw) To: 'Eli Zaretskii'; +Cc: 6018 > > 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. ^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#6018: 23.1.96; doc of version(-list)* 2010-04-23 20:39 ` Eli Zaretskii 2010-04-23 21:06 ` Drew Adams @ 2011-07-13 18:06 ` Lars Magne Ingebrigtsen 2011-07-13 18:20 ` Drew Adams 1 sibling, 1 reply; 12+ messages in thread From: Lars Magne Ingebrigtsen @ 2011-07-13 18:06 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 6018 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/ ^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#6018: 23.1.96; doc of version(-list)* 2011-07-13 18:06 ` Lars Magne Ingebrigtsen @ 2011-07-13 18:20 ` Drew Adams 2011-07-14 2:04 ` Chong Yidong 2011-07-16 18:42 ` Stefan Monnier 0 siblings, 2 replies; 12+ messages in thread From: Drew Adams @ 2011-07-13 18:20 UTC (permalink / raw) To: 'Lars Magne Ingebrigtsen', 'Eli Zaretskii'; +Cc: 6018 > 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. ^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#6018: 23.1.96; doc of version(-list)* 2011-07-13 18:20 ` Drew Adams @ 2011-07-14 2:04 ` Chong Yidong 2011-07-14 2:51 ` Drew Adams 2011-07-16 18:42 ` Stefan Monnier 1 sibling, 1 reply; 12+ messages in thread From: Chong Yidong @ 2011-07-14 2:04 UTC (permalink / raw) To: Drew Adams; +Cc: 'Lars Magne Ingebrigtsen', 6018 "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. ^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#6018: 23.1.96; doc of version(-list)* 2011-07-14 2:04 ` Chong Yidong @ 2011-07-14 2:51 ` Drew Adams 2011-07-14 6:30 ` Eli Zaretskii 0 siblings, 1 reply; 12+ messages in thread From: Drew Adams @ 2011-07-14 2:51 UTC (permalink / raw) To: 'Chong Yidong'; +Cc: 'Lars Magne Ingebrigtsen', 6018 > > 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. ^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#6018: 23.1.96; doc of version(-list)* 2011-07-14 2:51 ` Drew Adams @ 2011-07-14 6:30 ` Eli Zaretskii 2011-07-14 14:05 ` Drew Adams 0 siblings, 1 reply; 12+ messages in thread From: Eli Zaretskii @ 2011-07-14 6:30 UTC (permalink / raw) To: Drew Adams; +Cc: cyd, 6018, larsi > 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. ^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#6018: 23.1.96; doc of version(-list)* 2011-07-14 6:30 ` Eli Zaretskii @ 2011-07-14 14:05 ` Drew Adams 2011-07-14 15:58 ` Eli Zaretskii 0 siblings, 1 reply; 12+ messages in thread From: Drew Adams @ 2011-07-14 14:05 UTC (permalink / raw) To: 'Eli Zaretskii'; +Cc: cyd, 6018, larsi > > > > 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. ^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#6018: 23.1.96; doc of version(-list)* 2011-07-14 14:05 ` Drew Adams @ 2011-07-14 15:58 ` Eli Zaretskii 2012-01-07 6:15 ` Lars Magne Ingebrigtsen 0 siblings, 1 reply; 12+ messages in thread From: Eli Zaretskii @ 2011-07-14 15:58 UTC (permalink / raw) To: Drew Adams; +Cc: cyd, 6018, larsi > 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. ^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#6018: 23.1.96; doc of version(-list)* 2011-07-14 15:58 ` Eli Zaretskii @ 2012-01-07 6:15 ` Lars Magne Ingebrigtsen 0 siblings, 0 replies; 12+ messages in thread From: Lars Magne Ingebrigtsen @ 2012-01-07 6:15 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 6018 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/ ^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#6018: 23.1.96; doc of version(-list)* 2011-07-13 18:20 ` Drew Adams 2011-07-14 2:04 ` Chong Yidong @ 2011-07-16 18:42 ` Stefan Monnier 1 sibling, 0 replies; 12+ messages in thread From: Stefan Monnier @ 2011-07-16 18:42 UTC (permalink / raw) To: Drew Adams; +Cc: 'Lars Magne Ingebrigtsen', 6018 > 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 ^ permalink raw reply [flat|nested] 12+ messages in thread
end of thread, other threads:[~2012-01-07 6:15 UTC | newest] Thread overview: 12+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2010-04-23 19:04 bug#6018: 23.1.96; doc of version(-list)* Drew Adams 2010-04-23 20:39 ` Eli Zaretskii 2010-04-23 21:06 ` Drew Adams 2011-07-13 18:06 ` Lars Magne Ingebrigtsen 2011-07-13 18:20 ` Drew Adams 2011-07-14 2:04 ` Chong Yidong 2011-07-14 2:51 ` Drew Adams 2011-07-14 6:30 ` Eli Zaretskii 2011-07-14 14:05 ` Drew Adams 2011-07-14 15:58 ` Eli Zaretskii 2012-01-07 6:15 ` Lars Magne Ingebrigtsen 2011-07-16 18:42 ` Stefan Monnier
Code repositories for project(s) associated with this external index https://git.savannah.gnu.org/cgit/emacs.git https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.