* 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
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
@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 @acronym{ASCII} character set.)}
(while (< i ?0)
(modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table)
(setq i (1+ i)))
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 one
-of those. The meaning of other arguments is not specified.
+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
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 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}
+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.
+@code{display-time-string}, which holds a string containing the time
+and load information.
The @samp{%M} construct substitutes the value of
@code{global-mode-string}, but that is obsolete, since the variable is
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
-The value of @var{facename} is usually a face name (a symbol), but it
-can also be a list of the form
+However, @var{facespec} can also be a list of the form
@example
(face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{})
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{font-lock-face} property. If it
-is @code{append}, the face @var{facename} is added to the end of the
+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
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
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{facename} in
+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
@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-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
@section Hooks
@cindex 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.
-
-With @code{add-hook}, you can also add hook functions to the
-buffer-local value of a hook variable. If necessary, @code{add-hook}
-first makes the hook variable buffer-local and adds @code{t} to the
-buffer-local value. The element @code{t} in the buffer-local value of
-a hook variable acts as a signal for the various functions that run
-hooks to run the default value of the hook variable as well; @code{t}
-is basically substituted with the elements of the default value of a
-hook variable. Since @code{add-hook} normally adds hook functions to
-the front of hook variables, this means that the hook functions in the
-buffer-local value are called before the hook functions in the default
-value of hook variables.
+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
@defun run-hooks &rest hookvars
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 hook variable. These arguments are processed in the
-order specified.
+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.
+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.
For example, here's how @code{emacs-lisp-mode} runs its mode hook:
@end defmac
@defun run-hook-with-args hook &rest args
-This function is the way to run an abnormal hook. 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
@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} is not added if it
-is already present on @var{hook} (comparisons are performed with
-@code{equal}; @pxref{Equality Predicates}). @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
@defun remove-hook hook function &optional local
This function removes @var{function} from the hook variable
-@var{hook}. The argument @var{function} is compared with elements of
-@var{hook} by means of @code{equal} (@pxref{Equality Predicates}).
-This means that you can remove symbols with a function definition as
-well as lambda expressions.
+@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.
HCoop / bpt / emacs.git / blobdiff