Document prog-mode-hook in Emacs manual.

* custom.texi (Hooks): Reorganize.  Mention Prog mode.

* fixit.texi (Spelling): Mention using prog-mode-hook for flypsell
prog mode (Bug#8240).

3 files changed, 57 insertions, 47 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index d2f2c23ee3d..89a78263e94 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,10 @@
+2011-05-28  Chong Yidong  <cyd@stupidchicken.com>
+
+        * custom.texi (Hooks): Reorganize.  Mention Prog mode.
+
+        * fixit.texi (Spelling): Mention using prog-mode-hook for flypsell
+        prog mode (Bug#8240).
+
 2011-05-27  Glenn Morris  <rgm@gnu.org>
 
         * custom.texi (Specifying File Variables):
diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 9add95a5b48..a0dce5b3216 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -888,53 +888,48 @@ your initialization file to set it those sessions (@pxref{Init File}).
 hook is a Lisp variable which holds a list of functions, to be called
 on some well-defined occasion.  (This is called @dfn{running the
 hook}.)  The individual functions in the list are called the @dfn{hook
-functions} of the hook.  With rare exceptions, hooks in Emacs are
-empty when Emacs starts up, so the only hook functions in any given
-hook are the ones you explicitly put there as customization.
-
-  Most major modes run one or more @dfn{mode hooks} as the last step
-of initialization.  This makes it easy for you to customize the
-behavior of the mode, by setting up a hook function to override the
-local variable assignments already made by the mode.  But hooks are
-also used in other contexts.  For example, the hook
-@code{kill-emacs-hook} runs just before quitting the Emacs job
-(@pxref{Exiting}).
+functions} of the hook.  For example, the hook @code{kill-emacs-hook}
+runs just before exiting Emacs (@pxref{Exiting}).
 
 @cindex normal hook
-  Most Emacs hooks are @dfn{normal hooks}.  This means that running the
-hook operates by calling all the hook functions, unconditionally, with
-no arguments.  We have made an effort to keep most hooks normal so that
-you can use them in a uniform way.  Every variable in Emacs whose name
-ends in @samp{-hook} is a normal hook.
+  Most hooks are @dfn{normal hooks}.  This means that when Emacs runs
+the hook, it calls each hook function in turn, with no arguments.  We
+have made an effort to keep most hooks normal, so that you can use
+them in a uniform way.  Every variable whose name ends in @samp{-hook}
+is a normal hook.
 
 @cindex abnormal hook
-  There are also a few @dfn{abnormal hooks}.  These variables' names end
-in @samp{-hooks} or @samp{-functions}, instead of @samp{-hook}.  What
-makes these hooks abnormal is that there is something peculiar about the
-way its functions are called---perhaps they are given arguments, or
-perhaps the values they return are used in some way.  For example,
-@code{find-file-not-found-functions} (@pxref{Visiting}) is abnormal because
-as soon as one hook function returns a non-@code{nil} value, the rest
-are not called at all.  The documentation of each abnormal hook variable
-explains in detail what is peculiar about it.
+  A few hooks are @dfn{abnormal hooks}.  Their names end in
+@samp{-hooks} or @samp{-functions}, instead of @samp{-hook}.  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,
+@code{find-file-not-found-functions} is abnormal because as soon as
+one hook function returns a non-@code{nil} value, the rest are not
+called at all (@pxref{Visiting}).  The documentation of each abnormal
+hook variable explains how its functions are used.
 
 @findex add-hook
   You can set a hook variable with @code{setq} like any other Lisp
-variable, but the recommended way to add a hook function to a hook
-(either normal or abnormal) is by calling @code{add-hook}.
-@xref{Hooks,,, elisp, The Emacs Lisp Reference Manual}.
+variable, but the recommended way to add a function to a hook (either
+normal or abnormal) is to use @code{add-hook}, as shown by the
+following examples.  @xref{Hooks,,, elisp, The Emacs Lisp Reference
+Manual}, for details.
 
-  For example, here's how to set up a hook to turn on Auto Fill mode
-when entering Text mode and other modes based on Text mode:
+  Most major modes run one or more @dfn{mode hooks} as the last step
+of initialization.  Mode hooks are a convenient way to customize the
+behavior of individual modes; they are always normal.  For example,
+here's how to set up a hook to turn on Auto Fill mode when entering
+Text mode and other modes based on Text mode:
 
 @example
 (add-hook 'text-mode-hook 'turn-on-auto-fill)
 @end example
 
-  The next example shows how to use a hook to customize the indentation
-of C code.  (People often have strong personal preferences for one
-format compared to another.)  Here the hook function is an anonymous
-lambda expression.
+  Here is another example, showing how to use a hook to customize the
+indentation of C code.  The hook function uses an anonymous lambda
+expression (@pxref{Lambda Expressions,,, elisp, The Emacs Lisp
+Reference Manual}).
 
 @example
 @group
@@ -944,24 +939,32 @@ lambda expression.
 @group
     (c-cleanup-list . (scope-operator
                        empty-defun-braces
-                       defun-close-semi))
-@end group
-@group
-    (c-offsets-alist . ((arglist-close . c-lineup-arglist)
-                        (substatement-open . 0)))))
+                       defun-close-semi))))
 @end group
 
 @group
 (add-hook 'c-mode-common-hook
-  '(lambda ()
-     (c-add-style "my-style" my-c-style t)))
+  (lambda () (c-add-style "my-style" my-c-style t)))
 @end group
 @end example
 
