unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#15159: 24.3.50; doc of `file-relative-name'
@ 2013-08-22  3:42 Drew Adams
  2013-08-22 14:43 ` Eli Zaretskii
  2014-02-08  4:54 ` Lars Ingebrigtsen
  0 siblings, 2 replies; 5+ messages in thread
From: Drew Adams @ 2013-08-22  3:42 UTC (permalink / raw)
  To: 15159

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'





^ permalink raw reply	[flat|nested] 5+ messages in thread

* bug#15159: 24.3.50; doc of `file-relative-name'
  2013-08-22  3:42 bug#15159: 24.3.50; doc of `file-relative-name' Drew Adams
@ 2013-08-22 14:43 ` Eli Zaretskii
  2014-02-08  4:54 ` Lars Ingebrigtsen
  1 sibling, 0 replies; 5+ messages in thread
From: Eli Zaretskii @ 2013-08-22 14:43 UTC (permalink / raw)
  To: Drew Adams; +Cc: 15159

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





^ permalink raw reply	[flat|nested] 5+ messages in thread

* bug#15159: 24.3.50; doc of `file-relative-name'
       [not found] ` <<83d2p5kcps.fsf@gnu.org>
@ 2013-08-22 15:34   ` Drew Adams
  2013-08-22 19:05     ` Andreas Schwab
  0 siblings, 1 reply; 5+ messages in thread
From: Drew Adams @ 2013-08-22 15:34 UTC (permalink / raw)
  To: Eli Zaretskii, Drew Adams; +Cc: 15159

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





^ permalink raw reply	[flat|nested] 5+ messages in thread

* bug#15159: 24.3.50; doc of `file-relative-name'
  2013-08-22 15:34   ` Drew Adams
@ 2013-08-22 19:05     ` Andreas Schwab
  0 siblings, 0 replies; 5+ messages in thread
From: Andreas Schwab @ 2013-08-22 19:05 UTC (permalink / raw)
  To: Drew Adams; +Cc: 15159

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





^ permalink raw reply	[flat|nested] 5+ messages in thread

* bug#15159: 24.3.50; doc of `file-relative-name'
  2013-08-22  3:42 bug#15159: 24.3.50; doc of `file-relative-name' Drew Adams
  2013-08-22 14:43 ` Eli Zaretskii
@ 2014-02-08  4:54 ` Lars Ingebrigtsen
  1 sibling, 0 replies; 5+ messages in thread
From: Lars Ingebrigtsen @ 2014-02-08  4:54 UTC (permalink / raw)
  To: Drew Adams; +Cc: 15159

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/





^ permalink raw reply	[flat|nested] 5+ messages in thread

end of thread, other threads:[~2014-02-08  4:54 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2013-08-22  3:42 bug#15159: 24.3.50; doc of `file-relative-name' Drew Adams
2013-08-22 14:43 ` Eli Zaretskii
2014-02-08  4:54 ` Lars Ingebrigtsen
     [not found] <<88607a9f-9b87-45b3-b661-99970acc0c97@default>
     [not found] ` <<83d2p5kcps.fsf@gnu.org>
2013-08-22 15:34   ` Drew Adams
2013-08-22 19:05     ` Andreas Schwab

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).