/[emacs]/emacs/lispref/modes.texi
ViewVC logotype

Diff of /emacs/lispref/modes.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.49.2.1 by miles, Fri Apr 4 06:20:42 2003 UTC revision 1.49.2.2 by miles, Tue Oct 14 23:10:12 2003 UTC
# Line 1  Line 1 
1  @c -*-texinfo-*-  @c -*-texinfo-*-
2  @c This is part of the GNU Emacs Lisp Reference Manual.  @c This is part of the GNU Emacs Lisp Reference Manual.
3  @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999  @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003
4  @c   Free Software Foundation, Inc.  @c   Free Software Foundation, Inc.
5  @c See the file elisp.texi for copying conditions.  @c See the file elisp.texi for copying conditions.
6  @setfilename ../info/modes  @setfilename ../info/modes
7  @node Modes, Documentation,  Keymaps, Top  @node Modes, Documentation, Keymaps, Top
8  @chapter Major and Minor Modes  @chapter Major and Minor Modes
9  @cindex mode  @cindex mode
10    
# Line 236  setting up a buffer-local value for the Line 236  setting up a buffer-local value for the
236  @item  @item
237  The mode should specify how Imenu should find the definitions or  The mode should specify how Imenu should find the definitions or
238  sections of a buffer, by setting up a buffer-local value for the  sections of a buffer, by setting up a buffer-local value for the
239  variable @code{imenu-generic-expression} or  variable @code{imenu-generic-expression}, for the pair of variables
240    @code{imenu-prev-index-position-function} and
241    @code{imenu-extract-index-name-function}, or for the variable
242  @code{imenu-create-index-function} (@pxref{Imenu}).  @code{imenu-create-index-function} (@pxref{Imenu}).
243    
244  @item  @item
# Line 263  other packages would interfere with them Line 265  other packages would interfere with them
265  @cindex major mode hook  @cindex major mode hook
266  Each major mode should have a @dfn{mode hook} named  Each major mode should have a @dfn{mode hook} named
267  @code{@var{modename}-mode-hook}.  The major mode command should run that  @code{@var{modename}-mode-hook}.  The major mode command should run that
268  hook, with @code{run-hooks}, as the very last thing it  hook, with @code{run-mode-hooks}, as the very last thing it
269  does.  @xref{Hooks}.  does.  @xref{Hooks}.
270    
271  @item  @item
272  The major mode command may also run the hooks of some more basic modes.  The major mode command may start by calling some other major mode
273  For example, @code{indented-text-mode} runs @code{text-mode-hook} as  command (called the @dfn{parent mode}) and then alter some of its
274  well as @code{indented-text-mode-hook}.  It may run these other hooks  settings.  A mode that does this is called a @dfn{derived mode}.  The
275  immediately before the mode's own hook (that is, after everything else),  recommended way to define one is to use @code{define-derived-mode},
276  or it may run them earlier.  but this is not required.  Such a mode should use
277    @code{delay-mode-hooks} around its entire body, including the call to
278    the parent mode command and the final call to @code{run-mode-hooks}.
279    (Using @code{define-derived-mode} does this automatically.)
280    
281  @item  @item
282  If something special should be done if the user switches a buffer from  If something special should be done if the user switches a buffer from
# Line 283  If this mode is appropriate only for spe Line 288  If this mode is appropriate only for spe
288  major mode command symbol should have a property named @code{mode-class}  major mode command symbol should have a property named @code{mode-class}
289  with value @code{special}, put on as follows:  with value @code{special}, put on as follows:
290    
291  @cindex @code{mode-class} property  @kindex mode-class @r{(property)}
292  @cindex @code{special}  @cindex @code{special}
293  @example  @example
294  (put 'funny-mode 'mode-class 'special)  (put 'funny-mode 'mode-class 'special)
# Line 359  inherit all the commands defined in this Line 364  inherit all the commands defined in this
364  @end group  @end group
365  @end smallexample  @end smallexample
366    
367    Here is the complete major mode function definition for Text mode:    This was formerly the complete major mode function definition for Text mode:
368    
369  @smallexample  @smallexample
370  @group  @group
# Line 388  Turning on text-mode runs the hook `text Line 393  Turning on text-mode runs the hook `text
393  @group  @group
394    (setq mode-name "Text")    (setq mode-name "Text")
395    (setq major-mode 'text-mode)    (setq major-mode 'text-mode)
396    (run-hooks 'text-mode-hook))      ; @r{Finally, this permits the user to}    (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
397                                      ;   @r{customize the mode with a hook.}                                      ;   @r{customize the mode with a hook.}
398  @end group  @end group
399  @end smallexample  @end smallexample
# Line 543  if that value is non-nil." Line 548  if that value is non-nil."
548  @group  @group
549    (setq imenu-case-fold-search t)    (setq imenu-case-fold-search t)
550    (set-syntax-table lisp-mode-syntax-table)    (set-syntax-table lisp-mode-syntax-table)
551    (run-hooks 'lisp-mode-hook))           ; @r{This permits the user to use a}    (run-mode-hooks 'lisp-mode-hook))           ; @r{This permits the user to use a}
552                                           ;   @r{hook to customize the mode.}                                           ;   @r{hook to customize the mode.}
553  @end group  @end group
554  @end smallexample  @end smallexample
# Line 819  minor modes in effect. Line 824  minor modes in effect.
824  way to insert the necessary hook into the rest of Emacs.  Minor mode  way to insert the necessary hook into the rest of Emacs.  Minor mode
825  keymaps make this easier than it used to be.  keymaps make this easier than it used to be.
826    
827    @defvar minor-mode-list
828    The value of this variable is a list of all minor mode commands.
829    @end defvar
830    
831  @menu  @menu
832  * Minor Mode Conventions::      Tips for writing a minor mode.  * Minor Mode Conventions::      Tips for writing a minor mode.
833  * Keymaps and Minor Modes::     How a minor mode can have its own keymap.  * Keymaps and Minor Modes::     How a minor mode can have its own keymap.
# Line 864  Define a command whose name is the same Line 873  Define a command whose name is the same
873  Its job is to enable and disable the mode by setting the variable.  Its job is to enable and disable the mode by setting the variable.
874    
875  The command should accept one optional argument.  If the argument is  The command should accept one optional argument.  If the argument is
876  @code{nil}, it should toggle the mode (turn it on if it is off, and off  @code{nil}, it should toggle the mode (turn it on if it is off, and
877  if it is on).  Otherwise, it should turn the mode on if the argument is  off if it is on).  It should turn the mode on if the argument is a
878  a positive integer, a symbol other than @code{nil} or @code{-}, or a  positive integer, the symbol @code{t}, or a list whose @sc{car} is one
879  list whose @sc{car} is such an integer or symbol; it should turn the  of those.  It should turn the mode off if the argument is a negative
880  mode off otherwise.  integer or zero, the symbol @code{-}, or a list whose @sc{car} is one
881    of those.  The meaning of other arguments is not specified.
882    
883  Here is an example taken from the definition of @code{transient-mark-mode}.  Here is an example taken from the definition of @code{transient-mark-mode}.
884  It shows the use of @code{transient-mark-mode} as a variable that enables or  It shows the use of @code{transient-mark-mode} as a variable that enables or
# Line 980  characters are reserved for major modes. Line 990  characters are reserved for major modes.
990  implementing a mode in one self-contained definition.  It supports only  implementing a mode in one self-contained definition.  It supports only
991  buffer-local minor modes, not global ones.  buffer-local minor modes, not global ones.
992    
993  @defmac define-minor-mode mode doc &optional init-value mode-indicator keymap body...  @defmac define-minor-mode mode doc [init-value [lighter [keymap keyword-args... body...]]]
994  @tindex define-minor-mode  @tindex define-minor-mode
995  This macro defines a new minor mode whose name is @var{mode} (a symbol).  This macro defines a new minor mode whose name is @var{mode} (a
996  It defines a command named @var{mode} to toggle the minor  symbol).  It defines a command named @var{mode} to toggle the minor
997  mode, with @var{doc} as its documentation string.  It also defines a  mode, with @var{doc} as its documentation string.  It also defines a
998  variable named @var{mode}, which is set to @code{t} or @code{nil} by  variable named @var{mode}, which is set to @code{t} or @code{nil} by
999  enabling or disabling the mode.  The variable is initialized to  enabling or disabling the mode.  The variable is initialized to
1000  @var{init-value}.  @var{init-value}.
1001    
1002  The command named @var{mode} finishes by executing the @var{body} forms,  The string @var{lighter} says what to display in the mode line
 if any, after it has performed the standard actions such as setting  
 the variable named @var{mode}.  
   
 The string @var{mode-indicator} says what to display in the mode line  
