X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/47854a55680b5809811caf72f66ecbe8289c2855..4b0f717890dd0951bf68ebccada20f90580cdc30:/doc/lispref/modes.texi diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index efaccc2556..3547dd3e30 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/modes @node Modes, Documentation, Keymaps, Top @@ -77,15 +77,16 @@ convention. @samp{-hooks}. If the variable's name ends in @samp{-function}, then its value is just a single function, not a list of functions. - Here's an example that uses a mode hook to turn on Auto Fill mode when -in Lisp Interaction mode: +@menu +* Running Hooks:: How to run a hook. +* Setting Hooks:: How to put functions on a hook, or remove them. +@end menu -@example -(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill) -@end example +@node Running Hooks +@subsection Running Hooks - At the appropriate time, Emacs uses the @code{run-hooks} function to -run particular hooks. + At the appropriate times, Emacs uses the @code{run-hooks} function +and the other functions below to run particular hooks. @defun run-hooks &rest hookvars This function takes one or more normal hook variable names as @@ -125,6 +126,16 @@ the last hook function that was called. If all hook functions return @code{nil}, it returns @code{nil} as well. @end defun +@node Setting Hooks +@subsection Setting Hooks + + Here's an example that uses a mode hook to turn on Auto Fill mode when +in Lisp Interaction mode: + +@example +(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill) +@end example + @defun add-hook hook function &optional append local This function is the handy way to add function @var{function} to hook variable @var{hook}. You can use it for abnormal hooks as well as for @@ -141,6 +152,11 @@ adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}. If @var{function} is already present in @var{hook} (comparing using @code{equal}), then @code{add-hook} does not add it a second time. +If @var{function} has a non-@code{nil} property +@code{permanent-local-hook}, then @code{kill-all-local-variables} (or +changing major modes) won't delete it from the hook variable's local +value. + It is best to design your hook functions so that the order in which they are executed does not matter. Any dependence on the order is ``asking for trouble.'' However, the order is predictable: normally, @@ -301,8 +317,9 @@ which documentation to print. @item The major mode command should set the variable @code{mode-name} to the -``pretty'' name of the mode, as a string. This string appears in the -mode line. +``pretty'' name of the mode, usually a string (but see @ref{Mode Line +Data}, for other possible forms). The name of the mode appears +in the mode line. @item @cindex functions in modes @@ -359,7 +376,7 @@ Rmail that do not allow self-insertion of text can reasonably redefine letters and other printing characters as special commands. @item -Major modes modes for editing text should not define @key{RET} to do +Major modes for editing text should not define @key{RET} to do anything other than insert a newline. However, it is ok for specialized modes for text that users don't directly edit, such as Dired and Info modes, to redefine @key{RET} to do something entirely @@ -670,7 +687,7 @@ init file.) ;; @r{File name (within directory) starts with a dot.} '(("/\\.[^/]*\\'" . fundamental-mode) ;; @r{File name has no dot.} - ("[^\\./]*\\'" . fundamental-mode) + ("/[^\\./]*\\'" . fundamental-mode) ;; @r{File name ends in @samp{.C}.} ("\\.C\\'" . c++-mode)) auto-mode-alist)) @@ -1849,8 +1866,12 @@ effect. @defvar mode-name This buffer-local variable holds the ``pretty'' name of the current -buffer's major mode. Each major mode should set this variable so that the -mode name will appear in the mode line. +buffer's major mode. Each major mode should set this variable so that +the mode name will appear in the mode line. The value does not have +to be a string, but can use any of the data types valid in a mode-line +construct (@pxref{Mode Line Data}). To compute the string that will +identify the mode name in the mode line, use @code{format-mode-line} +(@pxref{Emulating Mode Line}). @end defvar @defvar mode-line-process @@ -2408,8 +2429,11 @@ The first element, @var{keywords}, indirectly specifies the value of It can be a symbol, a variable or a function whose value is the list to use for @code{font-lock-keywords}. It can also be a list of several such symbols, one for each possible level of fontification. -The first symbol specifies how to do level 1 fontification, the second -symbol how to do level 2, and so on. @xref{Levels of Font Lock}. +The first symbol specifies the @samp{mode default} level of +fontification, the next symbol level 1 fontification, the next level 2, +and so on. The @samp{mode default} level is normally the same as level +1. It is used when @code{font-lock-maximum-decoration} has a @code{nil} +value. @xref{Levels of Font Lock}. The second element, @var{keywords-only}, specifies the value of the variable @code{font-lock-keywords-only}. If this is omitted or @@ -2554,7 +2578,7 @@ which specifies how to highlight matches found by @var{matcher}. It has the form: @example -(@var{subexp} @var{facespec} [[@var{override} [@var{laxmatch}]]) +(@var{subexp} @var{facespec} [@var{override} [@var{laxmatch}]]) @end example The @sc{car}, @var{subexp}, is an integer specifying which subexpression @@ -2684,7 +2708,7 @@ Non-@code{nil} means that regular expression matching for the sake of You can use @code{font-lock-add-keywords} to add additional search-based fontification rules to a major mode, and -@code{font-lock-remove-keywords} to removes rules. +@code{font-lock-remove-keywords} to remove rules. @defun font-lock-add-keywords mode keywords &optional how This function adds highlighting @var{keywords}, for the current buffer @@ -2809,13 +2833,23 @@ arguments, the beginning and end of the region. The default value is @code{font-lock-default-unfontify-region}. @end defvar -@ignore -@defvar font-lock-inhibit-thing-lock -List of Font Lock mode related modes that should not be turned on. -Currently, valid mode names are @code{fast-lock-mode}, -@code{jit-lock-mode} and @code{lazy-lock-mode}. -@end defvar -@end ignore +@defun jit-lock-register function &optional contextual +This function tells Font Lock mode to run the Lisp function +@var{function} any time it has to fontify or refontify part of the +current buffer. It calls @var{function} before calling the default +fontification functions, and gives it two arguments, @var{start} and +@var{end}, which specify the region to be fontified or refontified. + +The optional argument @var{contextual}, if non-@code{nil}, forces Font +Lock mode to always refontify a syntactically relevant part of the +buffer, and not just the modified lines. This argument can usually be +omitted. +@end defun + +@defun jit-lock-unregister function +If @var{function} was previously registered as a fontification +function using @code{jit-lock-register}, this function unregisters it. +@end defun @node Levels of Font Lock @subsection Levels of Font Lock @@ -2823,9 +2857,10 @@ Currently, valid mode names are @code{fast-lock-mode}, Many major modes offer three different levels of fontification. You can define multiple levels by using a list of symbols for @var{keywords} in @code{font-lock-defaults}. Each symbol specifies one level of -fontification; it is up to the user to choose one of these levels. The -chosen level's symbol value is used to initialize -@code{font-lock-keywords}. +fontification; it is up to the user to choose one of these levels, +normally by setting @code{font-lock-maximum-decoration} (@pxref{Font +Lock,,, emacs, the GNU Emacs Manual}). The chosen level's symbol +value is used to initialize @code{font-lock-keywords}. Here are the conventions for how to define the levels of fontification: