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

Previous Next

Full log

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.

Previous Next

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