16 files changed, 60 insertions, 51 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index f1a3cdb6235..90beb08233d 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,7 @@
+2012-10-23  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * custom.texi (Hooks): Clarify that -hooks is deprecated.
+
 2012-10-23  Chong Yidong  <cyd@gnu.org>
 
         * kmacro.texi (Edit Keyboard Macro): Fix typo.
diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 68219d7890f..a614126dbc0 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -838,7 +838,8 @@ is a normal hook.
 
 @cindex abnormal hook
   A few hooks are @dfn{abnormal hooks}.  Their names end in
-@samp{-hooks} or @samp{-functions}, instead of @samp{-hook}.  What
+@samp{-functions}, instead of @samp{-hook} (some old code may also use
+the deprecated suffix @samp{-hooks}).  What
 makes these hooks abnormal is the way its functions are
 called---perhaps they are given arguments, or perhaps the values they
 return are used in some way.  For example,
@@ -1735,11 +1736,11 @@ and @kbd{C-c p} in Texinfo mode:
 
 @example
 (add-hook 'texinfo-mode-hook
-          '(lambda ()
-             (define-key texinfo-mode-map "\C-cp"
-                         'backward-paragraph)
-             (define-key texinfo-mode-map "\C-cn"
-                         'forward-paragraph)))
+          (lambda ()
+            (define-key texinfo-mode-map "\C-cp"
+                        'backward-paragraph)
+            (define-key texinfo-mode-map "\C-cn"
+                        'forward-paragraph)))
 @end example
 
 @node Modifier Keys
diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi
index 55c3ef4e09e..70ddb81c776 100644
--- a/doc/lispintro/emacs-lisp-intro.texi
+++ b/doc/lispintro/emacs-lisp-intro.texi
@@ -17909,10 +17909,10 @@ file that set values:
 @group
 ;; Set calendar highlighting colors
 (setq calendar-load-hook
-      '(lambda ()
-         (set-face-foreground 'diary-face   "skyblue")
-         (set-face-background 'holiday-face "slate blue")
-         (set-face-foreground 'holiday-face "white")))
+      (lambda ()
+        (set-face-foreground 'diary-face   "skyblue")
+        (set-face-background 'holiday-face "slate blue")
+        (set-face-foreground 'holiday-face "white")))
 @end group
 @end smallexample
 
@@ -20947,7 +20947,7 @@ not yet seen, @code{mapcar} and @code{lambda}.
 @group
 (defun one-fiftieth (full-range)
   "Return list, each number one-fiftieth of previous."
- (mapcar '(lambda (arg) (/ arg 50)) full-range))
+ (mapcar (lambda (arg) (/ arg 50)) full-range))
 @end group
 @end smallexample
 
@@ -21168,7 +21168,7 @@ and the second argument is @code{full-range}, which will be bound to
 The whole expression looks like this:
 
 @smallexample
-(mapcar '(lambda (arg) (/ arg 50)) full-range))
+(mapcar (lambda (arg) (/ arg 50)) full-range))
 @end smallexample
 
 @xref{Mapping Functions, , Mapping Functions, elisp, The GNU Emacs
@@ -21840,7 +21840,7 @@ each column."
 @group
 (defun one-fiftieth (full-range)
   "Return list, each number of which is 1/50th previous."
- (mapcar '(lambda (arg) (/ arg 50)) full-range))
+ (mapcar (lambda (arg) (/ arg 50)) full-range))
 @end group
 @end smallexample
 
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index a767bbf1fce..26765e7a384 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,7 @@
+2012-10-23  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * hooks.texi (Standard Hooks): Clarify that -hooks is deprecated.
+
 2012-10-23  Paul Eggert  <eggert@cs.ucla.edu>
 
         Fix outdated timestamp documentation in Elisp manual (bug#12706).
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index c94e46dad18..623106b6d06 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -978,7 +978,7 @@ anonymous function by quoting it as a list:
 @example
 @group
 (defun double-property (symbol prop)
-  (change-property symbol prop '(lambda (x) (* 2 x))))
+  (change-property symbol prop (lambda (x) (* 2 x))))
 @end group
 @end example
 
diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi
index 7c91b51b290..a7f01243641 100644
--- a/doc/lispref/hooks.texi
+++ b/doc/lispref/hooks.texi
@@ -17,11 +17,11 @@ arguments and their values are completely ignored.  The recommended way
 to put a new function on such a hook is to call @code{add-hook}.
 @xref{Hooks}, for more information about using hooks.
 
-The variables whose names end in @samp{-hooks} or @samp{-functions} are
-usually @dfn{abnormal hooks}; their values are lists of functions, but
-these functions are called in a special way (they are passed arguments,
-or their values are used). The variables whose names end in
-@samp{-function} have single functions as their values.
+The variables whose names end in @samp{-functions} are usually @dfn{abnormal
+hooks} (some old code may also use the deprecated @samp{-hooks} suffix); their
+values are lists of functions, but these functions are called in a special way
+(they are passed arguments, or their return values are used).  The variables
+whose names end in @samp{-function} have single functions as their values.
 
 This is not an exhaustive list, it only covers the more general hooks.
 For example, every major mode defines a hook named
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index aa243185359..77a31cfde7a 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -897,8 +897,8 @@ It then restores any autoloads formerly associated with those symbols.
 
 Before restoring the previous definitions, @code{unload-feature} runs
 @code{remove-hook} to remove functions in the library from certain
-hooks.  These hooks include variables whose names end in @samp{hook}
-or @samp{-hooks}, plus those listed in
+hooks.  These hooks include variables whose names end in @samp{-hook}
+(or the deprecated suffix @samp{-hooks}), plus those listed in
 @code{unload-feature-special-hooks}, as well as
 @code{auto-mode-alist}.  This is to prevent Emacs from ceasing to
 function because important hooks refer to functions that are no longer
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 8b5e3da493a..4e4d700aade 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -70,9 +70,9 @@ called.  You can use @code{add-hook} to add a function to an abnormal
 hook, but you must write the function to follow the hook's calling
 convention.
 
-  By convention, abnormal hook names end in @samp{-functions} or
-@samp{-hooks}.  If the variable's name ends in @samp{-function}, then
-its value is just a single function, not a list of functions.
+  By convention, abnormal hook names end in @samp{-functions}.  If the
+variable's name ends in @samp{-function}, then its value is just a single
+function, not a list of functions.
 
 @menu
 * Running Hooks::    How to run a hook.
diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi
index 865e99a3aa6..1f9a401df90 100644
--- a/doc/misc/dbus.texi
+++ b/doc/misc/dbus.texi
@@ -1981,7 +1981,7 @@ usually not desired.  D-Bus errors in events can be made visible by
 setting the variable @code{dbus-debug} to @code{t}.  They can also be
 handled by a hook function.
 
-@defvar dbus-event-error-hooks
+@defvar dbus-event-error-functions
 This hook variable keeps a list of functions, which are called when a
 D-Bus error happens in the event handler.  Every function must accept
 two arguments, the event and the error variable caught in
@@ -1997,7 +1997,7 @@ Example:
     (message "my-dbus-event-error-handler: %S %S" event error)
     (signal 'file-error (cdr error))))
 
-(add-hook 'dbus-event-error-hooks 'my-dbus-event-error-handler)
+(add-hook 'dbus-event-error-functions 'my-dbus-event-error-handler)
 @end lisp
 @end defvar
 
diff --git a/doc/misc/ede.texi b/doc/misc/ede.texi
index 046cdc99414..1299f2ff062 100644
--- a/doc/misc/ede.texi
+++ b/doc/misc/ede.texi
@@ -1248,7 +1248,7 @@ detection scheme works like this:
 
 @table @asis
 @item Step 1:
-@code{find-file-hooks} calls @code{ede-turn-on-hook} on BUFFER.
+@code{find-file-hook} calls @code{ede-turn-on-hook} on BUFFER.
 @item Step 2:
 @code{ede-turn-on-hook} turns on @code{ede-minor-mode}
 @item Step 3:
diff --git a/doc/misc/ediff.texi b/doc/misc/ediff.texi
index 01349e31468..0afcdd923d6 100644
--- a/doc/misc/ediff.texi
+++ b/doc/misc/ediff.texi
@@ -1248,7 +1248,7 @@ This hook is run just before @code{ediff-quit-hook}.  This is a good
 place to do various cleanups, such as deleting the variant buffers.
 Ediff provides a function, @code{ediff-janitor}, as one such possible
 hook, which you can add to @code{ediff-cleanup-hook} with
-@code{add-hooks}.
+@code{add-hook}.
 
 @findex ediff-janitor
 This function kills buffers A, B, and, possibly, C, if these buffers aren't
diff --git a/doc/misc/forms.texi b/doc/misc/forms.texi
index bcb8d8974ea..11c3782dd7e 100644
--- a/doc/misc/forms.texi
+++ b/doc/misc/forms.texi
@@ -170,8 +170,8 @@ of the buffer are parsed using the specifications in
 @code{forms-format-list}, and the data file is updated.  If the record
 has fields that aren't included in the display, they are not changed.
 
-@vindex forms-mode-hooks
-Entering Forms mode runs the normal hook @code{forms-mode-hooks} to
+@vindex forms-mode-hook
+Entering Forms mode runs the normal hook @code{forms-mode-hook} to
 perform user-defined customization.
 
 To save any modified data, you can use @kbd{C-x C-s}
diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi
index afc324e3fb4..a9cd0d3567c 100644
--- a/doc/misc/gnus.texi
+++ b/doc/misc/gnus.texi
@@ -3148,7 +3148,7 @@ following is added to a group parameter
 
 @lisp
 (gnus-summary-prepared-hook
-  '(lambda nil (local-set-key "d" (local-key-binding "n"))))
+  (lambda nil (local-set-key "d" (local-key-binding "n"))))
 @end lisp
 
 when the group is entered, the 'd' key will not mark the article as
diff --git a/doc/misc/mh-e.texi b/doc/misc/mh-e.texi
index f6adc435789..e59b312889d 100644
--- a/doc/misc/mh-e.texi
+++ b/doc/misc/mh-e.texi
@@ -429,7 +429,7 @@ for a description about @dfn{normal hooks} and @dfn{abnormal hooks}.
 MH-E uses normal hooks in nearly all cases, so you can assume that we
 are talking about normal hooks unless we explicitly mention that a
 hook is abnormal. We also follow the conventions described in that
-section: the name of the abnormal hooks end in @code{-hooks} and all
+section: the name of the abnormal hooks end in @code{-functions} and all
 the rest of the MH-E hooks end in @code{-hook}. You can add hooks with
 either @code{customize-option} or @code{add-hook}.
 
@@ -3749,9 +3749,9 @@ when you press @key{TAB} when prompted for a folder name.
 
 @findex mh-search-p
 @kindex k
-@vindex mh-kill-folder-suppress-prompt-hooks
+@vindex mh-kill-folder-suppress-prompt-functions
 
-The hook @code{mh-kill-folder-suppress-prompt-hooks} is an abnormal
+The hook @code{mh-kill-folder-suppress-prompt-functions} is an abnormal
 hook run at the beginning of the command @kbd{k}. The hook functions
 are called with no arguments and should return a non-nil value to
 suppress the normal prompt when you remove a folder. This is useful
diff --git a/doc/misc/sem-user.texi b/doc/misc/sem-user.texi
index 9f4dc72fea3..9d6fb11db50 100644
--- a/doc/misc/sem-user.texi
+++ b/doc/misc/sem-user.texi
@@ -277,7 +277,7 @@ variable.  This allows SemanticDB to save tag caches in directories
 controlled by them.
 @end defvar
 
-@deffn Option semanticdb-save-database-hooks
+@deffn Option semanticdb-save-database-functions
 Abnormal hook run after a database is saved.  Each function is called
 with one argument, the object representing the database recently
 written.
diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi
index 530b8fdd6c2..46f99acbb87 100644
--- a/doc/misc/tramp.texi
+++ b/doc/misc/tramp.texi
@@ -3007,10 +3007,10 @@ checksum.
 
 @lisp
 (add-hook
- 'find-file-hooks
- '(lambda ()
-    (when (file-remote-p default-directory)
-      (set (make-local-variable 'file-precious-flag) t))))
+ 'find-file-hook
+ (lambda ()
+   (when (file-remote-p default-directory)
+     (set (make-local-variable 'file-precious-flag) t))))
 @end lisp
 @end itemize
 
@@ -3126,7 +3126,7 @@ into your @file{~/.emacs}:
     (setq mode-line-format
           (format-mode-line mode-line-format 'font-lock-warning-face))))
 
-(add-hook 'find-file-hooks 'my-mode-line-function)
+(add-hook 'find-file-hook 'my-mode-line-function)
 (add-hook 'dired-mode-hook 'my-mode-line-function)
 @end lisp
 @end ifset
@@ -3159,10 +3159,10 @@ should put it into your @file{~/.emacs}:
 
 (add-hook
  'dired-mode-hook
- '(lambda ()
-    (setq
-     mode-line-buffer-identification
-     my-mode-line-buffer-identification)))
+ (lambda ()
+   (setq
+    mode-line-buffer-identification
+    my-mode-line-buffer-identification)))
 @end lisp
 
 Since @value{emacsname} 23.1, the mode line contains an indication if
@@ -3195,9 +3195,9 @@ like this:
 @lisp
 (add-hook
  'dired-before-readin-hook
- '(lambda ()
-    (when (file-remote-p default-directory)
-      (setq dired-actual-switches "-al"))))
+ (lambda ()
+   (when (file-remote-p default-directory)
+     (setq dired-actual-switches "-al"))))
 @end lisp
 @end ifset
 
@@ -3329,9 +3329,9 @@ minibuffer:
 
 (add-hook
  'minibuffer-setup-hook
- '(lambda ()
-    (abbrev-mode 1)
-    (setq local-abbrev-table my-tramp-abbrev-table)))
+ (lambda ()
+   (abbrev-mode 1)
+   (setq local-abbrev-table my-tramp-abbrev-table)))
 
 (defadvice minibuffer-complete
   (before my-minibuffer-complete activate)
@@ -3398,7 +3398,7 @@ their readability through a remote access:
 @ifset xemacs
 (recent-files-initialize)
 (add-hook
- 'find-file-hooks
+ 'find-file-hook
  (lambda ()
    (when (file-remote-p (buffer-file-name))
      (recent-files-make-permanent)))