Checked lispref/hooks.texi

* doc/lispref/hooks.texi (Standard Hooks): General update.
Put related hooks together.

* doc/lispref/commands.texi (Keyboard Macros):
Remove cross-ref to Standard Hooks.

* doc/lispref/modes.texi (Hooks): Tweak cross-ref description.
Remove non-standard file-local fill-column (2010-05-13T03:55:46Z!rgm@gnu.org).

* admin/FOR-RELEASE: Related markup.

5 files changed, 163 insertions, 131 deletions

diff --git a/admin/FOR-RELEASE b/admin/FOR-RELEASE
index 563e1588e35..8e712f5fcf8 100644
--- a/admin/FOR-RELEASE
+++ b/admin/FOR-RELEASE
@@ -201,7 +201,7 @@ frames.texi
 functions.texi    cyd
 hash.texi         cyd
 help.texi         cyd
-hooks.texi        
+hooks.texi        rgm
 index.texi
 internals.texi    
 intro.texi        cyd
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 7e51c20dacb..85fea55c93f 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,10 @@
+2012-03-02  Glenn Morris  <rgm@gnu.org>
+
+        * hooks.texi (Standard Hooks): General update.
+        Put related hooks together.  Add and remove items.
+        * commands.texi (Keyboard Macros): Remove cross-ref to Standard Hooks.
+        * modes.texi (Hooks): Tweak cross-ref description.
+
 2012-03-01  Michael Albinus  <michael.albinus@gmx.de>
 
         * files.texi (Kinds of Files): The return value of file-equal-p is
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index f4e7c922331..617f050f498 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -1,7 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
-@c   Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/commands
 @node Command Loop, Keymaps, Minibuffers, Top
@@ -3430,7 +3429,7 @@ buffer-local.  @xref{Multiple Terminals}.
 @end defvar
 
 @defvar kbd-macro-termination-hook
-This normal hook (@pxref{Standard Hooks}) is run when a keyboard
-macro terminates, regardless of what caused it to terminate (reaching
-the macro end or an error which ended the macro prematurely).
+This normal hook is run when a keyboard macro terminates, regardless
+of what caused it to terminate (reaching the macro end or an error
+which ended the macro prematurely).
 @end defvar
diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi
index 95fc0365c07..0d29c25c8b1 100644
--- a/doc/lispref/hooks.texi
+++ b/doc/lispref/hooks.texi
@@ -8,7 +8,7 @@
 @cindex standard hooks
 @cindex hook variables, list of
 
-The following is a list of hook variables that let you provide
+The following is a list of some hook variables that let you provide
 functions to be called from within Emacs on suitable occasions.
 
 Most of these variables have names ending with @samp{-hook}.  They are
@@ -18,85 +18,92 @@ 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.
 
-Every major mode defines a mode hook named
-@samp{@var{modename}-mode-hook}.  The major mode command runs this
-normal hook with @code{run-mode-hooks} as the very last thing it does.
-@xref{Mode Hooks}.  Most minor modes have mode hooks too.  Mode hooks
-are omitted from the list below.
-
 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.
 
+This is not an exhaustive list, it only covers the more general hooks.
+For example, every major mode defines a hook named
+@samp{@var{modename}-mode-hook}.  The major mode command runs this
+normal hook with @code{run-mode-hooks} as the very last thing it does.
+@xref{Mode Hooks}.  Most minor modes have mode hooks too.
+
 A special feature allows you to specify expressions to evaluate if and
 when a file is loaded (@pxref{Hooks for Loading}).  That feature is
 not exactly a hook, but does a similar job.
 
-@c We need to xref to where each hook is documented or else document
-@c it here.
+@c We need to xref to where each hook is documented or else document it here.
+@c Add vindex for anything not indexed elsewhere.
+@c This list is in alphabetical order, grouped by topic.
+@c TODO It should probably be more thoroughly ordered by topic.
 
 @table @code
-@item abbrev-expand-functions
-@xref{Abbrev Expansion}.
-
 @item activate-mark-hook
+@itemx deactivate-mark-hook
 @xref{The Mark}.
 
 @item after-change-functions
+@itemx before-change-functions
+@itemx first-change-hook
 @xref{Change Hooks}.
 
 @item after-change-major-mode-hook
+@itemx change-major-mode-after-body-hook
 @xref{Mode Hooks}.
 
 @item after-init-hook
+@itemx before-init-hook
+@itemx emacs-startup-hook
 @xref{Init File}.
 
 @item after-insert-file-functions
+@itemx write-region-annotate-functions
+@itemx write-region-post-annotation-function
 @xref{Format Conversion}.
 
 @item after-make-frame-functions
+@itemx before-make-frame-hook
 @xref{Creating Frames}.
 
+@c Not general enough?
+@ignore
 @item after-revert-hook
+@itemx before-revert-hook
+@itemx buffer-stale-function
+@itemx revert-buffer-function
+@itemx revert-buffer-insert-file-contents-function
 @xref{Reverting}.
