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

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

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

> Do you just want to say that `file-remote-p' never opens
> a new connection (i.e., a connection that is not already
> established/open)?

Yes.

> If so, let's just say that: It never opens a new remote
> connection.  It can only reuse a connection that is
> already open.

Sounds OK to me.

> I understand, and will try to propose something, once I
> understand what we're really trying to say.  Can the handler
> establish a _new_ connection?  If so, then `file-remote-p'
> can do so. If not, then can't we just say that
> `file-remote-p' never establishes (opens) a new connection?

It is a promise to libraries using `file-remote-p'. It is guaranteed
that the function call is cheap, and that it could be used here and
there w/o remarkable overhead.

It is also an implementation hint. Any handler that provides an own
implementation of `file-remote-p' shall behave like this.
`tramp-handle-file-remote-p' and `ange-ftp-file-remote-p' do so.

As a consequence, the result might differ whether a connection is
already open, or not. If the connection is not established yet, we get

(file-remote-p "/ssh::" 'localname) => ""

If there is an established connection, we see

(file-remote-p "/ssh::" 'localname) => "/home/albinus"

Best regards, Michael.