bug#18318: 24.4.50; doc of `file-readable-p'

bug#18318: 24.4.50; doc of `file-readable-p'

[Drew Adams]

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@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''

bug#18318: 24.4.50; doc of `file-readable-p'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@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

bug#18318: 24.4.50; doc of `file-readable-p'

[Drew Adams]

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

bug#18318: 24.4.50; doc of `file-readable-p'

[Eli Zaretskii]

> Date: Sat, 30 Apr 2016 08:07:31 -0800 (GMT-08:00)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 18318@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.

bug#18318: 24.4.50; doc of `file-readable-p'

[Drew Adams]

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

bug#18318: 24.4.50; doc of `file-readable-p'

[Eli Zaretskii]

> Date: Sat, 30 Apr 2016 09:32:01 -0800 (GMT-08:00)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: larsi@gnus.org, 18318@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.