Add file-local-name

* doc/lispref/files.texi (Magic File Names): Add `file-local-name'.
(Unique File Names): Use it.

* etc/NEWS: Mention `file-local-name'.

* lisp/files.el (file-local-name): New defun.
(file-expand-wildcards):
* lisp/eshell/em-tramp.el (eshell/su, eshell/sudo):
* lisp/eshell/esh-ext.el (eshell-remote-command):
* lisp/eshell/esh-proc.el (eshell-gather-process-output):
* lisp/org/ob-core.el (org-babel-local-file-name):
* lisp/progmodes/gud.el (gud-common-init, gud-format-command):
* lisp/progmodes/python.el (python-shell-send-file):
* lisp/shell.el (shell):
* lisp/vc/ediff-diff.el (ediff-same-file-contents):
* lisp/vc/vc-git.el (vc-git-checkin): Use it.

1 files changed, 8 insertions, 8 deletions

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index e189da9fbe2..d9e366be1ba 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2546,14 +2546,7 @@ that remote host.  If such a directory does not exist, or
 @end defun
 
 In order to extract the local part of the path name from a temporary
-file, the following code could be used:
-
-@example
-@group
-(let ((tmpfile (make-nearby-temp-file "foo")))
-  (or (file-remote-p tmpfile 'localname) tmpfile))
-@end group
-@end example
+file, @code{file-local-name} could be used.
 
 @node File Name Completion
 @subsection File Name Completion
@@ -3233,6 +3226,13 @@ non-magic directory to serve as its current directory, and this function
 is a good way to come up with one.
 @end defun
 
+@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.
+@end defun
+
 @defopt remote-file-name-inhibit-cache
 The attributes of remote files can be cached for better performance.  If
 they are changed outside of Emacs's control, the cached values become