From 954e9e983b7e446ebf4a7b4dfee0dca82b6b57f7 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Fri, 20 Jan 2017 10:57:14 +0200
Subject: [PATCH] Improve documentation of hooks related to saving buffers

* lisp/files.el (write-file-functions, write-contents-functions)
(before-save-hook, after-save-hook): Note that these are only used
by save-buffer.

* doc/lispref/backups.texi (Auto-Saving):
* doc/lispref/files.texi (Saving Buffers): Mention that
save-related hooks are not run by auto-saving.  (Bug#25460)
---
 doc/lispref/backups.texi |  5 +++++
 doc/lispref/files.texi   |  6 +++++-
 lisp/files.el            | 10 +++++++---
 3 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi
index 83d826018ca..361fa81099b 100644
--- a/doc/lispref/backups.texi
+++ b/doc/lispref/backups.texi
@@ -545,6 +545,11 @@ effect in an existing buffer until the next time auto-save mode is
 reenabled in it.  If auto-save mode is already enabled, auto-saves
 continue to go in the same file name until @code{auto-save-mode} is
 called again.
+
+Note that setting this variable to a non-@code{nil} value does not
+change the fact that auto-saving is different from saving the buffer;
+e.g., the hooks described in @ref{Saving Buffers} are @emph{not} run
+when a buffer is auto-saved.
 @end defopt
 
 @defun recent-auto-save-p
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 6f015e2d643..49cb150dc64 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -403,7 +403,11 @@ buffer name instead.
 @end deffn
 
   Saving a buffer runs several hooks.  It also performs format
-conversion (@pxref{Format Conversion}).
+conversion (@pxref{Format Conversion}).  Note that these hooks,
+described below, are only run by @code{save-buffer}, they are not run
+by other primitives and functions that write buffer text to files, and
+in particular auto-saving (@pxref{Auto-Saving}) doesn't run these
+hooks.
 
 @defvar write-file-functions
 The value of this variable is a list of functions to be called before
diff --git a/lisp/files.el b/lisp/files.el
index a6fe381a50a..83ef4e271cd 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -440,7 +440,8 @@ functions are called."
 
 (define-obsolete-variable-alias 'write-file-hooks 'write-file-functions "22.1")
 (defvar write-file-functions nil
-  "List of functions to be called before writing out a buffer to a file.
+  "List of functions to be called before saving a buffer to a file.
+Only used by `save-buffer'.
 If one of them returns non-nil, the file is considered already written
 and the rest are not called.
 These hooks are considered to pertain to the visited file.
@@ -465,6 +466,7 @@ updates before the buffer is saved, use `before-save-hook'.")
     'write-contents-functions "22.1")
 (defvar write-contents-functions nil
   "List of functions to be called before writing out a buffer to a file.
+Only used by `save-buffer'.
 If one of them returns non-nil, the file is considered already written
 and the rest are not called and neither are the functions in
 `write-file-functions'.
@@ -4721,13 +4723,15 @@ the last real save, but optional arg FORCE non-nil means delete anyway."
   "Normal hook run just before auto-saving.")
 
 (defcustom before-save-hook nil
-  "Normal hook that is run before a buffer is saved to its file."
+  "Normal hook that is run before a buffer is saved to its file.
+Only used by `save-buffer'."
   :options '(copyright-update time-stamp)
   :type 'hook
   :group 'files)
 
 (defcustom after-save-hook nil
-  "Normal hook that is run after a buffer is saved to its file."
+  "Normal hook that is run after a buffer is saved to its file.
+Only used by `save-buffer'."
   :options '(executable-make-buffer-file-executable-if-script-p)
   :type 'hook
   :group 'files)