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.

2 files changed, 15 insertions, 6 deletions

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