bug#17073: 24.3.50; file-symlink-p doesn't return t as described in the doc

bug#17073: 24.3.50; file-symlink-p doesn't return t as described in the doc

[Michael Heerdegen]

Hello,

the doc of `file-symlink-p' says:

This function returns t when given the name of a symlink that
points to a nonexistent file.

But this is not the case here.  Instead, it returns the resolved file
name, which is a nonexisting file.

This is with emacs -Q, and with all Emacs versions I tried, which were
23, 24 that come with Debian testing, and a recent built from trunk.

Tested on Debian testing. 


Thanks,

Michael.



In GNU Emacs 24.3.50.2 (x86_64-unknown-linux-gnu, GTK+ Version 3.10.7)
 of 2014-03-14 on drachen
Windowing system distributor `The X.Org Foundation', version 11.0.11500000
System Description:	Debian GNU/Linux testing (jessie)

bug#17073: 24.3.50; file-symlink-p doesn't return t as described in the doc

[Glenn Morris]

Michael Heerdegen wrote:

> the doc of `file-symlink-p' says:
>
> This function returns t when given the name of a symlink that
> points to a nonexistent file.
>
> But this is not the case here.  Instead, it returns the resolved file
> name, which is a nonexisting file.

Then I guess it means t in the sense of non-nil.

bug#17073: 24.3.50; file-symlink-p doesn't return t as described in the doc

[Glenn Morris]

Version: 24.4

Doc fixed.

bug#17073: 24.3.50; file-symlink-p doesn't return t as described in the doc

[Juanma Barranquero]

Perhaps it's me, but I don't find the doc for this function (in the
elisp reference) particularly clear

 -- Function: file-symlink-p filename
     If the file FILENAME is a symbolic link, the `file-symlink-p'
     function returns the (non-recursive) link target as a string.

Here it agrees with your interpretation, so at least that is clear.

     (Determining the file name that the link points to from the target
     is nontrivial.)  First, this function recursively follows symbolic
     links at all levels of parent directories.

IIUC, it's saying (above) that it does not follow symbolic links to
files recursively. But (below) that it does follow recursively
symbolic links to directories, until it finds a file (or a symbolic
link to a file). Is that?

   J

bug#17073: 24.3.50; file-symlink-p doesn't return t as described in the doc

[Eli Zaretskii]

> From: Juanma Barranquero <lekktu@gmail.com>
> Date: Mon, 24 Mar 2014 01:25:36 +0100
> 
> Perhaps it's me, but I don't find the doc for this function (in the
> elisp reference) particularly clear
> 
>  -- Function: file-symlink-p filename
>      If the file FILENAME is a symbolic link, the `file-symlink-p'
>      function returns the (non-recursive) link target as a string.
> 
> Here it agrees with your interpretation, so at least that is clear.
> 
>      (Determining the file name that the link points to from the target
>      is nontrivial.)  First, this function recursively follows symbolic
>      links at all levels of parent directories.
> 
> IIUC, it's saying (above) that it does not follow symbolic links to
> files recursively. But (below) that it does follow recursively
> symbolic links to directories, until it finds a file (or a symbolic
> link to a file). Is that?

The difference is between the file (a.k.a. "basename") part of the
file name, and the leading directories part.  And yes, it is true.

bug#17073: 24.3.50; file-symlink-p doesn't return t as described in the doc

[Juanma Barranquero]

On Mon, Mar 24, 2014 at 4:52 AM, Eli Zaretskii <eliz@gnu.org> wrote:

> The difference is between the file (a.k.a. "basename") part of the
> file name, and the leading directories part.  And yes, it is true.

Well, as I said, I think that docstring could benefit from a little love.

    J

bug#17073: 24.3.50; file-symlink-p doesn't return t as described in the doc

[Juanma Barranquero]

On Mon, Mar 24, 2014 at 5:00 AM, Juanma Barranquero <lekktu@gmail.com> wrote:

> Well, as I said, I think that docstring could benefit from a little love.

s/docstring/manual entry/

bug#17073: 24.3.50; file-symlink-p doesn't return t as described in the doc

[Eli Zaretskii]

> From: Juanma Barranquero <lekktu@gmail.com>
> Date: Mon, 24 Mar 2014 05:00:34 +0100
> Cc: 17073@debbugs.gnu.org, Glenn Morris <rgm@gnu.org>, 
> 	Michael Heerdegen <michael_heerdegen@web.de>
> 
> On Mon, Mar 24, 2014 at 4:52 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> > The difference is between the file (a.k.a. "basename") part of the
> > file name, and the leading directories part.  And yes, it is true.
> 
> Well, as I said, I think that docstring could benefit from a little love.

Not sure which part needs love.  Could you perhaps point out the
unclear parts?

bug#17073: 24.3.50; file-symlink-p doesn't return t as described in the doc

[Juanma Barranquero]

On Mon, Mar 24, 2014 at 5:49 PM, Eli Zaretskii <eliz@gnu.org> wrote:

> Not sure which part needs love.  Could you perhaps point out the
> unclear parts?

  First, this function recursively follows symbolic
     links at all levels of parent directories.

On one hand, though I suppose "First, this function recursively
follows..." means "This function, first of all, recursively
follows...", my instinct is that it is the start of an enumeration, so
I expect a "Second, it ...".

On the other hand, you've explained that this:

    If the file FILENAME is a symbolic link, the `file-symlink-p'
     function returns the (non-recursive) link target as a string.

