From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: emacs-26 99f92da: Improve documentation of 'directory-files-and-attributes' Date: Fri, 01 Jun 2018 16:09:22 +0300 Message-ID: <83h8mmfybh.fsf@gnu.org> References: <20180601082809.7179.74843@vcs0.savannah.gnu.org> <20180601082810.7BF3721297@vcs0.savannah.gnu.org> Reply-To: Eli Zaretskii NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1527858492 17399 195.159.176.226 (1 Jun 2018 13:08:12 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Fri, 1 Jun 2018 13:08:12 +0000 (UTC) Cc: emacs-devel@gnu.org To: Lars Ingebrigtsen Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Jun 01 15:08:08 2018 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fOjmp-0004Ri-QN for ged-emacs-devel@m.gmane.org; Fri, 01 Jun 2018 15:08:07 +0200 Original-Received: from localhost ([::1]:55680 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fOjow-0004D8-ST for ged-emacs-devel@m.gmane.org; Fri, 01 Jun 2018 09:10:18 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:49631) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fOjo7-0004CC-57 for emacs-devel@gnu.org; Fri, 01 Jun 2018 09:09:31 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fOjo2-0000vZ-Sr for emacs-devel@gnu.org; Fri, 01 Jun 2018 09:09:27 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:53351) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fOjo2-0000vT-QV; Fri, 01 Jun 2018 09:09:22 -0400 Original-Received: from [176.228.60.248] (port=4449 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1fOjo2-00034Q-6C; Fri, 01 Jun 2018 09:09:22 -0400 In-reply-to: (message from Lars Ingebrigtsen on Fri, 01 Jun 2018 12:21:49 +0200) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:225891 Archived-At: > From: Lars Ingebrigtsen > Cc: Eli Zaretskii > Date: Fri, 01 Jun 2018 12:21:49 +0200 > > eliz@gnu.org (Eli Zaretskii) writes: > > > +Value is a list of the form: > > + > > + ((FILE1 FILE1-ATTRS) (FILE2 FILE2-ATTRS) ...) > > + > > +where each FILEn-ATTRS is the attributes of FILEn as returned > > +by `file-attributes'. > > Heh, I read the same reddit post, apparently, and fixed it like this on > master: Please always fix documentation issues on the release branch, not on master. Unless they document features that are only available on master, of course. > +The list returned has elements that contain the data from > +`file-attributes' for each file -- with the file name prepended. So > +the structure of each element is > +`(FILE-NAME FILE-ATTRIBUTE1 FILE-ATTRIBUTE2 ...)'. I find "has elements that contain the data from `file-attributes' for each file -- with the file name prepended" less clear than what I wrote. YMMV, of course, and I'll let others tell which text they prefer. > +For instance, to get the size of the fourth element in a directory, > +you could say: > + > + (file-attribute-size (cdr (nth 3 (directory-files-and-attributes "/")))) That's redundant, I think; we never provide such "hints" anywhere else where we describe lists being returned. > Because (FILE1 FILE1-ATTRS) is a bit ambiguous, since it could mean > > ("file-name" (t 27 0 0 (23311 56666 366991 953000) (23220 586 761023 102000) (23220 586 761023 102000) 4096 "drwxr-xr-x" t 2 66306)) No, it cannot mean that, because the text says where each FILEn-ATTRS is the attributes of FILEn as returned by `file-attributes' It doesn't say it's a list. If we think that's not clear enough we can use this instead: ((FILE1 FILE1-ATTRS...) (FILE2 FILE2-ATTRS...) ...)