1003  when the mode is enabled; if it is @code{nil}, the mode is not displayed  when the mode is enabled; if it is @code{nil}, the mode is not displayed
1004  in the mode line.  in the mode line.
1005    
# Line 1004  specifying bindings in this form: Line 1010  specifying bindings in this form:
1010  @example  @example
1011  (@var{key-sequence} . @var{definition})  (@var{key-sequence} . @var{definition})
1012  @end example  @end example
1013    
1014    The @var{keyword-args} consist of keywords followed by corresponding
1015    values.  A few keywords have special meanings:
1016    
1017    @table @code
1018    @item :global @var{global}
1019    If non-@code{nil} specifies that the minor mode should be global.
1020    By default, minor modes are buffer-local.
1021    
1022    @item :init-value @var{init-value}
1023    This is equivalent to specifying @var{init-value} positionally.
1024    
1025    @item :lighter @var{lighter}
1026    This is equivalent to specifying @var{lighter} positionally.
1027    
1028    @item :keymap @var{keymap}
1029    This is equivalent to specifying @var{keymap} positionally.
1030    @end table
1031    
1032    Any other keyword arguments are passed passed directly to the
1033    @code{defcustom} generated for the variable @var{mode}.
1034    
1035    The command named @var{mode} finishes by executing the @var{body} forms,
1036    if any, after it has performed the standard actions such as setting
1037    the variable named @var{mode}.
1038  @end defmac  @end defmac
1039    
1040    @findex easy-mmode-define-minor-mode
1041      The name @code{easy-mmode-define-minor-mode} is an alias
1042    for this macro.
1043    
1044    Here is an example of using @code{define-minor-mode}:    Here is an example of using @code{define-minor-mode}:
1045    
1046  @smallexample  @smallexample
# Line 1027  See the command \\[hungry-electric-delet Line 1062  See the command \\[hungry-electric-delet
1062     ("\C-\M-\^?"     ("\C-\M-\^?"
1063      . (lambda ()      . (lambda ()
1064          (interactive)          (interactive)
1065          (hungry-electric-delete t)))))          (hungry-electric-delete t))))
1066     :group 'hunger)
1067  @end smallexample  @end smallexample
1068    
1069  @noindent  @noindent
# Line 1036  This defines a minor mode named ``Hungry Line 1072  This defines a minor mode named ``Hungry
1072  which indicates whether the mode is enabled, and a variable named  which indicates whether the mode is enabled, and a variable named
1073  @code{hungry-mode-map} which holds the keymap that is active when the  @code{hungry-mode-map} which holds the keymap that is active when the
1074  mode is enabled.  It initializes the keymap with key bindings for  mode is enabled.  It initializes the keymap with key bindings for
1075  @kbd{C-@key{DEL}} and @kbd{C-M-@key{DEL}}.  @kbd{C-@key{DEL}} and @kbd{C-M-@key{DEL}}.  It puts the variable
1076    @code{hungry-mode} into custom group @code{hunger}.  There are no
1077    @var{body} forms---many minor modes don't need any.
1078    
1079      Here's an equivalent way to write it:
1080    
1081  @findex easy-mmode-define-minor-mode  @smallexample
1082    The name @code{easy-mmode-define-minor-mode} is an alias  (define-minor-mode hungry-mode
1083  for this macro.    "Toggle Hungry mode.
1084    With no argument, this command toggles the mode.
1085    Non-null prefix argument turns on the mode.
1086    Null prefix argument turns off the mode.
1087    
1088    When Hungry mode is enabled, the control delete key
1089    gobbles all preceding whitespace except the last.
1090    See the command \\[hungry-electric-delete]."
1091     ;; The initial value.
1092     :initial-value nil
1093     ;; The indicator for the mode line.
1094     :lighter " Hungry"
1095     ;; The minor mode bindings.
1096     :keymap
1097     '(("\C-\^?" . hungry-electric-delete)
1098       ("\C-\M-\^?"
1099        . (lambda ()
1100            (interactive)
1101            (hungry-electric-delete t))))
1102     :group 'hunger)
1103    @end smallexample
1104    
1105  @node Mode Line Format  @node Mode Line Format
1106  @section Mode Line Format  @section Mode-Line Format
1107  @cindex mode line  @cindex mode line
1108    
1109    Each Emacs window (aside from minibuffer windows) typically has a mode    Each Emacs window (aside from minibuffer windows) typically has a mode
# Line 1104  actually appears. Line 1163  actually appears.
1163  * %-Constructs::          Putting information into a mode line.  * %-Constructs::          Putting information into a mode line.
1164  * Properties in Mode::    Using text properties in the mode line.  * Properties in Mode::    Using text properties in the mode line.
1165  * Header Lines::          Like a mode line, but at the top.  * Header Lines::          Like a mode line, but at the top.
1166    * Emulating Mode Line::   Formatting text as the mode line would.
1167  @end menu  @end menu
1168    
1169  @node Mode Line Data  @node Mode Line Data
1170  @subsection The Data Structure of the Mode Line  @subsection The Data Structure of the Mode Line
1171  @cindex mode line construct  @cindex mode-line construct
1172    
1173    The mode line contents are controlled by a data structure of lists,    The mode-line contents are controlled by a data structure of lists,
1174  strings, symbols, and numbers kept in buffer-local variables.  The data  strings, symbols, and numbers kept in buffer-local variables.  The data
1175  structure is called a @dfn{mode line construct}, and it is built in  structure is called a @dfn{mode-line construct}, and it is built in
1176  recursive fashion out of simpler mode line constructs.  The same data  recursive fashion out of simpler mode-line constructs.  The same data
1177  structure is used for constructing frame titles (@pxref{Frame Titles})  structure is used for constructing frame titles (@pxref{Frame Titles})
1178  and header lines (@pxref{Header Lines}).  and header lines (@pxref{Header Lines}).
1179    
1180  @defvar mode-line-format  @defvar mode-line-format
1181  The value of this variable is a mode line construct with overall  The value of this variable is a mode-line construct with overall
1182  responsibility for the mode line format.  The value of this variable  responsibility for the mode-line format.  The value of this variable
1183  controls which other variables are used to form the mode line text, and  controls which other variables are used to form the mode-line text, and
1184  where they appear.  where they appear.
1185    
1186  If you set this variable to @code{nil} in a buffer, that buffer does not  If you set this variable to @code{nil} in a buffer, that buffer does not
1187  have a mode line.  (This feature was added in Emacs 21.)  have a mode line.  (This feature was added in Emacs 21.)
1188  @end defvar  @end defvar
1189    
1190    A mode line construct may be as simple as a fixed string of text, but    A mode-line construct may be as simple as a fixed string of text, but
1191  it usually specifies how to use other variables to construct the text.  it usually specifies how to use other variables to construct the text.
1192  Many of these variables are themselves defined to have mode line  Many of these variables are themselves defined to have mode-line
1193  constructs as their values.  constructs as their values.
1194    
1195    The default value of @code{mode-line-format} incorporates the values    The default value of @code{mode-line-format} incorporates the values
1196  of variables such as @code{mode-name} and @code{minor-mode-alist}.  of variables such as @code{mode-line-position} and
1197  Because of this, very few modes need to alter @code{mode-line-format}  @code{mode-line-modes} (which in turn incorporates the values of the
1198  itself.  For most purposes, it is sufficient to alter some of the  variables @code{mode-name} and @code{minor-mode-alist}).  Because of
1199  variables that @code{mode-line-format} refers to.  this, very few modes need to alter @code{mode-line-format} itself.  For
1200    most purposes, it is sufficient to alter some of the variables that
1201    @code{mode-line-format} either directly or indirectly refers to.
1202    
1203    A mode line construct may be a list, a symbol, or a string.  If the    A mode-line construct may be a list, a symbol, or a string.  If the
1204  value is a list, each element may be a list, a symbol, or a string.  value is a list, each element may be a list, a symbol, or a string.
1205    
1206    The mode line can display various faces, if the strings that control    The mode line can display various faces, if the strings that control
# Line 1149  mode line (@pxref{Standard Faces}). Line 1211  mode line (@pxref{Standard Faces}).
1211  @table @code  @table @code
1212  @cindex percent symbol in mode line  @cindex percent symbol in mode line
1213  @item @var{string}  @item @var{string}
1214  A string as a mode line construct is displayed verbatim in the mode line  A string as a mode-line construct is displayed verbatim in the mode line
1215  except for @dfn{@code{%}-constructs}.  Decimal digits after the @samp{%}  except for @dfn{@code{%}-constructs}.  Decimal digits after the @samp{%}
1216  specify the field width for space filling on the right (i.e., the data  specify the field width for space filling on the right (i.e., the data
1217  is left justified).  @xref{%-Constructs}.  is left justified).  @xref{%-Constructs}.
1218    
1219  @item @var{symbol}  @item @var{symbol}
1220  A symbol as a mode line construct stands for its value.  The value of  A symbol as a mode-line construct stands for its value.  The value of
1221  @var{symbol} is used as a mode line construct, in place of @var{symbol}.  @var{symbol} is used as a mode-line construct, in place of @var{symbol}.
1222  However, the symbols @code{t} and @code{nil} are ignored, as is any  However, the symbols @code{t} and @code{nil} are ignored, as is any
1223  symbol whose value is void.  symbol whose value is void.
1224    
1225  There is one exception: if the value of @var{symbol} is a string, it is  There is one exception: if the value of @var{symbol} is a string, it is
1226  displayed verbatim: the @code{%}-constructs are not recognized.  displayed verbatim: the @code{%}-constructs are not recognized.
1227    
1228    Unless @var{symbol} is marked as ``risky'' (i.e., it has a
1229    non-@code{nil} @code{risky-local-variable} property), all properties in
1230    any strings, as well as all @code{:eval} and @code{:propertize} forms in
1231    the value of that symbol will be ignored.
1232    
1233  @item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{})  @item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{})
1234  A list whose first element is a string or list means to process all the  A list whose first element is a string or list means to process all the
1235  elements recursively and concatenate the results.  This is the most  elements recursively and concatenate the results.  This is the most
1236  common form of mode line construct.  common form of mode-line construct.
1237    
1238  @item (:eval @var{form})  @item (:eval @var{form})
1239  A list whose first element is the symbol @code{:eval} says to evaluate  A list whose first element is the symbol @code{:eval} says to evaluate
1240  @var{form}, and use the result as a string to display.  @var{form}, and use the result as a string to display.
1241  (This feature is new as of Emacs 21.)  (This feature is new as of Emacs 21.)
1242    
1243    @item (:propertize @var{elt} @var{props}@dots{})
1244    A list whose first element is the symbol @code{:propertize} says to
1245    process the mode-line construct @var{elt} recursively and add the text
1246    properties specified by @var{props} to the result.  The argument
1247    @var{props} should consist of zero or more pairs @var{text-property}
1248    @var{value}.  (This feature is new as of Emacs 21.4.)
1249    @c FIXME: This might be Emacs 21.5.
1250    
1251  @item (@var{symbol} @var{then} @var{else})  @item (@var{symbol} @var{then} @var{else})
1252  A list whose first element is a symbol that is not a keyword specifies a  A list whose first element is a symbol that is not a keyword specifies a
1253  conditional.  Its meaning depends on the value of @var{symbol}.  If the  conditional.  Its meaning depends on the value of @var{symbol}.  If the
1254  value is non-@code{nil}, the second element, @var{then}, is processed  value is non-@code{nil}, the second element, @var{then}, is processed
1255  recursively as a mode line element.  But if the value of @var{symbol} is  recursively as a mode-line element.  But if the value of @var{symbol} is
1256  @code{nil}, the third element, @var{else}, is processed recursively.  @code{nil}, the third element, @var{else}, is processed recursively.
1257  You may omit @var{else}; then the mode line element displays nothing if  You may omit @var{else}; then the mode-line element displays nothing if
1258  the value of @var{symbol} is @code{nil}.  the value of @var{symbol} is @code{nil}.
1259    
1260  @item (@var{width} @var{rest}@dots{})  @item (@var{width} @var{rest}@dots{})
1261  A list whose first element is an integer specifies truncation or  A list whose first element is an integer specifies truncation or
1262  padding of the results of @var{rest}.  The remaining elements  padding of the results of @var{rest}.  The remaining elements
1263  @var{rest} are processed recursively as mode line constructs and  @var{rest} are processed recursively as mode-line constructs and
1264  concatenated together.  Then the result is space filled (if  concatenated together.  Then the result is space filled (if
1265  @var{width} is positive) or truncated (to @minus{}@var{width} columns,  @var{width} is positive) or truncated (to @minus{}@var{width} columns,
1266  if @var{width} is negative) on the right.  if @var{width} is negative) on the right.
# Line 1217  directory. Line 1292  directory.
1292  @end group  @end group
1293  @group  @group
1294     ;; @r{Note that this is evaluated while making the list.}     ;; @r{Note that this is evaluated while making the list.}
1295     ;; @r{It makes a mode line construct which is just a string.}     ;; @r{It makes a mode-line construct which is just a string.}
1296     (getenv "HOST")     (getenv "HOST")
1297  @end group  @end group
1298     ":"     ":"
# Line 1234  directory. Line 1309  directory.
1309     '(which-func-mode ("" which-func-format "--"))     '(which-func-mode ("" which-func-format "--"))
1310     '(line-number-mode "L%l--")     '(line-number-mode "L%l--")
1311     '(column-number-mode "C%c--")     '(column-number-mode "C%c--")
1312     '(-3 . "%p")     '(-3 "%p")
1313     "-%-"))     "-%-"))
1314  @end group  @end group
1315  @end example  @end example
# Line 1274  Changing this variable does not force an Line 1349  Changing this variable does not force an
1349    
1350  @defvar mode-line-frame-identification  @defvar mode-line-frame-identification
1351  This variable identifies the current frame.  The default value is  This variable identifies the current frame.  The default value is
1352  @code{" "} if you are using a window system which can show multiple  @code{"  "} if you are using a window system which can show multiple
1353  frames, or @code{"-%F "} on an ordinary terminal which shows only one  frames, or @code{"-%F  "} on an ordinary terminal which shows only one
1354  frame at a time.  frame at a time.
1355  @end defvar  @end defvar
1356    
# Line 1285  default value is @code{("%12b")}, which Line 1360  default value is @code{("%12b")}, which
1360  with spaces to at least 12 columns.  with spaces to at least 12 columns.
1361  @end defvar  @end defvar
1362    
1363  @defvar global-mode-string  @defvar mode-line-position
1364  This variable holds a mode line spec that appears in the mode line by  This variable indicates the position in the buffer.  Here is a
1365  default, just after the buffer name.  The command @code{display-time}  simplified version of its default value.  The actual default value
1366  sets @code{global-mode-string} to refer to the variable  also specifies addition of the @code{help-echo} text property.
 @code{display-time-string}, which holds a string containing the time and  
 load information.  
