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