+@end ignore
 
 @item after-save-hook
+@itemx before-save-hook
+@itemx write-contents-functions
+@itemx write-file-functions
 @xref{Saving Buffers}.
 
-@item auto-fill-function
-@xref{Auto Filling}.
+@item after-setting-font-hook
+@vindex after-setting-font-hook
+Hook run after a frame's font changes.
 
 @item auto-save-hook
 @xref{Auto-Saving}.
 
-@item before-change-functions
-@xref{Change Hooks}.
-
 @item before-hack-local-variables-hook
+@itemx hack-local-variables-hook
 @xref{File Local Variables}.
 
-@item before-init-hook
-@xref{Init File}.
-
-@item before-make-frame-hook
-@xref{Creating Frames}.
-
-@item before-revert-hook
-@xref{Reverting}.
-
-@item before-save-hook
-@xref{Saving Buffers}.
-
-@item blink-paren-function
-@xref{Blinking}.
-
 @item buffer-access-fontify-functions
 @xref{Lazy Properties}.
 
-@item change-major-mode-after-body-hook
-@xref{Mode Hooks}.
+@item buffer-list-update-hook
+@vindex buffer-list-update-hook
+Hook run when the buffer list changes.
+
+@item buffer-quit-function
+@vindex buffer-quit-function
+Function to call to ``quit'' the current buffer.
 
 @item change-major-mode-hook
 @xref{Creating Buffer-Local}.
@@ -104,151 +111,175 @@ not exactly a hook, but does a similar job.
 @item command-line-functions
 @xref{Command-Line Arguments}.
 
-@item comment-indent-function
-@xref{Options for Comments,, Options Controlling Comments, emacs, the
-GNU Emacs Manual}.
-
-@item compilation-finish-functions
-Functions to call when a compilation process finishes.
-
-@item custom-define-hook
-Hook called after defining each customize option.
-
-@item deactivate-mark-hook
-@xref{The Mark}.
+@item delayed-warnings-hook
+@vindex delayed-warnings-hook
+The command loop runs this soon after @code{post-command-hook} (q.v.).
 
 @item delete-frame-functions
-Functions to call when Emacs deletes a frame.  @xref{Deleting Frames}.
+@xref{Deleting Frames}.
 
 @item delete-terminal-functions
-Functions to call when Emacs deletes a terminal.  @xref{Multiple Terminals}.
+@xref{Multiple Terminals}.
 
+@ignore
 @item disabled-command-function
 @xref{Disabling Commands}.
+@end ignore
+
+@item display-buffer-function
+@itemx pop-up-frame-function
+@itemx special-display-function
+@itemx split-window-preferred-function
+@xref{Choosing Window Options}.
 
 @item echo-area-clear-hook
 @xref{Echo Area Customization}.
 
-@item emacs-startup-hook
-@xref{Init File}.
-
 @item find-file-hook
+@itemx find-file-not-found-functions
 @xref{Visiting Functions}.
 
-@item find-file-not-found-functions
-@xref{Visiting Functions}.
-
-@item first-change-hook
-@xref{Change Hooks}.
+@item font-lock-extend-after-change-region-function
+@xref{Region to Refontify}.
 
-@item font-lock-beginning-of-syntax-function
-@xref{Syntactic Font Lock}.
+@item font-lock-extend-region-functions
+@xref{Multiline Font Lock}.
 
 @item font-lock-fontify-buffer-function
+@itemx font-lock-fontify-region-function
+@itemx font-lock-mark-block-function
+@itemx font-lock-unfontify-buffer-function
+@itemx font-lock-unfontify-region-function
 @xref{Other Font Lock Variables}.
 
-@item font-lock-fontify-region-function
-@xref{Other Font Lock Variables}.
-
-@item font-lock-mark-block-function
-@xref{Other Font Lock Variables}.
+@item fontification-functions
+@xref{Auto Faces,, Automatic Face Assignment}.
 
-@item font-lock-syntactic-face-function
-@xref{Syntactic Font Lock}.
-
-@item font-lock-unfontify-buffer-function
-@xref{Other Font Lock Variables}.
-
-@item hack-local-variables-hook
-@xref{File Local Variables}.
-
-@item font-lock-unfontify-region-function
-@xref{Other Font Lock Variables}.
-
-@item kbd-macro-termination-hook
-@xref{Keyboard Macros}.
+@item frame-auto-hide-function
+@xref{Quitting Windows}.
 
 @item kill-buffer-hook
-@xref{Killing Buffers}.
-
-@item kill-buffer-query-functions
+@itemx kill-buffer-query-functions
 @xref{Killing Buffers}.
 
 @item kill-emacs-hook
+@itemx kill-emacs-query-functions
 @xref{Killing Emacs}.
 
-@item kill-emacs-query-functions
-@xref{Killing Emacs}.
-
-@item mail-setup-hook
-@xref{Mail Misc,, Mail Miscellany, emacs, the GNU Emacs Manual}.
-
 @item menu-bar-update-hook
 @xref{Menu Bar}.
 
 @item minibuffer-setup-hook