1367    
1368  The @samp{%M} construct substitutes the value of  @example
1369  @code{global-mode-string}, but that is obsolete, since the variable is  @group
1370  included in the mode line from @code{mode-line-format}.  ((-3 "%p")
1371     (size-indication-mode (8 " of %I"))
1372    @end group
1373    @group
1374     (line-number-mode
1375      ((column-number-mode
1376        (10 " (%l,%c)")
1377        (6 " L%l")))
1378      ((column-number-mode
1379        (5 " C%c")))))
1380    @end group
1381    @end example
1382    
1383    This means that @code{mode-line-position} displays at least the buffer
1384    percentage and possibly the buffer size, the line number and the column
1385    number.
1386  @end defvar  @end defvar
1387    
1388    @defvar vc-mode
1389    The variable @code{vc-mode}, buffer-local in each buffer, records
1390    whether the buffer's visited file is maintained with version control,
1391    and, if so, which kind.  Its value is a string that appears in the mode
1392    line, or @code{nil} for no version control.
1393    @end defvar
1394    
1395    @defvar mode-line-modes
1396    This variable displays the buffer's major and minor modes.  Here is a
1397    simplified version of its default value.  The real default value also
1398    specifies addition of text properties.
1399    
1400    @example
1401    @group
1402    ("%[(" mode-name
1403     mode-line-process minor-mode-alist
1404     "%n" ")%]--")
1405    @end group
1406    @end example
1407    
1408    So @code{mode-line-modes} normally also displays the recursive editing
1409    level, information on the process status and whether narrowing is in
1410    effect.
1411    @end defvar
1412    
1413      The following three variables are used in @code{mode-line-modes}:
1414    
1415  @defvar mode-name  @defvar mode-name
1416  This buffer-local variable holds the ``pretty'' name of the current  This buffer-local variable holds the ``pretty'' name of the current
1417  buffer's major mode.  Each major mode should set this variable so that the  buffer's major mode.  Each major mode should set this variable so that the
1418  mode name will appear in the mode line.  mode name will appear in the mode line.
1419  @end defvar  @end defvar
1420    
1421    @defvar mode-line-process
1422    This buffer-local variable contains the mode-line information on process
1423    status in modes used for communicating with subprocesses.  It is
1424    displayed immediately following the major mode name, with no intervening
1425    space.  For example, its value in the @samp{*shell*} buffer is
1426    @code{(":%s")}, which allows the shell to display its status along
1427    with the major mode as: @samp{(Shell:run)}.  Normally this variable
1428    is @code{nil}.
1429    @end defvar
1430    
1431  @defvar minor-mode-alist  @defvar minor-mode-alist
1432  This variable holds an association list whose elements specify how the  This variable holds an association list whose elements specify how the
1433  mode line should indicate that a minor mode is active.  Each element of  mode line should indicate that a minor mode is active.  Each element of
# Line 1312  the @code{minor-mode-alist} should be a Line 1437  the @code{minor-mode-alist} should be a
1437  (@var{minor-mode-variable} @var{mode-line-string})  (@var{minor-mode-variable} @var{mode-line-string})
1438  @end example  @end example
1439    
1440  More generally, @var{mode-line-string} can be any mode line spec.  It  More generally, @var{mode-line-string} can be any mode-line spec.  It
1441  appears in the mode line when the value of @var{minor-mode-variable} is  appears in the mode line when the value of @var{minor-mode-variable}
1442  non-@code{nil}, and not otherwise.  These strings should begin with  is non-@code{nil}, and not otherwise.  These strings should begin with
1443  spaces so that they don't run together.  Conventionally, the  spaces so that they don't run together.  Conventionally, the
1444  @var{minor-mode-variable} for a specific mode is set to a non-@code{nil}  @var{minor-mode-variable} for a specific mode is set to a
1445  value when that minor mode is activated.  non-@code{nil} value when that minor mode is activated.
   
 The default value of @code{minor-mode-alist} is:  
   
 @example  
 @group  
 minor-mode-alist  
 @result{} ((vc-mode vc-mode)  
     (abbrev-mode " Abbrev")  
     (overwrite-mode overwrite-mode)  
     (auto-fill-function " Fill")  
     (defining-kbd-macro " Def")  
     (isearch-mode isearch-mode))  
 @end group  
 @end example  
