annotate man/custom.texi @ 73293:a12ab7c32707

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