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: Fri, 23 Apr 2010 14:06:39 -0700 Message-ID: <0A1266CAFFCB4B17869EA0174A34F9AF@us.oracle.com> References: <831ve53nv5.fsf@gnu.org> 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 1272057937 27985 80.91.229.12 (23 Apr 2010 21:25:37 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Fri, 23 Apr 2010 21:25:37 +0000 (UTC) Cc: 6018@debbugs.gnu.org To: "'Eli Zaretskii'" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Apr 23 23:25:36 2010 connect(): No such file or directory Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1O5QNT-00029g-DB for geb-bug-gnu-emacs@m.gmane.org; Fri, 23 Apr 2010 23:25:35 +0200 Original-Received: from localhost ([127.0.0.1]:44909 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1O5QNS-0006We-MC for geb-bug-gnu-emacs@m.gmane.org; Fri, 23 Apr 2010 17:25:34 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1O5QNN-0006Ve-Vh for bug-gnu-emacs@gnu.org; Fri, 23 Apr 2010 17:25:30 -0400 Original-Received: from [140.186.70.92] (port=57086 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1O5QNM-0006Ux-Kb for bug-gnu-emacs@gnu.org; Fri, 23 Apr 2010 17:25:29 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1O5QNL-0006mR-6E for bug-gnu-emacs@gnu.org; Fri, 23 Apr 2010 17:25:28 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:52480) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1O5QNL-0006mN-4c for bug-gnu-emacs@gnu.org; Fri, 23 Apr 2010 17:25:27 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1O5Q6T-0007iM-P5; Fri, 23 Apr 2010 17:08:01 -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: Fri, 23 Apr 2010 21:08:01 +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: Original-Received: via spool by 6018-submit@debbugs.gnu.org id=B6018.127205687829648 (code B ref 6018); Fri, 23 Apr 2010 21:08:01 +0000 Original-Received: (at 6018) by debbugs.gnu.org; 23 Apr 2010 21:07:58 +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 1O5Q6Q-0007i9-35 for submit@debbugs.gnu.org; Fri, 23 Apr 2010 17:07:58 -0400 Original-Received: from rcsinet10.oracle.com ([148.87.113.121]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1O5Q6N-0007i3-Mh for 6018@debbugs.gnu.org; Fri, 23 Apr 2010 17:07:56 -0400 Original-Received: from rcsinet15.oracle.com (rcsinet15.oracle.com [148.87.113.117]) by rcsinet10.oracle.com (Switch-3.4.2/Switch-3.4.1) with ESMTP id o3NL7mKW001078 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Fri, 23 Apr 2010 21:07:50 GMT Original-Received: from acsmt355.oracle.com (acsmt355.oracle.com [141.146.40.155]) by rcsinet15.oracle.com (Switch-3.4.2/Switch-3.4.1) with ESMTP id o3NL7l2c001702; Fri, 23 Apr 2010 21:07:47 GMT Original-Received: from abhmt008.oracle.com by acsmt353.oracle.com with ESMTP id 185413851272056794; Fri, 23 Apr 2010 14:06:34 -0700 Original-Received: from dradamslap1 (/10.175.223.120) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Fri, 23 Apr 2010 14:06:34 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <831ve53nv5.fsf@gnu.org> Thread-Index: AcrjJUvj53AcWNneSpibC3wZAp/uzAAADhzA X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5579 X-Auth-Type: Internal IP X-Source-IP: rcsinet15.oracle.com [148.87.113.117] X-CT-RefId: str=0001.0A090207.4BD20C26.00D4:SCFMA4539811,ss=1,fgs=0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Fri, 23 Apr 2010 17:08:01 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) 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: , Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:36460 Archived-At: > > 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.