annotate man/custom.texi @ 63576:7c3d537469b0

(grep-regexp-alist): Use backreference at the end of first regexp to limit the match to the position between line number and source line with same separator character as used between file name and line number. In the second regexp limit mouse-face area to file name and line number by adding new group for them and referring it in HYPERLINK arg. (grep-regexp-alist, grep-mode-font-lock-keywords): Use shy group. (grep-mode): Set font-lock-lines-before to 0 to not refontify the previous line where grep markers may be already removed.
author Juri Linkov <juri@jurta.org>
date Sat, 18 Jun 2005 12:56:14 +0000
parents 463dbe69de36
children c8d5956c919b f042e7c0fe20
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1 @c This is part of the Emacs manual.
61606
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2 @c Copyright (C) 1985,86,87,93,94,95,97,2000,2001,2002,2004,2005
28126
e7cf77f27506 Fix copyright line.
Dave Love <fx@gnu.org>
parents: 27218
diff changeset
3 @c Free Software Foundation, Inc.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
4 @c See file emacs.texi for copying conditions.
Dave Love <fx@gnu.org>
parents:
diff changeset
5 @node Customization, Quitting, Amusements, Top
Dave Love <fx@gnu.org>
parents:
diff changeset
6 @chapter Customization
Dave Love <fx@gnu.org>
parents:
diff changeset
7 @cindex customization
Dave Love <fx@gnu.org>
parents:
diff changeset
8
Dave Love <fx@gnu.org>
parents:
diff changeset
9 This chapter talks about various topics relevant to adapting the
Dave Love <fx@gnu.org>
parents:
diff changeset
10 behavior of Emacs in minor ways. See @cite{The Emacs Lisp Reference
40519
9b9cd5d7c886 Add xref to X Resources.
Richard M. Stallman <rms@gnu.org>
parents: 39544
diff changeset
11 Manual} for how to make more far-reaching changes. @xref{X Resources},
9b9cd5d7c886 Add xref to X Resources.
Richard M. Stallman <rms@gnu.org>
parents: 39544
diff changeset
12 for information on using X resources to customize Emacs.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
13
38322
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
14 Customization that you do within Emacs normally affects only the
56165
920d5b4fe0a2 * msdog.texi (Text and Binary, MS-DOS Printing): Use m-dash.
Jesper Harder <harder@ifa.au.dk>
parents: 56085
diff changeset
15 particular Emacs session that you do it in---it does not persist
38322
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
16 between sessions unless you save the customization in a file such as
38744
d7121931b3ba Show example of specifying C-M-= in Lisp.
Richard M. Stallman <rms@gnu.org>
parents: 38605
diff changeset
17 @file{.emacs} or @file{.Xdefaults} that will affect future sessions.
d7121931b3ba Show example of specifying C-M-= in Lisp.
Richard M. Stallman <rms@gnu.org>
parents: 38605
diff changeset
18 @xref{Init File}. In the customization buffer, when you save
d7121931b3ba Show example of specifying C-M-= in Lisp.
Richard M. Stallman <rms@gnu.org>
parents: 38605
diff changeset
19 customizations for future sessions, this actually works by editing
d7121931b3ba Show example of specifying C-M-= in Lisp.
Richard M. Stallman <rms@gnu.org>
parents: 38605
diff changeset
20 @file{.emacs} for you.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
21
52227
fd6d7ba60ecf (Customization): Add xref to Keyboard Macros chapter.
Kim F. Storm <storm@cua.dk>
parents: 51448
diff changeset
22 Another means of customization is the keyboard macro, which is a
fd6d7ba60ecf (Customization): Add xref to Keyboard Macros chapter.
Kim F. Storm <storm@cua.dk>
parents: 51448
diff changeset
23 sequence of keystrokes to be replayed with a single command.
fd6d7ba60ecf (Customization): Add xref to Keyboard Macros chapter.
Kim F. Storm <storm@cua.dk>
parents: 51448
diff changeset
24 @xref{Keyboard Macros}, for full instruction how to record, manage, and
fd6d7ba60ecf (Customization): Add xref to Keyboard Macros chapter.
Kim F. Storm <storm@cua.dk>
parents: 51448
diff changeset
25 replay sequences of keys.
fd6d7ba60ecf (Customization): Add xref to Keyboard Macros chapter.
Kim F. Storm <storm@cua.dk>
parents: 51448
diff changeset
26
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
27 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
28 * Minor Modes:: Each minor mode is one feature you can turn on
Dave Love <fx@gnu.org>
parents:
diff changeset
29 independently of any others.
62475
463dbe69de36 (Customization): Fix menu.
Lute Kamstra <lute@gnu.org>
parents: 61606
diff changeset
30 * Easy Customization:: Convenient way to browse and change user options.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
31 * Variables:: Many Emacs commands examine Emacs variables
Dave Love <fx@gnu.org>
parents:
diff changeset
32 to decide what to do; by setting variables,
Dave Love <fx@gnu.org>
parents:
diff changeset
33 you can control their functioning.
Dave Love <fx@gnu.org>
parents:
diff changeset
34 * Key Bindings:: The keymaps say what command each key runs.
Dave Love <fx@gnu.org>
parents:
diff changeset
35 By changing them, you can "redefine keys".
62475
463dbe69de36 (Customization): Fix menu.
Lute Kamstra <lute@gnu.org>
parents: 61606
diff changeset
36 * Keyboard Translations:: If your keyboard passes an undesired code
463dbe69de36 (Customization): Fix menu.
Lute Kamstra <lute@gnu.org>
parents: 61606
diff changeset
37 for a key, you can tell Emacs to
463dbe69de36 (Customization): Fix menu.
Lute Kamstra <lute@gnu.org>
parents: 61606
diff changeset
38 substitute another code.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
39 * Syntax:: The syntax table controls how words and
62475
463dbe69de36 (Customization): Fix menu.
Lute Kamstra <lute@gnu.org>
parents: 61606
diff changeset
40 expressions are parsed.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
41 * Init File:: How to write common customizations in the
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47535
diff changeset
42 @file{.emacs} file.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
43 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
44
Dave Love <fx@gnu.org>
parents:
diff changeset
45 @node Minor Modes
Dave Love <fx@gnu.org>
parents:
diff changeset
46 @section Minor Modes
Dave Love <fx@gnu.org>
parents:
diff changeset
47 @cindex minor modes
Dave Love <fx@gnu.org>
parents:
diff changeset
48 @cindex mode, minor
Dave Love <fx@gnu.org>
parents:
diff changeset
49
Dave Love <fx@gnu.org>
parents:
diff changeset
50 Minor modes are optional features which you can turn on or off. For
Dave Love <fx@gnu.org>
parents:
diff changeset
51 example, Auto Fill mode is a minor mode in which @key{SPC} breaks lines
Dave Love <fx@gnu.org>
parents:
diff changeset
52 between words as you type. All the minor modes are independent of each
Dave Love <fx@gnu.org>
parents:
diff changeset
53 other and of the selected major mode. Most minor modes say in the mode
Dave Love <fx@gnu.org>
parents:
diff changeset
54 line when they are on; for example, @samp{Fill} in the mode line means
Dave Love <fx@gnu.org>
parents:
diff changeset
55 that Auto Fill mode is on.
Dave Love <fx@gnu.org>
parents:
diff changeset
56
Dave Love <fx@gnu.org>
parents:
diff changeset
57 Append @code{-mode} to the name of a minor mode to get the name of a
Dave Love <fx@gnu.org>
parents:
diff changeset
58 command function that turns the mode on or off. Thus, the command to
Dave Love <fx@gnu.org>
parents:
diff changeset
59 enable or disable Auto Fill mode is called @kbd{M-x auto-fill-mode}. These
Dave Love <fx@gnu.org>
parents:
diff changeset
60 commands are usually invoked with @kbd{M-x}, but you can bind keys to them
Dave Love <fx@gnu.org>
parents:
diff changeset
61 if you wish. With no argument, the function turns the mode on if it was
Dave Love <fx@gnu.org>
parents:
diff changeset
62 off and off if it was on. This is known as @dfn{toggling}. A positive
Dave Love <fx@gnu.org>
parents:
diff changeset
63 argument always turns the mode on, and an explicit zero argument or a
Dave Love <fx@gnu.org>
parents:
diff changeset
64 negative argument always turns it off.
Dave Love <fx@gnu.org>
parents:
diff changeset
65
38322
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
66 Some minor modes are global: while enabled, they affect everything
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
67 you do in the Emacs session, in all buffers. Other minor modes are
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
68 buffer-local; they apply only to the current buffer, so you can enable
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
69 the mode in certain buffers and not others.
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
70
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
71 For most minor modes, the command name is also the name of a
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
72 variable which directly controls the mode. The mode is enabled
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
73 whenever this variable's value is non-@code{nil}, and the minor-mode
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
74 command works by setting the variable. For example, the command
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
75 @code{outline-minor-mode} works by setting the value of
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
76 @code{outline-minor-mode} as a variable; it is this variable that
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
77 directly turns Outline minor mode on and off. To check whether a
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
78 given minor mode works this way, use @kbd{C-h v} to ask for
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
79 documentation on the variable name.
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
80
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
81 These minor-mode variables provide a good way for Lisp programs to turn
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
82 minor modes on and off; they are also useful in a file's local variables
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
83 list. But please think twice before setting minor modes with a local
59949
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
84 variables list, because most minor modes are a matter of user
38322
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
85 preference---other users editing the same file might not want the same
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
86 minor modes you prefer.
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
87
245114062ee0 Explain more clearly what it takes to make a customization permanent.
Richard M. Stallman <rms@gnu.org>
parents: 38114
diff changeset
88 The buffer-local minor modes include Abbrev mode, Auto Fill mode,
38870
d44abb4e68b2 Don't use "print" for displaying a message.
Richard M. Stallman <rms@gnu.org>
parents: 38791
diff changeset
89 Auto Save mode, Font-Lock mode, Glasses mode, ISO Accents mode,
d44abb4e68b2 Don't use "print" for displaying a message.
Richard M. Stallman <rms@gnu.org>
parents: 38791
diff changeset
90 Outline minor mode, Overwrite mode, and Binary Overwrite mode.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
91
Dave Love <fx@gnu.org>
parents:
diff changeset
92 Abbrev mode allows you to define abbreviations that automatically expand
Dave Love <fx@gnu.org>
parents:
diff changeset
93 as you type them. For example, @samp{amd} might expand to @samp{abbrev
Dave Love <fx@gnu.org>
parents:
diff changeset
94 mode}. @xref{Abbrevs}, for full information.
Dave Love <fx@gnu.org>
parents:
diff changeset
95
Dave Love <fx@gnu.org>
parents:
diff changeset
96 Auto Fill mode allows you to enter filled text without breaking lines
Dave Love <fx@gnu.org>
parents:
diff changeset
97 explicitly. Emacs inserts newlines as necessary to prevent lines from
Dave Love <fx@gnu.org>
parents:
diff changeset
98 becoming too long. @xref{Filling}.
Dave Love <fx@gnu.org>
parents:
diff changeset
99
Dave Love <fx@gnu.org>
parents:
diff changeset
100 Auto Save mode causes the contents of a buffer to be saved
Dave Love <fx@gnu.org>
parents:
diff changeset
101 periodically to reduce the amount of work you can lose in case of a
Dave Love <fx@gnu.org>
parents:
diff changeset
102 system crash. @xref{Auto Save}.
Dave Love <fx@gnu.org>
parents:
diff changeset
103
Dave Love <fx@gnu.org>
parents:
diff changeset
104 Enriched mode enables editing and saving of formatted text.
Dave Love <fx@gnu.org>
parents:
diff changeset
105 @xref{Formatted Text}.
Dave Love <fx@gnu.org>
parents:
diff changeset
106
Dave Love <fx@gnu.org>
parents:
diff changeset
107 Flyspell mode automatically highlights misspelled words.
Dave Love <fx@gnu.org>
parents:
diff changeset
108 @xref{Spelling}.
Dave Love <fx@gnu.org>
parents:
diff changeset
109
Dave Love <fx@gnu.org>
parents:
diff changeset
110 Font-Lock mode automatically highlights certain textual units found in
Dave Love <fx@gnu.org>
parents:
diff changeset
111 programs, such as comments, strings, and function names being defined.
Dave Love <fx@gnu.org>
parents:
diff changeset
112 This requires a window system that can display multiple fonts.
Dave Love <fx@gnu.org>
parents:
diff changeset
113 @xref{Faces}.
Dave Love <fx@gnu.org>
parents:
diff changeset
114
Dave Love <fx@gnu.org>
parents:
diff changeset
115 ISO Accents mode makes the characters @samp{`}, @samp{'}, @samp{"},
Dave Love <fx@gnu.org>
parents:
diff changeset
116 @samp{^}, @samp{/} and @samp{~} combine with the following letter, to
38744
d7121931b3ba Show example of specifying C-M-= in Lisp.
Richard M. Stallman <rms@gnu.org>
parents: 38605
diff changeset
117 produce an accented letter in the ISO Latin-1 character set. The
d7121931b3ba Show example of specifying C-M-= in Lisp.
Richard M. Stallman <rms@gnu.org>
parents: 38605
diff changeset
118 newer and more general feature of input methods more or less
d7121931b3ba Show example of specifying C-M-= in Lisp.
Richard M. Stallman <rms@gnu.org>
parents: 38605
diff changeset
119 supersedes ISO Accents mode. @xref{Single-Byte Character Support}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
120
Dave Love <fx@gnu.org>
parents:
diff changeset
121 Outline minor mode provides the same facilities as the major mode
Dave Love <fx@gnu.org>
parents:
diff changeset
122 called Outline mode; but since it is a minor mode instead, you can
Dave Love <fx@gnu.org>
parents:
diff changeset
123 combine it with any major mode. @xref{Outline Mode}.
Dave Love <fx@gnu.org>
parents:
diff changeset
124
Dave Love <fx@gnu.org>
parents:
diff changeset
125 @cindex Overwrite mode
Dave Love <fx@gnu.org>
parents:
diff changeset
126 @cindex mode, Overwrite
Dave Love <fx@gnu.org>
parents:
diff changeset
127 Overwrite mode causes ordinary printing characters to replace existing
Dave Love <fx@gnu.org>
parents:
diff changeset
128 text instead of shoving it to the right. For example, if point is in
Dave Love <fx@gnu.org>
parents:
diff changeset
129 front of the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing a
Dave Love <fx@gnu.org>
parents:
diff changeset
130 @kbd{G} changes it to @samp{FOOGAR}, instead of producing @samp{FOOGBAR}
Dave Love <fx@gnu.org>
parents:
diff changeset
131 as usual. In Overwrite mode, the command @kbd{C-q} inserts the next
Dave Love <fx@gnu.org>
parents:
diff changeset
132 character whatever it may be, even if it is a digit---this gives you a
Dave Love <fx@gnu.org>
parents:
diff changeset
133 way to insert a character instead of replacing an existing character.
Dave Love <fx@gnu.org>
parents:
diff changeset
134
37571
9628e53b601d Document that overwrite-mode is bound to INSERT and add @kindex for INSERT.
Eli Zaretskii <eliz@gnu.org>
parents: 37419
diff changeset
135 @findex overwrite-mode
9628e53b601d Document that overwrite-mode is bound to INSERT and add @kindex for INSERT.
Eli Zaretskii <eliz@gnu.org>
parents: 37419
diff changeset
136 @kindex INSERT
9628e53b601d Document that overwrite-mode is bound to INSERT and add @kindex for INSERT.
Eli Zaretskii <eliz@gnu.org>
parents: 37419
diff changeset
137 The command @code{overwrite-mode} is an exception to the rule that
9628e53b601d Document that overwrite-mode is bound to INSERT and add @kindex for INSERT.
Eli Zaretskii <eliz@gnu.org>
parents: 37419
diff changeset
138 commands which toggle minor modes are normally not bound to keys: it is
9628e53b601d Document that overwrite-mode is bound to INSERT and add @kindex for INSERT.
Eli Zaretskii <eliz@gnu.org>
parents: 37419
diff changeset
139 bound to the @key{INSERT} function key. This is because many other
9628e53b601d Document that overwrite-mode is bound to INSERT and add @kindex for INSERT.
Eli Zaretskii <eliz@gnu.org>
parents: 37419
diff changeset
140 programs bind @key{INSERT} to similar functions.
9628e53b601d Document that overwrite-mode is bound to INSERT and add @kindex for INSERT.
Eli Zaretskii <eliz@gnu.org>
parents: 37419
diff changeset
141
9628e53b601d Document that overwrite-mode is bound to INSERT and add @kindex for INSERT.
Eli Zaretskii <eliz@gnu.org>
parents: 37419
diff changeset
142 @findex binary-overwrite-mode
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
143 Binary Overwrite mode is a variant of Overwrite mode for editing
Dave Love <fx@gnu.org>
parents:
diff changeset
144 binary files; it treats newlines and tabs like other characters, so that
Dave Love <fx@gnu.org>
parents:
diff changeset
145 they overwrite other characters and can be overwritten by them.
37843
e8365cfcb741 Explain how Binary Overwrite mode affects C-q.
Richard M. Stallman <rms@gnu.org>
parents: 37618
diff changeset
146 In Binary Overwrite mode, digits after @kbd{C-q} specify an
e8365cfcb741 Explain how Binary Overwrite mode affects C-q.
Richard M. Stallman <rms@gnu.org>
parents: 37618
diff changeset
147 octal character code, as usual.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
148
Dave Love <fx@gnu.org>
parents:
diff changeset
149 The following minor modes normally apply to all buffers at once.
Dave Love <fx@gnu.org>
parents:
diff changeset
150 Since each is enabled or disabled by the value of a variable, you
Dave Love <fx@gnu.org>
parents:
diff changeset
151 @emph{can} set them differently for particular buffers, by explicitly
Dave Love <fx@gnu.org>
parents:
diff changeset
152 making the corresponding variables local in those buffers.
Dave Love <fx@gnu.org>
parents:
diff changeset
153 @xref{Locals}.
Dave Love <fx@gnu.org>
parents:
diff changeset
154
Dave Love <fx@gnu.org>
parents:
diff changeset
155 Icomplete mode displays an indication of available completions when
Dave Love <fx@gnu.org>
parents:
diff changeset
156 you are in the minibuffer and completion is active. @xref{Completion
Dave Love <fx@gnu.org>
parents:
diff changeset
157 Options}.
Dave Love <fx@gnu.org>
parents:
diff changeset
158
Dave Love <fx@gnu.org>
parents:
diff changeset
159 Line Number mode enables continuous display in the mode line of the
36148
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
160 line number of point, and Column Number mode enables display of the
28126
e7cf77f27506 Fix copyright line.
Dave Love <fx@gnu.org>
parents: 27218
diff changeset
161 column number. @xref{Mode Line}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
162
Dave Love <fx@gnu.org>
parents:
diff changeset
163 Scroll Bar mode gives each window a scroll bar (@pxref{Scroll Bars}).
Dave Love <fx@gnu.org>
parents:
diff changeset
164 Menu Bar mode gives each frame a menu bar (@pxref{Menu Bars}). Both of
Dave Love <fx@gnu.org>
parents:
diff changeset
165 these modes are enabled by default when you use the X Window System.
Dave Love <fx@gnu.org>
parents:
diff changeset
166
Dave Love <fx@gnu.org>
parents:
diff changeset
167 In Transient Mark mode, every change in the buffer contents
Dave Love <fx@gnu.org>
parents:
diff changeset
168 ``deactivates'' the mark, so that commands that operate on the region
Dave Love <fx@gnu.org>
parents:
diff changeset
169 will get an error. This means you must either set the mark, or
Dave Love <fx@gnu.org>
parents:
diff changeset
170 explicitly ``reactivate'' it, before each command that uses the region.
Dave Love <fx@gnu.org>
parents:
diff changeset
171 The advantage of Transient Mark mode is that Emacs can display the
28126
e7cf77f27506 Fix copyright line.
Dave Love <fx@gnu.org>
parents: 27218
diff changeset
172 region highlighted (currently only when using X). @xref{Mark}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
173
58763
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
174 @node Easy Customization
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
175 @section Easy Customization Interface
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
176
58763
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
177 @cindex user option
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
178 Emacs has many @dfn{user options} which have values that you can set
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
179 in order to customize various commands. Many user options are
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
180 documented in this manual. Most user options are actually Lisp
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
181 variables (@pxref{Variables}), so their names appear in the Variable
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
182 Index (@pxref{Variable Index}). The rest are faces and their
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
183 attributes (@pxref{Faces}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
184
Dave Love <fx@gnu.org>
parents:
diff changeset
185 @findex customize
Dave Love <fx@gnu.org>
parents:
diff changeset
186 @cindex customization buffer
58763
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
187 You can browse interactively through the the user options and change
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
188 some of them using @kbd{M-x customize}. This command creates a
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
189 @dfn{customization buffer}, which offers commands to navigate through
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
190 a logically organized structure of the Emacs user options; you can
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
191 also use it to edit and set their values, and to save settings
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
192 permanently in your @file{~/.emacs} file (@pxref{Init File}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
193
58763
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
194 The appearance of the example buffers in this section is typically
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
195 different under a window system, since faces are then used to indicate
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
196 the active fields and other features.
31075
9c560a17ef4a (Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
197
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
198 @menu
59949
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
199 * Groups: Customization Groups. How options are classified in a structure.
59802
67941974673e (Easy Customization): Adapt menu to node name change.
Luc Teirlinck <teirllm@auburn.edu>
parents: 59800
diff changeset
200 * Changing a Variable:: How to edit a value and set an option.
47535
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
201 * Saving Customizations:: Details of saving customizations.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
202 * Face Customization:: How to edit the attributes of a face.
Dave Love <fx@gnu.org>
parents:
diff changeset
203 * Specific Customization:: Making a customization buffer for specific
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
204 variables, faces, or groups.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
205 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
206
Dave Love <fx@gnu.org>
parents:
diff changeset
207 @node Customization Groups
58763
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
208 @subsection Customization Groups
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
209 @cindex customization groups
Dave Love <fx@gnu.org>
parents:
diff changeset
210
Dave Love <fx@gnu.org>
parents:
diff changeset
211 For customization purposes, user options are organized into
Dave Love <fx@gnu.org>
parents:
diff changeset
212 @dfn{groups} to help you find them. Groups are collected into bigger
Dave Love <fx@gnu.org>
parents:
diff changeset
213 groups, all the way up to a master group called @code{Emacs}.
Dave Love <fx@gnu.org>
parents:
diff changeset
214
Dave Love <fx@gnu.org>
parents:
diff changeset
215 @kbd{M-x customize} creates a customization buffer that shows the
Dave Love <fx@gnu.org>
parents:
diff changeset
216 top-level @code{Emacs} group and the second-level groups immediately
Dave Love <fx@gnu.org>
parents:
diff changeset
217 under it. It looks like this, in part:
Dave Love <fx@gnu.org>
parents:
diff changeset
218
Dave Love <fx@gnu.org>
parents:
diff changeset
219 @smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
220 /- Emacs group: ---------------------------------------------------\
Dave Love <fx@gnu.org>
parents:
diff changeset
221 [State]: visible group members are all at standard settings.
Dave Love <fx@gnu.org>
parents:
diff changeset
222 Customization of the One True Editor.
Dave Love <fx@gnu.org>
parents:
diff changeset
223 See also [Manual].
Dave Love <fx@gnu.org>
parents:
diff changeset
224
37977
5ff6cac52888 Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents: 37976
diff changeset
225 Confirm Kill Emacs: [Hide] [Value Menu] Don't confirm
5ff6cac52888 Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents: 37976
diff changeset
226 [State]: this option is unchanged from its standard setting.
5ff6cac52888 Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents: 37976
diff changeset
227 How to ask for confirmation when leaving Emacs. [More]
5ff6cac52888 Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents: 37976
diff changeset
228
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47535
diff changeset
229 Editing group: [Go to Group]
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
230 Basic text editing facilities.
Dave Love <fx@gnu.org>
parents:
diff changeset
231
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47535
diff changeset
232 External group: [Go to Group]
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
233 Interfacing to external utilities.
Dave Love <fx@gnu.org>
parents:
diff changeset
234
Dave Love <fx@gnu.org>
parents:
diff changeset
235 @var{more second-level groups}
Dave Love <fx@gnu.org>
parents:
diff changeset
236
Dave Love <fx@gnu.org>
parents:
diff changeset
237 \- Emacs group end ------------------------------------------------/
Dave Love <fx@gnu.org>
parents:
diff changeset
238
Dave Love <fx@gnu.org>
parents:
diff changeset
239 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
240
Dave Love <fx@gnu.org>
parents:
diff changeset
241 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
242 This says that the buffer displays the contents of the @code{Emacs}
Dave Love <fx@gnu.org>
parents:
diff changeset
243 group. The other groups are listed because they are its contents. But
Dave Love <fx@gnu.org>
parents:
diff changeset
244 they are listed differently, without indentation and dashes, because
Dave Love <fx@gnu.org>
parents:
diff changeset
245 @emph{their} contents are not included. Each group has a single-line
Dave Love <fx@gnu.org>
parents:
diff changeset
246 documentation string; the @code{Emacs} group also has a @samp{[State]}
Dave Love <fx@gnu.org>
parents:
diff changeset
247 line.
Dave Love <fx@gnu.org>
parents:
diff changeset
248
Dave Love <fx@gnu.org>
parents:
diff changeset
249 @cindex editable fields (customization buffer)
Dave Love <fx@gnu.org>
parents:
diff changeset
250 @cindex active fields (customization buffer)
Dave Love <fx@gnu.org>
parents:
diff changeset
251 Most of the text in the customization buffer is read-only, but it
Dave Love <fx@gnu.org>
parents:
diff changeset
252 typically includes some @dfn{editable fields} that you can edit. There
Dave Love <fx@gnu.org>
parents:
diff changeset
253 are also @dfn{active fields}; this means a field that does something
Dave Love <fx@gnu.org>
parents:
diff changeset
254 when you @dfn{invoke} it. To invoke an active field, either click on it
Dave Love <fx@gnu.org>
parents:
diff changeset
255 with @kbd{Mouse-1}, or move point to it and type @key{RET}.
Dave Love <fx@gnu.org>
parents:
diff changeset
256
Dave Love <fx@gnu.org>
parents:
diff changeset
257 For example, the phrase @samp{[Go to Group]} that appears in a
Dave Love <fx@gnu.org>
parents:
diff changeset
258 second-level group is an active field. Invoking the @samp{[Go to
Dave Love <fx@gnu.org>
parents:
diff changeset
259 Group]} field for a group creates a new customization buffer, which
Dave Love <fx@gnu.org>
parents:
diff changeset
260 shows that group and its contents. This field is a kind of hypertext
Dave Love <fx@gnu.org>
parents:
diff changeset
261 link to another group.
Dave Love <fx@gnu.org>
parents:
diff changeset
262
38744
d7121931b3ba Show example of specifying C-M-= in Lisp.
Richard M. Stallman <rms@gnu.org>
parents: 38605
diff changeset
263 The @code{Emacs} group includes a few user options itself, but
d7121931b3ba Show example of specifying C-M-= in Lisp.
Richard M. Stallman <rms@gnu.org>
parents: 38605
diff changeset
264 mainly it contains other groups, which contain more groups, which
d7121931b3ba Show example of specifying C-M-= in Lisp.
Richard M. Stallman <rms@gnu.org>
parents: 38605
diff changeset
265 contain the user options. By browsing the hierarchy of groups, you
d7121931b3ba Show example of specifying C-M-= in Lisp.
Richard M. Stallman <rms@gnu.org>
parents: 38605
diff changeset
266 will eventually find the feature you are interested in customizing.
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
267 Then you can use the customization buffer to set the options
38744
d7121931b3ba Show example of specifying C-M-= in Lisp.
Richard M. Stallman <rms@gnu.org>
parents: 38605
diff changeset
268 pertaining to that feature. You can also go straight to a particular
d7121931b3ba Show example of specifying C-M-= in Lisp.
Richard M. Stallman <rms@gnu.org>
parents: 38605
diff changeset
269 group by name, using the command @kbd{M-x customize-group}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
270
Dave Love <fx@gnu.org>
parents:
diff changeset
271 @findex customize-browse
Dave Love <fx@gnu.org>
parents:
diff changeset
272 You can view the structure of customization groups on a larger scale
Dave Love <fx@gnu.org>
parents:
diff changeset
273 with @kbd{M-x customize-browse}. This command creates a special kind of
Dave Love <fx@gnu.org>
parents:
diff changeset
274 customization buffer which shows only the names of the groups (and
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
275 variables and faces), and their structure.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
276
Dave Love <fx@gnu.org>
parents:
diff changeset
277 In this buffer, you can show the contents of a group by invoking
Dave Love <fx@gnu.org>
parents:
diff changeset
278 @samp{[+]}. When the group contents are visible, this button changes to
Dave Love <fx@gnu.org>
parents:
diff changeset
279 @samp{[-]}; invoking that hides the group contents.
Dave Love <fx@gnu.org>
parents:
diff changeset
280
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
281 Each group, variable, or face name in this buffer has an active field
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
282 which says @samp{[Group]}, @samp{[Variable]} or @samp{[Face]}. Invoking
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
283 that active field creates an ordinary customization buffer showing just
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
284 that group and its contents, just that variable, or just that face.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
285 This is the way to set values in it.
Dave Love <fx@gnu.org>
parents:
diff changeset
286
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
287 @node Changing a Variable
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
288 @subsection Changing a Variable
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
289
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
290 Here is an example of what a variable looks like in the
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
291 customization buffer:
Dave Love <fx@gnu.org>
parents:
diff changeset
292
Dave Love <fx@gnu.org>
parents:
diff changeset
293 @smallexample
37977
5ff6cac52888 Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents: 37976
diff changeset
294 Kill Ring Max: [Hide] 60
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
295 [State]: this variable is unchanged from its standard setting.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
296 Maximum length of kill ring before oldest elements are thrown away.
Dave Love <fx@gnu.org>
parents:
diff changeset
297 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
298
37977
5ff6cac52888 Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents: 37976
diff changeset
299 The text following @samp{[Hide]}, @samp{60} in this case, indicates
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
300 the current value of the variable. If you see @samp{[Show]} instead of
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
301 @samp{[Hide]}, it means that the value is hidden; the customization
Dave Love <fx@gnu.org>
parents:
diff changeset
302 buffer initially hides values that take up several lines. Invoke
Dave Love <fx@gnu.org>
parents:
diff changeset
303 @samp{[Show]} to show the value.
Dave Love <fx@gnu.org>
parents:
diff changeset
304
Dave Love <fx@gnu.org>
parents:
diff changeset
305 The line after the option name indicates the @dfn{customization state}
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
306 of the variable: in the example above, it says you have not changed the
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
307 option yet. The word @samp{[State]} at the beginning of this line is
Dave Love <fx@gnu.org>
parents:
diff changeset
308 active; you can get a menu of various operations by invoking it with
Dave Love <fx@gnu.org>
parents:
diff changeset
309 @kbd{Mouse-1} or @key{RET}. These operations are essential for
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
310 customizing the variable.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
311
Dave Love <fx@gnu.org>
parents:
diff changeset
312 The line after the @samp{[State]} line displays the beginning of the
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
313 variable's documentation string. If there are more lines of
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
314 documentation, this line ends with @samp{[More]}; invoke this to show
Dave Love <fx@gnu.org>
parents:
diff changeset
315 the full documentation string.
Dave Love <fx@gnu.org>
parents:
diff changeset
316
Dave Love <fx@gnu.org>
parents:
diff changeset
317 To enter a new value for @samp{Kill Ring Max}, move point to the value
Dave Love <fx@gnu.org>
parents:
diff changeset
318 and edit it textually. For example, you can type @kbd{M-d}, then insert
Dave Love <fx@gnu.org>
parents:
diff changeset
319 another number.
Dave Love <fx@gnu.org>
parents:
diff changeset
320
Dave Love <fx@gnu.org>
parents:
diff changeset
321 When you begin to alter the text, you will see the @samp{[State]} line
Dave Love <fx@gnu.org>
parents:
diff changeset
322 change to say that you have edited the value:
Dave Love <fx@gnu.org>
parents:
diff changeset
323
Dave Love <fx@gnu.org>
parents:
diff changeset
324 @smallexample
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
325 [State]: you have edited the value as text, but not set the variable.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
326 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
327
Dave Love <fx@gnu.org>
parents:
diff changeset
328 @cindex setting option value
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
329 Editing the value does not actually set the variable. To do
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
330 that, you must @dfn{set} it. To do this, invoke the word
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
331 @samp{[State]} and choose @samp{Set for Current Session}.
Dave Love <fx@gnu.org>
parents:
diff changeset
332
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
333 The state of the variable changes visibly when you set it:
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
334
Dave Love <fx@gnu.org>
parents:
diff changeset
335 @smallexample
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
336 [State]: you have set this variable, but not saved it for future sessions.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
337 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
338
Dave Love <fx@gnu.org>
parents:
diff changeset
339 You don't have to worry about specifying a value that is not valid;
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
340 setting the variable checks for validity and will not really install an
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
341 unacceptable value.
Dave Love <fx@gnu.org>
parents:
diff changeset
342
Dave Love <fx@gnu.org>
parents:
diff changeset
343 @kindex M-TAB @r{(customization buffer)}
Dave Love <fx@gnu.org>
parents:
diff changeset
344 @findex widget-complete
Dave Love <fx@gnu.org>
parents:
diff changeset
345 While editing a value or field that is a file name, directory name,
60423
ad01c2a006c4 (Changing a Variable): C-M-i like M-TAB.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
346 command name, or anything else for which completion is defined, you
ad01c2a006c4 (Changing a Variable): C-M-i like M-TAB.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
347 can type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion.
ad01c2a006c4 (Changing a Variable): C-M-i like M-TAB.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
348 (@kbd{@key{ESC} @key{TAB}} and @kbd{C-M-i} do the same thing.)
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
349
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
350 Some variables have a small fixed set of possible legitimate values.
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
351 These variables don't let you edit the value textually. Instead, an
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
352 active field @samp{[Value Menu]} appears before the value; invoke this
Dave Love <fx@gnu.org>
parents:
diff changeset
353 field to edit the value. For a boolean ``on or off'' value, the active
Dave Love <fx@gnu.org>
parents:
diff changeset
354 field says @samp{[Toggle]}, and it changes to the other value.
Dave Love <fx@gnu.org>
parents:
diff changeset
355 @samp{[Value Menu]} and @samp{[Toggle]} edit the buffer; the changes
Dave Love <fx@gnu.org>
parents:
diff changeset
356 take effect when you use the @samp{Set for Current Session} operation.
Dave Love <fx@gnu.org>
parents:
diff changeset
357
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
358 Some variables have values with complex structure. For example, the
31075
9c560a17ef4a (Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
359 value of @code{file-coding-system-alist} is an association list. Here
9c560a17ef4a (Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
360 is how it appears in the customization buffer:
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
361
Dave Love <fx@gnu.org>
parents:
diff changeset
362 @smallexample
31075
9c560a17ef4a (Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
363 File Coding System Alist: [Hide]
9c560a17ef4a (Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
364 [INS] [DEL] File regexp: \.elc\'
9c560a17ef4a (Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
365 Choice: [Value Menu] Encoding/decoding pair:
9c560a17ef4a (Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
366 Decoding: emacs-mule
9c560a17ef4a (Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
367 Encoding: emacs-mule
9c560a17ef4a (Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
368 [INS] [DEL] File regexp: \(\`\|/\)loaddefs.el\'
9c560a17ef4a (Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
369 Choice: [Value Menu] Encoding/decoding pair:
37977
5ff6cac52888 Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents: 37976
diff changeset
370 Decoding: raw-text
5ff6cac52888 Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents: 37976
diff changeset
371 Encoding: raw-text-unix
31075
9c560a17ef4a (Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
372 [INS] [DEL] File regexp: \.tar\'
9c560a17ef4a (Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
373 Choice: [Value Menu] Encoding/decoding pair:
9c560a17ef4a (Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
374 Decoding: no-conversion
9c560a17ef4a (Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
375 Encoding: no-conversion
9c560a17ef4a (Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
376 [INS] [DEL] File regexp:
9c560a17ef4a (Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
377 Choice: [Value Menu] Encoding/decoding pair:
9c560a17ef4a (Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
378 Decoding: undecided
9c560a17ef4a (Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
379 Encoding: nil
36148
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
380 [INS]
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
381 [State]: this variable is unchanged from its standard setting.
31075
9c560a17ef4a (Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
382 Alist to decide a coding system to use for a file I/O operation. [Hide]
36148
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
383 The format is ((PATTERN . VAL) ...),
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
384 where PATTERN is a regular expression matching a file name,
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
385 @r{[@dots{}more lines of documentation@dots{}]}
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
386 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
387
Dave Love <fx@gnu.org>
parents:
diff changeset
388 @noindent
36148
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
389 Each association in the list appears on four lines, with several
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
390 editable or ``active'' fields. You can edit the regexps and coding
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
391 systems using ordinary editing commands. You can also invoke
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
392 @samp{[Value Menu]} to switch to a kind of value---for instance, to
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
393 specify a function instead of a pair of coding systems.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
394
36148
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
395 To delete an association from the list, invoke the @samp{[DEL]} button
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
396 for that item. To add an association, invoke @samp{[INS]} at the
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
397 position where you want to add it. There is an @samp{[INS]} button
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
398 between each pair of association, another at the beginning and another
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
399 at the end, so you can add the new association at any position in the
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
400 list.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
401
Dave Love <fx@gnu.org>
parents:
diff changeset
402 @kindex TAB @r{(customization buffer)}
Dave Love <fx@gnu.org>
parents:
diff changeset
403 @kindex S-TAB @r{(customization buffer)}
Dave Love <fx@gnu.org>
parents:
diff changeset
404 @findex widget-forward
Dave Love <fx@gnu.org>
parents:
diff changeset
405 @findex widget-backward
Dave Love <fx@gnu.org>
parents:
diff changeset
406 Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful for
Dave Love <fx@gnu.org>
parents:
diff changeset
407 moving through the customization buffer. @key{TAB}
Dave Love <fx@gnu.org>
parents:
diff changeset
408 (@code{widget-forward}) moves forward to the next active or editable
Dave Love <fx@gnu.org>
parents:
diff changeset
409 field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to the
Dave Love <fx@gnu.org>
parents:
diff changeset
410 previous active or editable field.
Dave Love <fx@gnu.org>
parents:
diff changeset
411
Dave Love <fx@gnu.org>
parents:
diff changeset
412 Typing @key{RET} on an editable field also moves forward, just like
36148
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
413 @key{TAB}. We set it up this way because people often type @key{RET}
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
414 when they are finished editing a field. To insert a newline within an
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
415 editable field, use @kbd{C-o} or @kbd{C-q C-j}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
416
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
417 @cindex saving variable value
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
418 @cindex customized variables, saving
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
419 Setting the variable changes its value in the current Emacs session;
47535
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
420 @dfn{saving} the value changes it for future sessions as well. To
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
421 save the variable, invoke @samp{[State]} and select the @samp{Save for
47535
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
422 Future Sessions} operation. This works by writing code so as to set
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
423 the variable again, each time you start Emacs (@pxref{Saving
47535
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
424 Customizations}).
37618
764853859fbc (Changing an Option): Document that "emacs -q" cannot save customizations.
Eli Zaretskii <eliz@gnu.org>
parents: 37596
diff changeset
425
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
426 You can also restore the variable to its standard value by invoking
47535
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
427 @samp{[State]} and selecting the @samp{Erase Customization} operation.
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
428 There are actually three reset operations:
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
429
Dave Love <fx@gnu.org>
parents:
diff changeset
430 @table @samp
Dave Love <fx@gnu.org>
parents:
diff changeset
431 @item Reset
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
432 If you have made some modifications and not yet set the variable,
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
433 this restores the text in the customization buffer to match
Dave Love <fx@gnu.org>
parents:
diff changeset
434 the actual value.
Dave Love <fx@gnu.org>
parents:
diff changeset
435
Dave Love <fx@gnu.org>
parents:
diff changeset
436 @item Reset to Saved
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
437 This restores the value of the variable to the last saved value,
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
438 and updates the text accordingly.
Dave Love <fx@gnu.org>
parents:
diff changeset
439
27218
ff77115434db Doc recent changes in Custom.
Dave Love <fx@gnu.org>
parents: 26392
diff changeset
440 @item Erase Customization
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
441 This sets the variable to its standard value, and updates the text
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
442 accordingly. This also eliminates any saved value for the option,
Dave Love <fx@gnu.org>
parents:
diff changeset
443 so that you will get the standard value in future Emacs sessions.
47535
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
444
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
445 @item Use Backup Value
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
446 This sets the variable to a previous value that was set in the
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
447 customization buffer in this session. If you customize a variable
58763
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
448 and then reset it, which discards the customized value,
47535
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
449 you can get the customized value back again with this operation.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
450 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
451
27218
ff77115434db Doc recent changes in Custom.
Dave Love <fx@gnu.org>
parents: 26392
diff changeset
452 @cindex comments on customized options
36148
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
453 Sometimes it is useful to record a comment about a specific
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
454 customization. Use the @samp{Add Comment} item from the
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
455 @samp{[State]} menu to create a field for entering the comment. The
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
456 comment you enter will be saved, and displayed again if you again view
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
457 the same variable in a customization buffer, even in another session.
27218
ff77115434db Doc recent changes in Custom.
Dave Love <fx@gnu.org>
parents: 26392
diff changeset
458
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
459 The state of a group indicates whether anything in that group has been
Dave Love <fx@gnu.org>
parents:
diff changeset
460 edited, set or saved. You can select @samp{Set for Current Session},
Dave Love <fx@gnu.org>
parents:
diff changeset
461 @samp{Save for Future Sessions} and the various kinds of @samp{Reset}
Dave Love <fx@gnu.org>
parents:
diff changeset
462 operation for the group; these operations on the group apply to all
Dave Love <fx@gnu.org>
parents:
diff changeset
463 options in the group and its subgroups.
Dave Love <fx@gnu.org>
parents:
diff changeset
464
Dave Love <fx@gnu.org>
parents:
diff changeset
465 Near the top of the customization buffer there are two lines
Dave Love <fx@gnu.org>
parents:
diff changeset
466 containing several active fields:
Dave Love <fx@gnu.org>
parents:
diff changeset
467
Dave Love <fx@gnu.org>
parents:
diff changeset
468 @smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
469 [Set for Current Session] [Save for Future Sessions]
27218
ff77115434db Doc recent changes in Custom.
Dave Love <fx@gnu.org>
parents: 26392
diff changeset
470 [Reset] [Reset to Saved] [Erase Customization] [Finish]
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
471 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
472
36593
4567e1729217 custom-buffer-done-function <- Custom-buffer-done
Dave Love <fx@gnu.org>
parents: 36292
diff changeset
473 @vindex custom-buffer-done-function
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
474 @noindent
27218
ff77115434db Doc recent changes in Custom.
Dave Love <fx@gnu.org>
parents: 26392
diff changeset
475 Invoking @samp{[Finish]} either buries or kills this customization
36593
4567e1729217 custom-buffer-done-function <- Custom-buffer-done
Dave Love <fx@gnu.org>
parents: 36292
diff changeset
476 buffer according to the setting of the option
4567e1729217 custom-buffer-done-function <- Custom-buffer-done
Dave Love <fx@gnu.org>
parents: 36292
diff changeset
477 @code{custom-buffer-done-function}; the default is to bury the buffer.
4567e1729217 custom-buffer-done-function <- Custom-buffer-done
Dave Love <fx@gnu.org>
parents: 36292
diff changeset
478 Each of the other fields performs an operation---set, save or
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
479 reset---on each of the options in the buffer that could meaningfully
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
480 be set, saved or reset. They do not operate on options whose values
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
481 are hidden.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
482
47535
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
483 @node Saving Customizations
58763
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
484 @subsection Saving Customizations
47535
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
485
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
486 @vindex custom-file
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
487 The customization buffer normally saves customizations in
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
488 @file{~/.emacs}. If you wish, you can save customizations in another
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
489 file instead. To make this work, your @file{~/.emacs} should set
59353
c13a0c603028 (Saving Customizations): Minor improvement.
Richard M. Stallman <rms@gnu.org>
parents: 59336
diff changeset
490 @code{custom-file} to the name of that file. Then you should load the
c13a0c603028 (Saving Customizations): Minor improvement.
Richard M. Stallman <rms@gnu.org>
parents: 59336
diff changeset
491 file by calling @code{load}. For example:
47535
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
492
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
493 @example
59336
b442f3501e4e (Saving Customizations): Emacs no longer loads `custom-file' after
Luc Teirlinck <teirllm@auburn.edu>
parents: 59282
diff changeset
494 (setq custom-file "~/.emacs-custom.el")
b442f3501e4e (Saving Customizations): Emacs no longer loads `custom-file' after
Luc Teirlinck <teirllm@auburn.edu>
parents: 59282
diff changeset
495 (load custom-file)
47535
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
496 @end example
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
497
58861
2e075e3c65a4 (Saving Customizations): Emacs only loads the custom file
Luc Teirlinck <teirllm@auburn.edu>
parents: 58764
diff changeset
498 You can also use @code{custom-file} to specify different
2e075e3c65a4 (Saving Customizations): Emacs only loads the custom file
Luc Teirlinck <teirllm@auburn.edu>
parents: 58764
diff changeset
499 customization files for different Emacs versions, like this:
47535
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
500
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
501 @example
58861
2e075e3c65a4 (Saving Customizations): Emacs only loads the custom file
Luc Teirlinck <teirllm@auburn.edu>
parents: 58764
diff changeset
502 (cond ((< emacs-major-version 21)
2e075e3c65a4 (Saving Customizations): Emacs only loads the custom file
Luc Teirlinck <teirllm@auburn.edu>
parents: 58764
diff changeset
503 ;; @r{Emacs 20 customization.}
2e075e3c65a4 (Saving Customizations): Emacs only loads the custom file
Luc Teirlinck <teirllm@auburn.edu>
parents: 58764
diff changeset
504 (setq custom-file "~/.custom-20.el"))
2e075e3c65a4 (Saving Customizations): Emacs only loads the custom file
Luc Teirlinck <teirllm@auburn.edu>
parents: 58764
diff changeset
505 ((and (= emacs-major-version 21) (< emacs-minor-version 4))
2e075e3c65a4 (Saving Customizations): Emacs only loads the custom file
Luc Teirlinck <teirllm@auburn.edu>
parents: 58764
diff changeset
506 ;; @r{Emacs 21 customization, before version 21.4.}
2e075e3c65a4 (Saving Customizations): Emacs only loads the custom file
Luc Teirlinck <teirllm@auburn.edu>
parents: 58764
diff changeset
507 (setq custom-file "~/.custom-21.el"))
59996
aac0a33f5772 Change release version from 21.4 to 22.1 throughout.
Kim F. Storm <storm@cua.dk>
parents: 59961
diff changeset
508 ((< emacs-major-version 22)
58861
2e075e3c65a4 (Saving Customizations): Emacs only loads the custom file
Luc Teirlinck <teirllm@auburn.edu>
parents: 58764
diff changeset
509 ;; @r{Emacs version 21.4 or later.}
59996
aac0a33f5772 Change release version from 21.4 to 22.1 throughout.
Kim F. Storm <storm@cua.dk>
parents: 59961
diff changeset
510 (setq custom-file "~/.custom-21.4.el"))
aac0a33f5772 Change release version from 21.4 to 22.1 throughout.
Kim F. Storm <storm@cua.dk>
parents: 59961
diff changeset
511 (t
aac0a33f5772 Change release version from 21.4 to 22.1 throughout.
Kim F. Storm <storm@cua.dk>
parents: 59961
diff changeset
512 ;; @r{Emacs version 22.1 or later.}
aac0a33f5772 Change release version from 21.4 to 22.1 throughout.
Kim F. Storm <storm@cua.dk>
parents: 59961
diff changeset
513 (setq custom-file "~/.custom-22.el")))
58861
2e075e3c65a4 (Saving Customizations): Emacs only loads the custom file
Luc Teirlinck <teirllm@auburn.edu>
parents: 58764
diff changeset
514
2e075e3c65a4 (Saving Customizations): Emacs only loads the custom file
Luc Teirlinck <teirllm@auburn.edu>
parents: 58764
diff changeset
515 (load custom-file)
47535
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
516 @end example
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
517
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
518 If Emacs was invoked with the @option{-q} or @option{--no-init-file}
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
519 options (@pxref{Initial Options}), it will not let you save your
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
520 customizations in your @file{~/.emacs} init file. This is because
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
521 saving customizations from such a session would wipe out all the other
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
522 customizations you might have on your init file.
761358848235 (Saving Customizations): New node has the info on custom-file.
Richard M. Stallman <rms@gnu.org>
parents: 46890
diff changeset
523
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
524 @node Face Customization
58763
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
525 @subsection Customizing Faces
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
526 @cindex customizing faces
Dave Love <fx@gnu.org>
parents:
diff changeset
527 @cindex bold font
Dave Love <fx@gnu.org>
parents:
diff changeset
528 @cindex italic font
Dave Love <fx@gnu.org>
parents:
diff changeset
529 @cindex fonts and faces
Dave Love <fx@gnu.org>
parents:
diff changeset
530
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
531 In addition to variables, some customization groups also include
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
532 faces. When you show the contents of a group, both the variables and
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
533 the faces in the group appear in the customization buffer. Here is an
Dave Love <fx@gnu.org>
parents:
diff changeset
534 example of how a face looks:
Dave Love <fx@gnu.org>
parents:
diff changeset
535
Dave Love <fx@gnu.org>
parents:
diff changeset
536 @smallexample
44278
2f0122b0b947 Update the `customize-face' example to reflect current reality.
Miles Bader <miles@gnu.org>
parents: 43062
diff changeset
537 Custom Changed Face:(sample) [Hide]
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
538 [State]: this face is unchanged from its standard setting.
44278
2f0122b0b947 Update the `customize-face' example to reflect current reality.
Miles Bader <miles@gnu.org>
parents: 43062
diff changeset
539 Face used when the customize item has been changed.
2f0122b0b947 Update the `customize-face' example to reflect current reality.
Miles Bader <miles@gnu.org>
parents: 43062
diff changeset
540 Parent groups: => Custom Magic Faces
2f0122b0b947 Update the `customize-face' example to reflect current reality.
Miles Bader <miles@gnu.org>
parents: 43062
diff changeset
541 Attributes: [ ] Font Family: *
2f0122b0b947 Update the `customize-face' example to reflect current reality.
Miles Bader <miles@gnu.org>
parents: 43062
diff changeset
542 [ ] Width: *
2f0122b0b947 Update the `customize-face' example to reflect current reality.
Miles Bader <miles@gnu.org>
parents: 43062
diff changeset
543 [ ] Height: *
2f0122b0b947 Update the `customize-face' example to reflect current reality.
Miles Bader <miles@gnu.org>
parents: 43062
diff changeset
544 [ ] Weight: *
2f0122b0b947 Update the `customize-face' example to reflect current reality.
Miles Bader <miles@gnu.org>
parents: 43062
diff changeset
545 [ ] Slant: *
2f0122b0b947 Update the `customize-face' example to reflect current reality.
Miles Bader <miles@gnu.org>
parents: 43062
diff changeset
546 [ ] Underline: *
2f0122b0b947 Update the `customize-face' example to reflect current reality.
Miles Bader <miles@gnu.org>
parents: 43062
diff changeset
547 [ ] Overline: *
2f0122b0b947 Update the `customize-face' example to reflect current reality.
Miles Bader <miles@gnu.org>
parents: 43062
diff changeset
548 [ ] Strike-through: *
2f0122b0b947 Update the `customize-face' example to reflect current reality.
Miles Bader <miles@gnu.org>
parents: 43062
diff changeset
549 [ ] Box around text: *
2f0122b0b947 Update the `customize-face' example to reflect current reality.
Miles Bader <miles@gnu.org>
parents: 43062
diff changeset
550 [ ] Inverse-video: *
2f0122b0b947 Update the `customize-face' example to reflect current reality.
Miles Bader <miles@gnu.org>
parents: 43062
diff changeset
551 [X] Foreground: white (sample)
2f0122b0b947 Update the `customize-face' example to reflect current reality.
Miles Bader <miles@gnu.org>
parents: 43062
diff changeset
552 [X] Background: blue (sample)
2f0122b0b947 Update the `customize-face' example to reflect current reality.
Miles Bader <miles@gnu.org>
parents: 43062
diff changeset
553 [ ] Stipple: *
2f0122b0b947 Update the `customize-face' example to reflect current reality.
Miles Bader <miles@gnu.org>
parents: 43062
diff changeset
554 [ ] Inherit: *
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
555 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
556
Dave Love <fx@gnu.org>
parents:
diff changeset
557 Each face attribute has its own line. The @samp{[@var{x}]} field
Dave Love <fx@gnu.org>
parents:
diff changeset
558 before the attribute name indicates whether the attribute is
Dave Love <fx@gnu.org>
parents:
diff changeset
559 @dfn{enabled}; @samp{X} means that it is. You can enable or disable the
Dave Love <fx@gnu.org>
parents:
diff changeset
560 attribute by invoking that field. When the attribute is enabled, you
Dave Love <fx@gnu.org>
parents:
diff changeset
561 can change the attribute value in the usual ways.
Dave Love <fx@gnu.org>
parents:
diff changeset
562
59282
b7abe21b4ff3 (Face Customization): Mention hex color specs.
Richard M. Stallman <rms@gnu.org>
parents: 59192
diff changeset
563 For the colors, you can specify a color name (use @kbd{M-x
b7abe21b4ff3 (Face Customization): Mention hex color specs.
Richard M. Stallman <rms@gnu.org>
parents: 59192
diff changeset
564 list-colors-display}) for a list of them) or a hexadecimal color
b7abe21b4ff3 (Face Customization): Mention hex color specs.
Richard M. Stallman <rms@gnu.org>
parents: 59192
diff changeset
565 specification of the form @samp{#@var{rr}@var{gg}@var{bb}}.
b7abe21b4ff3 (Face Customization): Mention hex color specs.
Richard M. Stallman <rms@gnu.org>
parents: 59192
diff changeset
566 (@samp{#000000} is black, @samp{#ff0000} is red, @samp{#00ff00} is
b7abe21b4ff3 (Face Customization): Mention hex color specs.
Richard M. Stallman <rms@gnu.org>
parents: 59192
diff changeset
567 green, @samp{#0000ff} is blue, and @samp{#ffffff} is white.) On a
b7abe21b4ff3 (Face Customization): Mention hex color specs.
Richard M. Stallman <rms@gnu.org>
parents: 59192
diff changeset
568 black-and-white display, the colors you can use for the background are
b7abe21b4ff3 (Face Customization): Mention hex color specs.
Richard M. Stallman <rms@gnu.org>
parents: 59192
diff changeset
569 @samp{black}, @samp{white}, @samp{gray}, @samp{gray1}, and
b7abe21b4ff3 (Face Customization): Mention hex color specs.
Richard M. Stallman <rms@gnu.org>
parents: 59192
diff changeset
570 @samp{gray3}. Emacs supports these shades of gray by using background
b7abe21b4ff3 (Face Customization): Mention hex color specs.
Richard M. Stallman <rms@gnu.org>
parents: 59192
diff changeset
571 stipple patterns instead of a color.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
572
Dave Love <fx@gnu.org>
parents:
diff changeset
573 Setting, saving and resetting a face work like the same operations for
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
574 variables (@pxref{Changing a Variable}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
575
Dave Love <fx@gnu.org>
parents:
diff changeset
576 A face can specify different appearances for different types of
Dave Love <fx@gnu.org>
parents:
diff changeset
577 display. For example, a face can make text red on a color display, but
Dave Love <fx@gnu.org>
parents:
diff changeset
578 use a bold font on a monochrome display. To specify multiple
37977
5ff6cac52888 Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents: 37976
diff changeset
579 appearances for a face, select @samp{Show all display specs} in the menu you
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
580 get from invoking @samp{[State]}.
Dave Love <fx@gnu.org>
parents:
diff changeset
581
Dave Love <fx@gnu.org>
parents:
diff changeset
582 @findex modify-face
Dave Love <fx@gnu.org>
parents:
diff changeset
583 Another more basic way to set the attributes of a specific face is
Dave Love <fx@gnu.org>
parents:
diff changeset
584 with @kbd{M-x modify-face}. This command reads the name of a face, then
Dave Love <fx@gnu.org>
parents:
diff changeset
585 reads the attributes one by one. For the color and stipple attributes,
Dave Love <fx@gnu.org>
parents:
diff changeset
586 the attribute's current value is the default---type just @key{RET} if
Dave Love <fx@gnu.org>
parents:
diff changeset
587 you don't want to change that attribute. Type @samp{none} if you want
Dave Love <fx@gnu.org>
parents:
diff changeset
588 to clear out the attribute.
Dave Love <fx@gnu.org>
parents:
diff changeset
589
Dave Love <fx@gnu.org>
parents:
diff changeset
590 @node Specific Customization
58763
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
591 @subsection Customizing Specific Items
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
592
Dave Love <fx@gnu.org>
parents:
diff changeset
593 Instead of finding the options you want to change by moving down
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
594 through the structure of groups, you can specify the particular variable,
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
595 face, or group that you want to customize.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
596
Dave Love <fx@gnu.org>
parents:
diff changeset
597 @table @kbd
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
598 @item M-x customize-variable @key{RET} @var{variable} @key{RET}
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
599 Set up a customization buffer with just one variable, @var{variable}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
600 @item M-x customize-face @key{RET} @var{face} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
601 Set up a customization buffer with just one face, @var{face}.
Dave Love <fx@gnu.org>
parents:
diff changeset
602 @item M-x customize-group @key{RET} @var{group} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
603 Set up a customization buffer with just one group, @var{group}.
Dave Love <fx@gnu.org>
parents:
diff changeset
604 @item M-x customize-apropos @key{RET} @var{regexp} @key{RET}
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
605 Set up a customization buffer with all the variables, faces and groups
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
606 that match @var{regexp}.
Dave Love <fx@gnu.org>
parents:
diff changeset
607 @item M-x customize-changed-options @key{RET} @var{version} @key{RET}
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
608 Set up a customization buffer with all the variables, faces and groups
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
609 whose meaning has changed since Emacs version @var{version}.
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47535
diff changeset
610 @item M-x customize-saved
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
611 Set up a customization buffer containing all variables and faces that you
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
612 have saved with customization buffers.
Dave Love <fx@gnu.org>
parents:
diff changeset
613 @item M-x customize-customized
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
614 Set up a customization buffer containing all variables and faces that you
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
615 have customized but not saved.
Dave Love <fx@gnu.org>
parents:
diff changeset
616 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
617
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
618 @findex customize-variable
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
619 If you want to alter a particular variable with the customization
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
620 buffer, and you know its name, you can use the command @kbd{M-x
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
621 customize-variable} and specify the variable name. This sets up the
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
622 customization buffer with just one variable---the one that you asked
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
623 for. Editing, setting and saving the value work as described above,
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
624 but only for the specified variable.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
625
Dave Love <fx@gnu.org>
parents:
diff changeset
626 @findex customize-face
Dave Love <fx@gnu.org>
parents:
diff changeset
627 Likewise, you can modify a specific face, chosen by name, using
46039
3c5d96a2d05f Doc default arg for customize-face.
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
628 @kbd{M-x customize-face}. By default it operates on the face used
3c5d96a2d05f Doc default arg for customize-face.
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
629 on the character after point.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
630
Dave Love <fx@gnu.org>
parents:
diff changeset
631 @findex customize-group
Dave Love <fx@gnu.org>
parents:
diff changeset
632 You can also set up the customization buffer with a specific group,
Dave Love <fx@gnu.org>
parents:
diff changeset
633 using @kbd{M-x customize-group}. The immediate contents of the chosen
58763
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
634 group, including user options, faces, and other groups, all appear
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
635 as well. However, these subgroups' own contents start out hidden. You
Dave Love <fx@gnu.org>
parents:
diff changeset
636 can show their contents in the usual way, by invoking @samp{[Show]}.
Dave Love <fx@gnu.org>
parents:
diff changeset
637
Dave Love <fx@gnu.org>
parents:
diff changeset
638 @findex customize-apropos
Dave Love <fx@gnu.org>
parents:
diff changeset
639 To control more precisely what to customize, you can use @kbd{M-x
Dave Love <fx@gnu.org>
parents:
diff changeset
640 customize-apropos}. You specify a regular expression as argument; then
Dave Love <fx@gnu.org>
parents:
diff changeset
641 all options, faces and groups whose names match this regular expression
Dave Love <fx@gnu.org>
parents:
diff changeset
642 are set up in the customization buffer. If you specify an empty regular
Dave Love <fx@gnu.org>
parents:
diff changeset
643 expression, this includes @emph{all} groups, options and faces in the
Dave Love <fx@gnu.org>
parents:
diff changeset
644 customization buffer (but that takes a long time).
Dave Love <fx@gnu.org>
parents:
diff changeset
645
Dave Love <fx@gnu.org>
parents:
diff changeset
646 @findex customize-changed-options
Dave Love <fx@gnu.org>
parents:
diff changeset
647 When you upgrade to a new Emacs version, you might want to customize
Dave Love <fx@gnu.org>
parents:
diff changeset
648 new options and options whose meanings or default values have changed.
Dave Love <fx@gnu.org>
parents:
diff changeset
649 To do this, use @kbd{M-x customize-changed-options} and specify a
Dave Love <fx@gnu.org>
parents:
diff changeset
650 previous Emacs version number using the minibuffer. It creates a
Dave Love <fx@gnu.org>
parents:
diff changeset
651 customization buffer which shows all the options (and groups) whose
Dave Love <fx@gnu.org>
parents:
diff changeset
652 definitions have been changed since the specified version.
Dave Love <fx@gnu.org>
parents:
diff changeset
653
Dave Love <fx@gnu.org>
parents:
diff changeset
654 @findex customize-saved
Dave Love <fx@gnu.org>
parents:
diff changeset
655 @findex customize-customized
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
656 If you change option values and then decide the change was a
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
657 mistake, you can use two special commands to revisit your previous
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
658 changes. Use @kbd{M-x customize-saved} to look at the options that
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
659 you have saved. Use @kbd{M-x customize-customized} to look at the
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
660 options that you have set but not saved.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
661
58763
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
662 @node Variables
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
663 @section Variables
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
664 @cindex variable
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
665 @cindex option, user
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
666 @cindex user option
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
667
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
668 A @dfn{variable} is a Lisp symbol which has a value. The symbol's
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
669 name is also called the name of the variable. A variable name can
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
670 contain any characters that can appear in a file, but conventionally
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
671 variable names consist of words separated by hyphens. A variable can
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
672 have a documentation string which describes what kind of value it should
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
673 have and how the value will be used.
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
674
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
675 Lisp allows any variable to have any kind of value, but most variables
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
676 that Emacs uses need a value of a certain type. Often the value should
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
677 always be a string, or should always be a number. Sometimes we say that a
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
678 certain feature is turned on if a variable is ``non-@code{nil},'' meaning
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
679 that if the variable's value is @code{nil}, the feature is off, but the
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
680 feature is on for @emph{any} other value. The conventional value to use to
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
681 turn on the feature---since you have to pick one particular value when you
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
682 set the variable---is @code{t}.
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
683
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
684 Emacs uses many Lisp variables for internal record keeping, but the
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
685 most interesting variables for a non-programmer user are those that
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
686 are also @dfn{user options}, the variables that are meant for users to
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
687 change. Each user option that you can set with the customization
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
688 buffer is (if it is not a face) in fact a Lisp variable. Emacs does
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
689 not (usually) change the values of these variables; instead, you set
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
690 the values, and thereby alter and control the behavior of certain
59949
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
691 Emacs commands. Use of the customization buffer is explained above
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
692 (@pxref{Easy Customization}); here we describe other aspects of Emacs
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
693 variables.
58763
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
694
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
695 @menu
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
696 * Examining:: Examining or setting one variable's value.
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
697 * Hooks:: Hook variables let you specify programs for parts
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
698 of Emacs to run on particular occasions.
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
699 * Locals:: Per-buffer values of variables.
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
700 * File Variables:: How files can specify variable values.
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
701 @end menu
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
702
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
703 @node Examining
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
704 @subsection Examining and Setting Variables
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
705 @cindex setting variables
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
706
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
707 @table @kbd
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
708 @item C-h v @var{var} @key{RET}
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
709 Display the value and documentation of variable @var{var}
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
710 (@code{describe-variable}).
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
711 @item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET}
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
712 Change the value of variable @var{var} to @var{value}.
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
713 @end table
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
714
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
715 To examine the value of a single variable, use @kbd{C-h v}
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
716 (@code{describe-variable}), which reads a variable name using the
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
717 minibuffer, with completion. It displays both the value and the
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
718 documentation of the variable. For example,
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
719
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
720 @example
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
721 C-h v fill-column @key{RET}
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
722 @end example
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
723
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
724 @noindent
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
725 displays something like this:
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
726
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
727 @smallexample
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
728 fill-column's value is 70
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
729
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
730 Documentation:
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
731 *Column beyond which automatic line-wrapping should happen.
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
732 Automatically becomes buffer-local when set in any fashion.
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
733 @end smallexample
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
734
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
735 @noindent
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
736 The star at the beginning of the documentation indicates that this
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
737 variable is a user option. @kbd{C-h v} is not restricted to user
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
738 options; it allows any variable name.
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
739
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
740 @findex set-variable
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
741 The most convenient way to set a specific user option variable is
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
742 with @kbd{M-x set-variable}. This reads the variable name with the
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
743 minibuffer (with completion), and then reads a Lisp expression for the
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
744 new value using the minibuffer a second time. For example,
58763
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
745
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
746 @example
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
747 M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET}
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
748 @end example
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
749
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
750 @noindent
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
751 sets @code{fill-column} to 75.
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
752
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
753 @kbd{M-x set-variable} is limited to user option variables, but you can
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
754 set any variable with a Lisp expression, using the function @code{setq}.
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
755 Here is a @code{setq} expression to set @code{fill-column}:
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
756
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
757 @example
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
758 (setq fill-column 75)
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
759 @end example
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
760
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
761 To execute an expression like this one, go to the @samp{*scratch*}
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
762 buffer, type in the expression, and then type @kbd{C-j}. @xref{Lisp
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
763 Interaction}.
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
764
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
765 Setting variables, like all means of customizing Emacs except where
59949
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
766 otherwise stated, affects only the current Emacs session. The only
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
767 way to alter the variable in future sessions is to put something in
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
768 the @file{~/.emacs} file to set it those sessions (@pxref{Init File}).
58763
25b217a7d2af (Easy Customization): Move up to section level,
Richard M. Stallman <rms@gnu.org>
parents: 58624
diff changeset
769
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
770 @node Hooks
Dave Love <fx@gnu.org>
parents:
diff changeset
771 @subsection Hooks
Dave Love <fx@gnu.org>
parents:
diff changeset
772 @cindex hook
Dave Love <fx@gnu.org>
parents:
diff changeset
773 @cindex running a hook
Dave Love <fx@gnu.org>
parents:
diff changeset
774
Dave Love <fx@gnu.org>
parents:
diff changeset
775 @dfn{Hooks} are an important mechanism for customization of Emacs. A
Dave Love <fx@gnu.org>
parents:
diff changeset
776 hook is a Lisp variable which holds a list of functions, to be called on
Dave Love <fx@gnu.org>
parents:
diff changeset
777 some well-defined occasion. (This is called @dfn{running the hook}.)
Dave Love <fx@gnu.org>
parents:
diff changeset
778 The individual functions in the list are called the @dfn{hook functions}
Dave Love <fx@gnu.org>
parents:
diff changeset
779 of the hook. With rare exceptions, hooks in Emacs are empty when Emacs
Dave Love <fx@gnu.org>
parents:
diff changeset
780 starts up, so the only hook functions in any given hook are the ones you
Dave Love <fx@gnu.org>
parents:
diff changeset
781 explicitly put there as customization.
Dave Love <fx@gnu.org>
parents:
diff changeset
782
Dave Love <fx@gnu.org>
parents:
diff changeset
783 Most major modes run one or more @dfn{mode hooks} as the last step of
Dave Love <fx@gnu.org>
parents:
diff changeset
784 initialization. This makes it easy for you to customize the behavior of
Dave Love <fx@gnu.org>
parents:
diff changeset
785 the mode, by setting up a hook function to override the local variable
Dave Love <fx@gnu.org>
parents:
diff changeset
786 assignments already made by the mode. But hooks are also used in other
Dave Love <fx@gnu.org>
parents:
diff changeset
787 contexts. For example, the hook @code{suspend-hook} runs just before
Dave Love <fx@gnu.org>
parents:
diff changeset
788 Emacs suspends itself (@pxref{Exiting}).
Dave Love <fx@gnu.org>
parents:
diff changeset
789
Dave Love <fx@gnu.org>
parents:
diff changeset
790 @cindex normal hook
Dave Love <fx@gnu.org>
parents:
diff changeset
791 Most Emacs hooks are @dfn{normal hooks}. This means that running the
Dave Love <fx@gnu.org>
parents:
diff changeset
792 hook operates by calling all the hook functions, unconditionally, with
Dave Love <fx@gnu.org>
parents:
diff changeset
793 no arguments. We have made an effort to keep most hooks normal so that
Dave Love <fx@gnu.org>
parents:
diff changeset
794 you can use them in a uniform way. Every variable in Emacs whose name
Dave Love <fx@gnu.org>
parents:
diff changeset
795 ends in @samp{-hook} is a normal hook.
Dave Love <fx@gnu.org>
parents:
diff changeset
796
Dave Love <fx@gnu.org>
parents:
diff changeset
797 @cindex abnormal hook
Dave Love <fx@gnu.org>
parents:
diff changeset
798 There are also a few @dfn{abnormal hooks}. These variables' names end
Dave Love <fx@gnu.org>
parents:
diff changeset
799 in @samp{-hooks} or @samp{-functions}, instead of @samp{-hook}. What
Dave Love <fx@gnu.org>
parents:
diff changeset
800 makes these hooks abnormal is that there is something peculiar about the
Dave Love <fx@gnu.org>
parents:
diff changeset
801 way its functions are called---perhaps they are given arguments, or
Dave Love <fx@gnu.org>
parents:
diff changeset
802 perhaps the values they return are used in some way. For example,
45979
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 44783
diff changeset
803 @code{find-file-not-found-functions} (@pxref{Visiting}) is abnormal because
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
804 as soon as one hook function returns a non-@code{nil} value, the rest
Dave Love <fx@gnu.org>
parents:
diff changeset
805 are not called at all. The documentation of each abnormal hook variable
Dave Love <fx@gnu.org>
parents:
diff changeset
806 explains in detail what is peculiar about it.
Dave Love <fx@gnu.org>
parents:
diff changeset
807
57156
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
808 You can set a hook variable with @code{setq} like any other Lisp
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
809 variable, but the recommended way to add a hook function to a hook
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
810 (either normal or abnormal) is by calling @code{add-hook}. You can
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
811 specify any valid Lisp function as the hook function, provided it can
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
812 handle the proper number of arguments (zero arguments, in the case of
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
813 a normal hook). Of course, not every Lisp function is @emph{useful}
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
814 in any particular hook.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
815
Dave Love <fx@gnu.org>
parents:
diff changeset
816 For example, here's how to set up a hook to turn on Auto Fill mode
Dave Love <fx@gnu.org>
parents:
diff changeset
817 when entering Text mode and other modes based on Text mode:
Dave Love <fx@gnu.org>
parents:
diff changeset
818
Dave Love <fx@gnu.org>
parents:
diff changeset
819 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
820 (add-hook 'text-mode-hook 'turn-on-auto-fill)
Dave Love <fx@gnu.org>
parents:
diff changeset
821 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
822
Dave Love <fx@gnu.org>
parents:
diff changeset
823 The next example shows how to use a hook to customize the indentation
Dave Love <fx@gnu.org>
parents:
diff changeset
824 of C code. (People often have strong personal preferences for one
Dave Love <fx@gnu.org>
parents:
diff changeset
825 format compared to another.) Here the hook function is an anonymous
Dave Love <fx@gnu.org>
parents:
diff changeset
826 lambda expression.
Dave Love <fx@gnu.org>
parents:
diff changeset
827
Dave Love <fx@gnu.org>
parents:
diff changeset
828 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
829 @group
Dave Love <fx@gnu.org>
parents:
diff changeset
830 (setq my-c-style
Dave Love <fx@gnu.org>
parents:
diff changeset
831 '((c-comment-only-line-offset . 4)
Dave Love <fx@gnu.org>
parents:
diff changeset
832 @end group
Dave Love <fx@gnu.org>
parents:
diff changeset
833 @group
Dave Love <fx@gnu.org>
parents:
diff changeset
834 (c-cleanup-list . (scope-operator
Dave Love <fx@gnu.org>
parents:
diff changeset
835 empty-defun-braces
Dave Love <fx@gnu.org>
parents:
diff changeset
836 defun-close-semi))
Dave Love <fx@gnu.org>
parents:
diff changeset
837 @end group
Dave Love <fx@gnu.org>
parents:
diff changeset
838 @group
Dave Love <fx@gnu.org>
parents:
diff changeset
839 (c-offsets-alist . ((arglist-close . c-lineup-arglist)
Dave Love <fx@gnu.org>
parents:
diff changeset
840 (substatement-open . 0)))))
Dave Love <fx@gnu.org>
parents:
diff changeset
841 @end group
Dave Love <fx@gnu.org>
parents:
diff changeset
842
Dave Love <fx@gnu.org>
parents:
diff changeset
843 @group
Dave Love <fx@gnu.org>
parents:
diff changeset
844 (add-hook 'c-mode-common-hook
36593
4567e1729217 custom-buffer-done-function <- Custom-buffer-done
Dave Love <fx@gnu.org>
parents: 36292
diff changeset
845 '(lambda ()
4567e1729217 custom-buffer-done-function <- Custom-buffer-done
Dave Love <fx@gnu.org>
parents: 36292
diff changeset
846 (c-add-style "my-style" my-c-style t)))
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
847 @end group
Dave Love <fx@gnu.org>
parents:
diff changeset
848 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
849
Dave Love <fx@gnu.org>
parents:
diff changeset
850 It is best to design your hook functions so that the order in which
Dave Love <fx@gnu.org>
parents:
diff changeset
851 they are executed does not matter. Any dependence on the order is
Dave Love <fx@gnu.org>
parents:
diff changeset
852 ``asking for trouble.'' However, the order is predictable: the most
Dave Love <fx@gnu.org>
parents:
diff changeset
853 recently added hook functions are executed first.
Dave Love <fx@gnu.org>
parents:
diff changeset
854
57156
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
855 If you play with adding various different versions of a hook
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
856 function by calling @code{add-hook} over and over, remember that all
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
857 the versions you added will remain in the hook variable together.
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
858 To clear them out, you can do @code{(setq @var{hook-variable} nil)}.
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
859
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
860 @node Locals
Dave Love <fx@gnu.org>
parents:
diff changeset
861 @subsection Local Variables
Dave Love <fx@gnu.org>
parents:
diff changeset
862
Dave Love <fx@gnu.org>
parents:
diff changeset
863 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
864 @item M-x make-local-variable @key{RET} @var{var} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
865 Make variable @var{var} have a local value in the current buffer.
Dave Love <fx@gnu.org>
parents:
diff changeset
866 @item M-x kill-local-variable @key{RET} @var{var} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
867 Make variable @var{var} use its global value in the current buffer.
Dave Love <fx@gnu.org>
parents:
diff changeset
868 @item M-x make-variable-buffer-local @key{RET} @var{var} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
869 Mark variable @var{var} so that setting it will make it local to the
Dave Love <fx@gnu.org>
parents:
diff changeset
870 buffer that is current at that time.
Dave Love <fx@gnu.org>
parents:
diff changeset
871 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
872
Dave Love <fx@gnu.org>
parents:
diff changeset
873 @cindex local variables
Dave Love <fx@gnu.org>
parents:
diff changeset
874 Almost any variable can be made @dfn{local} to a specific Emacs
Dave Love <fx@gnu.org>
parents:
diff changeset
875 buffer. This means that its value in that buffer is independent of its
Dave Love <fx@gnu.org>
parents:
diff changeset
876 value in other buffers. A few variables are always local in every
Dave Love <fx@gnu.org>
parents:
diff changeset
877 buffer. Every other Emacs variable has a @dfn{global} value which is in
Dave Love <fx@gnu.org>
parents:
diff changeset
878 effect in all buffers that have not made the variable local.
Dave Love <fx@gnu.org>
parents:
diff changeset
879
Dave Love <fx@gnu.org>
parents:
diff changeset
880 @findex make-local-variable
Dave Love <fx@gnu.org>
parents:
diff changeset
881 @kbd{M-x make-local-variable} reads the name of a variable and makes it
Dave Love <fx@gnu.org>
parents:
diff changeset
882 local to the current buffer. Further changes in this buffer will not
Dave Love <fx@gnu.org>
parents:
diff changeset
883 affect others, and further changes in the global value will not affect this
Dave Love <fx@gnu.org>
parents:
diff changeset
884 buffer.
Dave Love <fx@gnu.org>
parents:
diff changeset
885
Dave Love <fx@gnu.org>
parents:
diff changeset
886 @findex make-variable-buffer-local
Dave Love <fx@gnu.org>
parents:
diff changeset
887 @cindex per-buffer variables
Dave Love <fx@gnu.org>
parents:
diff changeset
888 @kbd{M-x make-variable-buffer-local} reads the name of a variable and
Dave Love <fx@gnu.org>
parents:
diff changeset
889 changes the future behavior of the variable so that it will become local
Dave Love <fx@gnu.org>
parents:
diff changeset
890 automatically when it is set. More precisely, once a variable has been
Dave Love <fx@gnu.org>
parents:
diff changeset
891 marked in this way, the usual ways of setting the variable automatically
Dave Love <fx@gnu.org>
parents:
diff changeset
892 do @code{make-local-variable} first. We call such variables
Dave Love <fx@gnu.org>
parents:
diff changeset
893 @dfn{per-buffer} variables.
Dave Love <fx@gnu.org>
parents:
diff changeset
894
Dave Love <fx@gnu.org>
parents:
diff changeset
895 Major modes (@pxref{Major Modes}) always make variables local to the
Dave Love <fx@gnu.org>
parents:
diff changeset
896 buffer before setting the variables. This is why changing major modes
Dave Love <fx@gnu.org>
parents:
diff changeset
897 in one buffer has no effect on other buffers. Minor modes also work by
Dave Love <fx@gnu.org>
parents:
diff changeset
898 setting variables---normally, each minor mode has one controlling
Dave Love <fx@gnu.org>
parents:
diff changeset
899 variable which is non-@code{nil} when the mode is enabled (@pxref{Minor
Dave Love <fx@gnu.org>
parents:
diff changeset
900 Modes}). For most minor modes, the controlling variable is per buffer.
Dave Love <fx@gnu.org>
parents:
diff changeset
901
Dave Love <fx@gnu.org>
parents:
diff changeset
902 Emacs contains a number of variables that are always per-buffer.
Dave Love <fx@gnu.org>
parents:
diff changeset
903 These include @code{abbrev-mode}, @code{auto-fill-function},
Dave Love <fx@gnu.org>
parents:
diff changeset
904 @code{case-fold-search}, @code{comment-column}, @code{ctl-arrow},
Dave Love <fx@gnu.org>
parents:
diff changeset
905 @code{fill-column}, @code{fill-prefix}, @code{indent-tabs-mode},
Dave Love <fx@gnu.org>
parents:
diff changeset
906 @code{left-margin}, @code{mode-line-format}, @code{overwrite-mode},
Dave Love <fx@gnu.org>
parents:
diff changeset
907 @code{selective-display-ellipses}, @code{selective-display},
Dave Love <fx@gnu.org>
parents:
diff changeset
908 @code{tab-width}, and @code{truncate-lines}. Some other variables are
Dave Love <fx@gnu.org>
parents:
diff changeset
909 always local in every buffer, but they are used for internal
Dave Love <fx@gnu.org>
parents:
diff changeset
910 purposes.@refill
Dave Love <fx@gnu.org>
parents:
diff changeset
911
Dave Love <fx@gnu.org>
parents:
diff changeset
912 A few variables cannot be local to a buffer because they are always
Dave Love <fx@gnu.org>
parents:
diff changeset
913 local to each display instead (@pxref{Multiple Displays}). If you try to
Dave Love <fx@gnu.org>
parents:
diff changeset
914 make one of these variables buffer-local, you'll get an error message.
Dave Love <fx@gnu.org>
parents:
diff changeset
915
Dave Love <fx@gnu.org>
parents:
diff changeset
916 @findex kill-local-variable
Dave Love <fx@gnu.org>
parents:
diff changeset
917 @kbd{M-x kill-local-variable} reads the name of a variable and makes
Dave Love <fx@gnu.org>
parents:
diff changeset
918 it cease to be local to the current buffer. The global value of the
Dave Love <fx@gnu.org>
parents:
diff changeset
919 variable henceforth is in effect in this buffer. Setting the major mode
Dave Love <fx@gnu.org>
parents:
diff changeset
920 kills all the local variables of the buffer except for a few variables
Dave Love <fx@gnu.org>
parents:
diff changeset
921 specially marked as @dfn{permanent locals}.
Dave Love <fx@gnu.org>
parents:
diff changeset
922
Dave Love <fx@gnu.org>
parents:
diff changeset
923 @findex setq-default
Dave Love <fx@gnu.org>
parents:
diff changeset
924 To set the global value of a variable, regardless of whether the
Dave Love <fx@gnu.org>
parents:
diff changeset
925 variable has a local value in the current buffer, you can use the Lisp
Dave Love <fx@gnu.org>
parents:
diff changeset
926 construct @code{setq-default}. This construct is used just like
Dave Love <fx@gnu.org>
parents:
diff changeset
927 @code{setq}, but it sets variables' global values instead of their local
Dave Love <fx@gnu.org>
parents:
diff changeset
928 values (if any). When the current buffer does have a local value, the
Dave Love <fx@gnu.org>
parents:
diff changeset
929 new global value may not be visible until you switch to another buffer.
Dave Love <fx@gnu.org>
parents:
diff changeset
930 Here is an example:
Dave Love <fx@gnu.org>
parents:
diff changeset
931
Dave Love <fx@gnu.org>
parents:
diff changeset
932 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
933 (setq-default fill-column 75)
Dave Love <fx@gnu.org>
parents:
diff changeset
934 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
935
Dave Love <fx@gnu.org>
parents:
diff changeset
936 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
937 @code{setq-default} is the only way to set the global value of a variable
Dave Love <fx@gnu.org>
parents:
diff changeset
938 that has been marked with @code{make-variable-buffer-local}.
Dave Love <fx@gnu.org>
parents:
diff changeset
939
Dave Love <fx@gnu.org>
parents:
diff changeset
940 @findex default-value
Dave Love <fx@gnu.org>
parents:
diff changeset
941 Lisp programs can use @code{default-value} to look at a variable's
Dave Love <fx@gnu.org>
parents:
diff changeset
942 default value. This function takes a symbol as argument and returns its
Dave Love <fx@gnu.org>
parents:
diff changeset
943 default value. The argument is evaluated; usually you must quote it
Dave Love <fx@gnu.org>
parents:
diff changeset
944 explicitly. For example, here's how to obtain the default value of
Dave Love <fx@gnu.org>
parents:
diff changeset
945 @code{fill-column}:
Dave Love <fx@gnu.org>
parents:
diff changeset
946
Dave Love <fx@gnu.org>
parents:
diff changeset
947 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
948 (default-value 'fill-column)
Dave Love <fx@gnu.org>
parents:
diff changeset
949 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
950
Dave Love <fx@gnu.org>
parents:
diff changeset
951 @node File Variables
Dave Love <fx@gnu.org>
parents:
diff changeset
952 @subsection Local Variables in Files
Dave Love <fx@gnu.org>
parents:
diff changeset
953 @cindex local variables in files
Dave Love <fx@gnu.org>
parents:
diff changeset
954 @cindex file local variables
Dave Love <fx@gnu.org>
parents:
diff changeset
955
Dave Love <fx@gnu.org>
parents:
diff changeset
956 A file can specify local variable values for use when you edit the
Dave Love <fx@gnu.org>
parents:
diff changeset
957 file with Emacs. Visiting the file checks for local variable
Dave Love <fx@gnu.org>
parents:
diff changeset
958 specifications; it automatically makes these variables local to the
Dave Love <fx@gnu.org>
parents:
diff changeset
959 buffer, and sets them to the values specified in the file.
Dave Love <fx@gnu.org>
parents:
diff changeset
960
Dave Love <fx@gnu.org>
parents:
diff changeset
961 There are two ways to specify local variable values: in the first
Dave Love <fx@gnu.org>
parents:
diff changeset
962 line, or with a local variables list. Here's how to specify them in the
Dave Love <fx@gnu.org>
parents:
diff changeset
963 first line:
Dave Love <fx@gnu.org>
parents:
diff changeset
964
Dave Love <fx@gnu.org>
parents:
diff changeset
965 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
966 -*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*-
Dave Love <fx@gnu.org>
parents:
diff changeset
967 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
968
Dave Love <fx@gnu.org>
parents:
diff changeset
969 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
970 You can specify any number of variables/value pairs in this way, each
Dave Love <fx@gnu.org>
parents:
diff changeset
971 pair with a colon and semicolon as shown above. @code{mode:
Dave Love <fx@gnu.org>
parents:
diff changeset
972 @var{modename};} specifies the major mode; this should come first in the
Dave Love <fx@gnu.org>
parents:
diff changeset
973 line. The @var{value}s are not evaluated; they are used literally.
Dave Love <fx@gnu.org>
parents:
diff changeset
974 Here is an example that specifies Lisp mode and sets two variables with
Dave Love <fx@gnu.org>
parents:
diff changeset
975 numeric values:
Dave Love <fx@gnu.org>
parents:
diff changeset
976
Dave Love <fx@gnu.org>
parents:
diff changeset
977 @smallexample
36632
1bfc2fad762a (File Variables): Fix a typo.
Eli Zaretskii <eliz@gnu.org>
parents: 36593
diff changeset
978 ;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*-
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
979 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
980
Dave Love <fx@gnu.org>
parents:
diff changeset
981 You can also specify the coding system for a file in this way: just
Dave Love <fx@gnu.org>
parents:
diff changeset
982 specify a value for the ``variable'' named @code{coding}. The ``value''
Dave Love <fx@gnu.org>
parents:
diff changeset
983 must be a coding system name that Emacs recognizes. @xref{Coding
58624
a322009ca3d0 * custom.texi (File Variables): Add `unibyte' and make it more
Reiner Steib <Reiner.Steib@gmx.de>
parents: 57156
diff changeset
984 Systems}. @w{@samp{unibyte: t}} specifies unibyte loading for a
a322009ca3d0 * custom.texi (File Variables): Add `unibyte' and make it more
Reiner Steib <Reiner.Steib@gmx.de>
parents: 57156
diff changeset
985 particular Lisp file. @xref{Enabling Multibyte}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
986
34116
1c497211a58d Docment that `eval' can be used with local variables in the first
Eli Zaretskii <eliz@gnu.org>
parents: 31075
diff changeset
987 The @code{eval} pseudo-variable, described below, can be specified in
1c497211a58d Docment that `eval' can be used with local variables in the first
Eli Zaretskii <eliz@gnu.org>
parents: 31075
diff changeset
988 the first line as well.
1c497211a58d Docment that `eval' can be used with local variables in the first
Eli Zaretskii <eliz@gnu.org>
parents: 31075
diff changeset
989
1c497211a58d Docment that `eval' can be used with local variables in the first
Eli Zaretskii <eliz@gnu.org>
parents: 31075
diff changeset
990 @cindex shell scripts, and local file variables
1c497211a58d Docment that `eval' can be used with local variables in the first
Eli Zaretskii <eliz@gnu.org>
parents: 31075
diff changeset
991 In shell scripts, the first line is used to identify the script
39263
343d48d4e64c Spelling corrections.
Richard M. Stallman <rms@gnu.org>
parents: 39161
diff changeset
992 interpreter, so you cannot put any local variables there. To accommodate
34116
1c497211a58d Docment that `eval' can be used with local variables in the first
Eli Zaretskii <eliz@gnu.org>
parents: 31075
diff changeset
993 for this, when Emacs visits a shell script, it looks for local variable
1c497211a58d Docment that `eval' can be used with local variables in the first
Eli Zaretskii <eliz@gnu.org>
parents: 31075
diff changeset
994 specifications in the @emph{second} line.
1c497211a58d Docment that `eval' can be used with local variables in the first
Eli Zaretskii <eliz@gnu.org>
parents: 31075
diff changeset
995
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
996 A @dfn{local variables list} goes near the end of the file, in the
Dave Love <fx@gnu.org>
parents:
diff changeset
997 last page. (It is often best to put it on a page by itself.) The local
Dave Love <fx@gnu.org>
parents:
diff changeset
998 variables list starts with a line containing the string @samp{Local
Dave Love <fx@gnu.org>
parents:
diff changeset
999 Variables:}, and ends with a line containing the string @samp{End:}. In
Dave Love <fx@gnu.org>
parents:
diff changeset
1000 between come the variable names and values, one set per line, as
Dave Love <fx@gnu.org>
parents:
diff changeset
1001 @samp{@var{variable}:@: @var{value}}. The @var{value}s are not
Dave Love <fx@gnu.org>
parents:
diff changeset
1002 evaluated; they are used literally. If a file has both a local
Dave Love <fx@gnu.org>
parents:
diff changeset
1003 variables list and a @samp{-*-} line, Emacs processes @emph{everything}
Dave Love <fx@gnu.org>
parents:
diff changeset
1004 in the @samp{-*-} line first, and @emph{everything} in the local
Dave Love <fx@gnu.org>
parents:
diff changeset
1005 variables list afterward.
Dave Love <fx@gnu.org>
parents:
diff changeset
1006
Dave Love <fx@gnu.org>
parents:
diff changeset
1007 Here is an example of a local variables list:
Dave Love <fx@gnu.org>
parents:
diff changeset
1008
Dave Love <fx@gnu.org>
parents:
diff changeset
1009 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
1010 ;;; Local Variables: ***
Dave Love <fx@gnu.org>
parents:
diff changeset
1011 ;;; mode:lisp ***
Dave Love <fx@gnu.org>
parents:
diff changeset
1012 ;;; comment-column:0 ***
Dave Love <fx@gnu.org>
parents:
diff changeset
1013 ;;; comment-start: ";;; " ***
Dave Love <fx@gnu.org>
parents:
diff changeset
1014 ;;; comment-end:"***" ***
Dave Love <fx@gnu.org>
parents:
diff changeset
1015 ;;; End: ***
Dave Love <fx@gnu.org>
parents:
diff changeset
1016 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
1017
Dave Love <fx@gnu.org>
parents:
diff changeset
1018 As you see, each line starts with the prefix @samp{;;; } and each line
Dave Love <fx@gnu.org>
parents:
diff changeset
1019 ends with the suffix @samp{ ***}. Emacs recognizes these as the prefix
Dave Love <fx@gnu.org>
parents:
diff changeset
1020 and suffix based on the first line of the list, by finding them
Dave Love <fx@gnu.org>
parents:
diff changeset
1021 surrounding the magic string @samp{Local Variables:}; then it
Dave Love <fx@gnu.org>
parents:
diff changeset
1022 automatically discards them from the other lines of the list.
Dave Love <fx@gnu.org>
parents:
diff changeset
1023
Dave Love <fx@gnu.org>
parents:
diff changeset
1024 The usual reason for using a prefix and/or suffix is to embed the
Dave Love <fx@gnu.org>
parents:
diff changeset
1025 local variables list in a comment, so it won't confuse other programs
Dave Love <fx@gnu.org>
parents:
diff changeset
1026 that the file is intended as input for. The example above is for a
Dave Love <fx@gnu.org>
parents:
diff changeset
1027 language where comment lines start with @samp{;;; } and end with
Dave Love <fx@gnu.org>
parents:
diff changeset
1028 @samp{***}; the local values for @code{comment-start} and
57156
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
1029 @code{comment-end} customize the rest of Emacs for this unusual
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
1030 syntax. Don't use a prefix (or a suffix) if you don't need one.
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
1031
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
1032 If you write a multi-line string value, you should put the prefix
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
1033 and suffix on each line, even lines that start or end within the
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
1034 string. They will be stripped off for processing the list. If you
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
1035 want to split a long string across multiple lines of the file, you can
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
1036 use backslash-newline, which is ignored in Lisp string constants.
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
1037 Here's an example of doing this:
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
1038
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
1039 @example
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
1040 # Local Variables:
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
1041 # compile-command: "cc foo.c -Dfoo=bar -Dhack=whatever \
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
1042 # -Dmumble=blaah"
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
1043 # End:
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
1044 @end example
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1045
58624
a322009ca3d0 * custom.texi (File Variables): Add `unibyte' and make it more
Reiner Steib <Reiner.Steib@gmx.de>
parents: 57156
diff changeset
1046 Some ``variable names'' have special meanings in a local variables
59192
f6c4c15febd7 (File Variables): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 58861
diff changeset
1047 list. Specifying the ``variable'' @code{mode} really sets the major
f6c4c15febd7 (File Variables): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 58861
diff changeset
1048 mode, while any value specified for the ``variable'' @code{eval} is
f6c4c15febd7 (File Variables): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 58861
diff changeset
1049 simply evaluated as an expression (its value is ignored). A value for
f6c4c15febd7 (File Variables): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 58861
diff changeset
1050 @code{coding} specifies the coding system for character code
f6c4c15febd7 (File Variables): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 58861
diff changeset
1051 conversion of this file, and a value of @code{t} for @code{unibyte}
f6c4c15febd7 (File Variables): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 58861
diff changeset
1052 says to visit the file in a unibyte buffer. These four ``variables''
f6c4c15febd7 (File Variables): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 58861
diff changeset
1053 are not really variables; setting them in any other context has no
f6c4c15febd7 (File Variables): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 58861
diff changeset
1054 special meaning.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1055
59192
f6c4c15febd7 (File Variables): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 58861
diff changeset
1056 @emph{If @code{mode} is used to set a major mode, it should be the
f6c4c15febd7 (File Variables): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 58861
diff changeset
1057 first ``variable'' in the list.} Otherwise, the entries that precede
f6c4c15febd7 (File Variables): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 58861
diff changeset
1058 it will usually be ignored, since most modes kill all local variables
f6c4c15febd7 (File Variables): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 58861
diff changeset
1059 as part of their initialization.
f6c4c15febd7 (File Variables): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 58861
diff changeset
1060
f6c4c15febd7 (File Variables): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 58861
diff changeset
1061 You can use the @code{mode} ``variable'' to set minor modes as well
f6c4c15febd7 (File Variables): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 58861
diff changeset
1062 as the major modes; in fact, you can use it more than once, first to
f6c4c15febd7 (File Variables): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 58861
diff changeset
1063 set the major mode and then to set minor modes which are specific to
f6c4c15febd7 (File Variables): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 58861
diff changeset
1064 particular buffers. But most minor modes should not be specified in
f6c4c15febd7 (File Variables): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 58861
diff changeset
1065 the file at all, regardless of how, because they represent user
f6c4c15febd7 (File Variables): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 58861
diff changeset
1066 preferences.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1067
Dave Love <fx@gnu.org>
parents:
diff changeset
1068 For example, you may be tempted to try to turn on Auto Fill mode with
Dave Love <fx@gnu.org>
parents:
diff changeset
1069 a local variable list. That is a mistake. The choice of Auto Fill mode
Dave Love <fx@gnu.org>
parents:
diff changeset
1070 or not is a matter of individual taste, not a matter of the contents of
Dave Love <fx@gnu.org>
parents:
diff changeset
1071 particular files. If you want to use Auto Fill, set up major mode hooks
Dave Love <fx@gnu.org>
parents:
diff changeset
1072 with your @file{.emacs} file to turn it on (when appropriate) for you
Dave Love <fx@gnu.org>
parents:
diff changeset
1073 alone (@pxref{Init File}). Don't use a local variable list to impose
Dave Love <fx@gnu.org>
parents:
diff changeset
1074 your taste on everyone.
Dave Love <fx@gnu.org>
parents:
diff changeset
1075
Dave Love <fx@gnu.org>
parents:
diff changeset
1076 The start of the local variables list must be no more than 3000
Dave Love <fx@gnu.org>
parents:
diff changeset
1077 characters from the end of the file, and must be in the last page if the
Dave Love <fx@gnu.org>
parents:
diff changeset
1078 file is divided into pages. Otherwise, Emacs will not notice it is
Dave Love <fx@gnu.org>
parents:
diff changeset
1079 there. The purpose of this rule is so that a stray @samp{Local
Dave Love <fx@gnu.org>
parents:
diff changeset
1080 Variables:}@: not in the last page does not confuse Emacs, and so that
Dave Love <fx@gnu.org>
parents:
diff changeset
1081 visiting a long file that is all one page and has no local variables
Dave Love <fx@gnu.org>
parents:
diff changeset
1082 list need not take the time to search the whole file.
Dave Love <fx@gnu.org>
parents:
diff changeset
1083
Dave Love <fx@gnu.org>
parents:
diff changeset
1084 Use the command @code{normal-mode} to reset the local variables and
Dave Love <fx@gnu.org>
parents:
diff changeset
1085 major mode of a buffer according to the file name and contents,
Dave Love <fx@gnu.org>
parents:
diff changeset
1086 including the local variables list if any. @xref{Choosing Modes}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1087
Dave Love <fx@gnu.org>
parents:
diff changeset
1088 @findex enable-local-variables
Dave Love <fx@gnu.org>
parents:
diff changeset
1089 The variable @code{enable-local-variables} controls whether to process
Dave Love <fx@gnu.org>
parents:
diff changeset
1090 local variables in files, and thus gives you a chance to override them.
Dave Love <fx@gnu.org>
parents:
diff changeset
1091 Its default value is @code{t}, which means do process local variables in
Dave Love <fx@gnu.org>
parents:
diff changeset
1092 files. If you set the value to @code{nil}, Emacs simply ignores local
Dave Love <fx@gnu.org>
parents:
diff changeset
1093 variables in files. Any other value says to query you about each file
Dave Love <fx@gnu.org>
parents:
diff changeset
1094 that has local variables, showing you the local variable specifications
Dave Love <fx@gnu.org>
parents:
diff changeset
1095 so you can judge.
Dave Love <fx@gnu.org>
parents:
diff changeset
1096
Dave Love <fx@gnu.org>
parents:
diff changeset
1097 @findex enable-local-eval
Dave Love <fx@gnu.org>
parents:
diff changeset
1098 The @code{eval} ``variable,'' and certain actual variables, create a
Dave Love <fx@gnu.org>
parents:
diff changeset
1099 special risk; when you visit someone else's file, local variable
Dave Love <fx@gnu.org>
parents:
diff changeset
1100 specifications for these could affect your Emacs in arbitrary ways.
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
1101 Therefore, the variable @code{enable-local-eval} controls whether Emacs
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1102 processes @code{eval} variables, as well variables with names that end
Dave Love <fx@gnu.org>
parents:
diff changeset
1103 in @samp{-hook}, @samp{-hooks}, @samp{-function} or @samp{-functions},
59800
4a45f5c001b2 (Easy Customization): Defn of "User Option" now
Richard M. Stallman <rms@gnu.org>
parents: 59353
diff changeset
1104 and certain other variables. The three possibilities for the variable's
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1105 value are @code{t}, @code{nil}, and anything else, just as for
Dave Love <fx@gnu.org>
parents:
diff changeset
1106 @code{enable-local-variables}. The default is @code{maybe}, which is
Dave Love <fx@gnu.org>
parents:
diff changeset
1107 neither @code{t} nor @code{nil}, so normally Emacs does ask for
Dave Love <fx@gnu.org>
parents:
diff changeset
1108 confirmation about file settings for these variables.
Dave Love <fx@gnu.org>
parents:
diff changeset
1109
54723
326aa7651bd6 (File Variables): Add safe-local-eval-forms.
Kim F. Storm <storm@cua.dk>
parents: 52979
diff changeset
1110 @findex safe-local-eval-forms
326aa7651bd6 (File Variables): Add safe-local-eval-forms.
Kim F. Storm <storm@cua.dk>
parents: 52979
diff changeset
1111 The @code{safe-local-eval-forms} is a customizable list of eval
326aa7651bd6 (File Variables): Add safe-local-eval-forms.
Kim F. Storm <storm@cua.dk>
parents: 52979
diff changeset
1112 forms which are safe to eval, so Emacs should not ask for
326aa7651bd6 (File Variables): Add safe-local-eval-forms.
Kim F. Storm <storm@cua.dk>
parents: 52979
diff changeset
1113 confirmation to evaluate these forms, even if
326aa7651bd6 (File Variables): Add safe-local-eval-forms.
Kim F. Storm <storm@cua.dk>
parents: 52979
diff changeset
1114 @code{enable-local-variables} says to ask for confirmation in general.
326aa7651bd6 (File Variables): Add safe-local-eval-forms.
Kim F. Storm <storm@cua.dk>
parents: 52979
diff changeset
1115
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1116 @node Key Bindings
Dave Love <fx@gnu.org>
parents:
diff changeset
1117 @section Customizing Key Bindings
Dave Love <fx@gnu.org>
parents:
diff changeset
1118 @cindex key bindings
Dave Love <fx@gnu.org>
parents:
diff changeset
1119
Dave Love <fx@gnu.org>
parents:
diff changeset
1120 This section describes @dfn{key bindings}, which map keys to commands,
Dave Love <fx@gnu.org>
parents:
diff changeset
1121 and @dfn{keymaps}, which record key bindings. It also explains how
Dave Love <fx@gnu.org>
parents:
diff changeset
1122 to customize key bindings.
Dave Love <fx@gnu.org>
parents:
diff changeset
1123
Dave Love <fx@gnu.org>
parents:
diff changeset
1124 Recall that a command is a Lisp function whose definition provides for
Dave Love <fx@gnu.org>
parents:
diff changeset
1125 interactive use. Like every Lisp function, a command has a function
Dave Love <fx@gnu.org>
parents:
diff changeset
1126 name which usually consists of lower-case letters and hyphens.
Dave Love <fx@gnu.org>
parents:
diff changeset
1127
Dave Love <fx@gnu.org>
parents:
diff changeset
1128 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
1129 * Keymaps:: Generalities. The global keymap.
Dave Love <fx@gnu.org>
parents:
diff changeset
1130 * Prefix Keymaps:: Keymaps for prefix keys.
Dave Love <fx@gnu.org>
parents:
diff changeset
1131 * Local Keymaps:: Major and minor modes have their own keymaps.
Dave Love <fx@gnu.org>
parents:
diff changeset
1132 * Minibuffer Maps:: The minibuffer uses its own local keymaps.
Dave Love <fx@gnu.org>
parents:
diff changeset
1133 * Rebinding:: How to redefine one key's meaning conveniently.
Dave Love <fx@gnu.org>
parents:
diff changeset
1134 * Init Rebinding:: Rebinding keys with your init file, @file{.emacs}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1135 * Function Keys:: Rebinding terminal function keys.
Dave Love <fx@gnu.org>
parents:
diff changeset
1136 * Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on.
52979
3649390c0f91 Replace @sc{ascii} and ASCII with @acronym{ASCII}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
1137 * Non-ASCII Rebinding:: Rebinding non-@acronym{ASCII} characters such as Latin-1.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1138 * Mouse Buttons:: Rebinding mouse buttons in Emacs.
Dave Love <fx@gnu.org>
parents:
diff changeset
1139 * Disabling:: Disabling a command means confirmation is required
Dave Love <fx@gnu.org>
parents:
diff changeset
1140 before it can be executed. This is done to protect
Dave Love <fx@gnu.org>
parents:
diff changeset
1141 beginners from surprises.
Dave Love <fx@gnu.org>
parents:
diff changeset
1142 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
1143
Dave Love <fx@gnu.org>
parents:
diff changeset
1144 @node Keymaps
Dave Love <fx@gnu.org>
parents:
diff changeset
1145 @subsection Keymaps
Dave Love <fx@gnu.org>
parents:
diff changeset
1146 @cindex keymap
Dave Love <fx@gnu.org>
parents:
diff changeset
1147
Dave Love <fx@gnu.org>
parents:
diff changeset
1148 The bindings between key sequences and command functions are recorded
Dave Love <fx@gnu.org>
parents:
diff changeset
1149 in data structures called @dfn{keymaps}. Emacs has many of these, each
Dave Love <fx@gnu.org>
parents:
diff changeset
1150 used on particular occasions.
Dave Love <fx@gnu.org>
parents:
diff changeset
1151
Dave Love <fx@gnu.org>
parents:
diff changeset
1152 Recall that a @dfn{key sequence} (@dfn{key}, for short) is a sequence
Dave Love <fx@gnu.org>
parents:
diff changeset
1153 of @dfn{input events} that have a meaning as a unit. Input events
Dave Love <fx@gnu.org>
parents:
diff changeset
1154 include characters, function keys and mouse buttons---all the inputs
Dave Love <fx@gnu.org>
parents:
diff changeset
1155 that you can send to the computer with your terminal. A key sequence
Dave Love <fx@gnu.org>
parents:
diff changeset
1156 gets its meaning from its @dfn{binding}, which says what command it
Dave Love <fx@gnu.org>
parents:
diff changeset
1157 runs. The function of keymaps is to record these bindings.
Dave Love <fx@gnu.org>
parents:
diff changeset
1158
Dave Love <fx@gnu.org>
parents:
diff changeset
1159 @cindex global keymap
Dave Love <fx@gnu.org>
parents:
diff changeset
1160 The @dfn{global} keymap is the most important keymap because it is
Dave Love <fx@gnu.org>
parents:
diff changeset
1161 always in effect. The global keymap defines keys for Fundamental mode;
Dave Love <fx@gnu.org>
parents:
diff changeset
1162 most of these definitions are common to most or all major modes. Each
Dave Love <fx@gnu.org>
parents:
diff changeset
1163 major or minor mode can have its own keymap which overrides the global
Dave Love <fx@gnu.org>
parents:
diff changeset
1164 definitions of some keys.
Dave Love <fx@gnu.org>
parents:
diff changeset
1165
Dave Love <fx@gnu.org>
parents:
diff changeset
1166 For example, a self-inserting character such as @kbd{g} is
Dave Love <fx@gnu.org>
parents:
diff changeset
1167 self-inserting because the global keymap binds it to the command
Dave Love <fx@gnu.org>
parents:
diff changeset
1168 @code{self-insert-command}. The standard Emacs editing characters such
Dave Love <fx@gnu.org>
parents:
diff changeset
1169 as @kbd{C-a} also get their standard meanings from the global keymap.
Dave Love <fx@gnu.org>
parents:
diff changeset
1170 Commands to rebind keys, such as @kbd{M-x global-set-key}, actually work
Dave Love <fx@gnu.org>
parents:
diff changeset
1171 by storing the new binding in the proper place in the global map.
Dave Love <fx@gnu.org>
parents:
diff changeset
1172 @xref{Rebinding}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1173
Dave Love <fx@gnu.org>
parents:
diff changeset
1174 Meta characters work differently; Emacs translates each Meta
Dave Love <fx@gnu.org>
parents:
diff changeset
1175 character into a pair of characters starting with @key{ESC}. When you
Dave Love <fx@gnu.org>
parents:
diff changeset
1176 type the character @kbd{M-a} in a key sequence, Emacs replaces it with
Dave Love <fx@gnu.org>
parents:
diff changeset
1177 @kbd{@key{ESC} a}. A meta key comes in as a single input event, but
Dave Love <fx@gnu.org>
parents:
diff changeset
1178 becomes two events for purposes of key bindings. The reason for this is
Dave Love <fx@gnu.org>
parents:
diff changeset
1179 historical, and we might change it someday.
Dave Love <fx@gnu.org>
parents:
diff changeset
1180
Dave Love <fx@gnu.org>
parents:
diff changeset
1181 @cindex function key
Dave Love <fx@gnu.org>
parents:
diff changeset
1182 Most modern keyboards have function keys as well as character keys.
Dave Love <fx@gnu.org>
parents:
diff changeset
1183 Function keys send input events just as character keys do, and keymaps
Dave Love <fx@gnu.org>
parents:
diff changeset
1184 can have bindings for them.
Dave Love <fx@gnu.org>
parents:
diff changeset
1185
59949
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1186 On text terminals, typing a function key actually sends the computer a
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1187 sequence of characters; the precise details of the sequence depends on
Dave Love <fx@gnu.org>
parents:
diff changeset
1188 which function key and on the model of terminal you are using. (Often
Dave Love <fx@gnu.org>
parents:
diff changeset
1189 the sequence starts with @kbd{@key{ESC} [}.) If Emacs understands your
Dave Love <fx@gnu.org>
parents:
diff changeset
1190 terminal type properly, it recognizes the character sequences forming
Dave Love <fx@gnu.org>
parents:
diff changeset
1191 function keys wherever they occur in a key sequence (not just at the
Dave Love <fx@gnu.org>
parents:
diff changeset
1192 beginning). Thus, for most purposes, you can pretend the function keys
Dave Love <fx@gnu.org>
parents:
diff changeset
1193 reach Emacs directly and ignore their encoding as character sequences.
Dave Love <fx@gnu.org>
parents:
diff changeset
1194
Dave Love <fx@gnu.org>
parents:
diff changeset
1195 @cindex mouse
Dave Love <fx@gnu.org>
parents:
diff changeset
1196 Mouse buttons also produce input events. These events come with other
Dave Love <fx@gnu.org>
parents:
diff changeset
1197 data---the window and position where you pressed or released the button,
Dave Love <fx@gnu.org>
parents:
diff changeset
1198 and a time stamp. But only the choice of button matters for key
Dave Love <fx@gnu.org>
parents:
diff changeset
1199 bindings; the other data matters only if a command looks at it.
Dave Love <fx@gnu.org>
parents:
diff changeset
1200 (Commands designed for mouse invocation usually do look at the other
Dave Love <fx@gnu.org>
parents:
diff changeset
1201 data.)
Dave Love <fx@gnu.org>
parents:
diff changeset
1202
Dave Love <fx@gnu.org>
parents:
diff changeset
1203 A keymap records definitions for single events. Interpreting a key
Dave Love <fx@gnu.org>
parents:
diff changeset
1204 sequence of multiple events involves a chain of keymaps. The first
Dave Love <fx@gnu.org>
parents:
diff changeset
1205 keymap gives a definition for the first event; this definition is
Dave Love <fx@gnu.org>
parents:
diff changeset
1206 another keymap, which is used to look up the second event in the
Dave Love <fx@gnu.org>
parents:
diff changeset
1207 sequence, and so on.
Dave Love <fx@gnu.org>
parents:
diff changeset
1208
Dave Love <fx@gnu.org>
parents:
diff changeset
1209 Key sequences can mix function keys and characters. For example,
Dave Love <fx@gnu.org>
parents:
diff changeset
1210 @kbd{C-x @key{SELECT}} is meaningful. If you make @key{SELECT} a prefix
Dave Love <fx@gnu.org>
parents:
diff changeset
1211 key, then @kbd{@key{SELECT} C-n} makes sense. You can even mix mouse
Dave Love <fx@gnu.org>
parents:
diff changeset
1212 events with keyboard events, but we recommend against it, because such
37419
201fa171a6e2 Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents: 37354
diff changeset
1213 key sequences are inconvenient to use.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1214
37419
201fa171a6e2 Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents: 37354
diff changeset
1215 As a user, you can redefine any key; but it is usually best to stick
44783
c00838d6756f Explain C-c LETTER better.
Richard M. Stallman <rms@gnu.org>
parents: 44278
diff changeset
1216 to key sequences that consist of @kbd{C-c} followed by a letter (upper
c00838d6756f Explain C-c LETTER better.
Richard M. Stallman <rms@gnu.org>
parents: 44278
diff changeset
1217 or lower case). These keys are ``reserved for users,'' so they won't
c00838d6756f Explain C-c LETTER better.
Richard M. Stallman <rms@gnu.org>
parents: 44278
diff changeset
1218 conflict with any properly designed Emacs extension. The function
c00838d6756f Explain C-c LETTER better.
Richard M. Stallman <rms@gnu.org>
parents: 44278
diff changeset
1219 keys @key{F5} through @key{F9} are also reserved for users. If you
c00838d6756f Explain C-c LETTER better.
Richard M. Stallman <rms@gnu.org>
parents: 44278
diff changeset
1220 redefine some other key, your definition may be overridden by certain
c00838d6756f Explain C-c LETTER better.
Richard M. Stallman <rms@gnu.org>
parents: 44278
diff changeset
1221 extensions or major modes which redefine the same key.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1222
Dave Love <fx@gnu.org>
parents:
diff changeset
1223 @node Prefix Keymaps
Dave Love <fx@gnu.org>
parents:
diff changeset
1224 @subsection Prefix Keymaps
Dave Love <fx@gnu.org>
parents:
diff changeset
1225
Dave Love <fx@gnu.org>
parents:
diff changeset
1226 A prefix key such as @kbd{C-x} or @key{ESC} has its own keymap,
Dave Love <fx@gnu.org>
parents:
diff changeset
1227 which holds the definition for the event that immediately follows
Dave Love <fx@gnu.org>
parents:
diff changeset
1228 that prefix.
Dave Love <fx@gnu.org>
parents:
diff changeset
1229
Dave Love <fx@gnu.org>
parents:
diff changeset
1230 The definition of a prefix key is usually the keymap to use for
Dave Love <fx@gnu.org>
parents:
diff changeset
1231 looking up the following event. The definition can also be a Lisp
Dave Love <fx@gnu.org>
parents:
diff changeset
1232 symbol whose function definition is the following keymap; the effect is
Dave Love <fx@gnu.org>
parents:
diff changeset
1233 the same, but it provides a command name for the prefix key that can be
Dave Love <fx@gnu.org>
parents:
diff changeset
1234 used as a description of what the prefix key is for. Thus, the binding
Dave Love <fx@gnu.org>
parents:
diff changeset
1235 of @kbd{C-x} is the symbol @code{Ctl-X-Prefix}, whose function
Dave Love <fx@gnu.org>
parents:
diff changeset
1236 definition is the keymap for @kbd{C-x} commands. The definitions of
Dave Love <fx@gnu.org>
parents:
diff changeset
1237 @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix keys appear in
Dave Love <fx@gnu.org>
parents:
diff changeset
1238 the global map, so these prefix keys are always available.
Dave Love <fx@gnu.org>
parents:
diff changeset
1239
Dave Love <fx@gnu.org>
parents:
diff changeset
1240 Aside from ordinary prefix keys, there is a fictitious ``prefix key''
Dave Love <fx@gnu.org>
parents:
diff changeset
1241 which represents the menu bar; see @ref{Menu Bar,,,elisp, The Emacs Lisp
Dave Love <fx@gnu.org>
parents:
diff changeset
1242 Reference Manual}, for special information about menu bar key bindings.
Dave Love <fx@gnu.org>
parents:
diff changeset
1243 Mouse button events that invoke pop-up menus are also prefix keys; see
Dave Love <fx@gnu.org>
parents:
diff changeset
1244 @ref{Menu Keymaps,,,elisp, The Emacs Lisp Reference Manual}, for more
Dave Love <fx@gnu.org>
parents:
diff changeset
1245 details.
Dave Love <fx@gnu.org>
parents:
diff changeset
1246
Dave Love <fx@gnu.org>
parents:
diff changeset
1247 Some prefix keymaps are stored in variables with names:
Dave Love <fx@gnu.org>
parents:
diff changeset
1248
Dave Love <fx@gnu.org>
parents:
diff changeset
1249 @itemize @bullet
Dave Love <fx@gnu.org>
parents:
diff changeset
1250 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
1251 @vindex ctl-x-map
Dave Love <fx@gnu.org>
parents:
diff changeset
1252 @code{ctl-x-map} is the variable name for the map used for characters that
Dave Love <fx@gnu.org>
parents:
diff changeset
1253 follow @kbd{C-x}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1254 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
1255 @vindex help-map
Dave Love <fx@gnu.org>
parents:
diff changeset
1256 @code{help-map} is for characters that follow @kbd{C-h}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1257 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
1258 @vindex esc-map
Dave Love <fx@gnu.org>
parents:
diff changeset
1259 @code{esc-map} is for characters that follow @key{ESC}. Thus, all Meta
Dave Love <fx@gnu.org>
parents:
diff changeset
1260 characters are actually defined by this map.
Dave Love <fx@gnu.org>
parents:
diff changeset
1261 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
1262 @vindex ctl-x-4-map
Dave Love <fx@gnu.org>
parents:
diff changeset
1263 @code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1264 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
1265 @vindex mode-specific-map
Dave Love <fx@gnu.org>
parents:
diff changeset
1266 @code{mode-specific-map} is for characters that follow @kbd{C-c}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1267 @end itemize
Dave Love <fx@gnu.org>
parents:
diff changeset
1268
Dave Love <fx@gnu.org>
parents:
diff changeset
1269 @node Local Keymaps
Dave Love <fx@gnu.org>
parents:
diff changeset
1270 @subsection Local Keymaps
Dave Love <fx@gnu.org>
parents:
diff changeset
1271
Dave Love <fx@gnu.org>
parents:
diff changeset
1272 @cindex local keymap
Dave Love <fx@gnu.org>
parents:
diff changeset
1273 So far we have explained the ins and outs of the global map. Major
Dave Love <fx@gnu.org>
parents:
diff changeset
1274 modes customize Emacs by providing their own key bindings in @dfn{local
Dave Love <fx@gnu.org>
parents:
diff changeset
1275 keymaps}. For example, C mode overrides @key{TAB} to make it indent the
Dave Love <fx@gnu.org>
parents:
diff changeset
1276 current line for C code. Portions of text in the buffer can specify
Dave Love <fx@gnu.org>
parents:
diff changeset
1277 their own keymaps to substitute for the keymap of the buffer's major
Dave Love <fx@gnu.org>
parents:
diff changeset
1278 mode.
Dave Love <fx@gnu.org>
parents:
diff changeset
1279
Dave Love <fx@gnu.org>
parents:
diff changeset
1280 @cindex minor mode keymap
Dave Love <fx@gnu.org>
parents:
diff changeset
1281 Minor modes can also have local keymaps. Whenever a minor mode is
Dave Love <fx@gnu.org>
parents:
diff changeset
1282 in effect, the definitions in its keymap override both the major
Dave Love <fx@gnu.org>
parents:
diff changeset
1283 mode's local keymap and the global keymap.
Dave Love <fx@gnu.org>
parents:
diff changeset
1284
Dave Love <fx@gnu.org>
parents:
diff changeset
1285 @vindex c-mode-map
Dave Love <fx@gnu.org>
parents:
diff changeset
1286 @vindex lisp-mode-map
Dave Love <fx@gnu.org>
parents:
diff changeset
1287 The local keymaps for Lisp mode and several other major modes always
Dave Love <fx@gnu.org>
parents:
diff changeset
1288 exist even when not in use. These are kept in variables named
Dave Love <fx@gnu.org>
parents:
diff changeset
1289 @code{lisp-mode-map} and so on. For major modes less often used, the
Dave Love <fx@gnu.org>
parents:
diff changeset
1290 local keymap is normally constructed only when the mode is used for the
Dave Love <fx@gnu.org>
parents:
diff changeset
1291 first time in a session. This is to save space. If you wish to change
Dave Love <fx@gnu.org>
parents:
diff changeset
1292 one of these keymaps, you must use the major mode's @dfn{mode
Dave Love <fx@gnu.org>
parents:
diff changeset
1293 hook}---see below.
Dave Love <fx@gnu.org>
parents:
diff changeset
1294
Dave Love <fx@gnu.org>
parents:
diff changeset
1295 All minor mode keymaps are created in advance. There is no way to
Dave Love <fx@gnu.org>
parents:
diff changeset
1296 defer their creation until the first time the minor mode is enabled.
Dave Love <fx@gnu.org>
parents:
diff changeset
1297
Dave Love <fx@gnu.org>
parents:
diff changeset
1298 A local keymap can locally redefine a key as a prefix key by defining
Dave Love <fx@gnu.org>
parents:
diff changeset
1299 it as a prefix keymap. If the key is also defined globally as a prefix,
Dave Love <fx@gnu.org>
parents:
diff changeset
1300 then its local and global definitions (both keymaps) effectively
Dave Love <fx@gnu.org>
parents:
diff changeset
1301 combine: both of them are used to look up the event that follows the
Dave Love <fx@gnu.org>
parents:
diff changeset
1302 prefix key. Thus, if the mode's local keymap defines @kbd{C-c} as
Dave Love <fx@gnu.org>
parents:
diff changeset
1303 another keymap, and that keymap defines @kbd{C-z} as a command, this
Dave Love <fx@gnu.org>
parents:
diff changeset
1304 provides a local meaning for @kbd{C-c C-z}. This does not affect other
Dave Love <fx@gnu.org>
parents:
diff changeset
1305 sequences that start with @kbd{C-c}; if those sequences don't have their
Dave Love <fx@gnu.org>
parents:
diff changeset
1306 own local bindings, their global bindings remain in effect.
Dave Love <fx@gnu.org>
parents:
diff changeset
1307
Dave Love <fx@gnu.org>
parents:
diff changeset
1308 Another way to think of this is that Emacs handles a multi-event key
Dave Love <fx@gnu.org>
parents:
diff changeset
1309 sequence by looking in several keymaps, one by one, for a binding of the
Dave Love <fx@gnu.org>
parents:
diff changeset
1310 whole key sequence. First it checks the minor mode keymaps for minor
Dave Love <fx@gnu.org>
parents:
diff changeset
1311 modes that are enabled, then it checks the major mode's keymap, and then
Dave Love <fx@gnu.org>
parents:
diff changeset
1312 it checks the global keymap. This is not precisely how key lookup
Dave Love <fx@gnu.org>
parents:
diff changeset
1313 works, but it's good enough for understanding ordinary circumstances.
Dave Love <fx@gnu.org>
parents:
diff changeset
1314
Dave Love <fx@gnu.org>
parents:
diff changeset
1315 @cindex rebinding major mode keys
26392
b3d3ff9a7a2c *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25829
diff changeset
1316 @findex define-key
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1317 To change the local bindings of a major mode, you must change the
Dave Love <fx@gnu.org>
parents:
diff changeset
1318 mode's local keymap. Normally you must wait until the first time the
Dave Love <fx@gnu.org>
parents:
diff changeset
1319 mode is used, because most major modes don't create their keymaps until
Dave Love <fx@gnu.org>
parents:
diff changeset
1320 then. If you want to specify something in your @file{~/.emacs} file to
Dave Love <fx@gnu.org>
parents:
diff changeset
1321 change a major mode's bindings, you must use the mode's mode hook to
Dave Love <fx@gnu.org>
parents:
diff changeset
1322 delay the change until the mode is first used.
Dave Love <fx@gnu.org>
parents:
diff changeset
1323
Dave Love <fx@gnu.org>
parents:
diff changeset
1324 For example, the command @code{texinfo-mode} to select Texinfo mode
Dave Love <fx@gnu.org>
parents:
diff changeset
1325 runs the hook @code{texinfo-mode-hook}. Here's how you can use the hook
Dave Love <fx@gnu.org>
parents:
diff changeset
1326 to add local bindings (not very useful, we admit) for @kbd{C-c n} and
Dave Love <fx@gnu.org>
parents:
diff changeset
1327 @kbd{C-c p} in Texinfo mode:
Dave Love <fx@gnu.org>
parents:
diff changeset
1328
Dave Love <fx@gnu.org>
parents:
diff changeset
1329 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
1330 (add-hook 'texinfo-mode-hook
36148
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
1331 '(lambda ()
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
1332 (define-key texinfo-mode-map "\C-cp"
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
1333 'backward-paragraph)
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
1334 (define-key texinfo-mode-map "\C-cn"
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
1335 'forward-paragraph)))
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1336 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
1337
Dave Love <fx@gnu.org>
parents:
diff changeset
1338 @xref{Hooks}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1339
Dave Love <fx@gnu.org>
parents:
diff changeset
1340 @node Minibuffer Maps
Dave Love <fx@gnu.org>
parents:
diff changeset
1341 @subsection Minibuffer Keymaps
Dave Love <fx@gnu.org>
parents:
diff changeset
1342
Dave Love <fx@gnu.org>
parents:
diff changeset
1343 @cindex minibuffer keymaps
Dave Love <fx@gnu.org>
parents:
diff changeset
1344 @vindex minibuffer-local-map
Dave Love <fx@gnu.org>
parents:
diff changeset
1345 @vindex minibuffer-local-ns-map
Dave Love <fx@gnu.org>
parents:
diff changeset
1346 @vindex minibuffer-local-completion-map
Dave Love <fx@gnu.org>
parents:
diff changeset
1347 @vindex minibuffer-local-must-match-map
Dave Love <fx@gnu.org>
parents:
diff changeset
1348 The minibuffer has its own set of local keymaps; they contain various
Dave Love <fx@gnu.org>
parents:
diff changeset
1349 completion and exit commands.
Dave Love <fx@gnu.org>
parents:
diff changeset
1350
Dave Love <fx@gnu.org>
parents:
diff changeset
1351 @itemize @bullet
Dave Love <fx@gnu.org>
parents:
diff changeset
1352 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
1353 @code{minibuffer-local-map} is used for ordinary input (no completion).
Dave Love <fx@gnu.org>
parents:
diff changeset
1354 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
1355 @code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
Dave Love <fx@gnu.org>
parents:
diff changeset
1356 just like @key{RET}. This is used mainly for Mocklisp compatibility.
Dave Love <fx@gnu.org>
parents:
diff changeset
1357 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
1358 @code{minibuffer-local-completion-map} is for permissive completion.
Dave Love <fx@gnu.org>
parents:
diff changeset
1359 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
1360 @code{minibuffer-local-must-match-map} is for strict completion and
Dave Love <fx@gnu.org>
parents:
diff changeset
1361 for cautious completion.
Dave Love <fx@gnu.org>
parents:
diff changeset
1362 @end itemize
Dave Love <fx@gnu.org>
parents:
diff changeset
1363
Dave Love <fx@gnu.org>
parents:
diff changeset
1364 @node Rebinding
Dave Love <fx@gnu.org>
parents:
diff changeset
1365 @subsection Changing Key Bindings Interactively
Dave Love <fx@gnu.org>
parents:
diff changeset
1366 @cindex key rebinding, this session
36263
11db0318031d Remove redundant index entries.
Eli Zaretskii <eliz@gnu.org>
parents: 36148
diff changeset
1367 @cindex redefining keys, this session
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1368
Dave Love <fx@gnu.org>
parents:
diff changeset
1369 The way to redefine an Emacs key is to change its entry in a keymap.
Dave Love <fx@gnu.org>
parents:
diff changeset
1370 You can change the global keymap, in which case the change is effective in
Dave Love <fx@gnu.org>
parents:
diff changeset
1371 all major modes (except those that have their own overriding local
Dave Love <fx@gnu.org>
parents:
diff changeset
1372 definitions for the same key). Or you can change the current buffer's
Dave Love <fx@gnu.org>
parents:
diff changeset
1373 local map, which affects all buffers using the same major mode.
Dave Love <fx@gnu.org>
parents:
diff changeset
1374
Dave Love <fx@gnu.org>
parents:
diff changeset
1375 @findex global-set-key
Dave Love <fx@gnu.org>
parents:
diff changeset
1376 @findex local-set-key
Dave Love <fx@gnu.org>
parents:
diff changeset
1377 @findex global-unset-key
Dave Love <fx@gnu.org>
parents:
diff changeset
1378 @findex local-unset-key
Dave Love <fx@gnu.org>
parents:
diff changeset
1379 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
1380 @item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
1381 Define @var{key} globally to run @var{cmd}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1382 @item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
1383 Define @var{key} locally (in the major mode now in effect) to run
Dave Love <fx@gnu.org>
parents:
diff changeset
1384 @var{cmd}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1385 @item M-x global-unset-key @key{RET} @var{key}
Dave Love <fx@gnu.org>
parents:
diff changeset
1386 Make @var{key} undefined in the global map.
Dave Love <fx@gnu.org>
parents:
diff changeset
1387 @item M-x local-unset-key @key{RET} @var{key}
Dave Love <fx@gnu.org>
parents:
diff changeset
1388 Make @var{key} undefined locally (in the major mode now in effect).
Dave Love <fx@gnu.org>
parents:
diff changeset
1389 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1390
Dave Love <fx@gnu.org>
parents:
diff changeset
1391 For example, suppose you like to execute commands in a subshell within
Dave Love <fx@gnu.org>
parents:
diff changeset
1392 an Emacs buffer, instead of suspending Emacs and executing commands in
Dave Love <fx@gnu.org>
parents:
diff changeset
1393 your login shell. Normally, @kbd{C-z} is bound to the function
Dave Love <fx@gnu.org>
parents:
diff changeset
1394 @code{suspend-emacs} (when not using the X Window System), but you can
Dave Love <fx@gnu.org>
parents:
diff changeset
1395 change @kbd{C-z} to invoke an interactive subshell within Emacs, by
Dave Love <fx@gnu.org>
parents:
diff changeset
1396 binding it to @code{shell} as follows:
Dave Love <fx@gnu.org>
parents:
diff changeset
1397
Dave Love <fx@gnu.org>
parents:
diff changeset
1398 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
1399 M-x global-set-key @key{RET} C-z shell @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
1400 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
1401
Dave Love <fx@gnu.org>
parents:
diff changeset
1402 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
1403 @code{global-set-key} reads the command name after the key. After you
Dave Love <fx@gnu.org>
parents:
diff changeset
1404 press the key, a message like this appears so that you can confirm that
Dave Love <fx@gnu.org>
parents:
diff changeset
1405 you are binding the key you want:
Dave Love <fx@gnu.org>
parents:
diff changeset
1406
Dave Love <fx@gnu.org>
parents:
diff changeset
1407 @example
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47535
diff changeset
1408 Set key C-z to command:
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1409 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
1410
Dave Love <fx@gnu.org>
parents:
diff changeset
1411 You can redefine function keys and mouse events in the same way; just
Dave Love <fx@gnu.org>
parents:
diff changeset
1412 type the function key or click the mouse when it's time to specify the
Dave Love <fx@gnu.org>
parents:
diff changeset
1413 key to rebind.
Dave Love <fx@gnu.org>
parents:
diff changeset
1414
Dave Love <fx@gnu.org>
parents:
diff changeset
1415 You can rebind a key that contains more than one event in the same
Dave Love <fx@gnu.org>
parents:
diff changeset
1416 way. Emacs keeps reading the key to rebind until it is a complete key
Dave Love <fx@gnu.org>
parents:
diff changeset
1417 (that is, not a prefix key). Thus, if you type @kbd{C-f} for
Dave Love <fx@gnu.org>
parents:
diff changeset
1418 @var{key}, that's the end; the minibuffer is entered immediately to
Dave Love <fx@gnu.org>
parents:
diff changeset
1419 read @var{cmd}. But if you type @kbd{C-x}, another character is read;
Dave Love <fx@gnu.org>
parents:
diff changeset
1420 if that is @kbd{4}, another character is read, and so on. For
Dave Love <fx@gnu.org>
parents:
diff changeset
1421 example,
Dave Love <fx@gnu.org>
parents:
diff changeset
1422
Dave Love <fx@gnu.org>
parents:
diff changeset
1423 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
1424 M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
1425 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
1426
Dave Love <fx@gnu.org>
parents:
diff changeset
1427 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
1428 redefines @kbd{C-x 4 $} to run the (fictitious) command
Dave Love <fx@gnu.org>
parents:
diff changeset
1429 @code{spell-other-window}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1430
Dave Love <fx@gnu.org>
parents:
diff changeset
1431 The two-character keys consisting of @kbd{C-c} followed by a letter
Dave Love <fx@gnu.org>
parents:
diff changeset
1432 are reserved for user customizations. Lisp programs are not supposed to
Dave Love <fx@gnu.org>
parents:
diff changeset
1433 define these keys, so the bindings you make for them will be available
Dave Love <fx@gnu.org>
parents:
diff changeset
1434 in all major modes and will never get in the way of anything.
Dave Love <fx@gnu.org>
parents:
diff changeset
1435
Dave Love <fx@gnu.org>
parents:
diff changeset
1436 You can remove the global definition of a key with
Dave Love <fx@gnu.org>
parents:
diff changeset
1437 @code{global-unset-key}. This makes the key @dfn{undefined}; if you
Dave Love <fx@gnu.org>
parents:
diff changeset
1438 type it, Emacs will just beep. Similarly, @code{local-unset-key} makes
Dave Love <fx@gnu.org>
parents:
diff changeset
1439 a key undefined in the current major mode keymap, which makes the global
Dave Love <fx@gnu.org>
parents:
diff changeset
1440 definition (or lack of one) come back into effect in that major mode.
Dave Love <fx@gnu.org>
parents:
diff changeset
1441
Dave Love <fx@gnu.org>
parents:
diff changeset
1442 If you have redefined (or undefined) a key and you subsequently wish
Dave Love <fx@gnu.org>
parents:
diff changeset
1443 to retract the change, undefining the key will not do the job---you need
Dave Love <fx@gnu.org>
parents:
diff changeset
1444 to redefine the key with its standard definition. To find the name of
Dave Love <fx@gnu.org>
parents:
diff changeset
1445 the standard definition of a key, go to a Fundamental mode buffer and
Dave Love <fx@gnu.org>
parents:
diff changeset
1446 use @kbd{C-h c}. The documentation of keys in this manual also lists
Dave Love <fx@gnu.org>
parents:
diff changeset
1447 their command names.
Dave Love <fx@gnu.org>
parents:
diff changeset
1448
Dave Love <fx@gnu.org>
parents:
diff changeset
1449 If you want to prevent yourself from invoking a command by mistake, it
Dave Love <fx@gnu.org>
parents:
diff changeset
1450 is better to disable the command than to undefine the key. A disabled
Dave Love <fx@gnu.org>
parents:
diff changeset
1451 command is less work to invoke when you really want to.
Dave Love <fx@gnu.org>
parents:
diff changeset
1452 @xref{Disabling}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1453
Dave Love <fx@gnu.org>
parents:
diff changeset
1454 @node Init Rebinding
Dave Love <fx@gnu.org>
parents:
diff changeset
1455 @subsection Rebinding Keys in Your Init File
Dave Love <fx@gnu.org>
parents:
diff changeset
1456
Dave Love <fx@gnu.org>
parents:
diff changeset
1457 If you have a set of key bindings that you like to use all the time,
Dave Love <fx@gnu.org>
parents:
diff changeset
1458 you can specify them in your @file{.emacs} file by using their Lisp
26392
b3d3ff9a7a2c *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25829
diff changeset
1459 syntax. (@xref{Init File}.)
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1460
52979
3649390c0f91 Replace @sc{ascii} and ASCII with @acronym{ASCII}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
1461 The simplest method for doing this works for @acronym{ASCII} characters and
3649390c0f91 Replace @sc{ascii} and ASCII with @acronym{ASCII}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
1462 Meta-modified @acronym{ASCII} characters only. This method uses a string to
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1463 represent the key sequence you want to rebind. For example, here's how
Dave Love <fx@gnu.org>
parents:
diff changeset
1464 to bind @kbd{C-z} to @code{shell}:
Dave Love <fx@gnu.org>
parents:
diff changeset
1465
Dave Love <fx@gnu.org>
parents:
diff changeset
1466 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
1467 (global-set-key "\C-z" 'shell)
Dave Love <fx@gnu.org>
parents:
diff changeset
1468 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
1469
Dave Love <fx@gnu.org>
parents:
diff changeset
1470 @noindent
59949
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1471 This example uses a string constant containing one character,
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1472 @kbd{C-z}. (@samp{\C-} is string syntax for a control character.) The
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1473 single-quote before the command name, @code{shell}, marks it as a
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1474 constant symbol rather than a variable. If you omit the quote, Emacs
Dave Love <fx@gnu.org>
parents:
diff changeset
1475 would try to evaluate @code{shell} immediately as a variable. This
Dave Love <fx@gnu.org>
parents:
diff changeset
1476 probably causes an error; it certainly isn't what you want.
Dave Love <fx@gnu.org>
parents:
diff changeset
1477
59949
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1478 Here is another example that binds the key sequence @kbd{C-x M-l}:
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1479
Dave Love <fx@gnu.org>
parents:
diff changeset
1480 @example
59949
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1481 (global-set-key "\C-x\M-l" 'make-symbolic-link)
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1482 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
1483
37419
201fa171a6e2 Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents: 37354
diff changeset
1484 To put @key{TAB}, @key{RET}, @key{ESC}, or @key{DEL} in the
201fa171a6e2 Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents: 37354
diff changeset
1485 string, you can use the Emacs Lisp escape sequences, @samp{\t},
201fa171a6e2 Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents: 37354
diff changeset
1486 @samp{\r}, @samp{\e}, and @samp{\d}. Here is an example which binds
201fa171a6e2 Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents: 37354
diff changeset
1487 @kbd{C-x @key{TAB}}:
201fa171a6e2 Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents: 37354
diff changeset
1488
201fa171a6e2 Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents: 37354
diff changeset
1489 @example
201fa171a6e2 Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents: 37354
diff changeset
1490 (global-set-key "\C-x\t" 'indent-rigidly)
201fa171a6e2 Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents: 37354
diff changeset
1491 @end example
201fa171a6e2 Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents: 37354
diff changeset
1492
52979
3649390c0f91 Replace @sc{ascii} and ASCII with @acronym{ASCII}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
1493 These examples show how to write some other special @acronym{ASCII} characters
39161
10b97dddcb68 Show how to put more special ASCII characters
Richard M. Stallman <rms@gnu.org>
parents: 39060
diff changeset
1494 in strings for key bindings:
10b97dddcb68 Show how to put more special ASCII characters
Richard M. Stallman <rms@gnu.org>
parents: 39060
diff changeset
1495
10b97dddcb68 Show how to put more special ASCII characters
Richard M. Stallman <rms@gnu.org>
parents: 39060
diff changeset
1496 @example
10b97dddcb68 Show how to put more special ASCII characters
Richard M. Stallman <rms@gnu.org>
parents: 39060
diff changeset
1497 (global-set-key "\r" 'newline) ;; @key{RET}
10b97dddcb68 Show how to put more special ASCII characters
Richard M. Stallman <rms@gnu.org>
parents: 39060
diff changeset
1498 (global-set-key "\d" 'delete-backward-char) ;; @key{DEL}
10b97dddcb68 Show how to put more special ASCII characters
Richard M. Stallman <rms@gnu.org>
parents: 39060
diff changeset
1499 (global-set-key "\C-x\e\e" 'repeat-complex-command) ;; @key{ESC}
10b97dddcb68 Show how to put more special ASCII characters
Richard M. Stallman <rms@gnu.org>
parents: 39060
diff changeset
1500 @end example
10b97dddcb68 Show how to put more special ASCII characters
Richard M. Stallman <rms@gnu.org>
parents: 39060
diff changeset
1501
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1502 When the key sequence includes function keys or mouse button events,
52979
3649390c0f91 Replace @sc{ascii} and ASCII with @acronym{ASCII}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
1503 or non-@acronym{ASCII} characters such as @code{C-=} or @code{H-a}, you must use
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1504 the more general method of rebinding, which uses a vector to specify the
Dave Love <fx@gnu.org>
parents:
diff changeset
1505 key sequence.
Dave Love <fx@gnu.org>
parents:
diff changeset
1506
Dave Love <fx@gnu.org>
parents:
diff changeset
1507 The way to write a vector in Emacs Lisp is with square brackets around
Dave Love <fx@gnu.org>
parents:
diff changeset
1508 the vector elements. Use spaces to separate the elements. If an
Dave Love <fx@gnu.org>
parents:
diff changeset
1509 element is a symbol, simply write the symbol's name---no other
Dave Love <fx@gnu.org>
parents:
diff changeset
1510 delimiters or punctuation are needed. If a vector element is a
Dave Love <fx@gnu.org>
parents:
diff changeset
1511 character, write it as a Lisp character constant: @samp{?} followed by
Dave Love <fx@gnu.org>
parents:
diff changeset
1512 the character as it would appear in a string.
Dave Love <fx@gnu.org>
parents:
diff changeset
1513
Dave Love <fx@gnu.org>
parents:
diff changeset
1514 Here are examples of using vectors to rebind @kbd{C-=} (a control
52979
3649390c0f91 Replace @sc{ascii} and ASCII with @acronym{ASCII}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
1515 character not in @acronym{ASCII}), @kbd{C-M-=} (not in @acronym{ASCII} because @kbd{C-=}
3649390c0f91 Replace @sc{ascii} and ASCII with @acronym{ASCII}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
1516 is not), @kbd{H-a} (a Hyper character; @acronym{ASCII} doesn't have Hyper at
38744
d7121931b3ba Show example of specifying C-M-= in Lisp.
Richard M. Stallman <rms@gnu.org>
parents: 38605
diff changeset
1517 all), @key{F7} (a function key), and @kbd{C-Mouse-1} (a
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1518 keyboard-modified mouse button):
Dave Love <fx@gnu.org>
parents:
diff changeset
1519
Dave Love <fx@gnu.org>
parents:
diff changeset
1520 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
1521 (global-set-key [?\C-=] 'make-symbolic-link)
38744
d7121931b3ba Show example of specifying C-M-= in Lisp.
Richard M. Stallman <rms@gnu.org>
parents: 38605
diff changeset
1522 (global-set-key [?\M-\C-=] 'make-symbolic-link)
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1523 (global-set-key [?\H-a] 'make-symbolic-link)
Dave Love <fx@gnu.org>
parents:
diff changeset
1524 (global-set-key [f7] 'make-symbolic-link)
Dave Love <fx@gnu.org>
parents:
diff changeset
1525 (global-set-key [C-mouse-1] 'make-symbolic-link)
Dave Love <fx@gnu.org>
parents:
diff changeset
1526 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
1527
39161
10b97dddcb68 Show how to put more special ASCII characters
Richard M. Stallman <rms@gnu.org>
parents: 39060
diff changeset
1528 You can use a vector for the simple cases too. Here's how to
59949
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1529 rewrite the first six examples above to use vectors:
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1530
Dave Love <fx@gnu.org>
parents:
diff changeset
1531 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
1532 (global-set-key [?\C-z] 'shell)
Dave Love <fx@gnu.org>
parents:
diff changeset
1533 (global-set-key [?\C-x ?l] 'make-symbolic-link)
37419
201fa171a6e2 Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents: 37354
diff changeset
1534 (global-set-key [?\C-x ?\t] 'indent-rigidly)
39161
10b97dddcb68 Show how to put more special ASCII characters
Richard M. Stallman <rms@gnu.org>
parents: 39060
diff changeset
1535 (global-set-key [?\r] 'newline)
10b97dddcb68 Show how to put more special ASCII characters
Richard M. Stallman <rms@gnu.org>
parents: 39060
diff changeset
1536 (global-set-key [?\d] 'delete-backward-char)
10b97dddcb68 Show how to put more special ASCII characters
Richard M. Stallman <rms@gnu.org>
parents: 39060
diff changeset
1537 (global-set-key [?\C-x ?\e ?\e] 'repeat-complex-command)
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1538 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
1539
39161
10b97dddcb68 Show how to put more special ASCII characters
Richard M. Stallman <rms@gnu.org>
parents: 39060
diff changeset
1540 @noindent
10b97dddcb68 Show how to put more special ASCII characters
Richard M. Stallman <rms@gnu.org>
parents: 39060
diff changeset
1541 As you see, you represent a multi-character key sequence with a vector
59949
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1542 by listing all of the characters in order within the square brackets that
39161
10b97dddcb68 Show how to put more special ASCII characters
Richard M. Stallman <rms@gnu.org>
parents: 39060
diff changeset
1543 delimit the vector.
10b97dddcb68 Show how to put more special ASCII characters
Richard M. Stallman <rms@gnu.org>
parents: 39060
diff changeset
1544
51448
596b12c24475 (Init Rebinding): Replace previous change with xref.
Richard M. Stallman <rms@gnu.org>
parents: 51274
diff changeset
1545 Language and coding systems can cause problems with key bindings
52979
3649390c0f91 Replace @sc{ascii} and ASCII with @acronym{ASCII}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
1546 for non-@acronym{ASCII} characters. @xref{Non-ASCII Rebinding}.
51274
78a8be5d896c (Init Rebinding): Xref Non-ASCII Rebinding, for
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 50696
diff changeset
1547
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1548 @node Function Keys
Dave Love <fx@gnu.org>
parents:
diff changeset
1549 @subsection Rebinding Function Keys
Dave Love <fx@gnu.org>
parents:
diff changeset
1550
Dave Love <fx@gnu.org>
parents:
diff changeset
1551 Key sequences can contain function keys as well as ordinary
Dave Love <fx@gnu.org>
parents:
diff changeset
1552 characters. Just as Lisp characters (actually integers) represent
Dave Love <fx@gnu.org>
parents:
diff changeset
1553 keyboard characters, Lisp symbols represent function keys. If the
Dave Love <fx@gnu.org>
parents:
diff changeset
1554 function key has a word as its label, then that word is also the name of
Dave Love <fx@gnu.org>
parents:
diff changeset
1555 the corresponding Lisp symbol. Here are the conventional Lisp names for
Dave Love <fx@gnu.org>
parents:
diff changeset
1556 common function keys:
Dave Love <fx@gnu.org>
parents:
diff changeset
1557
Dave Love <fx@gnu.org>
parents:
diff changeset
1558 @table @asis
Dave Love <fx@gnu.org>
parents:
diff changeset
1559 @item @code{left}, @code{up}, @code{right}, @code{down}
Dave Love <fx@gnu.org>
parents:
diff changeset
1560 Cursor arrow keys.
Dave Love <fx@gnu.org>
parents:
diff changeset
1561
Dave Love <fx@gnu.org>
parents:
diff changeset
1562 @item @code{begin}, @code{end}, @code{home}, @code{next}, @code{prior}
Dave Love <fx@gnu.org>
parents:
diff changeset
1563 Other cursor repositioning keys.
Dave Love <fx@gnu.org>
parents:
diff changeset
1564
Dave Love <fx@gnu.org>
parents:
diff changeset
1565 @item @code{select}, @code{print}, @code{execute}, @code{backtab}
Dave Love <fx@gnu.org>
parents:
diff changeset
1566 @itemx @code{insert}, @code{undo}, @code{redo}, @code{clearline}
37977
5ff6cac52888 Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents: 37976
diff changeset
1567 @itemx @code{insertline}, @code{deleteline}, @code{insertchar}, @code{deletechar}
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1568 Miscellaneous function keys.
Dave Love <fx@gnu.org>
parents:
diff changeset
1569
Dave Love <fx@gnu.org>
parents:
diff changeset
1570 @item @code{f1}, @code{f2}, @dots{} @code{f35}
Dave Love <fx@gnu.org>
parents:
diff changeset
1571 Numbered function keys (across the top of the keyboard).
Dave Love <fx@gnu.org>
parents:
diff changeset
1572
Dave Love <fx@gnu.org>
parents:
diff changeset
1573 @item @code{kp-add}, @code{kp-subtract}, @code{kp-multiply}, @code{kp-divide}
Dave Love <fx@gnu.org>
parents:
diff changeset
1574 @itemx @code{kp-backtab}, @code{kp-space}, @code{kp-tab}, @code{kp-enter}
Dave Love <fx@gnu.org>
parents:
diff changeset
1575 @itemx @code{kp-separator}, @code{kp-decimal}, @code{kp-equal}
Dave Love <fx@gnu.org>
parents:
diff changeset
1576 Keypad keys (to the right of the regular keyboard), with names or punctuation.
Dave Love <fx@gnu.org>
parents:
diff changeset
1577
Dave Love <fx@gnu.org>
parents:
diff changeset
1578 @item @code{kp-0}, @code{kp-1}, @dots{} @code{kp-9}
Dave Love <fx@gnu.org>
parents:
diff changeset
1579 Keypad keys with digits.
Dave Love <fx@gnu.org>
parents:
diff changeset
1580
Dave Love <fx@gnu.org>
parents:
diff changeset
1581 @item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
Dave Love <fx@gnu.org>
parents:
diff changeset
1582 Keypad PF keys.
Dave Love <fx@gnu.org>
parents:
diff changeset
1583 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1584
Dave Love <fx@gnu.org>
parents:
diff changeset
1585 These names are conventional, but some systems (especially when using
35188
94d46968a93f Don't say "X Windows". From Colin Walters <walters@cis.ohio-state.edu>.
Eli Zaretskii <eliz@gnu.org>
parents: 34151
diff changeset
1586 X) may use different names. To make certain what symbol is used for a
94d46968a93f Don't say "X Windows". From Colin Walters <walters@cis.ohio-state.edu>.
Eli Zaretskii <eliz@gnu.org>
parents: 34151
diff changeset
1587 given function key on your terminal, type @kbd{C-h c} followed by that
94d46968a93f Don't say "X Windows". From Colin Walters <walters@cis.ohio-state.edu>.
Eli Zaretskii <eliz@gnu.org>
parents: 34151
diff changeset
1588 key.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1589
Dave Love <fx@gnu.org>
parents:
diff changeset
1590 A key sequence which contains function key symbols (or anything but
59949
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1591 @acronym{ASCII} characters) must be a vector rather than a string.
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1592 Thus, to bind function key @samp{f1} to the command @code{rmail},
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1593 write the following:
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1594
Dave Love <fx@gnu.org>
parents:
diff changeset
1595 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
1596 (global-set-key [f1] 'rmail)
Dave Love <fx@gnu.org>
parents:
diff changeset
1597 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
1598
Dave Love <fx@gnu.org>
parents:
diff changeset
1599 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
1600 To bind the right-arrow key to the command @code{forward-char}, you can
Dave Love <fx@gnu.org>
parents:
diff changeset
1601 use this expression:
Dave Love <fx@gnu.org>
parents:
diff changeset
1602
Dave Love <fx@gnu.org>
parents:
diff changeset
1603 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
1604 (global-set-key [right] 'forward-char)
Dave Love <fx@gnu.org>
parents:
diff changeset
1605 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
1606
Dave Love <fx@gnu.org>
parents:
diff changeset
1607 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
1608 This uses the Lisp syntax for a vector containing the symbol
Dave Love <fx@gnu.org>
parents:
diff changeset
1609 @code{right}. (This binding is present in Emacs by default.)
Dave Love <fx@gnu.org>
parents:
diff changeset
1610
Dave Love <fx@gnu.org>
parents:
diff changeset
1611 @xref{Init Rebinding}, for more information about using vectors for
Dave Love <fx@gnu.org>
parents:
diff changeset
1612 rebinding.
Dave Love <fx@gnu.org>
parents:
diff changeset
1613
Dave Love <fx@gnu.org>
parents:
diff changeset
1614 You can mix function keys and characters in a key sequence. This
Dave Love <fx@gnu.org>
parents:
diff changeset
1615 example binds @kbd{C-x @key{NEXT}} to the command @code{forward-page}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1616
Dave Love <fx@gnu.org>
parents:
diff changeset
1617 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
1618 (global-set-key [?\C-x next] 'forward-page)
Dave Love <fx@gnu.org>
parents:
diff changeset
1619 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
1620
Dave Love <fx@gnu.org>
parents:
diff changeset
1621 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
1622 where @code{?\C-x} is the Lisp character constant for the character
Dave Love <fx@gnu.org>
parents:
diff changeset
1623 @kbd{C-x}. The vector element @code{next} is a symbol and therefore
Dave Love <fx@gnu.org>
parents:
diff changeset
1624 does not take a question mark.
Dave Love <fx@gnu.org>
parents:
diff changeset
1625
Dave Love <fx@gnu.org>
parents:
diff changeset
1626 You can use the modifier keys @key{CTRL}, @key{META}, @key{HYPER},
Dave Love <fx@gnu.org>
parents:
diff changeset
1627 @key{SUPER}, @key{ALT} and @key{SHIFT} with function keys. To represent
Dave Love <fx@gnu.org>
parents:
diff changeset
1628 these modifiers, add the strings @samp{C-}, @samp{M-}, @samp{H-},
Dave Love <fx@gnu.org>
parents:
diff changeset
1629 @samp{s-}, @samp{A-} and @samp{S-} at the front of the symbol name.
Dave Love <fx@gnu.org>
parents:
diff changeset
1630 Thus, here is how to make @kbd{Hyper-Meta-@key{RIGHT}} move forward a
Dave Love <fx@gnu.org>
parents:
diff changeset
1631 word:
Dave Love <fx@gnu.org>
parents:
diff changeset
1632
Dave Love <fx@gnu.org>
parents:
diff changeset
1633 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
1634 (global-set-key [H-M-right] 'forward-word)
Dave Love <fx@gnu.org>
parents:
diff changeset
1635 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
1636
61051
a45405053cb1 (Function Keys): Document kp- event types and keypad-setup package.
Richard M. Stallman <rms@gnu.org>
parents: 60423
diff changeset
1637 @cindex keypad
a45405053cb1 (Function Keys): Document kp- event types and keypad-setup package.
Richard M. Stallman <rms@gnu.org>
parents: 60423
diff changeset
1638 Many keyboards have a ``numeric keypad'' on the right hand side.
a45405053cb1 (Function Keys): Document kp- event types and keypad-setup package.
Richard M. Stallman <rms@gnu.org>
parents: 60423
diff changeset
1639 The numeric keys in the keypad double up as cursor motion keys,
a45405053cb1 (Function Keys): Document kp- event types and keypad-setup package.
Richard M. Stallman <rms@gnu.org>
parents: 60423
diff changeset
1640 toggled by a key labelled @samp{Num Lock}. By default, Emacs
a45405053cb1 (Function Keys): Document kp- event types and keypad-setup package.
Richard M. Stallman <rms@gnu.org>
parents: 60423
diff changeset
1641 translates these keys to the corresponding keys in the main keyboard
a45405053cb1 (Function Keys): Document kp- event types and keypad-setup package.
Richard M. Stallman <rms@gnu.org>
parents: 60423
diff changeset
1642 (@pxref{Keyboard Translations}). For example, when @samp{Num Lock} is
a45405053cb1 (Function Keys): Document kp- event types and keypad-setup package.
Richard M. Stallman <rms@gnu.org>
parents: 60423
diff changeset
1643 on, the key labelled @samp{8} on the numeric keypad produces
a45405053cb1 (Function Keys): Document kp- event types and keypad-setup package.
Richard M. Stallman <rms@gnu.org>
parents: 60423
diff changeset
1644 @code{kp-8}, which is translated to @kbd{8}; when @samp{Num Lock} is
a45405053cb1 (Function Keys): Document kp- event types and keypad-setup package.
Richard M. Stallman <rms@gnu.org>
parents: 60423
diff changeset
1645 off, the same key produces @code{kp-up}, which is translated to
a45405053cb1 (Function Keys): Document kp- event types and keypad-setup package.
Richard M. Stallman <rms@gnu.org>
parents: 60423
diff changeset
1646 @key{UP}. If you rebind a key such as @kbd{8} or @key{UP}, it affects
a45405053cb1 (Function Keys): Document kp- event types and keypad-setup package.
Richard M. Stallman <rms@gnu.org>
parents: 60423
diff changeset
1647 the equivalent keypad key too. However, if you rebind a @samp{kp-}
a45405053cb1 (Function Keys): Document kp- event types and keypad-setup package.
Richard M. Stallman <rms@gnu.org>
parents: 60423
diff changeset
1648 key directly, that won't affect its non-keypad equivalent.
a45405053cb1 (Function Keys): Document kp- event types and keypad-setup package.
Richard M. Stallman <rms@gnu.org>
parents: 60423
diff changeset
1649
a45405053cb1 (Function Keys): Document kp- event types and keypad-setup package.
Richard M. Stallman <rms@gnu.org>
parents: 60423
diff changeset
1650 Emacs provides a convenient method for binding the numeric keypad
a45405053cb1 (Function Keys): Document kp- event types and keypad-setup package.
Richard M. Stallman <rms@gnu.org>
parents: 60423
diff changeset
1651 keys, using the variables @code{keypad-setup},
a45405053cb1 (Function Keys): Document kp- event types and keypad-setup package.
Richard M. Stallman <rms@gnu.org>
parents: 60423
diff changeset
1652 @code{keypad-numlock-setup}, @code{keypad-shifted-setup}, and
a45405053cb1 (Function Keys): Document kp- event types and keypad-setup package.
Richard M. Stallman <rms@gnu.org>
parents: 60423
diff changeset
1653 @code{keypad-numlock-shifted-setup}. These can be found in the
a45405053cb1 (Function Keys): Document kp- event types and keypad-setup package.
Richard M. Stallman <rms@gnu.org>
parents: 60423
diff changeset
1654 @samp{keyboard} customization group (@pxref{Easy Customization}). You
a45405053cb1 (Function Keys): Document kp- event types and keypad-setup package.
Richard M. Stallman <rms@gnu.org>
parents: 60423
diff changeset
1655 can rebind the keys to perform other tasks, such as issuing numeric
a45405053cb1 (Function Keys): Document kp- event types and keypad-setup package.
Richard M. Stallman <rms@gnu.org>
parents: 60423
diff changeset
1656 prefix arguments.
a45405053cb1 (Function Keys): Document kp- event types and keypad-setup package.
Richard M. Stallman <rms@gnu.org>
parents: 60423
diff changeset
1657
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1658 @node Named ASCII Chars
52979
3649390c0f91 Replace @sc{ascii} and ASCII with @acronym{ASCII}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
1659 @subsection Named @acronym{ASCII} Control Characters
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1660
Dave Love <fx@gnu.org>
parents:
diff changeset
1661 @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC} and @key{DEL}
59949
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1662 started out as names for certain @acronym{ASCII} control characters,
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1663 used so often that they have special keys of their own. For instance,
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1664 @key{TAB} was another name for @kbd{C-i}. Later, users found it
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1665 convenient to distinguish in Emacs between these keys and the ``same''
59949
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1666 control characters typed with the @key{CTRL} key. Therefore, on most
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1667 modern terminals, they are no longer the same, and @key{TAB} is
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1668 distinguishable from @kbd{C-i}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1669
59949
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1670 Emacs can distinguish these two kinds of input if the keyboard does.
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1671 It treats the ``special'' keys as function keys named @code{tab},
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1672 @code{return}, @code{backspace}, @code{linefeed}, @code{escape}, and
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1673 @code{delete}. These function keys translate automatically into the
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1674 corresponding @acronym{ASCII} characters @emph{if} they have no
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1675 bindings of their own. As a result, neither users nor Lisp programs
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1676 need to pay attention to the distinction unless they care to.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1677
Dave Love <fx@gnu.org>
parents:
diff changeset
1678 If you do not want to distinguish between (for example) @key{TAB} and
52979
3649390c0f91 Replace @sc{ascii} and ASCII with @acronym{ASCII}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
1679 @kbd{C-i}, make just one binding, for the @acronym{ASCII} character @key{TAB}
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1680 (octal code 011). If you do want to distinguish, make one binding for
52979
3649390c0f91 Replace @sc{ascii} and ASCII with @acronym{ASCII}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
1681 this @acronym{ASCII} character, and another for the ``function key'' @code{tab}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1682
52979
3649390c0f91 Replace @sc{ascii} and ASCII with @acronym{ASCII}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
1683 With an ordinary @acronym{ASCII} terminal, there is no way to distinguish
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1684 between @key{TAB} and @kbd{C-i} (and likewise for other such pairs),
Dave Love <fx@gnu.org>
parents:
diff changeset
1685 because the terminal sends the same character in both cases.
Dave Love <fx@gnu.org>
parents:
diff changeset
1686
Dave Love <fx@gnu.org>
parents:
diff changeset
1687 @node Non-ASCII Rebinding
52979
3649390c0f91 Replace @sc{ascii} and ASCII with @acronym{ASCII}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
1688 @subsection Non-@acronym{ASCII} Characters on the Keyboard
3649390c0f91 Replace @sc{ascii} and ASCII with @acronym{ASCII}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
1689 @cindex rebinding non-@acronym{ASCII} keys
3649390c0f91 Replace @sc{ascii} and ASCII with @acronym{ASCII}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
1690 @cindex non-@acronym{ASCII} keys, binding
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1691
56690
d699954ad4c6 (Non-ASCII Rebinding):
Richard M. Stallman <rms@gnu.org>
parents: 56165
diff changeset
1692 If your keyboard has keys that send non-@acronym{ASCII}
d699954ad4c6 (Non-ASCII Rebinding):
Richard M. Stallman <rms@gnu.org>
parents: 56165
diff changeset
1693 characters, such as accented letters, rebinding these keys
d699954ad4c6 (Non-ASCII Rebinding):
Richard M. Stallman <rms@gnu.org>
parents: 56165
diff changeset
1694 must be done by using a vector like this@footnote{Note that
d699954ad4c6 (Non-ASCII Rebinding):
Richard M. Stallman <rms@gnu.org>
parents: 56165
diff changeset
1695 you should avoid the string syntax for binding
d699954ad4c6 (Non-ASCII Rebinding):
Richard M. Stallman <rms@gnu.org>
parents: 56165
diff changeset
1696 non-@acronym{ASCII} characters, since they will be
d699954ad4c6 (Non-ASCII Rebinding):
Richard M. Stallman <rms@gnu.org>
parents: 56165
diff changeset
1697 interpreted as meta keys. @xref{Strings of Events,,,elisp,
d699954ad4c6 (Non-ASCII Rebinding):
Richard M. Stallman <rms@gnu.org>
parents: 56165
diff changeset
1698 The Emacs Lisp Reference Manual}.}:
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1699
Dave Love <fx@gnu.org>
parents:
diff changeset
1700 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
1701 (global-set-key [?@var{char}] 'some-function)
Dave Love <fx@gnu.org>
parents:
diff changeset
1702 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
1703
Dave Love <fx@gnu.org>
parents:
diff changeset
1704 @noindent
36632
1bfc2fad762a (File Variables): Fix a typo.
Eli Zaretskii <eliz@gnu.org>
parents: 36593
diff changeset
1705 Type @kbd{C-q} followed by the key you want to bind, to insert @var{char}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1706
56690
d699954ad4c6 (Non-ASCII Rebinding):
Richard M. Stallman <rms@gnu.org>
parents: 56165
diff changeset
1707 Since this puts a non-@acronym{ASCII} character in the @file{.emacs},
57156
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
1708 you should specify a coding system for that file that supports the
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
1709 character in question. @xref{Init Syntax}.
51448
596b12c24475 (Init Rebinding): Replace previous change with xref.
Richard M. Stallman <rms@gnu.org>
parents: 51274
diff changeset
1710
57156
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
1711 @strong{Warning:} if you change the keyboard encoding, or change
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
1712 between multibyte and unibyte mode, or anything that would alter which
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
1713 code @kbd{C-q} would insert for that character, you'll need to edit
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
1714 the Lisp expression accordingly, to use the character code generated
a830d2693f6e (Hooks): Explain using setq to clear out a hook.
Richard M. Stallman <rms@gnu.org>
parents: 56785
diff changeset
1715 by @kbd{C-q} in the new mode.
27218
ff77115434db Doc recent changes in Custom.
Dave Love <fx@gnu.org>
parents: 26392
diff changeset
1716
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1717 @node Mouse Buttons
Dave Love <fx@gnu.org>
parents:
diff changeset
1718 @subsection Rebinding Mouse Buttons
Dave Love <fx@gnu.org>
parents:
diff changeset
1719 @cindex mouse button events
Dave Love <fx@gnu.org>
parents:
diff changeset
1720 @cindex rebinding mouse buttons
Dave Love <fx@gnu.org>
parents:
diff changeset
1721 @cindex click events
Dave Love <fx@gnu.org>
parents:
diff changeset
1722 @cindex drag events
Dave Love <fx@gnu.org>
parents:
diff changeset
1723 @cindex down events
Dave Love <fx@gnu.org>
parents:
diff changeset
1724 @cindex button down events
Dave Love <fx@gnu.org>
parents:
diff changeset
1725
Dave Love <fx@gnu.org>
parents:
diff changeset
1726 Emacs uses Lisp symbols to designate mouse buttons, too. The ordinary
Dave Love <fx@gnu.org>
parents:
diff changeset
1727 mouse events in Emacs are @dfn{click} events; these happen when you
Dave Love <fx@gnu.org>
parents:
diff changeset
1728 press a button and release it without moving the mouse. You can also
Dave Love <fx@gnu.org>
parents:
diff changeset
1729 get @dfn{drag} events, when you move the mouse while holding the button
Dave Love <fx@gnu.org>
parents:
diff changeset
1730 down. Drag events happen when you finally let go of the button.
Dave Love <fx@gnu.org>
parents:
diff changeset
1731
Dave Love <fx@gnu.org>
parents:
diff changeset
1732 The symbols for basic click events are @code{mouse-1} for the leftmost
Dave Love <fx@gnu.org>
parents:
diff changeset
1733 button, @code{mouse-2} for the next, and so on. Here is how you can
Dave Love <fx@gnu.org>
parents:
diff changeset
1734 redefine the second mouse button to split the current window:
Dave Love <fx@gnu.org>
parents:
diff changeset
1735
Dave Love <fx@gnu.org>
parents:
diff changeset
1736 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
1737 (global-set-key [mouse-2] 'split-window-vertically)
Dave Love <fx@gnu.org>
parents:
diff changeset
1738 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
1739
Dave Love <fx@gnu.org>
parents:
diff changeset
1740 The symbols for drag events are similar, but have the prefix
Dave Love <fx@gnu.org>
parents:
diff changeset
1741 @samp{drag-} before the word @samp{mouse}. For example, dragging the
Dave Love <fx@gnu.org>
parents:
diff changeset
1742 first button generates a @code{drag-mouse-1} event.
Dave Love <fx@gnu.org>
parents:
diff changeset
1743
Dave Love <fx@gnu.org>
parents:
diff changeset
1744 You can also define bindings for events that occur when a mouse button
Dave Love <fx@gnu.org>
parents:
diff changeset
1745 is pressed down. These events start with @samp{down-} instead of
Dave Love <fx@gnu.org>
parents:
diff changeset
1746 @samp{drag-}. Such events are generated only if they have key bindings.
Dave Love <fx@gnu.org>
parents:
diff changeset
1747 When you get a button-down event, a corresponding click or drag event
Dave Love <fx@gnu.org>
parents:
diff changeset
1748 will always follow.
Dave Love <fx@gnu.org>
parents:
diff changeset
1749
Dave Love <fx@gnu.org>
parents:
diff changeset
1750 @cindex double clicks
Dave Love <fx@gnu.org>
parents:
diff changeset
1751 @cindex triple clicks
Dave Love <fx@gnu.org>
parents:
diff changeset
1752 If you wish, you can distinguish single, double, and triple clicks. A
Dave Love <fx@gnu.org>
parents:
diff changeset
1753 double click means clicking a mouse button twice in approximately the
Dave Love <fx@gnu.org>
parents:
diff changeset
1754 same place. The first click generates an ordinary click event. The
Dave Love <fx@gnu.org>
parents:
diff changeset
1755 second click, if it comes soon enough, generates a double-click event
Dave Love <fx@gnu.org>
parents:
diff changeset
1756 instead. The event type for a double-click event starts with
Dave Love <fx@gnu.org>
parents:
diff changeset
1757 @samp{double-}: for example, @code{double-mouse-3}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1758
Dave Love <fx@gnu.org>
parents:
diff changeset
1759 This means that you can give a special meaning to the second click at
Dave Love <fx@gnu.org>
parents:
diff changeset
1760 the same place, but it must act on the assumption that the ordinary
Dave Love <fx@gnu.org>
parents:
diff changeset
1761 single click definition has run when the first click was received.
Dave Love <fx@gnu.org>
parents:
diff changeset
1762
Dave Love <fx@gnu.org>
parents:
diff changeset
1763 This constrains what you can do with double clicks, but user interface
Dave Love <fx@gnu.org>
parents:
diff changeset
1764 designers say that this constraint ought to be followed in any case. A
Dave Love <fx@gnu.org>
parents:
diff changeset
1765 double click should do something similar to the single click, only
Dave Love <fx@gnu.org>
parents:
diff changeset
1766 ``more so.'' The command for the double-click event should perform the
Dave Love <fx@gnu.org>
parents:
diff changeset
1767 extra work for the double click.
Dave Love <fx@gnu.org>
parents:
diff changeset
1768
Dave Love <fx@gnu.org>
parents:
diff changeset
1769 If a double-click event has no binding, it changes to the
Dave Love <fx@gnu.org>
parents:
diff changeset
1770 corresponding single-click event. Thus, if you don't define a
Dave Love <fx@gnu.org>
parents:
diff changeset
1771 particular double click specially, it executes the single-click command
Dave Love <fx@gnu.org>
parents:
diff changeset
1772 twice.
Dave Love <fx@gnu.org>
parents:
diff changeset
1773
Dave Love <fx@gnu.org>
parents:
diff changeset
1774 Emacs also supports triple-click events whose names start with
Dave Love <fx@gnu.org>
parents:
diff changeset
1775 @samp{triple-}. Emacs does not distinguish quadruple clicks as event
Dave Love <fx@gnu.org>
parents:
diff changeset
1776 types; clicks beyond the third generate additional triple-click events.
Dave Love <fx@gnu.org>
parents:
diff changeset
1777 However, the full number of clicks is recorded in the event list, so you
Dave Love <fx@gnu.org>
parents:
diff changeset
1778 can distinguish if you really want to. We don't recommend distinct
Dave Love <fx@gnu.org>
parents:
diff changeset
1779 meanings for more than three clicks, but sometimes it is useful for
Dave Love <fx@gnu.org>
parents:
diff changeset
1780 subsequent clicks to cycle through the same set of three meanings, so
Dave Love <fx@gnu.org>
parents:
diff changeset
1781 that four clicks are equivalent to one click, five are equivalent to
Dave Love <fx@gnu.org>
parents:
diff changeset
1782 two, and six are equivalent to three.
Dave Love <fx@gnu.org>
parents:
diff changeset
1783
Dave Love <fx@gnu.org>
parents:
diff changeset
1784 Emacs also records multiple presses in drag and button-down events.
Dave Love <fx@gnu.org>
parents:
diff changeset
1785 For example, when you press a button twice, then move the mouse while
Dave Love <fx@gnu.org>
parents:
diff changeset
1786 holding the button, Emacs gets a @samp{double-drag-} event. And at the
Dave Love <fx@gnu.org>
parents:
diff changeset
1787 moment when you press it down for the second time, Emacs gets a
Dave Love <fx@gnu.org>
parents:
diff changeset
1788 @samp{double-down-} event (which is ignored, like all button-down
Dave Love <fx@gnu.org>
parents:
diff changeset
1789 events, if it has no binding).
Dave Love <fx@gnu.org>
parents:
diff changeset
1790
Dave Love <fx@gnu.org>
parents:
diff changeset
1791 @vindex double-click-time
38744
d7121931b3ba Show example of specifying C-M-= in Lisp.
Richard M. Stallman <rms@gnu.org>
parents: 38605
diff changeset
1792 The variable @code{double-click-time} specifies how much time can
d7121931b3ba Show example of specifying C-M-= in Lisp.
Richard M. Stallman <rms@gnu.org>
parents: 38605
diff changeset
1793 elapse between clicks and still allow them to be grouped as a multiple
d7121931b3ba Show example of specifying C-M-= in Lisp.
Richard M. Stallman <rms@gnu.org>
parents: 38605
diff changeset
1794 click. Its value is in units of milliseconds. If the value is
d7121931b3ba Show example of specifying C-M-= in Lisp.
Richard M. Stallman <rms@gnu.org>
parents: 38605
diff changeset
1795 @code{nil}, double clicks are not detected at all. If the value is
38771
3e5c99acf21a (Mouse Buttons): Document the default values for double-click-time
Eli Zaretskii <eliz@gnu.org>
parents: 38744
diff changeset
1796 @code{t}, then there is no time limit. The default is 500.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1797
38605
f99d2e5ee830 Add description of double-click-fuzz.
Gerd Moellmann <gerd@gnu.org>
parents: 38376
diff changeset
1798 @vindex double-click-fuzz
f99d2e5ee830 Add description of double-click-fuzz.
Gerd Moellmann <gerd@gnu.org>
parents: 38376
diff changeset
1799 The variable @code{double-click-fuzz} specifies how much the mouse
38744
d7121931b3ba Show example of specifying C-M-= in Lisp.
Richard M. Stallman <rms@gnu.org>
parents: 38605
diff changeset
1800 can move between clicks still allow them to be grouped as a multiple
39060
07afb71a874e (Mouse Buttons): Document the different units of double-click-fuzz
Eli Zaretskii <eliz@gnu.org>
parents: 38870
diff changeset
1801 click. Its value is in units of pixels on windowed displays and in
07afb71a874e (Mouse Buttons): Document the different units of double-click-fuzz
Eli Zaretskii <eliz@gnu.org>
parents: 38870
diff changeset
1802 units of 1/8 of a character cell on text-mode terminals; the default is
07afb71a874e (Mouse Buttons): Document the different units of double-click-fuzz
Eli Zaretskii <eliz@gnu.org>
parents: 38870
diff changeset
1803 3.
38605
f99d2e5ee830 Add description of double-click-fuzz.
Gerd Moellmann <gerd@gnu.org>
parents: 38376
diff changeset
1804
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1805 The symbols for mouse events also indicate the status of the modifier
Dave Love <fx@gnu.org>
parents:
diff changeset
1806 keys, with the usual prefixes @samp{C-}, @samp{M-}, @samp{H-},
Dave Love <fx@gnu.org>
parents:
diff changeset
1807 @samp{s-}, @samp{A-} and @samp{S-}. These always precede @samp{double-}
Dave Love <fx@gnu.org>
parents:
diff changeset
1808 or @samp{triple-}, which always precede @samp{drag-} or @samp{down-}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1809
Dave Love <fx@gnu.org>
parents:
diff changeset
1810 A frame includes areas that don't show text from the buffer, such as
Dave Love <fx@gnu.org>
parents:
diff changeset
1811 the mode line and the scroll bar. You can tell whether a mouse button
Dave Love <fx@gnu.org>
parents:
diff changeset
1812 comes from a special area of the screen by means of dummy ``prefix
Dave Love <fx@gnu.org>
parents:
diff changeset
1813 keys.'' For example, if you click the mouse in the mode line, you get
Dave Love <fx@gnu.org>
parents:
diff changeset
1814 the prefix key @code{mode-line} before the ordinary mouse-button symbol.
Dave Love <fx@gnu.org>
parents:
diff changeset
1815 Thus, here is how to define the command for clicking the first button in
Dave Love <fx@gnu.org>
parents:
diff changeset
1816 a mode line to run @code{scroll-up}:
Dave Love <fx@gnu.org>
parents:
diff changeset
1817
Dave Love <fx@gnu.org>
parents:
diff changeset
1818 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
1819 (global-set-key [mode-line mouse-1] 'scroll-up)
Dave Love <fx@gnu.org>
parents:
diff changeset
1820 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
1821
Dave Love <fx@gnu.org>
parents:
diff changeset
1822 Here is the complete list of these dummy prefix keys and their
Dave Love <fx@gnu.org>
parents:
diff changeset
1823 meanings:
Dave Love <fx@gnu.org>
parents:
diff changeset
1824
Dave Love <fx@gnu.org>
parents:
diff changeset
1825 @table @code
Dave Love <fx@gnu.org>
parents:
diff changeset
1826 @item mode-line
Dave Love <fx@gnu.org>
parents:
diff changeset
1827 The mouse was in the mode line of a window.
Dave Love <fx@gnu.org>
parents:
diff changeset
1828 @item vertical-line
Dave Love <fx@gnu.org>
parents:
diff changeset
1829 The mouse was in the vertical line separating side-by-side windows. (If
Dave Love <fx@gnu.org>
parents:
diff changeset
1830 you use scroll bars, they appear in place of these vertical lines.)
Dave Love <fx@gnu.org>
parents:
diff changeset
1831 @item vertical-scroll-bar
Dave Love <fx@gnu.org>
parents:
diff changeset
1832 The mouse was in a vertical scroll bar. (This is the only kind of
Dave Love <fx@gnu.org>
parents:
diff changeset
1833 scroll bar Emacs currently supports.)
Dave Love <fx@gnu.org>
parents:
diff changeset
1834 @ignore
Dave Love <fx@gnu.org>
parents:
diff changeset
1835 @item horizontal-scroll-bar
Dave Love <fx@gnu.org>
parents:
diff changeset
1836 The mouse was in a horizontal scroll bar. Horizontal scroll bars do
Dave Love <fx@gnu.org>
parents:
diff changeset
1837 horizontal scrolling, and people don't use them often.
Dave Love <fx@gnu.org>
parents:
diff changeset
1838 @end ignore
Dave Love <fx@gnu.org>
parents:
diff changeset
1839 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1840
Dave Love <fx@gnu.org>
parents:
diff changeset
1841 You can put more than one mouse button in a key sequence, but it isn't
Dave Love <fx@gnu.org>
parents:
diff changeset
1842 usual to do so.
Dave Love <fx@gnu.org>
parents:
diff changeset
1843
Dave Love <fx@gnu.org>
parents:
diff changeset
1844 @node Disabling
Dave Love <fx@gnu.org>
parents:
diff changeset
1845 @subsection Disabling Commands
Dave Love <fx@gnu.org>
parents:
diff changeset
1846 @cindex disabled command
Dave Love <fx@gnu.org>
parents:
diff changeset
1847
Dave Love <fx@gnu.org>
parents:
diff changeset
1848 Disabling a command marks the command as requiring confirmation before it
Dave Love <fx@gnu.org>
parents:
diff changeset
1849 can be executed. The purpose of disabling a command is to prevent
Dave Love <fx@gnu.org>
parents:
diff changeset
1850 beginning users from executing it by accident and being confused.
Dave Love <fx@gnu.org>
parents:
diff changeset
1851
Dave Love <fx@gnu.org>
parents:
diff changeset
1852 An attempt to invoke a disabled command interactively in Emacs
Dave Love <fx@gnu.org>
parents:
diff changeset
1853 displays a window containing the command's name, its documentation, and
Dave Love <fx@gnu.org>
parents:
diff changeset
1854 some instructions on what to do immediately; then Emacs asks for input
Dave Love <fx@gnu.org>
parents:
diff changeset
1855 saying whether to execute the command as requested, enable it and
Dave Love <fx@gnu.org>
parents:
diff changeset
1856 execute it, or cancel. If you decide to enable the command, you are
Dave Love <fx@gnu.org>
parents:
diff changeset
1857 asked whether to do this permanently or just for the current session.
37977
5ff6cac52888 Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents: 37976
diff changeset
1858 (Enabling permanently works by automatically editing your @file{.emacs}
5ff6cac52888 Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents: 37976
diff changeset
1859 file.) You can also type @kbd{!} to enable @emph{all} commands,
5ff6cac52888 Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents: 37976
diff changeset
1860 for the current session only.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1861
Dave Love <fx@gnu.org>
parents:
diff changeset
1862 The direct mechanism for disabling a command is to put a
Dave Love <fx@gnu.org>
parents:
diff changeset
1863 non-@code{nil} @code{disabled} property on the Lisp symbol for the
Dave Love <fx@gnu.org>
parents:
diff changeset
1864 command. Here is the Lisp program to do this:
Dave Love <fx@gnu.org>
parents:
diff changeset
1865
Dave Love <fx@gnu.org>
parents:
diff changeset
1866 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
1867 (put 'delete-region 'disabled t)
Dave Love <fx@gnu.org>
parents:
diff changeset
1868 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
1869
Dave Love <fx@gnu.org>
parents:
diff changeset
1870 If the value of the @code{disabled} property is a string, that string
38870
d44abb4e68b2 Don't use "print" for displaying a message.
Richard M. Stallman <rms@gnu.org>
parents: 38791
diff changeset
1871 is included in the message displayed when the command is used:
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1872
Dave Love <fx@gnu.org>
parents:
diff changeset
1873 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
1874 (put 'delete-region 'disabled
Dave Love <fx@gnu.org>
parents:
diff changeset
1875 "It's better to use `kill-region' instead.\n")
Dave Love <fx@gnu.org>
parents:
diff changeset
1876 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
1877
Dave Love <fx@gnu.org>
parents:
diff changeset
1878 @findex disable-command
Dave Love <fx@gnu.org>
parents:
diff changeset
1879 @findex enable-command
Dave Love <fx@gnu.org>
parents:
diff changeset
1880 You can make a command disabled either by editing the @file{.emacs}
Dave Love <fx@gnu.org>
parents:
diff changeset
1881 file directly or with the command @kbd{M-x disable-command}, which edits
Dave Love <fx@gnu.org>
parents:
diff changeset
1882 the @file{.emacs} file for you. Likewise, @kbd{M-x enable-command}
Dave Love <fx@gnu.org>
parents:
diff changeset
1883 edits @file{.emacs} to enable a command permanently. @xref{Init File}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1884
43062
c9d1c7655c9f (Disabling): Document that .emacs is not edited from "emacs -q".
Eli Zaretskii <eliz@gnu.org>
parents: 43038
diff changeset
1885 If Emacs was invoked with the @option{-q} or @option{--no-init-file}
c9d1c7655c9f (Disabling): Document that .emacs is not edited from "emacs -q".
Eli Zaretskii <eliz@gnu.org>
parents: 43038
diff changeset
1886 options (@pxref{Initial Options}), it will not edit your
c9d1c7655c9f (Disabling): Document that .emacs is not edited from "emacs -q".
Eli Zaretskii <eliz@gnu.org>
parents: 43038
diff changeset
1887 @file{~/.emacs} init file. This is because editing the init file from
c9d1c7655c9f (Disabling): Document that .emacs is not edited from "emacs -q".
Eli Zaretskii <eliz@gnu.org>
parents: 43038
diff changeset
1888 such a session might overwrite the lines you might have on your init
c9d1c7655c9f (Disabling): Document that .emacs is not edited from "emacs -q".
Eli Zaretskii <eliz@gnu.org>
parents: 43038
diff changeset
1889 file which enable and disable commands.
c9d1c7655c9f (Disabling): Document that .emacs is not edited from "emacs -q".
Eli Zaretskii <eliz@gnu.org>
parents: 43038
diff changeset
1890
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1891 Whether a command is disabled is independent of what key is used to
Dave Love <fx@gnu.org>
parents:
diff changeset
1892 invoke it; disabling also applies if the command is invoked using
Dave Love <fx@gnu.org>
parents:
diff changeset
1893 @kbd{M-x}. Disabling a command has no effect on calling it as a
Dave Love <fx@gnu.org>
parents:
diff changeset
1894 function from Lisp programs.
Dave Love <fx@gnu.org>
parents:
diff changeset
1895
Dave Love <fx@gnu.org>
parents:
diff changeset
1896 @node Keyboard Translations
Dave Love <fx@gnu.org>
parents:
diff changeset
1897 @section Keyboard Translations
Dave Love <fx@gnu.org>
parents:
diff changeset
1898
Dave Love <fx@gnu.org>
parents:
diff changeset
1899 Some keyboards do not make it convenient to send all the special
Dave Love <fx@gnu.org>
parents:
diff changeset
1900 characters that Emacs uses. The most common problem case is the
Dave Love <fx@gnu.org>
parents:
diff changeset
1901 @key{DEL} character. Some keyboards provide no convenient way to type
Dave Love <fx@gnu.org>
parents:
diff changeset
1902 this very important character---usually because they were designed to
Dave Love <fx@gnu.org>
parents:
diff changeset
1903 expect the character @kbd{C-h} to be used for deletion. On these
Dave Love <fx@gnu.org>
parents:
diff changeset
1904 keyboards, if you press the key normally used for deletion, Emacs handles
Dave Love <fx@gnu.org>
parents:
diff changeset
1905 the @kbd{C-h} as a prefix character and offers you a list of help
Dave Love <fx@gnu.org>
parents:
diff changeset
1906 options, which is not what you want.
Dave Love <fx@gnu.org>
parents:
diff changeset
1907
Dave Love <fx@gnu.org>
parents:
diff changeset
1908 @cindex keyboard translations
Dave Love <fx@gnu.org>
parents:
diff changeset
1909 @findex keyboard-translate
Dave Love <fx@gnu.org>
parents:
diff changeset
1910 You can work around this problem within Emacs by setting up keyboard
Dave Love <fx@gnu.org>
parents:
diff changeset
1911 translations to turn @kbd{C-h} into @key{DEL} and @key{DEL} into
Dave Love <fx@gnu.org>
parents:
diff changeset
1912 @kbd{C-h}, as follows:
Dave Love <fx@gnu.org>
parents:
diff changeset
1913
Dave Love <fx@gnu.org>
parents:
diff changeset
1914 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
1915 ;; @r{Translate @kbd{C-h} to @key{DEL}.}
Dave Love <fx@gnu.org>
parents:
diff changeset
1916 (keyboard-translate ?\C-h ?\C-?)
Dave Love <fx@gnu.org>
parents:
diff changeset
1917
Dave Love <fx@gnu.org>
parents:
diff changeset
1918 ;; @r{Translate @key{DEL} to @kbd{C-h}.}
Dave Love <fx@gnu.org>
parents:
diff changeset
1919 (keyboard-translate ?\C-? ?\C-h)
Dave Love <fx@gnu.org>
parents:
diff changeset
1920 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
1921
Dave Love <fx@gnu.org>
parents:
diff changeset
1922 Keyboard translations are not the same as key bindings in keymaps
Dave Love <fx@gnu.org>
parents:
diff changeset
1923 (@pxref{Keymaps}). Emacs contains numerous keymaps that apply in
Dave Love <fx@gnu.org>
parents:
diff changeset
1924 different situations, but there is only one set of keyboard
Dave Love <fx@gnu.org>
parents:
diff changeset
1925 translations, and it applies to every character that Emacs reads from
Dave Love <fx@gnu.org>
parents:
diff changeset
1926 the terminal. Keyboard translations take place at the lowest level of
Dave Love <fx@gnu.org>
parents:
diff changeset
1927 input processing; the keys that are looked up in keymaps contain the
Dave Love <fx@gnu.org>
parents:
diff changeset
1928 characters that result from keyboard translation.
Dave Love <fx@gnu.org>
parents:
diff changeset
1929
36656
e562b27b8afd DELETE and BACSKPACE are supported on any window system, not only X.
Eli Zaretskii <eliz@gnu.org>
parents: 36632
diff changeset
1930 On a window system, the keyboard key named @key{DELETE} is a function
52979
3649390c0f91 Replace @sc{ascii} and ASCII with @acronym{ASCII}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
1931 key and is distinct from the @acronym{ASCII} character named @key{DEL}.
3649390c0f91 Replace @sc{ascii} and ASCII with @acronym{ASCII}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
1932 @xref{Named ASCII Chars}. Keyboard translations affect only @acronym{ASCII}
36656
e562b27b8afd DELETE and BACSKPACE are supported on any window system, not only X.
Eli Zaretskii <eliz@gnu.org>
parents: 36632
diff changeset
1933 character input, not function keys; thus, the above example used on a
e562b27b8afd DELETE and BACSKPACE are supported on any window system, not only X.
Eli Zaretskii <eliz@gnu.org>
parents: 36632
diff changeset
1934 window system does not affect the @key{DELETE} key. However, the
e562b27b8afd DELETE and BACSKPACE are supported on any window system, not only X.
Eli Zaretskii <eliz@gnu.org>
parents: 36632
diff changeset
1935 translation above isn't necessary on window systems, because Emacs can
e562b27b8afd DELETE and BACSKPACE are supported on any window system, not only X.
Eli Zaretskii <eliz@gnu.org>
parents: 36632
diff changeset
1936 also distinguish between the @key{BACKSPACE} key and @kbd{C-h}; and it
e562b27b8afd DELETE and BACSKPACE are supported on any window system, not only X.
Eli Zaretskii <eliz@gnu.org>
parents: 36632
diff changeset
1937 normally treats @key{BACKSPACE} as @key{DEL}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1938
Dave Love <fx@gnu.org>
parents:
diff changeset
1939 For full information about how to use keyboard translations, see
Dave Love <fx@gnu.org>
parents:
diff changeset
1940 @ref{Translating Input,,,elisp, The Emacs Lisp Reference Manual}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1941
Dave Love <fx@gnu.org>
parents:
diff changeset
1942 @node Syntax
Dave Love <fx@gnu.org>
parents:
diff changeset
1943 @section The Syntax Table
Dave Love <fx@gnu.org>
parents:
diff changeset
1944 @cindex syntax table
Dave Love <fx@gnu.org>
parents:
diff changeset
1945
Dave Love <fx@gnu.org>
parents:
diff changeset
1946 All the Emacs commands which parse words or balance parentheses are
Dave Love <fx@gnu.org>
parents:
diff changeset
1947 controlled by the @dfn{syntax table}. The syntax table says which
Dave Love <fx@gnu.org>
parents:
diff changeset
1948 characters are opening delimiters, which are parts of words, which are
37122
a34d1e2a580f Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents: 36656
diff changeset
1949 string quotes, and so on. It does this by assigning each character to
a34d1e2a580f Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents: 36656
diff changeset
1950 one of fifteen-odd @dfn{syntax classes}. In some cases it specifies
a34d1e2a580f Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents: 36656
diff changeset
1951 some additional information also.
a34d1e2a580f Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents: 36656
diff changeset
1952
38114
4face9462576 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 37977
diff changeset
1953 Each major mode has its own syntax table (though related major modes
4face9462576 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 37977
diff changeset
1954 sometimes share one syntax table) which it installs in each buffer
37122
a34d1e2a580f Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents: 36656
diff changeset
1955 that uses the mode. The syntax table installed in the current buffer
a34d1e2a580f Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents: 36656
diff changeset
1956 is the one that all commands use, so we call it ``the'' syntax table.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1957
Dave Love <fx@gnu.org>
parents:
diff changeset
1958 @kindex C-h s
Dave Love <fx@gnu.org>
parents:
diff changeset
1959 @findex describe-syntax
37122
a34d1e2a580f Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents: 36656
diff changeset
1960 To display a description of the contents of the current syntax
a34d1e2a580f Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents: 36656
diff changeset
1961 table, type @kbd{C-h s} (@code{describe-syntax}). The description of
a34d1e2a580f Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents: 36656
diff changeset
1962 each character includes both the string you would have to give to
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1963 @code{modify-syntax-entry} to set up that character's current syntax,
37122
a34d1e2a580f Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents: 36656
diff changeset
1964 starting with the character which designates its syntax class, plus
a34d1e2a580f Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents: 36656
diff changeset
1965 some English text to explain its meaning.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1966
37122
a34d1e2a580f Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents: 36656
diff changeset
1967 A syntax table is actually a Lisp object, a char-table, whose
a34d1e2a580f Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents: 36656
diff changeset
1968 elements are cons cells. For full information on the syntax table,
a34d1e2a580f Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents: 36656
diff changeset
1969 see @ref{Syntax Tables,, Syntax Tables, elisp, The Emacs Lisp
a34d1e2a580f Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents: 36656
diff changeset
1970 Reference Manual}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1971
Dave Love <fx@gnu.org>
parents:
diff changeset
1972 @node Init File
Dave Love <fx@gnu.org>
parents:
diff changeset
1973 @section The Init File, @file{~/.emacs}
Dave Love <fx@gnu.org>
parents:
diff changeset
1974 @cindex init file
Dave Love <fx@gnu.org>
parents:
diff changeset
1975 @cindex Emacs initialization file
Dave Love <fx@gnu.org>
parents:
diff changeset
1976 @cindex key rebinding, permanent
Dave Love <fx@gnu.org>
parents:
diff changeset
1977 @cindex rebinding keys, permanently
Dave Love <fx@gnu.org>
parents:
diff changeset
1978 @cindex startup (init file)
Dave Love <fx@gnu.org>
parents:
diff changeset
1979
59949
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1980 When Emacs is started, it normally loads a Lisp program from the
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1981 file @file{.emacs} or @file{.emacs.el} in your home directory. (You
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1982 can also put it in a subdirectory @file{~/.emacs.d} and Emacs will
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1983 still find it.) We call this file your @dfn{init file} because it
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1984 specifies how to initialize Emacs for you. You can use the command
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1985 line switch @samp{-q} to prevent loading your init file, and @samp{-u}
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1986 (or @samp{--user}) to specify a different user's init file
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
1987 (@pxref{Initial Options}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1988
37596
47f8d088e385 (Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents: 37581
diff changeset
1989 @cindex @file{default.el}, the default init file
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1990 There can also be a @dfn{default init file}, which is the library
Dave Love <fx@gnu.org>
parents:
diff changeset
1991 named @file{default.el}, found via the standard search path for
Dave Love <fx@gnu.org>
parents:
diff changeset
1992 libraries. The Emacs distribution contains no such library; your site
Dave Love <fx@gnu.org>
parents:
diff changeset
1993 may create one for local customizations. If this library exists, it is
Dave Love <fx@gnu.org>
parents:
diff changeset
1994 loaded whenever you start Emacs (except when you specify @samp{-q}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1995 But your init file, if any, is loaded first; if it sets
Dave Love <fx@gnu.org>
parents:
diff changeset
1996 @code{inhibit-default-init} non-@code{nil}, then @file{default} is not
Dave Love <fx@gnu.org>
parents:
diff changeset
1997 loaded.
Dave Love <fx@gnu.org>
parents:
diff changeset
1998
37596
47f8d088e385 (Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents: 37581
diff changeset
1999 @cindex site init file
47f8d088e385 (Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents: 37581
diff changeset
2000 @cindex @file{site-start.el}, the site startup file
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2001 Your site may also have a @dfn{site startup file}; this is named
37596
47f8d088e385 (Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents: 37581
diff changeset
2002 @file{site-start.el}, if it exists. Like @file{default.el}, Emacs
47f8d088e385 (Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents: 37581
diff changeset
2003 finds this file via the standard search path for Lisp libraries.
47f8d088e385 (Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents: 37581
diff changeset
2004 Emacs loads this library before it loads your init file. To inhibit
55834
a32af30ee1a1 (Init File): Two dashes start --no-site-file.
Richard M. Stallman <rms@gnu.org>
parents: 54723
diff changeset
2005 loading of this library, use the option @samp{--no-site-file}.
37596
47f8d088e385 (Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents: 37581
diff changeset
2006 @xref{Initial Options}.
47f8d088e385 (Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents: 37581
diff changeset
2007
47f8d088e385 (Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents: 37581
diff changeset
2008 You can place @file{default.el} and @file{site-start.el} in any of
47f8d088e385 (Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents: 37581
diff changeset
2009 the directories which Emacs searches for Lisp libraries. The variable
47f8d088e385 (Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents: 37581
diff changeset
2010 @code{load-path} (@pxref{Lisp Libraries}) specifies these directories.
47f8d088e385 (Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents: 37581
diff changeset
2011 Many sites put these files in the @file{site-lisp} subdirectory of the
47f8d088e385 (Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents: 37581
diff changeset
2012 Emacs installation directory, typically
47f8d088e385 (Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents: 37581
diff changeset
2013 @file{/usr/local/share/emacs/site-lisp}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2014
Dave Love <fx@gnu.org>
parents:
diff changeset
2015 If you have a large amount of code in your @file{.emacs} file, you
Dave Love <fx@gnu.org>
parents:
diff changeset
2016 should rename it to @file{~/.emacs.el}, and byte-compile it. @xref{Byte
Dave Love <fx@gnu.org>
parents:
diff changeset
2017 Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference Manual},
Dave Love <fx@gnu.org>
parents:
diff changeset
2018 for more information about compiling Emacs Lisp programs.
Dave Love <fx@gnu.org>
parents:
diff changeset
2019
Dave Love <fx@gnu.org>
parents:
diff changeset
2020 If you are going to write actual Emacs Lisp programs that go beyond
Dave Love <fx@gnu.org>
parents:
diff changeset
2021 minor customization, you should read the @cite{Emacs Lisp Reference Manual}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2022 @ifinfo
Dave Love <fx@gnu.org>
parents:
diff changeset
2023 @xref{Top, Emacs Lisp, Emacs Lisp, elisp, the Emacs Lisp Reference
Dave Love <fx@gnu.org>
parents:
diff changeset
2024 Manual}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2025 @end ifinfo
Dave Love <fx@gnu.org>
parents:
diff changeset
2026
Dave Love <fx@gnu.org>
parents:
diff changeset
2027 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
2028 * Init Syntax:: Syntax of constants in Emacs Lisp.
Dave Love <fx@gnu.org>
parents:
diff changeset
2029 * Init Examples:: How to do some things with an init file.
Dave Love <fx@gnu.org>
parents:
diff changeset
2030 * Terminal Init:: Each terminal type can have an init file.
Dave Love <fx@gnu.org>
parents:
diff changeset
2031 * Find Init:: How Emacs finds the init file.
Dave Love <fx@gnu.org>
parents:
diff changeset
2032 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
2033
Dave Love <fx@gnu.org>
parents:
diff changeset
2034 @node Init Syntax
Dave Love <fx@gnu.org>
parents:
diff changeset
2035 @subsection Init File Syntax
Dave Love <fx@gnu.org>
parents:
diff changeset
2036
Dave Love <fx@gnu.org>
parents:
diff changeset
2037 The @file{.emacs} file contains one or more Lisp function call
Dave Love <fx@gnu.org>
parents:
diff changeset
2038 expressions. Each of these consists of a function name followed by
Dave Love <fx@gnu.org>
parents:
diff changeset
2039 arguments, all surrounded by parentheses. For example, @code{(setq
Dave Love <fx@gnu.org>
parents:
diff changeset
2040 fill-column 60)} calls the function @code{setq} to set the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
2041 @code{fill-column} (@pxref{Filling}) to 60.
Dave Love <fx@gnu.org>
parents:
diff changeset
2042
56085
e6cc673c5461 (Init Syntax): Explain about vars that do special
Richard M. Stallman <rms@gnu.org>
parents: 55834
diff changeset
2043 You can set any Lisp variable with @code{setq}, but with certain
e6cc673c5461 (Init Syntax): Explain about vars that do special
Richard M. Stallman <rms@gnu.org>
parents: 55834
diff changeset
2044 variables @code{setq} won't do what you probably want in the
e6cc673c5461 (Init Syntax): Explain about vars that do special
Richard M. Stallman <rms@gnu.org>
parents: 55834
diff changeset
2045 @file{.emacs} file. Some variables automatically become buffer-local
e6cc673c5461 (Init Syntax): Explain about vars that do special
Richard M. Stallman <rms@gnu.org>
parents: 55834
diff changeset
2046 when set with @code{setq}; what you want in @file{.emacs} is to set
e6cc673c5461 (Init Syntax): Explain about vars that do special
Richard M. Stallman <rms@gnu.org>
parents: 55834
diff changeset
2047 the default value, using @code{setq-default}. Some customizable minor
e6cc673c5461 (Init Syntax): Explain about vars that do special
Richard M. Stallman <rms@gnu.org>
parents: 55834
diff changeset
2048 mode variables do special things to enable the mode when you set them
e6cc673c5461 (Init Syntax): Explain about vars that do special
Richard M. Stallman <rms@gnu.org>
parents: 55834
diff changeset
2049 with Customize, but ordinary @code{setq} won't do that; to enable the
e6cc673c5461 (Init Syntax): Explain about vars that do special
Richard M. Stallman <rms@gnu.org>
parents: 55834
diff changeset
2050 mode in your @file{.emacs} file, call the minor mode command. The
e6cc673c5461 (Init Syntax): Explain about vars that do special
Richard M. Stallman <rms@gnu.org>
parents: 55834
diff changeset
2051 following section has examples of both of these methods.
e6cc673c5461 (Init Syntax): Explain about vars that do special
Richard M. Stallman <rms@gnu.org>
parents: 55834
diff changeset
2052
e6cc673c5461 (Init Syntax): Explain about vars that do special
Richard M. Stallman <rms@gnu.org>
parents: 55834
diff changeset
2053 The second argument to @code{setq} is an expression for the new
e6cc673c5461 (Init Syntax): Explain about vars that do special
Richard M. Stallman <rms@gnu.org>
parents: 55834
diff changeset
2054 value of the variable. This can be a constant, a variable, or a
e6cc673c5461 (Init Syntax): Explain about vars that do special
Richard M. Stallman <rms@gnu.org>
parents: 55834
diff changeset
2055 function call expression. In @file{.emacs}, constants are used most
e6cc673c5461 (Init Syntax): Explain about vars that do special
Richard M. Stallman <rms@gnu.org>
parents: 55834
diff changeset
2056 of the time. They can be:
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2057
Dave Love <fx@gnu.org>
parents:
diff changeset
2058 @table @asis
Dave Love <fx@gnu.org>
parents:
diff changeset
2059 @item Numbers:
Dave Love <fx@gnu.org>
parents:
diff changeset
2060 Numbers are written in decimal, with an optional initial minus sign.
Dave Love <fx@gnu.org>
parents:
diff changeset
2061
Dave Love <fx@gnu.org>
parents:
diff changeset
2062 @item Strings:
Dave Love <fx@gnu.org>
parents:
diff changeset
2063 @cindex Lisp string syntax
Dave Love <fx@gnu.org>
parents:
diff changeset
2064 @cindex string syntax
Dave Love <fx@gnu.org>
parents:
diff changeset
2065 Lisp string syntax is the same as C string syntax with a few extra
Dave Love <fx@gnu.org>
parents:
diff changeset
2066 features. Use a double-quote character to begin and end a string constant.
Dave Love <fx@gnu.org>
parents:
diff changeset
2067
Dave Love <fx@gnu.org>
parents:
diff changeset
2068 In a string, you can include newlines and special characters literally.
Dave Love <fx@gnu.org>
parents:
diff changeset
2069 But often it is cleaner to use backslash sequences for them: @samp{\n}
Dave Love <fx@gnu.org>
parents:
diff changeset
2070 for newline, @samp{\b} for backspace, @samp{\r} for carriage return,
Dave Love <fx@gnu.org>
parents:
diff changeset
2071 @samp{\t} for tab, @samp{\f} for formfeed (control-L), @samp{\e} for
Dave Love <fx@gnu.org>
parents:
diff changeset
2072 escape, @samp{\\} for a backslash, @samp{\"} for a double-quote, or
Dave Love <fx@gnu.org>
parents:
diff changeset
2073 @samp{\@var{ooo}} for the character whose octal code is @var{ooo}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2074 Backslash and double-quote are the only characters for which backslash
Dave Love <fx@gnu.org>
parents:
diff changeset
2075 sequences are mandatory.
Dave Love <fx@gnu.org>
parents:
diff changeset
2076
Dave Love <fx@gnu.org>
parents:
diff changeset
2077 @samp{\C-} can be used as a prefix for a control character, as in
52979
3649390c0f91 Replace @sc{ascii} and ASCII with @acronym{ASCII}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
2078 @samp{\C-s} for @acronym{ASCII} control-S, and @samp{\M-} can be used as a prefix for
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2079 a Meta character, as in @samp{\M-a} for @kbd{Meta-A} or @samp{\M-\C-a} for
Dave Love <fx@gnu.org>
parents:
diff changeset
2080 @kbd{Control-Meta-A}.@refill
Dave Love <fx@gnu.org>
parents:
diff changeset
2081
37198
12c496043cb0 (Init Syntax): Mention the -*-coding:-*- tag if .emacs uses non-ASCII
Eli Zaretskii <eliz@gnu.org>
parents: 37122
diff changeset
2082 @cindex international characters in @file{.emacs}
52979
3649390c0f91 Replace @sc{ascii} and ASCII with @acronym{ASCII}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
2083 @cindex non-@acronym{ASCII} characters in @file{.emacs}
3649390c0f91 Replace @sc{ascii} and ASCII with @acronym{ASCII}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
2084 If you want to include non-@acronym{ASCII} characters in strings in your init
37354
39aa69a68098 (Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents: 37265
diff changeset
2085 file, you should consider putting a @w{@samp{-*-coding:
39aa69a68098 (Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents: 37265
diff changeset
2086 @var{coding-system}-*-}} tag on the first line which states the coding
37265
d2c4a8eb274a (Init Syntax): Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents: 37198
diff changeset
2087 system used to save your @file{.emacs}, as explained in @ref{Recognize
52979
3649390c0f91 Replace @sc{ascii} and ASCII with @acronym{ASCII}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
2088 Coding}. This is because the defaults for decoding non-@acronym{ASCII} text might
37265
d2c4a8eb274a (Init Syntax): Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents: 37198
diff changeset
2089 not yet be set up by the time Emacs reads those parts of your init file
d2c4a8eb274a (Init Syntax): Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents: 37198
diff changeset
2090 which use such strings, possibly leading Emacs to decode those strings
d2c4a8eb274a (Init Syntax): Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents: 37198
diff changeset
2091 incorrectly.
37198
12c496043cb0 (Init Syntax): Mention the -*-coding:-*- tag if .emacs uses non-ASCII
Eli Zaretskii <eliz@gnu.org>
parents: 37122
diff changeset
2092
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2093 @item Characters:
Dave Love <fx@gnu.org>
parents:
diff changeset
2094 Lisp character constant syntax consists of a @samp{?} followed by
Dave Love <fx@gnu.org>
parents:
diff changeset
2095 either a character or an escape sequence starting with @samp{\}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2096 Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that
Dave Love <fx@gnu.org>
parents:
diff changeset
2097 strings and characters are not interchangeable in Lisp; some contexts
Dave Love <fx@gnu.org>
parents:
diff changeset
2098 require one and some contexts require the other.
Dave Love <fx@gnu.org>
parents:
diff changeset
2099
37354
39aa69a68098 (Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents: 37265
diff changeset
2100 @xref{Non-ASCII Rebinding}, for information about binding commands to
52979
3649390c0f91 Replace @sc{ascii} and ASCII with @acronym{ASCII}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
2101 keys which send non-@acronym{ASCII} characters.
37354
39aa69a68098 (Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents: 37265
diff changeset
2102
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2103 @item True:
Dave Love <fx@gnu.org>
parents:
diff changeset
2104 @code{t} stands for `true'.
Dave Love <fx@gnu.org>
parents:
diff changeset
2105
Dave Love <fx@gnu.org>
parents:
diff changeset
2106 @item False:
Dave Love <fx@gnu.org>
parents:
diff changeset
2107 @code{nil} stands for `false'.
Dave Love <fx@gnu.org>
parents:
diff changeset
2108
Dave Love <fx@gnu.org>
parents:
diff changeset
2109 @item Other Lisp objects:
37976
23dc2eca0bd3 Proofreading changes from Tim Goodwin <tjg@star.le.ac.uk>.
Eli Zaretskii <eliz@gnu.org>
parents: 37843
diff changeset
2110 Write a single-quote (@code{'}) followed by the Lisp object you want.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2111 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
2112
Dave Love <fx@gnu.org>
parents:
diff changeset
2113 @node Init Examples
Dave Love <fx@gnu.org>
parents:
diff changeset
2114 @subsection Init File Examples
Dave Love <fx@gnu.org>
parents:
diff changeset
2115
Dave Love <fx@gnu.org>
parents:
diff changeset
2116 Here are some examples of doing certain commonly desired things with
Dave Love <fx@gnu.org>
parents:
diff changeset
2117 Lisp expressions:
Dave Love <fx@gnu.org>
parents:
diff changeset
2118
Dave Love <fx@gnu.org>
parents:
diff changeset
2119 @itemize @bullet
Dave Love <fx@gnu.org>
parents:
diff changeset
2120 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
2121 Make @key{TAB} in C mode just insert a tab if point is in the middle of a
Dave Love <fx@gnu.org>
parents:
diff changeset
2122 line.
Dave Love <fx@gnu.org>
parents:
diff changeset
2123
Dave Love <fx@gnu.org>
parents:
diff changeset
2124 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2125 (setq c-tab-always-indent nil)
Dave Love <fx@gnu.org>
parents:
diff changeset
2126 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
2127
Dave Love <fx@gnu.org>
parents:
diff changeset
2128 Here we have a variable whose value is normally @code{t} for `true'
Dave Love <fx@gnu.org>
parents:
diff changeset
2129 and the alternative is @code{nil} for `false'.
Dave Love <fx@gnu.org>
parents:
diff changeset
2130
Dave Love <fx@gnu.org>
parents:
diff changeset
2131 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
2132 Make searches case sensitive by default (in all buffers that do not
Dave Love <fx@gnu.org>
parents:
diff changeset
2133 override this).
Dave Love <fx@gnu.org>
parents:
diff changeset
2134
Dave Love <fx@gnu.org>
parents:
diff changeset
2135 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2136 (setq-default case-fold-search nil)
Dave Love <fx@gnu.org>
parents:
diff changeset
2137 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
2138
Dave Love <fx@gnu.org>
parents:
diff changeset
2139 This sets the default value, which is effective in all buffers that do
Dave Love <fx@gnu.org>
parents:
diff changeset
2140 not have local values for the variable. Setting @code{case-fold-search}
Dave Love <fx@gnu.org>
parents:
diff changeset
2141 with @code{setq} affects only the current buffer's local value, which
Dave Love <fx@gnu.org>
parents:
diff changeset
2142 is not what you probably want to do in an init file.
Dave Love <fx@gnu.org>
parents:
diff changeset
2143
Dave Love <fx@gnu.org>
parents:
diff changeset
2144 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
2145 @vindex user-mail-address
Dave Love <fx@gnu.org>
parents:
diff changeset
2146 Specify your own email address, if Emacs can't figure it out correctly.
Dave Love <fx@gnu.org>
parents:
diff changeset
2147
Dave Love <fx@gnu.org>
parents:
diff changeset
2148 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2149 (setq user-mail-address "coon@@yoyodyne.com")
Dave Love <fx@gnu.org>
parents:
diff changeset
2150 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
2151
Dave Love <fx@gnu.org>
parents:
diff changeset
2152 Various Emacs packages that need your own email address use the value of
Dave Love <fx@gnu.org>
parents:
diff changeset
2153 @code{user-mail-address}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2154
Dave Love <fx@gnu.org>
parents:
diff changeset
2155 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
2156 Make Text mode the default mode for new buffers.
Dave Love <fx@gnu.org>
parents:
diff changeset
2157
Dave Love <fx@gnu.org>
parents:
diff changeset
2158 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2159 (setq default-major-mode 'text-mode)
Dave Love <fx@gnu.org>
parents:
diff changeset
2160 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
2161
Dave Love <fx@gnu.org>
parents:
diff changeset
2162 Note that @code{text-mode} is used because it is the command for
Dave Love <fx@gnu.org>
parents:
diff changeset
2163 entering Text mode. The single-quote before it makes the symbol a
Dave Love <fx@gnu.org>
parents:
diff changeset
2164 constant; otherwise, @code{text-mode} would be treated as a variable
Dave Love <fx@gnu.org>
parents:
diff changeset
2165 name.
Dave Love <fx@gnu.org>
parents:
diff changeset
2166
Dave Love <fx@gnu.org>
parents:
diff changeset
2167 @need 1500
Dave Love <fx@gnu.org>
parents:
diff changeset
2168 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
2169 Set up defaults for the Latin-1 character set
Dave Love <fx@gnu.org>
parents:
diff changeset
2170 which supports most of the languages of Western Europe.
Dave Love <fx@gnu.org>
parents:
diff changeset
2171
Dave Love <fx@gnu.org>
parents:
diff changeset
2172 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2173 (set-language-environment "Latin-1")
Dave Love <fx@gnu.org>
parents:
diff changeset
2174 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
2175
Dave Love <fx@gnu.org>
parents:
diff changeset
2176 @need 1500
Dave Love <fx@gnu.org>
parents:
diff changeset
2177 @item
56085
e6cc673c5461 (Init Syntax): Explain about vars that do special
Richard M. Stallman <rms@gnu.org>
parents: 55834
diff changeset
2178 Turn off Line Number mode, a global minor mode.
e6cc673c5461 (Init Syntax): Explain about vars that do special
Richard M. Stallman <rms@gnu.org>
parents: 55834
diff changeset
2179
e6cc673c5461 (Init Syntax): Explain about vars that do special
Richard M. Stallman <rms@gnu.org>
parents: 55834
diff changeset
2180 @example
e6cc673c5461 (Init Syntax): Explain about vars that do special
Richard M. Stallman <rms@gnu.org>
parents: 55834
diff changeset
2181 (line-number-mode 0)
e6cc673c5461 (Init Syntax): Explain about vars that do special
Richard M. Stallman <rms@gnu.org>
parents: 55834
diff changeset
2182 @end example
e6cc673c5461 (Init Syntax): Explain about vars that do special
Richard M. Stallman <rms@gnu.org>
parents: 55834
diff changeset
2183
e6cc673c5461 (Init Syntax): Explain about vars that do special
Richard M. Stallman <rms@gnu.org>
parents: 55834
diff changeset
2184 @need 1500
e6cc673c5461 (Init Syntax): Explain about vars that do special
Richard M. Stallman <rms@gnu.org>
parents: 55834
diff changeset
2185 @item
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2186 Turn on Auto Fill mode automatically in Text mode and related modes.
Dave Love <fx@gnu.org>
parents:
diff changeset
2187
Dave Love <fx@gnu.org>
parents:
diff changeset
2188 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2189 (add-hook 'text-mode-hook
36148
a2719b6e7a2f Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents: 35188
diff changeset
2190 '(lambda () (auto-fill-mode 1)))
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2191 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
2192
Dave Love <fx@gnu.org>
parents:
diff changeset
2193 This shows how to add a hook function to a normal hook variable
Dave Love <fx@gnu.org>
parents:
diff changeset
2194 (@pxref{Hooks}). The function we supply is a list starting with
Dave Love <fx@gnu.org>
parents:
diff changeset
2195 @code{lambda}, with a single-quote in front of it to make it a list
Dave Love <fx@gnu.org>
parents:
diff changeset
2196 constant rather than an expression.
Dave Love <fx@gnu.org>
parents:
diff changeset
2197
Dave Love <fx@gnu.org>
parents:
diff changeset
2198 It's beyond the scope of this manual to explain Lisp functions, but for
Dave Love <fx@gnu.org>
parents:
diff changeset
2199 this example it is enough to know that the effect is to execute
Dave Love <fx@gnu.org>
parents:
diff changeset
2200 @code{(auto-fill-mode 1)} when Text mode is entered. You can replace
Dave Love <fx@gnu.org>
parents:
diff changeset
2201 that with any other expression that you like, or with several
Dave Love <fx@gnu.org>
parents:
diff changeset
2202 expressions in a row.
Dave Love <fx@gnu.org>
parents:
diff changeset
2203
Dave Love <fx@gnu.org>
parents:
diff changeset
2204 Emacs comes with a function named @code{turn-on-auto-fill} whose
Dave Love <fx@gnu.org>
parents:
diff changeset
2205 definition is @code{(lambda () (auto-fill-mode 1))}. Thus, a simpler
Dave Love <fx@gnu.org>
parents:
diff changeset
2206 way to write the above example is as follows:
Dave Love <fx@gnu.org>
parents:
diff changeset
2207
Dave Love <fx@gnu.org>
parents:
diff changeset
2208 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2209 (add-hook 'text-mode-hook 'turn-on-auto-fill)
Dave Love <fx@gnu.org>
parents:
diff changeset
2210 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
2211
Dave Love <fx@gnu.org>
parents:
diff changeset
2212 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
2213 Load the installed Lisp library named @file{foo} (actually a file
Dave Love <fx@gnu.org>
parents:
diff changeset
2214 @file{foo.elc} or @file{foo.el} in a standard Emacs directory).
Dave Love <fx@gnu.org>
parents:
diff changeset
2215
Dave Love <fx@gnu.org>
parents:
diff changeset
2216 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2217 (load "foo")
Dave Love <fx@gnu.org>
parents:
diff changeset
2218 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
2219
Dave Love <fx@gnu.org>
parents:
diff changeset
2220 When the argument to @code{load} is a relative file name, not starting
Dave Love <fx@gnu.org>
parents:
diff changeset
2221 with @samp{/} or @samp{~}, @code{load} searches the directories in
Dave Love <fx@gnu.org>
parents:
diff changeset
2222 @code{load-path} (@pxref{Lisp Libraries}).
Dave Love <fx@gnu.org>
parents:
diff changeset
2223
Dave Love <fx@gnu.org>
parents:
diff changeset
2224 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
2225 Load the compiled Lisp file @file{foo.elc} from your home directory.
Dave Love <fx@gnu.org>
parents:
diff changeset
2226
Dave Love <fx@gnu.org>
parents:
diff changeset
2227 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2228 (load "~/foo.elc")
Dave Love <fx@gnu.org>
parents:
diff changeset
2229 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
2230
Dave Love <fx@gnu.org>
parents:
diff changeset
2231 Here an absolute file name is used, so no searching is done.
Dave Love <fx@gnu.org>
parents:
diff changeset
2232
Dave Love <fx@gnu.org>
parents:
diff changeset
2233 @item
37354
39aa69a68098 (Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents: 37265
diff changeset
2234 @cindex loading Lisp libraries automatically
39aa69a68098 (Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents: 37265
diff changeset
2235 @cindex autoload Lisp libraries
38114
4face9462576 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 37977
diff changeset
2236 Tell Emacs to find the definition for the function @code{myfunction}
4face9462576 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 37977
diff changeset
2237 by loading a Lisp library named @file{mypackage} (i.e.@: a file
4face9462576 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 37977
diff changeset
2238 @file{mypackage.elc} or @file{mypackage.el}):
37354
39aa69a68098 (Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents: 37265
diff changeset
2239
39aa69a68098 (Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents: 37265
diff changeset
2240 @example
39aa69a68098 (Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents: 37265
diff changeset
2241 (autoload 'myfunction "mypackage" "Do what I say." t)
39aa69a68098 (Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents: 37265
diff changeset
2242 @end example
39aa69a68098 (Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents: 37265
diff changeset
2243
39aa69a68098 (Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents: 37265
diff changeset
2244 @noindent
38114
4face9462576 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 37977
diff changeset
2245 Here the string @code{"Do what I say."} is the function's
4face9462576 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 37977
diff changeset
2246 documentation string. You specify it in the @code{autoload}
4face9462576 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 37977
diff changeset
2247 definition so it will be available for help commands even when the
4face9462576 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 37977
diff changeset
2248 package is not loaded. The last argument, @code{t}, indicates that
4face9462576 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 37977
diff changeset
2249 this function is interactive; that is, it can be invoked interactively
4face9462576 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 37977
diff changeset
2250 by typing @kbd{M-x myfunction @key{RET}} or by binding it to a key.
4face9462576 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 37977
diff changeset
2251 If the function is not interactive, omit the @code{t} or use
4face9462576 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 37977
diff changeset
2252 @code{nil}.
37354
39aa69a68098 (Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents: 37265
diff changeset
2253
39aa69a68098 (Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents: 37265
diff changeset
2254 @item
59949
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
2255 Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}
59961
f8a952f61ced (Init Examples): Fix previous fix.
Lute Kamstra <lute@gnu.org>
parents: 59957
diff changeset
2256 (@pxref{Init Rebinding}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2257
Dave Love <fx@gnu.org>
parents:
diff changeset
2258 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2259 (global-set-key "\C-xl" 'make-symbolic-link)
Dave Love <fx@gnu.org>
parents:
diff changeset
2260 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
2261
Dave Love <fx@gnu.org>
parents:
diff changeset
2262 or
Dave Love <fx@gnu.org>
parents:
diff changeset
2263
Dave Love <fx@gnu.org>
parents:
diff changeset
2264 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2265 (define-key global-map "\C-xl" 'make-symbolic-link)
Dave Love <fx@gnu.org>
parents:
diff changeset
2266 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
2267
Dave Love <fx@gnu.org>
parents:
diff changeset
2268 Note once again the single-quote used to refer to the symbol
Dave Love <fx@gnu.org>
parents:
diff changeset
2269 @code{make-symbolic-link} instead of its value as a variable.
Dave Love <fx@gnu.org>
parents:
diff changeset
2270
Dave Love <fx@gnu.org>
parents:
diff changeset
2271 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
2272 Do the same thing for Lisp mode only.
Dave Love <fx@gnu.org>
parents:
diff changeset
2273
Dave Love <fx@gnu.org>
parents:
diff changeset
2274 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2275 (define-key lisp-mode-map "\C-xl" 'make-symbolic-link)
Dave Love <fx@gnu.org>
parents:
diff changeset
2276 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
2277
Dave Love <fx@gnu.org>
parents:
diff changeset
2278 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
2279 Redefine all keys which now run @code{next-line} in Fundamental mode
Dave Love <fx@gnu.org>
parents:
diff changeset
2280 so that they run @code{forward-line} instead.
Dave Love <fx@gnu.org>
parents:
diff changeset
2281
26392
b3d3ff9a7a2c *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25829
diff changeset
2282 @findex substitute-key-definition
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2283 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2284 (substitute-key-definition 'next-line 'forward-line
Dave Love <fx@gnu.org>
parents:
diff changeset
2285 global-map)
Dave Love <fx@gnu.org>
parents:
diff changeset
2286 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
2287
Dave Love <fx@gnu.org>
parents:
diff changeset
2288 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
2289 Make @kbd{C-x C-v} undefined.
Dave Love <fx@gnu.org>
parents:
diff changeset
2290
Dave Love <fx@gnu.org>
parents:
diff changeset
2291 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2292 (global-unset-key "\C-x\C-v")
Dave Love <fx@gnu.org>
parents:
diff changeset
2293 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
2294
Dave Love <fx@gnu.org>
parents:
diff changeset
2295 One reason to undefine a key is so that you can make it a prefix.
Dave Love <fx@gnu.org>
parents:
diff changeset
2296 Simply defining @kbd{C-x C-v @var{anything}} will make @kbd{C-x C-v} a
Dave Love <fx@gnu.org>
parents:
diff changeset
2297 prefix, but @kbd{C-x C-v} must first be freed of its usual non-prefix
Dave Love <fx@gnu.org>
parents:
diff changeset
2298 definition.
Dave Love <fx@gnu.org>
parents:
diff changeset
2299
Dave Love <fx@gnu.org>
parents:
diff changeset
2300 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
2301 Make @samp{$} have the syntax of punctuation in Text mode.
Dave Love <fx@gnu.org>
parents:
diff changeset
2302 Note the use of a character constant for @samp{$}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2303
Dave Love <fx@gnu.org>
parents:
diff changeset
2304 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2305 (modify-syntax-entry ?\$ "." text-mode-syntax-table)
Dave Love <fx@gnu.org>
parents:
diff changeset
2306 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
2307
Dave Love <fx@gnu.org>
parents:
diff changeset
2308 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
2309 Enable the use of the command @code{narrow-to-region} without confirmation.
Dave Love <fx@gnu.org>
parents:
diff changeset
2310
Dave Love <fx@gnu.org>
parents:
diff changeset
2311 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2312 (put 'narrow-to-region 'disabled nil)
Dave Love <fx@gnu.org>
parents:
diff changeset
2313 @end example
61606
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2314
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2315 @item
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2316 Adjusting the configuration to various contexts.
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2317
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2318 In most of the cases, people want their Emacs to behave the same on
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2319 all their machines, so their configuration should be the same, no
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2320 matter whether it's GNU/Linux or not, under X11 or on a tty, with one
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2321 version of Emacs or another, ...
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2322
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2323 What can happen, tho, is that depending on the circumstance some
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2324 features may or may not be available. In that case just prepend each
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2325 such customization with a little test that ensures that the feature
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2326 can be used. The best tests are usually checking that the feature is
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2327 available, rather than checking what kind of environment is
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2328 being used.
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2329
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2330 @example
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2331 (if (fboundp 'blinking-cursor-mode)
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2332 (blinking-cursor-mode 0))
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2333 @end example
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2334
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2335 @example
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2336 (if (boundp 'coding-category-utf-8)
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2337 (set-coding-priority '(coding-category-utf-8)))
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2338 @end example
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2339
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2340 @example
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2341 (require 'cl) ; To define `ignore-errors'.
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2342 (ignore-errors (set-face-background 'region "grey75"))
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2343 @end example
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2344
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2345 Note also that a @code{setq} on a variable which does not exist is
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2346 generally harmless, so those usually do not need to be made
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2347 conditional on any kind of test.
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2348
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2349 @end itemize
Dave Love <fx@gnu.org>
parents:
diff changeset
2350
61606
e348d86e70f8 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 61051
diff changeset
2351
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2352 @node Terminal Init
Dave Love <fx@gnu.org>
parents:
diff changeset
2353 @subsection Terminal-specific Initialization
Dave Love <fx@gnu.org>
parents:
diff changeset
2354
Dave Love <fx@gnu.org>
parents:
diff changeset
2355 Each terminal type can have a Lisp library to be loaded into Emacs when
Dave Love <fx@gnu.org>
parents:
diff changeset
2356 it is run on that type of terminal. For a terminal type named
Dave Love <fx@gnu.org>
parents:
diff changeset
2357 @var{termtype}, the library is called @file{term/@var{termtype}} and it is
Dave Love <fx@gnu.org>
parents:
diff changeset
2358 found by searching the directories @code{load-path} as usual and trying the
Dave Love <fx@gnu.org>
parents:
diff changeset
2359 suffixes @samp{.elc} and @samp{.el}. Normally it appears in the
Dave Love <fx@gnu.org>
parents:
diff changeset
2360 subdirectory @file{term} of the directory where most Emacs libraries are
Dave Love <fx@gnu.org>
parents:
diff changeset
2361 kept.@refill
Dave Love <fx@gnu.org>
parents:
diff changeset
2362
Dave Love <fx@gnu.org>
parents:
diff changeset
2363 The usual purpose of the terminal-specific library is to map the
Dave Love <fx@gnu.org>
parents:
diff changeset
2364 escape sequences used by the terminal's function keys onto more
Dave Love <fx@gnu.org>
parents:
diff changeset
2365 meaningful names, using @code{function-key-map}. See the file
Dave Love <fx@gnu.org>
parents:
diff changeset
2366 @file{term/lk201.el} for an example of how this is done. Many function
Dave Love <fx@gnu.org>
parents:
diff changeset
2367 keys are mapped automatically according to the information in the
Dave Love <fx@gnu.org>
parents:
diff changeset
2368 Termcap data base; the terminal-specific library needs to map only the
Dave Love <fx@gnu.org>
parents:
diff changeset
2369 function keys that Termcap does not specify.
Dave Love <fx@gnu.org>
parents:
diff changeset
2370
Dave Love <fx@gnu.org>
parents:
diff changeset
2371 When the terminal type contains a hyphen, only the part of the name
Dave Love <fx@gnu.org>
parents:
diff changeset
2372 before the first hyphen is significant in choosing the library name.
Dave Love <fx@gnu.org>
parents:
diff changeset
2373 Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
Dave Love <fx@gnu.org>
parents:
diff changeset
2374 the library @file{term/aaa}. The code in the library can use
Dave Love <fx@gnu.org>
parents:
diff changeset
2375 @code{(getenv "TERM")} to find the full terminal type name.@refill
Dave Love <fx@gnu.org>
parents:
diff changeset
2376
Dave Love <fx@gnu.org>
parents:
diff changeset
2377 @vindex term-file-prefix
Dave Love <fx@gnu.org>
parents:
diff changeset
2378 The library's name is constructed by concatenating the value of the
Dave Love <fx@gnu.org>
parents:
diff changeset
2379 variable @code{term-file-prefix} and the terminal type. Your @file{.emacs}
Dave Love <fx@gnu.org>
parents:
diff changeset
2380 file can prevent the loading of the terminal-specific library by setting
Dave Love <fx@gnu.org>
parents:
diff changeset
2381 @code{term-file-prefix} to @code{nil}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2382
Dave Love <fx@gnu.org>
parents:
diff changeset
2383 @vindex term-setup-hook
Dave Love <fx@gnu.org>
parents:
diff changeset
2384 Emacs runs the hook @code{term-setup-hook} at the end of
Dave Love <fx@gnu.org>
parents:
diff changeset
2385 initialization, after both your @file{.emacs} file and any
Dave Love <fx@gnu.org>
parents:
diff changeset
2386 terminal-specific library have been read in. Add hook functions to this
Dave Love <fx@gnu.org>
parents:
diff changeset
2387 hook if you wish to override part of any of the terminal-specific
Dave Love <fx@gnu.org>
parents:
diff changeset
2388 libraries and to define initializations for terminals that do not have a
Dave Love <fx@gnu.org>
parents:
diff changeset
2389 library. @xref{Hooks}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2390
Dave Love <fx@gnu.org>
parents:
diff changeset
2391 @node Find Init
Dave Love <fx@gnu.org>
parents:
diff changeset
2392 @subsection How Emacs Finds Your Init File
Dave Love <fx@gnu.org>
parents:
diff changeset
2393
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 28344
diff changeset
2394 Normally Emacs uses the environment variable @env{HOME} to find
59949
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
2395 @file{.emacs}; that's what @samp{~} means in a file name. If @file{.emacs}
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
2396 is not found directly inside @file{~/}, Emacs looks for it in
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
2397 @file{~/.emacs.d/}.
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
2398
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
2399 However, if you run Emacs from a shell started by @code{su}, Emacs
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
2400 tries to find your own @file{.emacs}, not that of the user you are
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
2401 currently pretending to be. The idea is that you should get your own
7c5b107612a0 (Minor Modes): Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 59802
diff changeset
2402 editor customizations even if you are running as the super user.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2403
Dave Love <fx@gnu.org>
parents:
diff changeset
2404 More precisely, Emacs first determines which user's init file to use.
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 28344
diff changeset
2405 It gets the user name from the environment variables @env{LOGNAME} and
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 28344
diff changeset
2406 @env{USER}; if neither of those exists, it uses effective user-ID.
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 28344
diff changeset
2407 If that user name matches the real user-ID, then Emacs uses @env{HOME};
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2408 otherwise, it looks up the home directory corresponding to that user
Dave Love <fx@gnu.org>
parents:
diff changeset
2409 name in the system's data base of users.
Dave Love <fx@gnu.org>
parents:
diff changeset
2410 @c LocalWords: backtab
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52227
diff changeset
2411
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52227
diff changeset
2412 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52227
diff changeset
2413 arch-tag: c68abddb-4410-4fb5-925f-63394e971d93
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52227
diff changeset
2414 @end ignore