custom.texi 106 KB
Newer Older
Glenn Morris's avatar
Glenn Morris committed
1 2
@c This is part of the Emacs manual.
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
3
@c   2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
4
@c   Free Software Foundation, Inc.
Glenn Morris's avatar
Glenn Morris committed
5 6 7 8 9
@c See file emacs.texi for copying conditions.
@node Customization, Quitting, Amusements, Top
@chapter Customization
@cindex customization

10 11 12 13 14 15 16 17
  This chapter describes some simple methods to customize the behavior
of Emacs.

  Apart from the methods described here, see @ref{X Resources} for
information about using X resources to customize Emacs, and see
@ref{Keyboard Macros} for information about recording and replaying
keyboard macros.  Making more far-reaching and open-ended changes
involves writing Emacs Lisp code; see
Glenn Morris's avatar
Glenn Morris committed
18
@iftex
19
@cite{The Emacs Lisp Reference Manual}.
Glenn Morris's avatar
Glenn Morris committed
20 21
@end iftex
@ifnottex
22 23
@ref{Top, Emacs Lisp, Emacs Lisp, elisp, The Emacs Lisp
Reference Manual}.
Glenn Morris's avatar
Glenn Morris committed
24 25 26
@end ifnottex

@menu
27 28
* Minor Modes::         Each minor mode is a feature you can turn on
                          independently of any others.
Glenn Morris's avatar
Glenn Morris committed
29
* Easy Customization::  Convenient way to browse and change settings.
30 31 32 33 34 35 36 37 38
* Variables::           Many Emacs commands examine Emacs variables
                          to decide what to do; by setting variables,
                          you can control their functioning.
* Key Bindings::        The keymaps say what command each key runs.
                          By changing them, you can "redefine keys".
* Syntax::              The syntax table controls how words and
                          expressions are parsed.
* Init File::           How to write common customizations in the
                          @file{.emacs} file.
Glenn Morris's avatar
Glenn Morris committed
39 40 41 42 43 44 45 46
@end menu

@node Minor Modes
@section Minor Modes
@cindex minor modes
@cindex mode, minor

  Minor modes are optional features which you can turn on or off.  For
47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73
example, Auto Fill mode is a minor mode in which @key{SPC} breaks
lines between words as you type.  Minor modes are independent of one
another and of the selected major mode.  Most minor modes say in the
mode line when they are enabled; for example, @samp{Fill} in the mode
line means that Auto Fill mode is enabled.

  Each minor mode is associated with a command, called the @dfn{mode
command}, which turns it on or off.  The name of this command consists
of the name of the minor mode, followed by @samp{-mode}; for instance,
the mode command for Auto Fill mode is @code{auto-fill-mode}.  Calling
the minor mode command with no prefix argument @dfn{toggles} the mode,
turning it on if it was off, and off if it was on.  A positive
argument always turns the mode on, and a zero or negative argument
always turns it off.  Mode commands are usually invoked with
@kbd{M-x}, but you can bind keys to them if you wish (@pxref{Key
Bindings}).

  Most minor modes also have a @dfn{mode variable}, with the same name
as the mode command.  Its value is non-@code{nil} if the mode is
enabled, and @code{nil} if it is disabled.  In some minor modes---but
not all---the value of the variable alone determines whether the mode
is active: the mode command works simply by setting the variable, and
changing the value of the variable has the same effect as calling the
mode command.  Because not all minor modes work this way, we recommend
that you avoid changing the mode variables directly; use the mode
commands instead.

74 75 76 77 78
  Some minor modes are @dfn{buffer-local}: they apply only to the
current buffer, so you can enable the mode in certain buffers and not
others.  Other minor modes are @dfn{global}: while enabled, they
affect everything you do in the Emacs session, in all buffers.  Some
global minor modes are enabled by default.
79 80 81 82 83 84 85 86 87 88

  The following is a list of some buffer-local minor modes:

@itemize @bullet
@item
Abbrev mode automatically expands text based on pre-defined
abbreviation definitions.  @xref{Abbrevs}.

@item
Auto Fill mode inserts newlines as you type to prevent lines from
Glenn Morris's avatar
Glenn Morris committed
89 90
becoming too long.  @xref{Filling}.

91 92
@item
Auto Save mode saves the buffer contents periodically to reduce the
Glenn Morris's avatar
Glenn Morris committed
93 94
amount of work you can lose in case of a crash.  @xref{Auto Save}.

95 96
@item
Enriched mode enables editing and saving of formatted text.
Glenn Morris's avatar
Glenn Morris committed
97 98
@xref{Formatted Text}.

99 100
@item
Flyspell mode automatically highlights misspelled words.
Glenn Morris's avatar
Glenn Morris committed
101 102
@xref{Spelling}.

103 104 105 106
@item
Font-Lock mode automatically highlights certain textual units found in
programs.  It is enabled globally by default, but you can disable it
in individual buffers.  @xref{Faces}.
Glenn Morris's avatar
Glenn Morris committed
107

108 109 110 111 112
@findex linum-mode
@cindex Linum mode
@item
Linum mode displays each line's line number in the window's left
margin.  Its mode command is @code{linum-mode}.
Glenn Morris's avatar
Glenn Morris committed
113

114 115 116
@item
Outline minor mode provides similar facilities to the major mode
called Outline mode.  @xref{Outline Mode}.
Glenn Morris's avatar
Glenn Morris committed
117 118 119 120 121

@cindex Overwrite mode
@cindex mode, Overwrite
@findex overwrite-mode
@kindex INSERT
122 123 124 125 126 127 128 129 130 131
@item
Overwrite mode causes ordinary printing characters to replace existing
text instead of shoving it to the right.  For example, if point is in
front of the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing
a @kbd{G} changes it to @samp{FOOGAR}, instead of producing
@samp{FOOGBAR} as usual.  In Overwrite mode, the command @kbd{C-q}
inserts the next character whatever it may be, even if it is a
digit---this gives you a way to insert a character instead of
replacing an existing character.  The mode command,
@code{overwrite-mode}, is bound to the @key{Insert} key.
Glenn Morris's avatar
Glenn Morris committed
132 133

@findex binary-overwrite-mode
134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162
@item
Binary Overwrite mode is a variant of Overwrite mode for editing
binary files; it treats newlines and tabs like other characters, so
that they overwrite other characters and can be overwritten by them.
In Binary Overwrite mode, digits after @kbd{C-q} specify an octal
character code, as usual.

@item
Visual Line mode performs ``word wrapping'', causing long lines to be
wrapped at word boundaries.  @xref{Visual Line Mode}.
@end itemize

  Here are some useful global minor modes.  Since Line Number mode and
Transient Mark mode can be enabled or disabled just by setting the
value of the minor mode variable, you @emph{can} set them differently
for particular buffers, by explicitly making the corresponding
variable local in those buffers.  @xref{Locals}.

@itemize @bullet
@item
Column Number mode enables display of the current column number in the
mode line.  @xref{Mode Line}.

@item
Delete Selection mode causes text insertion to first delete the text
in the region, if the region is active.  @xref{Using Region}.

@item
Icomplete mode displays an indication of available completions when
Glenn Morris's avatar
Glenn Morris committed
163 164 165
you are in the minibuffer and completion is active.  @xref{Completion
Options}.

166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188
@item
Line Number mode enables display of the current line number in the
mode line.  It is enabled by default.  @xref{Mode Line}.

@item
Menu Bar mode gives each frame a menu bar.  It is enabled by default.
@xref{Menu Bars}.

@item
Scroll Bar mode gives each window a scroll bar.  It is enabled by
default, but the scroll bar is only displayed on graphical terminals.
@xref{Scroll Bars}.

