Documentation of file-exists-p in the elisp manual could be better...

Documentation of file-exists-p in the elisp manual could be better...

[Dan Katz]

In GNU Emacs 21.3.2 (i386-pc-linux-gnu, X toolkit, Xaw3d scroll bars)
 of 2003-04-24 on raven, modified by Debian



Hi.

I went looking for a way to find out if a directory existed, and ended
up using file-exists-p.  Looking at the elisp manual, however, did not
make it clear whether this was the correct approach or whether it was
"working by accident."  In particular, the elisp manual description of
file-exists-p was not really clear whether (or how) this function
would (or should) work for directories, sym-links, etc.  While it
seems to basically "do the right thing", I suggest that the
documentation needs to be a bit more explicit about notions of
"generalized" files and how the file-handling functions apply.

The docstring for file-exists-p was not much use in this regard,
although it's link to file-attributes is what led me to suspect that
file-exists-p might be the correct approach for directories as well.
That's a rather indirect hint, however.

I hope this documentation commentary is useful.

Dan

Re: Documentation of file-exists-p in the elisp manual could be better...

[Kevin Rodgers]

Dan Katz wrote:

> I went looking for a way to find out if a directory existed, and ended
> up using file-exists-p.  Looking at the elisp manual, however, did not
> make it clear whether this was the correct approach or whether it was
> "working by accident."  In particular, the elisp manual description of
> file-exists-p was not really clear whether (or how) this function
> would (or should) work for directories, sym-links, etc.  While it
> seems to basically "do the right thing", I suggest that the
> documentation needs to be a bit more explicit about notions of
> "generalized" files and how the file-handling functions apply.
> 
> The docstring for file-exists-p was not much use in this regard,
> although it's link to file-attributes is what led me to suspect that
> file-exists-p might be the correct approach for directories as well.
> That's a rather indirect hint, however.

What is unclear about this:

| file-directory-p is a built-in function.
| (file-directory-p FILENAME)
|
| Return t if FILENAME names an existing directory.
| Symbolic links to directories count as directories.
| See `file-symlink-p' to distinguish symlinks.

-- 
<a href="mailto:&lt;kevin.rodgers&#64;ihs.com&gt;">Kevin Rodgers</a>

Re: Documentation of file-exists-p in the elisp manual could be better...

[Dan Katz]

On Thu, 05 Jun 2003, Kevin Rodgers wrote:

> Dan Katz wrote:
> 
>> I went looking for a way to find out if a directory existed, and
>> ended up using file-exists-p.  Looking at the elisp manual,
>> however, did not make it clear whether this was the correct
>> approach or whether it was "working by accident." 
> 
> What is unclear about this:
> 
> | file-directory-p is a built-in function.
> | (file-directory-p FILENAME)
> |
> | Return t if FILENAME names an existing directory.
> | Symbolic links to directories count as directories.
> | See `file-symlink-p' to distinguish symlinks.


Nothing at all; in fact I even looked at file-directory-p in my
excursion into the elisp manual, and saw that it would do the job.  On
the other hand, it was argued to me that file-exists-p expressed the
contextual intent of the test better than file-directory-p.  I
dunno...

What *is* still unclear to me, however, is the precise domain of
file-exists-p?  Regular files (i.e., the same as file-regular-p)?
Regular files + directories?  Everything which could possibly be
conceived of as a file?  Platform dependent?

I notice that at the end of the docstring for file-directory-p there
is a particularly useful "See `file-symlink-p' to distinguish
symlinks." comment.  If file-directory-p et al. are the preferred ways
to test for the existence of files, symlinks, etc., then I suggest
that similar comments might be useful in the context of file-exists-p.
My adventure into this area, at least, began with roughly the
following dialog:

step 0:    I need to see if a directory exists...
step 1:    M-x apropos exist
step 2:    Hmmm... no 'directory-exists-p', but there is this function 
           called 'file-exists-p'...

Thanks.

Dan