From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 29 Dec 2018 15:34:57 +0000 (+0200)
Subject: Improve documentation of 'file-local-name' and related APIs
X-Git-Tag: emacs-26.1.91~16
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=2e8825d6c55409c15749b12dacc1f49f9c8783c7;p=emacs.git
Improve documentation of 'file-local-name' and related APIs
* doc/lispref/files.texi (Unique File Names)
(Magic File Names, File Name Expansion): Improve documentation
of the "local part" of a remote file name.
* doc/lispref/processes.texi (Synchronous Processes)
(Asynchronous Processes): State explicitly that program and
file names passed to functions that start remote processes
need to be relative or obtained by 'file-local-name'.
* lisp/files.el (file-local-name):
* lisp/simple.el (start-file-process, process-file): Improve
the documentation of the "local part" of a remote file name,
and its use in APIs that start remote processes.
---
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index c434336d5a6..6364289b690 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2519,9 +2519,9 @@ with @samp{/:}.
@defmac file-name-quote name
This macro adds the quotation prefix @samp{/:} to the file @var{name}.
For a local file @var{name}, it prefixes @var{name} with @samp{/:}.
-If @var{name} is a remote file name, the local part of @var{name} is
-quoted. If @var{name} is already a quoted file name, @var{name} is
-returned unchanged.
+If @var{name} is a remote file name, the local part of @var{name}
+(@pxref{Magic File Names}) is quoted. If @var{name} is already a
+quoted file name, @var{name} is returned unchanged.
@example
@group
@@ -2700,8 +2700,8 @@ that remote host. If such a directory does not exist, or
@code{temporary-file-directory} is returned.
@end defun
-In order to extract the local part of the path name from a temporary
-file, @code{file-local-name} could be used.
+In order to extract the local part of the file's name of a temporary
+file, use @code{file-local-name} (@pxref{Magic File Names}).
@node File Name Completion
@subsection File Name Completion
@@ -3382,11 +3382,24 @@ non-magic directory to serve as its current directory, and this function
is a good way to come up with one.
@end defun
+@cindex local part of remote file name
@defun file-local-name filename
-This function returns the local part of file @var{filename}. For a
-remote @var{filename}, it returns a file name which could be used
-directly as argument of a remote process. If @var{filename} is local,
-this function returns the file name.
+This function returns the @dfn{local part} of @var{filename}. This is
+the part of the file's name that identifies it on the remote host, and
+is typically obtained by removing from the remote file name the parts
+that specify the remote host and the method of accessing it. For
+example:
+
+@smallexample
+(file-local-name "/ssh:@var{user}@@@var{host}:/foo/bar")
+ @result{} "/foo/bar"
+@end smallexample
+
+For a remote @var{filename}, this function returns a file name which
+could be used directly as an argument of a remote process
+(@pxref{Asynchronous Processes}, and @pxref{Synchronous Processes}),
+and as the program to run on the remote host. If @var{filename} is
+local, this function returns it unchanged.
@end defun
@defopt remote-file-name-inhibit-cache
diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 2aca7f82a1a..f2b3a9c096b 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -451,7 +451,9 @@ present in @var{args}. To avoid confusion, it may be best to avoid
absolute file names in @var{args}, but rather to specify all file
names as relative to @code{default-directory}. The function
@code{file-relative-name} is useful for constructing such relative
-file names.
+file names. Alternatively, you can use @code{file-local-name}
+(@pxref{Magic File Names}) to obtain an absolute file name as seen
+from the remote host's perspective.
@end defun
@defvar process-file-side-effects
@@ -817,7 +819,12 @@ In the latter case, the local part of @code{default-directory} becomes
the working directory of the process.
This function does not try to invoke file name handlers for
-@var{program} or for the rest of @var{args}.
+@var{program} or for the rest of @var{args}. For that reason, if
+@var{program} or any of @var{args} use the remote-file syntax
+(@pxref{Magic File Names}), they must be converted either to file
+names relative to @code{default-directory}, or to names that identify
+the files locally on the remote host, by running them through
+@code{file-local-name}.
Depending on the implementation of the file handler, it might not be
possible to apply @code{process-filter} or @code{process-sentinel} to
diff --git a/lisp/files.el b/lisp/files.el
index 7794f398cf9..e9d40f22f1c 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -1150,7 +1150,10 @@ consecutive checks. For example:
(defun file-local-name (file)
"Return the local name component of FILE.
-It returns a file name which can be used directly as argument of
+This function removes from FILE the specification of the remote host
+and the method of accessing the host, leaving only the part that
+identifies FILE locally on the remote system.
+The returned file name can be used directly as argument of
`process-file', `start-file-process', or `shell-command'."
(or (file-remote-p file 'localname) file))
diff --git a/lisp/simple.el b/lisp/simple.el
index 2116facd58b..8671fb91747 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -3866,11 +3866,14 @@ interactively, this is t."
(process-file shell-file-name nil t nil shell-command-switch command))))
(defun process-file (program &optional infile buffer display &rest args)
- "Process files synchronously in a separate process.
+ "Process files synchronously in a separate process that runs PROGRAM.
Similar to `call-process', but may invoke a file handler based on
`default-directory'. The current working directory of the
subprocess is `default-directory'.
+If PROGRAM is a remote file name, it should be processed
+by `file-local-name' before passing it to this function.
+
File names in INFILE and BUFFER are handled normally, but file
names in ARGS should be relative to `default-directory', as they
are passed to the process verbatim. (This is a difference to
@@ -3915,12 +3918,15 @@ Similar to `start-process', but may invoke a file handler based on
This handler ought to run PROGRAM, perhaps on the local host,
perhaps on a remote host that corresponds to `default-directory'.
-In the latter case, the local part of `default-directory' becomes
-the working directory of the process.
+In the latter case, the local part of `default-directory', the one
+produced from it by `file-local-name', becomes the working directory
+of the process on the remote host.
PROGRAM and PROGRAM-ARGS might be file names. They are not
-objects of file handler invocation. File handlers might not
-support pty association, if PROGRAM is nil."
+objects of file handler invocation, so they need to be obtained
+by calling `file-local-name', in case they are remote file names.
+
+File handlers might not support pty association, if PROGRAM is nil."
(let ((fh (find-file-name-handler default-directory 'start-file-process)))
(if fh (apply fh 'start-file-process name buffer program program-args)
(apply 'start-process name buffer program program-args))))