GNU bug report logs - #18318
24.4.50; doc of `file-readable-p'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 18318 in the body.
You can then email your comments to 18318 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.4.50; doc of `file-readable-p'
Date: Fri, 22 Aug 2014 14:14:05 -0700 (PDT)

The doc - both Elisp manual and doc string, should explicitly point out
that this returns non-nil for a directory, IOW, a non-nil value does not
mean that the file can be, say, inserted into a buffer.

In addition, it would be better to change the parameter name to
FILE-OR-DIR (or even FILE-OR-DIR-NAME).  It is all to easy to not
realize, when reading this, that this does not test for a non-directory
file that is readable.

In GNU Emacs 24.4.50.1 (i686-pc-mingw32)
 of 2014-06-28 on ODIEONE
Bzr revision: 117431 rgm <at> gnu.org-20140628015517-eku6hj8mpgcvfnso
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/snapshot/trunk
 --enable-checking=yes,glyphs 'CFLAGS=-O0 -g3'
 LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

Message #8 received at 18318 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 18318 <at> debbugs.gnu.org
Subject: Re: bug#18318: 24.4.50; doc of `file-readable-p'
Date: Sat, 30 Apr 2016 15:39:12 +0200

Drew Adams <drew.adams <at> oracle.com> writes:

> The doc - both Elisp manual and doc string, should explicitly point out
> that this returns non-nil for a directory, IOW, a non-nil value does not
> mean that the file can be, say, inserted into a buffer.
>
> In addition, it would be better to change the parameter name to
> FILE-OR-DIR (or even FILE-OR-DIR-NAME).  It is all to easy to not
> realize, when reading this, that this does not test for a non-directory
> file that is readable.

Well, the function isn't about files or directories, but filenames.  It
can be a fifo, a device node, etc.  So I think the doc is fine as it is.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #15 received at 18318 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 18318 <at> debbugs.gnu.org
Subject: RE: bug#18318: 24.4.50; doc of `file-readable-p'
Date: Sat, 30 Apr 2016 08:07:31 -0800 (GMT-08:00)

> > The doc - both Elisp manual and doc string, should explicitly point out
> > that this returns non-nil for a directory, IOW, a non-nil value does not
> > mean that the file can be, say, inserted into a buffer.
> >
> > In addition, it would be better to change the parameter name to
> > FILE-OR-DIR (or even FILE-OR-DIR-NAME).  It is all to easy to not
> > realize, when reading this, that this does not test for a non-directory
> > file that is readable.
> 
> Well, the function isn't about files or directories, but filenames.  It
> can be a fifo, a device node, etc.

All the more reason to make the doc clearer.  The argument
passed to the function is not necessarily the name of a file
whose contents can, say, be inserted into a buffer.  It is
not a FILENAME, unless you understand "filename" in the wider
sense you elaborated - elaboration that is missing from this doc.

It is (I think) far more common for a file or directory name
(string) to be passed as an argument than it is for a FIFO,
device node, etc. to be passed.  The directory case is common,
and the doc misleads.  If you want to mention other
possibilities, besides file and dir names, so much the better.
But ideal should not be the enemy of better.

> So I think the doc is fine as it is.

Disagree.

Message #18 received at 18318 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: larsi <at> gnus.org, 18318 <at> debbugs.gnu.org
Subject: Re: bug#18318: 24.4.50; doc of `file-readable-p'
Date: Sat, 30 Apr 2016 19:24:48 +0300

> Date: Sat, 30 Apr 2016 08:07:31 -0800 (GMT-08:00)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 18318 <at> debbugs.gnu.org
> 
> It is (I think) far more common for a file or directory name
> (string) to be passed as an argument than it is for a FIFO,
> device node, etc. to be passed.  The directory case is common,
> and the doc misleads.

Why do you say it misleads?  A directory is just a kind of file (the
manual explains that, if the user doesn't already know).  So I see
nothing misleading here.

Message #21 received at 18318 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: larsi <at> gnus.org, 18318 <at> debbugs.gnu.org
Subject: RE: bug#18318: 24.4.50; doc of `file-readable-p'
Date: Sat, 30 Apr 2016 09:32:01 -0800 (GMT-08:00)

> > It is (I think) far more common for a file or directory name
> > (string) to be passed as an argument than it is for a FIFO,
> > device node, etc. to be passed.  The directory case is common,
> > and the doc misleads.
> 
> Why do you say it misleads?  A directory is just a kind of file (the
> manual explains that, if the user doesn't already know).  So I see
> nothing misleading here.

Sure, a directory is also a file.  But it is a special kind
of file.  What is misleading is that a reader might well not
think that a directory name will return a non-nil value, and
so assume that s?he can do things with it such as insert its
contents in a buffer etc.

It's about being a bit clearer; that's all.

Message #24 received at 18318 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: larsi <at> gnus.org, 18318 <at> debbugs.gnu.org
Subject: Re: bug#18318: 24.4.50; doc of `file-readable-p'
Date: Sat, 30 Apr 2016 21:23:30 +0300

> Date: Sat, 30 Apr 2016 09:32:01 -0800 (GMT-08:00)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: larsi <at> gnus.org, 18318 <at> debbugs.gnu.org
> 
> What is misleading is that a reader might well not think that a
> directory name will return a non-nil value, and so assume that s?he
> can do things with it such as insert its contents in a buffer etc.

And she can, indeed, at least on some systems.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.