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

["Drew Adams" <drew.adams@oracle.com>]

> > So what are we trying to tell _users_ here?
> > Is this what we are really trying to say?
> >
> >  FILE must be an absolute file name.
> >
> > If so, what should we say happens if you nevertheless pass 
> > a relative file name?  Return value is unspecified (could
> > be nil or non-nil)?  An error is raised?  What should we
> > tell users is the behavior?
> 
> Any relative filename cannot expand to a different remote 
> connection, or a filename of your local filesystem. But you
> are right, this information is irrelevant for the docstring
> of `file-remote-p'.

"relative file names do not work across remote connections" should be dropped,
as it is not clear at all what we're trying to say by it.  If we want to say
something about relative file names, then it needs to be clear, whatever it is.

We really should say what happens if a relative file name is passed as arg.
It's still not clear to me, from your statement above.

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

If that's not the case, please try again to explain, and I'll propose something
else once I understand.  (Simple tests seem to indicate that nil is returned.)

> >> > 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.
> >
> > Sorry, I just don't understand your reply to my question 
> > (what is the complete identification - what is returned if 
> > IDENTIFICATION is nil).  Could you rephrase or elaborate?
> 
> 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.

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

HTH.