Show
Ignore:
Timestamp:
08/10/06 11:19:54 (2 years ago)
Author:
miyoshi
Message:

Sync up with Emacs CVS HEAD.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/lispref/modes.texi

    r4131 r4140  
    4444@cindex normal hook 
    4545  Most of the hooks in Emacs are @dfn{normal hooks}.  These variables 
    46 contain lists of functions to be called with no arguments.  When the 
    47 hook name ends in @samp{-hook}, that tells you it is normal.  We try to 
    48 make all hooks normal, as much as possible, so that you can use them in 
    49 a uniform way. 
    50  
    51   Every major mode function is supposed to run a normal hook called the 
    52 @dfn{mode hook} as the last step of initialization.  This makes it easy 
    53 for a user to customize the behavior of the mode, by overriding the 
    54 buffer-local variable assignments already made by the mode.  Most 
    55 minor modes also run a mode hook at their end.  But hooks are used in 
    56 other contexts too.  For example, the hook @code{suspend-hook} runs 
    57 just before Emacs suspends itself (@pxref{Suspending Emacs}). 
     46contain lists of functions to be called with no arguments.  By 
     47convention, whenever the hook name ends in @samp{-hook}, that tells 
     48you it is normal.  We try to make all hooks normal, as much as 
     49possible, so that you can use them in a uniform way. 
     50 
     51  Every major mode function is supposed to run a normal hook called 
     52the @dfn{mode hook} as the one of the last steps of initialization. 
     53This makes it easy for a user to customize the behavior of the mode, 
     54by overriding the buffer-local variable assignments already made by 
     55the mode.  Most minor mode functions also run a mode hook at the end. 
     56But hooks are used in other contexts too.  For example, the hook 
     57@code{suspend-hook} runs just before Emacs suspends itself 
     58(@pxref{Suspending Emacs}). 
    5859 
    5960  The recommended way to add a hook function to a normal hook is by 
    …… 
    6667@cindex abnormal hook 
    6768  If the hook variable's name does not end with @samp{-hook}, that 
    68 indicates it is probably an @dfn{abnormal hook}.  Then you should look at its 
    69 documentation to see how to use the hook properly. 
    70  
    71   If the variable's name ends in @samp{-functions} or @samp{-hooks}, 
    72 then the value is a list of functions, but it is abnormal in that either 
    73 these functions are called with arguments or their values are used in 
    74 some way.  You can use @code{add-hook} to add a function to the list, 
    75 but you must take care in writing the function.  (A few of these 
    76 variables, notably those ending in @samp{-hooks}, are actually 
    77 normal hooks which were named before we established the convention of 
    78 using @samp{-hook} for them.) 
    79  
    80   If the variable's name ends in @samp{-function}, then its value 
    81 is just a single function, not a list of functions. 
     69indicates it is probably an @dfn{abnormal hook}.  That means the hook 
     70functions are called with arguments, or their return values are used 
     71in some way.  The hook's documentation says how the functions are 
     72called.  You can use @code{add-hook} to add a function to an abnormal 
     73hook, but you must write the function to follow the hook's calling 
     74convention. 
     75 
     76  By convention, abnormal hook names end in @samp{-functions} or 
     77@samp{-hooks}.  If the variable's name ends in @samp{-function}, then 
     78its value is just a single function, not a list of functions. 
    8279 
    8380  Here's an example that uses a mode hook to turn on Auto Fill mode when 
    …… 
    9794in the order specified. 
    9895 
    99 If a hook variable has a non-@code{nil} value, that value may be a 
    100 function or a list of functions.  (The former option is considered 
    101 obsolete.)  If the value is a function (either a lambda expression or 
    102 a symbol with a function definition), it is called.  If it is a list 
    103 that isn't a function, its elements are called, consecutively.  All 
    104 the hook functions are called with no arguments. 
     96If a hook variable has a non-@code{nil} value, that value should be a 
     97list of functions.  @code{run-hooks} calls all the functions, one by 
     98one, with no arguments. 
     99 
     100The hook variable's value can also be a single function---either a 
     101lambda expression or a symbol with a function definition---which 
     102@code{run-hooks} calls.  But this usage is obsolete. 
    105103@end defun 
    106104 
    …… 
    188186* Major Mode Basics:: 
    189187* Major Mode Conventions::  Coding conventions for keymaps, etc. 
    190 * Example Major Modes::     Text mode and Lisp modes. 
    191188* Auto Major Mode::         How Emacs chooses the major mode automatically. 
    192189* Mode Help::               Finding out how to use a mode. 
    …… 
    196193                              comment syntax and Font Lock mode. 
    197194* Mode Hooks::              Hooks run at the end of major mode functions. 
     195* Example Major Modes::     Text mode and Lisp modes. 
    198196@end menu 
    199197 
    …… 
    215213writing a minor mode, which is often difficult). 
    216214 
    217   If the new mode is similar to an old one, it is often unwise to modify 
    218 the old one to serve two purposes, since it may become harder to use and 
    219 maintain.  Instead, copy and rename an existing major mode definition 
    220 and alter the copy---or define a @dfn{derived mode} (@pxref{Derived 
    221 Modes}).  For example, Rmail Edit mode, which is in 
    222 @file{emacs/lisp/mail/rmailedit.el}, is a major mode that is very similar to 
    223 Text mode except that it provides two additional commands.  Its 
    224 definition is distinct from that of Text mode, but uses that of Text mode. 
     215  If the new mode is similar to an old one, it is often unwise to 
     216modify the old one to serve two purposes, since it may become harder 
     217to use and maintain.  Instead, copy and rename an existing major mode 
     218definition and alter the copy---or use @code{define-derived-mode} to 
     219define a @dfn{derived mode} (@pxref{Derived Modes}).  For example, 
     220Rmail Edit mode is a major mode that is very similar to Text mode 
     221except that it provides two additional commands.  Its definition is 
     222distinct from that of Text mode, but uses that of Text mode. 
    225223 
    226224  Even if the new mode is not an obvious derivative of any other mode, 
    …… 
    288286@item 
    289287The major mode command should start by calling 
    290 @code{kill-all-local-variables}.  This is what gets rid of the 
    291 buffer-local variables of the major mode previously in effect. 
     288@code{kill-all-local-variables}.  This runs the normal hook 
     289@code{change-major-mode-hook}, then gets rid of the buffer-local 
     290variables of the major mode previously in effect.  @xref{Creating 
     291Buffer-Local}. 
    292292 
    293293@item 
    …… 
    356356 
    357357@item 
    358 Major modes must not define @key{RET} to do anything other than insert 
    359 a newline.  The command to insert a newline and then indent is 
    360 @kbd{C-j}.  Please keep this distinction uniform for all major modes. 
     358Major modes modes for editing text should not define @key{RET} to do 
     359anything other than insert a newline.  However, it is ok for 
     360specialized modes for text that users don't directly edit, such as 
     361Dired and Info modes, to redefine @key{RET} to do something entirely 
     362different. 
    361363 
    362364@item 
    …… 
    428430@cindex mode hook 
    429431@cindex major mode hook 
    430 Each major mode should have a @dfn{mode hook} named 
    431 @code{@var{modename}-mode-hook}.  The major mode command should run that 
    432 hook, with @code{run-mode-hooks}, as the very last thing it 
    433 does.  @xref{Mode Hooks}. 
     432Each major mode should have a normal @dfn{mode hook} named 
     433@code{@var{modename}-mode-hook}.  The very last thing the major mode command 
     434should do is to call @code{run-mode-hooks}.  This runs the mode hook, 
     435and then runs the normal hook @code{after-change-major-mode-hook}. 
     436@xref{Mode Hooks}. 
    434437 
    435438@item 
    …… 
    488491Even if you never load the file more than once, someone else will. 
    489492@end itemize 
    490  
    491 @node Example Major Modes 
    492 @subsection Major Mode Examples 
    493  
    494   Text mode is perhaps the simplest mode besides Fundamental mode. 
    495 Here are excerpts from  @file{text-mode.el} that illustrate many of 
    496 the conventions listed above: 
    497  
    498 @smallexample 
    499 @group 
    500 ;; @r{Create the syntax table for this mode.} 
    501 (defvar text-mode-syntax-table 
    502   (let ((st (make-syntax-table))) 
    503     (modify-syntax-entry ?\" ".   " st) 
    504     (modify-syntax-entry ?\\ ".   " st) 
    505     ;; Add `p' so M-c on `hello' leads to `Hello', not `hello'. 
    506     (modify-syntax-entry ?' "w p" st) 
    507     st) 
    508   "Syntax table used while in `text-mode'.") 
    509 @end group 
    510  
    511 ;; @r{Create the keymap for this mode.} 
    512 @group 
    513 (defvar text-mode-map 
    514   (let ((map (make-sparse-keymap))) 
    515     (define-key map "\e\t" 'ispell-complete-word) 
    516     (define-key map "\es" 'center-line) 
    517     (define-key map "\eS" 'center-paragraph) 
    518     map) 
    519   "Keymap for `text-mode'. 
    520 Many other modes, such as Mail mode, Outline mode 
    521 and Indented Text mode, inherit all the commands 
    522 defined in this map.") 
    523 @end group 
    524 @end smallexample 
    525  
    526   Here is how the actual mode command is defined now: 
    527  
    528 @smallexample 
    529 @group 
    530 (define-derived-mode text-mode nil "Text" 
    531   "Major mode for editing text written for humans to read. 
    532 In this mode, paragraphs are delimited only by blank or white lines. 
    533 You can thus get the full benefit of adaptive filling 
    534  (see the variable `adaptive-fill-mode'). 
    535 \\@{text-mode-map@} 
    536 Turning on Text mode runs the normal hook `text-mode-hook'." 
    537 @end group 
    538 @group 
    539   (make-local-variable 'text-mode-variant) 
    540   (setq text-mode-variant t) 
    541   ;; @r{These two lines are a feature added recently.} 
    542   (set (make-local-variable 'require-final-newline) 
    543        mode-require-final-newline) 
    544   (set (make-local-variable 'indent-line-function) 'indent-relative)) 
    545 @end group 
    546 @end smallexample 
    547  
    548   But here is how it was defined formerly, before 
    549 @code{define-derived-mode} existed: 
    550  
    551 @smallexample 
    552 @group 
    553 ;; @r{This isn't needed nowadays, since @code{define-derived-mode} does it.} 
    554 (defvar text-mode-abbrev-table nil 
    555   "Abbrev table used while in text mode.") 
    556 (define-abbrev-table 'text-mode-abbrev-table ()) 
    557 @end group 
    558  
    559 @group 
    560 (defun text-mode () 
    561   "Major mode for editing text intended for humans to read... 
    562  Special commands: \\@{text-mode-map@} 
    563 @end group 
    564 @group 
    565 Turning on text-mode runs the hook `text-mode-hook'." 
    566   (interactive) 
    567   (kill-all-local-variables) 
    568   (use-local-map text-mode-map) 
    569 @end group 
    570 @group 
    571   (setq local-abbrev-table text-mode-abbrev-table) 
    572   (set-syntax-table text-mode-syntax-table) 
    573 @end group 
    574 @group 
    575   ;; @r{These four lines are absent from the current version} 
    576   ;; @r{not because this is done some other way, but rather} 
    577   ;; @r{because nowadays Text mode uses the normal definition of paragraphs.} 
    578   (make-local-variable 'paragraph-start) 
    579   (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter)) 
    580   (make-local-variable 'paragraph-separate) 
    581   (setq paragraph-separate paragraph-start) 
    582   (make-local-variable 'indent-line-function) 
    583   (setq indent-line-function 'indent-relative-maybe) 
    584 @end group 
    585 @group 
    586   (setq mode-name "Text") 
    587   (setq major-mode 'text-mode) 
    588   (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to} 
    589                                     ;   @r{customize the mode with a hook.} 
    590 @end group 
    591 @end smallexample 
    592  
    593 @cindex @file{lisp-mode.el} 
    594   The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp 
    595 Interaction mode) have more features than Text mode and the code is 
    596 correspondingly more complicated.  Here are excerpts from 
    597 @file{lisp-mode.el} that illustrate how these modes are written. 
    598  
    599 @cindex syntax table example 
    600 @smallexample 
    601 @group 
    602 ;; @r{Create mode-specific table variables.} 
    603 (defvar lisp-mode-syntax-table nil "") 
    604 (defvar lisp-mode-abbrev-table nil "") 
    605 @end group 
    606  
    607 @group 
    608 (defvar emacs-lisp-mode-syntax-table 
    609   (let ((table (make-syntax-table))) 
    610     (let ((i 0)) 
    611 @end group 
    612  
    613 @group 
    614       ;; @r{Set syntax of chars up to @samp{0} to say they are} 
    615       ;;   @r{part of symbol names but not words.} 
    616       ;;   @r{(The digit @samp{0} is @code{48} in the @acronym{ASCII} character set.)} 
    617       (while (< i ?0) 
    618         (modify-syntax-entry i "_   " table) 
    619         (setq i (1+ i))) 
    620       ;; @r{@dots{} similar code follows for other character ranges.} 
    621 @end group 
    622 @group 
    623       ;; @r{Then set the syntax codes for characters that are special in Lisp.} 
    624       (modify-syntax-entry ?  "    " table) 
    625       (modify-syntax-entry ?\t "    " table) 
    626       (modify-syntax-entry ?\f "    " table) 
    627       (modify-syntax-entry ?\n ">   " table) 
    628 @end group 
    629 @group 
    630       ;; @r{Give CR the same syntax as newline, for selective-display.} 
    631       (modify-syntax-entry ?\^m ">   " table) 
    632       (modify-syntax-entry ?\; "<   " table) 
    633       (modify-syntax-entry ?` "'   " table) 
    634       (modify-syntax-entry ?' "'   " table) 
    635       (modify-syntax-entry ?, "'   " table) 
    636 @end group 
    637 @group 
    638       ;; @r{@dots{}likewise for many other characters@dots{}} 
    639       (modify-syntax-entry ?\( "()  " table) 
    640       (modify-syntax-entry ?\) ")(  " table) 
    641       (modify-syntax-entry ?\[ "(]  " table) 
    642       (modify-syntax-entry ?\] ")[  " table)) 
    643     table)) 
    644 @end group 
    645 @group 
    646 ;; @r{Create an abbrev table for lisp-mode.} 
    647 (define-abbrev-table 'lisp-mode-abbrev-table ()) 
    648 @end group 
    649 @end smallexample 
    650  
    651   Much code is shared among the three Lisp modes.  The following 
    652 function sets various variables; it is called by each of the major Lisp 
    653 mode functions: 
    654  
    655 @smallexample 
    656 @group 
    657 (defun lisp-mode-variables (lisp-syntax) 
    658   (when lisp-syntax 
    659     (set-syntax-table lisp-mode-syntax-table)) 
    660   (setq local-abbrev-table lisp-mode-abbrev-table) 
    661   @dots{} 
    662 @end group 
    663 @end smallexample 
    664  
    665   Functions such as @code{forward-paragraph} use the value of the 
    666 @code{paragraph-start} variable.  Since Lisp code is different from 
    667 ordinary text, the @code{paragraph-start} variable needs to be set 
    668 specially to handle Lisp.  Also, comments are indented in a special 
    669 fashion in Lisp and the Lisp modes need their own mode-specific 
    670 @code{comment-indent-function}.  The code to set these variables is the 
    671 rest of @code{lisp-mode-variables}. 
    672  
    673 @smallexample 
    674 @group 
    675   (make-local-variable 'paragraph-start) 
    676   (setq paragraph-start (concat page-delimiter "\\|$" )) 
    677   (make-local-variable 'paragraph-separate) 
    678   (setq paragraph-separate paragraph-start) 
    679   @dots{} 
    680 @end group 
    681 @group 
    682   (make-local-variable 'comment-indent-function) 
    683   (setq comment-indent-function 'lisp-comment-indent)) 
    684   @dots{} 
    685 @end group 
    686 @end smallexample 
    687  
    688   Each of the different Lisp modes has a slightly different keymap.  For 
    689 example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other 
    690 Lisp modes do not.  However, all Lisp modes have some commands in 
    691 common.  The following code sets up the common commands: 
    692  
    693 @smallexample 
    694 @group 
    695 (defvar shared-lisp-mode-map () 
    696   "Keymap for commands shared by all sorts of Lisp modes.") 
    697  
    698 ;; @r{Putting this @code{if} after the @code{defvar} is an older style.} 
    699 (if shared-lisp-mode-map 
    700     () 
    701    (setq shared-lisp-mode-map (make-sparse-keymap)) 
    702    (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp) 
    703    (define-key shared-lisp-mode-map "\177" 
    704                'backward-delete-char-untabify)) 
    705 @end group 
    706 @end smallexample 
    707  
    708 @noindent 
    709 And here is the code to set up the keymap for Lisp mode: 
    710  
    711 @smallexample 
    712 @group 
    713 (defvar lisp-mode-map () 
    714   "Keymap for ordinary Lisp mode...") 
    715  
    716 (if lisp-mode-map 
    717     () 
    718   (setq lisp-mode-map (make-sparse-keymap)) 
    719   (set-keymap-parent lisp-mode-map shared-lisp-mode-map) 
    720   (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun) 
    721   (define-key lisp-mode-map "\C-c\C-z" 'run-lisp)) 
    722 @end group 
    723 @end smallexample 
    724  
    725   Finally, here is the complete major mode function definition for 
    726 Lisp mode. 
    727  
    728 @smallexample 
    729 @group 
    730 (defun lisp-mode () 
    731   "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp. 
    732 Commands: 
    733 Delete converts tabs to spaces as it moves back. 
    734 Blank lines separate paragraphs.  Semicolons start comments. 
    735 \\@{lisp-mode-map@} 
    736 Note that `run-lisp' may be used either to start an inferior Lisp job 
    737 or to switch back to an existing one. 
    738 @end group 
    739  
    740 @group 
    741 Entry to this mode calls the value of `lisp-mode-hook' 
    742 if that value is non-nil." 
    743   (interactive) 
    744   (kill-all-local-variables) 
    745 @end group 
    746 @group 
    747   (use-local-map lisp-mode-map)          ; @r{Select the mode's keymap.} 
    748   (setq major-mode 'lisp-mode)           ; @r{This is how @code{describe-mode}} 
    749                                          ;   @r{finds out what to describe.} 
    750   (setq mode-name "Lisp")                ; @r{This goes into the mode line.} 
    751   (lisp-mode-variables t)                ; @r{This defines various variables.} 
    752   (make-local-variable 'comment-start-skip) 
    753   (setq comment-start-skip 
    754         "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *") 
    755   (make-local-variable 'font-lock-keywords-case-fold-search) 
    756   (setq font-lock-keywords-case-fold-search t) 
    757 @end group 
    758 @group 
    759   (setq imenu-case-fold-search t) 
    760   (set-syntax-table lisp-mode-syntax-table) 
    761   (run-mode-hooks 'lisp-mode-hook))           ; @r{This permits the user to use a} 
    762                                          ;   @r{hook to customize the mode.} 
    763 @end group 
    764 @end smallexample 
    765493 
    766494@node Auto Major Mode 
    …… 
    1074802@cindex generic mode 
    1075803 
    1076 @dfn{Generic modes} are simple major modes with basic support for 
    1077 comment syntax and Font Lock mode.  They are primarily useful for 
    1078 configuration files.  To define a generic mode, use the macro 
    1079 @code{define-generic-mode}.  See the file @file{generic-x.el} for some 
    1080 examples of the use of @code{define-generic-mode}. 
     804  @dfn{Generic modes} are simple major modes with basic support for 
     805comment syntax and Font Lock mode.  To define a generic mode, use the 
     806macro @code{define-generic-mode}.  See the file @file{generic-x.el} 
     807for some examples of the use of @code{define-generic-mode}. 
    1081808 
    1082809@defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring 
    1083 This macro creates a new generic mode.  The argument @var{mode} (an 
    1084 unquoted symbol) is the major mode command.  The optional argument 
    1085 @var{docstring} is the documentation for the mode command.  If you do 
    1086 not supply it, @code{define-generic-mode} uses a default documentation 
    1087 string instead. 
    1088  
    1089 @var{comment-list} is a list in which each element is either a 
    1090 character, a string of one or two characters, or a cons cell.  A 
    1091 character or a string is set up in the mode's syntax table as a 
     810This macro defines a generic mode command named @var{mode} (a symbol, 
     811not quoted).  The optional argument @var{docstring} is the 
     812documentation for the mode command.  If you do not supply it, 
     813@code{define-generic-mode} generates one by default. 
     814 
     815The argument @var{comment-list} is a list in which each element is 
     816either a character, a string of one or two characters, or a cons cell. 
     817A character or a string is set up in the mode's syntax table as a 
    1092818``comment starter.''  If the entry is a cons cell, the @sc{car} is set 
    1093819up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.'' 
    1094820(Use @code{nil} for the latter if you want comments to end at the end 
    1095 of the line.)  Note that the syntax table has limitations about what 
    1096 comment starters and enders are actually possible.  @xref{Syntax 
    1097 Tables}. 
    1098  
    1099 @var{keyword-list} is a list of keywords to highlight with 
    1100 @code{font-lock-keyword-face}.  Each keyword should be a string. 
    1101 @var{font-lock-list} is a list of additional expressions to highlight. 
    1102 Each element of this list should have the same form as an element of 
    1103 @code{font-lock-keywords}.  @xref{Search-based Fontification}. 
    1104  
    1105 @var{auto-mode-list} is a list of regular expressions to add to the 
    1106 variable @code{auto-mode-alist}.  These regular expressions are added 
    1107 when Emacs runs the macro expansion. 
    1108  
    1109 @var{function-list} is a list of functions to call to do some 
    1110 additional setup.  The mode command calls these functions just before 
    1111 it runs the mode hook variable @code{@var{mode}-hook}. 
     821of the line.)  Note that the syntax table mechanism has limitations 
     822about what comment starters and enders are actually possible. 
     823@xref{Syntax Tables}. 
     824 
     825The argument @var{keyword-list} is a list of keywords to highlight 
     826with @code{font-lock-keyword-face}.  Each keyword should be a string. 
     827Meanwhile, @var{font-lock-list} is a list of additional expressions to 
     828highlight.  Each element of this list should have the same form as an 
     829element of @code{font-lock-keywords}.  @xref{Search-based 
     830Fontification}. 
     831 
     832The argument @var{auto-mode-list} is a list of regular expressions to 
     833add to the variable @code{auto-mode-alist}.  They are added by the execution 
     834of the @code{define-generic-mode} form, not by expanding the macro call. 
     835 
     836Finally, @var{function-list} is a list of functions for the mode 
     837command to call for additional setup.  It calls these functions just 
     838before it runs the mode hook variable @code{@var{mode}-hook}. 
    1112839@end defmac 
    1113840 
    …… 
    1115842@subsection Mode Hooks 
    1116843 
    1117   The two last things a major mode function should do is run its mode 
    1118 hook and finally the mode independent normal hook 
    1119 @code{after-change-major-mode-hook}.  If the major mode is a derived 
    1120 mode, that is if it calls another major mode (the parent mode) in its 
    1121 body, then the parent's mode hook is run just before the derived 
    1122 mode's hook.  Neither the parent's mode hook nor 
    1123 @code{after-change-major-mode-hook} are run at the end of the actual 
    1124 call to the parent mode.  This applies recursively if the parent mode 
    1125 has itself a parent.  That is, the mode hooks of all major modes 
    1126 called directly or indirectly by the major mode function are all run 
    1127 in sequence at the end, just before 
    1128 @code{after-change-major-mode-hook}. 
    1129  
    1130   These conventions are new in Emacs 22, and some major modes 
    1131 implemented by users do not follow them yet.  So if you put a function 
    1132 onto @code{after-change-major-mode-hook}, keep in mind that some modes 
    1133 will fail to run it.  If a user complains about that, you can respond, 
    1134 ``That major mode fails to follow Emacs conventions, and that's why it 
    1135 fails to work.  Please fix the major mode.''  In most cases, that is 
    1136 good enough, so go ahead and use @code{after-change-major-mode-hook}. 
    1137 However, if a certain feature needs to be completely reliable, 
    1138 it should not use @code{after-change-major-mode-hook} as of yet. 
     844  Every major mode function should finish by running its mode hook and 
     845the mode-independent normal hook @code{after-change-major-mode-hook}. 
     846It does this by calling @code{run-mode-hooks}.  If the major mode is a 
     847derived mode, that is if it calls another major mode (the parent mode) 
     848in its body, it should do this inside @code{delay-mode-hooks} so that 
     849the parent won't run these hooks itself.  Instead, the derived mode's 
     850call to @code{run-mode-hooks} runs the parent's mode hook too. 
     851@xref{Major Mode Conventions}. 
     852 
     853  Emacs versions before Emacs 22 did not have @code{delay-mode-hooks}. 
     854When user-implemented major modes have not been updated to use it, 
     855they won't entirely follow these conventions: they may run the 
     856parent's mode hook too early, or fail to run 
     857@code{after-change-major-mode-hook}.  If you encounter such a major 
     858mode, please correct it to follow these conventions. 
    1139859 
    1140860  When you defined a major mode using @code{define-derived-mode}, it 
    1141861automatically makes sure these conventions are followed.  If you 
    1142 define a major mode ``from scratch,'' not using 
    1143 @code{define-derived-mode}, make sure the major mode command follows 
    1144 these and other conventions.  @xref{Major Mode Conventions}.  You use 
    1145 these functions to do it properly. 
     862define a major mode ``by hand,'' not using @code{define-derived-mode}, 
     863use the following functions to handle these conventions automatically. 
    1146864 
    1147865@defun run-mode-hooks &rest hookvars 
    …… 
    1150868@code{after-change-major-mode-hook}. 
    1151869 
    1152 When the call to this function is dynamically inside a 
    1153 @code{delay-mode-hooks} form, this function does not run any hooks. 
     870When this function is called during the execution of a 
     871@code{delay-mode-hooks} form, it does not run the hooks immediately. 
    1154872Instead, it arranges for the next call to @code{run-mode-hooks} to run 
    1155 @var{hookvars}. 
     873them. 
    1156874@end defun 
    1157875 
    1158876@defmac delay-mode-hooks body@dots{} 
    1159 This macro executes @var{body} like @code{progn}, but all calls to 
    1160 @code{run-mode-hooks} inside @var{body} delay running their hooks. 
    1161 They will be run by the first call to @code{run-mode-hooks} after exit 
    1162 from @code{delay-mode-hooks}.  This is the proper way for a major mode 
    1163 command to invoke its parent mode. 
     877When one major mode command calls another, it should do so inside of 
     878@code{delay-mode-hooks}. 
     879 
     880This macro executes @var{body}, but tells all @code{run-mode-hooks} 
     881calls during the execution of @var{body} to delay running their hooks. 
     882The hooks will actually run during the next call to 
     883@code{run-mode-hooks} after the end of the @code{delay-mode-hooks} 
     884construct. 
    1164885@end defmac 
    1165886 
    1166887@defvar after-change-major-mode-hook 
    1167 Every major mode function should run this normal hook at its very end. 
    1168 It normally does not need to do so explicitly.  Indeed, a major mode 
    1169 function should normally run its mode hook with @code{run-mode-hooks} 
    1170 as the very last thing it does, and the last thing 
    1171 @code{run-mode-hooks} does is run @code{after-change-major-mode-hook}. 
    1172 @end defvar 
     888This is a normal hook run by @code{run-mode-hooks}.  It is run at the 
     889very end of every properly-written major mode function. 
     890@end defvar 
     891 
     892@node Example Major Modes 
     893@subsection Major Mode Examples 
     894 
     895  Text mode is perhaps the simplest mode besides Fundamental mode. 
     896Here are excerpts from  @file{text-mode.el} that illustrate many of 
     897the conventions listed above: 
     898 
     899@smallexample 
     900@group 
     901;; @r{Create the syntax table for this mode.} 
     902(defvar text-mode-syntax-table 
     903  (let ((st (make-syntax-table))) 
     904    (modify-syntax-entry ?\" ".   " st) 
     905    (modify-syntax-entry ?\\ ".   " st) 
     906    ;; Add `p' so M-c on `hello' leads to `Hello', not `hello'. 
     907    (modify-syntax-entry ?' "w p" st) 
     908    st) 
     909  "Syntax table used while in `text-mode'.") 
     910@end group 
     911 
     912;; @r{Create the keymap for this mode.} 
     913@group 
     914(defvar text-mode-map 
     915  (let ((map (make-sparse-keymap))) 
     916    (define-key map "\e\t" 'ispell-complete-word) 
     917    (define-key map "\es" 'center-line) 
     918    (define-key map "\eS" 'center-paragraph) 
     919    map) 
     920  "Keymap for `text-mode'. 
     921Many other modes, such as Mail mode, Outline mode 
     922and Indented Text mode, inherit all the commands 
     923defined in this map.") 
     924@end group 
     925@end smallexample 
     926 
     927  Here is how the actual mode command is defined now: 
     928 
     929@smallexample 
     930@group 
     931(define-derived-mode text-mode nil "Text" 
     932  "Major mode for editing text written for humans to read. 
     933In this mode, paragraphs are delimited only by blank or white lines. 
     934You can thus get the full benefit of adaptive filling 
     935 (see the variable `adaptive-fill-mode'). 
     936\\@{text-mode-map@} 
     937Turning on Text mode runs the normal hook `text-mode-hook'." 
     938@end group 
     939@group 
     940  (make-local-variable 'text-mode-variant) 
     941  (setq text-mode-variant t) 
     942  ;; @r{These two lines are a feature added recently.} 
     943  (set (make-local-variable 'require-final-newline) 
     944       mode-require-final-newline) 
     945  (set (make-local-variable 'indent-line-function) 'indent-relative)) 
     946@end group 
     947@end smallexample 
     948 
     949  But here is how it was defined formerly, before 
     950@code{define-derived-mode} existed: 
     951 
     952@smallexample 
     953@group 
     954;; @r{This isn't needed nowadays, since @code{define-derived-mode} does it.} 
     955(defvar text-mode-abbrev-table nil 
     956  "Abbrev table used while in text mode.") 
     957(define-abbrev-table 'text-mode-abbrev-table ()) 
     958@end group 
     959 
     960@group 
     961(defun text-mode () 
     962  "Major mode for editing text intended for humans to read... 
     963 Special commands: \\@{text-mode-map@} 
     964@end group 
     965@group 
     966Turning on text-mode runs the hook `text-mode-hook'." 
     967  (interactive) 
     968  (kill-all-local-variables) 
     969  (use-local-map text-mode-map) 
     970@end group 
     971@group 
     972  (setq local-abbrev-table text-mode-abbrev-table) 
     973  (set-syntax-table text-mode-syntax-table) 
     974@end group 
     975@group 
     976  ;; @r{These four lines are absent from the current version} 
     977  ;; @r{not because this is done some other way, but rather} 
     978  ;; @r{because nowadays Text mode uses the normal definition of paragraphs.} 
     979  (make-local-variable 'paragraph-start) 
     980  (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter)) 
     981  (make-local-variable 'paragraph-separate) 
     982  (setq paragraph-separate paragraph-start) 
     983  (make-local-variable 'indent-line-function) 
     984  (setq indent-line-function 'indent-relative-maybe) 
     985@end group 
     986@group 
     987  (setq mode-name "Text") 
     988  (setq major-mode 'text-mode) 
     989  (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to} 
     990                                    ;   @r{customize the mode with a hook.} 
     991@end group 
     992@end smallexample 
     993 
     994@cindex @file{lisp-mode.el} 
     995  The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp 
     996Interaction mode) have more features than Text mode and the code is 
     997correspondingly more complicated.  Here are excerpts from 
     998@file{lisp-mode.el} that illustrate how these modes are written. 
     999 
     1000@cindex syntax table example 
     1001@smallexample 
     1002@group 
     1003;; @r{Create mode-specific table variables.} 
     1004(defvar lisp-mode-syntax-table nil "") 
     1005(defvar lisp-mode-abbrev-table nil "") 
     1006@end group 
     1007 
     1008@group 
     1009(defvar emacs-lisp-mode-syntax-table 
     1010  (let ((table (make-syntax-table))) 
     1011    (let ((i 0)) 
     1012@end group 
     1013 
     1014@group 
     1015      ;; @r{Set syntax of chars up to @samp{0} to say they are} 
     1016      ;;   @r{part of symbol names but not words.} 
     1017      ;;   @r{(The digit @samp{0} is @code{48} in the @acronym{ASCII} character set.)} 
     1018      (while (< i ?0) 
     1019        (modify-syntax-entry i "_   " table) 
     1020        (setq i (1+ i))) 
     1021      ;; @r{@dots{} similar code follows for other character ranges.} 
     1022@end group 
     1023@group 
     1024      ;; @r{Then set the syntax codes for characters that are special in Lisp.} 
     1025      (modify-syntax-entry ?  "    " table) 
     1026      (modify-syntax-entry ?\t "    " table) 
     1027      (modify-syntax-entry ?\f "    " table) 
     1028      (modify-syntax-entry ?\n ">   " table) 
     1029@end group 
     1030@group 
     1031      ;; @r{Give CR the same syntax as newline, for selective-display.} 
     1032      (modify-syntax-entry ?\^m ">   " table) 
     1033      (modify-syntax-entry ?\; "<   " table) 
     1034      (modify-syntax-entry ?` "'   " table) 
     1035      (modify-syntax-entry ?' "'   " table) 
     1036      (modify-syntax-entry ?, "'   " table) 
     1037@end group 
     1038@group 
     1039      ;; @r{@dots{}likewise for many other characters@dots{}} 
     1040      (modify-syntax-entry ?\( "()  " table) 
     1041      (modify-syntax-entry ?\) ")(  " table) 
     1042      (modify-syntax-entry ?\[ "(]  " table) 
     1043      (modify-syntax-entry ?\] ")[  " table)) 
     1044    table)) 
     1045@end group 
     1046@group 
     1047;; @r{Create an abbrev table for lisp-mode.} 
     1048(define-abbrev-table 'lisp-mode-abbrev-table ()) 
     1049@end group 
     1050@end smallexample 
     1051 
     1052  The three modes for Lisp share much of their code.  For instance, 
     1053each calls the following function to set various variables: 
     1054 
     1055@smallexample 
     1056@group 
     1057(defun lisp-mode-variables (lisp-syntax) 
     1058  (when lisp-syntax 
     1059    (set-syntax-table lisp-mode-syntax-table)) 
     1060  (setq local-abbrev-table lisp-mode-abbrev-table) 
     1061  @dots{} 
     1062@end group 
     1063@end smallexample 
     1064 
     1065  In Lisp and most programming languages, we want the paragraph 
     1066commands to treat only blank lines as paragraph separators.  And the 
     1067modes should undestand the Lisp conventions for comments.  The rest of 
     1068@code{lisp-mode-variables} sets this up: 
     1069 
     1070@smallexample 
     1071@group 
     1072  (make-local-variable 'paragraph-start) 
     1073  (setq paragraph-start (concat page-delimiter "\\|$" )) 
     1074  (make-local-variable 'paragraph-separate) 
     1075  (setq paragraph-separate paragraph-start) 
     1076  @dots{} 
     1077@end group 
     1078@group 
     1079  (make-local-variable 'comment-indent-function) 
     1080  (setq comment-indent-function 'lisp-comment-indent)) 
     1081  @dots{} 
     1082@end group 
     1083@end smallexample 
     1084 
     1085  Each of the different Lisp modes has a slightly different keymap.  For 
     1086example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other 
     1087Lisp modes do not.  However, all Lisp modes have some commands in 
     1088common.  The following code sets up the common commands: 
     1089 
     1090@smallexample 
     1091@group 
     1092(defvar shared-lisp-mode-map () 
     1093  "Keymap for commands shared by all sorts of Lisp modes.") 
     1094 
     1095;; @r{Putting this @code{if} after the @code{defvar} is an older style.} 
     1096(if shared-lisp-mode-map 
     1097    () 
     1098   (setq shared-lisp-mode-map (make-sparse-keymap)) 
     1099   (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp) 
     1100   (define-key shared-lisp-mode-map "\177" 
     1101               'backward-delete-char-untabify)) 
     1102@end group 
     1103@end smallexample 
     1104 
     1105@noindent 
     1106And here is the code to set up the keymap for Lisp mode: 
     1107 
     1108@smallexample 
     1109@group 
     1110(defvar lisp-mode-map () 
     1111  "Keymap for ordinary Lisp mode...") 
     1112 
     1113(if lisp-mode-map 
     1114    () 
     1115  (setq lisp-mode-map (make-sparse-keymap)) 
     1116  (set-keymap-parent lisp-mode-map shared-lisp-mode-map) 
     1117  (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun) 
     1118  (define-key lisp-mode-map "\C-c\C-z" 'run-lisp)) 
     1119@end group 
     1120@end smallexample 
     1121 
     1122  Finally, here is the complete major mode function definition for 
     1123Lisp mode. 
     1124 
     1125@smallexample 
     1126@group 
     1127(defun lisp-mode () 
     1128  "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp. 
     1129Commands: 
     1130Delete converts tabs to spaces as it moves back. 
     1131Blank lines separate paragraphs.  Semicolons start comments. 
     1132\\@{lisp-mode-map@} 
     1133Note that `run-lisp' may be used either to start an inferior Lisp job 
     1134or to switch back to an existing one. 
     1135@end group 
     1136 
     1137@group 
     1138Entry to this mode calls the value of `lisp-mode-hook' 
     1139if that value is non-nil." 
     1140  (interactive) 
     1141  (kill-all-local-variables) 
     1142@end group 
     1143@group 
     1144  (use-local-map lisp-mode-map)          ; @r{Select the mode's keymap.} 
     1145  (setq major-mode 'lisp-mode)           ; @r{This is how @code{describe-mode}} 
     1146                                         ;   @r{finds out what to describe.} 
     1147  (setq mode-name "Lisp")                ; @r{This goes into the mode line.} 
     1148  (lisp-mode-variables t)                ; @r{This defines various variables.} 
     1149  (make-local-variable 'comment-start-skip) 
     1150  (setq comment-start-skip 
     1151        "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *") 
     1152  (make-local-variable 'font-lock-keywords-case-fold-search) 
     1153  (setq font-lock-keywords-case-fold-search t) 
     1154@end group 
     1155@group 
     1156  (setq imenu-case-fold-search t) 
     1157  (set-syntax-table lisp-mode-syntax-table) 
     1158  (run-mode-hooks 'lisp-mode-hook))           ; @r{This permits the user to use a} 
     1159                                         ;   @r{hook to customize the mode.} 
     1160@end group 
     1161@end smallexample 
    11731162 
    11741163@node Minor Modes 
    …… 
    12961285 
    12971286@noindent 
    1298 or like this, using @code{add-to-list} (@pxref{Setting Variables}): 
     1287or like this, using @code{add-to-list} (@pxref{List Variables}): 
    12991288 
    13001289@smallexample 
    …… 
    15341523 
    15351524  @code{mode-line-format} is a buffer-local variable that holds a 
    1536 @dfn{mode line construct}, a kind of template, which controls the 
    1537 display the mode line of the current buffer.  All windows for the same 
    1538 buffer use the same @code{mode-line-format}, so their mode lines 
    1539 appear the same---except for scrolling percentages, and line and 
    1540 column numbers, since those depend on point and on how the window is 
    1541 scrolled.  The value of @code{header-line-format} specifies the 
    1542 buffer's header line in the same way, with a mode line construct. 
    1543  
    1544   For efficiency, Emacs does not recompute the mode line and header 
    1545 line of a window in every redisplay.  It does so when circumstances 
     1525@dfn{mode line construct}, a kind of template, which controls what is 
     1526displayed on the mode line of the current buffer.  The value of 
     1527@code{header-line-format} specifies the buffer's header line in the 
     1528same way.  All windows for the same buffer use the same 
     1529@code{mode-line-format} and @code{header-line-format}. 
     1530 
     1531  For efficiency, Emacs does not continuously recompute the mode 
     1532line and header line of a window.  It does so when circumstances 
    15461533appear to call for it---for instance, if you change the window 
    15471534configuration, switch buffers, narrow or widen the buffer, scroll, or 
    …… 
    15531540display it in the new way. 
    15541541 
    1555 @c Emacs 19 feature 
    15561542@defun force-mode-line-update &optional all 
    15571543Force redisplay of the current buffer's mode line and header line. 
    …… 
    15901576@cindex percent symbol in mode line 
    15911577@item @var{string} 
    1592 A string as a mode-line construct appears verbatim in the mode line 
    1593 except for @dfn{@code{%}-constructs} in it.  These stand for 
    1594 substitution of other data; see @ref{%-Constructs}. 
    1595  
    1596 If the string has @code{face} properties, they are copied into the 
    1597 mode line contents too (@pxref{Properties in Mode}).  Any characters 
    1598 in the mode line which have no @code{face} properties are displayed, 
    1599 by default, in the face @code{mode-line} or @code{mode-line-inactive} 
    1600 (@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}). 
     1578A string as a mode-line construct appears verbatim except for 
     1579@dfn{@code{%}-constructs} in it.  These stand for substitution of 
     1580other data; see @ref{%-Constructs}. 
     1581 
     1582If parts of the string have @code{face} properties, they control 
     1583display of the text just as they would text in the buffer.  Any 
     1584characters which have no @code{face} properties are displayed, by 
     1585default, in the face @code{mode-line} or @code{mode-line-inactive} 
     1586(@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}).  The 
     1587@code{help-echo} and @code{local-map} properties in @var{string} have 
     1588special meanings.  @xref{Properties in Mode}. 
    16011589 
    16021590@item @var{symbol} 
    …… 
    16131601properties specified in @var{symbol}'s value are ignored.  This 
    16141602includes the text properties of strings in @var{symbol}'s value, as 
    1615 well as all @code{:eval} and @code{:propertize} forms in it. 
     1603well as all @code{:eval} and @code{:propertize} forms in it.  (The 
     1604reason for this is security: non-risky variables could be set 
     1605automatically from file variables without prompting the user.) 
    16161606 
    16171607@item (@var{string} @var{rest}@dots{}) 
    …… 
    20562046@end enumerate 
    20572047 
    2058   You use the @code{local-map} property to specify a keymap.  Like any 
    2059 keymap, it can bind character keys and function keys; but that has no 
    2060 effect, since it is impossible to move point into the mode line.  This 
    2061 keymap can only take real effect for mouse clicks. 
     2048  You can use the @code{local-map} property to specify a keymap.  This 
     2049keymap only takes real effect for mouse clicks; binding character keys 
     2050and function keys to it has no effect, since it is impossible to move 
     2051point into the mode line. 
    20622052 
    20632053  When the mode line refers to a variable which does not have a 
    …… 
    28902880Used (typically) for preprocessor commands. 
    28912881 
     2882@item font-lock-negation-char-face 
     2883@vindex font-lock-negation-char-face 
     2884Used (typically) for easily-overlooked negation characters. 
     2885 
    28922886@item font-lock-warning-face 
    28932887@vindex font-lock-warning-face 
    …… 
    30453039attend explicitly to both aspects. 
    30463040 
    3047   There are two ways to ensure correct identification of multiline 
     3041  There are three ways to ensure correct identification of multiline 
    30483042constructs: 
    30493043 
    …… 
    30563050so that the scanned text never starts or ends in the middle of a 
    30573051multiline construct. 
     3052@item 
     3053Add a function to @code{font-lock-extend-region-functions} that does 
     3054the @emph{identification} and extends the scan so that the scanned 
     3055text never starts or ends in the middle of a multiline construct. 
    30583056@end itemize 
    30593057 
    …… 
    31453143one the following variables: 
    31463144 
    3147 @defvar font-lock-extend-region-function 
     3145@defvar font-lock-extend-after-change-region-function 
    31483146This buffer-local variable is either @code{nil} or a function for 
    31493147Font-Lock to call to determine the region to scan and fontify.