1446    
1447  @code{minor-mode-alist} itself is not buffer-local.  Each variable  @code{minor-mode-alist} itself is not buffer-local.  Each variable
1448  mentioned in the alist should be buffer-local if its minor mode can be  mentioned in the alist should be buffer-local if its minor mode can be
1449  enabled separately in each buffer.  enabled separately in each buffer.
1450  @end defvar  @end defvar
1451    
1452  @defvar mode-line-process  @defvar global-mode-string
1453  This buffer-local variable contains the mode line information on process  This variable holds a mode-line spec that appears in the mode line by
1454  status in modes used for communicating with subprocesses.  It is  default, just after the buffer name.  The command @code{display-time}
1455  displayed immediately following the major mode name, with no intervening  sets @code{global-mode-string} to refer to the variable
1456  space.  For example, its value in the @samp{*shell*} buffer is  @code{display-time-string}, which holds a string containing the time and
1457  @code{(":%s")}, which allows the shell to display its status along  load information.
 with the major mode as: @samp{(Shell:run)}.  Normally this variable  
 is @code{nil}.  
 @end defvar  
   
   Some variables are used by @code{minor-mode-alist} to display  
 a string for various minor modes when enabled.  This is a typical  
 example:  
1458    
1459  @defvar vc-mode  The @samp{%M} construct substitutes the value of
1460  The variable @code{vc-mode}, buffer-local in each buffer, records  @code{global-mode-string}, but that is obsolete, since the variable is
1461  whether the buffer's visited file is maintained with version control,  included in the mode line from @code{mode-line-format}.
 and, if so, which kind.  Its value is a string that appears in the mode  
 line, or @code{nil} for no version control.  
