definition is distinct from that of Text mode, but uses that of Text mode.
Even if the new mode is not an obvious derivative of any other mode,
-it can be convenient to define it as a derivative of
-@code{fundamental-mode}, so that @code{define-derived-mode} can
-automatically enforce the most important coding conventions for you.
+it is convenient to use @code{define-derived-mode} with a @code{nil}
+parent argument, since it automatically enforces the most important
+coding conventions for you.
Rmail Edit mode offers an example of changing the major mode
temporarily for a buffer, so it can be edited in a different way (with
The code for existing major modes follows various coding conventions,
including conventions for local keymap and syntax table initialization,
global names, and hooks. Please follow these conventions when you
-define a new major mode:
+define a new major mode.
+
+ This list of conventions is only partial, because each major mode
+should aim for consistency in general with other Emacs major modes.
+This makes Emacs as a whole more coherent. It is impossible to list
+here all the possible points where this issue might come up; if the
+Emacs developers point out an area where your major mode deviates from
+the usual conventions, please make it compatible.
@itemize @bullet
@item
have names that start with the major mode name (or with an abbreviation
of it if the name is long). @xref{Coding Conventions}.
+@item
+In a major mode for editing some kind of structured text, such as a
+programming language, indentation of text according to structure is
+probably useful. So the mode should set @code{indent-line-function}
+to a suitable function, and probably customize other variables
+for indentation.
+
@item
@cindex keymaps in modes
The major mode should usually have its own keymap, which is used as the
text can reasonably redefine letters and other printing characters as
editing commands. Dired and Rmail both do this.
+@item
+Major modes must not define @key{RET} to do anything other than insert
+a newline. The command to insert a newline and then indent is
+@kbd{C-j}. Please keep this distinction uniform for all major modes.
+
+@item
+Major modes should not alter options that are primary a matter of user
+preference, such as whether Auto-Fill mode is enabled. Leave this to
+each user to decide. However, a major mode should customize other
+variables so that Auto-Fill mode will work usefully @emph{if} the user
+decides to use it.
+
@item
@cindex syntax tables in modes
The mode may have its own syntax table or may share one with other
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 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.
(define-key hypertext-mode-map
[down-mouse-3] 'do-hyper-link)
@end example
+
+Do not write an @code{interactive} spec in the definition;
+@code{define-derived-mode} does that automatically.
@end defmac
@node Minor Modes
window is scrolled. @code{header-line-format} is used likewise for
header lines.
- The mode line and header line of a window are normally updated
-whenever a different buffer is shown in the window, or when the buffer's
-modified-status changes from @code{nil} to @code{t} or vice-versa. If
-you modify any of the variables referenced by @code{mode-line-format}
-(@pxref{Mode Line Variables}), or any other variables and data
-structures that affect how text is displayed (@pxref{Display}), you may
-want to force an update of the mode line so as to display the new
-information or display it in the new way.
+ For efficiency, Emacs does not recompute the mode line and header
+line of a window in every redisplay. It does so when circumstances
+appear to call for it---for instance, if you change the window
+configuration, switch buffers, narrow or widen the buffer, scroll, or
+change the buffer's modification status. If you modify any of the
+variables referenced by @code{mode-line-format} (@pxref{Mode Line
+Variables}), or any other variables and data structures that affect
+how text is displayed (@pxref{Display}), you may want to force an
+update of the mode line so as to display the new information or
+display it in the new way.
@c Emacs 19 feature
@defun force-mode-line-update
Force redisplay of the current buffer's mode line and header line.
+The next redisplay will update the mode line and header line based on
+the latest values of all relevant variables.
+
+This function also forces recomputation of the menu bar menus
+and the frame title.
@end defun
The mode line is usually displayed in inverse video; see
@code{mode-line-inverse-video} in @ref{Inverse Video}.
+ 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
+that is two lines tall cannot display both a mode line and a header
+line at once; if the variables call for both, only the mode line
+actually appears.
+
@menu
* Mode Line Data:: The data structure that controls the mode line.
* Mode Line Variables:: Variables used in that data structure.
it finds using @code{font-lock-keyword-face}.
When @var{function} is called, it receives one argument, the limit of
-the search. It should return non-@code{nil} if it succeeds, and set the
-match data to describe the match that was found.
+the search; it should searching at point, and not search beyond the
+limit. It should return non-@code{nil} if it succeeds, and set the
+match data to describe the match that was found. Returning @code{nil}
+indicates failure of the search.
+
+Fontification will call @var{function} repeatedly with the same limit,
+and with point where the previous invocation left it, until
+@var{function} fails. On failure, @var{function} need not reset point
+in any particular way.
@item (@var{matcher} . @var{match})
In this kind of element, @var{matcher} is either a regular
these functions are called with arguments or their values are used in
some way. You can use @code{add-hook} to add a function to the list,
but you must take care in writing the function. (A few of these
-variables are actually normal hooks which were named before we
-established the convention of using @samp{-hook} for them.)
+variables, notably those ending in @samp{-hooks}, are actually
+normal hooks which were named before we established the convention of
+using @samp{-hook} for them.)
If the variable's name ends in @samp{-function}, then its value
is just a single function, not a list of functions.
argument @var{append} is non-@code{nil}, the new hook function goes at
the end of the hook list and will be executed last.
-If @var{local} is non-@code{nil}, that says to make the new hook
-function buffer-local in the current buffer. Before you can do this, you must
-make the hook itself buffer-local by calling @code{make-local-hook}
-(@strong{not} @code{make-local-variable}). If the hook itself is not
-buffer-local, then the value of @var{local} makes no difference---the
-hook function is always global.
+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.
@end defun
@defun remove-hook hook function &optional local
If @var{local} is non-@code{nil}, that says to remove @var{function}
from the buffer-local hook list instead of from the global hook list.
-If the hook variable itself is not buffer-local, then the value of
-@var{local} makes no difference.
-@end defun
-
-@defun make-local-hook hook
-This function makes the hook variable @code{hook} buffer-local in the
-current buffer. When a hook variable is buffer-local, it can have
-buffer-local and global hook functions, and @code{run-hooks} runs all of
-them.
-
-This function works by adding @code{t} as an element of the buffer-local
-value. That serves as a flag to use the hook functions listed in the default
-value of the hook variable, as well as those listed in the buffer-local value.
-Since @code{run-hooks} understands this flag, @code{make-local-hook}
-works with all normal hooks. It works for only some non-normal
-hooks---those whose callers have been updated to understand this meaning
-of @code{t}.
-
-Do not use @code{make-local-variable} directly for hook variables; it is
-not sufficient.
@end defun
HCoop / bpt / emacs.git / blobdiff