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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 15159 in the body.
You can then email your comments to 15159 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.3.50; doc of `file-relative-name'
Date: Wed, 21 Aug 2013 20:42:19 -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.

(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 <at> 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'

Message #8 received at 15159 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: 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 17:43:43 +0300

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

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.

Message #14 received at 15159 <at> debbugs.gnu.org (full text, mbox):

From: Andreas Schwab <schwab <at> linux-m68k.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 15159 <at> debbugs.gnu.org
Subject: Re: bug#15159: 24.3.50; doc of `file-relative-name'
Date: Thu, 22 Aug 2013 21:05:28 +0200

Drew Adams <drew.adams <at> 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 <at> linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Message #19 received at 15159 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: 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: Fri, 07 Feb 2014 20:54:23 -0800

Drew Adams <drew.adams <at> 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/

Previous Next

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