* 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
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
@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
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
@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
HCoop / bpt / emacs.git / blobdiff