bug#10319: 24.0.92; doc string of `file-remote-p'

[Michael Albinus <michael.albinus@gmx.de>]

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

>>    A file is considered "remote" if accessing it is likely to
>>    be slower or less reliable than accessing local files.
>
> I'd suggest moving that just after the first sentence ("Test...").
>
>>    Furthermore, relative file names do not work across remote
>>    connections.
>
> Why "Furthermore"?  This seems unrelated to anything preceding it.  If I'm
> right, I'd suggest just dropping "Furthermore".  But in fact I don't know what
> this sentence means.  What do you mean here by "do not work"?

Both sentences from the docstring are not from me. For the first
sentence, I even disagree with Stefan (but we should NOT discuss this
here).

The second sentence means that a relative filename like "/sudo::../../.."
does not make sense, because it cannot expand out of the "/sudo::"
jail.

> Something like this (but see my question about relative file names not working):
>
>  Test whether FILE specifies a location on a remote system.
>  A file is considered remote if accessing it is likely to
>  be slower or less reliable than accessing local files.
>
>  `file-remote-p' never opens a new remote connection.  It can
>  only reuse a connection that is already open. Relative file
>  names do not work across remote connections (????).
>
>  Return nil or a string identifying the remote connection
>  (ideally a prefix of FILE).  For example, the remote
>  identification for filename "/user@host:/foo" could be
>  "/user@host:".  
>
>  IDENTIFICATION specifies which part of the identification to
>  return.  IDENTIFICATION can be the symbol `method',
>  `user', `host', or `localname'.  Any other value is handled
>  like nil and means to return the complete identification.
>  The string returned for IDENTIFICATION `localname' can differ
>  depending on whether there is an existing connection."
>
>  If CONNECTED is non-nil, return an identification only
>  if FILE is located on a remote system and a connection is
>  established to that remote system.

Sounds OK to me. From my point of view you could submit the changed docstring.

> We should also perhaps say what "the complete identification" is/means.  IOW,
> when IDENTIFICATION is nil, what can we say about the return value?

In that case, the returned string could make a local file name remote. We
could always offer to apply

   (concat (file-remote-p "whatever") "local-file-name")

given that `concat' accepts nil as argument.

> HTH - Drew

Best regards, Michael.