@smallexample
@group
(make-local-variable 'paragraph-start)
+ ;; @r{Having @samp{^} is not clean, but @code{page-delimiter}}
+ ;; @r{has them too, and removing those is a pain.}
(setq paragraph-start (concat "^$\\|" page-delimiter))
@dots{}
@end group
@end deffn
@deffn Command normal-mode &optional find-file
- This function establishes the proper major mode and local variable
+This function establishes the proper major mode and local variable
bindings for the current buffer. First it calls @code{set-auto-mode},
then it runs @code{hack-local-variables} to parse, and bind or
evaluate as appropriate, any local variables.
- If the @var{find-file} argument to @code{normal-mode} is
+If the @var{find-file} argument to @code{normal-mode} is
non-@code{nil}, @code{normal-mode} assumes that the @code{find-file}
function is calling it. In this case, it may process a local variables
-list at the end of the file. The variable @code{enable-local-variables}
-controls whether to do so.
+list at the end of the file and in the @samp{-*-} line. The variable
+@code{enable-local-variables} controls whether to do so.
- If you run @code{normal-mode} interactively, the argument
+If you run @code{normal-mode} interactively, the argument
@var{find-file} is normally @code{nil}. In this case,
@code{normal-mode} unconditionally processes any local variables list.
@xref{File variables, , Local Variables in Files, emacs, The GNU Emacs
Manual}, for the syntax of the local variables section of a file.
@cindex file mode specification error
- @code{normal-mode} uses @code{condition-case} around the call to the
+@code{normal-mode} uses @code{condition-case} around the call to the
major mode function, so errors are caught and reported as a @samp{File
mode specification error}, followed by the original error message.
@end deffn
ask the user what to do for each file. The default value is @code{t}.
@end defopt
+@defvar ignored-local-variables
+This variable holds a list of variables that should not be
+set by a local variables list. Any value specified
+for one of these variables is ignored.
+@end defvar
+
+In addition to this list, any variable whose name has a non-@code{nil}
+@code{risky-local-variable} property is also ignored.
+
@defopt enable-local-eval
This variable controls processing of @samp{Eval:} in local variables
lists in files being visited. A value of @code{t} means process them
been specially prepared.
@end defopt
+@defun set-buffer-major-mode buffer
+This function sets the major mode of @var{buffer} to the value of
+@code{default-major-mode}. If that variable is @code{nil}, it uses
+the current buffer's major mode (if that is suitable).
+
+The low-level primitives for creating buffers do not use this function,
+but medium-level commands such as @code{switch-to-buffer} and
+@code{find-file-noselect} use it whenever they create buffers.
+@end defun
+
@defvar initial-major-mode
@cindex @samp{*scratch*}
The value of this variable determines the major mode of the initial
@smallexample
@group
(("^/tmp/fol/" . text-mode)
- ("\\.texinfo$" . texinfo-mode)
- ("\\.texi$" . texinfo-mode)
+ ("\\.texinfo\\'" . texinfo-mode)
+ ("\\.texi\\'" . texinfo-mode)
@end group
@group
- ("\\.el$" . emacs-lisp-mode)
- ("\\.c$" . c-mode)
- ("\\.h$" . c-mode)
+ ("\\.el\\'" . emacs-lisp-mode)
+ ("\\.c\\'" . c-mode)
+ ("\\.h\\'" . c-mode)
@dots{})
@end group
@end smallexample
(setq auto-mode-alist
(append
;; @r{File name 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))
+ ("\\.C\\'" . c++-mode))
auto-mode-alist))
@end group
@end smallexample
Often the biggest problem in implementing a minor mode is finding a
way to insert the necessary hook into the rest of Emacs. Minor mode
-keymaps make this easier in Emacs 19 than it used to be.
+keymaps make this easier than it used to be.
@menu
* Minor Mode Conventions:: Tips for writing a minor mode.
list whose @sc{car} is such an integer or symbol; it should turn the
mode off otherwise.
-Here is an example taken from the definition of @code{overwrite-mode}.
-It shows the use of @code{overwrite-mode} as a variable that enables or
+Here is an example taken from the definition of @code{transient-mark-mode}.
+It shows the use of @code{transient-mark-mode} as a variable that enables or
disables the mode's behavior, and also shows the proper way to toggle,
enable or disable the minor mode based on the raw prefix argument value.
@smallexample
@group
-(setq overwrite-mode
- (if (null arg) (not overwrite-mode)
+(setq transient-mark-mode
+ (if (null arg) (not transient-mark-mode)
(> (prefix-numeric-value arg) 0)))
@end group
@end smallexample
@node Keymaps and Minor Modes
@subsection Keymaps and Minor Modes
-As of Emacs version 19, each minor mode can have its own keymap, which is
-active when the mode is enabled. @xref{Active Keymaps}. To set up a
-keymap for a minor mode, add an element to the alist
-@code{minor-mode-map-alist}.
+ Each minor mode can have its own keymap, which is active when the mode
+is enabled. To set up a keymap for a minor mode, add an element to the
+alist @code{minor-mode-map-alist}. @xref{Active Keymaps}.
@cindex @code{self-insert-command}, minor modes
One use of minor mode keymaps is to modify the behavior of certain
substituting your own definition of @code{self-insert-command} for the
standard one. The editor command loop handles this function specially.)
-@defvar minor-mode-map-alist
-This variable is an alist of elements that look like this:
-
-@example
-(@var{variable} . @var{keymap})
-@end example
-
-@noindent
-where @var{variable} is the variable that indicates whether the minor
-mode is enabled, and @var{keymap} is the keymap. The keymap
-@var{keymap} is active whenever @var{variable} has a non-@code{nil}
-value.
-
-Note that elements of @code{minor-mode-map-alist} do not have the same
-structure as elements of @code{minor-mode-alist}. The map must be the
-@sc{cdr} of the element; a list with the map as the second element will
-not do.
-
-What's more, the keymap itself must appear in the @sc{cdr}. It does not
-work to store a variable in the @sc{cdr} and make the map the value of
-that variable.
-
-When more than one minor mode keymap is active, their order of priority
-is the order of @code{minor-mode-map-alist}. But you should design
-minor modes so that they don't interfere with each other. If you do
-this properly, the order will not matter.
-@end defvar
-
@node Mode Line Format
@section Mode Line Format
@cindex mode line
@code{mode-line-format} is a buffer-local variable that holds a
template used to display the mode line of the current buffer. All
-windows for the same buffer use the same @code{mode-line-format} and the
-mode lines will appear the same (except for scrolling percentages and
+windows for the same buffer use the same @code{mode-line-format} and
+their mode lines appear the same (except for scrolling percentages and
line numbers).
The mode line of a window is normally updated whenever a different
strings, symbols, and numbers kept in the buffer-local variable
@code{mode-line-format}. The data structure is called a @dfn{mode line
construct}, and it is built in recursive fashion out of simpler mode line
-constructs.
+constructs. The same data structure is used for constructing
+frame titles (@pxref{Frame Titles}).
@defvar mode-line-format
The value of this variable is a mode line construct with overall
@cindex percent symbol in mode line
@item @var{string}
A string as a mode line construct is displayed verbatim in the mode line
-except for @dfn{@code{%}-constructs}. Decimal digits after the @code{%}
+except for @dfn{@code{%}-constructs}. Decimal digits after the @samp{%}
specify the field width for space filling on the right (i.e., the data
is left justified). @xref{%-Constructs}.
use the same variables that appear in the default value (@pxref{Mode
Line Variables}), rather than duplicating their contents or displaying
the information in another fashion. This way, customizations made by
-the user, by libraries (such as @code{display-time}) and by major modes
-via changes to those variables remain effective.
+the user or by Lisp programs (such as @code{display-time} and major
+modes) via changes to those variables remain effective.
@cindex Shell mode @code{mode-line-format}
Here is an example of a @code{mode-line-format} that might be
"%n"
")%]----"
@group
- (line-number-mode "L%l--")
+ '(line-number-mode "L%l--")
'(-3 . "%p")
"-%-"))
@end group
This variable holds the value of the mode-line construct that displays
whether the current buffer is modified.
-The default value of @code{mode-line-modified} is
-@code{("--%1*%1*-")}. This means that the mode line displays
-@samp{--**-} if the buffer is modified, @samp{-----} if the buffer is
-not modified, and @samp{--%%-} if the buffer is read only.
+The default value of @code{mode-line-modified} is @code{("--%1*%1+-")}.
+This means that the mode line displays @samp{--**-} if the buffer is
+modified, @samp{-----} if the buffer is not modified, @samp{--%%-} if
+the buffer is read only, and @samp{--%*--} if the buffer is read only
+and modified.
Changing this variable does not force an update of the mode line.
@end defvar
@defvar mode-line-buffer-identification
This variable identifies the buffer being displayed in the window. Its
-default value is @samp{Emacs: %17b}, which means that it displays
-@samp{Emacs:} followed by seventeen characters of the buffer name. You
-may want to change this in modes such as Rmail that do not behave like a
+default value is @code{("%F: %17b")}, which means that it usually
+displays @samp{Emacs:} followed by seventeen characters of the buffer
+name. (In a terminal frame, it displays the frame name instead of
+@samp{Emacs}; this has the effect of showing the frame number.) You may
+want to change this in modes such as Rmail that do not behave like a
``normal'' Emacs.
@end defvar
@example
@group
minor-mode-alist
-@result{} ((abbrev-mode " Abbrev")
- (overwrite-mode " Ovwrt")
+@result{} ((vc-mode vc-mode)
+ (abbrev-mode " Abbrev")
+ (overwrite-mode overwrite-mode)
(auto-fill-function " Fill")
- (defining-kbd-macro " Def"))
+ (defining-kbd-macro " Def")
+ (isearch-mode isearch-mode))
@end group
@end example
-@noindent
-(In earlier Emacs versions, @code{auto-fill-function} was called
-@code{auto-fill-hook}.)
-
- @code{minor-mode-alist} is not buffer-local. The variables mentioned
+@code{minor-mode-alist} is not buffer-local. The variables mentioned
in the alist should be buffer-local if the minor mode can be enabled
separately in each buffer.
@end defvar
mode-name
@end group
@group
+ mode-line-process
minor-mode-alist
"%n"
- mode-line-process
")%]----"
+ (line-number-mode "L%l--")
(-3 . "%p")
"-%-")
@end group
The visited file name, obtained with the @code{buffer-file-name}
function. @xref{Buffer File Name}.
+@item %F
+The name of the selected frame.
+
+@item %c
+The current column number of point.
+
+@item %l
+The current line number of point.
+
@item %*
@samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
@samp{-} otherwise. @xref{Buffer Modification}.
@item %+
+@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
+@samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
+@samp{-} otherwise. This differs from @samp{%*} only for a modified
+read-only buffer. @xref{Buffer Modification}.
+
+@item %&
@samp{*} if the buffer is modified, and @samp{-} otherwise.
@item %s
The status of the subprocess belonging to the current buffer, obtained with
@code{process-status}. @xref{Process Information}.
+@item %t
+Whether the visited file is a text file or a binary file. (This is a
+meaningful distinction only on certain operating systems.)
+
@item %p
-The percent of the buffer above the @strong{top} of window, or
+The percentage of the buffer text above the @strong{top} of window, or
@samp{Top}, @samp{Bottom} or @samp{All}.
@item %P
The name shows you that the hook is abnormal and that you should look at
its documentation string to see how to use it properly.
- Most major modes run hooks as the last step of initialization. This
-makes it easy for a user to customize the behavior of the mode, by
-overriding the local variable assignments already made by the mode. But
-hooks are used in other contexts too. For example, the hook
-@code{suspend-hook} runs just before Emacs suspends itself
-(@pxref{Suspending Emacs}).
+ Major mode functions are supposed to run a hook called the @dfn{mode
+hook} as the last step of initialization. This makes it easy for a user
+to customize the behavior of the mode, by overriding the local variable
+assignments already made by the mode. But hooks are used in other
+contexts too. For example, the hook @code{suspend-hook} runs just
+before Emacs suspends itself (@pxref{Suspending Emacs}).
- Here's an expression you can put in your @file{.emacs} file to turn on
-Auto Fill mode when in Lisp Interaction mode:
+ Here's an expression that uses a mode hook to turn on Auto Fill mode
+when in Lisp Interaction mode:
@example
(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
(setq c++-mode-hook c-mode-hook)
@end group
-@end example
-
- Finally, here is an example of how to use the Text mode hook to
-provide a customized mode line for buffers in Text mode, displaying the
-default directory in addition to the standard components of the
-mode line. (This may cause the mode line to run out of space if you
-have very long file names or display the time and load.)
-
-@example
-@group
-(add-hook 'text-mode-hook
- (function (lambda ()
- (setq mode-line-format
- '(mode-line-modified
- "Emacs: %14b"
- " "
-@end group
- default-directory
- " "
- global-mode-string
- "%[("
- mode-name
- minor-mode-alist
-@group
- "%n"
- mode-line-process
- ") %]---"
- (-3 . "%p")
- "-%-")))))
-@end group
@end example
At the appropriate time, Emacs uses the @code{run-hooks} function to
-run particular hooks. This function calls the hook functions you have
-added with @code{add-hooks}.
+run particular hooks. This function calls the hook functions that have
+been added with @code{add-hook}.
@defun run-hooks &rest hookvar
This function takes one or more hook variable names as arguments, and
called. If it is a list, the elements are called, in order.
The hook functions are called with no arguments.
-For example, here's how @code{emacs-lisp-hooks} runs its mode hook:
+For example, here's how @code{emacs-lisp-mode} runs its mode hook:
@example
(run-hooks 'emacs-lisp-mode-hook)
@end example
@end defun
-@defun add-hook hook function &optional append
+@defun 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,
If the optional argument @var{append} is non-@code{nil}, the new hook
function goes at the end of the hook list and will be executed last.
+
+If @var{local} is non-@code{nil}, that says to make the new hook
+function local to 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.
@end defun
-@defun remove-hook hook function
+@defun remove-hook hook function &optional local
This function removes @var{function} from the hook variable @var{hook}.
+
+If @var{local} is non-@code{nil}, that says to remove @var{function}
+from the local hook list instead of from the global hook list. If the
+hook 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} local to the current
+buffer. When a hook variable is local, it can have local and global
+hook functions, and @code{run-hooks} runs all of them.
+
+Do not use @code{make-local-variable} directly for hook variables; it is
+not sufficient.
@end defun