* 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.