master e135414: Replace doc references to load-hooks

[Glenn Morris]

branch: master
commit e135414b271e71c16e28efc2e3f29b803ab67424
Author: Glenn Morris <address@hidden>
Commit: Glenn Morris <address@hidden>

    Replace doc references to load-hooks
    
    with-eval-after-load is a cleaner, standard feature that works
    for every file
    * doc/misc/calc.texi (Hooks):
    * doc/misc/dired-x.texi (Installation)
    (Optional Installation File At Point, Omitting Files in Dired)
    (Omitting Examples, Find File At Point):
    * doc/misc/ediff.texi (Hooks, Selective Browsing)
    (Highlighting Difference Regions):
    * doc/misc/efaq.texi (Disabling backups):
    * doc/misc/gnus.texi (Startup Variables):
    * doc/misc/idlwave.texi (Structure Tag Completion, Misc Options):
    * doc/misc/org.texi (Handling Links):
    * doc/misc/reftex.texi (Key Bindings, Keymaps and Hooks):
    * doc/misc/sem-user.texi (Speedbar):
    * doc/misc/speedbar.texi (Hooks, Minor Display Modes):
    * doc/misc/viper.texi (Rudimentary Changes):
    Replace load-hooks with with-eval-after-load
---
 doc/misc/calc.texi     | 11 +----------
 doc/misc/dired-x.texi  | 41 +++++++++++++++++++----------------------
 doc/misc/ediff.texi    | 37 ++++++++++++++-----------------------
 doc/misc/efaq.texi     |  5 ++---
 doc/misc/gnus.texi     |  6 ------
 doc/misc/idlwave.texi  |  8 ++------
 doc/misc/org.texi      |  7 +++----
 doc/misc/reftex.texi   |  9 ++-------
 doc/misc/sem-user.texi |  2 +-
 doc/misc/speedbar.texi | 10 +++-------
 doc/misc/viper.texi    |  9 +++------
 11 files changed, 50 insertions(+), 95 deletions(-)

diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi
index a89a92d..a31f232 100644
--- a/doc/misc/calc.texi
+++ b/doc/misc/calc.texi
@@ -35164,16 +35164,7 @@ which are called at various times.  Calc defines a 
number of hooks
 that help you to customize it in various ways.  Calc uses the Lisp
 function @code{run-hooks} to invoke the hooks shown below.  Several
 other customization-related variables are also described here.
-
-@defvar calc-load-hook
-This hook is called at the end of @file{calc.el}, after the file has
-been loaded, before any functions in it have been called, but after
-@code{calc-mode-map} and similar variables have been set up.
-@end defvar
-
-@defvar calc-ext-load-hook
-This hook is called at the end of @file{calc-ext.el}.
-@end defvar
+To run code after Calc has loaded, use @code{with-eval-after-load}.
 
 @defvar calc-start-hook
 This hook is called as the last step in a @kbd{M-x calc} command.
diff --git a/doc/misc/dired-x.texi b/doc/misc/dired-x.texi
index 5965da1..d749780 100644
--- a/doc/misc/dired-x.texi
+++ b/doc/misc/dired-x.texi
@@ -185,13 +185,12 @@ In your @file{~/.emacs} file, or in the system-wide 
initialization file
 @file{default.el} in the @file{site-lisp} directory, put
 
 @example
