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