@item
Tool Bar mode gives each frame a tool bar.  It is enabled by default,
but the tool bar is only displayed on graphical terminals.  @xref{Tool
Bars}.

@item
Transient Mark mode highlights the region, and makes many Emacs
commands operate on the region when the mark is active.  It is enabled
by default.  @xref{Mark}.
@end itemize
Glenn Morris's avatar
Glenn Morris committed
189 190 191 192 193

@node Easy Customization
@section Easy Customization Interface

@cindex settings
194 195 196 197 198
  Emacs has many @dfn{settings} which have values that you can change.
Many are documented in this manual.  Most settings are @dfn{user
options}---that is to say, Lisp variables (@pxref{Variables})---and
their names appear in the Variable Index (@pxref{Variable Index}).
The other settings are faces and their attributes (@pxref{Faces}).
Glenn Morris's avatar
Glenn Morris committed
199 200 201

@findex customize
@cindex customization buffer
202 203 204 205 206
  You can browse settings and change them using @kbd{M-x customize}.
This creates a @dfn{customization buffer}, which lets you navigate
through a logically organized list of settings, edit and set their
values, and save them permanently in your initialization file
(@pxref{Init File}).
Glenn Morris's avatar
Glenn Morris committed
207 208

@menu
209 210
* Customization Groups::     How settings are classified in a structure.
* Browsing Custom::          Browsing and searching for settings.
Glenn Morris's avatar
Glenn Morris committed
211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236
* Changing a Variable::      How to edit an option's value and set the option.
* Saving Customizations::    Specifying the file for saving customizations.
* Face Customization::       How to edit the attributes of a face.
* Specific Customization::   Making a customization buffer for specific
                                variables, faces, or groups.
* Custom Themes::            How to define collections of customized options
                                that can be loaded and unloaded together.
@end menu

@node Customization Groups
@subsection Customization Groups
@cindex customization groups

  For customization purposes, settings are organized into @dfn{groups}
to help you find them.  Groups are collected into bigger groups, all
the way up to a master group called @code{Emacs}.

  @kbd{M-x customize} creates a customization buffer that shows the
top-level @code{Emacs} group and the second-level groups immediately
under it.  It looks like this, in part:

@c we want the buffer example to all be on one page, but unfortunately
@c that's quite a bit of text, so force all space to the bottom.
@page
@smallexample
@group
237
/- Emacs group: Customization of the One True Editor. -------------\
Glenn Morris's avatar
Glenn Morris committed
238
      [State]: visible group members are all at standard values.
239
   
Glenn Morris's avatar
Glenn Morris committed
240 241
   See also [Manual].

242
[Editing] : Basic text editing facilities.
Glenn Morris's avatar
Glenn Morris committed
243

244
[External] : Interfacing to external utilities.
Glenn Morris's avatar
Glenn Morris committed
245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268

@var{more second-level groups}

\- Emacs group end ------------------------------------------------/
@end group
@end smallexample

@noindent
This says that the buffer displays the contents of the @code{Emacs}
group.  The other groups are listed because they are its contents.  But
they are listed differently, without indentation and dashes, because
@emph{their} contents are not included.  Each group has a single-line
documentation string; the @code{Emacs} group also has a @samp{[State]}
line.

@cindex editable fields (customization buffer)
@cindex buttons (customization buffer)
@cindex links (customization buffer)
  Most of the text in the customization buffer is read-only, but it
typically includes some @dfn{editable fields} that you can edit.
There are also @dfn{buttons} and @dfn{links}, which do something when
you @dfn{invoke} them.  To invoke a button or a link, either click on
it with @kbd{Mouse-1}, or move point to it and type @key{RET}.

269 270 271 272 273
  For example, the phrase @samp{[State]} that appears in a
second-level group is a button.  It operates on the same customization
buffer.  Each group name, such as @samp{[Editing]}, is a hypertext
link to that group; invoking it creates a new customization buffer,
showing the group and its contents.
Glenn Morris's avatar
Glenn Morris committed
274

275 276 277 278 279 280
  The @code{Emacs} group only contains other groups.  These groups, in
turn, can contain settings or still more groups.  By browsing the
hierarchy of groups, you will eventually find the feature you are
interested in customizing.  Then you can use the customization buffer
to set that feature's settings.  You can also go straight to a
particular group by name, using the command @kbd{M-x customize-group}.
Glenn Morris's avatar
Glenn Morris committed
281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436

@node Browsing Custom
@subsection Browsing and Searching for Options and Faces
@findex customize-browse

  @kbd{M-x customize-browse} is another way to browse the available
settings.  This command creates a special customization buffer which
shows only the names of groups and settings, and puts them in a
structure.

  In this buffer, you can show the contents of a group by invoking the
@samp{[+]} button.  When the group contents are visible, this button
changes to @samp{[-]}; invoking that hides the group contents again.

  Each group or setting in this buffer has a link which says
@samp{[Group]}, @samp{[Option]} or @samp{[Face]}.  Invoking this link
creates an ordinary customization buffer showing just that group and
its contents, just that user option, or just that face.  This is the
way to change settings that you find with @kbd{M-x customize-browse}.

  If you can guess part of the name of the settings you are interested
in, @kbd{M-x customize-apropos} is another way to search for settings.
However, unlike @code{customize} and @code{customize-browse},
@code{customize-apropos} can only find groups and settings that are
loaded in the current Emacs session.  @xref{Specific Customization,,
Customizing Specific Items}.

@node Changing a Variable
@subsection Changing a Variable

  Here is an example of what a variable (a user option) looks like in
the customization buffer:

@smallexample
Kill Ring Max: [Hide Value] 60
   [State]: STANDARD.
Maximum length of kill ring before oldest elements are thrown away.
@end smallexample

  The text following @samp{[Hide Value]}, @samp{60} in this case, indicates
the current value of the variable.  If you see @samp{[Show Value]} instead of
@samp{[Hide Value]}, it means that the value is hidden; the customization
buffer initially hides values that take up several lines.  Invoke
@samp{[Show Value]} to show the value.

  The line after the variable name indicates the @dfn{customization
state} of the variable: in the example above, it says you have not
changed the option yet.  The @samp{[State]} button at the beginning of
this line gives you a menu of various operations for customizing the
variable.

  The line after the @samp{[State]} line displays the beginning of the
variable's documentation string.  If there are more lines of
documentation, this line ends with a @samp{[More]} button; invoke that
to show the full documentation string.

  To enter a new value for @samp{Kill Ring Max}, move point to the
value and edit it textually.  For example, you can type @kbd{M-d},
then insert another number.  As you begin to alter the text, you will
see the @samp{[State]} line change to say that you have edited the
value:

@smallexample
[State]: EDITED, shown value does not take effect until you set or @r{@dots{}}
                                                           save it.
@end smallexample

@cindex user options, how to set
@cindex variables, how to set
@cindex settings, how to set
  Editing the value does not actually set the variable.  To do that,
you must @dfn{set} the variable.  To do this, invoke the
@samp{[State]} button and choose @samp{Set for Current Session}.

  The state of the variable changes visibly when you set it:

@smallexample
[State]: SET for current session only.
@end smallexample

   You don't have to worry about specifying a value that is not valid;
the @samp{Set for Current Session} operation checks for validity and
will not install an unacceptable value.

@kindex M-TAB @r{(customization buffer)}
@findex widget-complete
  While editing a field that is a file name, directory name,
command name, or anything else for which completion is defined, you
can type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion.
(@kbd{@key{ESC} @key{TAB}} and @kbd{C-M-i} do the same thing.)

  Some variables have a small fixed set of possible legitimate values.
