@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999,
+@c 2003, 2004, 2005 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/modes
-@node Modes, Documentation, Keymaps, Top
+@node Modes, Documentation, Keymaps, Top
@chapter Major and Minor Modes
@cindex mode
* Imenu:: How a mode can provide a menu
of definitions in the buffer.
* Font Lock Mode:: How modes can highlight text according to syntax.
+* Desktop Save Mode:: How modes can have buffer state saved between
+ Emacs sessions.
* Hooks:: How to use hooks; how to write code that provides hooks.
@end menu
parent argument, since it automatically enforces the most important
coding conventions for you.
+@findex define-generic-mode
+ For a very simple programming language major mode that handles
+comments and fontification, you can use @code{define-generic-mode}
+in @file{generic.el}.
+
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
* Example Major Modes:: Text mode and Lisp modes.
* Auto Major Mode:: How Emacs chooses the major mode automatically.
* Mode Help:: Finding out how to use a mode.
-* Derived Modes:: Defining a new major mode based on another major
+* Derived Modes:: Defining a new major mode based on another major
mode.
+* Mode Hooks:: Hooks run at the end of major mode functions.
@end menu
@node Major Mode Conventions
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.
+A major mode can also rebind the keys @kbd{M-n}, @kbd{M-p} and
+@kbd{M-s}. The bindings for @kbd{M-n} and @kbd{M-p} should normally
+be some kind of ``moving forward and backward,'' but this does not
+necessarily mean cursor motion.
+
+It is legitimate for a major mode to rebind a standard key sequence if
+it provides a command that does ``the same job'' in a way better
+suited to the text this mode is used for. 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.
+
+It is also legitimate for a major mode to rebind a standard key
+sequence whose standard meaning is rarely useful in that mode. For
+instance, minibuffer modes rebind @kbd{M-r}, whose standard meaning is
+rarely of any use in the minibuffer. Major modes such as Dired or
+Rmail that do not allow self-insertion of text can reasonably redefine
+letters and other printing characters as special commands.
@item
Major modes must not define @key{RET} to do anything other than insert
@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
+Major modes should not alter options that are primarily 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
@item
@cindex abbrev tables in modes
The mode may have its own abbrev table or may share one with other
-related modes. If it has its own abbrev table, it should store this in
-a variable named @code{@var{modename}-mode-abbrev-table}. @xref{Abbrev
-Tables}.
+related modes. If it has its own abbrev table, it should store this
+in a variable named @code{@var{modename}-mode-abbrev-table}. If the
+major mode command defines any abbrevs itself, it should pass @code{t}
+for the @var{system-flag} argument to @code{define-abbrev}.
+@xref{Abbrev Tables}.
@item
The mode should specify how to do highlighting for Font Lock mode, by
@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
+variable @code{imenu-generic-expression}, for the pair of variables
+@code{imenu-prev-index-position-function} and
+@code{imenu-extract-index-name-function}, or for the variable
@code{imenu-create-index-function} (@pxref{Imenu}).
@item
would affect buffers that do not use this mode. It is undesirable for a
mode to have such global effects. @xref{Buffer-Local Variables}.
-With rare exceptions, the only reasonable way to use
+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.
@cindex major 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}.
+hook, with @code{run-mode-hooks}, as the very last thing it
+does. @xref{Mode Hooks}.
@item
-The major mode command may also run the hooks of some more basic modes.
-For example, @code{indented-text-mode} runs @code{text-mode-hook} as
-well as @code{indented-text-mode-hook}. It may run these other hooks
-immediately before the mode's own hook (that is, after everything else),
-or it may run them earlier.
+The major mode command may start by calling some other major mode
+command (called the @dfn{parent mode}) and then alter some of its
+settings. A mode that does this is called a @dfn{derived mode}. The
+recommended way to define one is to use @code{define-derived-mode},
+but this is not required. Such a mode should use
+@code{delay-mode-hooks} around its entire body (including the call to
+the parent mode command) @emph{except} for the final call to
+@code{run-mode-hooks}, which runs the derived mode's hook. (Using
+@code{define-derived-mode} does this automatically.) @xref{Derived
+Modes}, and @ref{Mode Hooks}.
@item
If something special should be done if the user switches a buffer from
major mode command symbol should have a property named @code{mode-class}
with value @code{special}, put on as follows:
-@cindex @code{mode-class} property
+@kindex mode-class @r{(property)}
@cindex @code{special}
@example
(put 'funny-mode 'mode-class 'special)
@end example
@noindent
-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,
+This tells Emacs that new buffers created while the current buffer is
+in Funny mode should not inherit Funny mode, in case
+@code{default-major-mode} is @code{nil}. Modes such as Dired, Rmail,
and Buffer List use this feature.
@item
file that contains the mode definition. @xref{Auto Major Mode}.
@item
-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 init files (@pxref{Init File}).
+In the comments that document the file, 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 init files
+(@pxref{Init File}).
@item
@cindex mode loading
@smallexample
@group
-;; @r{Create mode-specific tables.}
-(defvar text-mode-syntax-table nil
- "Syntax table used while in text mode.")
+;; @r{Create the syntax table for this mode.}
+(defvar text-mode-syntax-table
+ (let ((st (make-syntax-table)))
+ (modify-syntax-entry ?\" ". " st)
+ (modify-syntax-entry ?\\ ". " st)
+ ;; We add `p' so that M-c on 'hello' leads to 'Hello' rather than 'hello'.
+ (modify-syntax-entry ?' "w p" st)
+ st)
+ "Syntax table used while in `text-mode'.")
@end group
+;; @r{Create the keymap for this mode.}
@group
-(if text-mode-syntax-table
- () ; @r{Do not change the table if it is already set up.}
- (setq text-mode-syntax-table (make-syntax-table))
- (modify-syntax-entry ?\" ". " text-mode-syntax-table)
- (modify-syntax-entry ?\\ ". " text-mode-syntax-table)
- (modify-syntax-entry ?' "w " text-mode-syntax-table))
+(defvar text-mode-map
+ (let ((map (make-sparse-keymap)))
+ (define-key map "\e\t" 'ispell-complete-word)
+ (define-key map "\es" 'center-line)
+ (define-key map "\eS" 'center-paragraph)
+ map)
+ "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.")
@end group
+@end smallexample
+
+ Here is how the actual mode command is defined now:
+@smallexample
@group
-(defvar text-mode-abbrev-table nil
- "Abbrev table used while in text mode.")
-(define-abbrev-table 'text-mode-abbrev-table ())
+(define-derived-mode text-mode nil "Text"
+ "Major mode for editing text written for humans to read.
+In this mode, paragraphs are delimited only by blank or white lines.
+You can thus get the full benefit of adaptive filling
+ (see the variable `adaptive-fill-mode').
+\\@{text-mode-map@}
+Turning on Text mode runs the normal hook `text-mode-hook'."
@end group
-
@group
-(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 "\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))
+ (make-local-variable 'text-mode-variant)
+ (setq text-mode-variant t)
+ ;; @r{These two lines are a feature added recently.}
+ (set (make-local-variable 'require-final-newline)
+ mode-require-final-newline)
+ (set (make-local-variable 'indent-line-function) 'indent-relative))
@end group
@end smallexample
- Here is the complete major mode function definition for Text mode:
+ But here is how it was defined formerly, before
+@code{define-derived-mode} existed:
@smallexample
+@group
+;; @r{This isn't needed nowadays, since @code{define-derived-mode} does it.}
+(defvar text-mode-abbrev-table nil
+ "Abbrev table used while in text mode.")
+(define-abbrev-table 'text-mode-abbrev-table ())
+@end group
+
@group
(defun text-mode ()
"Major mode for editing text intended for humans to read...
(set-syntax-table text-mode-syntax-table)
@end group
@group
+ ;; @r{These four lines are absent from the current version}
+ ;; @r{not because this is done some other way, but rather}
+ ;; @r{because nowadays Text mode uses the normal definition of paragraphs.}
(make-local-variable 'paragraph-start)
(setq paragraph-start (concat "[ \t]*$\\|" page-delimiter))
(make-local-variable 'paragraph-separate)
@group
(setq mode-name "Text")
(setq major-mode 'text-mode)
- (run-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
+ (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
; @r{customize the mode with a hook.}
@end group
@end smallexample
@smallexample
@group
;; @r{Create mode-specific table variables.}
-(defvar lisp-mode-syntax-table nil "")
-(defvar emacs-lisp-mode-syntax-table nil "")
+(defvar lisp-mode-syntax-table nil "")
(defvar lisp-mode-abbrev-table nil "")
@end group
@group
-(if (not emacs-lisp-mode-syntax-table) ; @r{Do not change the table}
- ; @r{if it is already set.}
+(defvar emacs-lisp-mode-syntax-table
+ (let ((table (make-syntax-table)))
(let ((i 0))
- (setq emacs-lisp-mode-syntax-table (make-syntax-table))
@end group
@group
- ;; @r{Set syntax of chars up to 0 to class of chars that are}
+ ;; @r{Set syntax of chars up to @samp{0} to say they are}
;; @r{part of symbol names but not words.}
- ;; @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)))
- @dots{}
+ ;; @r{(The digit @samp{0} is @code{48} in the @acronym{ASCII} character set.)}
+ (while (< i ?0)
+ (modify-syntax-entry i "_ " table)
+ (setq i (1+ i)))
+ ;; @r{@dots{} similar code follows for other character ranges.}
+@end group
+@group
+ ;; @r{Then set the syntax codes for characters that are special in Lisp.}
+ (modify-syntax-entry ? " " table)
+ (modify-syntax-entry ?\t " " table)
+ (modify-syntax-entry ?\f " " table)
+ (modify-syntax-entry ?\n "> " table)
@end group
@group
- ;; @r{Set the syntax for other characters.}
- (modify-syntax-entry ? " " emacs-lisp-mode-syntax-table)
- (modify-syntax-entry ?\t " " emacs-lisp-mode-syntax-table)
- @dots{}
+ ;; @r{Give CR the same syntax as newline, for selective-display.}
+ (modify-syntax-entry ?\^m "> " table)
+ (modify-syntax-entry ?\; "< " table)
+ (modify-syntax-entry ?` "' " table)
+ (modify-syntax-entry ?' "' " table)
+ (modify-syntax-entry ?, "' " table)
+@end group
+@group
+ ;; @r{@dots{}likewise for many other characters@dots{}}
+ (modify-syntax-entry ?\( "() " table)
+ (modify-syntax-entry ?\) ")( " table)
+ (modify-syntax-entry ?\[ "(] " table)
+ (modify-syntax-entry ?\] ")[ " table))
+ table))
@end group
@group
- (modify-syntax-entry ?\( "() " emacs-lisp-mode-syntax-table)
- (modify-syntax-entry ?\) ")( " emacs-lisp-mode-syntax-table)
- @dots{}))
;; @r{Create an abbrev table for lisp-mode.}
(define-abbrev-table 'lisp-mode-abbrev-table ())
@end group
@smallexample
@group
(defun lisp-mode-variables (lisp-syntax)
- (cond (lisp-syntax
- (set-syntax-table lisp-mode-syntax-table)))
+ (when lisp-syntax
+ (set-syntax-table lisp-mode-syntax-table))
(setq local-abbrev-table lisp-mode-abbrev-table)
@dots{}
@end group
(defvar shared-lisp-mode-map ()
"Keymap for commands shared by all sorts of Lisp modes.")
+;; @r{Putting this @code{if} after the @code{defvar} is an older style.}
(if shared-lisp-mode-map
()
(setq shared-lisp-mode-map (make-sparse-keymap))
@end smallexample
Finally, here is the complete major mode function definition for
-Lisp mode.
+Lisp mode.
@smallexample
@group
; @r{finds out what to describe.}
(setq mode-name "Lisp") ; @r{This goes into the mode line.}
(lisp-mode-variables t) ; @r{This defines various variables.}
+ (make-local-variable 'comment-start-skip)
+ (setq comment-start-skip
+ "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *")
+ (make-local-variable 'font-lock-keywords-case-fold-search)
+ (setq font-lock-keywords-case-fold-search t)
@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}
+ (run-mode-hooks 'lisp-mode-hook)) ; @r{This permits the user to use a}
; @r{hook to customize the mode.}
@end group
@end smallexample
in particular. Other major modes are defined in effect by comparison
with this one---their definitions say what to change, starting from
Fundamental mode. The @code{fundamental-mode} function does @emph{not}
-run any hooks; you're not supposed to customize it. (If you want Emacs
+run any mode hooks; you're not supposed to customize it. (If you want Emacs
to behave differently in Fundamental mode, change the @emph{global}
state of Emacs.)
@end deffn
How Major Modes are Chosen, emacs, The GNU Emacs Manual}.
@end defun
-@defopt default-major-mode
+@defopt default-major-mode
This variable holds the default major mode for new buffers. The
standard value is @code{fundamental-mode}.
@end group
@group
("\\.el\\'" . emacs-lisp-mode)
- ("\\.c\\'" . c-mode)
+ ("\\.c\\'" . c-mode)
("\\.h\\'" . c-mode)
@dots{})
@end group
@smallexample
@group
(setq auto-mode-alist
- (append
+ (append
;; @r{File name (within directory) starts with a dot.}
- '(("/\\.[^/]*\\'" . fundamental-mode)
+ '(("/\\.[^/]*\\'" . fundamental-mode)
;; @r{File name has no dot.}
- ("[^\\./]*\\'" . fundamental-mode)
+ ("[^\\./]*\\'" . fundamental-mode)
;; @r{File name ends in @samp{.C}.}
("\\.C\\'" . c++-mode))
auto-mode-alist))
The new command @var{variant} is defined to call the function
@var{parent}, then override certain aspects of that parent mode:
-@itemize @bullet
+@itemize @bullet
@item
The new mode has its own keymap, named @code{@var{variant}-map}.
@code{define-derived-mode} initializes this map to inherit from
@item
The new mode has its own syntax table, kept in the variable
@code{@var{variant}-syntax-table}.
-@code{define-derived-mode} initializes this variable by copying
+@code{define-derived-mode} initializes this variable by copying
@code{@var{parent}-syntax-table}, if it is not already set.
@item
The new mode has its own abbrev table, kept in the variable
@code{@var{variant}-abbrev-table}.
-@code{define-derived-mode} initializes this variable by copying
+@code{define-derived-mode} initializes this variable by copying
@code{@var{parent}-abbrev-table}, if it is not already set.
@item
The new mode has its own mode hook, @code{@var{variant}-hook},
which it runs in standard fashion as the very last thing that it does.
-(The new mode also runs the mode hook of @var{parent} as part
+(The new mode also runs the mode hook of @var{parent} as part
of calling @var{parent}.)
@end itemize
In addition, you can specify how to override other aspects of
@var{parent} with @var{body}. The command @var{variant}
-evaluates the forms in @var{body} after setting up all its usual
+evaluates the forms in @var{body} after setting up all its usual
overrides, just before running @code{@var{variant}-hook}.
The argument @var{docstring} specifies the documentation string for the
@code{define-derived-mode} does that automatically.
@end defmac
+@node Mode Hooks
+@subsection Mode Hooks
+
+The two last things a major mode function does is to run its mode
+hook and finally the mode independent normal hook
+@code{after-change-major-mode-hook}. If the major mode is a derived
+mode, that is if it calls another major mode (the parent mode) in its
+body, then the parent's mode hook is run just before the derived
+mode's hook. Neither the parent's mode hook nor
+@code{after-change-major-mode-hook} are run at the end of the actual
+call to the parent mode. This applies recursively if the parent mode
+has itself a parent. That is, the mode hooks of all major modes called
+directly or indirectly by the major mode function are all run in
+sequence at the end, just before @code{after-change-major-mode-hook}.
+
+If you are customizing a major mode, rather than defining one, the
+above is all you need to know about the hooks run at the end of a
+major mode. This also applies if you use @code{define-derived-mode}
+to define a major mode, because that macro will automatically
+implement the above for you.
+
+Programmers wishing to define a major mode without using
+@code{define-derived-mode}, should make sure that their major mode
+follows the above conventions. @xref{Major Mode Conventions}, for how
+this should be accomplished. Below, we give some implementation
+details.
+
+@defun run-mode-hooks &rest hookvars
+Major modes should run their mode hook using this function. It is
+similar to @code{run-hooks} (@pxref{Hooks}), but if run inside a
+@code{delay-mode-hooks} form, this function does not run any hooks.
+Instead, it arranges for @var{hookvars} to be run at a later call to
+the function. Otherwise, @code{run-mode-hooks} runs any delayed hooks
+in order, then @var{hookvars} and finally
+@code{after-change-major-mode-hook}.
+@end defun
+
+@defmac delay-mode-hooks body...
+This macro executes @var{body} like @code{progn}, but all calls to
+@code{run-mode-hooks} inside @var{body} delay running their hooks.
+They will be run by the first call to @code{run-mode-hooks} after exit
+from @code{delay-mode-hooks}.
+@end defmac
+
+@defvar after-change-major-mode-hook
+Every major mode function should run this normal hook at its very end.
+It normally does not need to do so explicitly. Indeed, a major mode
+function should normally run its mode hook with @code{run-mode-hooks}
+as the very last thing it does and @code{run-mode-hooks} runs
+@code{after-change-major-mode-hook} at its very end.
+@end defvar
+
@node Minor Modes
@section Minor Modes
@cindex minor mode
way to insert the necessary hook into the rest of Emacs. Minor mode
keymaps make this easier than it used to be.
+@defvar minor-mode-list
+The value of this variable is a list of all minor mode commands.
+@end defvar
+
@menu
* Minor Mode Conventions:: Tips for writing a minor mode.
* Keymaps and Minor Modes:: How a minor mode can have its own keymap.
other tables.
In addition, there are several conventions that are specific to
-minor modes.
+minor modes. (The easiest way to follow all the conventions is to use
+the macro @code{define-minor-mode}; @ref{Defining Minor Modes}.)
@itemize @bullet
@item
Its job is to enable and disable the mode by setting the variable.
The command should accept one optional argument. If the argument is
-@code{nil}, it should toggle the mode (turn it on if it is off, and off
-if it is on). Otherwise, it should turn the mode on if the argument is
-a positive integer, a symbol other than @code{nil} or @code{-}, or a
-list whose @sc{car} is such an integer or symbol; it should turn the
-mode off otherwise.
+@code{nil}, it should toggle the mode (turn it on if it is off, and
+off if it is on). It should turn the mode on if the argument is a
+positive integer, the symbol @code{t}, or a list whose @sc{car} is one
+of those. It should turn the mode off if the argument is a negative
+integer or zero, the symbol @code{-}, or a list whose @sc{car} is a
+negative integer or zero. The meaning of other arguments is not
+specified.
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
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
+invoking 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}),
@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.
+implementing a mode in one self-contained definition.
-@defmac define-minor-mode mode doc &optional init-value mode-indicator keymap body...
+@defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args... body...
@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
+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
+The string @var{lighter} 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.
@example
(@var{key-sequence} . @var{definition})
@end example
+
+The above three arguments @var{init-value}, @var{lighter}, and
+@var{keymap} can be (partially) omitted when @var{keyword-args} are
+used. The @var{keyword-args} consist of keywords followed by
+corresponding values. A few keywords have special meanings:
+
+@table @code
+@item :global @var{global}
+If non-@code{nil} specifies that the minor mode should be global.
+By default, minor modes are buffer-local.
+
+@item :init-value @var{init-value}
+This is equivalent to specifying @var{init-value} positionally.
+
+@item :lighter @var{lighter}
+This is equivalent to specifying @var{lighter} positionally.
+
+@item :keymap @var{keymap}
+This is equivalent to specifying @var{keymap} positionally.
+@end table
+
+Any other keyword arguments are passed passed directly to the
+@code{defcustom} generated for the variable @var{mode}.
+
+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}.
@end defmac
+@findex easy-mmode-define-minor-mode
+ The name @code{easy-mmode-define-minor-mode} is an alias
+for this macro.
+
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.
+With no argument, this command toggles the mode.
Non-null prefix argument turns on the mode.
Null prefix argument turns off the mode.
;; The indicator for the mode line.
" Hungry"
;; The minor mode bindings.
- '(("\C-\^?" . hungry-electric-delete)
- ("\C-\M-\^?"
- . (lambda ()
- (interactive)
- (hungry-electric-delete t)))))
+ '(("\C-\^?" . hungry-electric-delete))
+ :group 'hunger)
@end smallexample
@noindent
@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}}.
+mode is enabled. It initializes the keymap with a key binding for
+@kbd{C-@key{DEL}}. It puts the variable @code{hungry-mode} into
+custom group @code{hunger}. There are no @var{body} forms---many
+minor modes don't need any.
+ Here's an equivalent way to write it:
-@findex easy-mmode-define-minor-mode
- The name @code{easy-mmode-define-minor-mode} is an alias
-for this macro.
+@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.
+ :initial-value nil
+ ;; The indicator for the mode line.
+ :lighter " Hungry"
+ ;; The minor mode bindings.
+ :keymap
+ '(("\C-\^?" . hungry-electric-delete)
+ ("\C-\M-\^?"
+ . (lambda ()
+ (interactive)
+ (hungry-electric-delete t))))
+ :group 'hunger)
+@end smallexample
@node Mode Line Format
-@section Mode Line Format
+@section Mode-Line Format
@cindex mode line
Each Emacs window (aside from minibuffer windows) typically has a mode
display it in the new way.
@c Emacs 19 feature
-@defun force-mode-line-update
+@defun force-mode-line-update &optional all
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.
+the latest values of all relevant variables. With optional
+non-@code{nil} @var{all}, force redisplay of all mode lines and header
+lines.
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
-@code{mode-line-inverse-video} in @ref{Inverse Video}.
+ The selected window's mode line is usually displayed in a different
+color using the face @code{mode-line}. Other windows' mode lines
+appear in the face @code{mode-line-inactive} instead. @xref{Faces}.
A window that is just one line tall does not display either a mode
line or a header line, even if the variables call for one. A window
* %-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.
+* Emulating Mode Line:: Formatting text as the mode line would.
@end menu
@node Mode Line Data
@subsection The Data Structure of the Mode Line
-@cindex mode line construct
+@cindex mode-line construct
- The mode line contents are controlled by a data structure of lists,
+ The mode-line contents are controlled by a data structure of lists,
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 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
+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
+ A mode-line construct may be as simple as a fixed string of text, but
it usually specifies how to use other variables to construct the text.
-Many of these variables are themselves defined to have mode line
+Many of these variables are themselves defined to have mode-line
constructs as their values.
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}
-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
+of variables such as @code{mode-line-position} and
+@code{mode-line-modes} (which in turn incorporates the values of the
+variables @code{mode-name} and @code{minor-mode-alist}). 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} either directly or indirectly 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
@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
+A string as a mode-line construct is displayed verbatim in the mode line
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}.
+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, as is any
symbol whose value is void.
There is one exception: if the value of @var{symbol} is a string, it is
displayed verbatim: the @code{%}-constructs are not recognized.
+Unless @var{symbol} is marked as ``risky'' (i.e., it has a
+non-@code{nil} @code{risky-local-variable} property), all properties in
+any strings, as well as all @code{:eval} and @code{:propertize} forms in
+the value of that symbol will be ignored.
+
@item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{})
A list whose first element is a string or list means to process all the
elements recursively and concatenate the results. This is the most
-common form of mode line construct.
+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 (:propertize @var{elt} @var{props}@dots{})
+A list whose first element is the symbol @code{:propertize} says to
+process the mode-line construct @var{elt} recursively and add the text
+properties specified by @var{props} to the result. The argument
+@var{props} should consist of zero or more pairs @var{text-property}
+@var{value}. (This feature is new as of Emacs 22.1.)
+
@item (@var{symbol} @var{then} @var{else})
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
+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
+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
padding of the results of @var{rest}. The remaining elements
-@var{rest} are processed recursively as mode line constructs and
+@var{rest} are processed recursively as mode-line constructs and
concatenated together. Then the result is space filled (if
@var{width} is positive) or truncated (to @minus{}@var{width} columns,
if @var{width} is negative) on the right.
'mode-line-mule-info
'mode-line-modified
'mode-line-frame-identification
- "%b--"
+ "%b--"
@end group
@group
;; @r{Note that this is evaluated while making the list.}
- ;; @r{It makes a mode line construct which is just a string.}
+ ;; @r{It makes a mode-line construct which is just a string.}
(getenv "HOST")
@end group
- ":"
+ ":"
'default-directory
" "
'global-mode-string
" %[("
'(:eval (mode-line-mode-name))
- 'mode-line-process
- 'minor-mode-alist
- "%n"
+ 'mode-line-process
+ 'minor-mode-alist
+ "%n"
")%]--"
@group
'(which-func-mode ("" which-func-format "--"))
'(line-number-mode "L%l--")
'(column-number-mode "C%c--")
- '(-3 . "%p")
+ '(-3 "%p")
"-%-"))
@end group
@end example
@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
+@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
with spaces to at least 12 columns.
@end defvar
-@defvar global-mode-string
-This variable holds a mode line spec that appears in the mode line by
-default, just after the buffer name. The command @code{display-time}
-sets @code{global-mode-string} to refer to the variable
-@code{display-time-string}, which holds a string containing the time and
-load information.
+@defvar mode-line-position
+This variable indicates the position in the buffer. Here is a
+simplified version of its default value. The actual default value
+also specifies addition of the @code{help-echo} text property.
-The @samp{%M} construct substitutes the value of
-@code{global-mode-string}, but that is obsolete, since the variable is
-included in the mode line from @code{mode-line-format}.
+@example
+@group
+((-3 "%p")
+ (size-indication-mode (8 " of %I"))
+@end group
+@group
+ (line-number-mode
+ ((column-number-mode
+ (10 " (%l,%c)")
+ (6 " L%l")))
+ ((column-number-mode
+ (5 " C%c")))))
+@end group
+@end example
+
+This means that @code{mode-line-position} displays at least the buffer
+percentage and possibly the buffer size, the line number and the column
+number.
+@end defvar
+
+@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
+@defvar mode-line-modes
+This variable displays the buffer's major and minor modes. Here is a
+simplified version of its default value. The real default value also
+specifies addition of text properties.
+
+@example
+@group
+("%[(" mode-name
+ mode-line-process minor-mode-alist
+ "%n" ")%]--")
+@end group
+@end example
+
+So @code{mode-line-modes} normally also displays the recursive editing
+level, information on the process status and whether narrowing is in
+effect.
+@end defvar
+
+ The following three variables are used in @code{mode-line-modes}:
+
@defvar mode-name
This buffer-local variable holds the ``pretty'' name of the current
buffer's major mode. Each major mode should set this variable so that the
mode name will appear in the mode line.
@end defvar
+@defvar mode-line-process
+This buffer-local variable contains the mode-line information on 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
+is @code{nil}.
+@end defvar
+
@defvar minor-mode-alist
This variable holds an association list whose elements specify how the
mode line should indicate that a minor mode is active. Each element of
(@var{minor-mode-variable} @var{mode-line-string})
@end example
-More generally, @var{mode-line-string} can be any mode line spec. It
-appears in the mode line when the value of @var{minor-mode-variable} is
-non-@code{nil}, and not otherwise. These strings should begin with
+More generally, @var{mode-line-string} can be any mode-line spec. It
+appears in the mode line when the value of @var{minor-mode-variable}
+is non-@code{nil}, and not otherwise. These strings should begin with
spaces so that they don't run together. Conventionally, the
-@var{minor-mode-variable} for a specific mode is set to a non-@code{nil}
-value when that minor mode is activated.
-
-The default value of @code{minor-mode-alist} is:
-
-@example
-@group
-minor-mode-alist
-@result{} ((vc-mode vc-mode)
- (abbrev-mode " Abbrev")
- (overwrite-mode overwrite-mode)
- (auto-fill-function " Fill")
- (defining-kbd-macro " Def")
- (isearch-mode isearch-mode))
-@end group
-@end example
+@var{minor-mode-variable} for a specific mode is set to a
+non-@code{nil} value when that minor mode is activated.
@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
-This buffer-local variable contains the mode line information on 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
-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 global-mode-string
+This variable holds a mode-line spec that, by default, appears in the
+mode line just after the @code{which-func-mode} minor mode if set,
+else after @code{mode-line-modes}. The command @code{display-time}
+sets @code{global-mode-string} to refer to the variable
+@code{display-time-string}, which holds a string containing the time
+and load information.
-@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.
+The @samp{%M} construct substitutes the value of
+@code{global-mode-string}, but that is obsolete, since the variable is
+included in the mode line from @code{mode-line-format}.
@end defvar
The variable @code{default-mode-line-format} is where
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 this list:
+Here is a simplified version of the default value of
+@code{default-mode-line-format}. The real default value also
+specifies addition of text properties.
@example
@group
mode-line-buffer-identification
@end group
" "
- global-mode-string
-@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"
- ")%]--"
-@end group
+ mode-line-position
+ (vc-mode vc-mode)
+ " "
@group
+ mode-line-modes
(which-func-mode ("" which-func-format "--"))
- (line-number-mode "L%l--")
- (column-number-mode "C%c--")
- (-3 . "%p")
+ (global-mode-string ("--" global-mode-string))
"-%-")
@end group
@end example
The title (only on a window system) or the name of the selected frame.
@xref{Window Frame Parameters}.
+@item %i
+The size of the accessible part of the current buffer; basically
+@code{(- (point-max) (point-min))}.
+
+@item %I
+Like @samp{%i}, but the size is printed in a more readable way by using
+@samp{k} for 10^3, @samp{M} for 10^6, @samp{G} for 10^9, etc., to
+abbreviate.
+
@item %l
The current line number of point, counting within the accessible portion
of the buffer.
@node Properties in Mode
@subsection Properties in the Mode Line
+@cindex text 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
+ There are four 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.
+Put a string with a text property directly into the mode-line data
+structure.
+
+@item
+Put a text property on a mode-line %-construct such as @samp{%12b}; then
+the expansion of the %-construct will have that same text property.
@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.
+Use a @code{(:propertize @var{elt} @var{props}@dots{})} construct to
+give @var{elt} a text property specified by @var{props}.
@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.
+structure, and make @var{form} evaluate to a string that has a text
+property.
@end enumerate
You use the @code{local-map} property to specify a keymap. Like any
effect, since it is impossible to move point into the mode line. This
keymap can only take real effect for mouse clicks.
+ When the mode line refers to a variable which does not have a
+non-@code{nil} @code{risky-local-variable} property, any text
+properties given or specified within that variable's values are
+ignored. This is because such properties could otherwise specify
+functions to be called, and those functions could come from file
+local variables.
+
@node Header Lines
@subsection Window Header Lines
@cindex header line (of a window)
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
+feature works just like the mode-line feature, except that it's
controlled by different variables.
@tindex header-line-format
It is normally @code{nil}, so that ordinary buffers have no header line.
@end defvar
+@node Emulating Mode Line
+@subsection Emulating Mode-Line Formatting
+
+ You can use the function @code{format-mode-line} to compute
+the text that would appear in a mode line or header line
+based on certain mode-line specification.
+
+@defun format-mode-line format &optional face window buffer
+This function formats a line of text according to @var{format} as if
+it were generating the mode line for @var{window}, but instead of
+displaying the text in the mode line or the header line, it returns
+the text as a string. The argument @var{window} defaults to the
+selected window. If @var{buffer} is non-@code{nil}, all the
+information used is taken from @var{buffer}; by default, it comes from
+@var{window}'s buffer.
+
+The value string normally has text properties that correspond to the
+faces, keymaps, etc., that the mode line would have. And any character
+for which no @code{face} property is specified gets a default
+value which is usually @var{face}. (If @var{face} is @code{t},
+that stands for either @code{mode-line} if @var{window} is selected,
+otherwise @code{mode-line-inactive}.)
+
+However, if @var{face} is an integer, the value has no text properties.
+
+For example, @code{(format-mode-line header-line-format)} returns the
+text that would appear in the selected window's header line (@code{""}
+if it has no header line). @code{(format-mode-line header-line-format
+'header-line)} returns the same text, with each character
+carrying the face that it will have in the header line itself.
+@end defun
+
@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
+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.
+choose one of them and move point to it. Major modes can add a menu
+bar item to use Imenu using @code{imenu-add-to-menubar}.
+
+@defun imenu-add-to-menubar name
+This function defines a local menu bar item named @var{name}
+to run Imenu.
+@end defun
+
+ The user-level commands for using Imenu are described in the Emacs
+Manual (@pxref{Imenu,, Imenu, emacs, the Emacs Manual}). This section
+explains how to customize Imenu's method of finding 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:
+This variable, if non-@code{nil}, is a list that specifies regular
+expressions for finding definitions for Imenu. Simple elements of
+@code{imenu-generic-expression} look like this:
@example
-(@var{menu-title} @var{regexp} @var{subexp})
+(@var{menu-title} @var{regexp} @var{index})
@end example
Here, if @var{menu-title} is non-@code{nil}, it says that the matches
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.
+(@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{index}, is a non-negative integer that indicates
+which subexpression in @var{regexp} matches the definition's name.
An element can also look like this:
(@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}.
+Like in the previous case, each match for this element creates an
+index item. However, if this index item is selected by the user, it
+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:
+For Emacs Lisp mode, @code{imenu-generic-expression} could look like
+this:
@c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]
@example
@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.
+This variable controls whether matching against the regular
+expressions in the value of @code{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
For example, Fortran mode uses it this way:
@example
- (setq imenu-syntax-alist '(("_$" . "w")))
+(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.
+The @code{imenu-generic-expression} regular expressions 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
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
+doesn't find another ``definition'' before point. Otherwise it should
leave point at the place it finds a ``definition,'' and return any
non-@code{nil} value.
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.
+This variable specifies the function to use for creating a buffer
+index. The function should take no arguments, and return an index
+alist 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.
+The index alist can have three types of elements. Simple elements
+look like this:
-Setting this variable makes it buffer-local in the current buffer.
-@end defvar
+@example
+(@var{index-name} . @var{index-position})
+@end example
+
+Selecting a simple element has the effect of moving to position
+@var{index-position} in the buffer. Special elements look like this:
+
+@example
+(@var{index-name} @var{index-position} @var{function} @var{arguments}@dots{})
+@end example
-@defvar imenu-index-alist
-This variable holds the index alist for the current buffer.
-Setting it makes it buffer-local in the current buffer.
+Selecting a special element performs:
-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.
+@example
+(funcall @var{function}
+ @var{index-name} @var{index-position} @var{arguments}@dots{})
+@end example
-Special elements look like @code{(@var{index-name} @var{position}
-@var{function} @var{arguments}@dots{})}. Selecting a special element
-performs
+A nested sub-alist element looks like this:
@example
-(funcall @var{function} @var{index-name} @var{position} @var{arguments}@dots{})
+(@var{menu-title} @var{sub-alist})
@end example
-A nested sub-alist element looks like @code{(@var{index-name}
-@var{sub-alist})}.
+It creates the submenu @var{menu-title} specified by @var{sub-alist}.
+
+The default value of @code{imenu-create-index-function} is
+@code{imenu-default-create-index-function}. This function uses
+@code{imenu-prev-index-position-function} and
+@code{imenu-extract-index-name-function} to produce the index alist.
+However, if either of these two variables is @code{nil}, the default
+function uses @code{imenu-generic-expression} instead.
+
+Setting this variable makes it buffer-local in the current buffer.
@end defvar
@node Font Lock Mode
(@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::
+* Font Lock Basics:: Overview of customizing Font Lock.
+* Search-based Fontification:: Fontification based on regexps.
+* Other Font Lock Variables:: Additional customization facilities.
+* Levels of Font Lock:: Each mode can define alternative levels
+ so that the user can select more or less.
+* Precalculated Fontification:: How Lisp programs that produce the buffer
+ contents can also specify how to fontify it.
+* Faces for Font Lock:: Special faces specifically for Font Lock.
+* Syntactic Font Lock:: Defining character syntax based on context
+ using the Font Lock mechanism.
@end menu
@node Font Lock Basics
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
+@code{font-lock-keywords-case-fold-search}. If it is non-@code{nil}, Font Lock
mode ignores case when searching as directed by
@code{font-lock-keywords}.
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
+the search; it should begin 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.
@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.
+@item (@var{matcher} . @var{facespec})
+In this kind of element, @var{facespec} is an object which specifies
+the face variable to use for highlighting. In the simplest case, it
+is a Lisp variable (a symbol), whose value should be a face name.
@example
;; @r{Highlight occurrences of @samp{fubar},}
("fubar" . fubar-face)
@end example
+However, @var{facespec} can also be a list of the form
+
+@example
+(face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{})
+@end example
+
+to specify various text properties to put on the text that matches.
+If you do this, be sure to add the other text property names that you
+set in this way to the value of @code{font-lock-extra-managed-props}
+so that the properties will also be cleared out when they are no longer
+appropriate.
+
@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})
+(@var{subexp} @var{facespec} @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.
+subelement, @var{facespec}, 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.
+@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 specified by
+@var{facespec} is added to the beginning of the @code{font-lock-face}
+property. If it is @code{append}, the face is added to the end of the
+@code{font-lock-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
+specified subexpression is missing, then an error is signaled which
terminates search-based fontification.
Here are some examples of elements of this kind, and what they do:
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.
+line at a time. If you have patterns that typically only span one
+line but can occasionally span two or three, such as
+@samp{<title>...</title>}, you can ask font-lock to be more careful by
+setting @code{font-lock-multiline} to @code{t}. But it still will not
+work in all cases.
@node Other Font Lock Variables
@subsection Other Font Lock Variables
textual modes.
@end defvar
+@defvar font-lock-extra-managed-props
+Additional properties (other than @code{font-lock-face}) that are
+being managed by Font Lock mode. Font Lock mode normally manages only
+the @code{font-lock-face} property; if you want it to manage others as
+well, you must specify them in a @var{facespec} in
+@code{font-lock-keywords} as well as adding them to this list.
+@end defvar
+
+@defvar font-lock-syntactic-face-function
+A function to determine which face to use for a given syntactic
+element (a string or a comment). The function is called with one
+argument, the parse state at point returned by
+@code{parse-partial-sexp}, and should return a face. The default
+value returns @code{font-lock-comment-face} for comments and
+@code{font-lock-string-face} for strings.
+
+This can be used to highlighting different kinds of strings or
+comments differently. It is also sometimes abused together with
+@code{font-lock-syntactic-keywords} to highlight elements that span
+multiple lines, but this is too obscure to document in this manual.
+@end defvar
+
@node Levels of Font Lock
@subsection Levels of Font Lock
wherever they appear.
@end itemize
+@node Precalculated Fontification
+@subsection Precalculated Fontification
+
+ In addition to using @code{font-lock-defaults} for search-based
+fontification, you may use the special character property
+@code{font-lock-face} (@pxref{Special Properties}). This property
+acts just like the explicit @code{face} property, but its activation
+is toggled when the user calls @kbd{M-x font-lock-mode}. Using
+@code{font-lock-face} is especially convenient for special modes
+which construct their text programmatically, such as
+@code{list-buffers} and @code{occur}.
+
+If your mode does not use any of the other machinery of Font Lock
+(i.e. it only uses the @code{font-lock-face} property), you can tell
+Emacs not to load all of font-lock.el (unless it's already loaded), by
+setting the variable @code{font-lock-core-only} to non-@code{nil} as
+part of the @code{font-lock-defaults} settings. Here is the canonical
+way to do this:
+
+@example
+(set (make-local-variable 'font-lock-defaults)
+ '(nil t nil nil nil (font-lock-core-only . t)))
+@end example
+
@node Faces for Font Lock
@subsection Faces for Font Lock
@vindex font-lock-comment-face
Used (typically) for comments.
+@item font-lock-doc-face
+@vindex font-lock-doc-face
+Used (typically) for documentation strings in the code.
+
@item font-lock-string-face
@vindex font-lock-string-face
Used (typically) for string constants.
@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.
+in a function definition or declaration.
@item font-lock-variable-name-face
@vindex font-lock-variable-name-face
@vindex font-lock-constant-face
Used (typically) for constant names.
+@item font-lock-preprocessor-face
+@vindex font-lock-preprocessor-face
+Used (typically) for preprocessor commands.
+
@item font-lock-warning-face
@vindex font-lock-warning-face
Used (typically) for constructs that are peculiar, or that greatly
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:
+This variable enables and controls syntactic Font Lock. It is
+normally set via @code{font-lock-defaults}. Its value should be a
+list of elements of this form:
@example
(@var{matcher} @var{subexp} @var{syntax} @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.
+@code{face} property, it specifies the value @var{syntax} to use for
+the @code{syntax-table} property. Here, @var{syntax} can be a string
+(as taken by @code{modify-syntax-entry}), a syntax table, a cons cell
+(as returned by @code{string-to-syntax}), or an expression whose value
+is one of those two types. @var{override} cannot be @code{prepend} or
+@code{append}.
+
+For example, an element of the form:
+
+@example
+("\\$\\(#\\)" 1 ".")
+@end example
+
+highlights syntactically a hash character when following a dollar
+character, with a SYNTAX of @code{"."} (meaning punctuation syntax).
+Assuming that the buffer syntax table specifies hash characters to
+have comment start syntax, the element will only highlight hash
+characters that do not follow dollar characters as comments
+syntactically.
+
+An element of the form:
+
+@example
+ ("\\('\\).\\('\\)"
+ (1 "\"")
+ (2 "\""))
+@end example
+
+highlights syntactically both single quotes which surround a single
+character, with a SYNTAX of @code{"\""} (meaning string quote syntax).
+Assuming that the buffer syntax table does not specify single quotes
+to have quote syntax, the element will only highlight single quotes of
+the form @samp{'@var{c}'} as strings syntactically. Other forms, such
+as @samp{foo'bar} or @samp{'fubar'}, will not be highlighted as
+strings.
+
+@end defvar
+
+@node Desktop Save Mode
+@section Desktop Save Mode
+@cindex desktop save mode
+
+@dfn{Desktop Save Mode} is a feature to save the state of Emacs from
+one session to another. The user-level commands for using Desktop
+Save Mode are described in the GNU Emacs Manual (@pxref{Saving Emacs
+Sessions,,, emacs, the GNU Emacs Manual}). Modes whose buffers visit
+a file, don't have to do anything to use this feature.
+
+For buffers not visiting a file to have their state saved, the major
+mode must bind the buffer local variable @code{desktop-save-buffer} to
+a non-@code{nil} value.
+
+@defvar desktop-save-buffer
+If this buffer-local variable is non-@code{nil}, the buffer will have
+its state saved in the desktop file at desktop save. If the value is
+a function, it is called at desktop save with argument
+@var{desktop-dirname}, and its value is saved in the desktop file along
+with the state of the buffer for which it was called. When file names
+are returned as part of the auxiliary information, they should be
+formatted using the call
+
+@example
+(desktop-file-name @var{file-name} @var{desktop-dirname})
+@end example
+
+@end defvar
+
+For buffers not visiting a file to be restored, the major mode must
+define a function to do the job, and that function must be listed in
+the alist @code{desktop-buffer-mode-handlers}.
+
+@defvar desktop-buffer-mode-handlers
+Alist with elements
+
+@example
+(@var{major-mode} . @var{restore-buffer-function})
+@end example
+
+The function @var{restore-buffer-function} will be called with
+argument list
+
+@example
+(@var{buffer-file-name} @var{buffer-name} @var{desktop-buffer-misc})
+@end example
+
+and it should return the restored buffer.
+Here @var{desktop-buffer-misc} is the value returned by the function
+optionally bound to @code{desktop-save-buffer}.
+
@end defvar
@node Hooks
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
-the valid kinds of functions that @code{funcall} accepts (@pxref{What Is
-a Function}). Most normal hook variables are initially void;
-@code{add-hook} knows how to deal with this.
+the valid kinds of functions that @code{funcall} accepts (@pxref{What
+Is a Function}). Most normal hook variables are initially void;
+@code{add-hook} knows how to deal with this. You can add hooks either
+globally or buffer-locally with @code{add-hook}.
@cindex abnormal hook
If the hook variable's name does not end with @samp{-hook}, that
been added with @code{add-hook}.
@defun run-hooks &rest hookvars
-This function takes one or more hook variable names as arguments, and
-runs each hook in turn. Each argument should be a symbol that is a hook
-variable. These arguments are processed in the order specified.
+This function takes one or more normal hook variable names as
+arguments, and runs each hook in turn. Each argument should be a
+symbol that is a normal 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. 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-mode} runs its mode hook:
-
-@example
-(run-hooks 'emacs-lisp-mode-hook)
-@end example
+function or a list of functions. (The former option is considered
+obsolete.) 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
+that isn't a function, its elements are called, consecutively. All
+the hook functions are called with no arguments.
@end defun
@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}.
+This function is the way to run an abnormal hook and always call all
+of the hook functions. It calls each of the hook functions one by
+one, 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.
+This function is the way to run an abnormal hook until one of the hook
+functions fails. It calls each of the hook functions, passing each of
+them the arguments @var{args}, until some hook function returns
+@code{nil}. It then stops and returns @code{nil}. If none of the
+hook functions return @code{nil}, 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.
+This function is the way to run an abnormal hook until a 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. If all hook functions return
+@code{nil}, it returns @code{nil} as well.
@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,
+variable @var{hook}. You can use it for abnormal hooks as well as for
+normal hooks. @var{function} can be any Lisp function that can accept
+the proper number of arguments for @var{hook}. For example,
@example
(add-hook 'text-mode-hook 'my-text-hook-function)
@noindent
adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
-You can use @code{add-hook} for abnormal hooks as well as for normal
-hooks.
+If @var{function} is already present in @var{hook} (comparing using
+@code{equal}), then @code{add-hook} does not add it a second time.
It is best to design your hook functions so that the order in which they
are executed does not matter. Any dependence on the order is ``asking
-for trouble.'' However, the order is predictable: normally,
+for trouble''. However, the order is predictable: normally,
@var{function} goes at the front of the hook list, so it will be
executed first (barring another @code{add-hook} call). If the optional
argument @var{append} is non-@code{nil}, the new hook function goes at
the end of the hook list and will be executed last.
-If @var{local} is non-@code{nil}, that says to add @var{function}
-to the buffer-local hook list instead of to the global hook list.
+If @var{local} is non-@code{nil}, that says to add @var{function} to
+the buffer-local hook list instead of to the global hook list. If
+needed, this makes the hook buffer-local and adds @code{t} to the
+buffer-local value. The latter acts as a flag to run the hook
+functions in the default value as well as in the local value.
@end defun
@defun remove-hook hook function &optional local
-This function removes @var{function} from the hook variable @var{hook}.
+This function removes @var{function} from the hook variable
+@var{hook}. It compares @var{function} with elements of @var{hook}
+using @code{equal}, so it works for both symbols and lambda
+expressions.
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.
@end defun
+
+@ignore
+ arch-tag: 4c7bff41-36e6-4da6-9e7f-9b9289e27c8e
+@end ignore
HCoop / bpt / emacs.git / blobdiff