[Emacs-diffs] /srv/bzr/emacs/trunk r104405: Document prog-mode-hook in Emacs manual.

[Chong Yidong]

------------------------------------------------------------
revno: 104405
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sat 2011-05-28 14:22:08 -0400
message:
  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).
modified:
  doc/emacs/ChangeLog
  doc/emacs/custom.texi
  doc/emacs/fixit.texi

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2011-05-27 01:00:53 +0000
+++ b/doc/emacs/ChangeLog       2011-05-28 18:22:08 +0000
@@ -1,3 +1,10 @@
+2011-05-28  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        * custom.texi (Specifying File Variables):

=== modified file 'doc/emacs/custom.texi'
--- a/doc/emacs/custom.texi     2011-05-27 01:00:53 +0000
+++ b/doc/emacs/custom.texi     2011-05-28 18:22:08 +0000
@@ -888,53 +888,48 @@
 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
address@hidden 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,
address@hidden (@pxref{Visiting}) is abnormal because
-as soon as one hook function returns a address@hidden 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
address@hidden 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,
address@hidden is abnormal because as soon as
+one hook function returns a address@hidden 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}.
address@hidden,,, 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 @@
 @group
     (c-cleanup-list . (scope-operator
                        empty-defun-braces
-                       defun-close-semi))
address@hidden group
address@hidden
-    (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
 
address@hidden Prog mode
address@hidden 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
address@hidden 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

=== modified file 'doc/emacs/fixit.texi'
--- a/doc/emacs/fixit.texi      2011-05-17 02:26:56 +0000
+++ b/doc/emacs/fixit.texi      2011-05-28 18:22:08 +0000
@@ -400,17 +400,16 @@
 
 @cindex Flyspell mode
 @findex flyspell-mode
address@hidden 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.
address@hidden 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 @@
 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
address@hidden to @code{prog-mode-hook} (@pxref{Hooks}).