[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to custom.texi
From: |
Glenn Morris |
Subject: |
[Emacs-diffs] Changes to custom.texi |
Date: |
Thu, 06 Sep 2007 04:44:55 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Glenn Morris <gm> 07/09/06 04:44:54
Index: custom.texi
===================================================================
RCS file: custom.texi
diff -N custom.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ custom.texi 6 Sep 2007 04:44:54 -0000 1.1
@@ -0,0 +1,2515 @@
address@hidden This is part of the Emacs manual.
address@hidden Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000,
2001,
address@hidden 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation,
Inc.
address@hidden See file emacs.texi for copying conditions.
address@hidden Customization, Quitting, Amusements, Top
address@hidden Customization
address@hidden customization
+
+ This chapter talks about various topics relevant to adapting the
+behavior of Emacs in ways we have anticipated.
address@hidden
+See @cite{The Emacs Lisp Reference Manual}
address@hidden iftex
address@hidden
address@hidden, Emacs Lisp, Emacs Lisp, elisp, The Emacs Lisp
+Reference Manual},
address@hidden ifnottex
+for how to make more far-reaching and open-ended changes. @xref{X
+Resources}, for information on using X resources to customize Emacs.
+
+ Customization that you do within Emacs normally affects only the
+particular Emacs session that you do it in---it does not persist
+between sessions unless you save the customization in a file such as
+your init file (@file{.emacs}) that will affect future sessions.
+(@xref{Init File}.) When you tell the customization buffer to save
+customizations for future sessions, this actually works by editing
address@hidden for you.
+
+ Another means of customization is the keyboard macro, which is a
+sequence of keystrokes to be replayed with a single command.
address@hidden Macros}, for full instruction how to record, manage, and
+replay sequences of keys.
+
address@hidden
+* Minor Modes:: Each minor mode is one feature you can turn on
+ independently of any others.
+* Easy Customization:: Convenient way to browse and change settings.
+* 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.
address@hidden menu
+
address@hidden Minor Modes
address@hidden Minor Modes
address@hidden minor modes
address@hidden mode, minor
+
+ Minor modes are optional features which you can turn on or off. For
+example, Auto Fill mode is a minor mode in which @key{SPC} breaks lines
+between words as you type. All the minor modes are independent of each
+other 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.
+
+ You should append @code{-mode} to the name of a minor mode to
+produce the name of the command that turns the mode on or off. Thus,
+the command to enable or disable Auto Fill mode is called
address@hidden These commands are usually invoked with
address@hidden, but you can bind keys to them if you wish.
+
+ With no argument, the minor mode function turns the mode on if it
+was off, and off if it was on. This is known as @dfn{toggling}. A
+positive argument always turns the mode on, and an explicit zero
+argument or a negative argument always turns it off.
+
+ Some minor modes are global: while enabled, they affect everything
+you do in the Emacs session, in all buffers. Other minor modes are
+buffer-local; they apply only to the current buffer, so you can enable
+the mode in certain buffers and not others.
+
+ For most minor modes, the command name is also the name of a
+variable. The variable's value is address@hidden if the mode is
+enabled and @code{nil} if it is disabled. Some minor-mode commands
+work by just setting the variable. For example, the command
address@hidden works by setting the value of @code{abbrev-mode} as
+a variable; it is this variable that directly turns Abbrev mode on and
+off. You can directly set the variable's value instead of calling the
+mode function. For other minor modes, you need to either set the
+variable through the Customize interface or call the mode function to
+correctly enable or disable the mode. To check which of these two
+possibilities applies to a given minor mode, use @kbd{C-h v} to ask
+for documentation on the variable name.
+
+ For minor mode commands that work by just setting the minor mode
+variable, that variable provides a good way for Lisp programs to turn
+minor modes on and off; it is also useful in a file's local variables
+list (@pxref{File Variables}). But please think twice before setting
+minor modes with a local variables list, because most minor modes are
+a matter of user preference---other users editing the same file might
+not want the same minor modes you prefer.
+
+ The most useful buffer-local minor modes include Abbrev mode, Auto
+Fill mode, Auto Save mode, Font-Lock mode, Glasses mode, Outline minor
+mode, Overwrite mode, and Binary Overwrite mode.
+
+ Abbrev mode allows you to define abbreviations that automatically expand
+as you type them. For example, @samp{amd} might expand to @samp{abbrev
+mode}. @xref{Abbrevs}, for full information.
+
+ Auto Fill mode allows you to enter filled text without breaking lines
+explicitly. Emacs inserts newlines as necessary to prevent lines from
+becoming too long. @xref{Filling}.
+
+ Auto Save mode saves the buffer contents periodically to reduce the
+amount of work you can lose in case of a crash. @xref{Auto Save}.
+
+ Enriched mode enables editing and saving of formatted text.
address@hidden Text}.
+
+ Flyspell mode automatically highlights misspelled words.
address@hidden
+
+ Font-Lock mode automatically highlights certain textual units found
+in programs, such as comments, strings, and function names being
+defined. This requires a display that can show multiple fonts or
+colors. @xref{Faces}.
+
address@hidden
+ ISO Accents mode makes the characters @samp{`}, @samp{'}, @samp{"},
address@hidden, @samp{/} and @samp{~} combine with the following letter, to
+produce an accented letter in the ISO Latin-1 character set. The
+newer and more general feature of input methods more or less
+supersedes ISO Accents mode. @xref{Unibyte Mode}.
address@hidden ignore
+
+ Outline minor mode provides the same facilities as the major mode
+called Outline mode; but since it is a minor mode instead, you can
+combine it with any major mode. @xref{Outline Mode}.
+
address@hidden Overwrite mode
address@hidden mode, Overwrite
+ 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
address@hidden 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.
+
address@hidden overwrite-mode
address@hidden INSERT
+ The command @code{overwrite-mode} is an exception to the rule that
+commands which toggle minor modes are normally not bound to keys: it is
+bound to the @key{INSERT} function key. This is because many other
+programs bind @key{INSERT} to similar functions.
+
address@hidden binary-overwrite-mode
+ 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.
+
+ Here are some useful minor modes that normally apply to all buffers
+at once. 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}.
+
+ Icomplete mode displays an indication of available completions when
+you are in the minibuffer and completion is active. @xref{Completion
+Options}.
+
+ Line Number mode enables continuous display in the mode line of the
+line number of point, and Column Number mode enables display of the
+column number. @xref{Mode Line}.
+
+ Scroll Bar mode gives each window a scroll bar (@pxref{Scroll Bars}).
+Menu Bar mode gives each frame a menu bar (@pxref{Menu Bars}). Both of
+these modes are enabled by default when you use the X Window System.
+
+ In Transient Mark mode, every change in the buffer contents
+``deactivates'' the mark, so that commands that operate on the region
+will get an error. This means you must either set the mark, or
+explicitly ``reactivate'' it, before each command that uses the region.
+The advantage of Transient Mark mode is that Emacs can display the
+region highlighted. @xref{Mark}.
+
address@hidden Easy Customization
address@hidden Easy Customization Interface
+
address@hidden settings
+ Emacs has many @dfn{settings} which have values that you can specify
+in order to customize various commands. Many are documented in this
+manual. Most settings are @dfn{user options}---that is to say, Lisp
+variables (@pxref{Variables})---so their names appear in the Variable
+Index (@pxref{Variable Index}). The other settings are faces and
+their attributes (@pxref{Faces}).
+
address@hidden customize
address@hidden customization buffer
+ You can browse interactively through settings and change them using
address@hidden customize}. This command creates a @dfn{customization
+buffer}, which offers commands to navigate through a logically
+organized structure of the Emacs settings; you can also use it to edit
+and set their values, and to save settings permanently in your
address@hidden/.emacs} file (@pxref{Init File}).
+
+ The appearance of the example buffers in this section is typically
+different under a graphical display, since faces are then used to indicate
+buttons, links and editable fields.
+
address@hidden
+* Groups: Customization Groups. How settings are classified in a structure.
+* Browsing: Browsing Custom. Browsing and searching for settings.
+* 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.
address@hidden menu
+
address@hidden Customization Groups
address@hidden Customization Groups
address@hidden 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:
+
address@hidden we want the buffer example to all be on one page, but
unfortunately
address@hidden that's quite a bit of text, so force all space to the bottom.
address@hidden
address@hidden
address@hidden
+/- Emacs group: ---------------------------------------------------\
+ [State]: visible group members are all at standard values.
+ Customization of the One True Editor.
+ See also [Manual].
+
+Editing group: [Go to Group]
+Basic text editing facilities.
+
+External group: [Go to Group]
+Interfacing to external utilities.
+
address@hidden second-level groups}
+
+\- Emacs group end ------------------------------------------------/
address@hidden group
address@hidden smallexample
+
address@hidden
+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
address@hidden contents are not included. Each group has a single-line
+documentation string; the @code{Emacs} group also has a @samp{[State]}
+line.
+
address@hidden editable fields (customization buffer)
address@hidden buttons (customization buffer)
address@hidden 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}.
+
+ For example, the phrase @samp{[State]} that appears in
+a second-level group is a button. It operates on the same
+customization buffer. The phrase @samp{[Go to Group]} is a kind
+of hypertext link to another group. Invoking it creates a new
+customization buffer, which shows that group and its contents.
+
+ The @code{Emacs} group includes a few settings, but mainly it
+contains other groups, which contain more groups, which contain the
+settings. 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}.
+
address@hidden Browsing Custom
address@hidden Browsing and Searching for Options and Faces
address@hidden 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
address@hidden 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
address@hidden, @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},
address@hidden can only find groups and settings that are
+loaded in the current Emacs session. @xref{Specific Customization,,
+Customizing Specific Items}.
+
address@hidden Changing a Variable
address@hidden Changing a Variable
+
+ Here is an example of what a variable (a user option) looks like in
+the customization buffer:
+
address@hidden
+Kill Ring Max: [Hide Value] 60
+ [State]: STANDARD.
+Maximum length of kill ring before oldest elements are thrown away.
address@hidden 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
address@hidden Value]}, it means that the value is hidden; the customization
+buffer initially hides values that take up several lines. Invoke
address@hidden 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:
+
address@hidden
+[State]: EDITED, shown value does not take effect until you set or
@address@hidden
+ save it.
address@hidden smallexample
+
address@hidden user options, how to set
address@hidden variables, how to set
address@hidden 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
address@hidden button and choose @samp{Set for Current Session}.
+
+ The state of the variable changes visibly when you set it:
+
address@hidden
+[State]: SET for current session only.
address@hidden 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.
+
address@hidden M-TAB @r{(customization buffer)}
address@hidden 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 @address@hidden (@code{widget-complete}) to do completion.
+(@address@hidden @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
address@hidden 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.
address@hidden 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:
+
address@hidden
+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 @address@hidden
+ operation. [Hide Rest]
+The format is ((PATTERN . VAL) ...),
+where PATTERN is a regular expression matching a file name,
address@hidden@dots{}more lines of address@hidden
address@hidden smallexample
+
address@hidden
+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
address@hidden 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.
+
address@hidden TAB @r{(customization buffer)}
address@hidden S-TAB @r{(customization buffer)}
address@hidden widget-forward
address@hidden widget-backward
+ Two special commands, @key{TAB} and @address@hidden, are useful
+for moving through the customization buffer. @key{TAB}
+(@code{widget-forward}) moves forward to the next button or editable
+field; @address@hidden (@code{widget-backward}) moves backward to
+the previous button or editable field.
+
+ Typing @key{RET} on an editable field also moves forward, just like
address@hidden We set it up this way because people often type @key{RET}
+when they are finished editing a field. To insert a newline within an
+editable field, use @kbd{C-o} or @kbd{C-q C-j}.
+
address@hidden saving a setting
address@hidden settings, how to save
+ Setting the variable changes its value in the current Emacs session;
address@hidden 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
address@hidden and selecting the @samp{Erase Customization} operation.
+There are actually four reset operations:
+
address@hidden @samp
address@hidden 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.
+
address@hidden Reset to Saved
+This restores the value of the variable to the last saved value,
+and updates the text accordingly.
+
address@hidden 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.
+
address@hidden 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.
address@hidden table
+
address@hidden comments on customized settings
+ Sometimes it is useful to record a comment about a specific
+customization. Use the @samp{Add Comment} item from the
address@hidden 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:
+
address@hidden
+ [Set for Current Session] [Save for Future Sessions]
+ [Undo Edits] [Reset to Saved] [Erase Customization] [Finish]
address@hidden smallexample
+
address@hidden custom-buffer-done-function
address@hidden
+Invoking @samp{[Finish]} either buries or kills this customization
+buffer according to the setting of the option
address@hidden; 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.
+
address@hidden Saving Customizations
address@hidden Saving Customizations
+
+ Saving customizations from the customization buffer works by writing
+code that future sessions will read, code to set up those
+customizations again.
+
address@hidden custom-file
+ Normally this saves customizations in your init file,
address@hidden/.emacs}. If you wish, you can save customizations in another
+file instead. To make this work, your @file{~/.emacs} should set
address@hidden to the name of that file. Then you should load the
+file by calling @code{load}. For example:
+
address@hidden
+(setq custom-file "~/.emacs-custom.el")
+(load custom-file)
address@hidden example
+
+ You can use @code{custom-file} to specify different customization
+files for different Emacs versions, like this:
+
address@hidden
+(cond ((< emacs-major-version 21)
+ ;; @r{Emacs 20 customization.}
+ (setq custom-file "~/.custom-20.el"))
+ ((and (= emacs-major-version 21) (< emacs-minor-version 4))
+ ;; @r{Emacs 21 customization, before version 21.4.}
+ (setq custom-file "~/.custom-21.el"))
+ ((< emacs-major-version 22)
+ ;; @r{Emacs version 21.4 or later.}
+ (setq custom-file "~/.custom-21.4.el"))
+ (t
+ ;; @r{Emacs version 22.1 or later.}
+ (setq custom-file "~/.custom-22.el")))
+
+(load custom-file)
address@hidden 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
+customizations in your @file{~/.emacs} init file. This is because
+saving customizations from such a session would wipe out all the other
+customizations you might have on your init file.
+
address@hidden Face Customization
address@hidden Customizing Faces
address@hidden customizing faces
address@hidden bold font
address@hidden italic font
address@hidden 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:
+
address@hidden
+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: *
address@hidden smallexample
+
+ Each face attribute has its own line. The @address@hidden button
+before the attribute name indicates whether the attribute is
address@hidden; @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.
+
+ For the colors, 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 @address@hidden@address@hidden
+(@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
address@hidden, @samp{white}, @samp{gray}, @samp{gray1}, and
address@hidden Emacs supports these shades of gray by using background
+stipple patterns instead of a color.
+
+ 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]}.
+
address@hidden 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.
+
address@hidden Specific Customization
address@hidden 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.
+
address@hidden @kbd
address@hidden M-x customize-option @key{RET} @var{option} @key{RET}
+Set up a customization buffer with just one user option variable,
address@hidden
address@hidden M-x customize-face @key{RET} @var{face} @key{RET}
+Set up a customization buffer with just one face, @var{face}.
address@hidden M-x customize-group @key{RET} @var{group} @key{RET}
+Set up a customization buffer with just one group, @var{group}.
address@hidden 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}.
address@hidden 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}.
address@hidden M-x customize-saved
+Set up a customization buffer containing all settings that you
+have saved with customization buffers.
address@hidden M-x customize-unsaved
+Set up a customization buffer containing all settings that you have
+set but not saved.
address@hidden table
+
address@hidden 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.
+
address@hidden customize-face
+ Likewise, you can modify a specific face, chosen by name, using
address@hidden customize-face}. By default it operates on the face used
+on the character after point.
+
address@hidden 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.
+
address@hidden customize-apropos
+ For a more general way of controlling what to customize, you can use
address@hidden 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.
+
address@hidden 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.
+
address@hidden customize-saved
address@hidden 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
address@hidden 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.
+
address@hidden Custom Themes
address@hidden Customization Themes
address@hidden 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.
+
address@hidden 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}.
+
address@hidden 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
address@hidden@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
address@hidden file.
+
address@hidden 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
address@hidden 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.
+
address@hidden load-theme
address@hidden enable-theme
address@hidden 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.)
+
address@hidden Variables
address@hidden Variables
address@hidden variable
address@hidden option, user
address@hidden user option
+
+ A @dfn{variable} is a Lisp symbol which has a value. The symbol's
+name is also called the name of the variable. A variable name can
+contain any characters that can appear in a file, but conventionally
+variable names consist of words separated by hyphens. A variable can
+have a documentation string which describes what kind of value it should
+have and how the value will be used.
+
+ Emacs Lisp allows any variable (with a few exceptions) to have any
+kind of value, but most variables that Emacs uses expect a value of a
+certain type. Often the value should always be a string, or should
+always be a number. Sometimes we say that a certain feature is turned
+on if a variable is address@hidden,'' meaning that if the variable's
+value is @code{nil}, the feature is off, but the feature is on for
address@hidden other value. The conventional value to use to turn on the
+feature---since you have to pick one particular value when you set the
+variable---is @code{t}.
+
+ Emacs uses many Lisp variables for internal record keeping, but the
+most interesting variables for a non-programmer user are those meant
+for users to change---these are called @dfn{user options}.
+
+ Each user option that you can set with the customization buffer is
+in fact a Lisp variable. Emacs does not (usually) change the values
+of these variables on its own; instead, you set the values in order to
+control the behavior of certain Emacs commands. Use of the
+customization buffer is explained above (@pxref{Easy Customization});
+here we describe other aspects of Emacs variables.
+
address@hidden
+* 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.
+* File Variables:: How files can specify variable values.
address@hidden menu
+
address@hidden Examining
address@hidden Examining and Setting Variables
address@hidden setting variables
+
address@hidden @kbd
address@hidden C-h v @var{var} @key{RET}
+Display the value and documentation of variable @var{var}
+(@code{describe-variable}).
address@hidden M-x set-variable @key{RET} @var{var} @key{RET} @var{value}
@key{RET}
+Change the value of variable @var{var} to @var{value}.
address@hidden 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,
+
address@hidden
+C-h v fill-column @key{RET}
address@hidden example
+
address@hidden
+displays something like this:
+
address@hidden
+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.
+
+This variable is safe to use as a file local variable only if its value
+satisfies the predicate `integerp'.
+
+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.
address@hidden smallexample
+
address@hidden
+The line that says you can customize the variable indicates that this
+variable is a user option. (The star also indicates this, but it is
+an obsolete indicator that may eventually disappear.) @kbd{C-h v} is
+not restricted to user options; it allows any variable name.
+
address@hidden set-variable
+The most convenient way to set a specific user option variable is with
address@hidden set-variable}. This reads the variable name with the
+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,
+
address@hidden
+M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET}
address@hidden example
+
address@hidden
+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}:
+
address@hidden
+(setq fill-column 75)
address@hidden 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
+the @file{~/.emacs} file to set it those sessions (@pxref{Init File}).
+
address@hidden Hooks
address@hidden Hooks
address@hidden hook
address@hidden running a hook
+
+ @dfn{Hooks} are an important mechanism for customization of 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{suspend-hook} runs just before
+Emacs suspends itself (@pxref{Exiting}).
+
address@hidden 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.
+
address@hidden 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,
address@hidden (@pxref{Visiting}) is abnormal because
+as soon as one hook function returns a address@hidden value, the rest
+are not called at all. The documentation of each abnormal hook variable
+explains in detail what is peculiar about it.
+
address@hidden 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}.
address@hidden,,, 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:
+
address@hidden
+(add-hook 'text-mode-hook 'turn-on-auto-fill)
address@hidden 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.
+
address@hidden
address@hidden
+(setq my-c-style
+ '((c-comment-only-line-offset . 4)
address@hidden group
address@hidden
+ (c-cleanup-list . (scope-operator
+ empty-defun-braces
+ defun-close-semi))
address@hidden group
address@hidden
+ (c-offsets-alist . ((arglist-close . c-lineup-arglist)
+ (substatement-open . 0)))))
address@hidden group
+
address@hidden
+(add-hook 'c-mode-common-hook
+ '(lambda ()
+ (c-add-style "my-style" my-c-style t)))
address@hidden group
address@hidden 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.
+
address@hidden 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.
+
address@hidden Locals
address@hidden Local Variables
+
address@hidden @kbd
address@hidden M-x make-local-variable @key{RET} @var{var} @key{RET}
+Make variable @var{var} have a local value in the current buffer.
address@hidden M-x kill-local-variable @key{RET} @var{var} @key{RET}
+Make variable @var{var} use its global value in the current buffer.
address@hidden 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.
address@hidden table
+
address@hidden 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.
+
address@hidden 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.
+
address@hidden make-variable-buffer-local
address@hidden 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 address@hidden 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.
+
address@hidden 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}.
+
address@hidden 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
address@hidden, 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:
+
address@hidden
+(setq-default fill-column 75)
address@hidden example
+
address@hidden
address@hidden is the only way to set the global value of a variable
+that has been marked with @code{make-variable-buffer-local}.
+
address@hidden 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
address@hidden:
+
address@hidden
+(default-value 'fill-column)
address@hidden example
+
address@hidden File Variables
address@hidden Local Variables in Files
address@hidden local variables in files
address@hidden 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.
+
address@hidden
+* Specifying File Variables:: Specifying file local variables.
+* Safe File Variables:: Making sure file local variables are safe.
address@hidden menu
+
address@hidden Specifying File Variables
address@hidden 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:
+
address@hidden
+-*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*-
address@hidden example
+
address@hidden
+You can specify any number of variables/value pairs in this way, each
+pair with a colon and semicolon as shown above. @code{mode:
address@hidden;} specifies the major mode; this should come first in the
+line. The @var{value}s are not evaluated; they are used literally.
+Here is an example that specifies Lisp mode and sets two variables with
+numeric values:
+
address@hidden
+;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*-
address@hidden smallexample
+
+ You can also specify the coding system for a file in this way: just
+specify a value for the ``variable'' named @code{coding}. The ``value''
+must be a coding system name that Emacs recognizes. @xref{Coding
+Systems}. @address@hidden: t}} specifies unibyte loading for a
+particular Lisp file. @xref{Enabling Multibyte}.
+
+ The @code{eval} pseudo-variable, described below, can be specified in
+the first line as well.
+
address@hidden shell scripts, and local file variables
+ 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
address@hidden line when the first line specifies an interpreter.
+
+ A @dfn{local variables list} goes near the end of the file, in the
+last page. (It is often best to put it on a page by itself.) The 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, as
address@hidden@var{variable}:@: @var{value}}. The @var{value}s are not
+evaluated; they are used literally. 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.
+
+ Here is an example of a local variables list:
+
address@hidden
+;; Local Variables: **
+;; mode:lisp **
+;; comment-column:0 **
+;; comment-start: ";; " **
+;; comment-end:"**" **
+;; End: **
address@hidden example
+
+ Each line starts with the prefix @samp{;; } and each line ends with
+the suffix @samp{ **}. Emacs recognizes these as the prefix and
+suffix based on the first line of the list, by finding them
+surrounding the magic string @samp{Local Variables:}; then it
+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 as input for. The example above is for a
+language where comment lines start with @samp{;; } and end with
address@hidden; the local values for @code{comment-start} and
address@hidden customize the rest of Emacs for this unusual
+syntax. Don't use a prefix (or a suffix) if you don't need one.
+
+ If you write a multi-line string value, you should put the prefix
+and suffix on each line, even lines that start or end within the
+string. They will be stripped off for processing the list. 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.
+Here's an example of doing this:
+
address@hidden
+# Local Variables:
+# compile-command: "cc foo.c -Dfoo=bar -Dhack=whatever \
+# -Dmumble=blaah"
+# End:
address@hidden example
+
+ Some ``variable names'' have special meanings in a local variables
+list. Specifying the ``variable'' @code{mode} really sets the major
+mode, while any value specified for the ``variable'' @code{eval} is
+simply evaluated as an expression (its value is ignored). A value for
address@hidden specifies the coding system for character code
+conversion of this file, and a value of @code{t} for @code{unibyte}
+says to visit the file in a unibyte buffer. These four ``variables''
+are not really variables; setting them in any other context has no
+special meaning.
+
+ @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
+it will usually be ignored, since most modes kill all local variables
+as part of their initialization.
+
+ You can use the @code{mode} ``variable'' to set 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 set minor modes which are specific to
+particular buffers. But most minor modes should not be specified in
+the file at all, because they represent user preferences.
+
+ For example, you may be tempted to try to turn on Auto Fill mode with
+a local variable list. That is a mistake. The choice of Auto Fill mode
+or not is a matter of individual taste, not a matter of the contents of
+particular files. If you want to use Auto Fill, set up major mode hooks
+with your @file{.emacs} file to turn it on (when appropriate) for you
+alone (@pxref{Init File}). Don't use a local variable list to impose
+your taste on everyone.
+
+ The start of the local variables list must be no more than 3000
+characters from the end of the file, and must be in the last page if the
+file is divided into pages. Otherwise, Emacs will not notice it is
+there. The purpose of this rule is so that a stray @samp{Local
+Variables:}@: not in the last page does not confuse Emacs, and so that
+visiting a long file that is all one page and has no local variables
+list need not take the time to search the whole file.
+
+ 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}.
+
address@hidden Safe File Variables
address@hidden 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
+your Emacs. Improper values of the @code{eval} ``variable,'' and
+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}.
+
+ Emacs normally recognizes certain variables/value pairs as safe.
+For instance, it is safe to give @code{comment-column} or
address@hidden 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.
+
address@hidden safe-local-variable-values
address@hidden 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
address@hidden 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
address@hidden (@pxref{Easy Customization}).
+
address@hidden 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.
+
address@hidden enable-local-eval
+ 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.
+
address@hidden safe-local-eval-forms
+ But there is an exception. The @code{safe-local-eval-forms} is a
+customizable list of eval forms which are safe. Emacs does not ask
+for confirmation when it finds these forms for the @code{eval}
+variable.
+
address@hidden Key Bindings
address@hidden Customizing Key Bindings
address@hidden key bindings
+
+ 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.
+
+ Recall that a 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.
+
address@hidden
+* 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}.
+* 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.
address@hidden menu
+
address@hidden Keymaps
address@hidden Keymaps
address@hidden keymap
+
+ 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.
+
+ Recall that a @dfn{key sequence} (@dfn{key}, for short) is a sequence
+of @dfn{input events} that have a meaning as a unit. Input events
+include characters, function keys and mouse buttons---all the inputs
+that you can send to the computer with your terminal. A key sequence
+gets its meaning from its @dfn{binding}, which says what command it
+runs. The function of keymaps is to record these bindings.
+
address@hidden global keymap
+ The @dfn{global} keymap is the most important keymap because it is
+always in effect. The global keymap defines keys for Fundamental mode;
+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.
+
+ For example, a self-inserting character such as @kbd{g} is
+self-inserting because the global keymap binds it to the command
address@hidden 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}, actually work
+by storing the new binding in the proper place in the global map.
address@hidden
+
+ Meta characters work differently; Emacs translates each Meta
+character into a pair of characters starting with @key{ESC}. When you
+type the character @kbd{M-a} in a key sequence, Emacs replaces it with
address@hidden@key{ESC} a}. A meta key comes in as a single input event, but
+becomes two events for purposes of key bindings. The reason for this is
+historical, and we might change it someday.
+
address@hidden 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
+can have bindings for them.
+
+ On text terminals, typing a function key actually sends the computer a
+sequence of characters; the precise details of the sequence depends on
+which function key and on the model of terminal you are using. (Often
+the sequence starts with @address@hidden [}.) If Emacs understands your
+terminal type properly, it recognizes the character sequences forming
+function keys wherever they occur in a key sequence (not just at the
+beginning). Thus, for most purposes, you can pretend the function keys
+reach Emacs directly and ignore their encoding as character sequences.
+
address@hidden mouse
+ Mouse buttons also produce input events. These events come with other
+data---the window and position where you pressed or released the button,
+and a time stamp. But only the choice of button matters for key
+bindings; the other data matters only if a command looks at it.
+(Commands designed for mouse invocation usually do look at the other
+data.)
+
+ A keymap records definitions for single events. Interpreting a key
+sequence of multiple events involves a chain of keymaps. The first
+keymap gives a definition for the first event; this definition is
+another keymap, which is used to look up the second event in the
+sequence, and so on.
+
+ Key sequences can mix function keys and characters. For example,
address@hidden @key{SELECT}} is meaningful. If you make @key{SELECT} a prefix
+key, then @address@hidden C-n} makes sense. You can even mix mouse
+events with keyboard events, but we recommend against it, because such
+key sequences are inconvenient to use.
+
+ As a user, you can redefine any key; but it is usually best to stick
+to key sequences that consist of @kbd{C-c} followed by a letter (upper
+or lower case). These keys are ``reserved for users,'' so they won't
+conflict with any properly designed Emacs extension. The function
+keys @key{F5} through @key{F9} are also reserved for users. If you
+redefine some other key, your definition may be overridden by certain
+extensions or major modes which redefine the same key.
+
address@hidden Prefix Keymaps
address@hidden Prefix Keymaps
+
+ A prefix key such as @kbd{C-x} or @key{ESC} has its own keymap,
+which holds the definition for the event that immediately follows
+that prefix.
+
+ The definition of a prefix key is usually the keymap to use for
+looking up the following event. The definition can also be a Lisp
+symbol whose function definition is the following keymap; the effect is
+the same, but it provides a command name for the prefix key that can be
+used as a description of what the prefix key is for. Thus, the binding
+of @kbd{C-x} is the symbol @code{Control-X-prefix}, whose function
+definition is the keymap for @kbd{C-x} commands. The definitions of
address@hidden, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix keys appear in
+the global map, so these prefix keys are always available.
+
+ Aside from ordinary prefix keys, there is a fictitious ``prefix key''
+which represents the menu bar; see @ref{Menu Bar,,,elisp, The Emacs Lisp
+Reference Manual}, for special information about menu bar key bindings.
+Mouse button events that invoke pop-up menus are also prefix keys; see
address@hidden Keymaps,,,elisp, The Emacs Lisp Reference Manual}, for more
+details.
+
+ Some prefix keymaps are stored in variables with names:
+
address@hidden @bullet
address@hidden
address@hidden ctl-x-map
address@hidden is the variable name for the map used for characters that
+follow @kbd{C-x}.
address@hidden
address@hidden help-map
address@hidden is for characters that follow @kbd{C-h}.
address@hidden
address@hidden esc-map
address@hidden is for characters that follow @key{ESC}. Thus, all Meta
+characters are actually defined by this map.
address@hidden
address@hidden ctl-x-4-map
address@hidden is for characters that follow @kbd{C-x 4}.
address@hidden
address@hidden mode-specific-map
address@hidden is for characters that follow @kbd{C-c}.
address@hidden itemize
+
address@hidden Local Keymaps
address@hidden Local Keymaps
+
address@hidden local keymap
+ So far we have explained the ins and outs of the global map. Major
+modes customize Emacs by providing their own key bindings in @dfn{local
+keymaps}. For example, C mode overrides @key{TAB} to make it indent the
+current line for C code. Portions of text in the buffer can specify
+their own keymaps to substitute for the keymap of the buffer's major
+mode.
+
address@hidden minor mode keymap
+ Minor modes can also have local keymaps. Whenever a minor mode is
+in effect, the definitions in its keymap override both the major
+mode's local keymap and the global keymap.
+
+ A local keymap can locally redefine a key as a prefix key by defining
+it as a prefix keymap. If the key is also defined globally as a prefix,
+then its local and global definitions (both keymaps) effectively
+combine: both of them are used to look up the event that follows the
+prefix key. Thus, if the mode's local keymap defines @kbd{C-c} as
+another keymap, and that keymap defines @kbd{C-z} as a command, this
+provides a local meaning for @kbd{C-c C-z}. This does not affect other
+sequences that start with @kbd{C-c}; if those sequences don't have their
+own local bindings, their global bindings remain in effect.
+
+ Another way to think of this is that Emacs handles a multi-event key
+sequence by looking in several keymaps, one by one, for a binding of the
+whole key sequence. First it checks the minor mode keymaps for minor
+modes that are enabled, then it checks the major mode's keymap, and then
+it checks the global keymap. This is not precisely how key lookup
+works, but it's good enough for understanding the results in ordinary
+circumstances.
+
address@hidden rebinding major mode keys
+ Most major modes construct their keymaps when the mode is used for
+the first time in a session. If you wish to change one of these
+keymaps, you must use the major mode's @dfn{mode hook}
+(@pxref{Hooks}).
+
address@hidden define-key
+ For example, the command @code{texinfo-mode} to select Texinfo mode
+runs the hook @code{texinfo-mode-hook}. Here's how you can use the hook
+to add local bindings (not very useful, we admit) for @kbd{C-c n} and
address@hidden p} in Texinfo mode:
+
address@hidden
+(add-hook 'texinfo-mode-hook
+ '(lambda ()
+ (define-key texinfo-mode-map "\C-cp"
+ 'backward-paragraph)
+ (define-key texinfo-mode-map "\C-cn"
+ 'forward-paragraph)))
address@hidden example
+
address@hidden Minibuffer Maps
address@hidden Minibuffer Keymaps
+
address@hidden minibuffer keymaps
address@hidden minibuffer-local-map
address@hidden minibuffer-local-ns-map
address@hidden minibuffer-local-completion-map
address@hidden minibuffer-local-must-match-map
address@hidden minibuffer-local-filename-completion-map
address@hidden minibuffer-local-must-match-filename-map
+ The minibuffer has its own set of local keymaps; they contain various
+completion and exit commands.
+
address@hidden @bullet
address@hidden
address@hidden is used for ordinary input (no completion).
address@hidden
address@hidden is similar, except that @key{SPC} exits
+just like @key{RET}. This is used mainly for Mocklisp compatibility.
address@hidden
address@hidden is for permissive completion.
address@hidden
address@hidden is for strict completion and
+for cautious completion.
address@hidden
+Finally, @code{minibuffer-local-filename-completion-map} and
address@hidden are like the two
+previous ones, but they are specifically for file name completion.
+They do not bind @key{SPC}.
address@hidden itemize
+
address@hidden Rebinding
address@hidden Changing Key Bindings Interactively
address@hidden key rebinding, this session
address@hidden redefining keys, this session
+
+ The way to redefine an Emacs key is to change its entry in a keymap.
+You can change the global keymap, in which case the change is effective in
+all major modes (except those that have their own overriding local
+definitions for the same key). Or you can change the current buffer's
+local map, which affects all buffers using the same major mode.
+
address@hidden global-set-key
address@hidden local-set-key
address@hidden global-unset-key
address@hidden local-unset-key
address@hidden @kbd
address@hidden M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}
+Define @var{key} globally to run @var{cmd}.
address@hidden M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET}
+Define @var{key} locally (in the major mode now in effect) to run
address@hidden
address@hidden M-x global-unset-key @key{RET} @var{key}
+Make @var{key} undefined in the global map.
address@hidden M-x local-unset-key @key{RET} @var{key}
+Make @var{key} undefined locally (in the major mode now in effect).
address@hidden table
+
+ For example, suppose you like to execute commands in a subshell within
+an Emacs buffer, instead of suspending Emacs and executing commands in
+your login shell. Normally, @kbd{C-z} is bound to the function
address@hidden (when not using the X Window System), but you can
+change @kbd{C-z} to invoke an interactive subshell within Emacs, by
+binding it to @code{shell} as follows:
+
address@hidden
+M-x global-set-key @key{RET} C-z shell @key{RET}
address@hidden example
+
address@hidden
address@hidden reads the command name after the key. After you
+press the key, a message like this appears so that you can confirm that
+you are binding the key you want:
+
address@hidden
+Set key C-z to command:
address@hidden example
+
+ You can redefine function keys and mouse events in the same way; just
+type the function key or click the mouse when it's time to specify the
+key to rebind.
+
+ You can rebind a key that contains more than one event in the same
+way. Emacs keeps reading the key to rebind until it is a complete key
+(that is, not a prefix key). Thus, if you type @kbd{C-f} for
address@hidden, that's the end; it enters the minibuffer immediately to
+read @var{cmd}. But if you type @kbd{C-x}, since that's a prefix, it
+reads another character; if that is @kbd{4}, another prefix character,
+it reads one more character, and so on. For example,
+
address@hidden
+M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET}
address@hidden example
+
address@hidden
+redefines @kbd{C-x 4 $} to run the (fictitious) command
address@hidden
+
+ The two-character keys consisting of @kbd{C-c} followed by a letter
+are reserved for user customizations. Lisp programs are not supposed to
+define these keys, so the bindings you make for them will be available
+in all major modes and will never get in the way of anything.
+
+ You can remove the global definition of a key with
address@hidden This makes the key @dfn{undefined}; if you
+type it, Emacs will just beep. Similarly, @code{local-unset-key} makes
+a key undefined in the current major mode keymap, which makes the global
+definition (or lack of one) come back into effect in that major mode.
+
+ If you have redefined (or undefined) a key and you subsequently wish
+to retract the change, undefining the key will not do the job---you need
+to redefine the key with its standard definition. To find the name of
+the standard definition of a key, go to a Fundamental mode buffer in a
+fresh Emacs and use @kbd{C-h c}. The documentation of keys in this
+manual also lists their command names.
+
+ If you want to prevent yourself from invoking a command by mistake, it
+is better to disable the command than to undefine the key. A disabled
+command is less work to invoke when you really want to.
address@hidden
+
address@hidden Init Rebinding
address@hidden Rebinding Keys in Your Init File
+
+ If you have a set of key bindings that you like to use all the time,
+you can specify them in your @file{.emacs} file by using their Lisp
+syntax. (@xref{Init File}.)
+
+ The simplest method for doing this works for @acronym{ASCII} characters and
+Meta-modified @acronym{ASCII} characters only. This method uses a string to
+represent the key sequence you want to rebind. For example, here's how
+to bind @kbd{C-z} to @code{shell}:
+
address@hidden
+(global-set-key "\C-z" 'shell)
address@hidden example
+
address@hidden
+This example uses a string constant containing one character,
address@hidden (@samp{\C-} is string syntax for a control character.) The
+single-quote before the command name, @code{shell}, marks it as a
+constant symbol rather than a variable. If you omit the quote, Emacs
+would try to evaluate @code{shell} immediately as a variable. This
+probably causes an error; it certainly isn't what you want.
+
+ Here is another example that binds the key sequence @kbd{C-x M-l}:
+
address@hidden
+(global-set-key "\C-x\M-l" 'make-symbolic-link)
address@hidden example
+
+ To put @key{TAB}, @key{RET}, @key{ESC}, or @key{DEL} in the
+string, you can use the Emacs Lisp escape sequences, @samp{\t},
address@hidden, @samp{\e}, and @samp{\d}. Here is an example which binds
address@hidden @key{TAB}}:
+
address@hidden
+(global-set-key "\C-x\t" 'indent-rigidly)
address@hidden example
+
+ These examples show how to write some other special @acronym{ASCII}
characters
+in strings for key bindings:
+
address@hidden
+(global-set-key "\r" 'newline) ;; @key{RET}
+(global-set-key "\d" 'delete-backward-char) ;; @key{DEL}
+(global-set-key "\C-x\e\e" 'repeat-complex-command) ;; @key{ESC}
address@hidden example
+
+ When the key sequence includes function keys or mouse button events,
+or address@hidden characters such as @code{C-=} or @code{H-a}, you must use
+the more general method of rebinding, which uses a vector to specify the
+key sequence.
+
+ The way to write a vector in Emacs Lisp is with square brackets around
+the vector elements. Use spaces to separate the elements. If an
+element is a symbol, simply write the symbol's name---no other
+delimiters or punctuation are needed. If a vector element is a
+character, write it as a Lisp character constant: @samp{?} followed by
+the character as it would appear in a string.
+
+ Here are examples of using vectors to rebind @kbd{C-=} (a control
+character not in @acronym{ASCII}), @kbd{C-M-=} (not in @acronym{ASCII} because
@kbd{C-=}
+is not), @kbd{H-a} (a Hyper character; @acronym{ASCII} doesn't have Hyper at
+all), @key{F7} (a function key), and @kbd{C-Mouse-1} (a
+keyboard-modified mouse button):
+
address@hidden
+(global-set-key [?\C-=] 'make-symbolic-link)
+(global-set-key [?\M-\C-=] 'make-symbolic-link)
+(global-set-key [?\H-a] 'make-symbolic-link)
+(global-set-key [f7] 'make-symbolic-link)
+(global-set-key [C-mouse-1] 'make-symbolic-link)
address@hidden example
+
+ You can use a vector for the simple cases too. Here's how to
+rewrite the first six examples above to use vectors:
+
address@hidden
+(global-set-key [?\C-z] 'shell)
+(global-set-key [?\C-x ?l] 'make-symbolic-link)
+(global-set-key [?\C-x ?\t] 'indent-rigidly)
+(global-set-key [?\r] 'newline)
+(global-set-key [?\d] 'delete-backward-char)
+(global-set-key [?\C-x ?\e ?\e] 'repeat-complex-command)
address@hidden example
+
address@hidden
+As you see, you represent a multi-character key sequence with a vector
+by listing all of the characters, in order, within the square brackets
+that delimit the vector.
+
+ Language and coding systems can cause problems with key bindings
+for address@hidden characters. @xref{Init Non-ASCII}.
+
address@hidden Function Keys
address@hidden Rebinding Function Keys
+
+ Key sequences can contain function keys as well as ordinary
+characters. Just as Lisp characters (actually integers) represent
+keyboard characters, Lisp symbols represent function keys. If the
+function key has a word as its label, then that word is also the name of
+the corresponding Lisp symbol. Here are the conventional Lisp names for
+common function keys:
+
address@hidden @asis
address@hidden @code{left}, @code{up}, @code{right}, @code{down}
+Cursor arrow keys.
+
address@hidden @code{begin}, @code{end}, @code{home}, @code{next}, @code{prior}
+Other cursor repositioning keys.
+
address@hidden @code{select}, @code{print}, @code{execute}, @code{backtab}
address@hidden @code{insert}, @code{undo}, @code{redo}, @code{clearline}
address@hidden @code{insertline}, @code{deleteline}, @code{insertchar},
@code{deletechar}
+Miscellaneous function keys.
+
address@hidden @code{f1}, @code{f2}, @dots{} @code{f35}
+Numbered function keys (across the top of the keyboard).
+
address@hidden @code{kp-add}, @code{kp-subtract}, @code{kp-multiply},
@code{kp-divide}
address@hidden @code{kp-backtab}, @code{kp-space}, @code{kp-tab},
@code{kp-enter}
address@hidden @code{kp-separator}, @code{kp-decimal}, @code{kp-equal}
+Keypad keys (to the right of the regular keyboard), with names or punctuation.
+
address@hidden @code{kp-0}, @code{kp-1}, @dots{} @code{kp-9}
+Keypad keys with digits.
+
address@hidden @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
+Keypad PF keys.
address@hidden table
+
+ These names are conventional, but some systems (especially when using
+X) may use different names. To make certain what symbol is used for a
+given function key on your terminal, type @kbd{C-h c} followed by that
+key.
+
+ A key sequence which contains function key symbols (or anything but
address@hidden characters) must be a vector rather than a string.
+Thus, to bind function key @samp{f1} to the command @code{rmail},
+write the following:
+
address@hidden
+(global-set-key [f1] 'rmail)
address@hidden example
+
address@hidden
+To bind the right-arrow key to the command @code{forward-char}, you can
+use this expression:
+
address@hidden
+(global-set-key [right] 'forward-char)
address@hidden example
+
address@hidden
+This uses the Lisp syntax for a vector containing the symbol
address@hidden (This binding is present in Emacs by default.)
+
+ @xref{Init Rebinding}, for more information about using vectors for
+rebinding.
+
+ You can mix function keys and characters in a key sequence. This
+example binds @kbd{C-x @key{NEXT}} to the command @code{forward-page}.
+
address@hidden
+(global-set-key [?\C-x next] 'forward-page)
address@hidden example
+
address@hidden
+where @code{?\C-x} is the Lisp character constant for the character
address@hidden The vector element @code{next} is a symbol and therefore
+does not take a question mark.
+
+ You can use the modifier keys @key{CTRL}, @key{META}, @key{HYPER},
address@hidden, @key{ALT} and @key{SHIFT} with function keys. To represent
+these modifiers, add the strings @samp{C-}, @samp{M-}, @samp{H-},
address@hidden, @samp{A-} and @samp{S-} at the front of the symbol name.
+Thus, here is how to make @address@hidden move forward a
+word:
+
address@hidden
+(global-set-key [H-M-right] 'forward-word)
address@hidden example
+
address@hidden keypad
+ Many keyboards have a ``numeric keypad'' on the right hand side.
+The numeric keys in the keypad double up as cursor motion keys,
+toggled by a key labeled @samp{Num Lock}. By default, Emacs
+translates these keys to the corresponding keys in the main keyboard.
+For example, when @samp{Num Lock} is on, the key labeled @samp{8} on
+the numeric keypad produces @code{kp-8}, which is translated to
address@hidden; when @samp{Num Lock} is off, the same key produces
address@hidden, which is translated to @key{UP}. If you rebind a key
+such as @kbd{8} or @key{UP}, it affects the equivalent keypad key too.
+However, if you rebind a @samp{kp-} key directly, that won't affect
+its non-keypad equivalent.
+
+ Emacs provides a convenient method for binding the numeric keypad
+keys, using the variables @code{keypad-setup},
address@hidden, @code{keypad-shifted-setup}, and
address@hidden These can be found in the
address@hidden customization group (@pxref{Easy Customization}). You
+can rebind the keys to perform other tasks, such as issuing numeric
+prefix arguments.
+
address@hidden Named ASCII Chars
address@hidden Named @acronym{ASCII} Control Characters
+
+ @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC} and @key{DEL}
+started out as names for certain @acronym{ASCII} control characters,
+used so often that they have special keys of their own. For instance,
address@hidden was another name for @kbd{C-i}. Later, users found it
+convenient to distinguish in Emacs between these keys and the ``same''
+control characters typed with the @key{CTRL} key. Therefore, on most
+modern terminals, they are no longer the same, and @key{TAB} is
+distinguishable from @kbd{C-i}.
+
+ Emacs can distinguish these two kinds of input if the keyboard does.
+It treats the ``special'' keys as function keys named @code{tab},
address@hidden, @code{backspace}, @code{linefeed}, @code{escape}, and
address@hidden These function keys translate automatically into the
+corresponding @acronym{ASCII} characters @emph{if} they have no
+bindings of their own. As a result, neither users nor Lisp programs
+need to pay attention to the distinction unless they care to.
+
+ If you do not want to distinguish between (for example) @key{TAB} and
address@hidden, make just one binding, for the @acronym{ASCII} character
@key{TAB}
+(octal code 011). If you do want to distinguish, make one binding for
+this @acronym{ASCII} character, and another for the ``function key''
@code{tab}.
+
+ With an ordinary @acronym{ASCII} terminal, there is no way to distinguish
+between @key{TAB} and @kbd{C-i} (and likewise for other such pairs),
+because the terminal sends the same character in both cases.
+
address@hidden Mouse Buttons
address@hidden Rebinding Mouse Buttons
address@hidden mouse button events
address@hidden rebinding mouse buttons
address@hidden click events
address@hidden drag events
address@hidden down events
address@hidden button down events
+
+ Emacs uses Lisp symbols to designate mouse buttons, too. The ordinary
+mouse events in Emacs are @dfn{click} events; these happen when you
+press a button and release it without moving the mouse. You can also
+get @dfn{drag} events, when you move the mouse while holding the button
+down. Drag events happen when you finally let go of the button.
+
+ The symbols for basic click events are @code{mouse-1} for the leftmost
+button, @code{mouse-2} for the next, and so on. Here is how you can
+redefine the second mouse button to split the current window:
+
address@hidden
+(global-set-key [mouse-2] 'split-window-vertically)
address@hidden example
+
+ The symbols for drag events are similar, but have the prefix
address@hidden before the word @samp{mouse}. For example, dragging the
+first button generates a @code{drag-mouse-1} event.
+
+ You can also define bindings for events that occur when a mouse button
+is pressed down. These events start with @samp{down-} instead of
address@hidden Such events are generated only if they have key bindings.
+When you get a button-down event, a corresponding click or drag event
+will always follow.
+
address@hidden double clicks
address@hidden triple clicks
+ If you wish, you can distinguish single, double, and triple clicks. A
+double click means clicking a mouse button twice in approximately the
+same place. The first click generates an ordinary click event. The
+second click, if it comes soon enough, generates a double-click event
+instead. The event type for a double-click event starts with
address@hidden: for example, @code{double-mouse-3}.
+
+ This means that you can give a special meaning to the second click at
+the same place, but it must act on the assumption that the ordinary
+single click definition has run when the first click was received.
+
+ This constrains what you can do with double clicks, but user interface
+designers say that this constraint ought to be followed in any case. A
+double click should do something similar to the single click, only
+``more so.'' The command for the double-click event should perform the
+extra work for the double click.
+
+ If a double-click event has no binding, it changes to the
+corresponding single-click event. Thus, if you don't define a
+particular double click specially, it executes the single-click command
+twice.
+
+ Emacs also supports triple-click events whose names start with
address@hidden Emacs does not distinguish quadruple clicks as event
+types; clicks beyond the third generate additional triple-click events.
+However, the full number of clicks is recorded in the event list, so
+if you know Emacs Lisp you can distinguish if you really want to
+(@pxref{Accessing Events,,, elisp, The Emacs Lisp Reference Manual}).
+We don't recommend distinct meanings for more than three clicks, but
+sometimes it is useful for subsequent clicks to cycle through the same
+set of three meanings, so that four clicks are equivalent to one
+click, five are equivalent to two, and six are equivalent to three.
+
+ Emacs also records multiple presses in drag and button-down events.
+For example, when you press a button twice, then move the mouse while
+holding the button, Emacs gets a @samp{double-drag-} event. And at the
+moment when you press it down for the second time, Emacs gets a
address@hidden event (which is ignored, like all button-down
+events, if it has no binding).
+
address@hidden double-click-time
+ The variable @code{double-click-time} specifies how much time can
+elapse between clicks and still allow them to be grouped as a multiple
+click. Its value is in units of milliseconds. If the value is
address@hidden, double clicks are not detected at all. If the value is
address@hidden, then there is no time limit. The default is 500.
+
address@hidden double-click-fuzz
+ The variable @code{double-click-fuzz} specifies how much the mouse
+can move between clicks and still allow them to be grouped as a multiple
+click. Its value is in units of pixels on windowed displays and in
+units of 1/8 of a character cell on text-mode terminals; the default is
+3.
+
+ The symbols for mouse events also indicate the status of the modifier
+keys, with the usual prefixes @samp{C-}, @samp{M-}, @samp{H-},
address@hidden, @samp{A-} and @samp{S-}. These always precede @samp{double-}
+or @samp{triple-}, which always precede @samp{drag-} or @samp{down-}.
+
+ A frame includes areas that don't show text from the buffer, such as
+the mode line and the scroll bar. You can tell whether a mouse button
+comes from a special area of the screen by means of dummy ``prefix
+keys.'' For example, if you click the mouse in the mode line, you get
+the prefix key @code{mode-line} before the ordinary mouse-button symbol.
+Thus, here is how to define the command for clicking the first button in
+a mode line to run @code{scroll-up}:
+
address@hidden
+(global-set-key [mode-line mouse-1] 'scroll-up)
address@hidden example
+
+ Here is the complete list of these dummy prefix keys and their
+meanings:
+
address@hidden @code
address@hidden mode-line
+The mouse was in the mode line of a window.
address@hidden vertical-line
+The mouse was in the vertical line separating side-by-side windows. (If
+you use scroll bars, they appear in place of these vertical lines.)
address@hidden vertical-scroll-bar
+The mouse was in a vertical scroll bar. (This is the only kind of
+scroll bar Emacs currently supports.)
address@hidden menu-bar
+The mouse was in the menu bar.
address@hidden header-line
+The mouse was in a header line.
address@hidden
address@hidden horizontal-scroll-bar
+The mouse was in a horizontal scroll bar. Horizontal scroll bars do
+horizontal scrolling, and people don't use them often.
address@hidden ignore
address@hidden table
+
+ You can put more than one mouse button in a key sequence, but it isn't
+usual to do so.
+
address@hidden Disabling
address@hidden Disabling Commands
address@hidden disabled command
+
+ Disabling a command means that invoking it interactively asks for
+confirmation from the user. The purpose of disabling a command is to
+prevent users from executing it by accident; we do this for commands
+that might be confusing to the uninitiated.
+
+ Attempting to invoke a disabled command interactively in Emacs
+displays a window containing the command's name, its documentation,
+and some instructions on what to do immediately; then Emacs asks for
+input saying whether to execute the command as requested, enable it
+and execute it, or cancel. If you decide to enable the command, you
+must then answer another question---whether to do this permanently, or
+just for the current session. (Enabling permanently works by
+automatically editing your @file{.emacs} file.) You can also type
address@hidden to enable @emph{all} commands, for the current session only.
+
+ The direct mechanism for disabling a command is to put a
address@hidden @code{disabled} property on the Lisp symbol for the
+command. Here is the Lisp program to do this:
+
address@hidden
+(put 'delete-region 'disabled t)
address@hidden example
+
+ If the value of the @code{disabled} property is a string, that string
+is included in the message displayed when the command is used:
+
address@hidden
+(put 'delete-region 'disabled
+ "It's better to use `kill-region' instead.\n")
address@hidden example
+
address@hidden disable-command
address@hidden enable-command
+ You can make a command disabled either by editing the @file{.emacs}
+file directly, or with the command @kbd{M-x disable-command}, which edits
+the @file{.emacs} file for you. Likewise, @kbd{M-x enable-command}
+edits @file{.emacs} to enable a command permanently. @xref{Init File}.
+
+ If Emacs was invoked with the @option{-q} or @option{--no-init-file}
+options (@pxref{Initial Options}), it will not edit your
address@hidden/.emacs} init file. Doing so could lose information
+because Emacs has not read your init file.
+
+ Whether a command is disabled is independent of what key is used to
+invoke it; disabling also applies if the command is invoked using
address@hidden However, disabling a command has no effect on calling it
+as a function from Lisp programs.
+
address@hidden Syntax
address@hidden The Syntax Table
address@hidden syntax table
+
+ All the Emacs commands which parse words or balance parentheses are
+controlled by the @dfn{syntax table}. The syntax table says which
+characters are opening delimiters, which are parts of words, which are
+string quotes, and so on. It does this by assigning each character to
+one of fifteen-odd @dfn{syntax classes}. In some cases it specifies
+some additional information also.
+
+ Each major mode has its own syntax table (though related major modes
+sometimes share one syntax table), which it installs in each buffer
+that uses the mode. The syntax table installed in the current buffer
+is the one that all commands use, so we call it ``the'' syntax table.
+
address@hidden C-h s
address@hidden describe-syntax
+ To display a description of the contents of the current syntax
+table, type @kbd{C-h s} (@code{describe-syntax}). The description of
+each character includes the string you would have to give to
address@hidden to set up that character's current syntax,
+starting with the character which designates its syntax class, plus
+some English text to explain its meaning.
+
+ A syntax table is actually a Lisp object, a char-table, whose
+elements are cons cells. For full information on the syntax table,
+see @ref{Syntax Tables,, Syntax Tables, elisp, The Emacs Lisp
+Reference Manual}.
+
address@hidden Init File
address@hidden The Init File, @file{~/.emacs}
address@hidden init file
address@hidden Emacs initialization file
address@hidden key rebinding, permanent
address@hidden rebinding keys, permanently
address@hidden startup (init file)
+
+ When Emacs is started, it normally loads a Lisp program from the file
address@hidden or @file{.emacs.el} in your home directory (@pxref{Find Init}).
+We call this file your @dfn{init file} because it specifies how to
+initialize Emacs for you. You can use the command line switch
address@hidden to prevent loading your init file, and @samp{-u} (or
address@hidden) to specify a different user's init file (@pxref{Initial
+Options}).
+
+ You can also use @file{~/.emacs.d/init.el} as the init file. Emacs
+tries this if it cannot find @file{~/.emacs} or @file{~/.emacs.el}.
+
address@hidden @file{default.el}, the default init file
+ There can also be a @dfn{default init file}, which is the library
+named @file{default.el}, found via the standard search path for
+libraries. The Emacs distribution contains no such library; your site
+may create one for local customizations. If this library exists, it is
+loaded whenever you start Emacs (except when you specify @samp{-q}).
+But your init file, if any, is loaded first; if it sets
address@hidden address@hidden, then @file{default} is not
+loaded.
+
address@hidden site init file
address@hidden @file{site-start.el}, the site startup file
+ Your site may also have a @dfn{site startup file}; this is named
address@hidden, if it exists. Like @file{default.el}, Emacs
+finds this file via the standard search path for Lisp libraries.
+Emacs loads this library before it loads your init file. To inhibit
+loading of this library, use the option @samp{--no-site-file}.
address@hidden Options}. We recommend against using
address@hidden for changes that some users may not like. It is
+better to put them in @file{default.el}, so that users can more easily
+override them.
+
+ You can place @file{default.el} and @file{site-start.el} in any of
+the directories which Emacs searches for Lisp libraries. The variable
address@hidden (@pxref{Lisp Libraries}) specifies these directories.
+Many sites put these files in the @file{site-lisp} subdirectory of the
+Emacs installation directory, typically
address@hidden/usr/local/share/emacs/site-lisp}.
+
+ If you have a large amount of code in your @file{.emacs} file, you
+should rename it to @file{~/.emacs.el}, and byte-compile it. @xref{Byte
+Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference Manual},
+for more information about compiling Emacs Lisp programs.
+
+ If you are going to write actual Emacs Lisp programs that go beyond
+minor customization, you should read the @cite{Emacs Lisp Reference Manual}.
address@hidden
address@hidden, Emacs Lisp, Emacs Lisp, elisp, the Emacs Lisp Reference
+Manual}.
address@hidden ifnottex
+
address@hidden
+* Init Syntax:: Syntax of constants in Emacs Lisp.
+* Init Examples:: How to do some things with an init file.
+* Terminal Init:: Each terminal type can have an init file.
+* Find Init:: How Emacs finds the init file.
+* Init Non-ASCII:: Using address@hidden characters in an init file.
address@hidden menu
+
address@hidden Init Syntax
address@hidden Init File Syntax
+
+ The @file{.emacs} file contains one or more Lisp function call
+expressions. Each of these consists of a function name followed by
+arguments, all surrounded by parentheses. For example, @code{(setq
+fill-column 60)} calls the function @code{setq} to set the variable
address@hidden (@pxref{Filling}) to 60.
+
+ You can set any Lisp variable with @code{setq}, but with certain
+variables @code{setq} won't do what you probably want in the
address@hidden file. Some variables automatically become buffer-local
+when set with @code{setq}; what you want in @file{.emacs} is to set
+the default value, using @code{setq-default}. Some customizable minor
+mode variables do special things to enable the mode when you set them
+with Customize, but ordinary @code{setq} won't do that; to enable the
+mode in your @file{.emacs} file, call the minor mode command. The
+following section has examples of both of these methods.
+
+ The second argument to @code{setq} is an expression for the new
+value of the variable. This can be a constant, a variable, or a
+function call expression. In @file{.emacs}, constants are used most
+of the time. They can be:
+
address@hidden @asis
address@hidden Numbers:
+Numbers are written in decimal, with an optional initial minus sign.
+
address@hidden Strings:
address@hidden Lisp string syntax
address@hidden string syntax
+Lisp string syntax is the same as C string syntax with a few extra
+features. Use a double-quote character to begin and end a string constant.
+
+In a string, you can include newlines and special characters literally.
+But often it is cleaner to use backslash sequences for them: @samp{\n}
+for newline, @samp{\b} for backspace, @samp{\r} for carriage return,
address@hidden for tab, @samp{\f} for formfeed (control-L), @samp{\e} for
+escape, @samp{\\} for a backslash, @samp{\"} for a double-quote, or
address@hidden@var{ooo}} for the character whose octal code is @var{ooo}.
+Backslash and double-quote are the only characters for which backslash
+sequences are mandatory.
+
address@hidden can be used as a prefix for a control character, as in
address@hidden for @acronym{ASCII} control-S, and @samp{\M-} can be used as a
prefix for
+a Meta character, as in @samp{\M-a} for @kbd{Meta-A} or @samp{\M-\C-a} for
address@hidden@refill
+
address@hidden Non-ASCII}, for information about including
address@hidden in your init file.
+
address@hidden Characters:
+Lisp character constant syntax consists of a @samp{?} followed by
+either a character or an escape sequence starting with @samp{\}.
+Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that
+strings and characters are not interchangeable in Lisp; some contexts
+require one and some contexts require the other.
+
address@hidden Non-ASCII}, for information about binding commands to
+keys which send address@hidden characters.
+
address@hidden True:
address@hidden stands for `true'.
+
address@hidden False:
address@hidden stands for `false'.
+
address@hidden Other Lisp objects:
+Write a single-quote (@code{'}) followed by the Lisp object you want.
address@hidden table
+
address@hidden Init Examples
address@hidden Init File Examples
+
+ Here are some examples of doing certain commonly desired things with
+Lisp expressions:
+
address@hidden @bullet
address@hidden
+Make @key{TAB} in C mode just insert a tab if point is in the middle of a
+line.
+
address@hidden
+(setq c-tab-always-indent nil)
address@hidden example
+
+Here we have a variable whose value is normally @code{t} for `true'
+and the alternative is @code{nil} for `false'.
+
address@hidden
+Make searches case sensitive by default (in all buffers that do not
+override this).
+
address@hidden
+(setq-default case-fold-search nil)
address@hidden example
+
+This sets the default value, which is effective in all buffers that do
+not have local values for the variable. Setting @code{case-fold-search}
+with @code{setq} affects only the current buffer's local value, which
+is not what you probably want to do in an init file.
+
address@hidden
address@hidden user-mail-address
+Specify your own email address, if Emacs can't figure it out correctly.
+
address@hidden
+(setq user-mail-address "rumsfeld@@torture.gov")
address@hidden example
+
+Various Emacs packages that need your own email address use the value of
address@hidden
+
address@hidden
+Make Text mode the default mode for new buffers.
+
address@hidden
+(setq default-major-mode 'text-mode)
address@hidden example
+
+Note that @code{text-mode} is used because it is the command for
+entering Text mode. The single-quote before it makes the symbol a
+constant; otherwise, @code{text-mode} would be treated as a variable
+name.
+
address@hidden 1500
address@hidden
+Set up defaults for the Latin-1 character set
+which supports most of the languages of Western Europe.
+
address@hidden
+(set-language-environment "Latin-1")
address@hidden example
+
address@hidden 1500
address@hidden
+Turn off Line Number mode, a global minor mode.
+
address@hidden
+(line-number-mode 0)
address@hidden example
+
address@hidden 1500
address@hidden
+Turn on Auto Fill mode automatically in Text mode and related modes.
+
address@hidden
+(add-hook 'text-mode-hook
+ '(lambda () (auto-fill-mode 1)))
address@hidden example
+
+This shows how to add a hook function to a normal hook variable
+(@pxref{Hooks}). The function we supply is a list starting with
address@hidden, with a single-quote in front of it to make it a list
+constant rather than an expression.
+
+It's beyond the scope of this manual to explain Lisp functions, but for
+this example it is enough to know that the effect is to execute
address@hidden(auto-fill-mode 1)} when Text mode is entered. You can replace
+that with any other expression that you like, or with several
+expressions in a row.
+
+Emacs comes with a function named @code{turn-on-auto-fill} whose
+definition is @code{(lambda () (auto-fill-mode 1))}. Thus, a simpler
+way to write the above example is as follows:
+
address@hidden
+(add-hook 'text-mode-hook 'turn-on-auto-fill)
address@hidden example
+
address@hidden
+Load the installed Lisp library named @file{foo} (actually a file
address@hidden or @file{foo.el} in a standard Emacs directory).
+
address@hidden
+(load "foo")
address@hidden example
+
+When the argument to @code{load} is a relative file name, not starting
+with @samp{/} or @samp{~}, @code{load} searches the directories in
address@hidden (@pxref{Lisp Libraries}).
+
address@hidden
+Load the compiled Lisp file @file{foo.elc} from your home directory.
+
address@hidden
+(load "~/foo.elc")
address@hidden example
+
+Here an absolute file name is used, so no searching is done.
+
address@hidden
address@hidden loading Lisp libraries automatically
address@hidden autoload Lisp libraries
+Tell Emacs to find the definition for the function @code{myfunction}
+by loading a Lisp library named @file{mypackage} (i.e.@: a file
address@hidden or @file{mypackage.el}):
+
address@hidden
+(autoload 'myfunction "mypackage" "Do what I say." t)
address@hidden example
+
address@hidden
+Here the string @code{"Do what I say."} is the function's
+documentation string. You specify it in the @code{autoload}
+definition so it will be available for help commands even when the
+package is not loaded. The last argument, @code{t}, indicates that
+this function is interactive; that is, it can be invoked interactively
+by typing @kbd{M-x myfunction @key{RET}} or by binding it to a key.
+If the function is not interactive, omit the @code{t} or use
address@hidden
+
address@hidden
+Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}
+(@pxref{Init Rebinding}).
+
address@hidden
+(global-set-key "\C-xl" 'make-symbolic-link)
address@hidden example
+
+or
+
address@hidden
+(define-key global-map "\C-xl" 'make-symbolic-link)
address@hidden example
+
+Note once again the single-quote used to refer to the symbol
address@hidden instead of its value as a variable.
+
address@hidden
+Do the same thing for Lisp mode only.
+
address@hidden
+(define-key lisp-mode-map "\C-xl" 'make-symbolic-link)
address@hidden example
+
address@hidden
+Redefine all keys which now run @code{next-line} in Fundamental mode
+so that they run @code{forward-line} instead.
+
address@hidden substitute-key-definition
address@hidden
+(substitute-key-definition 'next-line 'forward-line
+ global-map)
address@hidden example
+
address@hidden
+Make @kbd{C-x C-v} undefined.
+
address@hidden
+(global-unset-key "\C-x\C-v")
address@hidden example
+
+One reason to undefine a key is so that you can make it a prefix.
+Simply defining @kbd{C-x C-v @var{anything}} will make @kbd{C-x C-v} a
+prefix, but @kbd{C-x C-v} must first be freed of its usual non-prefix
+definition.
+
address@hidden
+Make @samp{$} have the syntax of punctuation in Text mode.
+Note the use of a character constant for @samp{$}.
+
address@hidden
+(modify-syntax-entry ?\$ "." text-mode-syntax-table)
address@hidden example
+
address@hidden
+Enable the use of the command @code{narrow-to-region} without confirmation.
+
address@hidden
+(put 'narrow-to-region 'disabled nil)
address@hidden example
+
address@hidden
+Adjusting the configuration to various platforms and Emacs versions.
+
+Users typically want Emacs to behave the same on all systems, so the
+same init file is right for all platforms. However, sometimes it
+happens that a function you use for customizing Emacs is not available
+on some platforms or in older Emacs versions. To deal with that
+situation, put the customization inside a conditional that tests whether
+the function or facility is available, like this:
+
address@hidden
+(if (fboundp 'blink-cursor-mode)
+ (blink-cursor-mode 0))
+
+(if (boundp 'coding-category-utf-8)
+ (set-coding-priority '(coding-category-utf-8)))
address@hidden example
+
address@hidden
+You can also simply disregard the errors that occur if the
+function is not defined.
+
address@hidden
+(condition case ()
+ (set-face-background 'region "grey75")
+ (error nil))
address@hidden example
+
+A @code{setq} on a variable which does not exist is generally
+harmless, so those do not need a conditional.
address@hidden itemize
+
address@hidden Terminal Init
address@hidden Terminal-specific Initialization
+
+ Each terminal type can have a Lisp library to be loaded into Emacs when
+it is run on that type of terminal. For a terminal type named
address@hidden, the library is called @file{term/@var{termtype}} and it is
+found by searching the directories @code{load-path} as usual and trying the
+suffixes @samp{.elc} and @samp{.el}. Normally it appears in the
+subdirectory @file{term} of the directory where most Emacs libraries are
address@hidden
+
+ The usual purpose of the terminal-specific library is to map the
+escape sequences used by the terminal's function keys onto more
+meaningful names, using @code{function-key-map}. See the file
address@hidden/lk201.el} for an example of how this is done. Many function
+keys are mapped automatically according to the information in the
+Termcap data base; the terminal-specific library needs to map only the
+function keys that Termcap does not specify.
+
+ When the terminal type contains a hyphen, only the part of the name
+before the first hyphen is significant in choosing the library name.
+Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
+the library @file{term/aaa}. The code in the library can use
address@hidden(getenv "TERM")} to find the full terminal type address@hidden
+
address@hidden term-file-prefix
+ The library's name is constructed by concatenating the value of the
+variable @code{term-file-prefix} and the terminal type. Your @file{.emacs}
+file can prevent the loading of the terminal-specific library by setting
address@hidden to @code{nil}.
+
address@hidden term-setup-hook
+ Emacs runs the hook @code{term-setup-hook} at the end of
+initialization, after both your @file{.emacs} file and any
+terminal-specific library have been read in. Add hook functions to this
+hook if you wish to override part of any of the terminal-specific
+libraries and to define initializations for terminals that do not have a
+library. @xref{Hooks}.
+
address@hidden Find Init
address@hidden How Emacs Finds Your Init File
+
+ Normally Emacs uses the environment variable @env{HOME}
+(@pxref{General Variables, HOME}) to find @file{.emacs}; that's what
address@hidden means in a file name. If @file{.emacs} is not found inside
address@hidden/} (nor @file{.emacs.el}), Emacs looks for
address@hidden/.emacs.d/init.el} (which, like @file{~/.emacs.el}, can be
+byte-compiled).
+
+ However, if you run Emacs from a shell started by @code{su}, Emacs
+tries to find your own @file{.emacs}, not that of the user you are
+currently pretending to be. The idea is that you should get your own
+editor customizations even if you are running as the super user.
+
+ More precisely, Emacs first determines which user's init file to use.
+It gets your user name from the environment variables @env{LOGNAME} and
address@hidden; if neither of those exists, it uses effective user-ID.
+If that user name matches the real user-ID, then Emacs uses @env{HOME};
+otherwise, it looks up the home directory corresponding to that user
+name in the system's data base of users.
address@hidden LocalWords: backtab
+
address@hidden Init Non-ASCII
address@hidden address@hidden Characters in Init Files
address@hidden international characters in @file{.emacs}
address@hidden address@hidden characters in @file{.emacs}
address@hidden address@hidden keys, binding
address@hidden rebinding address@hidden keys
+
+ Language and coding systems may cause problems if your init file
+contains address@hidden characters, such as accented letters, in
+strings or key bindings.
+
+ If you want to use address@hidden characters in your init file,
+you should put a @address@hidden: @var{coding-system}-*-}} tag on
+the first line of the init file, and specify a coding system that
+supports the character(s) in question. @xref{Recognize Coding}. This
+is because the defaults for decoding address@hidden text might
+not yet be set up by the time Emacs reads those parts of your init
+file which use such strings, possibly leading Emacs to decode those
+strings incorrectly. You should then avoid adding Emacs Lisp code
+that modifies the coding system in other ways, such as calls to
address@hidden
+
+ To bind address@hidden keys, you must use a vector (@pxref{Init
+Rebinding}). The string syntax cannot be used, since the
address@hidden characters will be interpreted as meta keys. For
+instance:
+
address@hidden
+(global-set-key address@hidden 'some-function)
address@hidden example
+
address@hidden
+Type @kbd{C-q}, followed by the key you want to bind, to insert @var{char}.
+
+ @strong{Warning:} if you change the keyboard encoding, or change
+between multibyte and unibyte mode, or anything that would alter which
+code @kbd{C-q} would insert for that character, this keybinding may
+stop working. It is therefore advisable to use one and only one
+coding system, for your init file as well as the files you edit. For
+example, don't mix the @samp{latin-1} and @samp{latin-9} coding
+systems.
+
address@hidden
+ arch-tag: c68abddb-4410-4fb5-925f-63394e971d93
address@hidden ignore
- [Emacs-diffs] Changes to custom.texi,
Glenn Morris <=