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.