Document file-name-quote, file-name-unquote and file-name-quoted-p

* doc/lispref/files.texi (File Name Expansion):
* etc/NEWS: Mention file-name-quote, file-name-unquote and
file-name-quoted-p.

* lisp/files.el (file-name-non-special): Revert using
file-name-quote, file-name-unquote and file-name-quoted-p.

3 files changed, 55 insertions, 4 deletions

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 26db93cd8fd..906cd562612 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2402,6 +2402,47 @@ through the immediately preceding @samp{/}).
 
 @end defun
 
+  Sometimes, it is not desired to expand file names.  In such cases,
+the file name can be quoted to suppress the expansion, and to handle
+the file name literally.  Quoting happens by prefixing the file name
+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.
+
+@example
+@group
+(substitute-in-file-name (file-name-quote "bar/~/foo"))
+     @result{} "/:bar/~/foo"
+@end group
+
+@group
+(substitute-in-file-name (file-name-quote "/ssh:host:bar/~/foo"))
+     @result{} "/ssh:host:/:bar/~/foo"
+@end group
+@end example
+
+The macro cannot be used to suppress file name handlers from magic
+file names (@pxref{Magic File Names}).
+@end defmac
+
+@defmac file-name-unquote name
+This macro removes the quotation prefix @samp{/:} from the file
+@var{name}, if any. If @var{name} is a remote file name, the local
+part of @var{name} is unquoted.
+@end defmac
+
+@defmac file-name-quoted-p name
+This macro returns non-@code{nil}, when @var{name} is quoted with the
+prefix @samp{/:}.  If @var{name} is a remote file name, the local part
+of @var{name} is checked.
+@end defmac
+
+
 @node Unique File Names
 @subsection Generating Unique File Names
 @cindex unique file names
diff --git a/etc/NEWS b/etc/NEWS
index a62668a2625..614b6144308 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -749,6 +749,11 @@ can be used for creation of temporary files of remote or mounted directories.
 of remote processes.
 
 +++
+** The new functions 'file-name-quote', 'file-name-unquote' and
+'file-name-quoted-p' can be used to quote / unquote file names with
+the prefix "/:".
+
++++
 ** The new error 'file-missing', a subcategory of 'file-error', is now
 signaled instead of 'file-error' if a file operation acts on a file
 that does not exist.
diff --git a/lisp/files.el b/lisp/files.el
index 6f6e8687f52..790f6cedfd6 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -6923,19 +6923,24 @@ only these files will be asked to be saved."
     (save-match-data
       (while (consp file-arg-indices)
         (let ((pair (nthcdr (car file-arg-indices) arguments)))
-          (and (car pair) (setcar pair (file-name-unquote (car pair)))))
+          (and (car pair)
+               (string-match "\\`/:" (car pair))
+               (setcar pair
+                       (if (= (length (car pair)) 2)
+                           "/"
+                         (substring (car pair) 2)))))
         (setq file-arg-indices (cdr file-arg-indices))))
     (pcase method
       (`identity (car arguments))
-      (`add (file-name-quote (apply operation arguments)))
+      (`add (concat "/:" (apply operation arguments)))
       (`insert-file-contents
        (let ((visit (nth 1 arguments)))
          (unwind-protect
              (apply operation arguments)
            (when (and visit buffer-file-name)
-             (setq buffer-file-name (file-name-quote buffer-file-name))))))
+             (setq buffer-file-name (concat "/:" buffer-file-name))))))
       (`unquote-then-quote
-       (let ((buffer-file-name (file-name-unquote buffer-file-name)))
+       (let ((buffer-file-name (substring buffer-file-name 2)))
          (apply operation arguments)))
       (_
        (apply operation arguments)))))