From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: owner@emacsbugs.donarmstrong.com (Emacs bug Tracking System) Newsgroups: gmane.emacs.bugs Subject: bug#4638: marked as done (23.1; doc string and Elisp manual descriptions of file-attributes) Date: Mon, 05 Oct 2009 08:55:07 +0000 Message-ID: References: <83ocomns6w.fsf@gnu.org> <1ECFBF8A2C4348C3B763D29276A04BC5@us.oracle.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="----------=_1254732907-17415-0" X-Trace: ger.gmane.org 1254733740 8499 80.91.229.12 (5 Oct 2009 09:09:00 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 5 Oct 2009 09:09:00 +0000 (UTC) To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Oct 05 11:08:56 2009 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.50) id 1MujYp-0005KK-8G for geb-bug-gnu-emacs@m.gmane.org; Mon, 05 Oct 2009 11:08:52 +0200 Original-Received: from localhost ([127.0.0.1]:47103 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MujYo-0007Zu-Ut for geb-bug-gnu-emacs@m.gmane.org; Mon, 05 Oct 2009 05:08:51 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1MujXO-00079P-1V for bug-gnu-emacs@gnu.org; Mon, 05 Oct 2009 05:07:22 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1MujXI-00077S-4v for bug-gnu-emacs@gnu.org; Mon, 05 Oct 2009 05:07:20 -0400 Original-Received: from [199.232.76.173] (port=53232 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MujXH-00077J-TH for bug-gnu-emacs@gnu.org; Mon, 05 Oct 2009 05:07:15 -0400 Original-Received: from rzlab.ucr.edu ([138.23.92.77]:52265) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1MujXC-0004Bj-OL; Mon, 05 Oct 2009 05:07:11 -0400 Original-Received: from rzlab.ucr.edu (rzlab.ucr.edu [127.0.0.1]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n95978bg020442; Mon, 5 Oct 2009 02:07:08 -0700 Original-Received: (from debbugs@localhost) by rzlab.ucr.edu (8.14.3/8.14.3/Submit) id n958t7ih017530; Mon, 5 Oct 2009 01:55:07 -0700 X-Mailer: MIME-tools 5.427 (Entity 5.427) X-Loop: owner@emacsbugs.donarmstrong.com X-Emacs-PR-Message: closed 4638 X-Emacs-PR-Package: emacs X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6 (newer, 2) X-BeenThere: bug-gnu-emacs@gnu.org X-Mailman-Version: 2.1.5 Precedence: list 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:31695 Archived-At: This is a multi-part message in MIME format... ------------=_1254732907-17415-0 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=utf-8 Your message dated Mon, 05 Oct 2009 10:47:03 +0200 with message-id <83ocomns6w.fsf@gnu.org> and subject line Re: bug#4638: 23.1; doc string and Elisp manual descriptio= ns of file-attributes has caused the Emacs bug report #4638, regarding 23.1; doc string and Elisp manual descriptions of file-attributes to be marked as done. This means that you claim that the problem has been dealt with. If this is not the case it is now your responsibility to reopen the bug report if necessary, and/or fix the problem forthwith. (NB: If you are a system administrator and have no idea what this message is talking about, this may indicate a serious mail system misconfiguration somewhere. Please contact owner@emacsbugs.donarmstrong.com immediately.) --=20 4638: http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=3D4638 Emacs Bug Tracking System Contact owner@emacsbugs.donarmstrong.com with problems ------------=_1254732907-17415-0 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at submit) by emacsbugs.donarmstrong.com; 5 Oct 2009 00:58:44 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-2.4 required=4.0 tests=AWL,FOURLA autolearn=no version=3.2.5-bugs.debian.org_2005_01_02 Received: from lists.gnu.org (lists.gnu.org [199.232.76.165]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n950whOs000542 for ; Sun, 4 Oct 2009 17:58:44 -0700 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1MubuV-0001T5-1o for bug-gnu-emacs@gnu.org; Sun, 04 Oct 2009 20:58:43 -0400 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1MubuP-0001St-IH for bug-gnu-emacs@gnu.org; Sun, 04 Oct 2009 20:58:41 -0400 Received: from [199.232.76.173] (port=52759 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MubuP-0001Sq-E6 for bug-gnu-emacs@gnu.org; Sun, 04 Oct 2009 20:58:37 -0400 Received: from rcsinet11.oracle.com ([148.87.113.123]:40383 helo=rgminet11.oracle.com) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1MubuO-00089p-RD for bug-gnu-emacs@gnu.org; Sun, 04 Oct 2009 20:58:37 -0400 Received: from acsinet15.oracle.com (acsinet15.oracle.com [141.146.126.227]) by rgminet11.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n950xdpD015769 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Mon, 5 Oct 2009 00:59:40 GMT Received: from acsmt356.oracle.com (acsmt356.oracle.com [141.146.40.156]) by acsinet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n94NXKmu013142 for ; Mon, 5 Oct 2009 00:59:18 GMT Received: from abhmt021.oracle.com by acsmt355.oracle.com with ESMTP id 20193103071254704284; Sun, 04 Oct 2009 17:58:04 -0700 Received: from dradamslap1 (/24.5.184.158) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sun, 04 Oct 2009 17:58:04 -0700 From: "Drew Adams" To: Subject: 23.1; doc string and Elisp manual descriptions of file-attributes Date: Sun, 4 Oct 2009 17:58:15 -0700 Message-ID: <1ECFBF8A2C4348C3B763D29276A04BC5@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 Thread-Index: AcpFVuu8NRWvDEVKT32s8PpsR5RcFA== X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5579 X-Source-IP: acsmt356.oracle.com [141.146.40.156] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090201.4AC944B7.00E9:SCFMA4539814,ss=1,fgs=0 X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6 (newer, 1) >From the doc string: 1. Number of links to file. Please state that it is an integer value. 2. File uid as a string or a number. If a string value cannot be looked up, a numeric value, either an integer or a float, is returned. Can we say how long the string is (fixed length or max)? 10. inode number. If inode number is larger than the Emacs integer... Should presumably say "than the _largest_ Emacs integer". Also, #10 contradicts what is said in the Elisp manual, node `File Attributes'. Which is correct? The doc string speaks of a cons cell containing possibly 3 integers. (And how can a single cons cell contain 3 integers? Not clear.) The manual speaks of a (single) cons cell with car and cdr integers. 11. Device number. If it is larger than the Emacs integer, this is a cons cell, similar to the inode number. Again, it should presumably say _largest_ Emacs integer. Also, it's not clear what "device number" means, and the Elisp manual describes this differently, as "the file system number of the file system that the file is in". Neither description is understandable, but they especially do not seem to correspond, at least not in a self-evident way. These desciptions need to be improved, at the very least by referring to the original terminology (UNIX) or reference. The following note is referenced only from #4, but #5 and #6 say "likewise". The note speaks of "access time". It is not clear whether the note applies only to #4 (access time) or also to #5 and #6. If it applies only to #4, then it should just be moved to #4. Otherwise, things should be rephrased to make clear what is meant (not necessarily access time). On some FAT-based filesystems, only the date of last access is recorded, so last access time will always be midnight of that day. It is important to get these descriptions right. How can we expect someone to write code that depends on these values, if s?he cannot even know what forms they can take? In GNU Emacs 23.1.1 (i386-mingw-nt5.1.2600) of 2009-07-29 on SOFT-MJASON Windowing system distributor `Microsoft Corp.', version 5.1.2600 configured using `configure --with-gcc (4.4)' ------------=_1254732907-17415-0 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at 4638-done) by emacsbugs.donarmstrong.com; 5 Oct 2009 08:49:14 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-4.7 required=4.0 tests=AWL,FOURLA,HAS_BUG_NUMBER autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from mtaout3.012.net.il (mtaout4.012.net.il [84.95.2.10]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n958nC0w016476 for <4638-done@emacsbugs.donarmstrong.com>; Mon, 5 Oct 2009 01:49:13 -0700 Received: from conversion-daemon.i_mtaout3.012.net.il by i_mtaout3.012.net.il (HyperSendmail v2004.12) id <0KR1005009O4QB00@i_mtaout3.012.net.il> for 4638-done@emacsbugs.donarmstrong.com; Mon, 05 Oct 2009 10:49:05 +0200 (IST) Received: from HOME-C4E4A596F7 ([84.229.44.55]) by i_mtaout3.012.net.il (HyperSendmail v2004.12) with ESMTPA id <0KR1004YY9TT4E00@i_mtaout3.012.net.il>; Mon, 05 Oct 2009 10:49:05 +0200 (IST) Date: Mon, 05 Oct 2009 10:47:03 +0200 From: Eli Zaretskii Subject: Re: bug#4638: 23.1; doc string and Elisp manual descriptions of file-attributes In-reply-to: <1ECFBF8A2C4348C3B763D29276A04BC5@us.oracle.com> X-012-Sender: halo1@inter.net.il To: Drew Adams , 4638-done@emacsbugs.donarmstrong.com Reply-to: Eli Zaretskii Message-id: <83ocomns6w.fsf@gnu.org> References: <1ECFBF8A2C4348C3B763D29276A04BC5@us.oracle.com> > From: "Drew Adams" > Date: Sun, 4 Oct 2009 17:58:15 -0700 > Cc: > > From the doc string: > > 1. Number of links to file. > > Please state that it is an integer value. I don't think this is important. A "number" means what `numberp' will return non-nil for. Stating that it's an integer is a maintenance burden, because, like other attributes in this function, it may evolve from an integer to a float. (Other attributes in the doc say specifically that they can be floats because in the past the doc string stated they are integers.) > 2. File uid as a string or a number. If a string value cannot be > looked up, a numeric value, either an integer or a float, is > returned. > > Can we say how long the string is (fixed length or max)? There's no limit, as far as Emacs is concerned (except that every string is inherently limited by the size of an Emacs integer), so no, we can't state any useful limitation. > 10. inode number. If inode number is larger than the Emacs integer... > > Should presumably say "than the _largest_ Emacs integer". Changed this to say "is larger than what Emacs integer can hold". > Also, #10 contradicts what is said in the Elisp manual, node `File > Attributes'. Which is correct? The doc string speaks of a cons cell > containing possibly 3 integers. The manual speaks of a (single) cons > cell with car and cdr integers. The manual is wrong, I fixed it. > (And how can a single cons cell contain 3 integers? Not clear.) "M-: (cons 'a (cons 'b 'c)) RET" Anyway, I changed the text not to use ``cons cell'' in this case. > 11. Device number. If it is larger than the Emacs integer, this is > a cons cell, similar to the inode number. > > Again, it should presumably say _largest_ Emacs integer. > > Also, it's not clear what "device number" means, and the Elisp manual > describes this differently, as "the file system number of the file > system that the file is in". Neither description is understandable, > but they especially do not seem to correspond, at least not in a > self-evident way. These desciptions need to be improved, at the very > least by referring to the original terminology (UNIX) or reference. The doc string now says 11. Filesystem device number. If it is larger than what the Emacs integer can hold, this is a cons cell, similar to the inode number. A more detailed description already existed in the manual. I don't think the Unix terminology will help here, btw, because we want this documentation to be as system independent as possible, and the Unix meaning is wrong on Windows. The important part is this: On most filesystems, the combination of the inode and the device number uniquely identifies the file. which I added to the doc string (it was already in the manual, albeit in slightly different wording). > The following note is referenced only from #4, but #5 and #6 say > "likewise". The note speaks of "access time". It is not clear whether > the note applies only to #4 (access time) or also to #5 and #6. If it > applies only to #4, then it should just be moved to #4. Otherwise, > things should be rephrased to make clear what is meant (not > necessarily access time). > > On some FAT-based filesystems, only the date of last > access is recorded, so last access time will always be > midnight of that day. It applies only to the last access time. The note now says (See a note below about access time on FAT-based filesystems.) I don't think it's a good idea to have the note right at #4 because this is an obscure misfeature of an old DOS/Windows filesystem, so it should be near the end of the doc string. > What does "status change" mean? Does it mean change of mode (rwx), > owner, group,...? I hope this new text is more clear: 5. Last modification time, likewise. This is the time of the last change to the file's contents. 6. Last status change time, likewise. This is the time of last change to the file's attributes: owner and group, access mode bits, etc. > How can we expect someone to write code that depends on these > values, if s?he cannot even know what forms they can take? I don't think the situation was quite that bad, and I hope it is better now. ------------=_1254732907-17415-0--