+@cindex Prog mode
+@cindex program editing
+  Major mode hooks also apply to other major modes @dfn{derived} from
+the original mode (@pxref{Derived Modes,,, elisp, The Emacs Lisp
+Reference Manual}).  For instance, HTML mode (@pxref{HTML Mode})
+inherits from Text mode; when HTML mode is enabled, it runs
+@code{text-mode-hook} before running @code{html-mode-hook}.  This
+provides a convenient way to use a single hook to affect several
+related modes.  In particular, if you want to apply a hook function to
+any programming language mode, add it to @code{prog-mode-hook}; Prog
+mode is a major mode that does little else than to let other major
+modes inherit from it, exactly for this purpose.
+
   It is best to design your hook functions so that the order in which
 they are executed does not matter.  Any dependence on the order is
-``asking for trouble.''  However, the order is predictable: the most
-recently added hook functions are executed first.
+asking for trouble.  However, the order is predictable: the hook
+functions are executed in the order they appear in the hook.
 
 @findex remove-hook
   If you play with adding various different versions of a hook
diff --git a/doc/emacs/fixit.texi b/doc/emacs/fixit.texi
index 0c9cc829fc3..c14041f2271 100644
--- a/doc/emacs/fixit.texi
+++ b/doc/emacs/fixit.texi
@@ -400,17 +400,16 @@ is a spell checking dictionary but no word completion dictionary.
 
 @cindex Flyspell mode
 @findex flyspell-mode
+@findex turn-on-flyspell
   Flyspell mode is a fully-automatic way to check spelling as you edit
 in Emacs.  It operates by checking words as you change or insert them.
 When it finds a word that it does not recognize, it highlights that
 word.  This does not interfere with your editing, but when you see the
 highlighted word, you can move to it and fix it.  Type @kbd{M-x
 flyspell-mode} to enable or disable this mode in the current buffer.
-@findex turn-on-flyspell
-To enable @code{flyspell-mode} in all text mode buffers, add
+To enable Flyspell mode in all text mode buffers, add
 @code{turn-on-flyspell} to @code{text-mode-hook}.
 
-
   When Flyspell mode highlights a word as misspelled, you can click on
 it with @kbd{Mouse-2} to display a menu of possible corrections and
 actions.  You can also correct the word by editing it manually in any
@@ -421,4 +420,5 @@ way you like.
 that it only checks words in comments and string constants.  This
 feature is useful for editing programs.  Type @kbd{M-x
 flyspell-prog-mode} to enable or disable this mode in the current
-buffer.
+buffer.  To enable this mode in all programming mode buffers, add
+@code{flyspell-prog-mode} to @code{prog-mode-hook} (@pxref{Hooks}).