From c4fc0fc32fdca29fe64429c22cde3c4ab0805b7a Mon Sep 17 00:00:00 2001 From: Michael Albinus Date: Fri, 19 Jul 2024 18:29:49 +0200 Subject: [PATCH] Adapt file-remote-p doc * doc/lispref/files.texi (Magic File Names): Adapt file-remote-p. * lisp/files.el (file-remote-p): Adapt docstring. (cherry picked from commit 0218fb214376555df52188be4afee16249e3639c) --- doc/lispref/files.texi | 16 ++++++++++++---- lisp/files.el | 11 ++++++++--- 2 files changed, 20 insertions(+), 7 deletions(-) diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index e8769b56bfc..5eae6aac894 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -3636,10 +3636,18 @@ ensure this principle is valid. @var{identification} specifies which part of the identifier shall be returned as string. @var{identification} can be the symbol -@code{method}, @code{user} or @code{host}; any other value is handled -like @code{nil} and means to return the complete identifier string. -In the example above, the remote @code{user} identifier string would -be @code{root}. +@code{method}, @code{user}, @code{host} or @code{localname}; any other +value is handled like @code{nil} and means to return the complete +identifier string. In the example above, the remote @code{user} +identifier string would be @code{root}. + +If the remote @var{file} does not contain a method, a user name, or a +host name, the respective default value is returned. The string +returned for @var{identification} @code{localname} can differ depending +on whether there is an existing connection. File name handler specific +implementations could support further @var{identification} symbols; +@xref{Top, Tramp, Tramp, tramp}, for example, knows also the @code{hop} +symbol. If @var{connected} is non-@code{nil}, this function returns @code{nil} even if @var{filename} is remote, if Emacs has no network connection diff --git a/lisp/files.el b/lisp/files.el index 89de62673c2..ab9babbd43f 100644 --- a/lisp/files.el +++ b/lisp/files.el @@ -1310,9 +1310,14 @@ any that are missing. IDENTIFICATION can specify 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. +means to return the complete identification. + +If the remote FILE does not contain a method, a user name, or a host +name, the respective default value is returned. The string returned for +IDENTIFICATION `localname' can differ depending on whether there is an +existing connection. File name handler specific implementations could +support further IDENTIFICATION symbols; Tramp, for example, knows also +the `hop' symbol. If CONNECTED is non-nil, return an identification only if FILE is located on a remote system and a connection is established to -- 2.39.5