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