1462  @end defvar  @end defvar
1463    
1464    The variable @code{default-mode-line-format} is where    The variable @code{default-mode-line-format} is where
# Line 1367  This variable holds the default @code{mo Line 1469  This variable holds the default @code{mo
1469  that do not override it.  This is the same as @code{(default-value  that do not override it.  This is the same as @code{(default-value
1470  'mode-line-format)}.  'mode-line-format)}.
1471    
1472  The default value of @code{default-mode-line-format} is this list:  Here is a simplified version of the default value of
1473    @code{default-mode-line-format}.  The real default value also
1474    specifies addition of text properties.
1475    
1476  @example  @example
1477  @group  @group
# Line 1378  The default value of @code{default-mode- Line 1482  The default value of @code{default-mode-
1482   mode-line-buffer-identification   mode-line-buffer-identification
1483  @end group  @end group
1484   "   "   "   "
1485   global-mode-string   mode-line-position
1486  @group   (vc-mode vc-mode)
1487   "   %[("   "   "
  ;; @r{@code{mode-line-mode-name} is a function}  
  ;; @r{that copies the mode name and adds text}  
  ;; @r{properties to make it mouse-sensitive.}  
  (:eval (mode-line-mode-name))  
  mode-line-process  
  minor-mode-alist  
  "%n"  
  ")%]--"  
 @end group  
1488  @group  @group
1489     mode-line-modes
1490   (which-func-mode ("" which-func-format "--"))   (which-func-mode ("" which-func-format "--"))
1491   (line-number-mode "L%l--")   (global-mode-string ("--" global-mode-string))
  (column-number-mode "C%c--")  
  (-3 . "%p")  
1492   "-%-")   "-%-")
1493  @end group  @end group
1494  @end example  @end example
# Line 1423  function.  @xref{Buffer File Name}. Line 1517  function.  @xref{Buffer File Name}.
1517  The title (only on a window system) or the name of the selected frame.  The title (only on a window system) or the name of the selected frame.
1518  @xref{Window Frame Parameters}.  @xref{Window Frame Parameters}.
1519    
1520    @item %i
1521    The size of the accessible part of the current buffer; basically
1522    @code{(- (point-max) (point-min))}.
1523    
1524    @item %I
1525    Like @samp{%i}, but the size is printed in a more readable way by using
1526    @samp{k} for 10^3, @samp{M} for 10^6, @samp{G} for 10^9, etc., to
1527    abbreviate.
1528    
1529  @item %l  @item %l
1530  The current line number of point, counting within the accessible portion  The current line number of point, counting within the accessible portion
1531  of the buffer.  of the buffer.
# Line 1497  The value of @code{global-mode-string}. Line 1600  The value of @code{global-mode-string}.
1600    
1601  @node Properties in Mode  @node Properties in Mode
1602  @subsection Properties in the Mode Line  @subsection Properties in the Mode Line
1603    @cindex text properties in the mode line
1604    
1605    Starting in Emacs 21, certain text properties are meaningful in the    Starting in Emacs 21, certain text properties are meaningful in the
1606  mode line.  The @code{face} property affects the appearance of text; the  mode line.  The @code{face} property affects the appearance of text; the
1607  @code{help-echo} property associate help strings with the text, and  @code{help-echo} property associate help strings with the text, and
1608  @code{local-map} can make the text mouse-sensitive.  @code{local-map} can make the text mouse-sensitive.
1609    
1610    There are three ways to specify text properties for text in the mode    There are four ways to specify text properties for text in the mode
1611  line:  line:
1612    
1613  @enumerate  @enumerate
1614  @item  @item
1615  Put a string with the @code{local-map} property directly into the  Put a string with a text property directly into the mode-line data
1616  mode-line data structure.  structure.
1617    
1618    @item
1619    Put a text property on a mode-line %-construct such as @samp{%12b}; then
1620    the expansion of the %-construct will have that same text property.
1621    
1622  @item  @item
1623  Put a @code{local-map} property on a mode-line %-construct  Use a @code{(:propertize @var{elt} @var{props}@dots{})} construct to
1624  such as @samp{%12b}; then the expansion of the %-construct  give @var{elt} a text property specified by @var{props}.
 will have that same text property.  
1625    
1626  @item  @item
1627  Use a list containing @code{:eval @var{form}} in the mode-line data  Use a list containing @code{:eval @var{form}} in the mode-line data
1628  structure, and make @var{form} evaluate to a string that has a  structure, and make @var{form} evaluate to a string that has a text
1629  @code{local-map} property.  property.
1630  @end enumerate  @end enumerate
1631    
1632    You use the @code{local-map} property to specify a keymap.  Like any    You use the @code{local-map} property to specify a keymap.  Like any
# Line 1534  keymap can only take real effect for mou Line 1641  keymap can only take real effect for mou
1641    
1642    Starting in Emacs 21, a window can have a @dfn{header line} at the    Starting in Emacs 21, a window can have a @dfn{header line} at the
1643  top, just as it can have a mode line at the bottom.  The header line  top, just as it can have a mode line at the bottom.  The header line
1644  feature works just like the mode line feature, except that it's  feature works just like the mode-line feature, except that it's
1645  controlled by different variables.  controlled by different variables.
1646    
1647  @tindex header-line-format  @tindex header-line-format
# Line 1553  that do not override it.  This is the sa Line 1660  that do not override it.  This is the sa
1660  It is normally @code{nil}, so that ordinary buffers have no header line.  It is normally @code{nil}, so that ordinary buffers have no header line.
1661  @end defvar  @end defvar
1662    
1663    @node Emulating Mode Line
1664    @subsection Emulating Mode-Line Formatting
1665    
1666      You can use the function @code{format-mode-line} to compute
1667    the text that would appear in a mode line or header line
1668    based on certain mode-line specification.
1669    
1670    @defun format-mode-line &optional format window no-props
1671    This function formats a line of text according to @var{format} as if
1672    it were generating the mode line for @var{window}, but instead of
1673    displaying the text in the mode line or the header line, it returns
1674    the text as a string.
1675    
1676    If @var{format} is @code{nil}, that means to use
1677    @code{mode-line-format} and return the text that would appear in the
1678    mode line.  If @var{format} is @code{t}, that means to use
1679    @code{header-line-format} so as to return the text that would appear
1680    in the header line (@code{""} if the window has no header line).
1681    The argument @var{window} defaults to the selected window.
1682    
1683    The value string normally has text properties that correspond to the
1684    faces, keymaps, etc., that the mode line would have.  If
1685    @var{no-props} is non-@code{nil}, the value has no text properties.
1686    @end defun
1687    
1688  @node Imenu  @node Imenu
1689  @section Imenu  @section Imenu
1690    
1691  @cindex Imenu  @cindex Imenu
1692    @dfn{Imenu} is a feature that lets users select a definition or    @dfn{Imenu} is a feature that lets users select a definition or
1693  section in the buffer, from a menu which lists all of them, to go  section in the buffer, from a menu which lists all of them, to go
1694  directly to that location in the buffer.  Imenu works by constructing a  directly to that location in the buffer.  Imenu works by constructing
1695  buffer index which lists the names and buffer positions of the  a buffer index which lists the names and buffer positions of the
1696  definitions, or other named portions of the buffer; then the user can  definitions, or other named portions of the buffer; then the user can
1697  choose one of them and move point to it.  This section explains how to  choose one of them and move point to it.  The user-level commands for
1698  customize how Imenu finds the definitions or buffer portions for a  using Imenu are described in the Emacs Manual (@pxref{Imenu,, Imenu,
1699    emacs, the Emacs Manual}).  This section explains how to customize
1700    Imenu's method of finding definitions or buffer portions for a
1701  particular major mode.  particular major mode.
1702    
1703    The usual and simplest way is to set the variable    The usual and simplest way is to set the variable
1704  @code{imenu-generic-expression}:  @code{imenu-generic-expression}:
1705    
1706  @defvar imenu-generic-expression  @defvar imenu-generic-expression
1707  This variable, if non-@code{nil}, specifies regular expressions for  This variable, if non-@code{nil}, is a list that specifies regular
1708  finding definitions for Imenu.  In the simplest case, elements should  expressions for finding definitions for Imenu.  Simple elements of
1709  look like this:  @code{imenu-generic-expression} look like this:
1710    
1711  @example  @example
1712  (@var{menu-title} @var{regexp} @var{subexp})  (@var{menu-title} @var{regexp} @var{index})
1713  @end example  @end example
1714    
1715  Here, if @var{menu-title} is non-@code{nil}, it says that the matches  Here, if @var{menu-title} is non-@code{nil}, it says that the matches
# Line 1585  for this element should go in a submenu Line 1719  for this element should go in a submenu
1719  in the top level of the buffer index.  in the top level of the buffer index.
1720    
1721  The second item in the list, @var{regexp}, is a regular expression  The second item in the list, @var{regexp}, is a regular expression
1722  (@pxref{Regular Expressions}); anything in the buffer that it matches is  (@pxref{Regular Expressions}); anything in the buffer that it matches
1723  considered a definition, something to mention in the buffer index.  The  is considered a definition, something to mention in the buffer index.
1724  third item, @var{subexp}, indicates which subexpression in @var{regexp}  The third item, @var{index}, is a non-negative integer that indicates
1725  matches the definition's name.  which subexpression in @var{regexp} matches the definition's name.
1726    
1727  An element can also look like this:  An element can also look like this:
1728    
# Line 1596  An element can also look like this: Line 1730  An element can also look like this:
1730  (@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{})  (@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{})
1731  @end example  @end example
1732    
1733  Each match for this element creates a special index item which, if  Like in the previous case, each match for this element creates an
1734  selected by the user, calls @var{function} with arguments consisting of  index item.  However, if this index item is selected by the user, it
1735  the item name, the buffer position, and @var{arguments}.  calls @var{function} with arguments consisting of the item name, the
1736    buffer position, and @var{arguments}.
1737    
1738  For Emacs Lisp mode, @var{pattern} could look like this:  For Emacs Lisp mode, @code{imenu-generic-expression} could look like
1739    this:
1740    
1741  @c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]  @c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]
1742  @example  @example
# Line 1624  Setting this variable makes it buffer-lo Line 1760  Setting this variable makes it buffer-lo
1760  @end defvar  @end defvar
1761    
1762  @defvar imenu-case-fold-search  @defvar imenu-case-fold-search
1763  This variable controls whether matching against  This variable controls whether matching against the regular
1764  @var{imenu-generic-expression} is case-sensitive: @code{t}, the default,  expressions in the value of @code{imenu-generic-expression} is
1765  means matching should ignore case.  case-sensitive: @code{t}, the default, means matching should ignore
1766    case.
1767    
1768  Setting this variable makes it buffer-local in the current buffer.  Setting this variable makes it buffer-local in the current buffer.
1769  @end defvar  @end defvar
# Line 1651  normally have symbol syntax, and thus to Line 1788  normally have symbol syntax, and thus to
1788  For example, Fortran mode uses it this way:  For example, Fortran mode uses it this way:
1789    
1790  @example  @example
1791    (setq imenu-syntax-alist '(("_$" . "w")))  (setq imenu-syntax-alist '(("_$" . "w")))
1792  @end example  @end example
1793    
1794  The @code{imenu-generic-expression} patterns can then use @samp{\\sw+}  The @code{imenu-generic-expression} regular expressions can then use
1795  instead of @samp{\\(\\sw\\|\\s_\\)+}.  Note that this technique may be  @samp{\\sw+} instead of @samp{\\(\\sw\\|\\s_\\)+}.  Note that this
1796  inconvenient when the mode needs to limit the initial character  technique may be inconvenient when the mode needs to limit the initial
1797  of a name to a smaller set of characters than are allowed in the rest  character of a name to a smaller set of characters than are allowed in
1798  of a name.  the rest of a name.
1799    
1800  Setting this variable makes it buffer-local in the current buffer.  Setting this variable makes it buffer-local in the current buffer.
1801  @end defvar  @end defvar
# Line 1691  Setting this variable makes it buffer-lo Line 1828  Setting this variable makes it buffer-lo
1828  variable @code{imenu-create-index-function}:  variable @code{imenu-create-index-function}:
1829    
1830  @defvar imenu-create-index-function  @defvar imenu-create-index-function
1831  This variable specifies the function to use for creating a buffer index.  This variable specifies the function to use for creating a buffer
1832  The function should take no arguments, and return an index for the  index.  The function should take no arguments, and return an index
1833  current buffer.  It is called within @code{save-excursion}, so where it  alist for the current buffer.  It is called within
1834  leaves point makes no difference.  @code{save-excursion}, so where it leaves point makes no difference.
   
 The default value is a function that uses  
 @code{imenu-generic-expression} to produce the index alist.  If you  
 specify a different function, then @code{imenu-generic-expression} is  
 not used.  
