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

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

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

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?

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

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?

Thx - Drew