* Re: emacs-26 99f92da: Improve documentation of 'directory-files-and-attributes' [not found] ` <20180601082810.7BF3721297@vcs0.savannah.gnu.org> @ 2018-06-01 10:21 ` Lars Ingebrigtsen 2018-06-01 12:10 ` Stefan Monnier 2018-06-01 13:09 ` Eli Zaretskii 0 siblings, 2 replies; 4+ messages in thread From: Lars Ingebrigtsen @ 2018-06-01 10:21 UTC (permalink / raw) To: emacs-devel; +Cc: Eli Zaretskii 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: +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 ...)'. + +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 "/")))) + 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)) instead of ("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) -- (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no ^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: emacs-26 99f92da: Improve documentation of 'directory-files-and-attributes' 2018-06-01 10:21 ` emacs-26 99f92da: Improve documentation of 'directory-files-and-attributes' Lars Ingebrigtsen @ 2018-06-01 12:10 ` Stefan Monnier 2018-06-01 13:09 ` Eli Zaretskii 1 sibling, 0 replies; 4+ messages in thread From: Stefan Monnier @ 2018-06-01 12:10 UTC (permalink / raw) To: emacs-devel > 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)) AFAIC, it's not ambiguous and the above is exactly what it means. You can fix it with (FILE1 . FILE1-ATTRS) or (FILE1 FILE1-ATTRS...) Stefan ^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: emacs-26 99f92da: Improve documentation of 'directory-files-and-attributes' 2018-06-01 10:21 ` emacs-26 99f92da: Improve documentation of 'directory-files-and-attributes' Lars Ingebrigtsen 2018-06-01 12:10 ` Stefan Monnier @ 2018-06-01 13:09 ` Eli Zaretskii 2018-06-01 13:20 ` Lars Ingebrigtsen 1 sibling, 1 reply; 4+ messages in thread From: Eli Zaretskii @ 2018-06-01 13:09 UTC (permalink / raw) To: Lars Ingebrigtsen; +Cc: emacs-devel > From: Lars Ingebrigtsen <larsi@gnus.org> > Cc: Eli Zaretskii <eliz@gnu.org> > 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...) ...) ^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: emacs-26 99f92da: Improve documentation of 'directory-files-and-attributes' 2018-06-01 13:09 ` Eli Zaretskii @ 2018-06-01 13:20 ` Lars Ingebrigtsen 0 siblings, 0 replies; 4+ messages in thread From: Lars Ingebrigtsen @ 2018-06-01 13:20 UTC (permalink / raw) To: Eli Zaretskii; +Cc: emacs-devel Eli Zaretskii <eliz@gnu.org> writes: >> +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. I think the Emacs doc strings could do with more code examples in general... >> 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...) ...) As long as it's clear to the user that they have to say `cdr' to get to the attributes instead of `cadr', that's fine (and is pretty much what I did in my version). I mean, this is a very simple function, but describing what the user has to do to get to the values is surprisingly difficult due to the non-opacity of the data structures here. And sorry for not doing the doc fix on the emacs-26 branch instead of master; I should know better. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no ^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2018-06-01 13:20 UTC | newest] Thread overview: 4+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- [not found] <20180601082809.7179.74843@vcs0.savannah.gnu.org> [not found] ` <20180601082810.7BF3721297@vcs0.savannah.gnu.org> 2018-06-01 10:21 ` emacs-26 99f92da: Improve documentation of 'directory-files-and-attributes' Lars Ingebrigtsen 2018-06-01 12:10 ` Stefan Monnier 2018-06-01 13:09 ` Eli Zaretskii 2018-06-01 13:20 ` Lars Ingebrigtsen
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.