1835    
1836  Setting this variable makes it buffer-local in the current buffer.  The index alist can have three types of elements.  Simple elements
1837  @end defvar  look like this:
1838    
1839  @defvar imenu-index-alist  @example
1840  This variable holds the index alist for the current buffer.  (@var{index-name} . @var{index-position})
1841  Setting it makes it buffer-local in the current buffer.  @end example
1842    
1843  Simple elements in the alist look like @code{(@var{index-name}  Selecting a simple element has the effect of moving to position
1844  . @var{index-position})}.  Selecting a simple element has the effect of  @var{index-position} in the buffer.  Special elements look like this:
 moving to position @var{index-position} in the buffer.  
1845    
1846  Special elements look like @code{(@var{index-name} @var{position}  @example
1847  @var{function} @var{arguments}@dots{})}.  Selecting a special element  (@var{index-name} @var{index-position} @var{function} @var{arguments}@dots{})
1848  performs  @end example
1849    
1850    Selecting a special element performs:
1851    
1852  @example  @example
1853  (funcall @var{function} @var{index-name} @var{position} @var{arguments}@dots{})  (funcall @var{function}
1854             @var{index-name} @var{index-position} @var{arguments}@dots{})
1855  @end example  @end example
1856    
1857  A nested sub-alist element looks like @code{(@var{index-name}  A nested sub-alist element looks like this:
1858  @var{sub-alist})}.  
1859    @example
1860    (@var{menu-title} @var{sub-alist})
1861    @end example
1862    
1863    It creates the submenu @var{menu-title} specified by @var{sub-alist}.
1864    
1865    The default value of @code{imenu-create-index-function} is
1866    @code{imenu-default-create-index-function}.  This function uses
1867    @code{imenu-prev-index-position-function} and
1868    @code{imenu-extract-index-name-function} to produce the index alist.
1869    However, if either of these two variables is @code{nil}, the default
1870    function uses @code{imenu-generic-expression} instead.
1871    
1872    Setting this variable makes it buffer-local in the current buffer.
1873  @end defvar  @end defvar
1874    
1875  @node Font Lock Mode  @node Font Lock Mode
# Line 1884  specifies the face name to use for highl Line 2032  specifies the face name to use for highl
2032  ("fubar" . fubar-face)  ("fubar" . fubar-face)
2033  @end example  @end example
2034    
2035    The value of @var{facename} is usually a face name (a symbol), but it
2036    can also be a list of the form
2037    
2038    @example
2039    (face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{})
2040    @end example
2041    
2042    to specify various text properties to put on the text that matches.
2043    If you do this, be sure to add the other text property names that you
2044    set in this way to the value of @code{font-lock-extra-managed-props}
2045    so that the properties will also be cleared out when they are no longer
2046    appropriate.
2047    
2048  @item (@var{matcher} . @var{highlighter})  @item (@var{matcher} . @var{highlighter})
2049  In this kind of element, @var{highlighter} is a list  In this kind of element, @var{highlighter} is a list
2050  which specifies how to highlight matches found by @var{matcher}.  which specifies how to highlight matches found by @var{matcher}.
# Line 1898  of the match to fontify (0 means the ent Line 2059  of the match to fontify (0 means the ent
2059  subelement, @var{facename}, specifies the face, as described above.  subelement, @var{facename}, specifies the face, as described above.
2060    
2061  The last two values in @var{highlighter}, @var{override} and  The last two values in @var{highlighter}, @var{override} and
2062  @var{laxmatch}, are flags.  If @var{override} is @code{t}, this element  @var{laxmatch}, are flags.  If @var{override} is @code{t}, this
2063  can override existing fontification made by previous elements of  element can override existing fontification made by previous elements
2064  @code{font-lock-keywords}.  If it is @code{keep}, then each character is  of @code{font-lock-keywords}.  If it is @code{keep}, then each
2065  fontified if it has not been fontified already by some other element.  character is fontified if it has not been fontified already by some
2066  If it is @code{prepend}, the face @var{facename} is added to the  other element.  If it is @code{prepend}, the face @var{facename} is
2067  beginning of the @code{face} property.  If it is @code{append}, the face  added to the beginning of the @code{font-lock-face} property.  If it
2068  @var{facename} is added to the end of the @code{face} property.  is @code{append}, the face @var{facename} is added to the end of the
2069    @code{font-lock-face} property.
2070    
2071  If @var{laxmatch} is non-@code{nil}, it means there should be no error  If @var{laxmatch} is non-@code{nil}, it means there should be no error
2072  if there is no subexpression numbered @var{subexp} in @var{matcher}.  if there is no subexpression numbered @var{subexp} in @var{matcher}.
# Line 2059  are @code{mark-defun} for programming mo Line 2221  are @code{mark-defun} for programming mo
2221  textual modes.  textual modes.
2222  @end defvar  @end defvar
2223    
2224    @defvar font-lock-extra-managed-props
2225    Additional properties (other than @code{font-lock-face}) that are
2226    being managed by Font Lock mode.  Font Lock mode normally manages only
2227    the @code{font-lock-face} property; if you want it to manage others as
2228    well, you must specify them in a @var{facename} in
2229    @code{font-lock-keywords} as well as adding them to this list.
2230    @end defvar
2231    
2232  @node Levels of Font Lock  @node Levels of Font Lock
2233  @subsection Levels of Font Lock  @subsection Levels of Font Lock
2234    
# Line 2098  fontification, you may use the special c Line 2268  fontification, you may use the special c
2268  @code{font-lock-face} (@pxref{Special Properties}).  This property  @code{font-lock-face} (@pxref{Special Properties}).  This property
2269  acts just like the explicit @code{face} property, but its activation  acts just like the explicit @code{face} property, but its activation
2270  is toggled when the user calls @kbd{M-x font-lock-mode}.  Using  is toggled when the user calls @kbd{M-x font-lock-mode}.  Using
2271  @code{font-lock-face} is especially conveninent for special modes  @code{font-lock-face} is especially convenient for special modes
2272  which construct their text programmatically, such as  which construct their text programmatically, such as
2273  @code{list-buffers} and @code{occur}.  @code{list-buffers} and @code{occur}.
2274    
2275  If your mode does not use any of the other machinery of Font Lock  If your mode does not use any of the other machinery of Font Lock
2276  (i.e. it only uses the @code{font-lock-face} property), you can tell  (i.e. it only uses the @code{font-lock-face} property), you can tell
2277  Emacs not to load all of font-lock.el (unless it's already loaded), by  Emacs not to load all of font-lock.el (unless it's already loaded), by
2278  setting the variable @code{font-lock-core-only} to non-nil as part of  setting the variable @code{font-lock-core-only} to non-@code{nil} as
2279  the @code{font-lock-defaults} settings.  Here is the canonical way to  part of the @code{font-lock-defaults} settings.  Here is the canonical
2280  do this:  way to do this:
2281    
2282  @example  @example
2283  (set (make-local-variable 'font-lock-defaults)  (set (make-local-variable 'font-lock-defaults)
# Line 2162  where they are defined and where they ar Line 2332  where they are defined and where they ar
2332  @vindex font-lock-constant-face  @vindex font-lock-constant-face
2333  Used (typically) for constant names.  Used (typically) for constant names.
2334    
2335    @item font-lock-preprocessor-face
2336    @vindex font-lock-preprocessor-face
2337    Used (typically) for preprocessor commands.
2338    
2339  @item font-lock-warning-face  @item font-lock-warning-face
2340  @vindex font-lock-warning-face  @vindex font-lock-warning-face
2341  Used (typically) for constructs that are peculiar, or that greatly  Used (typically) for constructs that are peculiar, or that greatly
# Line 2178  automatically.  This is useful in langua Line 2352  automatically.  This is useful in langua
2352  table by itself is not sufficient.  table by itself is not sufficient.
2353    
2354  @defvar font-lock-syntactic-keywords  @defvar font-lock-syntactic-keywords
2355  This variable enables and controls syntactic Font Lock.  Its value  This variable enables and controls syntactic Font Lock.  It is
2356  should be a list of elements of this form:  normally set via @code{font-lock-defaults}.  Its value should be a
2357    list of elements of this form:
2358    
2359  @example  @example
2360  (@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch})  (@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch})
# Line 2193  sort of element of @code{font-lock-keywo Line 2368  sort of element of @code{font-lock-keywo
2368  @end example  @end example
2369    
2370  However, instead of specifying the value @var{facename} to use for the  However, instead of specifying the value @var{facename} to use for the
2371  @code{face} property, it specifies the value @var{syntax} to use for the  @code{face} property, it specifies the value @var{syntax} to use for
2372  @code{syntax-table} property.  Here, @var{syntax} can be a variable  the @code{syntax-table} property.  Here, @var{syntax} can be a string
2373  whose value is a syntax table, a syntax entry of the form  (as taken by @code{modify-syntax-entry}), a syntax table, a cons cell
2374  @code{(@var{syntax-code} . @var{matching-char})}, or an expression whose  (as returned by @code{string-to-syntax}), or an expression whose value
2375  value is one of those two types.  is one of those two types.  @var{override} cannot be @code{prepend} or
2376    @code{append}.
2377    
2378    For example, an element of the form:
2379    
2380    @example
2381    ("\\$\\(#\\)" 1 ".")
2382    @end example
2383    
2384    highlights syntactically a hash character when following a dollar
2385    character, with a SYNTAX of @code{"."} (meaning punctuation syntax).
2386    Assuming that the buffer syntax table specifies hash characters to
2387    have comment start syntax, the element will only highlight hash
2388    characters that do not follow dollar characters as comments
2389    syntactically.
2390    
2391    An element of the form:
2392    
2393    @example
2394     ("\\('\\).\\('\\)"
2395      (1 "\"")
2396      (2 "\""))
2397    @end example
2398    
2399    highlights syntactically both single quotes which surround a single
2400    character, with a SYNTAX of @code{"\""} (meaning string quote syntax).
2401    Assuming that the buffer syntax table does not specify single quotes
2402    to have quote syntax, the element will only highlight single quotes of
2403    the form @samp{'@var{c}'} as strings syntactically.  Other forms, such
2404    as @samp{foo'bar} or @samp{'fubar'}, will not be highlighted as
2405    strings.
2406    
2407  @end defvar  @end defvar
2408    
2409  @node Hooks  @node Hooks
# Line 2227  are used in other contexts too.  For exa Line 2433  are used in other contexts too.  For exa
2433    
2434    The recommended way to add a hook function to a normal hook is by    The recommended way to add a hook function to a normal hook is by
2435  calling @code{add-hook} (see below).  The hook functions may be any of  calling @code{add-hook} (see below).  The hook functions may be any of
2436  the valid kinds of functions that @code{funcall} accepts (@pxref{What Is  the valid kinds of functions that @code{funcall} accepts (@pxref{What
2437  a Function}).  Most normal hook variables are initially void;  Is a Function}).  Most normal hook variables are initially void;
2438  @code{add-hook} knows how to deal with this.  @code{add-hook} knows how to deal with this.  You can add hooks either
2439    globally or buffer-locally with @code{add-hook}.
2440    
2441  @cindex abnormal hook  @cindex abnormal hook
2442    If the hook variable's name does not end with @samp{-hook}, that    If the hook variable's name does not end with @samp{-hook}, that
# Line 2260  run particular hooks.  This function cal Line 2467  run particular hooks.  This function cal
2467  been added with @code{add-hook}.  been added with @code{add-hook}.
2468    
2469  @defun run-hooks &rest hookvars  @defun run-hooks &rest hookvars
2470  This function takes one or more hook variable names as arguments, and  This function takes one or more normal hook variable names as
2471  runs each hook in turn.  Each argument should be a symbol that is a hook  arguments, and runs each hook in turn.  Each argument should be a
2472  variable.  These arguments are processed in the order specified.  symbol that is a normal hook variable.  These arguments are processed
2473    in the order specified.
2474    
2475  If a hook variable has a non-@code{nil} value, that value may be a  If a hook variable has a non-@code{nil} value, that value may be a
2476  function or a list of functions.  If the value is a function (either a  function or a list of functions.  (The former option is considered
2477  lambda expression or a symbol with a function definition), it is called.  obsolete.)  If the value is a function (either a lambda expression or
2478  If it is a list, the elements are called, in order.  The hook functions  a symbol with a function definition), it is called.  If it is a list
2479  are called with no arguments.  Nowadays, storing a single function in  that isn't a function, its elements are called, consecutively.  All
2480  the hook variable is semi-obsolete; you should always use a list of  the hook functions are called with no arguments.
 functions.  
2481    
2482  For example, here's how @code{emacs-lisp-mode} runs its mode hook:  For example, here's how @code{emacs-lisp-mode} runs its mode hook:
2483    
# Line 2279  For example, here's how @code{emacs-lisp Line 2486  For example, here's how @code{emacs-lisp
2486  @end example  @end example
2487  @end defun  @end defun
2488    
2489    @defun run-mode-hooks &rest hookvars
2490    Like @code{run-hooks}, but is affected by the @code{delay-mode-hooks}
2491    macro.
2492    @end defun
2493    
2494    @defmac delay-mode-hooks body...
2495    This macro executes the @var{body} forms but defers all calls to
2496    @code{run-mode-hooks} within them until the end of @var{body}.
2497    This macro enables a derived mode to arrange not to run
2498    its parent modes' mode hooks until the end.
2499    @end defmac
2500    
2501  @defun run-hook-with-args hook &rest args  @defun run-hook-with-args hook &rest args
2502  This function is the way to run an abnormal hook which passes arguments  This function is the way to run an abnormal hook and always call all
2503  to the hook functions.  It calls each of the hook functions, passing  of the hook functions.  It calls each of the hook functions one by
2504  each of them the arguments @var{args}.  one, passing each of them the arguments @var{args}.
2505  @end defun  @end defun
2506    
2507  @defun run-hook-with-args-until-failure hook &rest args  @defun run-hook-with-args-until-failure hook &rest args
2508  This function is the way to run an abnormal hook which passes arguments  This function is the way to run an abnormal hook until one of the hook
2509  to the hook functions, and stops as soon as any hook function fails.  It  functions fails.  It calls each of the hook functions, passing each of
2510  calls each of the hook functions, passing each of them the arguments  them the arguments @var{args}, until some hook function returns
2511  @var{args}, until some hook function returns @code{nil}.  Then it stops,  @code{nil}.  It then stops and returns @code{nil}.  If none of the
2512  and returns @code{nil} if some hook function returned @code{nil}.  hook functions return @code{nil}, it returns a non-@code{nil} value.
 Otherwise it returns a non-@code{nil} value.  
2513  @end defun  @end defun
2514    
2515  @defun run-hook-with-args-until-success hook &rest args  @defun run-hook-with-args-until-success hook &rest args
2516  This function is the way to run an abnormal hook which passes arguments  This function is the way to run an abnormal hook until a hook function
2517  to the hook functions, and stops as soon as any hook function succeeds.  succeeds.  It calls each of the hook functions, passing each of them
2518  It calls each of the hook functions, passing each of them the arguments  the arguments @var{args}, until some hook function returns
2519  @var{args}, until some hook function returns non-@code{nil}.  Then it  non-@code{nil}.  Then it stops, and returns whatever was returned by
2520  stops, and returns whatever was returned by the last hook function  the last hook function that was called.  If all hook functions return
2521  that was called.  @code{nil}, it returns @code{nil} as well.
2522  @end defun  @end defun
2523    
2524  @defun add-hook hook function &optional append local  @defun add-hook hook function &optional append local
2525  This function is the handy way to add function @var{function} to hook  This function is the handy way to add function @var{function} to hook
2526  variable @var{hook}.  The argument @var{function} may be any valid Lisp  variable @var{hook}.  You can use it for abnormal hooks as well as for
2527  function with the proper number of arguments.  For example,  normal hooks.  @var{function} can be any Lisp function that can accept
2528    the proper number of arguments for @var{hook}.  For example,
2529    
2530  @example  @example
2531  (add-hook 'text-mode-hook 'my-text-hook-function)  (add-hook 'text-mode-hook 'my-text-hook-function)
# Line 2315  function with the proper number of argum Line 2534  function with the proper number of argum
2534  @noindent  @noindent
2535  adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.  adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
2536    
2537  You can use @code{add-hook} for abnormal hooks as well as for normal  If @var{function} is already present in @var{hook} (comparing using
2538  hooks.  @code{equal}), then @code{add-hook} does not add it a second time.
2539    
2540  It is best to design your hook functions so that the order in which they  It is best to design your hook functions so that the order in which they
2541  are executed does not matter.  Any dependence on the order is ``asking  are executed does not matter.  Any dependence on the order is ``asking
2542  for trouble.''  However, the order is predictable: normally,  for trouble''.  However, the order is predictable: normally,
2543  @var{function} goes at the front of the hook list, so it will be  @var{function} goes at the front of the hook list, so it will be
2544  executed first (barring another @code{add-hook} call).  If the optional  executed first (barring another @code{add-hook} call).  If the optional
2545  argument @var{append} is non-@code{nil}, the new hook function goes at  argument @var{append} is non-@code{nil}, the new hook function goes at
2546  the end of the hook list and will be executed last.  the end of the hook list and will be executed last.
2547    
2548  If @var{local} is non-@code{nil}, that says to add @var{function}  If @var{local} is non-@code{nil}, that says to add @var{function} to
2549  to the buffer-local hook list instead of to the global hook list.  the buffer-local hook list instead of to the global hook list.  If
2550    needed, this makes the hook buffer-local and adds @code{t} to the
2551    buffer-local value.  The latter acts as a flag to run the hook
2552    functions in the default value as well as in the local value.
2553  @end defun  @end defun
2554    
2555  @defun remove-hook hook function &optional local  @defun remove-hook hook function &optional local
2556  This function removes @var{function} from the hook variable @var{hook}.  This function removes @var{function} from the hook variable
2557    @var{hook}.  It compares @var{function} with elements of @var{hook}
2558    using @code{equal}, so it works for both symbols and lambda
2559    expressions.
2560    
2561  If @var{local} is non-@code{nil}, that says to remove @var{function}  If @var{local} is non-@code{nil}, that says to remove @var{function}
2562  from the buffer-local hook list instead of from the global hook list.  from the buffer-local hook list instead of from the global hook list.
2563  @end defun  @end defun
2564    
2565    @ignore
2566       arch-tag: 4c7bff41-36e6-4da6-9e7f-9b9289e27c8e
2567    @end ignore

Legend:
Removed from v.1.49.2.1  
changed lines
  Added in v.1.49.2.2

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26