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.

4 files changed, 46 insertions, 17 deletions

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