These variables don't let you edit the value textually.  Instead, a
@samp{[Value Menu]} button appears before the value; invoke this
button to change the value.  For a boolean ``on or off'' value, the
button says @samp{[Toggle]}, and it changes to the other value.
@samp{[Value Menu]} and @samp{[Toggle]} simply edit the buffer; the
changes take real effect when you use the @samp{Set for Current
Session} operation.

  Some variables have values with complex structure.  For example, the
value of @code{file-coding-system-alist} is an association list.  Here
is how it appears in the customization buffer:

@smallexample
File Coding System Alist: [Hide Value]
[INS] [DEL] File regexp: \.elc\'
            Choice: [Value Menu] Encoding/decoding pair:
            Decoding: emacs-mule
            Encoding: emacs-mule
[INS] [DEL] File regexp: \(\`\|/\)loaddefs.el\'
            Choice: [Value Menu] Encoding/decoding pair:
            Decoding: raw-text
            Encoding: raw-text-unix
[INS] [DEL] File regexp: \.tar\'
            Choice: [Value Menu] Encoding/decoding pair:
            Decoding: no-conversion
            Encoding: no-conversion
[INS] [DEL] File regexp:
            Choice: [Value Menu] Encoding/decoding pair:
            Decoding: undecided
            Encoding: nil
[INS]
   [State]: STANDARD.
Alist to decide a coding system to use for a file I/O @r{@dots{}}
                                operation. [Hide Rest]
The format is ((PATTERN . VAL) ...),
where PATTERN is a regular expression matching a file name,
@r{[@dots{}more lines of documentation@dots{}]}
@end smallexample

@noindent
Each association in the list appears on four lines, with several
editable fields and/or buttons.  You can edit the regexps and coding
systems using ordinary editing commands.  You can also invoke
@samp{[Value Menu]} to switch to a different kind of value---for
instance, to specify a function instead of a pair of coding systems.

To delete an association from the list, invoke the @samp{[DEL]} button
for that item.  To add an association, invoke @samp{[INS]} at the
position where you want to add it.  There is an @samp{[INS]} button
between each pair of associations, another at the beginning and another
at the end, so you can add a new association at any position in the
list.

@kindex TAB @r{(customization buffer)}
@kindex S-TAB @r{(customization buffer)}
@findex widget-forward
@findex widget-backward
  Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful
for moving through the customization buffer.  @key{TAB}
(@code{widget-forward}) moves forward to the next button or editable
field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to
the previous button or editable field.

  Typing @key{RET} on an editable field also moves forward, just like
437 438 439
@key{TAB}.  You can thus type @key{RET} when you are finished editing
a field, to move on to the next button or field.  To insert a newline
within an editable field, use @kbd{C-o} or @kbd{C-q C-j}.
Glenn Morris's avatar
Glenn Morris committed
440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505

@cindex saving a setting
@cindex settings, how to save
  Setting the variable changes its value in the current Emacs session;
@dfn{saving} the value changes it for future sessions as well.  To
save the variable, invoke @samp{[State]} and select the @samp{Save for
Future Sessions} operation.  This works by writing code so as to set
the variable again, each time you start Emacs (@pxref{Saving
Customizations}).

  You can also restore the variable to its standard value by invoking
@samp{[State]} and selecting the @samp{Erase Customization} operation.
There are actually four reset operations:

@table @samp
@item Undo Edits
If you have made some modifications and not yet set the variable,
this restores the text in the customization buffer to match
the actual value.

@item Reset to Saved
This restores the value of the variable to the last saved value,
and updates the text accordingly.

@item Erase Customization
This sets the variable to its standard value, and updates the text
accordingly.  This also eliminates any saved value for the variable,
so that you will get the standard value in future Emacs sessions.

@item Set to Backup Value
This sets the variable to a previous value that was set in the
customization buffer in this session.  If you customize a variable
and then reset it, which discards the customized value,
you can get the discarded value back again with this operation.
@end table

@cindex comments on customized settings
  Sometimes it is useful to record a comment about a specific
customization.  Use the @samp{Add Comment} item from the
@samp{[State]} menu to create a field for entering the comment.  The
comment you enter will be saved, and displayed again if you again view
the same variable in a customization buffer, even in another session.

  The state of a group indicates whether anything in that group has been
edited, set or saved.

  Near the top of the customization buffer there are two lines of buttons:

@smallexample
 [Set for Current Session] [Save for Future Sessions]
 [Undo Edits] [Reset to Saved] [Erase Customization]   [Finish]
@end smallexample

@vindex custom-buffer-done-function
@noindent
Invoking @samp{[Finish]} either buries or kills this customization
buffer according to the setting of the option
@code{custom-buffer-done-kill}; the default is to bury the buffer.
Each of the other buttons performs an operation---set, save or
reset---on each of the settings in the buffer that could meaningfully
be set, saved or reset.  They do not operate on settings whose values
are hidden, nor on subgroups which are hidden or not visible in the buffer.

@node Saving Customizations
@subsection Saving Customizations

506
@vindex custom-file
Glenn Morris's avatar
Glenn Morris committed
507
  Saving customizations from the customization buffer works by writing
508 509 510
code to a file.  By reading this code, future sessions can set up the
customizations again.  Normally, the code is saved in your
initialization file (@pxref{Init File}).
Glenn Morris's avatar
Glenn Morris committed
511

512 513 514 515 516
  You can choose to save your customizations in a file other than your
initialization file.  To make this work, you must add a couple of
lines of code to your initialization file, to set the variable
@code{custom-file} to the name of the desired file, and to load that
file.  For example:
Glenn Morris's avatar
Glenn Morris committed
517 518 519 520 521 522 523 524 525 526

@example
(setq custom-file "~/.emacs-custom.el")
(load custom-file)
@end example

  You can use @code{custom-file} to specify different customization
files for different Emacs versions, like this:

@example
527 528
(cond ((< emacs-major-version 22)
       ;; @r{Emacs 21 customization.}
Glenn Morris's avatar
Glenn Morris committed
529
       (setq custom-file "~/.custom-21.el"))
530 531
      ((and (= emacs-major-version 22)
            (< emacs-minor-version 3))
532 533
       ;; @r{Emacs 22 customization, before version 22.3.}
       (setq custom-file "~/.custom-22.el"))
Glenn Morris's avatar
Glenn Morris committed
534
      (t
535 536
       ;; @r{Emacs version 22.3 or later.}
       (setq custom-file "~/.emacs-custom.el")))
Glenn Morris's avatar
Glenn Morris committed
537 538 539 540 541 542

(load custom-file)
@end example

  If Emacs was invoked with the @option{-q} or @option{--no-init-file}
options (@pxref{Initial Options}), it will not let you save your
543 544 545
customizations in your initialization file.  This is because saving
customizations from such a session would wipe out all the other
customizations you might have on your initialization file.
Glenn Morris's avatar
Glenn Morris committed
546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586

@node Face Customization
@subsection Customizing Faces
@cindex customizing faces
@cindex bold font
@cindex italic font
@cindex fonts and faces

  In addition to variables, some customization groups also include
faces.  When you show the contents of a group, both the variables and
the faces in the group appear in the customization buffer.  Here is an
example of how a face looks:

@smallexample
Custom Changed Face:(sample) [Hide Face]
   [State]: STANDARD.
Face used when the customize item has been changed.
Parent groups: [Custom Magic Faces]
Attributes: [ ] Font Family: *
            [ ] Width: *
            [ ] Height: *
            [ ] Weight: *
            [ ] Slant: *
            [ ] Underline: *
            [ ] Overline: *
            [ ] Strike-through: *
            [ ] Box around text: *
            [ ] Inverse-video: *
            [X] Foreground: white       (sample)
            [X] Background: blue        (sample)
            [ ] Stipple: *
            [ ] Inherit: *
@end smallexample

  Each face attribute has its own line.  The @samp{[@var{x}]} button
before the attribute name indicates whether the attribute is
@dfn{enabled}; @samp{[X]} means that it's enabled, and @samp{[ ]}
means that it's disabled.  You can enable or disable the attribute by
clicking that button.  When the attribute is enabled, you can change
the attribute value in the usual ways.

587 588 589 590 591 592 593 594 595
  You can specify a color name (use @kbd{M-x list-colors-display} for
a list of them) or a hexadecimal color specification of the form
@samp{#@var{rr}@var{gg}@var{bb}}.  (@samp{#000000} is black,
@samp{#ff0000} is red, @samp{#00ff00} is green, @samp{#0000ff} is
blue, and @samp{#ffffff} is white.)  On a black-and-white display, the
colors you can use for the background are @samp{black}, @samp{white},
@samp{gray}, @samp{gray1}, and @samp{gray3}.  Emacs supports these
shades of gray by using background stipple patterns instead of a
color.
Glenn Morris's avatar
Glenn Morris committed
596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759

  Setting, saving and resetting a face work like the same operations for
variables (@pxref{Changing a Variable}).

  A face can specify different appearances for different types of
display.  For example, a face can make text red on a color display, but
use a bold font on a monochrome display.  To specify multiple
appearances for a face, select @samp{For All Kinds of Displays} in the
menu you get from invoking @samp{[State]}.

@findex modify-face
  Another more basic way to set the attributes of a specific face is
with @kbd{M-x modify-face}.  This command reads the name of a face, then
reads the attributes one by one.  For the color and stipple attributes,
the attribute's current value is the default---type just @key{RET} if
you don't want to change that attribute.  Type @samp{none} if you want
to clear out the attribute.

@node Specific Customization
@subsection Customizing Specific Items

  Instead of finding the setting you want to change by navigating the
structure of groups, here are other ways to specify the settings that
you want to customize.

@table @kbd
@item M-x customize-option @key{RET} @var{option} @key{RET}
Set up a customization buffer with just one user option variable,
@var{option}.
@item M-x customize-face @key{RET} @var{face} @key{RET}
Set up a customization buffer with just one face, @var{face}.
@item M-x customize-group @key{RET} @var{group} @key{RET}
Set up a customization buffer with just one group, @var{group}.
@item M-x customize-apropos @key{RET} @var{regexp} @key{RET}
Set up a customization buffer with all the settings and groups that
match @var{regexp}.
@item M-x customize-changed @key{RET} @var{version} @key{RET}
Set up a customization buffer with all the settings and groups
whose meaning has changed since Emacs version @var{version}.
@item M-x customize-saved
Set up a customization buffer containing all settings that you
have saved with customization buffers.
@item M-x customize-unsaved
Set up a customization buffer containing all settings that you have
set but not saved.
@end table

@findex customize-option
  If you want to alter a particular user option with the customization
buffer, and you know its name, you can use the command @kbd{M-x
customize-option} and specify the user option (variable) name.  This
sets up the customization buffer with just one user option---the one
that you asked for.  Editing, setting and saving the value work as
described above, but only for the specified user option.  Minibuffer
completion is handy if you only know part of the name.  However, this
command can only see options that have been loaded in the current
Emacs session.

@findex customize-face
  Likewise, you can modify a specific face, chosen by name, using
@kbd{M-x customize-face}.  By default it operates on the face used
on the character after point.

@findex customize-group
  You can also set up the customization buffer with a specific group,
using @kbd{M-x customize-group}.  The immediate contents of the chosen
group, including settings (user options and faces), and other groups,
all appear as well (even if not already loaded).  However, the
subgroups' own contents are not included.

@findex customize-apropos
  For a more general way of controlling what to customize, you can use
@kbd{M-x customize-apropos}.  You specify a regular expression as
argument; then all @emph{loaded} settings and groups whose names match
this regular expression are set up in the customization buffer.  If
you specify an empty regular expression, this includes @emph{all}
loaded groups and settings---which takes a long time to set up.

@findex customize-changed
  When you upgrade to a new Emacs version, you might want to consider
customizing new settings, and settings whose meanings or default
values have changed.  To do this, use @kbd{M-x customize-changed} and
specify a previous Emacs version number using the minibuffer.  It
creates a customization buffer which shows all the settings and groups
whose definitions have been changed since the specified version,
loading them if necessary.

@findex customize-saved
@findex customize-unsaved
  If you change settings and then decide the change was a mistake, you
can use two special commands to revisit your previous changes.  Use
@kbd{M-x customize-saved} to look at the settings that you have saved.
Use @kbd{M-x customize-unsaved} to look at the settings that you
have set but not saved.

@node Custom Themes
@subsection Customization Themes
@cindex custom themes

  @dfn{Custom themes} are collections of settings that can be enabled
or disabled as a unit.  You can use Custom themes to switch quickly
and easily between various collections of settings, and to transfer
such collections from one computer to another.

@findex customize-create-theme
  To define a Custom theme, use @kbd{M-x customize-create-theme},
which brings up a buffer named @samp{*New Custom Theme*}.  At the top
of the buffer is an editable field where you can specify the name of
the theme.  Click on the button labelled @samp{Insert Variable} to add
a variable to the theme, and click on @samp{Insert Face} to add a
face.  You can edit these values in the @samp{*New Custom Theme*}
buffer like in an ordinary Customize buffer.  To remove an option from
the theme, click on its @samp{State} button and select @samp{Delete}.

@vindex custom-theme-directory
  After adding the desired options, click on @samp{Save Theme} to save
the Custom theme.  This writes the theme definition to a file
@file{@var{foo}-theme.el} (where @var{foo} is the theme name you
supplied), in the directory @file{~/.emacs.d/}.  You can specify the
directory by setting @code{custom-theme-directory}.

  You can view and edit the settings of a previously-defined theme by
clicking on @samp{Visit Theme} and specifying the theme name.  You can
also import the variables and faces that you have set using Customize
by visiting the ``special'' theme named @samp{user}.  This theme, which
records all the options that you set in the ordinary customization
buffer, is always enabled, and always takes precedence over all other
enabled Custom themes.  Additionally, the @samp{user} theme is
recorded with code in your @file{.emacs} file, rather than a
@file{user-theme.el} file.

@vindex custom-enabled-themes
  Once you have defined a Custom theme, you can use it by customizing
the variable @code{custom-enabled-themes}.  This is a list of Custom
themes that are @dfn{enabled}, or put into effect.  If you set
@code{custom-enabled-themes} using the Customize interface, the theme
definitions are automatically loaded from the theme files, if they
aren't already.  If you save the value of @code{custom-enabled-themes}
for future Emacs sessions, those Custom themes will be enabled
whenever Emacs is started up.

  If two enabled themes specify different values for an option, the
theme occurring earlier in @code{custom-enabled-themes} takes effect.

@findex load-theme
@findex enable-theme
@findex disable-theme
  You can temporarily enable a Custom theme with @kbd{M-x
enable-theme}.  This prompts for a theme name in the minibuffer, loads
the theme from the theme file if necessary, and enables the theme.
You can @dfn{disable} any enabled theme with the command @kbd{M-x
disable-theme}; this returns the options specified in the theme to
their original values.  To re-enable the theme, type @kbd{M-x
enable-theme} again.  If a theme file is changed during your Emacs
session, you can reload it by typing @kbd{M-x load-theme}.  (This also
enables the theme.)

@node Variables
@section Variables
@cindex variable
@cindex option, user
@cindex user option

  A @dfn{variable} is a Lisp symbol which has a value.  The symbol's
760 761 762
name is also called the @dfn{variable name}.  A variable name can
contain any characters that can appear in a file, but most variable
names consist of ordinary words separated by hyphens.
Glenn Morris's avatar
Glenn Morris committed
763

764 765 766 767 768 769
  The name of the variable serves as a compact description of its
role.  Most variables also have a @dfn{documentation string}, which
describes what the variable's purpose is, what kind of value it should
have, and how the value will be used.  You can view this documentation
using the help command @kbd{C-h v} (@code{describe-variable}).
@xref{Examining}.
Glenn Morris's avatar
Glenn Morris committed
770 771 772

  Emacs uses many Lisp variables for internal record keeping, but the
most interesting variables for a non-programmer user are those meant
773 774
for users to change---these are called @dfn{user options}.  @xref{Easy
Customization}, for information about using the Customize facility to
775
set user options.  In the following sections, we will describe other
776
aspects of Emacs variables, such as how to set them outside Customize.
Glenn Morris's avatar
Glenn Morris committed
777

778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795
  Emacs Lisp allows any variable (with a few exceptions) to have any
kind of value.  However, many variables are meaningful only if
assigned values of a certain type.  For example, only numbers are
meaningful values for @code{kill-ring-max}, which specifies the
maximum length of the kill ring (@pxref{Earlier Kills}); if you give
@code{kill-ring-max} a string value, commands such as @kbd{C-y}
(@code{yank}) will signal an error.  On the other hand, some variables
don't care about type; for instance, if a variable has one effect for
@code{nil} values and another effect for ``non-@code{nil}'' values,
then any value that is not the symbol @code{nil} induces the second
effect, regardless of its type (by convention, we usually use the
value @code{t}---a symbol which stands for ``true''---to specify a
non-@code{nil} value).  If you set a variable using the customization
buffer, you need not worry about giving it an invalid type: the
customization buffer usually only allows you to enter meaningful
values.  When in doubt, use @kbd{C-h v} (@code{describe-variable}) to
check the variable's documentation string to see kind of value it
expects (@pxref{Examining}).
Glenn Morris's avatar
Glenn Morris committed
796 797

@menu
798 799 800 801
* Examining::           Examining or setting one variable's value.
* Hooks::               Hook variables let you specify programs for parts
                          of Emacs to run on particular occasions.
* Locals::              Per-buffer values of variables.
Glenn Morris's avatar
Glenn Morris committed
802
* File Variables::      How files can specify variable values.
803
* Directory Variables:: How variable values can be specified by directory.
Glenn Morris's avatar
Glenn Morris committed
804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835
@end menu

@node Examining
@subsection Examining and Setting Variables
@cindex setting variables

@table @kbd
@item C-h v @var{var} @key{RET}
Display the value and documentation of variable @var{var}
(@code{describe-variable}).
@item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET}
Change the value of variable @var{var} to @var{value}.
@end table

  To examine the value of a single variable, use @kbd{C-h v}
(@code{describe-variable}), which reads a variable name using the
minibuffer, with completion.  It displays both the value and the
documentation of the variable.  For example,

@example
C-h v fill-column @key{RET}
@end example

@noindent
displays something like this:

@smallexample
fill-column is a variable defined in `C source code'.
fill-column's value is 70
Local in buffer custom.texi; global value is 70
Automatically becomes buffer-local when set in any fashion.

836 837 838
  Automatically becomes buffer-local when set in any fashion.
  This variable is safe as a file local variable if its value
  satisfies the predicate `integerp'.
Glenn Morris's avatar
Glenn Morris committed
839 840 841 842 843 844 845 846 847

Documentation:
*Column beyond which automatic line-wrapping should happen.
Interactively, you can set the buffer local value using C-x f.

You can customize this variable.
@end smallexample

@noindent
848 849 850
The line that says ``You can customize the variable'' indicates that
this variable is a user option.  @kbd{C-h v} is not restricted to user
options; it allows any variable name.
Glenn Morris's avatar
Glenn Morris committed
851 852

@findex set-variable
853 854
  The most convenient way to set a specific user option variable is
with @kbd{M-x set-variable}.  This reads the variable name with the
Glenn Morris's avatar
Glenn Morris committed
855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880
minibuffer (with completion), and then reads a Lisp expression for the
new value using the minibuffer a second time (you can insert the old
value into the minibuffer for editing via @kbd{M-n}).  For example,

@example
M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET}
@end example

@noindent
sets @code{fill-column} to 75.

 @kbd{M-x set-variable} is limited to user option variables, but you can
set any variable with a Lisp expression, using the function @code{setq}.
Here is a @code{setq} expression to set @code{fill-column}:

@example
(setq fill-column 75)
@end example

  To execute an expression like this one, go to the @samp{*scratch*}
buffer, type in the expression, and then type @kbd{C-j}.  @xref{Lisp
Interaction}.

  Setting variables, like all means of customizing Emacs except where
otherwise stated, affects only the current Emacs session.  The only
way to alter the variable in future sessions is to put something in
881
your initialization file to set it those sessions (@pxref{Init File}).
Glenn Morris's avatar
Glenn Morris committed
882 883 884 885 886 887

@node Hooks
@subsection Hooks
@cindex hook
@cindex running a hook

888 889 890 891 892 893 894 895 896 897 898 899 900 901 902
  @dfn{Hooks} are an important mechanism for customizing Emacs.  A
hook is a Lisp variable which holds a list of functions, to be called
on some well-defined occasion.  (This is called @dfn{running the
hook}.)  The individual functions in the list are called the @dfn{hook
functions} of the hook.  With rare exceptions, hooks in Emacs are
empty when Emacs starts up, so the only hook functions in any given
hook are the ones you explicitly put there as customization.

  Most major modes run one or more @dfn{mode hooks} as the last step
of initialization.  This makes it easy for you to customize the
behavior of the mode, by setting up a hook function to override the
local variable assignments already made by the mode.  But hooks are
also used in other contexts.  For example, the hook
@code{kill-emacs-hook} runs just before quitting the Emacs job
(@pxref{Exiting}).
Glenn Morris's avatar
Glenn Morris committed
903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946

@cindex normal hook
  Most Emacs hooks are @dfn{normal hooks}.  This means that running the
hook operates by calling all the hook functions, unconditionally, with
no arguments.  We have made an effort to keep most hooks normal so that
you can use them in a uniform way.  Every variable in Emacs whose name
ends in @samp{-hook} is a normal hook.

@cindex abnormal hook
  There are also a few @dfn{abnormal hooks}.  These variables' names end
in @samp{-hooks} or @samp{-functions}, instead of @samp{-hook}.  What
makes these hooks abnormal is that there is something peculiar about the
way its functions are called---perhaps they are given arguments, or
perhaps the values they return are used in some way.  For example,
@code{find-file-not-found-functions} (@pxref{Visiting}) is abnormal because
as soon as one hook function returns a non-@code{nil} value, the rest
are not called at all.  The documentation of each abnormal hook variable
explains in detail what is peculiar about it.

@findex add-hook
  You can set a hook variable with @code{setq} like any other Lisp
variable, but the recommended way to add a hook function to a hook
(either normal or abnormal) is by calling @code{add-hook}.
@xref{Hooks,,, elisp, The Emacs Lisp Reference Manual}.

  For example, here's how to set up a hook to turn on Auto Fill mode
when entering Text mode and other modes based on Text mode:

@example
(add-hook 'text-mode-hook 'turn-on-auto-fill)
@end example

  The next example shows how to use a hook to customize the indentation
of C code.  (People often have strong personal preferences for one
format compared to another.)  Here the hook function is an anonymous
lambda expression.

@example
@group
(setq my-c-style
  '((c-comment-only-line-offset . 4)
@end group
@group
    (c-cleanup-list . (scope-operator
947 948
                       empty-defun-braces
                       defun-close-semi))
Glenn Morris's avatar
Glenn Morris committed
949 950 951
@end group
@group
    (c-offsets-alist . ((arglist-close . c-lineup-arglist)
952
                        (substatement-open . 0)))))
Glenn Morris's avatar
Glenn Morris committed
953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086
@end group

@group
(add-hook 'c-mode-common-hook
  '(lambda ()
     (c-add-style "my-style" my-c-style t)))
@end group
@end example

  It is best to design your hook functions so that the order in which
they are executed does not matter.  Any dependence on the order is
``asking for trouble.''  However, the order is predictable: the most
recently added hook functions are executed first.

@findex remove-hook
  If you play with adding various different versions of a hook
function by calling @code{add-hook} over and over, remember that all
the versions you added will remain in the hook variable together.  You
can clear out individual functions by calling @code{remove-hook}, or
do @code{(setq @var{hook-variable} nil)} to remove everything.

@node Locals
@subsection Local Variables

@table @kbd
@item M-x make-local-variable @key{RET} @var{var} @key{RET}
Make variable @var{var} have a local value in the current buffer.
@item M-x kill-local-variable @key{RET} @var{var} @key{RET}
Make variable @var{var} use its global value in the current buffer.
@item M-x make-variable-buffer-local @key{RET} @var{var} @key{RET}
Mark variable @var{var} so that setting it will make it local to the
buffer that is current at that time.
@end table

@cindex local variables
  Almost any variable can be made @dfn{local} to a specific Emacs
buffer.  This means that its value in that buffer is independent of its
value in other buffers.  A few variables are always local in every
buffer.  Every other Emacs variable has a @dfn{global} value which is in
effect in all buffers that have not made the variable local.

@findex make-local-variable
  @kbd{M-x make-local-variable} reads the name of a variable and makes
it local to the current buffer.  Changing its value subsequently in
this buffer will not affect others, and changes in its global value
will not affect this buffer.

@findex make-variable-buffer-local
@cindex per-buffer variables
  @kbd{M-x make-variable-buffer-local} marks a variable so it will
become local automatically whenever it is set.  More precisely, once a
variable has been marked in this way, the usual ways of setting the
variable automatically do @code{make-local-variable} first.  We call
such variables @dfn{per-buffer} variables.  Many variables in Emacs
are normally per-buffer; the variable's document string tells you when
this is so.  A per-buffer variable's global value is normally never
effective in any buffer, but it still has a meaning: it is the initial
value of the variable for each new buffer.

  Major modes (@pxref{Major Modes}) always make variables local to the
buffer before setting the variables.  This is why changing major modes
in one buffer has no effect on other buffers.  Minor modes also work
by setting variables---normally, each minor mode has one controlling
variable which is non-@code{nil} when the mode is enabled
(@pxref{Minor Modes}).  For many minor modes, the controlling variable
is per buffer, and thus always buffer-local.  Otherwise, you can make
it local in a specific buffer like any other variable.

  A few variables cannot be local to a buffer because they are always
local to each display instead (@pxref{Multiple Displays}).  If you try to
make one of these variables buffer-local, you'll get an error message.

@findex kill-local-variable
  @kbd{M-x kill-local-variable} makes a specified variable cease to be
local to the current buffer.  The global value of the variable
henceforth is in effect in this buffer.  Setting the major mode kills
all the local variables of the buffer except for a few variables
specially marked as @dfn{permanent locals}.

@findex setq-default
  To set the global value of a variable, regardless of whether the
variable has a local value in the current buffer, you can use the Lisp
construct @code{setq-default}.  This construct is used just like
@code{setq}, but it sets variables' global values instead of their local
values (if any).  When the current buffer does have a local value, the
new global value may not be visible until you switch to another buffer.
Here is an example:

@example
(setq-default fill-column 75)
@end example

@noindent
@code{setq-default} is the only way to set the global value of a variable
that has been marked with @code{make-variable-buffer-local}.

@findex default-value
  Lisp programs can use @code{default-value} to look at a variable's
default value.  This function takes a symbol as argument and returns its
default value.  The argument is evaluated; usually you must quote it
explicitly.  For example, here's how to obtain the default value of
@code{fill-column}:

@example
(default-value 'fill-column)
@end example

@node File Variables
@subsection Local Variables in Files
@cindex local variables in files
@cindex file local variables

  A file can specify local variable values for use when you edit the
file with Emacs.  Visiting the file checks for local variable
specifications; it automatically makes these variables local to the
buffer, and sets them to the values specified in the file.

@menu
* Specifying File Variables:: Specifying file local variables.
* Safe File Variables::       Making sure file local variables are safe.
@end menu

@node Specifying File Variables
@subsubsection Specifying File Variables

  There are two ways to specify file local variable values: in the first
line, or with a local variables list.  Here's how to specify them in the
first line:

@example
-*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*-
@end example

@noindent
1087
You can specify any number of variable/value pairs in this way, each
1088 1089 1090
pair with a colon and semicolon as shown above.  The special
variable/value pair @code{mode: @var{modename};}, if present,
specifies a major or minor mode; if you use this to specify a major
1091
mode, it should come first in the line.  The @var{value}s are used
1092 1093
literally, and not evaluated.

1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106
@findex add-file-local-variable-prop-line
@findex delete-file-local-variable-prop-line
@findex copy-dir-locals-to-file-locals-prop-line
  You can use the command @code{add-file-local-variable-prop-line}
instead of adding entries by hand.  It prompts for a variable
and value, and adds them to the first line in the appropriate way.
The command @code{delete-file-local-variable-prop-line} deletes a
variable from the line.  The command
@code{copy-dir-locals-to-file-locals-prop-line} copies directory-local
variables (@pxref{Directory Variables}) to the first line.

  Here is an example first line that specifies Lisp mode and sets two
variables with numeric values:
Glenn Morris's avatar
Glenn Morris committed
1107 1108 1109 1110 1111

@smallexample
;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*-
@end smallexample

1112 1113 1114 1115
@noindent
Aside from @code{mode}, other keywords that have special meanings as
file variables are @code{coding}, @code{unibyte}, and @code{eval}.
These are described below.
Glenn Morris's avatar
Glenn Morris committed
1116 1117

@cindex shell scripts, and local file variables
1118
@cindex man pages, and local file variables
Glenn Morris's avatar
Glenn Morris committed
1119 1120 1121
  In shell scripts, the first line is used to identify the script
interpreter, so you cannot put any local variables there.  To
accommodate this, Emacs looks for local variable specifications in the
1122 1123
@emph{second} line if the first line specifies an interpreter.  The
same is true for man pages which start with the magic string
1124 1125
@samp{'\"} to specify a list of troff preprocessors (not all do,
however).
Glenn Morris's avatar
Glenn Morris committed
1126

1127 1128 1129 1130 1131
  Instead of using a @samp{-*-} line, you can define file local
variables using a @dfn{local variables list} near the end of the file.
The start of the local variables list should be no more than 3000
characters from the end of the file, and must be on the last page if
the file is divided into pages.
Glenn Morris's avatar
Glenn Morris committed
1132

1133 1134 1135 1136 1137 1138 1139 1140
  If a file has both a local variables list and a @samp{-*-} line,
Emacs processes @emph{everything} in the @samp{-*-} line first, and
@emph{everything} in the local variables list afterward.

  A local variables list starts with a line containing the string
@samp{Local Variables:}, and ends with a line containing the string
@samp{End:}.  In between come the variable names and values, one set
per line, like this:
Glenn Morris's avatar
Glenn Morris committed
1141 1142

@example
1143 1144 1145 1146
/* Local Variables: */
/* mode:c           */
/* comment-column:0 */
/* End:             */
Glenn Morris's avatar
Glenn Morris committed
1147 1148
@end example

1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159
@noindent
In this example, each line starts with the prefix @samp{/*} and ends
with the suffix @samp{*/}.  Emacs recognizes the prefix and suffix by
finding them surrounding the magic string @samp{Local Variables:}, on
the first line of the list; it then automatically discards them from
the other lines of the list.  The usual reason for using a prefix
and/or suffix is to embed the local variables list in a comment, so it
won't confuse other programs that the file is intended for.  The
example above is for the C programming language, where comment lines
start with @samp{/*} and end with @samp{*/}.

1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170
@findex add-file-local-variable
@findex delete-file-local-variable
@findex copy-dir-locals-to-file-locals
  You can construct the local variables list yourself, or use the
command @code{add-file-local-variable}.  This prompts for a variable
and value, and adds them to the list.  If necessary, it also adds the
start and end markers.  The command @code{delete-file-local-variable}
deletes a variable from the list.  The command
@code{copy-dir-locals-to-file-locals} copies directory-local variables
(@pxref{Directory Variables}) to the list.

1171 1172 1173 1174 1175 1176 1177
  As with the @samp{-*-} line, the variables in a local variables list
are used literally, and are not evaluated first.  If you want to split
a long string across multiple lines of the file, you can use
backslash-newline, which is ignored in Lisp string constants; you
should put the prefix and suffix on each line, even lines that start
or end within the string, as they will be stripped off when processing
the list.  Here is an example:
Glenn Morris's avatar
Glenn Morris committed
1178 1179 1180 1181 1182 1183 1184 1185 1186

@example
# Local Variables:
# compile-command: "cc foo.c -Dfoo=bar -Dhack=whatever \
#   -Dmumble=blaah"
# End:
@end example

  Some ``variable names'' have special meanings in a local variables
1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197
list:

@itemize
@item
@code{mode} enables the specified major or minor mode.

@item
@code{eval} evaluates the specified Lisp expression (the value
returned by that expression is ignored).

@item
Glenn Morris's avatar
Glenn Morris committed
1198
@code{coding} specifies the coding system for character code
1199 1200 1201 1202 1203 1204 1205 1206 1207 1208
conversion of this file.  @xref{Coding Systems}.

@item
@code{unibyte} says to visit the file in a unibyte buffer, if the
value is @code{t}.  @xref{Enabling Multibyte}.
@end itemize

@noindent
These four ``variables'' are not really variables; setting them in any
other context has no special meaning.
Glenn Morris's avatar
Glenn Morris committed
1209 1210 1211

  @emph{If @code{mode} is used to set a major mode, it should be the
first ``variable'' in the list.}  Otherwise, the entries that precede
1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225
it will usually have no effect, since most major modes kill all local
variables as part of their initialization.

  You can use the @code{mode} ``variable'' to enable minor modes as
well as the major modes; in fact, you can use it more than once, first
to set the major mode and then to enable minor modes which are
specific to particular buffers.

  Often, however, it is a mistake to enable minor modes this way.
Most minor modes, like Auto Fill mode, represent individual user
preferences.  If you want to use a minor mode, it is better to set up
major mode hooks with your init file to turn that minor mode on for
yourself alone (@pxref{Init File}), instead of using a local variable
list to impose your taste on everyone.
Glenn Morris's avatar
Glenn Morris committed
1226 1227 1228 1229 1230 1231 1232 1233 1234 1235

  Use the command @code{normal-mode} to reset the local variables and
major mode of a buffer according to the file name and contents,
including the local variables list if any.  @xref{Choosing Modes}.

@node Safe File Variables
@subsubsection Safety of File Variables

  File-local variables can be dangerous; when you visit someone else's
file, there's no telling what its local variables list could do to
1236
your Emacs.  Improper values of the @code{eval} ``variable'', and
Glenn Morris's avatar
Glenn Morris committed
1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247
other variables such as @code{load-path}, could execute Lisp code you
didn't intend to run.

  Therefore, whenever Emacs encounters file local variable values that
are not known to be safe, it displays the file's entire local
variables list, and asks you for confirmation before setting them.
You can type @kbd{y} or @key{SPC} to put the local variables list into
effect, or @kbd{n} to ignore it.  When Emacs is run in batch mode
(@pxref{Initial Options}), it can't really ask you, so it assumes the
answer @kbd{n}.

1248
  Emacs normally recognizes certain variable/value pairs as safe.
Glenn Morris's avatar
Glenn Morris committed
1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280
For instance, it is safe to give @code{comment-column} or
@code{fill-column} any integer value.  If a file specifies only
known-safe variable/value pairs, Emacs does not ask for confirmation
before setting them.  Otherwise, you can tell Emacs to record all the
variable/value pairs in this file as safe, by typing @kbd{!} at the
confirmation prompt.  When Emacs encounters these variable/value pairs
subsequently, in the same file or others, it will assume they are
safe.

@vindex safe-local-variable-values
@cindex risky variable
  Some variables, such as @code{load-path}, are considered
particularly @dfn{risky}: there is seldom any reason to specify them
as local variables, and changing them can be dangerous.  If a file
contains only risky local variables, Emacs neither offers nor accepts
@kbd{!} as input at the confirmation prompt.  If some of the local
variables in a file are risky, and some are only potentially unsafe, you
can enter @kbd{!} at the prompt.  It applies all the variables, but only
marks the non-risky ones as safe for the future.  If you really want to
record safe values for risky variables, do it directly by customizing
@samp{safe-local-variable-values} (@pxref{Easy Customization}).

@vindex enable-local-variables
  The variable @code{enable-local-variables} allows you to change the
way Emacs processes local variables.  Its default value is @code{t},
which specifies the behavior described above.  If it is @code{nil},
Emacs simply ignores all file local variables.  @code{:safe} means use
only the safe values and ignore the rest.  Any other value says to
query you about each file that has local variables, without trying to
determine whether the values are known to be safe.

@vindex enable-local-eval
1281
@vindex safe-local-eval-forms
Glenn Morris's avatar
Glenn Morris committed
1282 1283 1284 1285 1286 1287 1288
  The variable @code{enable-local-eval} controls whether Emacs
processes @code{eval} variables.  The three possibilities for the
variable's value are @code{t}, @code{nil}, and anything else, just as
for @code{enable-local-variables}.  The default is @code{maybe}, which
is neither @code{t} nor @code{nil}, so normally Emacs does ask for
confirmation about processing @code{eval} variables.

1289 1290 1291
  As an exception, Emacs never asks for confirmation to evaluate any
@code{eval} form if that form occurs within the variable
@code{safe-local-eval-forms}.
Glenn Morris's avatar
Glenn Morris committed
1292

1293 1294
@node Directory Variables
@subsection Per-Directory Local Variables
1295
@cindex local variables, for all files in a directory
1296
@cindex directory local variables
1297
@cindex per-directory local variables
1298

1299 1300 1301 1302
  A @dfn{project} is a collection of files on which you work together.
Usually, the project's files are kept in one or more directories.
Occasionally, you may wish to define Emacs settings that are common to
all the files that belong to the project.
1303

1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330
  Emacs provides two ways to specify settings that are applicable to
files in a specific directory: you can put a special file in that
directory, or you can define a @dfn{project class} for that directory.

@cindex @file{.dir-locals.el} file
  If you put a file with a special name @file{.dir-locals.el}@footnote{
On MS-DOS, the name of this file should be @file{_dir-locals.el}, due
to limitations of the DOS filesystems.  If the filesystem is limited
to 8+3 file names, the name of the file will be truncated by the OS to
@file{_dir-loc.el}.
} in a directory, Emacs will read it when it visits any file in that
directory or any of its subdirectories, and apply the settings it
specifies to the file's buffer.  Emacs searches for
@file{.dir-locals.el} starting in the directory of the visited file,
and moving up the directory tree.  (To avoid slowdown, this search is
skipped for remote files.)

  The @file{.dir-locals.el} file should hold a specially-constructed
list.  This list maps Emacs mode names (symbols) to alists; each alist
specifies values for variables to use when the respective mode is
turned on.  The special mode name @samp{nil} means that its alist
applies to any mode.  Instead of a mode name, you can specify a string
that is a name of a subdirectory of the project's directory; then the
corresponding alist applies to all the files in that subdirectory.

  Here's an example of a @file{.dir-locals.el} file:

1331 1332 1333 1334 1335 1336 1337
@example
((nil . ((indent-tabs-mode . t)
         (tab-width . 4)
         (fill-column . 80)))
 (c-mode . ((c-file-style . "BSD")))
 (java-mode . ((c-file-style . "BSD")))
 ("src/imported"
1338 1339
  . ((nil . ((change-log-default-name .
              "ChangeLog.local"))))))
1340 1341
@end example

1342 1343 1344 1345 1346 1347 1348 1349 1350
@noindent
This example shows some settings for a hypothetical project.  It sets
@samp{indent-tabs-mode}, @code{tab-width}, and @code{fill-column} for
any file in the project's directory tree, and it sets the indentation
style for any C or Java source file.  Finally, it specifies a different
@file{ChangeLog} file name for any file in the @file{src/imported}
subdirectory of the directory where you put the @file{.dir-locals.el}
file.

1351 1352 1353 1354 1355 1356 1357 1358 1359 1360
@findex add-dir-local-variable
@findex delete-dir-local-variable
@findex copy-file-locals-to-dir-locals
  You can edit the @file{.dir-locals.el} file by hand, or use the
command @code{add-dir-local-variable}.  This prompts for a mode (or
subdirectory), variable and value, and adds an entry to the file.
The command @code{delete-dir-local-variable} deletes an entry.  The
command @code{copy-file-locals-to-dir-locals} copies file local
variables (@pxref{File Variables}) to the @file{.dir-locals.el} file.

1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371
@findex dir-locals-set-class-variables
@findex dir-locals-set-directory-class
  Another method of specifying directory-local variables is to explicitly
define a project class using @code{dir-locals-set-class-variables}, and
then tell Emacs which directories correspond to that class, using
@code{dir-locals-set-directory-class}.  You can put calls to these functions
in your @file{~/.emacs} init file; this can be useful when you can't put
@file{.dir-locals.el} in the directory for some reason, or if you want
to keep in a single place settings for several directories that don't
have a common parent.  For example, you could apply settings to an
unwritable directory this way:
1372 1373

@example
Chong Yidong's avatar
Chong Yidong committed
1374
(dir-locals-set-class-variables 'unwritable-directory
1375 1376
   '((nil . ((some-useful-setting . value)))))

1377
(dir-locals-set-directory-class
Chong Yidong's avatar
Chong Yidong committed
1378
   "/usr/include/" 'unwritable-directory)
1379 1380 1381
@end example

  Unsafe directory-local variables are handled in the same way as
1382
unsafe file-local variables (@pxref{Safe File Variables}).
1383

Glenn Morris's avatar
Glenn Morris committed
1384 1385 1386 1387
@node Key Bindings
@section Customizing Key Bindings
@cindex key bindings

1388 1389 1390 1391
  This section describes @dfn{key bindings}, which map keys to
commands, and @dfn{keymaps}, which record key bindings.  It also
explains how to customize key bindings, which is done by editing your
init file (@pxref{Init Rebinding}).
Glenn Morris's avatar
Glenn Morris committed
1392 1393 1394 1395 1396 1397 1398 1399

@menu
* Keymaps::             Generalities.  The global keymap.
* Prefix Keymaps::      Keymaps for prefix keys.
* Local Keymaps::       Major and minor modes have their own keymaps.
* Minibuffer Maps::     The minibuffer uses its own local keymaps.
* Rebinding::           How to redefine one key's meaning conveniently.
* Init Rebinding::      Rebinding keys with your init file, @file{.emacs}.
Chong Yidong's avatar
Chong Yidong committed
1400
* Modifier Keys::       Using modifier keys in key bindings.
Glenn Morris's avatar
Glenn Morris committed
1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412
* Function Keys::       Rebinding terminal function keys.
* Named ASCII Chars::   Distinguishing @key{TAB} from @kbd{C-i}, and so on.
* Mouse Buttons::       Rebinding mouse buttons in Emacs.
* Disabling::           Disabling a command means confirmation is required
                          before it can be executed.  This is done to protect
                          beginners from surprises.
@end menu

@node Keymaps
@subsection Keymaps
@cindex keymap

1413 1414 1415 1416
  As described in @ref{Commands}, each Emacs command is a Lisp
function whose definition provides for interactive use.  Like every
Lisp function, a command has a function name, which usually consists
of lower-case letters and hyphens.
Glenn Morris's avatar
Glenn Morris committed
1417

1418 1419
  A @dfn{key sequence} (@dfn{key}, for short) is a sequence of
@dfn{input events} that have a meaning as a unit.  Input events
Glenn Morris's avatar
Glenn Morris committed
1420
include characters, function keys and mouse buttons---all the inputs
1421 1422 1423 1424 1425 1426
that you can send to the computer.  A key sequence gets its meaning
from its @dfn{binding}, which says what command it runs.

  The bindings between key sequences and command functions are
recorded in data structures called @dfn{keymaps}.  Emacs has many of
these, each used on particular occasions.
Glenn Morris's avatar
Glenn Morris committed
1427 1428 1429

@cindex global keymap
  The @dfn{global} keymap is the most important keymap because it is
1430 1431 1432 1433
always in effect.  The global keymap defines keys for Fundamental mode
(@pxref{Major Modes}); most of these definitions are common to most or
all major modes.  Each major or minor mode can have its own keymap
which overrides the global definitions of some keys.
Glenn Morris's avatar
Glenn Morris committed
1434 1435 1436

  For example, a self-inserting character such as @kbd{g} is
self-inserting because the global keymap binds it to the command
1437 1438 1439 1440 1441
@code{self-insert-command}.  The standard Emacs editing characters
such as @kbd{C-a} also get their standard meanings from the global
keymap.  Commands to rebind keys, such as @kbd{M-x global-set-key},
work by storing the new binding in the proper place in the global map
(@pxref{Rebinding}).
Glenn Morris's avatar
Glenn Morris committed
1442 1443 1444 1445

@cindex function key
  Most modern keyboards have function keys as well as character keys.
Function keys send input events just as character keys do, and keymaps
1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457
can have bindings for them.  Key sequences can mix function keys and
characters.  For example, if your keyboard has a @key{Home} function
key, Emacs can recognize key sequences like @kbd{C-x @key{Home}}.  You
can even mix mouse events with keyboard events, such as
@kbd{S-down-mouse-1}.

  On text terminals, typing a function key actually sends the computer
a sequence of characters; the precise details of the sequence depends
on the function key and on the terminal type.  (Often the sequence