From 7e809b9ef7b8e07851525ffb9c03a02c5ea6af82 Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs@gmail.com>
Date: Wed, 26 Aug 2020 12:37:24 +0200
Subject: [PATCH] Don't recommend redefining auto-save filename functions

* doc/lispref/backups.texi (Auto-Saving): Document
auto-save-file-name-transforms.
* lisp/files.el (make-auto-save-file-name)
(auto-save-file-name-p): Remove suggestion to redefine for
customization (bug#34911).
---
 doc/lispref/backups.texi | 67 ++++++++++++++++------------------------
 lisp/files.el            |  5 +--
 2 files changed, 30 insertions(+), 42 deletions(-)

diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi
index e14f77f9fc4..e651ef8c554 100644
--- a/doc/lispref/backups.texi
+++ b/doc/lispref/backups.texi
@@ -466,6 +466,33 @@ Auto Save mode is enabled if @code{buffer-auto-save-file-name} is
 non-@code{nil} and @code{buffer-saved-size} (see below) is non-zero.
 @end deffn
 
+@defvar auto-save-file-name-transforms
+This variable lists transforms to apply to buffer file name before
+making auto-save file name.
+
+Each transform is a list of the form @code{(@var{regexp}
+@var{replacement} [@var{uniquify}])}: @var{regexp} is a regular
+expression to match against the file name.  If it matches,
+@code{replace-match} is used to replace the matching part with
+@var{replacement}.  If the optional element @var{uniquify} is non-nil,
+the auto-save file name is constructed by taking the directory part of
+the replaced file-name, concatenated with the buffer file name with
+all directory separators changed to @samp{!} to prevent clashes.  This
+will not work correctly if your filesystem truncates the resulting
+name.
+
+All the transforms in the list are tried, in the order they are listed.
+When one transform applies, its result is final;
+no further transforms are tried.
+
+The default value is set up to put the auto-save file into the
+temporary directory (@pxref{Unique File Names}) for editing a
+remote file.
+
+On MS-DOS filesystems without long names this variable is always
+ignored.
+@end defvar
+
 @defun auto-save-file-name-p filename
 This function returns a non-@code{nil} value if @var{filename} is a
 string that could be the name of an auto-save file.  It assumes
@@ -487,21 +514,6 @@ name.  The argument @var{filename} should not contain a directory part.
      @result{} nil
 @end group
 @end example
-
-The standard definition of this function is as follows:
-
-@example
-@group
-(defun auto-save-file-name-p (filename)
-  "Return non-nil if FILENAME can be yielded by..."
-  (string-match "^#.*#$" filename))
-@end group
-@end example
-
-This function exists so that you can customize it if you wish to
-change the naming convention for auto-save files.  If you redefine it,
-be sure to redefine the function @code{make-auto-save-file-name}
-correspondingly.
 @end defun
 
 @defun make-auto-save-file-name
@@ -517,31 +529,6 @@ function should check that variable first.
      @result{} "/xcssun/users/rms/lewis/#backups.texi#"
 @end group
 @end example
-
-Here is a simplified version of the standard definition of this
-function:
-
-@example
-@group
-(defun make-auto-save-file-name ()
-  "Return file name to use for auto-saves \
-of current buffer.."
-  (if buffer-file-name
-@end group
-@group
-      (concat
-       (file-name-directory buffer-file-name)
-       "#"
-       (file-name-nondirectory buffer-file-name)
-       "#")
-    (expand-file-name
-     (concat "#%" (buffer-name) "#"))))
-@end group
-@end example
-
-This exists as a separate function so that you can redefine it to
-customize the naming convention for auto-save files.  Be sure to
-change @code{auto-save-file-name-p} in a corresponding way.
 @end defun
 
 @defopt auto-save-visited-file-name
diff --git a/lisp/files.el b/lisp/files.el
index 9a20ad41bae..e08f0f0134c 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -6483,7 +6483,7 @@ Also rename any existing auto save file, if it was made in this session."
 (defun make-auto-save-file-name ()
   "Return file name to use for auto-saves of current buffer.
 Does not consider `auto-save-visited-file-name' as that variable is checked
-before calling this function.  You can redefine this for customization.
+before calling this function.
 See also `auto-save-file-name-p'."
   (if buffer-file-name
       (let ((handler (find-file-name-handler buffer-file-name
@@ -6590,7 +6590,8 @@ See also `auto-save-file-name-p'."
 
 (defun auto-save-file-name-p (filename)
   "Return non-nil if FILENAME can be yielded by `make-auto-save-file-name'.
-FILENAME should lack slashes.  You can redefine this for customization."
+FILENAME should lack slashes.
+See also `make-auto-save-file-name'."
   (string-match "\\`#.*#\\'" filename))
 
 (defun wildcard-to-regexp (wildcard)
-- 
2.39.2