-(add-hook 'dired-load-hook
-          (lambda ()
-            (load "dired-x")
-            ;; Set dired-x global variables here.  For example:
-            ;; (setq dired-guess-shell-gnutar "gtar")
-            ;; (setq dired-x-hands-off-my-keys nil)
-            ))
+(with-eval-after-load 'dired
+  (require 'dired-x)
+  ;; Set dired-x global variables here.  For example:
+  ;; (setq dired-guess-shell-gnutar "gtar")
+  ;; (setq dired-x-hands-off-my-keys nil)
+  ))
 (add-hook 'dired-mode-hook
           (lambda ()
             ;; Set dired-x buffer-local variables here.  For example:
@@ -242,12 +241,10 @@ If you choose to have @file{dired-x.el} bind 
@code{dired-x-find-file} over
 or call @code{dired-x-bind-find-file} after changing the value.
 
 @example
-(add-hook 'dired-load-hook
-          (lambda ()
-            ;; Bind dired-x-find-file.
-            (setq dired-x-hands-off-my-keys nil)
-            (load "dired-x")
-            ))
+(with-eval-after-load 'dired
+  ;; Bind dired-x-find-file.
+  (setq dired-x-hands-off-my-keys nil)
+  (require 'dired-x))
 @end example
 
 @node Omitting Files in Dired
@@ -294,8 +291,8 @@ Marked files are never omitted.
 @end table
 
 @noindent
-In order to make Dired Omit work you first need to load @file{dired-x.el}
-inside @code{dired-load-hook} (@pxref{Installation}) and then evaluate
+In order to make Dired Omit work you need to load @file{dired-x}
+after loading @file{dired} (@pxref{Installation}) and then evaluate
 @code{(dired-omit-mode 1)} in some way (@pxref{Omitting Variables}).
 
 @ifnottex
@@ -410,7 +407,7 @@ The default value is @kbd{C-o}.
 @item
 @cindex RCS files, how to omit them in Dired
 @cindex omitting RCS files in Dired
-If you wish to avoid seeing RCS files and the @file{RCS} directory, then put
+If you wish to avoid seeing RCS files and the @file{RCS} directory, then use
 
 @example
 (setq dired-omit-files
@@ -418,7 +415,7 @@ If you wish to avoid seeing RCS files and the @file{RCS} 
directory, then put
 @end example
 
 @noindent
-in the @code{dired-load-hook} (@pxref{Installation}).  This assumes
+after loading @file{dired-x} (@pxref{Installation}).  This assumes
 @code{dired-omit-localp} has its default value of @code{no-dir} to make the
 @code{^}-anchored matches work.  As a slower alternative, with
 @code{dired-omit-localp} set to @code{nil}, you can use @code{/} instead of
@@ -429,7 +426,7 @@ in the @code{dired-load-hook} (@pxref{Installation}).  This 
assumes
 @cindex omitting tib files in Dired
 If you use @code{tib}, the bibliography program for use with @TeX{} and
 @LaTeX{}, and you
-want to omit the @file{INDEX} and the @file{*-t.tex} files, then put
+want to omit the @file{INDEX} and the @file{*-t.tex} files, then use
 
 @example
 (setq dired-omit-files
@@ -437,13 +434,13 @@ want to omit the @file{INDEX} and the @file{*-t.tex} 
files, then put
 @end example
 
 @noindent
-in the @code{dired-load-hook} (@pxref{Installation}).
+after loading @file{dired-x} (@pxref{Installation}).
 
 @item
 @cindex dot files, how to omit them in Dired
 @cindex omitting dot files in Dired
 If you do not wish to see @samp{dot} files (files starting with a @file{.}),
-then put
+then use
 
 @example
 (setq dired-omit-files
@@ -451,7 +448,7 @@ then put
 @end example
 
 @noindent
-in the @code{dired-load-hook} (@pxref{Installation}).  (Of course, a
+after loading @file{dired-x} (@pxref{Installation}).  (Of course, a
 better way to achieve this particular goal is simply to omit @samp{-a} from
 @code{dired-listing-switches}.)
 
@@ -830,7 +827,7 @@ When installed @file{dired-x} will substitute 
@code{dired-x-find-file} for
 (normally bound to @kbd{C-x 4 C-f}).
 
 In order to use this feature, you will need to set
-@code{dired-x-hands-off-my-keys} to @code{nil} inside @code{dired-load-hook}
+@code{dired-x-hands-off-my-keys} to @code{nil} before loading @file{dired-x}
 (@pxref{Optional Installation File At Point}).
 
 @table @code
diff --git a/doc/misc/ediff.texi b/doc/misc/ediff.texi
index 99ba89b..1ef1371 100644
--- a/doc/misc/ediff.texi
+++ b/doc/misc/ediff.texi
@@ -1197,10 +1197,6 @@ refer to Emacs manual for the information on how to set 
Emacs X resources.
 The bulk of customization can be done via the following hooks:
 
 @table @code
-@item ediff-load-hook
-@vindex ediff-load-hook
-This hook can be used to change defaults after Ediff is loaded.
-
 @item ediff-before-setup-hook
 @vindex ediff-before-setup-hook
 Hook that is run just before Ediff rearranges windows to its liking.
@@ -1211,8 +1207,8 @@ Can be used to save windows configuration.
 @vindex ediff-mode-map
 This hook can be used to alter bindings in Ediff's keymap,
 @code{ediff-mode-map}.  These hooks are
-run right after the default bindings are set but before
-@code{ediff-load-hook}.  The regular user needs not be concerned with this
+run right after the default bindings are set.
+The regular user needs not be concerned with this
 hook---it is provided for implementers of other Emacs packages built on top
 of Ediff.
 
@@ -1545,12 +1541,13 @@ directly (using @kbd{j})  to any numbered
 difference.
 
 Users can supply their own functions to specify how Ediff should do
-selective browsing.  To change the default Ediff function, add a function to
-@code{ediff-load-hook} which will do the following assignments:
+selective browsing.  To change the default Ediff function, use
+something like the following:
 
 @example
-(setq ediff-hide-regexp-matches-function 'your-hide-function)
-(setq ediff-focus-on-regexp-matches-function 'your-focus-function)
+(with-eval-after-load 'ediff
+  (setq ediff-hide-regexp-matches-function 'your-hide-function)
+  (setq ediff-focus-on-regexp-matches-function 'your-focus-function))
 @end example
 
 @strong{Useful hint}: To specify a regexp that matches everything, don't
@@ -1728,23 +1725,17 @@ difference region in buffer A (this face is not a good 
choice, by the way).
 
 If you are unhappy with just @emph{some} of the aspects of the default
 faces, you can modify them when Ediff is being loaded using
-@code{ediff-load-hook}.  For instance:
+@code{with-eval-after-load}.  For instance:
 
 @smallexample
-(add-hook 'ediff-load-hook
-          (lambda ()
-            (set-face-foreground
-              ediff-current-diff-face-B "blue")
-            (set-face-background
-              ediff-current-diff-face-B "red")
-            (make-face-italic
-              ediff-current-diff-face-B)))
+(with-eval-after-load 'ediff
+  (set-face-foreground
+    ediff-current-diff-face-B "blue")
+  (set-face-background
+    ediff-current-diff-face-B "red")
+  (make-face-italic ediff-current-diff-face-B))
 @end smallexample
 
-@strong{Please note:} to set Ediff's faces, use only @code{copy-face}
-or @code{set/make-face-@dots{}} as shown above. Emacs's low-level
-face-manipulation functions should be avoided.
-
 @node Narrowing
 @section Narrowing
 
diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi
index dcb0a68..06c39a5 100644
--- a/doc/misc/efaq.texi
+++ b/doc/misc/efaq.texi
@@ -2533,9 +2533,8 @@ To avoid seeing backup files (and other ``uninteresting'' 
files) in Dired,
 load @code{dired-x} by adding the following to your @file{.emacs} file:
 
 @lisp
-(add-hook 'dired-load-hook
-          (lambda ()
-           (require 'dired-x)))
+(with-eval-after-load 'dired
+  (require 'dired-x))
 @end lisp
 
 With @code{dired-x} loaded, @kbd{M-o} toggles omitting in each dired buffer.
diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi
index 5ec1f02..2545d21 100644
--- a/doc/misc/gnus.texi
+++ b/doc/misc/gnus.texi
@@ -1563,12 +1563,6 @@ secondary select methods.
 
 @table @code
 
-@item gnus-load-hook
-@vindex gnus-load-hook
-A hook run while Gnus is being loaded.  Note that this hook will
-normally be run just once in each Emacs session, no matter how many
-times you start Gnus.
-
 @item gnus-before-startup-hook
 @vindex gnus-before-startup-hook
 A hook called as the first thing when Gnus is started.
diff --git a/doc/misc/idlwave.texi b/doc/misc/idlwave.texi
index 547b166..5cb6b19 100644
--- a/doc/misc/idlwave.texi
+++ b/doc/misc/idlwave.texi
@@ -1805,8 +1805,8 @@ Structure tag completion is not enabled by default.  To 
enable it,
 simply add the following to your @file{.emacs}:
 
 @lisp
-   (add-hook 'idlwave-load-hook
-             (lambda () (require 'idlw-complete-structtag)))
+(with-eval-after-load 'idlwave
+  (require 'idlw-complete-structtag))
 @end lisp
 
 Once enabled, you'll also be able to access online help on the structure
@@ -2360,10 +2360,6 @@ is first called.
 Normal hook.  Executed when a buffer is put into @code{idlwave-mode}.
 @end defopt
 
-@defopt idlwave-load-hook
-Normal hook.  Executed when @file{idlwave.el} is loaded.
-@end defopt
-
 @node The IDLWAVE Shell
 @chapter The IDLWAVE Shell
 @cindex IDLWAVE shell
diff --git a/doc/misc/org.texi b/doc/misc/org.texi
index 0de91fa..8979796 100644
--- a/doc/misc/org.texi
+++ b/doc/misc/org.texi
@@ -3979,10 +3979,9 @@ key bindings for this are really too long; you might 
want to bind
 this also to @kbd{M-n} and @kbd{M-p}.
 
 @lisp
-(add-hook 'org-load-hook
-          (lambda ()
-            (define-key org-mode-map "\M-n" 'org-next-link)
-            (define-key org-mode-map "\M-p" 'org-previous-link)))
+(with-eval-after-load 'org
+  (define-key org-mode-map "\M-n" 'org-next-link)
+  (define-key org-mode-map "\M-p" 'org-previous-link))
 @end lisp
 @end table
 
diff --git a/doc/misc/reftex.texi b/doc/misc/reftex.texi
index 013c563..0dab524 100644
--- a/doc/misc/reftex.texi
+++ b/doc/misc/reftex.texi
@@ -2896,9 +2896,8 @@ default.  If you want to have these key bindings 
available, set in your
 Note that this variable has to be set before @RefTeX{} is loaded to
 have an effect.
 
-@vindex reftex-load-hook
-Changing and adding to @RefTeX{}'s key bindings is best done in the hook
-@code{reftex-load-hook}.  For information on the keymaps
+Changing and adding to @RefTeX{}'s key bindings is best done using
+@code{with-eval-after-load}.  For information on the keymaps
 which should be used to add keys, see @ref{Keymaps and Hooks}.
 
 @node Faces
@@ -5320,10 +5319,6 @@ argument.
 The keymap for @RefTeX{} mode.
 @end deffn
 
-@deffn {Normal Hook} reftex-load-hook
-Normal hook which is being run when loading @file{reftex.el}.
-@end deffn
-
 @deffn {Normal Hook} reftex-mode-hook
 Normal hook which is being run when turning on @RefTeX{} mode.
 @end deffn
diff --git a/doc/misc/sem-user.texi b/doc/misc/sem-user.texi
index c02887d..d151cee 100644
--- a/doc/misc/sem-user.texi
+++ b/doc/misc/sem-user.texi
@@ -1068,7 +1068,7 @@ You can integrate @semantic{} with the Speedbar.
 line to your init file:
 
 @example
-(add-hook 'speedbar-load-hook (lambda () (require 'semantic/sb)))
+(with-eval-after-load 'speedbar (require 'semantic/sb))
 @end example
 
 @noindent
diff --git a/doc/misc/speedbar.texi b/doc/misc/speedbar.texi
index 57ad022..c9c3daf 100644
--- a/doc/misc/speedbar.texi
+++ b/doc/misc/speedbar.texi
@@ -828,9 +828,6 @@ Hooks run when speedbar visits a file in the selected frame.
 @cindex @code{speedbar-visiting-tag-hook}
 @item speedbar-visiting-tag-hook
 Hooks run when speedbar visits a tag in the selected frame.
-@cindex @code{speedbar-load-hook}
-@item speedbar-load-hook
-Hooks run when speedbar is loaded.
 @cindex @code{speedbar-reconfigure-keymaps-hook}
 @item speedbar-reconfigure-keymaps-hook
 Hooks run when the keymaps are regenerated.  Keymaps are reconfigured
@@ -913,12 +910,11 @@ bindings:
 This function creates a special keymap for use in speedbar.
 
 @item
-Call your install function, or assign it to a hook like this:
+Call your install function, like this:
 
 @smallexample
-(if (featurep 'speedbar)
-    (@var{name}-install-speedbar-variables)
-  (add-hook 'speedbar-load-hook '@var{name}-install-speedbar-variables))
+(with-eval-after-load 'speedbar
+  (@var{name}-install-speedbar-variables))
 @end smallexample
 
 @item
diff --git a/doc/misc/viper.texi b/doc/misc/viper.texi
index 9ce809e..661eb7c 100644
--- a/doc/misc/viper.texi
+++ b/doc/misc/viper.texi
@@ -1752,10 +1752,10 @@ state.  If @code{nil}, the cursor stays where it was 
before the switch.
 @item viper-always t
 @code{t} means: leave it to Viper to decide when a buffer must be brought
 up in Vi state,
-Insert state, or Emacs state.  This heuristics works well in virtually all
-cases.  @code{nil} means you either has to invoke @code{viper-mode} manually
+Insert state, or Emacs state.  This heuristic works well in virtually all
+cases.  @code{nil} means you either have to invoke @code{viper-mode} manually
 for each buffer (or you can add @code{viper-mode} to the appropriate major mode
-hooks using @code{viper-load-hook}).
+hooks using @code{with-eval-after-load}).
 
 This option must be set in your Viper customization file.
 @item viper-custom-file-name "~/.emacs.d/viper"
@@ -1903,9 +1903,6 @@ List of (parameterless) functions called just after 
entering Replace state
 @item viper-emacs-state-hook nil
 List of (parameterless) functions called just after switching from Vi state
 to Emacs state.
-@item viper-load-hook nil
-List of (parameterless) functions called just after loading Viper.  This is
-the last chance to do customization before Viper is up and running.
 @end table
 @noindent
 You can reset some of these constants in Viper with the Ex command @kbd{:set}