talks about the 'file (a.k.a. "basename") part of the file name', and this

  First, this function recursively follows symbolic
     links at all levels of parent directories.

talks about the 'leading directories part'. Well, I don't find that clear.

   J

bug#17073: 24.3.50; file-symlink-p doesn't return t as described in the doc

[Eli Zaretskii]

> From: Juanma Barranquero <lekktu@gmail.com>
> Date: Mon, 24 Mar 2014 18:01:04 +0100
> Cc: Michael Heerdegen <michael_heerdegen@web.de>, 17073@debbugs.gnu.org
> 
> On Mon, Mar 24, 2014 at 5:49 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> > Not sure which part needs love.  Could you perhaps point out the
> > unclear parts?
> 
>   First, this function recursively follows symbolic
>      links at all levels of parent directories.
> 
> On one hand, though I suppose "First, this function recursively
> follows..." means "This function, first of all, recursively
> follows...", my instinct is that it is the start of an enumeration, so
> I expect a "Second, it ...".
> 
> On the other hand, you've explained that this:
> 
>     If the file FILENAME is a symbolic link, the `file-symlink-p'
>      function returns the (non-recursive) link target as a string.
> 
> talks about the 'file (a.k.a. "basename") part of the file name', and this
> 
>   First, this function recursively follows symbolic
>      links at all levels of parent directories.
> 
> talks about the 'leading directories part'. Well, I don't find that clear.

I tried to clarify and improve the documentation in revision 116859 on
the emacs-24 branch, please take a look.

bug#17073: 24.3.50; file-symlink-p doesn't return t as described in the doc

[Juanma Barranquero]

On Tue, Mar 25, 2014 at 5:10 PM, Eli Zaretskii <eliz@gnu.org> wrote:

> I tried to clarify and improve the documentation in revision 116859 on
> the emacs-24 branch, please take a look.

Superb!  Thanks.

bug#17073: 24.3.50; file-symlink-p doesn't return t as described in the doc

[Eli Zaretskii]

> From: Juanma Barranquero <lekktu@gmail.com>
> Date: Tue, 25 Mar 2014 17:29:26 +0100
> Cc: Michael Heerdegen <michael_heerdegen@web.de>, 17073@debbugs.gnu.org
> 
> On Tue, Mar 25, 2014 at 5:10 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> > I tried to clarify and improve the documentation in revision 116859 on
> > the emacs-24 branch, please take a look.
> 
> Superb!  Thanks.

Thanks.  Can this be closed, then?

bug#17073: 24.3.50; file-symlink-p doesn't return t as described in the doc

[Juanma Barranquero]

Version: 24.3.50

> Can this be closed, then?

Sure. Done.

bug#17073: 24.3.50; file-symlink-p doesn't return t as described in the doc

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

> Thanks.  Can this be closed, then?

The changes in the manual look great, thanks.

Sorry if this is a dumb question, but:

  If the leading directories of @var{filename} include symbolic links,
  this function recursively follows them.

Is this obvious? If not - doesn't it also belong in the docstring?

Thanks,
Michael.

bug#17073: 24.3.50; file-symlink-p doesn't return t as described in the doc

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: Juanma Barranquero <lekktu@gmail.com>,  17073@debbugs.gnu.org
> Date: Tue, 25 Mar 2014 19:37:43 +0100
> 
>   If the leading directories of @var{filename} include symbolic links,
>   this function recursively follows them.
> 
> Is this obvious?

Hard to say.  I think it's pretty obvious to those who are used to
semantics of symlinks (I actually find strange and even confusing the
fact that the manual insists on telling which functions follow links
and in which parts of the filename).  For those who are not used to
symlinks, I'm pretty sure even the above sentence does not say enough.

> If not - doesn't it also belong in the docstring?

Well, we don't normally say about each file-related function whether
it does or doesn't follow symlinks.  So why this one?

bug#17073: 24.3.50; file-symlink-p doesn't return t as described in the doc

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

> >   If the leading directories of @var{filename} include symbolic links,
> >   this function recursively follows them.
> > 
> > Is this obvious?
>
> Hard to say.  I think it's pretty obvious to those who are used to
> semantics of symlinks

I understand it now after thinking about it a bit. Yes, it's quite
obvious.

> > If not - doesn't it also belong in the docstring?
>
> Well, we don't normally say about each file-related function whether
> it does or doesn't follow symlinks.  So why this one?

Ok, I agree.  So I too think we are ready here.


Thanks,

Michael.

bug#17073: 24.3.50; file-symlink-p doesn't return t as described in the doc

[Stefan Monnier]

>> If the leading directories of @var{filename} include symbolic links,
>> this function recursively follows them.
>> Is this obvious?
> Hard to say.  I think it's pretty obvious to those who are used to
> semantics of symlinks (I actually find strange and even confusing the
> fact that the manual insists on telling which functions follow links
> and in which parts of the filename).  For those who are not used to
> symlinks, I'm pretty sure even the above sentence does not say enough.

I think the sentence is more confusing than helpful.  To me it makes it
sound like there something special going on, whereas it's just business
as usual.  And as you say, for people not used to the semantics of
symlinks it's not helpful either (and putting it in file-symlink-p is
confusing since it gives the impression that symlinks only affect
file-symlink-p).


        Stefan

bug#17073: 24.3.50; file-symlink-p doesn't return t as described in the doc

[Eli Zaretskii]

> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> Cc: Michael Heerdegen <michael_heerdegen@web.de>, lekktu@gmail.com,
>         17073@debbugs.gnu.org
> Date: Tue, 25 Mar 2014 20:41:53 -0400
> 
> >> If the leading directories of @var{filename} include symbolic links,
> >> this function recursively follows them.
> >> Is this obvious?
> > Hard to say.  I think it's pretty obvious to those who are used to
> > semantics of symlinks (I actually find strange and even confusing the
> > fact that the manual insists on telling which functions follow links
> > and in which parts of the filename).  For those who are not used to
> > symlinks, I'm pretty sure even the above sentence does not say enough.
> 
> I think the sentence is more confusing than helpful.  To me it makes it
> sound like there something special going on, whereas it's just business
> as usual.

But the same is true for all the other places in files.texi which
document what functions follow symlinks and in which part(s) of their
arguments.  This one is just one such place, one of many.