@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/modes
@node Modes, Documentation, Keymaps, Top
* Major Modes:: Defining major modes.
* Minor Modes:: Defining minor modes.
* Mode Line Format:: Customizing the text that appears in the mode line.
+* Imenu:: How a mode can provide a menu
+ of definitions in the buffer.
+* Font Lock Mode:: How modes can highlight text according to syntax.
* Hooks:: How to use hooks; how to write code that provides hooks.
@end menu
Emacs command behaves in its default manner, and each option is in its
default state. All other major modes redefine various keys and options.
For example, Lisp Interaction mode provides special key bindings for
-@key{LFD} (@code{eval-print-last-sexp}), @key{TAB}
+@kbd{C-j} (@code{eval-print-last-sexp}), @key{TAB}
(@code{lisp-indent-line}), and other keys.
When you need to write several editing commands to help you perform a
maintain. Instead, copy and rename an existing major mode definition
and alter the copy---or define a @dfn{derived mode} (@pxref{Derived
Modes}). For example, Rmail Edit mode, which is in
-@file{emacs/lisp/rmailedit.el}, is a major mode that is very similar to
-Text mode except that it provides three additional commands. Its
-definition is distinct from that of Text mode, but was derived from it.
-
- Rmail Edit mode is an example of a case where one piece of text is put
-temporarily into a different major mode so it can be edited in a
-different way (with ordinary Emacs commands rather than Rmail). In such
-cases, the temporary major mode usually has a command to switch back to
-the buffer's usual mode (Rmail mode, in this case). You might be
-tempted to present the temporary redefinitions inside a recursive edit
-and restore the usual ones when the user exits; but this is a bad idea
-because it constrains the user's options when it is done in more than
-one buffer: recursive edits must be exited most-recently-entered first.
-Using alternative major modes avoids this limitation. @xref{Recursive
+@file{emacs/lisp/mail/rmailedit.el}, 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}
+parent argument, since it automatically enforces the most important
+coding conventions for you.
+
+ Rmail Edit mode offers an example of changing the major mode
+temporarily for a buffer, so it can be edited in a different way (with
+ordinary Emacs commands rather than Rmail commands). In such cases, the
+temporary major mode usually provides a command to switch back to the
+buffer's usual mode (Rmail mode, in this case). You might be tempted to
+present the temporary redefinitions inside a recursive edit and restore
+the usual ones when the user exits; but this is a bad idea because it
+constrains the user's options when it is done in more than one buffer:
+recursive edits must be exited most-recently-entered first. Using an
+alternative major mode avoids this limitation. @xref{Recursive
Editing}.
- The standard GNU Emacs Lisp library directory contains the code for
-several major modes, in files including @file{text-mode.el},
+ The standard GNU Emacs Lisp library directory tree contains the code
+for several major modes, in files such as @file{text-mode.el},
@file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
-@file{rmail.el}. You can look at these libraries to see how modes are
-written. Text mode is perhaps the simplest major mode aside from
+@file{rmail.el}. They are found in various subdirectories of the
+@file{lisp} directory. You can study these libraries to see how modes
+are written. Text mode is perhaps the simplest major mode aside from
Fundamental mode. Rmail mode is a complicated and specialized mode.
@menu
The code for existing major modes follows various coding conventions,
including conventions for local keymap and syntax table initialization,
global names, and hooks. Please follow these conventions when you
-define a new major mode:
+define a new major mode.
+
+ This list of conventions is only partial, because each major mode
+should aim for consistency in general with other Emacs major modes.
+This makes Emacs as a whole more coherent. It is impossible to list
+here all the possible points where this issue might come up; if the
+Emacs developers point out an area where your major mode deviates from
+the usual conventions, please make it compatible.
@itemize @bullet
@item
Define a command whose name ends in @samp{-mode}, with no arguments,
that switches to the new mode in the current buffer. This command
-should set up the keymap, syntax table, and local variables in an
-existing buffer without changing the buffer's text.
+should set up the keymap, syntax table, and buffer-local variables in an
+existing buffer, without changing the buffer's contents.
@item
Write a documentation string for this command that describes the
The documentation string may include the special documentation
substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
-@samp{\<@var{keymap}>}, that enable the documentation to adapt
+@samp{\<@var{keymap}>}, which enable the documentation to adapt
automatically to the user's own key bindings. @xref{Keys in
Documentation}.
@item
The major mode command should start by calling
-@code{kill-all-local-variables}. This is what gets rid of the local
-variables of the major mode previously in effect.
+@code{kill-all-local-variables}. This is what gets rid of the
+buffer-local variables of the major mode previously in effect.
@item
The major mode command should set the variable @code{major-mode} to the
@item
The major mode command should set the variable @code{mode-name} to the
-``pretty'' name of the mode, as a string. This appears in the mode
-line.
+``pretty'' name of the mode, as a string. This string appears in the
+mode line.
@item
@cindex functions in modes
Since all global names are in the same name space, all the global
variables, constants, and functions that are part of the mode should
have names that start with the major mode name (or with an abbreviation
-of it if the name is long). @xref{Style Tips}.
+of it if the name is long). @xref{Coding Conventions}.
+
+@item
+In a major mode for editing some kind of structured text, such as a
+programming language, indentation of text according to structure is
+probably useful. So the mode should set @code{indent-line-function}
+to a suitable function, and probably customize other variables
+for indentation.
@item
@cindex keymaps in modes
The major mode should usually have its own keymap, which is used as the
-local keymap in all buffers in that mode. The major mode function
-should call @code{use-local-map} to install this local map.
-@xref{Active Keymaps}, for more information.
+local keymap in all buffers in that mode. The major mode command should
+call @code{use-local-map} to install this local map. @xref{Active
+Keymaps}, for more information.
-This keymap should be kept in a global variable named
+This keymap should be stored permanently in a global variable named
@code{@var{modename}-mode-map}. Normally the library that defines the
mode sets this variable.
+@xref{Tips for Defining}, for advice about how to write the code to set
+up the mode's keymap variable.
+
+@item
+The key sequences bound in a major mode keymap should usually start with
+@kbd{C-c}, followed by a control character, a digit, or @kbd{@{},
+@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}. The other punctuation
+characters are reserved for minor modes, and ordinary letters are
+reserved for users.
+
+It is reasonable for a major mode to rebind a key sequence with a
+standard meaning, if it implements a command that does ``the same job''
+in a way that fits the major mode better. For example, a major mode for
+editing a programming language might redefine @kbd{C-M-a} to ``move to
+the beginning of a function'' in a way that works better for that
+language.
+
+Major modes such as Dired or Rmail that do not allow self-insertion of
+text can reasonably redefine letters and other printing characters as
+editing commands. Dired and Rmail both do this.
+
+@item
+Major modes must not define @key{RET} to do anything other than insert
+a newline. The command to insert a newline and then indent is
+@kbd{C-j}. Please keep this distinction uniform for all major modes.
+
+@item
+Major modes should not alter options that are primary a matter of user
+preference, such as whether Auto-Fill mode is enabled. Leave this to
+each user to decide. However, a major mode should customize other
+variables so that Auto-Fill mode will work usefully @emph{if} the user
+decides to use it.
+
@item
@cindex syntax tables in modes
The mode may have its own syntax table or may share one with other
a variable named @code{@var{modename}-mode-syntax-table}. @xref{Syntax
Tables}.
+@item
+If the mode handles a language that has a syntax for comments, it should
+set the variables that define the comment syntax. @xref{Options for
+Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}.
+
@item
@cindex abbrev tables in modes
The mode may have its own abbrev table or may share one with other
Tables}.
@item
-Use @code{defvar} to set mode-related variables, so that they are not
-reinitialized if they already have a value. (Such reinitialization
-could discard customizations made by the user.)
+The mode should specify how to do highlighting for Font Lock mode, by
+setting up a buffer-local value for the variable
+@code{font-lock-defaults} (@pxref{Font Lock Mode}).
+
+@item
+The mode should specify how Imenu should find the definitions or
+sections of a buffer, by setting up a buffer-local value for the
+variable @code{imenu-generic-expression} or
+@code{imenu-create-index-function} (@pxref{Imenu}).
+
+@item
+Use @code{defvar} or @code{defcustom} to set mode-related variables, so
+that they are not reinitialized if they already have a value. (Such
+reinitialization could discard customizations made by the user.)
@item
@cindex buffer-local variables in modes
would affect buffers that do not use this mode. It is undesirable for a
mode to have such global effects. @xref{Buffer-Local Variables}.
-It's ok to use @code{make-variable-buffer-local}, if you wish, for a
-variable used only within a single Lisp package.
+With rare exceptions, the only reasonable way to use
+@code{make-variable-buffer-local} in a Lisp package is for a variable
+which is used only within that package. Using it on a variable used by
+other packages would interfere with them.
@item
@cindex mode hook
Each major mode should have a @dfn{mode hook} named
@code{@var{modename}-mode-hook}. The major mode command should run that
hook, with @code{run-hooks}, as the very last thing it
-does. @xref{Hooks}.
+does. @xref{Hooks}.
@item
The major mode command may also run the hooks of some more basic modes.
@item
If something special should be done if the user switches a buffer from
-this mode to any other major mode, the mode can set a local value for
-@code{change-major-mode-hook}.
+this mode to any other major mode, this mode can set up a buffer-local
+value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}).
@item
If this mode is appropriate only for specially-prepared text, then the
@end example
@noindent
-This tells Emacs that new buffers created while the current buffer has
+This tells Emacs that new buffers created while the current buffer is in
Funny mode should not inherit Funny mode. Modes such as Dired, Rmail,
and Buffer List use this feature.
file that contains the mode definition. @xref{Auto Major Mode}.
@item
-@cindex @file{.emacs} customization
In the documentation, you should provide a sample @code{autoload} form
and an example of how to add to @code{auto-mode-alist}, that users can
-include in their @file{.emacs} files.
+include in their init files (@pxref{Init File}).
@item
@cindex mode loading
Even if you never load the file more than once, someone else will.
@end itemize
-@defvar change-major-mode-hook
-This normal hook is run by @code{kill-all-local-variables} before it
-does anything else. This gives major modes a way to arrange for
-something special to be done if the user switches to a different major
-mode. For best results, make this variable buffer-local, so that it
-will disappear after doing its job and will not interfere with the
-subsequent major mode. @xref{Hooks}.
-@end defvar
-
@node Example Major Modes
@subsection Major Mode Examples
@end group
@group
-(defvar text-mode-map nil) ; @r{Create a mode-specific keymap.}
+(defvar text-mode-map nil ; @r{Create a mode-specific keymap.}
+ "Keymap for Text mode.
+Many other modes, such as Mail mode, Outline mode and Indented Text mode,
+inherit all the commands defined in this map.")
(if text-mode-map
() ; @r{Do not change the keymap if it is already set up.}
(setq text-mode-map (make-sparse-keymap))
- (define-key text-mode-map "\t" 'tab-to-tab-stop)
+ (define-key text-mode-map "\e\t" 'ispell-complete-word)
+ (define-key text-mode-map "\t" 'indent-relative)
(define-key text-mode-map "\es" 'center-line)
(define-key text-mode-map "\eS" 'center-paragraph))
@end group
@smallexample
@group
(defun text-mode ()
- "Major mode for editing text intended for humans to read.
+ "Major mode for editing text intended for humans to read...
Special commands: \\@{text-mode-map@}
@end group
@group
Turning on text-mode runs the hook `text-mode-hook'."
(interactive)
(kill-all-local-variables)
+ (use-local-map text-mode-map)
@end group
@group
- (use-local-map text-mode-map) ; @r{This provides the local keymap.}
- (setq mode-name "Text") ; @r{This name goes into the mode line.}
- (setq major-mode 'text-mode) ; @r{This is how @code{describe-mode}}
- ; @r{finds the doc string to print.}
(setq local-abbrev-table text-mode-abbrev-table)
(set-syntax-table text-mode-syntax-table)
+@end group
+@group
+ (make-local-variable 'paragraph-start)
+ (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter))
+ (make-local-variable 'paragraph-separate)
+ (setq paragraph-separate paragraph-start)
+ (make-local-variable 'indent-line-function)
+ (setq indent-line-function 'indent-relative-maybe)
+@end group
+@group
+ (setq mode-name "Text")
+ (setq major-mode 'text-mode)
(run-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
; @r{customize the mode with a hook.}
@end group
@group
;; @r{Set syntax of chars up to 0 to class of chars that are}
;; @r{part of symbol names but not words.}
- ;; @r{(The number 0 is @code{48} in the @sc{ASCII} character set.)}
+ ;; @r{(The number 0 is @code{48} in the @sc{ascii} character set.)}
(while (< i ?0)
(modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table)
(setq i (1+ i)))
@smallexample
@group
(defun lisp-mode-variables (lisp-syntax)
- ;; @r{The @code{lisp-syntax} argument is @code{nil} in Emacs Lisp mode,}
- ;; @r{and @code{t} in the other two Lisp modes.}
(cond (lisp-syntax
- (if (not lisp-mode-syntax-table)
- ;; @r{The Emacs Lisp mode syntax table always exists, but}
- ;; @r{the Lisp Mode syntax table is created the first time a}
- ;; @r{mode that needs it is called. This is to save space.}
-@end group
-@group
- (progn (setq lisp-mode-syntax-table
- (copy-syntax-table emacs-lisp-mode-syntax-table))
- ;; @r{Change some entries for Lisp mode.}
- (modify-syntax-entry ?\| "\" "
- lisp-mode-syntax-table)
- (modify-syntax-entry ?\[ "_ "
- lisp-mode-syntax-table)
- (modify-syntax-entry ?\] "_ "
- lisp-mode-syntax-table)))
-@end group
-@group
- (set-syntax-table lisp-mode-syntax-table)))
+ (set-syntax-table lisp-mode-syntax-table)))
(setq local-abbrev-table lisp-mode-abbrev-table)
- @dots{})
+ @dots{}
@end group
@end smallexample
@smallexample
@group
(make-local-variable 'paragraph-start)
- (setq paragraph-start (concat "^$\\|" page-delimiter))
+ (setq paragraph-start (concat page-delimiter "\\|$" ))
+ (make-local-variable 'paragraph-separate)
+ (setq paragraph-separate paragraph-start)
@dots{}
@end group
@group
(make-local-variable 'comment-indent-function)
(setq comment-indent-function 'lisp-comment-indent))
+ @dots{}
@end group
@end smallexample
Each of the different Lisp modes has a slightly different keymap. For
-example, Lisp mode binds @kbd{C-c C-l} to @code{run-lisp}, but the other
+example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other
Lisp modes do not. However, all Lisp modes have some commands in
-common. The following function adds these common commands to a given
-keymap.
+common. The following code sets up the common commands:
@smallexample
@group
-(defun lisp-mode-commands (map)
- (define-key map "\e\C-q" 'indent-sexp)
- (define-key map "\177" 'backward-delete-char-untabify)
- (define-key map "\t" 'lisp-indent-line))
+(defvar shared-lisp-mode-map ()
+ "Keymap for commands shared by all sorts of Lisp modes.")
+
+(if shared-lisp-mode-map
+ ()
+ (setq shared-lisp-mode-map (make-sparse-keymap))
+ (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp)
+ (define-key shared-lisp-mode-map "\177"
+ 'backward-delete-char-untabify))
@end group
@end smallexample
- Here is an example of using @code{lisp-mode-commands} to initialize a
-keymap, as part of the code for Emacs Lisp mode. First we declare a
-variable with @code{defvar} to hold the mode-specific keymap. When this
-@code{defvar} executes, it sets the variable to @code{nil} if it was
-void. Then we set up the keymap if the variable is @code{nil}.
-
- This code avoids changing the keymap or the variable if it is already
-set up. This lets the user customize the keymap.
+@noindent
+And here is the code to set up the keymap for Lisp mode:
@smallexample
@group
-(defvar emacs-lisp-mode-map () "")
-(if emacs-lisp-mode-map
+(defvar lisp-mode-map ()
+ "Keymap for ordinary Lisp mode...")
+
+(if lisp-mode-map
()
- (setq emacs-lisp-mode-map (make-sparse-keymap))
- (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun)
- (lisp-mode-commands emacs-lisp-mode-map))
+ (setq lisp-mode-map (make-sparse-keymap))
+ (set-keymap-parent lisp-mode-map shared-lisp-mode-map)
+ (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun)
+ (define-key lisp-mode-map "\C-c\C-z" 'run-lisp))
@end group
@end smallexample
Finally, here is the complete major mode function definition for
-Emacs Lisp mode.
+Lisp mode.
@smallexample
@group
-(defun emacs-lisp-mode ()
- "Major mode for editing Lisp code to run in Emacs.
+(defun lisp-mode ()
+ "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
Commands:
Delete converts tabs to spaces as it moves back.
Blank lines separate paragraphs. Semicolons start comments.
-\\@{emacs-lisp-mode-map@}
+\\@{lisp-mode-map@}
+Note that `run-lisp' may be used either to start an inferior Lisp job
+or to switch back to an existing one.
@end group
+
@group
-Entry to this mode runs the hook `emacs-lisp-mode-hook'."
+Entry to this mode calls the value of `lisp-mode-hook'
+if that value is non-nil."
(interactive)
(kill-all-local-variables)
- (use-local-map emacs-lisp-mode-map) ; @r{This provides the local keymap.}
- (set-syntax-table emacs-lisp-mode-syntax-table)
@end group
@group
- (setq major-mode 'emacs-lisp-mode) ; @r{This is how @code{describe-mode}}
+ (use-local-map lisp-mode-map) ; @r{Select the mode's keymap.}
+ (setq major-mode 'lisp-mode) ; @r{This is how @code{describe-mode}}
; @r{finds out what to describe.}
- (setq mode-name "Emacs-Lisp") ; @r{This goes into the mode line.}
- (lisp-mode-variables nil) ; @r{This defines various variables.}
- (run-hooks 'emacs-lisp-mode-hook)) ; @r{This permits the user to use a}
+ (setq mode-name "Lisp") ; @r{This goes into the mode line.}
+ (lisp-mode-variables t) ; @r{This defines various variables.}
+@end group
+@group
+ (setq imenu-case-fold-search t)
+ (set-syntax-table lisp-mode-syntax-table)
+ (run-hooks 'lisp-mode-hook)) ; @r{This permits the user to use a}
; @r{hook to customize the mode.}
@end group
@end smallexample
Based on information in the file name or in the file itself, Emacs
automatically selects a major mode for the new buffer when a file is
-visited.
+visited. It also processes local variables specified in the file text.
@deffn Command fundamental-mode
Fundamental mode is a major mode that is not specialized for anything
@end deffn
@deffn Command normal-mode &optional find-file
- This function establishes the proper major mode and local variable
+This function establishes the proper major mode and buffer-local variable
bindings for the current buffer. First it calls @code{set-auto-mode},
then it runs @code{hack-local-variables} to parse, and bind or
-evaluate as appropriate, any local variables.
+evaluate as appropriate, the file's local variables.
- If the @var{find-file} argument to @code{normal-mode} is
-non-@code{nil}, @code{normal-mode} assumes that the @code{find-file}
-function is calling it. In this case, it may process a local variables
-list at the end of the file. The variable @code{enable-local-variables}
-controls whether to do so.
+If the @var{find-file} argument to @code{normal-mode} is non-@code{nil},
+@code{normal-mode} assumes that the @code{find-file} function is calling
+it. In this case, it may process a local variables list at the end of
+the file and in the @samp{-*-} line. The variable
+@code{enable-local-variables} controls whether to do so. @xref{File
+variables, , Local Variables in Files, emacs, The GNU Emacs Manual}, for
+the syntax of the local variables section of a file.
- If you run @code{normal-mode} interactively, the argument
+If you run @code{normal-mode} interactively, the argument
@var{find-file} is normally @code{nil}. In this case,
@code{normal-mode} unconditionally processes any local variables list.
-@xref{File variables, , Local Variables in Files, emacs, The GNU Emacs
-Manual}, for the syntax of the local variables section of a file.
@cindex file mode specification error
- @code{normal-mode} uses @code{condition-case} around the call to the
+@code{normal-mode} uses @code{condition-case} around the call to the
major mode function, so errors are caught and reported as a @samp{File
mode specification error}, followed by the original error message.
@end deffn
-@defopt enable-local-variables
-This variable controls processing of local variables lists in files
-being visited. A value of @code{t} means process the local variables
-lists unconditionally; @code{nil} means ignore them; anything else means
-ask the user what to do for each file. The default value is @code{t}.
-@end defopt
-
-@defopt enable-local-eval
-This variable controls processing of @samp{Eval:} in local variables
-lists in files being visited. A value of @code{t} means process them
-unconditionally; @code{nil} means ignore them; anything else means ask
-the user what to do for each file. The default value is @code{maybe}.
-@end defopt
-
@defun set-auto-mode
@cindex visited file mode
This function selects the major mode that is appropriate for the
current buffer. It may base its decision on the value of the @w{@samp{-*-}}
-line, on the visited file name (using @code{auto-mode-alist}), or on the
-value of a local variable. However, this function does not look for
+line, on the visited file name (using @code{auto-mode-alist}), on the
+@w{@samp{#!}} line (using @code{interpreter-mode-alist}), or on the
+file's local variables list. However, this function does not look for
the @samp{mode:} local variable near the end of a file; the
@code{hack-local-variables} function does that. @xref{Choosing Modes, ,
How Major Modes are Chosen, emacs, The GNU Emacs Manual}.
@end defun
@defopt default-major-mode
- This variable holds the default major mode for new buffers. The
+This variable holds the default major mode for new buffers. The
standard value is @code{fundamental-mode}.
- If the value of @code{default-major-mode} is @code{nil}, Emacs uses
+If the value of @code{default-major-mode} is @code{nil}, Emacs uses
the (previously) current buffer's major mode for the major mode of a new
-buffer. However, if the major mode symbol has a @code{mode-class}
+buffer. However, if that major mode symbol has a @code{mode-class}
property with value @code{special}, then it is not used for new buffers;
Fundamental mode is used instead. The modes that have this property are
those such as Dired and Rmail that are useful only with text that has
been specially prepared.
@end defopt
+@defun set-buffer-major-mode buffer
+This function sets the major mode of @var{buffer} to the value of
+@code{default-major-mode}. If that variable is @code{nil}, it uses
+the current buffer's major mode (if that is suitable).
+
+The low-level primitives for creating buffers do not use this function,
+but medium-level commands such as @code{switch-to-buffer} and
+@code{find-file-noselect} use it whenever they create buffers.
+@end defun
+
@defvar initial-major-mode
@cindex @samp{*scratch*}
The value of this variable determines the major mode of the initial
@samp{*scratch*} buffer. The value should be a symbol that is a major
-mode command name. The default value is @code{lisp-interaction-mode}.
+mode command. The default value is @code{lisp-interaction-mode}.
@end defvar
@defvar auto-mode-alist
This variable contains an association list of file name patterns
(regular expressions; @pxref{Regular Expressions}) and corresponding
-major mode functions. Usually, the file name patterns test for
-suffixes, such as @samp{.el} and @samp{.c}, but this need not be the
-case. An ordinary element of the alist looks like @code{(@var{regexp} .
+major mode commands. Usually, the file name patterns test for suffixes,
+such as @samp{.el} and @samp{.c}, but this need not be the case. An
+ordinary element of the alist looks like @code{(@var{regexp} .
@var{mode-function})}.
For example,
@smallexample
@group
-(("^/tmp/fol/" . text-mode)
- ("\\.texinfo$" . texinfo-mode)
- ("\\.texi$" . texinfo-mode)
+(("\\`/tmp/fol/" . text-mode)
+ ("\\.texinfo\\'" . texinfo-mode)
+ ("\\.texi\\'" . texinfo-mode)
@end group
@group
- ("\\.el$" . emacs-lisp-mode)
- ("\\.c$" . c-mode)
- ("\\.h$" . c-mode)
+ ("\\.el\\'" . emacs-lisp-mode)
+ ("\\.c\\'" . c-mode)
+ ("\\.h\\'" . c-mode)
@dots{})
@end group
@end smallexample
If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
@var{function} t)}, then after calling @var{function}, Emacs searches
@code{auto-mode-alist} again for a match against the portion of the file
-name that did not match before.
-
-This match-again feature is useful for uncompression packages: an entry
-of the form @code{("\\.gz\\'" . @var{function})} can uncompress the file
-and then put the uncompressed file in the proper mode according to the
-name sans @samp{.gz}.
+name that did not match before. This feature is useful for
+uncompression packages: an entry of the form @code{("\\.gz\\'"
+@var{function} t)} can uncompress the file and then put the uncompressed
+file in the proper mode according to the name sans @samp{.gz}.
Here is an example of how to prepend several pattern pairs to
@code{auto-mode-alist}. (You might use this sort of expression in your
-@file{.emacs} file.)
+init file.)
@smallexample
@group
(setq auto-mode-alist
(append
- ;; @r{File name starts with a dot.}
- '(("/\\.[^/]*$" . fundamental-mode)
+ ;; @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))
+ ("\\.C\\'" . c++-mode))
auto-mode-alist))
@end group
@end smallexample
@end defvar
@defvar interpreter-mode-alist
-This variable specifes major modes to use for scripts that specify a
-command interpreter in an @samp{!#} line. Its value is a list of
+This variable specifies major modes to use for scripts that specify a
+command interpreter in a @samp{#!} line. Its value is a list of
elements of the form @code{(@var{interpreter} . @var{mode})}; for
example, @code{("perl" . perl-mode)} is one element present by default.
The element says to use mode @var{mode} if the file specifies
-@var{interpreter}.
+an interpreter which matches @var{interpreter}. The value of
+@var{interpreter} is actually a regular expression.
This variable is applicable only when the @code{auto-mode-alist} does
not indicate which major mode to use.
@end defvar
-@defun hack-local-variables &optional force
- This function parses, and binds or evaluates as appropriate, any local
-variables for the current buffer.
-
- The handling of @code{enable-local-variables} documented for
-@code{normal-mode} actually takes place here. The argument @var{force}
-usually comes from the argument @var{find-file} given to
-@code{normal-mode}.
-@end defun
-
@node Mode Help
@subsection Getting Help about a Major Mode
@cindex mode help
(define-key hypertext-mode-map
[down-mouse-3] 'do-hyper-link)
@end example
+
+Do not write an @code{interactive} spec in the definition;
+@code{define-derived-mode} does that automatically.
@end defmac
@node Minor Modes
A @dfn{minor mode} provides features that users may enable or disable
independently of the choice of major mode. Minor modes can be enabled
individually or in combination. Minor modes would be better named
-``Generally available, optional feature modes'' except that such a name is
-unwieldy.
+``generally available, optional feature modes,'' except that such a name
+would be unwieldy.
- A minor mode is not usually a modification of single major mode. For
-example, Auto Fill mode may be used in any major mode that permits text
+ A minor mode is not usually meant as a variation of a single major mode.
+Usually they are general and can apply to many major modes. For
+example, Auto Fill mode works with any major mode that permits text
insertion. To be general, a minor mode must be effectively independent
of the things major modes do.
Often the biggest problem in implementing a minor mode is finding a
way to insert the necessary hook into the rest of Emacs. Minor mode
-keymaps make this easier in Emacs 19 than it used to be.
+keymaps make this easier than it used to be.
@menu
* Minor Mode Conventions:: Tips for writing a minor mode.
* Keymaps and Minor Modes:: How a minor mode can have its own keymap.
+* Defining Minor Modes:: A convenient facility for defining minor modes.
@end menu
@node Minor Mode Conventions
@itemize @bullet
@item
@cindex mode variable
-Make a variable whose name ends in @samp{-mode} to represent the minor
-mode. Its value should enable or disable the mode (@code{nil} to
-disable; anything else to enable.) We call this the @dfn{mode
-variable}.
+Make a variable whose name ends in @samp{-mode} to control the minor
+mode. We call this the @dfn{mode variable}. The minor mode command
+should set this variable (@code{nil} to disable; anything else to
+enable).
+
+If possible, implement the mode so that setting the variable
+automatically enables or disables the mode. Then the minor mode command
+does not need to do anything except set the variable.
This variable is used in conjunction with the @code{minor-mode-alist} to
display the minor mode name in the mode line. It can also enable
list whose @sc{car} is such an integer or symbol; it should turn the
mode off otherwise.
-Here is an example taken from the definition of @code{overwrite-mode}.
-It shows the use of @code{overwrite-mode} as a variable that enables or
+Here is an example taken from the definition of @code{transient-mark-mode}.
+It shows the use of @code{transient-mark-mode} as a variable that enables or
disables the mode's behavior, and also shows the proper way to toggle,
enable or disable the minor mode based on the raw prefix argument value.
@smallexample
@group
-(setq overwrite-mode
- (if (null arg) (not overwrite-mode)
+(setq transient-mark-mode
+ (if (null arg) (not transient-mark-mode)
(> (prefix-numeric-value arg) 0)))
@end group
@end smallexample
@item
Add an element to @code{minor-mode-alist} for each minor mode
-(@pxref{Mode Line Variables}). This element should be a list of the
-following form:
+(@pxref{Mode Line Variables}), if you want to indicate the minor mode in
+the mode line. This element should be a list of the following form:
@smallexample
(@var{mode-variable} @var{string})
@smallexample
@group
-(or (assq 'leif-mode minor-mode-alist)
- (setq minor-mode-alist
- (cons '(leif-mode " Leif") minor-mode-alist)))
+(unless (assq 'leif-mode minor-mode-alist)
+ (setq minor-mode-alist
+ (cons '(leif-mode " Leif") minor-mode-alist)))
+@end group
+@end smallexample
+
+@noindent
+or like this, using @code{add-to-list} (@pxref{Setting Variables}):
+
+@smallexample
+@group
+(add-to-list 'minor-mode-alist '(leif-mode " Leif"))
@end group
@end smallexample
@end itemize
+ Global minor modes distributed with Emacs should if possible support
+enabling and disabling via Custom (@pxref{Customization}). To do this,
+the first step is to define the mode variable with @code{defcustom}, and
+specify @code{:type boolean}.
+
+ If just setting the variable is not sufficient to enable the mode, you
+should also specify a @code{:set} method which enables the mode by
+invoke the mode command. Note in the variable's documentation string that
+setting the variable other than via Custom may not take effect.
+
+ Also mark the definition with an autoload cookie (@pxref{Autoload}),
+and specify a @code{:require} so that customizing the variable will load
+the library that defines the mode. This will copy suitable definitions
+into @file{loaddefs.el} so that users can use @code{customize-option} to
+enable the mode. For example:
+
+@smallexample
+@group
+
+;;;###autoload
+(defcustom msb-mode nil
+ "Toggle msb-mode.
+Setting this variable directly does not take effect;
+use either \\[customize] or the function `msb-mode'."
+ :set (lambda (symbol value)
+ (msb-mode (or value 0)))
+ :initialize 'custom-initialize-default
+ :version "20.4"
+ :type 'boolean
+ :group 'msb
+ :require 'msb)
+@end group
+@end smallexample
+
@node Keymaps and Minor Modes
@subsection Keymaps and Minor Modes
-As of Emacs version 19, each minor mode can have its own keymap, which is
-active when the mode is enabled. @xref{Active Keymaps}. To set up a
-keymap for a minor mode, add an element to the alist
-@code{minor-mode-map-alist}.
+ Each minor mode can have its own keymap, which is active when the mode
+is enabled. To set up a keymap for a minor mode, add an element to the
+alist @code{minor-mode-map-alist}. @xref{Active Keymaps}.
@cindex @code{self-insert-command}, minor modes
-One use of minor mode keymaps is to modify the behavior of certain
+ One use of minor mode keymaps is to modify the behavior of certain
self-inserting characters so that they do something else as well as
self-insert. In general, this is the only way to do that, since the
facilities for customizing @code{self-insert-command} are limited to
substituting your own definition of @code{self-insert-command} for the
standard one. The editor command loop handles this function specially.)
-@defvar minor-mode-map-alist
-This variable is an alist of elements that look like this:
+The key sequences bound in a minor mode should consist of @kbd{C-c}
+followed by a punctuation character @emph{other than} @kbd{@{},
+@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:}, and @kbd{;}. (Those few punctuation
+characters are reserved for major modes.)
+
+@node Defining Minor Modes
+@subsection Defining Minor Modes
+
+ The macro @code{define-minor-mode} offers a convenient way of
+implementing a mode in one self-contained definition. It supports only
+buffer-local minor modes, not global ones.
+
+@defmac define-minor-mode mode doc &optional init-value mode-indicator keymap body...
+@tindex define-minor-mode
+This macro defines a new minor mode whose name is @var{mode} (a symbol).
+It defines a command named @var{mode} to toggle the minor
+mode, with @var{doc} as its documentation string. It also defines a
+variable named @var{mode}, which is set to @code{t} or @code{nil} by
+enabling or disabling the mode. The variable is initialized to
+@var{init-value}.
+
+The command named @var{mode} finishes by executing the @var{body} forms,
+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
+when the mode is enabled; if it is @code{nil}, the mode is not displayed
+in the mode line.
+
+The optional argument @var{keymap} specifies the keymap for the minor mode.
+It can be a variable name, whose value is the keymap, or it can be an alist
+specifying bindings in this form:
@example
-(@var{variable} . @var{keymap})
+(@var{key-sequence} . @var{definition})
@end example
+@end defmac
+
+ Here is an example of using @code{define-minor-mode}:
+
+@smallexample
+(define-minor-mode hungry-mode
+ "Toggle Hungry mode.
+With no argument, this command toggles the mode.
+Non-null prefix argument turns on the mode.
+Null prefix argument turns off the mode.
+
+When Hungry mode is enabled, the control delete key
+gobbles all preceding whitespace except the last.
+See the command \\[hungry-electric-delete]."
+ ;; The initial value.
+ nil
+ ;; The indicator for the mode line.
+ " Hungry"
+ ;; The minor mode bindings.
+ '(("\C-\^?" . hungry-electric-delete)
+ ("\C-\M-\^?"
+ . (lambda ()
+ (interactive)
+ (hungry-electric-delete t)))))
+@end smallexample
@noindent
-where @var{variable} is the variable that indicates whether the minor
-mode is enabled, and @var{keymap} is the keymap. The keymap
-@var{keymap} is active whenever @var{variable} has a non-@code{nil}
-value.
-
-Note that elements of @code{minor-mode-map-alist} do not have the same
-structure as elements of @code{minor-mode-alist}. The map must be the
-@sc{cdr} of the element; a list with the map as the second element will
-not do.
-
-What's more, the keymap itself must appear in the @sc{cdr}. It does not
-work to store a variable in the @sc{cdr} and make the map the value of
-that variable.
-
-When more than one minor mode keymap is active, their order of priority
-is the order of @code{minor-mode-map-alist}. But you should design
-minor modes so that they don't interfere with each other. If you do
-this properly, the order will not matter.
-@end defvar
+This defines a minor mode named ``Hungry mode'', a command named
+@code{hungry-mode} to toggle it, a variable named @code{hungry-mode}
+which indicates whether the mode is enabled, and a variable named
+@code{hungry-mode-map} which holds the keymap that is active when the
+mode is enabled. It initializes the keymap with key bindings for
+@kbd{C-@key{DEL}} and @kbd{C-M-@key{DEL}}.
+
+
+@findex easy-mmode-define-minor-mode
+ The name @code{easy-mmode-define-minor-mode} is an alias
+for this macro.
@node Mode Line Format
@section Mode Line Format
@cindex mode line
- Each Emacs window (aside from minibuffer windows) includes a mode line,
-which displays status information about the buffer displayed in the
-window. The mode line contains information about the buffer, such as its
-name, associated file, depth of recursive editing, and the major and
-minor modes.
+ Each Emacs window (aside from minibuffer windows) typically has a mode
+line at the bottom, which displays status information about the buffer
+displayed in the window. The mode line contains information about the
+buffer, such as its name, associated file, depth of recursive editing,
+and major and minor modes. A window can also have a @dfn{header
+line}, which is much like the mode line but appears at the top of the
+window (starting in Emacs 21).
- This section describes how the contents of the mode line are
-controlled. It is in the chapter on modes because much of the
+ This section describes how to control the contents of the mode line
+and header line. We include it in this chapter because much of the
information displayed in the mode line relates to the enabled major and
minor modes.
@code{mode-line-format} is a buffer-local variable that holds a
template used to display the mode line of the current buffer. All
-windows for the same buffer use the same @code{mode-line-format} and the
-mode lines will appear the same (except for scrolling percentages and
-line numbers).
-
- The mode line of a window is normally updated whenever a different
-buffer is shown in the window, or when the buffer's modified-status
-changes from @code{nil} to @code{t} or vice-versa. If you modify any of
-the variables referenced by @code{mode-line-format} (@pxref{Mode Line
-Variables}), you may want to force an update of the mode line so as to
-display the new information.
+windows for the same buffer use the same @code{mode-line-format}, so
+their mode lines appear the same---except for scrolling percentages, and
+line and column numbers, since those depend on point and on how the
+window is scrolled. @code{header-line-format} is used likewise for
+header lines.
+
+ For efficiency, Emacs does not recompute the mode line and header
+line of a window in every redisplay. It does so when circumstances
+appear to call for it---for instance, if you change the window
+configuration, switch buffers, narrow or widen the buffer, scroll, or
+change the buffer's modification status. If you modify any of the
+variables referenced by @code{mode-line-format} (@pxref{Mode Line
+Variables}), or any other variables and data structures that affect
+how text is displayed (@pxref{Display}), you may want to force an
+update of the mode line so as to display the new information or
+display it in the new way.
@c Emacs 19 feature
@defun force-mode-line-update
-Force redisplay of the current buffer's mode line.
+Force redisplay of the current buffer's mode line and header line.
+The next redisplay will update the mode line and header line based on
+the latest values of all relevant variables.
+
+This function also forces recomputation of the menu bar menus
+and the frame title.
@end defun
The mode line is usually displayed in inverse video; see
* Mode Line Data:: The data structure that controls the mode line.
* Mode Line Variables:: Variables used in that data structure.
* %-Constructs:: Putting information into a mode line.
+* Properties in Mode:: Using text properties in the mode line.
+* Header Lines:: Like a mode line, but at the top.
@end menu
@node Mode Line Data
@cindex mode line construct
The mode line contents are controlled by a data structure of lists,
-strings, symbols, and numbers kept in the buffer-local variable
-@code{mode-line-format}. The data structure is called a @dfn{mode line
-construct}, and it is built in recursive fashion out of simpler mode line
-constructs.
+strings, symbols, and numbers kept in buffer-local variables. The data
+structure is called a @dfn{mode line construct}, and it is built in
+recursive fashion out of simpler mode line constructs. The same data
+structure is used for constructing frame titles (@pxref{Frame Titles})
+and header lines (@pxref{Header Lines}).
@defvar mode-line-format
The value of this variable is a mode line construct with overall
responsibility for the mode line format. The value of this variable
controls which other variables are used to form the mode line text, and
where they appear.
+
+If you set this variable to @code{nil} in a buffer, that buffer does not
+have a mode line. (This feature was added in Emacs 21.)
@end defvar
A mode line construct may be as simple as a fixed string of text, but
The default value of @code{mode-line-format} incorporates the values
of variables such as @code{mode-name} and @code{minor-mode-alist}.
-Because of this, very few modes need to alter @code{mode-line-format}.
-For most purposes, it is sufficient to alter the variables referenced by
-@code{mode-line-format}.
+Because of this, very few modes need to alter @code{mode-line-format}
+itself. For most purposes, it is sufficient to alter some of the
+variables that @code{mode-line-format} refers to.
A mode line construct may be a list, a symbol, or a string. If the
value is a list, each element may be a list, a symbol, or a string.
+ The mode line can display various faces, if the strings that control
+it have the @code{face} property. @xref{Properties in Mode}. In
+addition, the face @code{mode-line} is used as a default for the whole
+mode line (@pxref{Standard Faces}).
+
@table @code
@cindex percent symbol in mode line
@item @var{string}
A string as a mode line construct is displayed verbatim in the mode line
-except for @dfn{@code{%}-constructs}. Decimal digits after the @code{%}
+except for @dfn{@code{%}-constructs}. Decimal digits after the @samp{%}
specify the field width for space filling on the right (i.e., the data
is left justified). @xref{%-Constructs}.
@item @var{symbol}
A symbol as a mode line construct stands for its value. The value of
@var{symbol} is used as a mode line construct, in place of @var{symbol}.
-However, the symbols @code{t} and @code{nil} are ignored; so is any
+However, the symbols @code{t} and @code{nil} are ignored, as is any
symbol whose value is void.
There is one exception: if the value of @var{symbol} is a string, it is
elements recursively and concatenate the results. This is the most
common form of mode line construct.
+@item (:eval @var{form})
+A list whose first element is the symbol @code{:eval} says to evaluate
+@var{form}, and use the result as a string to display.
+(This feature is new as of Emacs 21.)
+
@item (@var{symbol} @var{then} @var{else})
-A list whose first element is a symbol is a conditional. Its meaning
-depends on the value of @var{symbol}. If the value is non-@code{nil},
-the second element, @var{then}, is processed recursively as a mode line
-element. But if the value of @var{symbol} is @code{nil}, the third
-element, @var{else}, is processed recursively. You may omit @var{else};
-then the mode line element displays nothing if the value of @var{symbol}
-is @code{nil}.
+A list whose first element is a symbol that is not a keyword specifies a
+conditional. Its meaning depends on the value of @var{symbol}. If the
+value is non-@code{nil}, the second element, @var{then}, is processed
+recursively as a mode line element. But if the value of @var{symbol} is
+@code{nil}, the third element, @var{else}, is processed recursively.
+You may omit @var{else}; then the mode line element displays nothing if
+the value of @var{symbol} is @code{nil}.
@item (@var{width} @var{rest}@dots{})
A list whose first element is an integer specifies truncation or
use the same variables that appear in the default value (@pxref{Mode
Line Variables}), rather than duplicating their contents or displaying
the information in another fashion. This way, customizations made by
-the user, by libraries (such as @code{display-time}) and by major modes
-via changes to those variables remain effective.
+the user or by Lisp programs (such as @code{display-time} and major
+modes) via changes to those variables remain effective.
@cindex Shell mode @code{mode-line-format}
Here is an example of a @code{mode-line-format} that might be
-useful for @code{shell-mode}, since it contains the hostname and default
+useful for @code{shell-mode}, since it contains the host name and default
directory.
@example
@group
(setq mode-line-format
- (list ""
+ (list "-"
+ 'mode-line-mule-info
'mode-line-modified
+ 'mode-line-frame-identification
"%b--"
@end group
- (getenv "HOST") ; @r{One element is not constant.}
+@group
+ ;; @r{Note that this is evaluated while making the list.}
+ ;; @r{It makes a mode line construct which is just a string.}
+ (getenv "HOST")
+@end group
":"
'default-directory
" "
'global-mode-string
" %[("
- 'mode-name
+ '(:eval (mode-line-mode-name))
'mode-line-process
'minor-mode-alist
"%n"
- ")%]----"
+ ")%]--"
@group
- (line-number-mode "L%l--")
+ '(which-func-mode ("" which-func-format "--"))
+ '(line-number-mode "L%l--")
+ '(column-number-mode "C%c--")
'(-3 . "%p")
"-%-"))
@end group
@end example
+@noindent
+(The variables @code{line-number-mode}, @code{column-number-mode}
+and @code{which-func-mode} enable particular minor modes; as usual,
+these variable names are also the minor mode command names.)
+
@node Mode Line Variables
@subsection Variables Used in the Mode Line
other variables could have the same effects on the mode line if
@code{mode-line-format} were changed to use them.
+@defvar mode-line-mule-info
+This variable holds the value of the mode-line construct that displays
+information about the language environment, buffer coding system, and
+current input method. @xref{Non-ASCII Characters}.
+@end defvar
+
@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, and @samp{--%%-} if the buffer is read only.
+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.
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.
+@end defvar
+
@defvar mode-line-buffer-identification
This variable identifies the buffer being displayed in the window. Its
-default value is @code{("Emacs: %17b")}, which means that it displays
-@samp{Emacs:} followed by seventeen characters of the buffer name. You
-may want to change this in modes such as Rmail that do not behave like a
-``normal'' Emacs.
+default value is @code{("%12b")}, which displays the buffer name, padded
+with spaces to at least 12 columns.
@end defvar
@defvar global-mode-string
load information.
The @samp{%M} construct substitutes the value of
-@code{global-mode-string}, but this is obsolete, since the variable is
-included directly in the mode line.
+@code{global-mode-string}, but that is obsolete, since the variable is
+included in the mode line from @code{mode-line-format}.
@end defvar
@defvar mode-name
@example
@group
minor-mode-alist
-@result{} ((abbrev-mode " Abbrev")
- (overwrite-mode " Ovwrt")
+@result{} ((vc-mode vc-mode)
+ (abbrev-mode " Abbrev")
+ (overwrite-mode overwrite-mode)
(auto-fill-function " Fill")
- (defining-kbd-macro " Def"))
+ (defining-kbd-macro " Def")
+ (isearch-mode isearch-mode))
@end group
@end example
-@noindent
-(In earlier Emacs versions, @code{auto-fill-function} was called
-@code{auto-fill-hook}.)
-
- @code{minor-mode-alist} is not buffer-local. The variables mentioned
-in the alist should be buffer-local if the minor mode can be enabled
-separately in each buffer.
+@code{minor-mode-alist} itself is not buffer-local. Each variable
+mentioned in the alist should be buffer-local if its minor mode can be
+enabled separately in each buffer.
@end defvar
@defvar mode-line-process
status in modes used for communicating with subprocesses. It is
displayed immediately following the major mode name, with no intervening
space. For example, its value in the @samp{*shell*} buffer is
-@code{(":@: %s")}, which allows the shell to display its status along
-with the major mode as: @samp{(Shell:@: run)}. Normally this variable
+@code{(":%s")}, which allows the shell to display its status along
+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:
+
+@defvar vc-mode
+The variable @code{vc-mode}, buffer-local in each buffer, records
+whether the buffer's visited file is maintained with version control,
+and, if so, which kind. Its value is a string that appears in the mode
+line, or @code{nil} for no version control.
+@end defvar
+
+ The variable @code{default-mode-line-format} is where
+@code{mode-line-format} usually gets its value:
+
@defvar default-mode-line-format
This variable holds the default @code{mode-line-format} for buffers
that do not override it. This is the same as @code{(default-value
'mode-line-format)}.
-The default value of @code{default-mode-line-format} is:
+The default value of @code{default-mode-line-format} is this list:
@example
@group
-(""
+("-"
+ mode-line-mule-info
mode-line-modified
+ mode-line-frame-identification
mode-line-buffer-identification
+@end group
" "
global-mode-string
- " %[("
- mode-name
-@end group
@group
+ " %[("
+ ;; @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"
- mode-line-process
- ")%]----"
+ ")%]--"
+@end group
+@group
+ (which-func-mode ("" which-func-format "--"))
+ (line-number-mode "L%l--")
+ (column-number-mode "C%c--")
(-3 . "%p")
"-%-")
@end group
@end example
@end defvar
-@defvar vc-mode
-The variable @code{vc-mode}, local in each buffer, records whether the
-buffer's visited file is maintained with version control, and, if so,
-which kind. Its value is @code{nil} for no version control, or a string
-that appears in the mode line.
-@end defvar
-
@node %-Constructs
@subsection @code{%}-Constructs in the Mode Line
The current buffer name, obtained with the @code{buffer-name} function.
@xref{Buffer Names}.
+@item %c
+The current column number of point.
+
@item %f
The visited file name, obtained with the @code{buffer-file-name}
function. @xref{Buffer File Name}.
-@item %*
-@samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
-@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
-@samp{-} otherwise. @xref{Buffer Modification}.
+@item %F
+The title (only on a window system) or the name of the selected frame.
+@xref{Window Frame Parameters}.
-@item %+
-@samp{*} if the buffer is modified, and @samp{-} otherwise.
+@item %l
+The current line number of point, counting within the accessible portion
+of the buffer.
-@item %s
-The status of the subprocess belonging to the current buffer, obtained with
-@code{process-status}. @xref{Process Information}.
+@item %n
+@samp{Narrow} when narrowing is in effect; nothing otherwise (see
+@code{narrow-to-region} in @ref{Narrowing}).
@item %p
-The percent of the buffer above the @strong{top} of window, or
-@samp{Top}, @samp{Bottom} or @samp{All}.
+The percentage of the buffer text above the @strong{top} of window, or
+@samp{Top}, @samp{Bottom} or @samp{All}. Note that the default
+mode-line specification truncates this to three characters.
@item %P
The percentage of the buffer text that is above the @strong{bottom} of
the text above the top), plus @samp{Top} if the top of the buffer is
visible on screen; or @samp{Bottom} or @samp{All}.
-@item %n
-@samp{Narrow} when narrowing is in effect; nothing otherwise (see
-@code{narrow-to-region} in @ref{Narrowing}).
+@item %s
+The status of the subprocess belonging to the current buffer, obtained with
+@code{process-status}. @xref{Process Information}.
+
+@item %t
+Whether the visited file is a text file or a binary file. This is a
+meaningful distinction only on certain operating systems (@pxref{MS-DOS
+File Types}).
+
+@item %*
+@samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
+@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
+@samp{-} otherwise. @xref{Buffer Modification}.
+
+@item %+
+@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
+@samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
+@samp{-} otherwise. This differs from @samp{%*} only for a modified
+read-only buffer. @xref{Buffer Modification}.
+
+@item %&
+@samp{*} if the buffer is modified, and @samp{-} otherwise.
@item %[
An indication of the depth of recursive editing levels (not counting
One @samp{]} for each recursive editing level (not counting minibuffer
levels).
+@item %-
+Dashes sufficient to fill the remainder of the mode line.
+
@item %%
The character @samp{%}---this is how to include a literal @samp{%} in a
string in which @code{%}-constructs are allowed.
-
-@item %-
-Dashes sufficient to fill the remainder of the mode line.
@end table
The following two @code{%}-constructs are still supported, but they are
@code{display-time} modifies the value of @code{global-mode-string}.
@end table
+@node Properties in Mode
+@subsection Properties in the Mode Line
+
+ Starting in Emacs 21, certain text properties are meaningful in the
+mode line. The @code{face} property affects the appearance of text; the
+@code{help-echo} property associate help strings with the text, and
+@code{local-map} can make the text mouse-sensitive.
+
+ There are three ways to specify text properties for text in the mode
+line:
+
+@enumerate
+@item
+Put a string with the @code{local-map} property directly into the
+mode-line data structure.
+
+@item
+Put a @code{local-map} property on a mode-line %-construct
+such as @samp{%12b}; then the expansion of the %-construct
+will have that same text property.
+
+@item
+Use a list containing @code{:eval @var{form}} in the mode-line data
+structure, and make @var{form} evaluate to a string that has a
+@code{local-map} property.
+@end enumerate
+
+ You use the @code{local-map} property to specify a keymap. Like any
+keymap, it can bind character keys and function keys; but that has no
+effect, since it is impossible to move point into the mode line. This
+keymap can only take real effect for mouse clicks.
+
+@node Header Lines
+@subsection Window Header Lines
+@cindex header line (of a window)
+@cindex window header line
+
+ Starting in Emacs 21, a window can have a @dfn{header line} at the
+top, just as it can have a mode line at the bottom. The header line
+feature works just like the mode line feature, except that it's
+controlled by different variables.
+
+@tindex header-line-format
+@defvar header-line-format
+This variable, local in every buffer, specifies how to display the
+header line, for windows displaying the buffer. The format of the value
+is the same as for @code{mode-line-format} (@pxref{Mode Line Data}).
+@end defvar
+
+@tindex default-header-line-format
+@defvar default-header-line-format
+This variable holds the default @code{header-line-format} for buffers
+that do not override it. This is the same as @code{(default-value
+'header-line-format)}.
+
+It is normally @code{nil}, so that ordinary buffers have no header line.
+@end defvar
+
+@node Imenu
+@section Imenu
+
+@cindex Imenu
+ @dfn{Imenu} is a feature that lets users select a definition or
+section in the buffer, from a menu which lists all of them, to go
+directly to that location in the buffer. Imenu works by constructing a
+buffer index which lists the names and buffer positions of the
+definitions, or other named portions of the buffer; then the user can
+choose one of them and move point to it. This section explains how to
+customize how Imenu finds the definitions or buffer portions for a
+particular major mode.
+
+ The usual and simplest way is to set the variable
+@code{imenu-generic-expression}:
+
+@defvar imenu-generic-expression
+This variable, if non-@code{nil}, specifies regular expressions for
+finding definitions for Imenu. In the simplest case, elements should
+look like this:
+
+@example
+(@var{menu-title} @var{regexp} @var{subexp})
+@end example
+
+Here, if @var{menu-title} is non-@code{nil}, it says that the matches
+for this element should go in a submenu of the buffer index;
+@var{menu-title} itself specifies the name for the submenu. If
+@var{menu-title} is @code{nil}, the matches for this element go directly
+in the top level of the buffer index.
+
+The second item in the list, @var{regexp}, is a regular expression
+(@pxref{Regular Expressions}); anything in the buffer that it matches is
+considered a definition, something to mention in the buffer index. The
+third item, @var{subexp}, indicates which subexpression in @var{regexp}
+matches the definition's name.
+
+An element can also look like this:
+
+@example
+(@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{})
+@end example
+
+Each match for this element creates a special index item which, if
+selected by the user, calls @var{function} with arguments consisting of
+the item name, the buffer position, and @var{arguments}.
+
+For Emacs Lisp mode, @var{pattern} could look like this:
+
+@c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]
+@example
+@group
+((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
+\\s-+\\([-A-Za-z0-9+]+\\)" 2)
+@end group
+@group
+ ("*Vars*" "^\\s-*(def\\(var\\|const\\)\
+\\s-+\\([-A-Za-z0-9+]+\\)" 2)
+@end group
+@group
+ ("*Types*"
+ "^\\s-*\
+(def\\(type\\|struct\\|class\\|ine-condition\\)\
+\\s-+\\([-A-Za-z0-9+]+\\)" 2))
+@end group
+@end example
+
+Setting this variable makes it buffer-local in the current buffer.
+@end defvar
+
+@defvar imenu-case-fold-search
+This variable controls whether matching against
+@var{imenu-generic-expression} is case-sensitive: @code{t}, the default,
+means matching should ignore case.
+
+Setting this variable makes it buffer-local in the current buffer.
+@end defvar
+
+@defvar imenu-syntax-alist
+This variable is an alist of syntax table modifiers to use while
+processing @code{imenu-generic-expression}, to override the syntax table
+of the current buffer. Each element should have this form:
+
+@example
+(@var{characters} . @var{syntax-description})
+@end example
+
+The @sc{car}, @var{characters}, can be either a character or a string.
+The element says to give that character or characters the syntax
+specified by @var{syntax-description}, which is passed to
+@code{modify-syntax-entry} (@pxref{Syntax Table Functions}).
+
+This feature is typically used to give word syntax to characters which
+normally have symbol syntax, and thus to simplify
+@code{imenu-generic-expression} and speed up matching.
+For example, Fortran mode uses it this way:
+
+@example
+ (setq imenu-syntax-alist '(("_$" . "w")))
+@end example
+
+The @code{imenu-generic-expression} patterns can then use @samp{\\sw+}
+instead of @samp{\\(\\sw\\|\\s_\\)+}. Note that this technique may be
+inconvenient when the mode needs to limit the initial character
+of a name to a smaller set of characters than are allowed in the rest
+of a name.
+
+Setting this variable makes it buffer-local in the current buffer.
+@end defvar
+
+ Another way to customize Imenu for a major mode is to set the
+variables @code{imenu-prev-index-position-function} and
+@code{imenu-extract-index-name-function}:
+
+@defvar imenu-prev-index-position-function
+If this variable is non-@code{nil}, its value should be a function that
+finds the next ``definition'' to put in the buffer index, scanning
+backward in the buffer from point. It should return @code{nil} if it
+doesn't find another ``definition'' before point. Otherwise it shuould
+leave point at the place it finds a ``definition,'' and return any
+non-@code{nil} value.
+
+Setting this variable makes it buffer-local in the current buffer.
+@end defvar
+
+@defvar imenu-extract-index-name-function
+If this variable is non-@code{nil}, its value should be a function to
+return the name for a definition, assuming point is in that definition
+as the @code{imenu-prev-index-position-function} function would leave
+it.
+
+Setting this variable makes it buffer-local in the current buffer.
+@end defvar
+
+ The last way to customize Imenu for a major mode is to set the
+variable @code{imenu-create-index-function}:
+
+@defvar imenu-create-index-function
+This variable specifies the function to use for creating a buffer index.
+The function should take no arguments, and return an index for the
+current buffer. It is called within @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.
+
+Setting this variable makes it buffer-local in the current buffer.
+@end defvar
+
+@defvar imenu-index-alist
+This variable holds the index alist for the current buffer.
+Setting it makes it buffer-local in the current buffer.
+
+Simple elements in the alist look like @code{(@var{index-name}
+. @var{index-position})}. Selecting a simple element has the effect of
+moving to position @var{index-position} in the buffer.
+
+Special elements look like @code{(@var{index-name} @var{position}
+@var{function} @var{arguments}@dots{})}. Selecting a special element
+performs
+
+@example
+(funcall @var{function} @var{index-name} @var{position} @var{arguments}@dots{})
+@end example
+
+A nested sub-alist element looks like @code{(@var{index-name}
+@var{sub-alist})}.
+@end defvar
+
+@node Font Lock Mode
+@section Font Lock Mode
+@cindex Font Lock Mode
+
+ @dfn{Font Lock mode} is a feature that automatically attaches
+@code{face} properties to certain parts of the buffer based on their
+syntactic role. How it parses the buffer depends on the major mode;
+most major modes define syntactic criteria for which faces to use in
+which contexts. This section explains how to customize Font Lock for a
+particular major mode.
+
+ Font Lock mode finds text to highlight in two ways: through syntactic
+parsing based on the syntax table, and through searching (usually for
+regular expressions). Syntactic fontification happens first; it finds
+comments and string constants, and highlights them using
+@code{font-lock-comment-face} and @code{font-lock-string-face}
+(@pxref{Faces for Font Lock}). Search-based fontification follows.
+
+@menu
+* Font Lock Basics::
+* Search-based Fontification::
+* Other Font Lock Variables::
+* Levels of Font Lock::
+* Faces for Font Lock::
+* Syntactic Font Lock::
+@end menu
+
+@node Font Lock Basics
+@subsection Font Lock Basics
+
+ There are several variables that control how Font Lock mode highlights
+text. But major modes should not set any of these variables directly.
+Instead, they should set @code{font-lock-defaults} as a buffer-local
+variable. The value assigned to this variable is used, if and when Font
+Lock mode is enabled, to set all the other variables.
+
+@defvar font-lock-defaults
+This variable is set by major modes, as a buffer-local variable, to
+specify how to fontify text in that mode. The value should look like
+this:
+
+@example
+(@var{keywords} @var{keywords-only} @var{case-fold}
+ @var{syntax-alist} @var{syntax-begin} @var{other-vars}@dots{})
+@end example
+
+The first element, @var{keywords}, indirectly specifies the value of
+@code{font-lock-keywords}. It can be a symbol, a variable 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.
+
+The second element, @var{keywords-only}, specifies the value of the
+variable @code{font-lock-keywords-only}. If this is non-@code{nil},
+syntactic fontification (of strings and comments) is not performed.
+
+The third element, @var{case-fold}, specifies the value of
+@code{font-lock-case-fold-search}. If it is non-@code{nil}, Font Lock
+mode ignores case when searching as directed by
+@code{font-lock-keywords}.
+
+If the fourth element, @var{syntax-alist}, is non-@code{nil}, it should be
+a list of cons cells of the form @code{(@var{char-or-string}
+. @var{string})}. These are used to set up a syntax table for
+fontification (@pxref{Syntax Table Functions}). The resulting syntax
+table is stored in @code{font-lock-syntax-table}.
+
+The fifth element, @var{syntax-begin}, specifies the value of
+@code{font-lock-beginning-of-syntax-function} (see below).
+
+All the remaining elements (if any) are collectively called
+@var{other-vars}. Each of these elements should have the form
+@code{(@var{variable} . @var{value})}---which means, make @var{variable}
+buffer-local and then set it to @var{value}. You can use these
+@var{other-vars} to set other variables that affect fontification,
+aside from those you can control with the first five elements.
+@end defvar
+
+@node Search-based Fontification
+@subsection Search-based Fontification
+
+ The most important variable for customizing Font Lock mode is
+@code{font-lock-keywords}. It specifies the search criteria for
+search-based fontification.
+
+@defvar font-lock-keywords
+This variable's value is a list of the keywords to highlight. Be
+careful when composing regular expressions for this list; a poorly
+written pattern can dramatically slow things down!
+@end defvar
+
+ Each element of @code{font-lock-keywords} specifies how to find
+certain cases of text, and how to highlight those cases. Font Lock mode
+processes the elements of @code{font-lock-keywords} one by one, and for
+each element, it finds and handles all matches. Ordinarily, once
+part of the text has been fontified already, this cannot be overridden
+by a subsequent match in the same text; but you can specify different
+behavior using the @var{override} element of a @var{highlighter}.
+
+ Each element of @code{font-lock-keywords} should have one of these
+forms:
+
+@table @code
+@item @var{regexp}
+Highlight all matches for @var{regexp} using
+@code{font-lock-keyword-face}. For example,
+
+@example
+;; @r{Highlight discrete occurrences of @samp{foo}}
+;; @r{using @code{font-lock-keyword-face}.}
+"\\<foo\\>"
+@end example
+
+The function @code{regexp-opt} (@pxref{Syntax of Regexps}) is useful for
+calculating optimal regular expressions to match a number of different
+keywords.
+
+@item @var{function}
+Find text by calling @var{function}, and highlight the matches
+it finds using @code{font-lock-keyword-face}.
+
+When @var{function} is called, it receives one argument, the limit of
+the search; it should searching at point, and not search beyond the
+limit. It should return non-@code{nil} if it succeeds, and set the
+match data to describe the match that was found. Returning @code{nil}
+indicates failure of the search.
+
+Fontification will call @var{function} repeatedly with the same limit,
+and with point where the previous invocation left it, until
+@var{function} fails. On failure, @var{function} need not reset point
+in any particular way.
+
+@item (@var{matcher} . @var{match})
+In this kind of element, @var{matcher} is either a regular
+expression or a function, as described above. The @sc{cdr},
+@var{match}, specifies which subexpression of @var{matcher} should be
+highlighted (instead of the entire text that @var{matcher} matched).
+
+@example
+;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},}
+;; @r{using @code{font-lock-keyword-face}.}
+("fu\\(bar\\)" . 1)
+@end example
+
+If you use @code{regexp-opt} to produce the regular expression
+@var{matcher}, then you can use @code{regexp-opt-depth} (@pxref{Syntax
+of Regexps}) to calculate the value for @var{match}.
+
+@item (@var{matcher} . @var{facename})
+In this kind of element, @var{facename} is an expression whose value
+specifies the face name to use for highlighting.
+
+@example
+;; @r{Highlight occurrences of @samp{fubar},}
+;; @r{using the face which is the value of @code{fubar-face}.}
+("fubar" . fubar-face)
+@end example
+
+@item (@var{matcher} . @var{highlighter})
+In this kind of element, @var{highlighter} is a list
+which specifies how to highlight matches found by @var{matcher}.
+It has the form
+
+@example
+(@var{subexp} @var{facename} @var{override} @var{laxmatch})
+@end example
+
+The @sc{car}, @var{subexp}, is an integer specifying which subexpression
+of the match to fontify (0 means the entire matching text). The second
+subelement, @var{facename}, specifies the face, as described above.
+
+The last two values in @var{highlighter}, @var{override} and
+@var{laxmatch}, are flags. If @var{override} is @code{t}, this element
+can override existing fontification made by previous elements of
+@code{font-lock-keywords}. If it is @code{keep}, then each character is
+fontified if it has not been fontified already by some other element.
+If it is @code{prepend}, the face @var{facename} is added to the
+beginning of the @code{face} property. If it is @code{append}, the face
+@var{facename} is added to the end of the @code{face} property.
+
+If @var{laxmatch} is non-@code{nil}, it means there should be no error
+if there is no subexpression numbered @var{subexp} in @var{matcher}.
+Obviously, fontification of the subexpression numbered @var{subexp} will
+not occur. However, fontification of other subexpressions (and other
+regexps) will continue. If @var{laxmatch} is @code{nil}, and the
+specified subexpression is missing, then an error is signalled which
+terminates search-based fontification.
+
+Here are some examples of elements of this kind, and what they do:
+
+@smallexample
+;; @r{Highlight occurrences of either @samp{foo} or @samp{bar},}
+;; @r{using @code{foo-bar-face}, even if they have already been highlighted.}
+;; @r{@code{foo-bar-face} should be a variable whose value is a face.}
+("foo\\|bar" 0 foo-bar-face t)
+
+;; @r{Highlight the first subexpression within each occurrence}
+;; @r{that the function @code{fubar-match} finds,}
+;; @r{using the face which is the value of @code{fubar-face}.}
+(fubar-match 1 fubar-face)
+@end smallexample
+
+@item (@var{matcher} @var{highlighters}@dots{})
+This sort of element specifies several @var{highlighter} lists for a
+single @var{matcher}. In order for this to be useful, each
+@var{highlighter} should have a different value of @var{subexp}; that is,
+each one should apply to a different subexpression of @var{matcher}.
+
+@ignore
+@item (@var{matcher} . @var{anchored})
+In this kind of element, @var{anchored} acts much like a
+@var{highlighter}, but it is more complex and can specify multiple
+successive searches.
+
+For highlighting single items, typically only @var{highlighter} is
+required. However, if an item or (typically) items are to be
+highlighted following the instance of another item (the anchor) then
+@var{anchored} may be required.
+
+It has this format:
+
+@example
+(@var{submatcher} @var{pre-match-form} @var{post-match-form} @var{highlighters}@dots{})
+@end example
+
+@c I can't parse this text -- rms
+where @var{submatcher} is much like @var{matcher}, with one
+exception---see below. @var{pre-match-form} and @var{post-match-form}
+are evaluated before the first, and after the last, instance
+@var{anchored}'s @var{submatcher} is used. Therefore they can be used
+to initialize before, and cleanup after, @var{submatcher} is used.
+Typically, @var{pre-match-form} is used to move to some position
+relative to the original @var{submatcher}, before starting with
+@var{anchored}'s @var{submatcher}. @var{post-match-form} might be used
+to move, before resuming with @var{anchored}'s parent's @var{matcher}.
+
+For example, an element of the form highlights (if not already highlighted):
+
+@example
+("\\<anchor\\>" (0 anchor-face) ("\\<item\\>" nil nil (0 item-face)))
+@end example
+
+Discrete occurrences of @samp{anchor} in the value of
+@code{anchor-face}, and subsequent discrete occurrences of @samp{item}
+(on the same line) in the value of @code{item-face}. (Here
+@var{pre-match-form} and @var{post-match-form} are @code{nil}.
+Therefore @samp{item} is initially searched for starting from the end of
+the match of @samp{anchor}, and searching for subsequent instance of
+@samp{anchor} resumes from where searching for @samp{item} concluded.)
+
+The above-mentioned exception is as follows. The limit of the
+@var{submatcher} search defaults to the end of the line after
+@var{pre-match-form} is evaluated. However, if @var{pre-match-form}
+returns a position greater than the position after @var{pre-match-form}
+is evaluated, that position is used as the limit of the search. It is
+generally a bad idea to return a position greater than the end of the
+line; in other words, the @var{submatcher} search should not span lines.
+
+@item (@var{matcher} @var{highlighters-or-anchoreds} ...)
+@end ignore
+
+@item (eval . @var{form})
+Here @var{form} is an expression to be evaluated the first time
+this value of @code{font-lock-keywords} is used in a buffer.
+Its value should have one of the forms described in this table.
+@end table
+
+@strong{Warning:} Do not design an element of @code{font-lock-keywords}
+to match text which spans lines; this does not work reliably. While
+@code{font-lock-fontify-buffer} handles multi-line patterns correctly,
+updating when you edit the buffer does not, since it considers text one
+line at a time.
+
+@node Other Font Lock Variables
+@subsection Other Font Lock Variables
+
+ This section describes additional variables that a major mode
+can set by means of @code{font-lock-defaults}.
+
+@defvar font-lock-keywords-only
+Non-@code{nil} means Font Lock should not fontify comments or strings
+syntactically; it should only fontify based on
+@code{font-lock-keywords}.
+@end defvar
+
+@ignore
+Other variables include those for buffer-specialized fontification functions,
+`font-lock-fontify-buffer-function', `font-lock-unfontify-buffer-function',
+`font-lock-fontify-region-function', `font-lock-unfontify-region-function',
+`font-lock-inhibit-thing-lock' and `font-lock-maximum-size'.
+@end ignore
+
+@defvar font-lock-keywords-case-fold-search
+Non-@code{nil} means that regular expression matching for the sake of
+@code{font-lock-keywords} should be case-insensitive.
+@end defvar
+
+@defvar font-lock-syntax-table
+This variable specifies the syntax table to use for fontification of
+comments and strings.
+@end defvar
+
+@defvar font-lock-beginning-of-syntax-function
+If this variable is non-@code{nil}, it should be a function to move
+point back to a position that is syntactically at ``top level'' and
+outside of strings or comments. Font Lock uses this when necessary
+to get the right results for syntactic fontification.
+
+This function is called with no arguments. It should leave point at the
+beginning of any enclosing syntactic block. Typical values are
+@code{beginning-of-line} (i.e., the start of the line is known to be
+outside a syntactic block), or @code{beginning-of-defun} for programming
+modes or @code{backward-paragraph} for textual modes (i.e., the
+mode-dependent function is known to move outside a syntactic block).
+
+If the value is @code{nil}, the beginning of the buffer is used as a
+position outside of a syntactic block. This cannot be wrong, but it can
+be slow.
+@end defvar
+
+@defvar font-lock-mark-block-function
+If this variable is non-@code{nil}, it should be a function that is
+called with no arguments, to choose an enclosing range of text for
+refontification for the command @kbd{M-g M-g}
+(@code{font-lock-fontify-block}).
+
+The function should report its choice by placing the region around it.
+A good choice is a range of text large enough to give proper results,
+but not too large so that refontification becomes slow. Typical values
+are @code{mark-defun} for programming modes or @code{mark-paragraph} for
+textual modes.
+@end defvar
+
+@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}.
+
+ Here are the conventions for how to define the levels of
+fontification:
+
+@itemize @bullet
+@item
+Level 1: highlight function declarations, file directives (such as include or
+import directives), strings and comments. The idea is speed, so only
+the most important and top-level components are fontified.
+
+@item
+Level 2: in addition to level 1, highlight all language keywords,
+including type names that act like keywords, as well as named constant
+values. The idea is that all keywords (either syntactic or semantic)
+should be fontified appropriately.
+
+@item
+Level 3: in addition to level 2, highlight the symbols being defined in
+function and variable declarations, and all builtin function names,
+wherever they appear.
+@end itemize
+
+@node Faces for Font Lock
+@subsection Faces for Font Lock
+
+ You can make Font Lock mode use any face, but several faces are
+defined specifically for Font Lock mode. Each of these symbols is both
+a face name, and a variable whose default value is the symbol itself.
+Thus, the default value of @code{font-lock-comment-face} is
+@code{font-lock-comment-face}. This means you can write
+@code{font-lock-comment-face} in a context such as
+@code{font-lock-keywords} where a face-name-valued expression is used.
+
+@table @code
+@item font-lock-comment-face
+@vindex font-lock-comment-face
+Used (typically) for comments.
+
+@item font-lock-string-face
+@vindex font-lock-string-face
+Used (typically) for string constants.
+
+@item font-lock-keyword-face
+@vindex font-lock-keyword-face
+Used (typically) for keywords---names that have special syntactic
+significance, like @code{for} and @code{if} in C.
+
+@item font-lock-builtin-face
+@vindex font-lock-builtin-face
+Used (typically) for built-in function names.
+
+@item font-lock-function-name-face
+@vindex font-lock-function-name-face
+Used (typically) for the name of a function being defined or declared,
+in a function definition or declaration.
+
+@item font-lock-variable-name-face
+@vindex font-lock-variable-name-face
+Used (typically) for the name of a variable being defined or declared,
+in a variable definition or declaration.
+
+@item font-lock-type-face
+@vindex font-lock-type-face
+Used (typically) for names of user-defined data types,
+where they are defined and where they are used.
+
+@item font-lock-constant-face
+@vindex font-lock-constant-face
+Used (typically) for constant names.
+
+@item font-lock-warning-face
+@vindex font-lock-warning-face
+Used (typically) for constructs that are peculiar, or that greatly
+change the meaning of other text. For example, this is used for
+@samp{;;;###autoload} cookies in Emacs Lisp, and for @code{#error}
+directives in C.
+@end table
+
+@node Syntactic Font Lock
+@subsection Syntactic Font Lock
+
+ Font Lock mode can be used to update @code{syntax-table} properties
+automatically. This is useful in languages for which a single syntax
+table by itself is not sufficient.
+
+@defvar font-lock-syntactic-keywords
+This variable enables and controls syntactic Font Lock. Its value
+should be a list of elements of this form:
+
+@example
+(@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch})
+@end example
+
+The parts of this element have the same meanings as in the corresponding
+sort of element of @code{font-lock-keywords},
+
+@example
+(@var{matcher} @var{subexp} @var{facename} @var{override} @var{laxmatch})
+@end example
+
+However, instead of specifying the value @var{facename} to use for the
+@code{face} property, it specifies the value @var{syntax} to use for the
+@code{syntax-table} property. Here, @var{syntax} can be a variable
+whose value is a syntax table, a syntax entry of the form
+@code{(@var{syntax-code} . @var{matching-char})}, or an expression whose
+value is one of those two types.
+@end defvar
+
@node Hooks
@section Hooks
@cindex hooks
A @dfn{hook} is a variable where you can store a function or functions
to be called on a particular occasion by an existing program. Emacs
provides hooks for the sake of customization. Most often, hooks are set
-up in the @file{.emacs} file, but Lisp programs can set them also.
+up in the init file (@pxref{Init File}), but Lisp programs can set them also.
@xref{Standard Hooks}, for a list of standard hook variables.
+@cindex normal hook
Most of the hooks in Emacs are @dfn{normal hooks}. These variables
-contain lists of functions to be called with no arguments. The reason
-most hooks are normal hooks is so that you can use them in a uniform
-way. You can always tell when a hook is a normal hook, because its
-name ends in @samp{-hook}.
+contain lists of functions to be called with no arguments. When the
+hook name ends in @samp{-hook}, that tells you it is normal. We try to
+make all hooks normal, as much as possible, so that you can use them in
+a uniform way.
+
+ Every major mode function is supposed to run a normal hook called the
+@dfn{mode hook} as the last step of initialization. This makes it easy
+for a user to customize the behavior of the mode, by overriding the
+buffer-local variable assignments already made by the mode. But hooks
+are used in other contexts too. For example, the hook
+@code{suspend-hook} runs just before Emacs suspends itself
+(@pxref{Suspending Emacs}).
The recommended way to add a hook function to a normal hook is by
calling @code{add-hook} (see below). The hook functions may be any of
a Function}). Most normal hook variables are initially void;
@code{add-hook} knows how to deal with this.
- As for abnormal hooks, those whose names end in @samp{-function} have
-a value that is a single function. Those whose names end in
-@samp{-hooks} have a value that is a list of functions. Any hook that
-is abnormal is abnormal because a normal hook won't do the job; either
-the functions are called with arguments, or their values are meaningful.
-The name shows you that the hook is abnormal and that you should look at
-its documentation string to see how to use it properly.
-
- Most major modes run hooks as the last step of initialization. This
-makes it easy for a user to customize the behavior of the mode, by
-overriding the local variable assignments already made by the mode. But
-hooks are used in other contexts too. For example, the hook
-@code{suspend-hook} runs just before Emacs suspends itself
-(@pxref{Suspending Emacs}).
-
- Here's an expression you can put in your @file{.emacs} file to turn on
-Auto Fill mode when in Lisp Interaction mode:
-
-@example
-(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
-@end example
-
- The next example shows how to use a hook to customize the way Emacs
-formats C code. (People often have strong personal preferences for one
-format or another.) Here the hook function is an anonymous lambda
-expression.
+@cindex abnormal hook
+ If the hook variable's name does not end with @samp{-hook}, that
+indicates it is probably an @dfn{abnormal hook}. Then you should look at its
+documentation to see how to use the hook properly.
-@cindex lambda expression in hook
-@example
-@group
-(add-hook 'c-mode-hook
- (function (lambda ()
- (setq c-indent-level 4
- c-argdecl-indent 0
- c-label-offset -4
-@end group
-@group
- c-continued-statement-indent 0
- c-brace-offset 0
- comment-column 40))))
+ If the variable's name ends in @samp{-functions} or @samp{-hooks},
+then the value is a list of functions, but it is abnormal in that either
+these functions are called with arguments or their values are used in
+some way. You can use @code{add-hook} to add a function to the list,
+but you must take care in writing the function. (A few of these
+variables are actually normal hooks which were named before we
+established the convention of using @samp{-hook} for them.)
-(setq c++-mode-hook c-mode-hook)
-@end group
-@end example
+ If the variable's name ends in @samp{-function}, then its value
+is just a single function, not a list of functions.
- Finally, here is an example of how to use the Text mode hook to
-provide a customized mode line for buffers in Text mode, displaying the
-default directory in addition to the standard components of the
-mode line. (This may cause the mode line to run out of space if you
-have very long file names or display the time and load.)
+ Here's an example that uses a mode hook to turn on Auto Fill mode when
+in Lisp Interaction mode:
@example
-@group
-(add-hook 'text-mode-hook
- (function (lambda ()
- (setq mode-line-format
-@end group
- '(mode-line-modified
- "Emacs: %14b"
- " "
- default-directory
- " "
- global-mode-string
- "%[("
- mode-name
- minor-mode-alist
-@group
- "%n"
- mode-line-process
- ") %]---"
- (-3 . "%p")
- "-%-")))))
-@end group
+(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
@end example
At the appropriate time, Emacs uses the @code{run-hooks} function to
-run particular hooks. This function calls the hook functions you have
-added with @code{add-hooks}.
+run particular hooks. This function calls the hook functions that have
+been added with @code{add-hook}.
-@defun run-hooks &rest hookvar
+@defun run-hooks &rest hookvars
This function takes one or more hook variable names as arguments, and
-runs each hook in turn. Each @var{hookvar} argument should be a symbol
-that is a hook variable. These arguments are processed in the order
-specified.
+runs each hook in turn. Each argument should be a symbol that is a hook
+variable. These arguments are processed in the order specified.
If a hook variable has a non-@code{nil} value, that value may be a
function or a list of functions. If the value is a function (either a
-lambda expression or a symbol with a function definition), it is
-called. If it is a list, the elements are called, in order.
-The hook functions are called with no arguments.
+lambda expression or a symbol with a function definition), it is called.
+If it is a list, the elements are called, in order. The hook functions
+are called with no arguments. Nowadays, storing a single function in
+the hook variable is semi-obsolete; you should always use a list of
+functions.
-For example, here's how @code{emacs-lisp-hooks} runs its mode hook:
+For example, here's how @code{emacs-lisp-mode} runs its mode hook:
@example
(run-hooks 'emacs-lisp-mode-hook)
@end example
@end defun
-@defun add-hook hook function &optional append
+@defun run-hook-with-args hook &rest args
+This function is the way to run an abnormal hook which passes arguments
+to the hook functions. It calls each of the hook functions, passing
+each of them the arguments @var{args}.
+@end defun
+
+@defun run-hook-with-args-until-failure hook &rest args
+This function is the way to run an abnormal hook which passes arguments
+to the hook functions, and stops as soon as any hook function fails. It
+calls each of the hook functions, passing each of them the arguments
+@var{args}, until some hook function returns @code{nil}. Then it stops,
+and returns @code{nil} if some hook function returned @code{nil}.
+Otherwise it returns a non-@code{nil} value.
+@end defun
+
+@defun run-hook-with-args-until-success hook &rest args
+This function is the way to run an abnormal hook which passes arguments
+to the hook functions, and stops as soon as any hook function succeeds.
+It calls each of the hook functions, passing each of them the arguments
+@var{args}, until some hook function returns non-@code{nil}. Then it
+stops, and returns whatever was returned by the last hook function
+that was called.
+@end defun
+
+@defun add-hook hook function &optional append local
This function is the handy way to add function @var{function} to hook
variable @var{hook}. The argument @var{function} may be any valid Lisp
function with the proper number of arguments. For example,
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).
+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.
-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.
+If @var{local} is non-@code{nil}, that says to make the new hook
+function buffer-local in the current buffer and automatically calls
+@code{make-local-hook} to make the hook itself buffer-local.
@end defun
-@defun remove-hook hook function
+@defun remove-hook hook function &optional local
This function removes @var{function} from the hook variable @var{hook}.
+
+If @var{local} is non-@code{nil}, that says to remove @var{function}
+from the buffer-local hook list instead of from the global hook list.
+If the hook variable itself is not buffer-local, then the value of
+@var{local} makes no difference.
+@end defun
+
+@defun make-local-hook hook
+This function makes the hook variable @code{hook} buffer-local in the
+current buffer. When a hook variable is buffer-local, it can have
+buffer-local and global hook functions, and @code{run-hooks} runs all of
+them.
+
+This function works by adding @code{t} as an element of the buffer-local
+value. That serves as a flag to use the hook functions listed in the default
+value of the hook variable, as well as those listed in the buffer-local value.
+Since @code{run-hooks} understands this flag, @code{make-local-hook}
+works with all normal hooks. It works for only some non-normal
+hooks---those whose callers have been updated to understand this meaning
+of @code{t}.
+
+Do not use @code{make-local-variable} directly for hook variables; it is
+not sufficient.
@end defun
HCoop / bpt / emacs.git / blobdiff