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

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

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

> Are you saying that nil is always returned for a relative file name?  If so,
> let's just say that: "Return nil if FILE is a relative file name".  (No need to
> say that you must or should use an absolute name.)

Thinking about (and testing a little bit) it seems like this: for
relative file names it always returns nil, indeed. This is because it
does not apply `expand-file-name'. Your proposed sentence looks OK.

>> When IDENTIFICATION is nil, the returned string is everything 
>> until the last ":" (with expanded default method, default user,
>> default host).
>> 
>> (file-remote-p "/sudo::/") => "/sudo:root@localhost:"
>> (file-remote-p "/localhost:/") => "/scpc:localhost:"
>
> Fine. Let's say that (it's not obvious, IMHO).
>
>  When IDENTIFICATION is nil, the returned string is a complete
>  remote identifier: with components method, user, and host.
>  The components are those present in FILE, with defaults filled
>  in for any that are missing.

OK.

>> What I have tried to explain is a common technique for creation of new
>> remote filenames, derived from an existing one. Let's say you have a
>> variable `file' containing the remote filename "/sudo::/path/to/file",
>> and you want to create a new remote filename for the file 
>> "/bin/sh". You apply then (concat (file-remote-p file) "/bin/sh")
>
> That's a useful tip about another way to _use_ the function, and also not so
> obvious.  Let's say that too.
>
>   Tip: You can use this expansion of remote identifier components
>   to derive a new remote name from an existing one.  For example,
>   if FILE is "/sudo::/path/to/file" then 
>   (concat (file-remote-p FILE) "/bin/sh") returns a remote
>   name for file "/bin/sh" that has the same remote identifier as
>   FILE but expanded; a name such as "/sudo:myhost.org:/bin/sh".

OK as well. Minor change: the result for the sudo case ought to be
"/sudo:root@myhost:/bin/sh". "root" is the default user name for "sudo",
and "myhost" instead of "myhost.org" because the default host name in
this case is the value of `system-name'.

> HTH.

Thanks, and best regards, Michael.