@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, 2008 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
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,
+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,
@var{function} goes at the front of the hook list, so it will be
-executed first (barring another @code{add-hook} call). If the optional
-argument @var{append} is non-@code{nil}, the new hook function goes at
-the end of the hook list and will be executed last.
+executed first (barring another @code{add-hook} call). If the
+optional argument @var{append} is non-@code{nil}, the new hook
+function goes at the end of the hook list and will be executed last.
@code{add-hook} can handle the cases where @var{hook} is void or its
value is a single function; it sets or changes the value to a list of
If the new mode is similar to an old one, it is often unwise to
modify the old one to serve two purposes, since it may become harder
to use and maintain. Instead, copy and rename an existing major mode
-definition and alter the copy---or use @code{define-derived-mode} to
-define a @dfn{derived mode} (@pxref{Derived Modes}). For example,
-Rmail Edit mode is a major mode that is very similar to Text mode
-except that it provides two additional commands. Its definition is
-distinct from that of Text mode, but uses that of Text mode.
+definition and alter the copy---or use the @code{define-derived-mode}
+macro to define a @dfn{derived mode} (@pxref{Derived Modes}). For
+example, Rmail Edit mode is a major mode that is very similar to Text
+mode except that it provides two additional commands. Its definition
+is distinct from that of Text mode, but uses that of Text mode.
Even if the new mode is not an obvious derivative of any other mode,
it is convenient to use @code{define-derived-mode} with a @code{nil}
@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
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
The major mode command may start by calling some other major mode
command (called the @dfn{parent mode}) and then alter some of its
settings. A mode that does this is called a @dfn{derived mode}. The
-recommended way to define one is to use @code{define-derived-mode},
-but this is not required. Such a mode should call the parent mode
-command inside a @code{delay-mode-hooks} form. (Using
+recommended way to define one is to use the @code{define-derived-mode}
+macro, but this is not required. Such a mode should call the parent
+mode command inside a @code{delay-mode-hooks} form. (Using
@code{define-derived-mode} does this automatically.) @xref{Derived
Modes}, and @ref{Mode Hooks}.
@code{default-major-mode} is @code{nil}. Modes such as Dired, Rmail,
and Buffer List use this feature.
+The @code{define-derived-mode} macro automatically marks the derived
+mode as special if the parent mode is special. The special mode
+@code{special-mode} provides a convenient parent for other special
+modes to inherit from; it sets @code{buffer-read-only} to @code{t},
+and does nothing else.
+
@item
If you want to make the new mode the default for files with certain
recognizable names, add an element to @code{auto-mode-alist} to select
;; @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))
one. An easy way to do this is to use @code{define-derived-mode}.
@defmac define-derived-mode variant parent name docstring keyword-args@dots{} body@dots{}
-This construct defines @var{variant} as a major mode command, using
+This macro defines @var{variant} as a major mode command, using
@var{name} as the string form of the mode name. @var{variant} and
@var{parent} should be unquoted symbols.
evaluates the forms in @var{body} after setting up all its usual
overrides, just before running the mode hooks.
+If @var{parent} has a non-@code{nil} @code{mode-class} symbol
+property, then @code{define-derived-mode} sets the @code{mode-class}
+property of @var{variant} to the same value. This ensures, for
+example, that if @var{parent} is a special mode, then @var{variant} is
+also a special mode (@pxref{Major Mode Conventions}).
+
You can also specify @code{nil} for @var{parent}. This gives the new
mode no parent. Then @code{define-derived-mode} behaves as described
above, but, of course, omits all actions connected with @var{parent}.
The variable in overall control of the mode line is
@code{mode-line-format}.
-@defvar mode-line-format
+@defopt mode-line-format
The value of this variable is a mode-line construct that controls the
contents of the mode-line. It is always buffer-local in all buffers.
If you set this variable to @code{nil} in a buffer, that buffer does
not have a mode line. (A window that is just one line tall never
displays a mode line.)
-@end defvar
+@end defopt
The default value of @code{mode-line-format} is designed to use the
values of other variables such as @code{mode-line-position} and
@defvar mode-line-modified
This variable holds the value of the mode-line construct that displays
-whether the current buffer is modified.
-
-The default value of @code{mode-line-modified} is @code{("%1*%1+")}.
-This means that the mode line displays @samp{**} if the buffer is
-modified, @samp{--} if the buffer is not modified, @samp{%%} if the
-buffer is read only, and @samp{%*} if the buffer is read only and
-modified.
+whether the current buffer is modified. Its default value displays
+@samp{**} if the buffer is modified, @samp{--} if the buffer is not
+modified, @samp{%%} if the buffer is read only, and @samp{%*} if the
+buffer is read only and modified.
Changing this variable does not force an update of the mode line.
@end defvar
@defvar mode-line-frame-identification
-This variable identifies the current frame. The default value is
-@code{" "} if you are using a window system which can show multiple
-frames, or @code{"-%F "} on an ordinary terminal which shows only one
-frame at a time.
+This variable identifies the current frame. Its default value
+displays @code{" "} if you are using a window system which can show
+multiple frames, or @code{"-%F "} on an ordinary terminal which shows
+only one frame at a time.
@end defvar
@defvar mode-line-buffer-identification
-This variable identifies the buffer being displayed in the window. Its
-default value is @code{("%12b")}, which displays the buffer name, padded
-with spaces to at least 12 columns.
+This variable identifies the buffer being displayed in the window.
+Its default value displays the buffer name, padded with spaces to at
+least 12 columns.
@end defvar
-@defvar mode-line-position
-This variable indicates the position in the buffer. Here is a
-simplified version of its default value. The actual default value
-also specifies addition of the @code{help-echo} text property.
-
-@example
-@group
-((-3 "%p")
- (size-indication-mode (8 " of %I"))
-@end group
-@group
- (line-number-mode
- ((column-number-mode
- (10 " (%l,%c)")
- (6 " L%l")))
- ((column-number-mode
- (5 " C%c")))))
-@end group
-@end example
-
-This means that @code{mode-line-position} displays at least the buffer
-percentage and possibly the buffer size, the line number and the column
-number.
-@end defvar
+@defopt mode-line-position
+This variable indicates the position in the buffer. Its default value
+displays the buffer percentage and, optionally, the buffer size, the
+line number and the column number.
+@end defopt
@defvar vc-mode
The variable @code{vc-mode}, buffer-local in each buffer, records
line, or @code{nil} for no version control.
@end defvar
-@defvar mode-line-modes
-This variable displays the buffer's major and minor modes. Here is a
-simplified version of its default value. The real default value also
-specifies addition of text properties.
-
-@example
-@group
-("%[(" mode-name
- mode-line-process minor-mode-alist
- "%n" ")%]--")
-@end group
-@end example
-
-So @code{mode-line-modes} normally also displays the recursive editing
-level, information on the process status and whether narrowing is in
-effect.
-@end defvar
+@defopt mode-line-modes
+This variable displays the buffer's major and minor modes. Its
+default value also displays the recursive editing level, information
+on the process status, and whether narrowing is in effect.
+@end defopt
The following three variables are used in @code{mode-line-modes}:
@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
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
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
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
@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
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:
@node Precalculated Fontification
@subsection Precalculated Fontification
- In addition to using @code{font-lock-defaults} for search-based
-fontification, you may use the special character property
-@code{font-lock-face} (@pxref{Special Properties}). This property
-acts just like the explicit @code{face} property, but its activation
-is toggled when the user calls @kbd{M-x font-lock-mode}. Using
-@code{font-lock-face} is especially convenient for special modes
-which construct their text programmatically, such as
-@code{list-buffers} and @code{occur}.
-
-If your mode does not use any of the other machinery of Font Lock
-(i.e. it only uses the @code{font-lock-face} property), it should not
-set the variable @code{font-lock-defaults}.
+ Some major modes such as @code{list-buffers} and @code{occur}
+construct the buffer text programmatically. The easiest way for them
+to support Font Lock mode is to specify the faces of text when they
+insert the text in the buffer.
+
+ The way to do this is to specify the faces in the text with the
+special text property @code{font-lock-face} (@pxref{Special
+Properties}). When Font Lock mode is enabled, this property controls
+the display, just like the @code{face} property. When Font Lock mode
+is disabled, @code{font-lock-face} has no effect on the display.
+
+ It is ok for a mode to use @code{font-lock-face} for some text and
+also use the normal Font Lock machinery. But if the mode does not use
+the normal Font Lock machinery, it should not set the variable
+@code{font-lock-defaults}.
@node Faces for Font Lock
@subsection Faces for Font Lock
HCoop / bpt / emacs.git / blobdiff