@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011
@c Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
-@node Customization, Quitting, Amusements, Top
+@node Customization
@chapter Customization
@cindex customization
@end ifnottex
@menu
-* Minor Modes:: Each minor mode is a feature you can turn on
- independently of any others.
* Easy Customization:: Convenient way to browse and change settings.
* Variables:: Many Emacs commands examine Emacs variables
to decide what to do; by setting variables,
you can control their functioning.
* Key Bindings:: The keymaps say what command each key runs.
By changing them, you can "redefine keys".
-* Syntax:: The syntax table controls how words and
- expressions are parsed.
* Init File:: How to write common customizations in the
@file{.emacs} file.
@end menu
-@node Minor Modes
-@section Minor Modes
-@cindex minor modes
-@cindex mode, minor
-
- Minor modes are optional features which you can turn on or off. For
-example, Auto Fill mode is a minor mode in which @key{SPC} breaks
-lines between words as you type. Minor modes are independent of one
-another and of the selected major mode. Most minor modes say in the
-mode line when they are enabled; for example, @samp{Fill} in the mode
-line means that Auto Fill mode is enabled.
-
- Each minor mode is associated with a command, called the @dfn{mode
-command}, which turns it on or off. The name of this command consists
-of the name of the minor mode, followed by @samp{-mode}; for instance,
-the mode command for Auto Fill mode is @code{auto-fill-mode}. Calling
-the minor mode command with no prefix argument @dfn{toggles} the mode,
-turning it on if it was off, and off if it was on. A positive
-argument always turns the mode on, and a zero or negative argument
-always turns it off. Mode commands are usually invoked with
-@kbd{M-x}, but you can bind keys to them if you wish (@pxref{Key
-Bindings}).
-
- Most minor modes also have a @dfn{mode variable}, with the same name
-as the mode command. Its value is non-@code{nil} if the mode is
-enabled, and @code{nil} if it is disabled. In some minor modes---but
-not all---the value of the variable alone determines whether the mode
-is active: the mode command works simply by setting the variable, and
-changing the value of the variable has the same effect as calling the
-mode command. Because not all minor modes work this way, we recommend
-that you avoid changing the mode variables directly; use the mode
-commands instead.
-
- Some minor modes are @dfn{buffer-local}: they apply only to the
-current buffer, so you can enable the mode in certain buffers and not
-others. Other minor modes are @dfn{global}: while enabled, they
-affect everything you do in the Emacs session, in all buffers. Some
-global minor modes are enabled by default.
-
- The following is a list of some buffer-local minor modes:
-
-@itemize @bullet
-@item
-Abbrev mode automatically expands text based on pre-defined
-abbreviation definitions. @xref{Abbrevs}.
-
-@item
-Auto Fill mode inserts newlines as you type to prevent lines from
-becoming too long. @xref{Filling}.
-
-@item
-Auto Save mode saves the buffer contents periodically to reduce the
-amount of work you can lose in case of a crash. @xref{Auto Save}.
-
-@item
-Enriched mode enables editing and saving of formatted text.
-@xref{Formatted Text}.
-
-@item
-Flyspell mode automatically highlights misspelled words.
-@xref{Spelling}.
-
-@item
-Font-Lock mode automatically highlights certain textual units found in
-programs. It is enabled globally by default, but you can disable it
-in individual buffers. @xref{Faces}.
-
-@findex linum-mode
-@cindex Linum mode
-@item
-Linum mode displays each line's line number in the window's left
-margin. Its mode command is @code{linum-mode}.
-
-@item
-Outline minor mode provides similar facilities to the major mode
-called Outline mode. @xref{Outline Mode}.
-
-@cindex Overwrite mode
-@cindex mode, Overwrite
-@findex overwrite-mode
-@kindex INSERT
-@item
-Overwrite mode causes ordinary printing characters to replace existing
-text instead of shoving it to the right. For example, if point is in
-front of the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing
-a @kbd{G} changes it to @samp{FOOGAR}, instead of producing
-@samp{FOOGBAR} as usual. In Overwrite mode, the command @kbd{C-q}
-inserts the next character whatever it may be, even if it is a
-digit---this gives you a way to insert a character instead of
-replacing an existing character. The mode command,
-@code{overwrite-mode}, is bound to the @key{Insert} key.
-
-@findex binary-overwrite-mode
-@item
-Binary Overwrite mode is a variant of Overwrite mode for editing
-binary files; it treats newlines and tabs like other characters, so
-that they overwrite other characters and can be overwritten by them.
-In Binary Overwrite mode, digits after @kbd{C-q} specify an octal
-character code, as usual.
-
-@item
-Visual Line mode performs ``word wrapping'', causing long lines to be
-wrapped at word boundaries. @xref{Visual Line Mode}.
-@end itemize
-
- Here are some useful global minor modes. Since Line Number mode and
-Transient Mark mode can be enabled or disabled just by setting the
-value of the minor mode variable, you @emph{can} set them differently
-for particular buffers, by explicitly making the corresponding
-variable local in those buffers. @xref{Locals}.
-
-@itemize @bullet
-@item
-Column Number mode enables display of the current column number in the
-mode line. @xref{Mode Line}.
-
-@item
-Delete Selection mode causes text insertion to first delete the text
-in the region, if the region is active. @xref{Using Region}.
-
-@item
-Icomplete mode displays an indication of available completions when
-you are in the minibuffer and completion is active. @xref{Completion
-Options}.
-
-@item
-Line Number mode enables display of the current line number in the
-mode line. It is enabled by default. @xref{Mode Line}.
-
-@item
-Menu Bar mode gives each frame a menu bar. It is enabled by default.
-@xref{Menu Bars}.
-
-@item
-Scroll Bar mode gives each window a scroll bar. It is enabled by
-default, but the scroll bar is only displayed on graphical terminals.
-@xref{Scroll Bars}.
-
-@item
-Tool Bar mode gives each frame a tool bar. It is enabled by default,
-but the tool bar is only displayed on graphical terminals. @xref{Tool
-Bars}.
-
-@item
-Transient Mark mode highlights the region, and makes many Emacs
-commands operate on the region when the mark is active. It is enabled
-by default. @xref{Mark}.
-@end itemize
-
@node Easy Customization
@section Easy Customization Interface
(cond ((< emacs-major-version 22)
;; @r{Emacs 21 customization.}
(setq custom-file "~/.custom-21.el"))
- ((and (= emacs-major-version 22) (< emacs-minor-version 3))
+ ((and (= emacs-major-version 22)
+ (< emacs-minor-version 3))
;; @r{Emacs 22 customization, before version 22.3.}
(setq custom-file "~/.custom-22.el"))
(t
clicking that button. When the attribute is enabled, you can change
the attribute value in the usual ways.
- For the colors, you can specify a color name (use @kbd{M-x
-list-colors-display} for a list of them) or a hexadecimal color
-specification of the form @samp{#@var{rr}@var{gg}@var{bb}}.
-(@samp{#000000} is black, @samp{#ff0000} is red, @samp{#00ff00} is
-green, @samp{#0000ff} is blue, and @samp{#ffffff} is white.) On a
-black-and-white display, the colors you can use for the background are
-@samp{black}, @samp{white}, @samp{gray}, @samp{gray1}, and
-@samp{gray3}. Emacs supports these shades of gray by using background
-stipple patterns instead of a color.
+ You can specify a color name (use @kbd{M-x list-colors-display} for
+a list of them) or a hexadecimal color specification of the form
+@samp{#@var{rr}@var{gg}@var{bb}}. (@samp{#000000} is black,
+@samp{#ff0000} is red, @samp{#00ff00} is green, @samp{#0000ff} is
+blue, and @samp{#ffffff} is white.) On a black-and-white display, the
+colors you can use for the background are @samp{black}, @samp{white},
+@samp{gray}, @samp{gray1}, and @samp{gray3}. Emacs supports these
+shades of gray by using background stipple patterns instead of a
+color.
Setting, saving and resetting a face work like the same operations for
variables (@pxref{Changing a Variable}).
most interesting variables for a non-programmer user are those meant
for users to change---these are called @dfn{user options}. @xref{Easy
Customization}, for information about using the Customize facility to
-set user options. In the following sections, we describe will other
+set user options. In the following sections, we will describe other
aspects of Emacs variables, such as how to set them outside Customize.
Emacs Lisp allows any variable (with a few exceptions) to have any
hook is a Lisp variable which holds a list of functions, to be called
on some well-defined occasion. (This is called @dfn{running the
hook}.) The individual functions in the list are called the @dfn{hook
-functions} of the hook. With rare exceptions, hooks in Emacs are
-empty when Emacs starts up, so the only hook functions in any given
-hook are the ones you explicitly put there as customization.
-
- Most major modes run one or more @dfn{mode hooks} as the last step
-of initialization. This makes it easy for you to customize the
-behavior of the mode, by setting up a hook function to override the
-local variable assignments already made by the mode. But hooks are
-also used in other contexts. For example, the hook
-@code{kill-emacs-hook} runs just before quitting the Emacs job
-(@pxref{Exiting}).
+functions} of the hook. For example, the hook @code{kill-emacs-hook}
+runs just before exiting Emacs (@pxref{Exiting}).
@cindex normal hook
- Most Emacs hooks are @dfn{normal hooks}. This means that running the
-hook operates by calling all the hook functions, unconditionally, with
-no arguments. We have made an effort to keep most hooks normal so that
-you can use them in a uniform way. Every variable in Emacs whose name
-ends in @samp{-hook} is a normal hook.
+ Most hooks are @dfn{normal hooks}. This means that when Emacs runs
+the hook, it calls each hook function in turn, with no arguments. We
+have made an effort to keep most hooks normal, so that you can use
+them in a uniform way. Every variable whose name ends in @samp{-hook}
+is a normal hook.
@cindex abnormal hook
- There are also a few @dfn{abnormal hooks}. These variables' names end
-in @samp{-hooks} or @samp{-functions}, instead of @samp{-hook}. What
-makes these hooks abnormal is that there is something peculiar about the
-way its functions are called---perhaps they are given arguments, or
-perhaps the values they return are used in some way. For example,
-@code{find-file-not-found-functions} (@pxref{Visiting}) is abnormal because
-as soon as one hook function returns a non-@code{nil} value, the rest
-are not called at all. The documentation of each abnormal hook variable
-explains in detail what is peculiar about it.
+ A few hooks are @dfn{abnormal hooks}. Their names end in
+@samp{-hooks} or @samp{-functions}, instead of @samp{-hook}. What
+makes these hooks abnormal is the way its functions are
+called---perhaps they are given arguments, or perhaps the values they
+return are used in some way. For example,
+@code{find-file-not-found-functions} is abnormal because as soon as
+one hook function returns a non-@code{nil} value, the rest are not
+called at all (@pxref{Visiting}). The documentation of each abnormal
+hook variable explains how its functions are used.
@findex add-hook
You can set a hook variable with @code{setq} like any other Lisp
-variable, but the recommended way to add a hook function to a hook
-(either normal or abnormal) is by calling @code{add-hook}.
-@xref{Hooks,,, elisp, The Emacs Lisp Reference Manual}.
+variable, but the recommended way to add a function to a hook (either
+normal or abnormal) is to use @code{add-hook}, as shown by the
+following examples. @xref{Hooks,,, elisp, The Emacs Lisp Reference
+Manual}, for details.
- For example, here's how to set up a hook to turn on Auto Fill mode
-when entering Text mode and other modes based on Text mode:
+ Most major modes run one or more @dfn{mode hooks} as the last step
+of initialization. Mode hooks are a convenient way to customize the
+behavior of individual modes; they are always normal. For example,
+here's how to set up a hook to turn on Auto Fill mode when entering
+Text mode and other modes based on Text mode:
@example
-(add-hook 'text-mode-hook 'turn-on-auto-fill)
+(add-hook 'text-mode-hook 'auto-fill-mode)
@end example
- The next example shows how to use a hook to customize the indentation
-of C code. (People often have strong personal preferences for one
-format compared to another.) Here the hook function is an anonymous
-lambda expression.
+ Here is another example, showing how to use a hook to customize the
+indentation of C code. The hook function uses an anonymous lambda
+expression (@pxref{Lambda Expressions,,, elisp, The Emacs Lisp
+Reference Manual}).
@example
@group
@group
(c-cleanup-list . (scope-operator
empty-defun-braces
- defun-close-semi))
-@end group
-@group
- (c-offsets-alist . ((arglist-close . c-lineup-arglist)
- (substatement-open . 0)))))
+ defun-close-semi))))
@end group
@group
(add-hook 'c-mode-common-hook
- '(lambda ()
- (c-add-style "my-style" my-c-style t)))
+ (lambda () (c-add-style "my-style" my-c-style t)))
@end group
@end example
+@cindex Prog mode
+@cindex program editing
+ Major mode hooks also apply to other major modes @dfn{derived} from
+the original mode (@pxref{Derived Modes,,, elisp, The Emacs Lisp
+Reference Manual}). For instance, HTML mode (@pxref{HTML Mode})
+inherits from Text mode; when HTML mode is enabled, it runs
+@code{text-mode-hook} before running @code{html-mode-hook}. This
+provides a convenient way to use a single hook to affect several
+related modes. In particular, if you want to apply a hook function to
+any programming language mode, add it to @code{prog-mode-hook}; Prog
+mode is a major mode that does little else than to let other major
+modes inherit from it, exactly for this purpose.
+
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: the most
-recently added hook functions are executed first.
+asking for trouble. However, the order is predictable: the hook
+functions are executed in the order they appear in the hook.
@findex remove-hook
If you play with adding various different versions of a hook
can clear out individual functions by calling @code{remove-hook}, or
do @code{(setq @var{hook-variable} nil)} to remove everything.
+@cindex buffer-local hooks
+ If the hook variable is buffer-local, the buffer-local variable will
+be used instead of the global variable. However, if the buffer-local
+variable contains the element @code{t}, the global hook variable will
+be run as well.
+
@node Locals
@subsection Local Variables
You can specify any number of variable/value pairs in this way, each
pair with a colon and semicolon as shown above. The special
variable/value pair @code{mode: @var{modename};}, if present,
-specifies a major or minor mode; if you use this to specify a major
-mode, it should come first in the line. The @var{value}s are used
-literally, and not evaluated.
+specifies a major mode, and should come first in the line. The
+@var{value}s are used literally, and not evaluated.
@findex add-file-local-variable-prop-line
@findex delete-file-local-variable-prop-line
If a file has both a local variables list and a @samp{-*-} line,
Emacs processes @emph{everything} in the @samp{-*-} line first, and
-@emph{everything} in the local variables list afterward.
+@emph{everything} in the local variables list afterward. The exception
+to this is a major mode specification. Emacs applies this first,
+wherever it appears, since most major modes kill all local variables as
+part of their initialization.
A local variables list starts with a line containing the string
@samp{Local Variables:}, and ends with a line containing the string
@itemize
@item
-@code{mode} enables the specified major or minor mode.
+@code{mode} enables the specified major mode.
@item
@code{eval} evaluates the specified Lisp expression (the value
These four ``variables'' are not really variables; setting them in any
other context has no special meaning.
- @emph{If @code{mode} is used to set a major mode, it should be the
-first ``variable'' in the list.} Otherwise, the entries that precede
-it will usually have no effect, since most major modes kill all local
-variables as part of their initialization.
-
You can use the @code{mode} ``variable'' to enable minor modes as
well as the major modes; in fact, you can use it more than once, first
to set the major mode and then to enable minor modes which are
-specific to particular buffers.
+specific to particular buffers. Using @code{mode} for minor modes
+is deprecated, though---instead, use @code{eval: (minor-mode 1)}.
- Often, however, it is a mistake to enable minor modes this way.
-Most minor modes, like Auto Fill mode, represent individual user
+ Often, however, it is a mistake to enable minor modes in file local
+variables. Most minor modes, like Auto Fill mode, represent individual user
preferences. If you want to use a minor mode, it is better to set up
major mode hooks with your init file to turn that minor mode on for
yourself alone (@pxref{Init File}), instead of using a local variable
(tab-width . 4)
(fill-column . 80)))
(c-mode . ((c-file-style . "BSD")))
- (java-mode . ((c-file-style . "BSD")))
+ (java-mode . ((c-file-style . "BSD")
+ (subdirs . nil)))
("src/imported"
- . ((nil . ((change-log-default-name . "ChangeLog.local"))))))
+ . ((nil . ((change-log-default-name .
+ "ChangeLog.local"))))))
@end example
@noindent
This example shows some settings for a hypothetical project. It sets
@samp{indent-tabs-mode}, @code{tab-width}, and @code{fill-column} for
any file in the project's directory tree, and it sets the indentation
-style for any C or Java source file. Finally, it specifies a different
-@file{ChangeLog} file name for any file in the @file{src/imported}
+style for any C or Java source file. The special @code{subdirs} element
+indicates that the Java mode settings are only to be applied in the
+current directory, not in any subdirectories. Finally, it specifies a
+different @file{ChangeLog} file name for any file in the @file{src/imported}
subdirectory of the directory where you put the @file{.dir-locals.el}
file.
@code{minibuffer-local-must-match-map} is for strict completion and
for cautious completion.
@item
-Finally, @code{minibuffer-local-filename-completion-map} and
+@code{minibuffer-local-filename-completion-map} and
@code{minibuffer-local-must-match-filename-map} are like the two
previous ones, but they are specifically for file name completion.
They do not bind @key{SPC}.
(global-set-key (kbd "C-<f5>") 'linum-mode)
(global-set-key (kbd "C-<right>") 'forward-sentence)
(global-set-key (kbd "<mouse-2>") 'mouse-save-then-kill)
-(global-set-key (kbd "C-<down-mouse-3>") 'mouse-yank-at-click)
@end example
Instead of using the @code{kbd} macro, you can use a Lisp string or
@example
(add-hook 'texinfo-mode-hook
'(lambda ()
- (define-key texinfo-mode-map "\C-cp" 'backward-paragraph)
- (define-key texinfo-mode-map "\C-cn" 'forward-paragraph)))
+ (define-key texinfo-mode-map "\C-cp"
+ 'backward-paragraph)
+ (define-key texinfo-mode-map "\C-cn"
+ 'forward-paragraph)))
@end example
@node Modifier Keys
redefine the second mouse button to split the current window:
@example
-(global-set-key [mouse-2] 'split-window-vertically)
+(global-set-key [mouse-2] 'split-window-below)
@end example
The symbols for drag events are similar, but have the prefix
keys.'' For example, if you click the mouse in the mode line, you get
the prefix key @code{mode-line} before the ordinary mouse-button symbol.
Thus, here is how to define the command for clicking the first button in
-a mode line to run @code{scroll-up}:
+a mode line to run @code{scroll-up-command}:
@example
-(global-set-key [mode-line mouse-1] 'scroll-up)
+(global-set-key [mode-line mouse-1] 'scroll-up-command)
@end example
Here is the complete list of these dummy prefix keys and their
@kbd{M-x}. However, disabling a command has no effect on calling it
as a function from Lisp programs.
-@node Syntax
-@section The Syntax Table
-@cindex syntax table
-
- All the Emacs commands which parse words or balance parentheses are
-controlled by the @dfn{syntax table}. The syntax table says which
-characters are opening delimiters, which are parts of words, which are
-string quotes, and so on. It does this by assigning each character to
-one of fifteen-odd @dfn{syntax classes}. In some cases it specifies
-some additional information also.
-
- Each major mode has its own syntax table (though related major modes
-sometimes share one syntax table), which it installs in each buffer
-that uses the mode. The syntax table installed in the current buffer
-is the one that all commands use, so we call it ``the'' syntax table.
-
-@kindex C-h s
-@findex describe-syntax
- To display a description of the contents of the current syntax
-table, type @kbd{C-h s} (@code{describe-syntax}). The description of
-each character includes the string you would have to give to
-@code{modify-syntax-entry} to set up that character's current syntax,
-starting with the character which designates its syntax class, plus
-some English text to explain its meaning.
-
- A syntax table is actually a Lisp object, a char-table, whose
-elements are cons cells. For full information on the syntax table,
-see @ref{Syntax Tables,, Syntax Tables, elisp, The Emacs Lisp
-Reference Manual}.
-
@node Init File
@section The Init File, @file{~/.emacs}
@cindex init file
+@cindex .emacs file
+@cindex ~/.emacs file
@cindex Emacs initialization file
@cindex key rebinding, permanent
@cindex rebinding keys, permanently
Turn on Auto Fill mode automatically in Text mode and related modes.
@example
-(add-hook 'text-mode-hook
- '(lambda () (auto-fill-mode 1)))
+(add-hook 'text-mode-hook 'auto-fill-mode)
@end example
This shows how to add a hook function to a normal hook variable
@code{lambda}, with a single-quote in front of it to make it a list
constant rather than an expression.
-It's beyond the scope of this manual to explain Lisp functions, but for
-this example it is enough to know that the effect is to execute
-@code{(auto-fill-mode 1)} when Text mode is entered. You can replace
-that with any other expression that you like, or with several
-expressions in a row.
-
-Emacs comes with a function named @code{turn-on-auto-fill} whose
-definition is @code{(lambda () (auto-fill-mode 1))}. Thus, a simpler
-way to write the above example is as follows:
-
-@example
-(add-hook 'text-mode-hook 'turn-on-auto-fill)
-@end example
+It's beyond the scope of this manual to explain Lisp functions, but
+for this example it is enough to know that the effect is to execute
+the @code{auto-fill-mode} function when Text mode is entered.
@item
Load the installed Lisp library named @file{foo} (actually a file