From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs Subject: bug#6018: 23.1.96; doc of version(-list)* Date: Wed, 13 Jul 2011 19:51:15 -0700 Message-ID: References: <831ve53nv5.fsf@gnu.org> <73AC74BD8215444E997358F72C146FC8@us.oracle.com> <87r55tpqh4.fsf@stupidchicken.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: dough.gmane.org 1310611948 10112 80.91.229.12 (14 Jul 2011 02:52:28 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Thu, 14 Jul 2011 02:52:28 +0000 (UTC) Cc: 'Lars Magne Ingebrigtsen' , 6018@debbugs.gnu.org To: "'Chong Yidong'" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Jul 14 04:52:21 2011 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1QhC2G-0003ZG-Si for geb-bug-gnu-emacs@m.gmane.org; Thu, 14 Jul 2011 04:52:21 +0200 Original-Received: from localhost ([::1]:53169 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QhC2F-0007fA-Mk for geb-bug-gnu-emacs@m.gmane.org; Wed, 13 Jul 2011 22:52:19 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:55924) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QhC20-0007ev-Pc for bug-gnu-emacs@gnu.org; Wed, 13 Jul 2011 22:52:05 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QhC1z-00045D-La for bug-gnu-emacs@gnu.org; Wed, 13 Jul 2011 22:52:04 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:47174) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QhC1z-000457-ID for bug-gnu-emacs@gnu.org; Wed, 13 Jul 2011 22:52:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1QhC1y-00005x-Is; Wed, 13 Jul 2011 22:52:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 14 Jul 2011 02:52:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 6018 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: wontfix Original-Received: via spool by 6018-submit@debbugs.gnu.org id=B6018.1310611899319 (code B ref 6018); Thu, 14 Jul 2011 02:52:02 +0000 Original-Received: (at 6018) by debbugs.gnu.org; 14 Jul 2011 02:51:39 +0000 Original-Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QhC1a-000055-Sj for submit@debbugs.gnu.org; Wed, 13 Jul 2011 22:51:39 -0400 Original-Received: from rcsinet15.oracle.com ([148.87.113.117]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QhC1Y-0008WQ-Rq for 6018@debbugs.gnu.org; Wed, 13 Jul 2011 22:51:37 -0400 Original-Received: from rtcsinet21.oracle.com (rtcsinet21.oracle.com [66.248.204.29]) by rcsinet15.oracle.com (Switch-3.4.4/Switch-3.4.4) with ESMTP id p6E2pS0F018164 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Thu, 14 Jul 2011 02:51:30 GMT Original-Received: from acsmt357.oracle.com (acsmt357.oracle.com [141.146.40.157]) by rtcsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id p6E2pQW2004474 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Thu, 14 Jul 2011 02:51:27 GMT Original-Received: from abhmt101.oracle.com (abhmt101.oracle.com [141.146.116.53]) by acsmt357.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id p6E2pLhD009571; Wed, 13 Jul 2011 21:51:21 -0500 Original-Received: from dradamslap1 (/10.159.37.192) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Wed, 13 Jul 2011 19:51:17 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <87r55tpqh4.fsf@stupidchicken.com> Thread-Index: AcxBynF79p7+ZTDnQRGml8IbReUJdgABIAwg X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6109 X-Source-IP: rtcsinet21.oracle.com [66.248.204.29] X-CT-RefId: str=0001.0A090202.4E1E59B2.00D1:SCFSTAT5015188, ss=1, re=-4.000, fgs=0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Wed, 13 Jul 2011 22:52:02 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:48975 Archived-At: > > 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.