GNU bug report logs - #15159
24.3.50; doc of `file-relative-name'

Previous Next

Full log

Message #11 received at 15159 <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: 15159 <at> debbugs.gnu.org
Subject: RE: bug#15159: 24.3.50; doc of `file-relative-name'
Date: Thu, 22 Aug 2013 08:34:57 -0700 (PDT)

> > The doc says nothing about whether arg FILENAME needs to be absolute or
> > relative, and in fact it can be either.  It is clear enough what the
> > function does if it is absolute, but the doc should say explicitly what
> > it does for a relative FILENAME, namely, it expands the FILENAME in the
> > `default-directory' of the current buffer.
> 
> Sorry, but I see nothing unclear in this doc string:
> 
>   (file-relative-name FILENAME &optional DIRECTORY)
> 
>   Convert FILENAME to be relative to DIRECTORY (default: `default-
>   directory').
>   This function returns a relative file name which is equivalent to FILENAME
>   when used with that default directory as the default.
> 
> "Convert FILENAME to be relative to DIRECTORY" is accurate and
> unequivocal.  The fact that relative file names are treated as
> relative to the current buffer's default-directory is what Emacs does
> with _every_ file name in _any_ function; if users don't know this
> basic fact, they will have problems all over the place.

OK, so everything is clear to you.  Wunderbar.

I reported this bug because everything was not clear to me.  To begin with,
it was not clear to me whether FILENAME needed to be absolute.

OK, so I tried it and figured out how the function handles a relative
FILENAME.  Not a big deal.  Still, I would suggest (again) that the doc 
make this clear by being explicit.

Previous Next

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