bug#15159: 24.3.50; doc of `file-relative-name'

bug#15159: 24.3.50; doc of `file-relative-name'

[Drew Adams]

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.

(The doc says that DIRECTORY defaults to the `default-directory' of the
current buffer, but this is about FILENAME, not DIRECTORY.)

Both the doc string and (elisp) `Relative File Names' need to be fixed.



In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
 of 2013-08-17 on ODIEONE
Bzr revision: 113938 eliz@gnu.org-20130817171807-fxigtkbc6yy8m9iw
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/binary --enable-checking=yes,glyphs
 CFLAGS=-O0 -g3 LDFLAGS=-Lc:/Devel/emacs/lib
 CPPFLAGS=-Ic:/Devel/emacs/include'

bug#15159: 24.3.50; doc of `file-relative-name'

[Eli Zaretskii]

> Date: Wed, 21 Aug 2013 20:42:19 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> 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.

bug#15159: 24.3.50; doc of `file-relative-name'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> 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.
>
> (The doc says that DIRECTORY defaults to the `default-directory' of the
> current buffer, but this is about FILENAME, not DIRECTORY.)

Fixed on trunk.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#15159: 24.3.50; doc of `file-relative-name'

[Drew Adams]

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

bug#15159: 24.3.50; doc of `file-relative-name'

[Andreas Schwab]

Drew Adams <drew.adams@oracle.com> writes:

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

It also doesn't say whether DIRECTORY needs to end with a slash.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."