+@itemx minibuffer-exit-hook
 @xref{Minibuffer Misc}.
 
-@item minibuffer-exit-hook
-@xref{Minibuffer Misc}.
+@item mouse-leave-buffer-hook
+@vindex mouse-leave-buffer-hook
+Hook run when about to switch windows with a mouse command.
 
 @item mouse-position-function
 @xref{Mouse Position}.
 
 @item post-command-hook
+@itemx pre-command-hook
 @xref{Command Overview}.
 
+@item post-gc-hook
+@xref{Garbage Collection}.
+
 @item post-self-insert-hook
 @xref{Keymaps and Minor Modes}.
 
-@item pre-command-hook
-@xref{Command Overview}.
-
+@ignore
 @item prog-mode-hook
+@itemx special-mode-hook
+@vindex special-mode-hook
 @xref{Basic Major Modes}.
-
-@item resume-tty-functions
-@xref{Suspending Emacs}.
+@end ignore
 
 @item suspend-hook
+@itemx suspend-resume-hook
+@itemx suspend-tty-functions
+@itemx resume-tty-functions
 @xref{Suspending Emacs}.
 
-@item suspend-resume-hook
-@xref{Suspending Emacs}.
-
-@item suspend-tty-functions
-@xref{Suspending Emacs}.
+@item syntax-begin-function
+@itemx syntax-propertize-extend-region-functions
+@itemx syntax-propertize-function
+@itemx font-lock-syntactic-face-function
+@xref{Syntactic Font Lock}.  @xref{Syntax Properties}.
 
 @item temp-buffer-setup-hook
-@xref{Temporary Displays}.
-
-@item temp-buffer-show-function
-@xref{Temporary Displays}.
-
-@item temp-buffer-show-hook
+@itemx temp-buffer-show-function
+@itemx temp-buffer-show-hook
 @xref{Temporary Displays}.
 
 @item term-setup-hook
 @xref{Terminal-Specific}.
 
 @item window-configuration-change-hook
-@xref{Window Hooks}.
-
-@item window-scroll-functions
+@itemx window-scroll-functions
+@itemx window-size-change-functions
 @xref{Window Hooks}.
 
 @item window-setup-hook
 @xref{Window Systems}.
 
-@item window-size-change-functions
-@xref{Window Hooks}.
-
-@item write-contents-functions
-@xref{Saving Buffers}.
-
-@item write-file-functions
-@xref{Saving Buffers}.
+@item window-text-change-functions
+@vindex window-text-change-functions
+Functions to call in redisplay when text in the window might change.
 
-@item write-region-annotate-functions
-@xref{Format Conversion}.
 @end table
+
+@ignore
+Some -hook, -function, -functions from preloaded Lisp or C files that
+I thought did not need to be mentioned here:
+
+Lisp:
+after-load-functions
+auto-coding-functions
+choose-completion-string-functions
+completing-read-function
+completion-annotate-function
+completion-at-point-functions
+completion-in-region-functions
+completion-list-insert-choice-function
+describe-current-input-method-function
+filter-buffer-substring-functions
+font-lock-function
+inactivate-current-input-method-function
+menu-bar-select-buffer-function
+read-file-name-function
+replace-re-search-function
+replace-search-function
+yank-undo-function
+
+C hooks:
+kbd-macro-termination-hook
+signal-hook-function
+
+C functions:
+redisplay-end-trigger-functions
+x-lost-selection-functions
+x-sent-selection-functions
+
+C function:
+auto-composition-function
+auto-fill-function
+command-error-function
+compose-chars-after-function
+composition-function-table
+deferred-action-function
+input-method-function
+load-read-function
+load-source-file-function
+macro-declaration-function
+read-buffer-function
+ring-bell-function
+select-safe-coding-system-function
+set-auto-coding-function
+show-help-function
+signal-hook-function
+undo-outer-limit-function
+
+@end ignore
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index eac895b6279..b0e9d4a3139 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012  Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/modes
 @node Modes, Documentation, Keymaps, Top
@@ -38,7 +38,7 @@ user.  For related topics such as keymaps and syntax tables, see
 to be called on a particular occasion by an existing program.  Emacs
 provides hooks for the sake of customization.  Most often, hooks are set
 up in the init file (@pxref{Init File}), but Lisp programs can set them also.
-@xref{Standard Hooks}, for a list of standard hook variables.
+@xref{Standard Hooks}, for a list of some standard hook variables.
 
 @cindex normal hook
   Most of the hooks in Emacs are @dfn{normal hooks}.  These variables
@@ -4030,8 +4030,3 @@ Here @var{desktop-buffer-misc} is the value returned by the function
 optionally bound to @code{desktop-save-buffer}.
 @end defvar
 
-@ignore
-   Local Variables:
-   fill-column: 72
-   End:
-@end ignore