0001: @c -*- coding: utf-8 -*-
0002: @c This is part of the Emacs manual.
0003: @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software
0004: @c Foundation, Inc.
0005: @c See file emacs.texi for copying conditions.
0006: @node Customization
0007: @chapter Customization
0008: @cindex customization
0009: 
0010:   This chapter describes some simple methods to customize the behavior
0011: of Emacs.
0012: 
0013:   Apart from the methods described here, see @ref{X Resources} for
0014: information about using X resources to customize Emacs, and see
0015: @ref{Keyboard Macros} for information about recording and replaying
0016: keyboard macros.  Making more far-reaching and open-ended changes
0017: involves writing Emacs Lisp code; see
0018: @iftex
0019: @cite{The Emacs Lisp Reference Manual}.
0020: @end iftex
0021: @ifnottex
0022: @ref{Top, Emacs Lisp, Emacs Lisp, elisp, The Emacs Lisp
0023: Reference Manual}.
0024: @end ifnottex
0025: 
0026: @menu
0027: * Easy Customization::  Convenient way to browse and change settings.
0028: * Variables::           Many Emacs commands examine Emacs variables
0029:                           to decide what to do; by setting variables,
0030:                           you can control their functioning.
0031: * Key Bindings::        The keymaps say what command each key runs.
0032:                           By changing them, you can redefine keys.
0033: * Init File::           How to write common customizations in the
0034:                           initialization file.
0035: @end menu
0036: 
0037: @node Easy Customization
0038: @section Easy Customization Interface
0039: 
0040: @cindex settings
0041: @cindex user option
0042: @cindex customizable variable
0043:   Emacs has many @dfn{settings} which you can change.  Most settings
0044: are @dfn{customizable variables} (@pxref{Variables}), which are also
0045: called @dfn{user options}.  There is a huge number of customizable
0046: variables, controlling numerous aspects of Emacs behavior; the
0047: variables documented in this manual are listed in @ref{Variable
0048: Index}.  A separate class of settings are the @dfn{faces}, which
0049: determine the fonts, colors, and other attributes of text
0050: (@pxref{Faces}).
0051: 
0052: @findex customize
0053: @cindex customization buffer
0054:   To browse and alter settings (both variables and faces), type
0055: @kbd{M-x customize}.  This creates a @dfn{customization buffer}, which
0056: lets you navigate through a logically organized list of settings, edit
0057: and set their values, and save them permanently.
0058: 
0059: @menu
0060: * Customization Groups::     How settings are classified.
0061: * Browsing Custom::          Browsing and searching for settings.
0062: * Changing a Variable::      How to edit an option's value and set the option.
0063: * Saving Customizations::    Saving customizations for future Emacs sessions.
0064: * Face Customization::       How to edit the attributes of a face.
0065: * Specific Customization::   Customizing specific settings or groups.
0066: * Custom Themes::            Collections of customization settings.
0067: * Creating Custom Themes::   How to create a new custom theme.
0068: @end menu
0069: 
0070: @node Customization Groups
0071: @subsection Customization Groups
0072: @cindex customization groups
0073: 
0074:   Customization settings are organized into @dfn{customization
0075: groups}.  These groups are collected into bigger groups, all the way
0076: up to a master group called @code{Emacs}.
0077: 
0078:   @kbd{M-x customize} creates a customization buffer that shows the
0079: top-level @code{Emacs} group.  It looks like this, in part:
0080: 
0081: @c we want the buffer example to all be on one page, but unfortunately
0082: @c that's quite a bit of text, so force all space to the bottom.
0083: @c @page
0084: @smallexample
0085: @group
0086: For help using this buffer, see [Easy Customization] in the [Emacs manual].
0087: 
0088: ________________________________________ [ Search ]
0089: 
0090:  Operate on all settings in this buffer:
0091:  [ Revert... ] [ Apply ] [ Apply and Save ]
0092: 
0093: 
0094: Emacs group: Customization of the One True Editor.
0095:       [State]: visible group members are all at standard values.
0096:       See also [Manual].
0097: 
0098: [Editing]      Basic text editing facilities.
0099: [Convenience]  Convenience features for faster editing.
0100: 
0101: @var{...more second-level groups...}
0102: @end group
0103: @end smallexample
0104: 
0105: @noindent
0106: The main part of this buffer shows the @samp{Emacs} customization
0107: group, which contains several other groups (@samp{Editing},
0108: @samp{Convenience}, etc.).  The contents of those groups are not
0109: listed here, only one line of documentation each.
0110: 
0111:   The @dfn{state} of the group indicates whether setting in that group
0112: has been edited, set, or saved.  @xref{Changing a Variable}.
0113: 
0114: @cindex editable fields (customization buffer)
0115: @cindex buttons (customization buffer)
0116: @cindex links (customization buffer)
0117:   Most of the customization buffer is read-only, but it includes some
0118: @dfn{editable fields} that you can edit.  For example, at the top of
0119: the customization buffer is an editable field for searching for
0120: settings (@pxref{Browsing Custom}).  There are also @dfn{buttons} and
0121: @dfn{links}, which you can activate by either clicking with the mouse,
0122: or moving point there and typing @kbd{@key{RET}}.  For example, the group
0123: names like @samp{[Editing]} are links; activating one of these links
0124: brings up the customization buffer for that group.
0125: 
0126: @kindex TAB @r{(customization buffer)}
0127: @kindex S-TAB @r{(customization buffer)}
0128: @findex widget-forward
0129: @findex widget-backward
0130:   In the customization buffer, you can type @kbd{@key{TAB}}
0131: (@code{widget-forward}) to move forward to the next button or editable
0132: field.  @kbd{S-@key{TAB}} (@code{widget-backward}) moves back to the
0133: previous button or editable field.
0134: 
0135: @node Browsing Custom
0136: @subsection Browsing and Searching for Settings
0137: @findex customize-browse
0138: 
0139:   From the top-level customization buffer created by @kbd{M-x
0140: customize}, you can follow the links to the subgroups of the
0141: @samp{Emacs} customization group.  These subgroups may contain
0142: settings for you to customize; they may also contain further subgroups,
0143: dealing with yet more specialized subsystems of Emacs.  As you
0144: navigate the hierarchy of customization groups, you should find some
0145: settings that you want to customize.
0146: 
0147:   If you are interested in customizing a particular setting or
0148: customization group, you can go straight there with the commands
0149: @kbd{M-x customize-option}, @kbd{M-x customize-face}, or @w{@kbd{M-x
0150: customize-group}}.  @xref{Specific Customization}.
0151: 
0152: @vindex custom-search-field
0153:   If you don't know exactly what groups or settings you want to
0154: customize, you can search for them using the editable search field at
0155: the top of each customization buffer.  Here, you can type in a search
0156: term---either one or more words separated by spaces, or a regular
0157: expression (@pxref{Regexps}).  Then type @kbd{@key{RET}} in the field,
0158: or activate the @samp{Search} button next to it, to switch to a
0159: customization buffer containing groups and settings that match those
0160: terms.  Note, however, that this feature only finds groups and
0161: settings that are loaded in the current Emacs session.
0162: 
0163:   If you don't want customization buffers to show the search field,
0164: change the variable @code{custom-search-field} to @code{nil}.
0165: 
0166:   The command @kbd{M-x customize-apropos} is similar to using the
0167: search field, except that it reads the search term(s) using the
0168: minibuffer.  @xref{Specific Customization}.
0169: 
0170:   @kbd{M-x customize-browse} is another way to browse the available
0171: settings.  This command creates a special customization buffer, which
0172: shows only the names of groups and settings, in a structured layout.
0173: You can show the contents of a group, in the same buffer, by invoking
0174: the @samp{[+]} button next to the group name.  When the group contents
0175: are shown, the button changes to @samp{[-]}; invoking that hides the
0176: group contents again.  Each group or setting in this buffer has a link
0177: which says @samp{[Group]}, @samp{[Option]} or @samp{[Face]}.  Invoking
0178: this link creates an ordinary customization buffer showing just that
0179: group, option, or face; this is the way to change settings that you
0180: find with @kbd{M-x customize-browse}.
0181: 
0182: @node Changing a Variable
0183: @subsection Changing a Variable
0184: 
0185:   Here is an example of what a variable, or user option, looks like in
0186: the customization buffer:
0187: 
0188: @smallexample
0189: [Hide] Kill Ring Max: 60
0190:    [State]: STANDARD.
0191:    Maximum length of kill ring before oldest elements are thrown away.
0192: @end smallexample
0193: 
0194:   The first line shows that the variable is named
0195: @code{kill-ring-max}, formatted as @samp{Kill Ring Max} for easier
0196: viewing.  Its value is @samp{60}.  The button labeled @samp{[Hide]},
0197: if activated, hides the variable's value and state; this is useful to
0198: avoid cluttering up the customization buffer with very long values
0199: (for this reason, variables that have very long values may start out
0200: hidden).  If you use the @samp{[Hide]} button, it changes to
0201: @samp{[Show Value]}, which you can activate to reveal the value and
0202: state.  On a graphical display, the @samp{[Hide]} and @samp{[Show
0203: Value]} buttons are replaced with graphical triangles pointing
0204: downwards and rightwards respectively.
0205: 
0206:   The line after the variable name indicates the @dfn{customization
0207: state} of the variable: in this example, @samp{STANDARD} means you
0208: have not changed the variable, so its value is the default one.  The
0209: @samp{[State]} button gives a menu of operations for customizing the
0210: variable.
0211: 
0212:   Below the customization state is the documentation for the variable.
0213: This is the same documentation that would be shown by the @kbd{C-h v}
0214: command (@pxref{Examining}).  If the documentation is more than one
0215: line long, only one line may be shown.  If so, that line ends with a
0216: @samp{[More]} button; activate this to see the full documentation.
0217: 
0218: @cindex user options, changing
0219: @cindex customizing variables
0220: @cindex variables, changing
0221:   To enter a new value for @samp{Kill Ring Max}, just move point to
0222: the value and edit it.  For example, type @kbd{M-d} to delete the
0223: @samp{60} and type in another number.  As you begin to alter the text,
0224: the @samp{[State]} line will change:
0225: 
0226: @smallexample
0227: [State]: EDITED, shown value does not take effect until you
0228:          set or save it.
0229: @end smallexample
0230: 
0231: @noindent
0232: Editing the value does not make it take effect right away.  To do
0233: that, you must @dfn{set} the variable by activating the @samp{[State]}
0234: button and choosing @samp{Set for Current Session}.  Then the
0235: variable's state becomes:
0236: 
0237: @smallexample
0238: [State]: SET for current session only.
0239: @end smallexample
0240: 
0241: @noindent
0242: You don't have to worry about specifying a value that is not valid;
0243: the @samp{Set for Current Session} operation checks for validity and
0244: will not install an unacceptable value.
0245: 
0246: @kindex M-TAB @r{(customization buffer)}
0247: @kindex C-M-i @r{(customization buffer)}
0248: @findex widget-complete
0249:   While editing certain kinds of values, such as file names, directory
0250: names, and Emacs command names, you can perform completion with
0251: @kbd{C-M-i} (@code{widget-complete}), or the equivalent keys
0252: @kbd{M-@key{TAB}} or @kbd{@key{ESC} @key{TAB}}.  This behaves much
0253: like minibuffer completion (@pxref{Completion}).
0254: 
0255:   Typing @kbd{@key{RET}} on an editable value field moves point
0256: forward to the next field or button, like @kbd{@key{TAB}}.  You can
0257: thus type @kbd{@key{RET}} when you are finished editing a field, to
0258: move on to the next button or field.  To insert a newline within an
0259: editable field, use @kbd{C-o} or @kbd{C-q C-j}.
0260: 
0261:   For some variables, there is only a fixed set of legitimate values,
0262: and you are not allowed to edit the value directly.  Instead, a
0263: @samp{[Value Menu]} button appears before the value; activating this
0264: button presents a choice of values.  For a boolean ``on or off''
0265: value, the button says @samp{[Toggle]}, and flips the value.  After
0266: using the @samp{[Value Menu]} or @samp{[Toggle]} button, you must
0267: again set the variable to make the chosen value take effect.
0268: 
0269:   Some variables have values with complex structure.  For example, the
0270: value of @code{minibuffer-frame-alist} is an association list.  Here
0271: is how it appears in the customization buffer:
0272: 
0273: @smallexample
0274: [Hide] Minibuffer Frame Alist:
0275: [INS] [DEL] Parameter: width
0276:             Value: 80
0277: [INS] [DEL] Parameter: height
0278:             Value: 2
0279: [INS]
0280:    [ State ]: STANDARD.
0281:    Alist of parameters for the initial minibuffer frame. [Hide]
0282:    @r{[@dots{}more lines of documentation@dots{}]}
0283: @end smallexample
0284: 
0285: @noindent
0286: In this case, each association in the list consists of two items, one
0287: labeled @samp{Parameter} and one labeled @samp{Value}; both are
0288: editable fields.  You can delete an association from the list with the
0289: @samp{[DEL]} button next to it.  To add an association, use the
0290: @samp{[INS]} button at the position where you want to insert it; the
0291: very last @samp{[INS]} button inserts at the end of the list.
0292: 
0293: @cindex saving a setting
0294: @cindex settings, how to save
0295:   When you set a variable, the new value takes effect only in the
0296: current Emacs session.  To @dfn{save} the value for future sessions,
0297: use the @samp{[State]} button and select the @samp{Save for Future
0298: Sessions} operation.  @xref{Saving Customizations}.
0299: 
0300:   You can also restore the variable to its standard value by using the
0301: @samp{[State]} button and selecting the @samp{Erase Customization}
0302: operation.  There are actually four reset operations:
0303: 
0304: @table @samp
0305: @item Undo Edits
0306: If you have modified but not yet set the variable, this restores the
0307: text in the customization buffer to match the actual value.
0308: 
0309: @item Revert This Session's Customizations
0310: This restores the value of the variable to the last saved value, if
0311: there was one.  Otherwise it restores the standard value.  It updates
0312: the text accordingly.
0313: 
0314: @item Erase Customization
0315: This sets the variable to its standard value.  Any saved value that
0316: you have is also eliminated.
0317: 
0318: @item Set to Backup Value
0319: This sets the variable to a previous value that was set in the
0320: customization buffer in this session.  If you customize a variable
0321: and then reset it, which discards the customized value,
0322: you can get the discarded value back again with this operation.
0323: @end table
0324: 
0325: @cindex comments on customized settings
0326:   Sometimes it is useful to record a comment about a specific
0327: customization.  Use the @samp{Add Comment} item from the
0328: @samp{[State]} menu to create a field for entering the comment.
0329: 
0330:   Near the top of the customization buffer are two lines of buttons:
0331: 
0332: @smallexample
0333:  Operate on all settings in this buffer:
0334:  [Revert...] [Apply] [Apply and Save]
0335: @end smallexample
0336: 
0337: @noindent
0338: The @samp{[Revert...]} button drops a menu with the first 3 reset
0339: operations described above.  The @samp{[Apply]} button applies the
0340: settings for the current session.  The @samp{[Apply and Save]} button
0341: applies the settings and saves them for future sessions; this button
0342: does not appear if Emacs was started with the @option{-q} or
0343: @option{-Q} option (@pxref{Initial Options}).
0344: 
0345: @kindex C-c C-c @r{(customization buffer)}
0346: @kindex C-x C-c @r{(customization buffer)}
0347: @findex Custom-set
0348: @findex Custom-save
0349:   The command @kbd{C-c C-c} (@code{Custom-set}) is equivalent to using
0350: the @samp{[Set for Current Session]} button.  The command @kbd{C-x
0351: C-s} (@code{Custom-save}) is like using the @samp{[Save for Future
0352: Sessions]} button.
0353: 
0354: @vindex custom-buffer-done-kill
0355:   The @samp{[Exit]} button switches out of the customization buffer,
0356: and buries the buffer at the bottom of the buffer list.  To make it
0357: kill the customization buffer instead, change the variable
0358: @code{custom-buffer-done-kill} to @code{t}.
0359: 
0360: @node Saving Customizations
0361: @subsection Saving Customizations
0362: 
0363:   In the customization buffer, you can @dfn{save} a customization
0364: setting by choosing the @samp{Save for Future Sessions} choice from
0365: its @samp{[State]} button.  The @kbd{C-x C-s} (@code{Custom-save})
0366: command, or the @samp{[Apply and Save]} button at the top of the
0367: customization buffer, saves all applicable settings in the buffer.
0368: 
0369:   Saving works by writing code to a file, usually your initialization
0370: file (@pxref{Init File}).  Future Emacs sessions automatically read
0371: this file at startup, which sets up the customizations again.
0372: 
0373: @vindex custom-file
0374:   You can choose to save customizations somewhere other than your
0375: initialization file.  To make this work, you must add a couple of
0376: lines of code to your initialization file, to set the variable
0377: @code{custom-file} to the name of the desired file, and to load that
0378: file.  For example:
0379: 
0380: @example
0381: (setq custom-file "~/.emacs-custom.el")
0382: (load custom-file)
0383: @end example
0384: 
0385:   You can even specify different customization files for different
0386: Emacs versions, like this:
0387: 
0388: @example
0389: (cond ((< emacs-major-version 22)
0390:        ;; @r{Emacs 21 customization.}
0391:        (setq custom-file "~/.custom-21.el"))
0392:       ((and (= emacs-major-version 22)
0393:             (< emacs-minor-version 3))
0394:        ;; @r{Emacs 22 customization, before version 22.3.}
0395:        (setq custom-file "~/.custom-22.el"))
0396:       (t
0397:        ;; @r{Emacs version 22.3 or later.}
0398:        (setq custom-file "~/.emacs-custom.el")))
0399: 
0400: (load custom-file)
0401: @end example
0402: 
0403:   If Emacs was invoked with the @option{-q} or @option{--no-init-file}
0404: options (@pxref{Initial Options}), it will not let you save your
0405: customizations in your initialization file.  This is because saving
0406: customizations from such a session would wipe out all the other
0407: customizations you might have on your initialization file.
0408: 
0409: @cindex unsaved customizations, reminder to save
0410: @findex custom-prompt-customize-unsaved-options
0411:   Please note that any customizations you have not chosen to save for
0412: future sessions will be lost when you terminate Emacs.  If you'd like
0413: to be prompted about unsaved customizations at termination time, add
0414: the following to your initialization file:
0415: 
0416: @example
0417: (add-hook 'kill-emacs-query-functions
0418:           'custom-prompt-customize-unsaved-options)
0419: @end example
0420: 
0421: @node Face Customization
0422: @subsection Customizing Faces
0423: @cindex customizing faces
0424: @cindex faces, customizing
0425: @cindex fonts and faces
0426: 
0427:   You can customize faces (@pxref{Faces}), which determine how Emacs
0428: displays different types of text.  Customization groups can contain
0429: both variables and faces.
0430: 
0431:   For example, in programming language modes, source code comments are
0432: shown with @code{font-lock-comment-face} (@pxref{Font Lock}).  In a
0433: customization buffer, that face appears like this, after you click on
0434: the @samp{[Show All Attributes]} link:
0435: 
0436: @smallexample
0437: [Hide] Font Lock Comment Face:[sample]
0438:    [State] : STANDARD.
0439:    Font Lock mode face used to highlight comments.
0440:    [ ] Font Family: --
0441:    [ ] Font Foundry: --
0442:    [ ] Width: --
0443:    [ ] Height: --
0444:    [ ] Weight: --
0445:    [ ] Slant: --
0446:    [ ] Underline: --
0447:    [ ] Overline: --
0448:    [ ] Strike-through: --
0449:    [ ] Box around text: --
0450:    [ ] Inverse-video: --
0451:    [X] Foreground: Firebrick     [Choose]  (sample)
0452:    [ ] Background: --
0453:    [ ] Stipple: --
0454:    [ ] Inherit: --
0455:    [Hide Unused Attributes]
0456: @end smallexample
0457: 
0458: @noindent
0459: The first three lines show the name, @samp{[State]} button, and
0460: documentation for the face.  Below that is a list of @dfn{face
0461: attributes}.  In front of each attribute is a checkbox.  A filled
0462: checkbox, @samp{[X]}, means that the face specifies a value for this
0463: attribute; an empty checkbox, @samp{[ ]}, means that the face does not
0464: specify any special value for the attribute.  You can activate a
0465: checkbox to specify or unspecify its attribute.
0466: 
0467:   A face does not have to specify every single attribute; in fact,
0468: most faces only specify a few attributes.  In the above example,
0469: @code{font-lock-comment-face} only specifies the foreground color.
0470: Any unspecified attribute is taken from the special face named
0471: @code{default}, whose attributes are all specified.  The
0472: @code{default} face is the face used to display any text that does not
0473: have an explicitly-assigned face; furthermore, its background color
0474: attribute serves as the background color of the frame.
0475: 
0476:   The @samp{[Hide Unused Attributes]} button, at the end of the
0477: attribute list, hides the unspecified attributes of the face.  When
0478: attributes are being hidden, the button changes to @samp{[Show All
0479: Attributes]}, which reveals the entire attribute list.  The
0480: customization buffer may start out with unspecified attributes hidden,
0481: to avoid cluttering the interface.
0482: 
0483:   When an attribute is specified, you can change its value in the
0484: usual ways.
0485: 
0486:   Foreground and background colors can be specified using either color
0487: names or RGB triplets (@pxref{Colors}).  You can also use the
0488: @samp{[Choose]} button to switch to a list of color names; select a
0489: color with @kbd{@key{RET}} in that buffer to put the color name in the
0490: value field.
0491: 
0492:   Setting, saving and resetting a face work like the same operations for
0493: variables (@pxref{Changing a Variable}).
0494: 
0495:   A face can specify different appearances for different types of
0496: displays.  For example, a face can make text red on a color display,
0497: but use a bold font on a monochrome display.  To specify multiple
0498: appearances for a face, select @samp{For All Kinds of Displays} in the
0499: menu you get from invoking @samp{[State]}.
0500: 
0501: @node Specific Customization
0502: @subsection Customizing Specific Items
0503: 
0504: @table @kbd
0505: @item M-x customize-option @key{RET} @var{option} @key{RET}
0506: @itemx M-x customize-variable @key{RET} @var{option} @key{RET}
0507: Set up a customization buffer for just one user option, @var{option}.
0508: 
0509: @item M-x customize-face @key{RET} @var{face} @key{RET}
0510: Set up a customization buffer for just one face, @var{face}.
0511: 
0512: @item M-x customize-group @key{RET} @var{group} @key{RET}
0513: Set up a customization buffer for just one group, @var{group}.
0514: 
0515: @item M-x customize-apropos @key{RET} @var{regexp} @key{RET}
0516: Set up a customization buffer for all the settings and groups that
0517: match @var{regexp}.
0518: 
0519: @item M-x customize-changed @key{RET} @var{version} @key{RET}
0520: Set up a customization buffer with all the settings and groups
0521: whose meaning has changed since Emacs version @var{version}.
0522: 
0523: @item M-x customize-changed-options @key{RET} @var{version} @key{RET}
0524: Set up a customization buffer with all the options whose meaning or
0525: default values have changed since Emacs version @var{version}.
0526: 
0527: @item M-x customize-saved
0528: Set up a customization buffer containing all settings that you
0529: have saved with customization buffers.
0530: 
0531: @item M-x customize-unsaved
0532: Set up a customization buffer containing all settings that you have
0533: set but not saved.
0534: @end table
0535: 
0536: @findex customize-option
0537:   If you want to customize a particular user option, type @kbd{M-x
0538: customize-option}.  This reads the variable name, and sets up the
0539: customization buffer with just that one user option.  When entering
0540: the variable name into the minibuffer, completion is available, but
0541: only for the names of variables that have been loaded into Emacs.
0542: 
0543: @findex customize-face
0544: @findex customize-group
0545:   Likewise, you can customize a specific face using @kbd{M-x
0546: customize-face}.  You can set up a customization buffer for a specific
0547: customization group using @kbd{M-x customize-group}.
0548: 
0549: @findex customize-apropos
0550:   @kbd{M-x customize-apropos} prompts for a search term---either one
0551: or more words separated by spaces, or a regular expression---and sets
0552: up a customization buffer for all @emph{loaded} settings and groups
0553: with matching names.  This is like using the search field at the top
0554: of the customization buffer (@pxref{Customization Groups}).
0555: 
0556: @findex customize-changed
0557:   When you upgrade to a new Emacs version, you might want to consider
0558: customizing new settings, and settings whose meanings or default
0559: values have changed.  To do this, use @kbd{M-x customize-changed} and
0560: specify a previous Emacs version number using the minibuffer.  It
0561: creates a customization buffer which shows all the settings and groups
0562: whose definitions have been changed since the specified version,
0563: loading them if necessary.
0564: 
0565: @findex customize-saved
0566: @findex customize-unsaved
0567:   If you change settings and then decide the change was a mistake, you
0568: can use two commands to revisit your changes.  Use @kbd{M-x
0569: customize-saved} to customize settings that you have saved.  Use
0570: @kbd{M-x customize-unsaved} to customize settings that you have set
0571: but not saved.
0572: 
0573: @node Custom Themes
0574: @subsection Custom Themes
0575: @cindex custom themes
0576: 
0577:   @dfn{Custom themes} are collections of settings that can be enabled
0578: or disabled as a unit.  You can use Custom themes to switch easily
0579: between various collections of settings, and to transfer such
0580: collections from one computer to another.
0581: 
0582:   A Custom theme is stored as an Emacs Lisp source file.  If the name of
0583: the Custom theme is @var{name}, the theme file is named
0584: @file{@var{name}-theme.el}.  @xref{Creating Custom Themes}, for the
0585: format of a theme file and how to make one.
0586: 
0587: @findex customize-themes
0588: @vindex custom-theme-directory
0589: @cindex color scheme
0590:   Type @kbd{M-x customize-themes} to switch to a buffer named
0591: @file{*Custom Themes*}, which lists the Custom themes that Emacs knows
0592: about.  By default, Emacs looks for theme files in two locations: the
0593: directory specified by the variable @code{custom-theme-directory}
0594: (which defaults to @file{~/.emacs.d/}), and a directory named
0595: @file{etc/themes} in your Emacs installation (see the variable
0596: @code{data-directory}).  The latter contains several Custom themes
0597: distributed with Emacs that customize Emacs's faces to fit
0598: various color schemes.  (Note, however, that Custom themes need not be
0599: restricted to this purpose; they can be used to customize variables
0600: too.)
0601: 
0602: @vindex custom-theme-load-path
0603:   If you want Emacs to look for Custom themes in some other directory,
0604: add the directory to the list variable
0605: @code{custom-theme-load-path}.  Its default value is
0606: @code{(custom-theme-directory t)}; here, the symbol
0607: @code{custom-theme-directory} has the special meaning of the value of
0608: the variable @code{custom-theme-directory}, while @code{t} stands for
0609: the built-in theme directory @file{etc/themes}.  The themes listed in
0610: the @file{*Custom Themes*} buffer are those found in the directories
0611: specified by @code{custom-theme-load-path}.
0612: 
0613: @kindex C-x C-s @r{(Custom Themes buffer)}
0614:   In the @file{*Custom Themes*} buffer, you can activate the checkbox
0615: next to a Custom theme to enable or disable the theme for the current
0616: Emacs session.  When a Custom theme is enabled, all of its settings
0617: (variables and faces) take effect in the Emacs session.  To apply the
0618: choice of theme(s) to future Emacs sessions, type @kbd{C-x C-s}
0619: (@code{custom-theme-save}) or use the @samp{[Save Theme Settings]}
0620: button.
0621: 
0622: @vindex custom-safe-themes
0623:   When you first enable a Custom theme, Emacs displays the contents of
0624: the theme file and asks if you really want to load it.  Because
0625: loading a Custom theme can execute arbitrary Lisp code, you should
0626: only say yes if you know that the theme is safe; in that case, Emacs
0627: offers to remember in the future that the theme is safe (this is done
0628: by saving the theme file's SHA-256 hash to the variable
0629: @code{custom-safe-themes}; if you want to treat all themes as safe,
0630: change its value to @code{t}).  Themes that come with Emacs (in the
0631: @file{etc/themes} directory) are exempt from this check, and are
0632: always considered safe.
0633: 
0634: @vindex custom-enabled-themes
0635:   Setting or saving Custom themes actually works by customizing the
0636: variable @code{custom-enabled-themes}.  The value of this variable is
0637: a list of Custom theme names (as Lisp symbols, e.g., @code{tango}).
0638: Instead of using the @file{*Custom Themes*} buffer to set
0639: @code{custom-enabled-themes}, you can customize the variable using the
0640: usual customization interface, e.g., with @kbd{M-x customize-option}.
0641: Note that Custom themes are not allowed to set
0642: @code{custom-enabled-themes} themselves.
0643: 
0644:   Any customizations that you make through the customization buffer
0645: take precedence over theme settings.  This lets you easily override
0646: individual theme settings that you disagree with.  If settings from
0647: two different themes overlap, the theme occurring earlier in
0648: @code{custom-enabled-themes} takes precedence.  In the customization
0649: buffer, if a setting has been changed from its default by a Custom
0650: theme, its @samp{State} display shows @samp{THEMED} instead of
0651: @samp{STANDARD}.
0652: 
0653: @findex load-theme
0654: @findex enable-theme
0655: @findex disable-theme
0656:   You can enable a specific Custom theme in the current Emacs session
0657: by typing @kbd{M-x load-theme}.  This prompts for a theme name, loads
0658: the theme from the theme file, and enables it.  If a theme file
0659: has been loaded before, you can enable the theme without loading its
0660: file by typing @kbd{M-x enable-theme}.  To disable a Custom theme,
0661: type @kbd{M-x disable-theme}.
0662: 
0663: @findex describe-theme
0664:   To see a description of a Custom theme, type @kbd{?} on its line in
0665: the @file{*Custom Themes*} buffer; or type @kbd{M-x describe-theme}
0666: anywhere in Emacs and enter the theme name.
0667: 
0668: @node Creating Custom Themes
0669: @subsection Creating Custom Themes
0670: @cindex custom themes, creating
0671: 
0672: @findex customize-create-theme
0673:   You can define a Custom theme using an interface similar to the
0674: customization buffer, by typing @kbd{M-x customize-create-theme}.
0675: This switches to a buffer named @file{*Custom Theme*}.  It also offers
0676: to insert some common Emacs faces into the theme (a convenience, since
0677: Custom themes are often used to customize faces).  If you answer no,
0678: the theme will initially contain no settings.
0679: 
0680:   Near the top of the @file{*Custom Theme*} buffer, there are editable fields
0681: where you can enter the theme's name and description.  The name can be
0682: anything except @samp{user}.  The description is the one that will be
0683: shown when you invoke @kbd{M-x describe-theme} for the theme.  Its
0684: first line should be a brief one-sentence summary; in the buffer made
0685: by @kbd{M-x customize-themes}, this sentence is displayed next to the
0686: theme name.
0687: 
0688:   To add a new setting to the theme, use the @samp{[Insert Additional
0689: Face]} or @samp{[Insert Additional Variable]} buttons.  Each button
0690: reads a face or variable name using the minibuffer, with completion,
0691: and inserts a customization entry for the face or variable.  You can
0692: edit the variable values or face attributes in the same way as in a
0693: normal customization buffer.  To remove a face or variable from the
0694: theme, uncheck the checkbox next to its name.
0695: 
0696: @vindex custom-theme-directory@r{, saving theme files}
0697:   After specifying the Custom theme's faces and variables, type
0698: @kbd{C-x C-s} (@code{custom-theme-write}) or use the buffer's
0699: @samp{[Save Theme]} button.  This saves the theme file, named
0700: @file{@var{name}-theme.el} where @var{name} is the theme name, in the
0701: directory named by @code{custom-theme-directory}.
0702: 
0703:   From the @file{*Custom Theme*} buffer, you can view and edit an
0704: existing Custom theme by activating the @samp{[Visit Theme]} button
0705: and specifying the theme name.  You can also add the settings of
0706: another theme into the buffer, using the @samp{[Merge Theme]} button.
0707: You can import your non-theme settings into a Custom theme by using
0708: the @samp{[Merge Theme]} button and specifying the special theme named
0709: @samp{user}.
0710: 
0711:   A theme file is simply an Emacs Lisp source file, and loading the
0712: Custom theme works by loading the Lisp file.  Therefore, you can edit
0713: a theme file directly instead of using the @file{*Custom Theme*}
0714: buffer.  @xref{Custom Themes,,, elisp, The Emacs Lisp Reference
0715: Manual}, for details.
0716: 
0717: @node Variables
0718: @section Variables
0719: @cindex variable
0720: 
0721:   A @dfn{variable} is a Lisp symbol which has a value.  The symbol's
0722: name is also called the @dfn{variable name}.  A variable name can
0723: contain any characters that can appear in a file, but most variable
0724: names consist of ordinary words separated by hyphens.
0725: 
0726:   The name of the variable serves as a compact description of its
0727: role.  Most variables also have a @dfn{documentation string}, which
0728: describes what the variable's purpose is, what kind of value it should
0729: have, and how the value will be used.  You can view this documentation
0730: using the help command @kbd{C-h v} (@code{describe-variable}).
0731: @xref{Examining}.
0732: 
0733:   Emacs uses many Lisp variables for internal record keeping, but the
0734: most interesting variables for a non-programmer user are those meant
0735: for users to change---these are called @dfn{customizable variables} or
0736: @dfn{user options} (@pxref{Easy Customization}).  In the following
0737: sections, we will describe other aspects of Emacs variables, such as
0738: how to set them outside Customize.
0739: 
0740:   Emacs Lisp allows any variable (with a few exceptions) to have any
0741: kind of value.  However, many variables are meaningful only if
0742: assigned values of a certain type.  For example, only numbers are
0743: meaningful values for @code{kill-ring-max}, which specifies the
0744: maximum length of the kill ring (@pxref{Earlier Kills}); if you give
0745: @code{kill-ring-max} a string value, commands such as @kbd{C-y}
0746: (@code{yank}) will signal an error.  On the other hand, some variables
0747: don't care about type; for instance, if a variable has one effect for
0748: @code{nil} values and another effect for non-@code{nil} values,
0749: then any value that is not the symbol @code{nil} induces the second
0750: effect, regardless of its type (by convention, we usually use the
0751: value @code{t}---a symbol which stands for ``true''---to specify a
0752: non-@code{nil} value).  If you set a variable using the customization
0753: buffer, you need not worry about giving it an invalid type: the
0754: customization buffer usually only allows you to enter meaningful
0755: values.  When in doubt, use @kbd{C-h v} (@code{describe-variable}) to
0756: check the variable's documentation string to see kind of value it
0757: expects (@pxref{Examining}).
0758: 
0759: @menu
0760: * Examining::           Examining or setting one variable's value.
0761: * Hooks::               Hook variables let you specify programs for parts
0762:                           of Emacs to run on particular occasions.
0763: * Locals::              Per-buffer values of variables.
0764: * File Variables::      How files can specify variable values.
0765: * Directory Variables:: How variable values can be specified by directory.
0766: @end menu
0767: 
0768: @node Examining
0769: @subsection Examining and Setting Variables
0770: @cindex setting variables
0771: 
0772: @table @kbd
0773: @item C-h v @var{var} @key{RET}
0774: Display the value and documentation of variable @var{var}
0775: (@code{describe-variable}).
0776: 
0777: @item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET}
0778: Change the value of variable @var{var} to @var{value}.
0779: @end table
0780: 
0781:   To examine the value of a variable, use @kbd{C-h v}
0782: (@code{describe-variable}).  This reads a variable name using the
0783: minibuffer, with completion, and displays both the value and the
0784: documentation of the variable.  For example,
0785: 
0786: @example
0787: C-h v fill-column @key{RET}
0788: @end example
0789: 
0790: @noindent
0791: displays something like this:
0792: 
0793: @example
0794: fill-column is a variable defined in ‘C source code’.
0795: Its value is 70
0796: 
0797:   Automatically becomes buffer-local when set.
0798:   This variable is safe as a file local variable if its value
0799:   satisfies the predicate ‘integerp’.
0800: 
0801: Documentation:
0802: Column beyond which automatic line-wrapping should happen.
0803: Interactively, you can set the buffer local value using C-x f.
0804: 
0805: You can customize this variable.
0806: @end example
0807: 
0808: @noindent
0809: The line that says @samp{You can customize the variable} indicates that
0810: this variable is a user option.  @kbd{C-h v} is not restricted to user
0811: options; it allows non-customizable variables too.
0812: 
0813: @findex set-variable
0814:   The most convenient way to set a specific customizable variable is
0815: with @kbd{M-x set-variable}.  This reads the variable name with the
0816: minibuffer (with completion), and then reads a Lisp expression for the
0817: new value using the minibuffer a second time (you can insert the old
0818: value into the minibuffer for editing via @kbd{M-n}).  For example,
0819: 
0820: @example
0821: M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET}
0822: @end example
0823: 
0824: @noindent
0825: sets @code{fill-column} to 75.
0826: 
0827:  @kbd{M-x set-variable} is limited to customizable variables, but you
0828: can set any variable with a Lisp expression like this:
0829: 
0830: @example
0831: (setq fill-column 75)
0832: @end example
0833: 
0834: @noindent
0835: To execute such an expression, type @kbd{M-:} (@code{eval-expression})
0836: and enter the expression in the minibuffer (@pxref{Lisp Eval}).
0837: Alternatively, go to the @file{*scratch*} buffer, type in the
0838: expression, and then type @kbd{C-j} (@pxref{Lisp Interaction}).
0839: 
0840:   Setting variables, like all means of customizing Emacs except where
0841: otherwise stated, affects only the current Emacs session.  The only
0842: way to alter the variable in future sessions is to put something in
0843: your initialization file (@pxref{Init File}).
0844: 
0845: @node Hooks
0846: @subsection Hooks
0847: @cindex hook
0848: @cindex running a hook
0849: 
0850:   @dfn{Hooks} are an important mechanism for customizing Emacs.  A
0851: hook is a Lisp variable which holds a list of functions, to be called
0852: on some well-defined occasion.  (This is called @dfn{running the
0853: hook}.)  The individual functions in the list are called the @dfn{hook
0854: functions} of the hook.  For example, the hook @code{kill-emacs-hook}
0855: runs just before exiting Emacs (@pxref{Exiting}).
0856: 
0857: @cindex normal hook
0858:   Most hooks are @dfn{normal hooks}.  This means that when Emacs runs
0859: the hook, it calls each hook function in turn, with no arguments.  We
0860: have made an effort to keep most hooks normal, so that you can use
0861: them in a uniform way.  Every variable whose name ends in @samp{-hook}
0862: is a normal hook.
0863: 
0864: @cindex abnormal hook
0865:   A few hooks are @dfn{abnormal hooks}.  Their names end in
0866: @samp{-functions}, instead of @samp{-hook} (some old code may also use
0867: the deprecated suffix @samp{-hooks}).  What
0868: makes these hooks abnormal is the way its functions are
0869: called---perhaps they are given arguments, or perhaps the values they
0870: return are used in some way.  For example,
0871: @code{find-file-not-found-functions} is abnormal because as soon as
0872: one hook function returns a non-@code{nil} value, the rest are not
0873: called at all (@pxref{Visiting}).  The documentation of each abnormal
0874: hook variable explains how its functions are used.
0875: 
0876: @findex add-hook
0877:   You can set a hook variable with @code{setq} like any other Lisp
0878: variable, but the recommended way to add a function to a hook (either
0879: normal or abnormal) is to use @code{add-hook}, as shown by the
0880: following examples.  @xref{Hooks,,, elisp, The Emacs Lisp Reference
0881: Manual}, for details.
0882: 
0883:   Most major modes run one or more @dfn{mode hooks} as the last step
0884: of initialization.  Mode hooks are a convenient way to customize the
0885: behavior of individual modes; they are always normal.  For example,
0886: here's how to set up a hook to turn on Auto Fill mode in Text mode and
0887: other modes based on Text mode:
0888: 
0889: @example
0890: (add-hook 'text-mode-hook 'auto-fill-mode)
0891: @end example
0892: 
0893: @noindent
0894: This works by calling @code{auto-fill-mode}, which enables the minor
0895: mode when no argument is supplied (@pxref{Minor Modes}).  Next,
0896: suppose you don't want Auto Fill mode turned on in @LaTeX{} mode,
0897: which is one of the modes based on Text mode.  You can do this with
0898: the following additional line:
0899: 
0900: @example
0901: (add-hook 'latex-mode-hook (lambda () (auto-fill-mode -1)))
0902: @end example
0903: 
0904: @noindent
0905: Here we have used the special macro @code{lambda} to construct an
0906: anonymous function (@pxref{Lambda Expressions,,, elisp, The Emacs Lisp
0907: Reference Manual}), which calls @code{auto-fill-mode} with an argument
0908: of @code{-1} to disable the minor mode.  Because @LaTeX{} mode runs
0909: @code{latex-mode-hook} after running @code{text-mode-hook}, the result
0910: leaves Auto Fill mode disabled.
0911: 
0912:   Here is a more complex example, showing how to use a hook to
0913: customize the indentation of C code:
0914: 
0915: @example
0916: @group
0917: (setq my-c-style
0918:   '((c-comment-only-line-offset . 4)
0919: @end group
0920: @group
0921:     (c-cleanup-list . (scope-operator
0922:                        empty-defun-braces
0923:                        defun-close-semi))))
0924: @end group
0925: 
0926: @group
0927: (add-hook 'c-mode-common-hook
0928:   (lambda () (c-add-style "my-style" my-c-style t)))
0929: @end group
0930: @end example
0931: 
0932: @cindex Prog mode
0933: @cindex modes for editing programs
0934:   Major mode hooks also apply to other major modes @dfn{derived} from
0935: the original mode (@pxref{Derived Modes,,, elisp, The Emacs Lisp
0936: Reference Manual}).  For instance, HTML mode is derived from Text mode
0937: (@pxref{HTML Mode}); when HTML mode is enabled, it runs
0938: @code{text-mode-hook} before running @code{html-mode-hook}.  This
0939: provides a convenient way to use a single hook to affect several
0940: related modes.  In particular, if you want to apply a hook function to
0941: any programming language mode, add it to @code{prog-mode-hook}; Prog
0942: mode is a major mode that does little else than to let other major
0943: modes inherit from it, exactly for this purpose.
0944: 
0945:   It is best to design your hook functions so that the order in which
0946: they are executed does not matter.  Any dependence on the order is
0947: asking for trouble.  However, the order is predictable: the hook
0948: functions are executed in the order they appear in the hook.
0949: 
0950: @findex remove-hook
0951:   If you play with adding various different versions of a hook
0952: function by calling @code{add-hook} over and over, remember that all
0953: the versions you added will remain in the hook variable together.  You
0954: can clear out individual functions by calling @code{remove-hook}, or
0955: do @code{(setq @var{hook-variable} nil)} to remove everything.
0956: 
0957: @cindex buffer-local hooks
0958:   If the hook variable is buffer-local, the buffer-local variable will
0959: be used instead of the global variable.  However, if the buffer-local
0960: variable contains the element @code{t}, the global hook variable will
0961: be run as well.
0962: 
0963: @node Locals
0964: @subsection Local Variables
0965: 
0966: @table @kbd
0967: @item M-x make-local-variable @key{RET} @var{var} @key{RET}
0968: Make variable @var{var} have a local value in the current buffer.
0969: 
0970: @item M-x kill-local-variable @key{RET} @var{var} @key{RET}
0971: Make variable @var{var} use its global value in the current buffer.
0972: 
0973: @item M-x make-variable-buffer-local @key{RET} @var{var} @key{RET}
0974: Mark variable @var{var} so that setting it will make it local to the
0975: buffer that is current at that time.
0976: @end table
0977: 
0978: @cindex local variables
0979:   Almost any variable can be made @dfn{local} to a specific Emacs
0980: buffer.  This means that its value in that buffer is independent of its
0981: value in other buffers.  A few variables are always local in every
0982: buffer.  Every other Emacs variable has a @dfn{global} value which is in
0983: effect in all buffers that have not made the variable local.
0984: 
0985: @findex make-local-variable
0986:   @kbd{M-x make-local-variable} reads the name of a variable and makes
0987: it local to the current buffer.  Changing its value subsequently in
0988: this buffer will not affect others, and changes in its global value
0989: will not affect this buffer.
0990: 
0991: @findex make-variable-buffer-local
0992: @cindex per-buffer variables
0993:   @kbd{M-x make-variable-buffer-local} marks a variable so it will
0994: become local automatically whenever it is set.  More precisely, once a
0995: variable has been marked in this way, the usual ways of setting the
0996: variable automatically do @code{make-local-variable} first.  We call
0997: such variables @dfn{per-buffer} variables.  Many variables in Emacs
0998: are normally per-buffer; the variable's document string tells you when
0999: this is so.  A per-buffer variable's global value is normally never
1000: effective in any buffer, but it still has a meaning: it is the initial
1001: value of the variable for each new buffer.
1002: 
1003:   Major modes (@pxref{Major Modes}) always make variables local to the
1004: buffer before setting the variables.  This is why changing major modes
1005: in one buffer has no effect on other buffers.  Minor modes also work
1006: by setting variables---normally, each minor mode has one controlling
1007: variable which is non-@code{nil} when the mode is enabled
1008: (@pxref{Minor Modes}).  For many minor modes, the controlling variable
1009: is per buffer, and thus always buffer-local.  Otherwise, you can make
1010: it local in a specific buffer like any other variable.
1011: 
1012:   A few variables cannot be local to a buffer because they are always
1013: local to each display instead (@pxref{Multiple Displays}).  If you try to
1014: make one of these variables buffer-local, you'll get an error message.
1015: 
1016: @findex kill-local-variable
1017:   @kbd{M-x kill-local-variable} makes a specified variable cease to be
1018: local to the current buffer.  The global value of the variable
1019: henceforth is in effect in this buffer.  Setting the major mode kills
1020: all the local variables of the buffer except for a few variables
1021: specially marked as @dfn{permanent locals}.
1022: 
1023: @findex setq-default
1024:   To set the global value of a variable, regardless of whether the
1025: variable has a local value in the current buffer, you can use the Lisp
1026: construct @code{setq-default}.  This construct is used just like
1027: @code{setq}, but it sets variables' global values instead of their local
1028: values (if any).  When the current buffer does have a local value, the
1029: new global value may not be visible until you switch to another buffer.
1030: Here is an example:
1031: 
1032: @example
1033: (setq-default fill-column 75)
1034: @end example
1035: 
1036: @noindent
1037: @code{setq-default} is the only way to set the global value of a variable
1038: that has been marked with @code{make-variable-buffer-local}.
1039: 
1040: @findex default-value
1041:   Lisp programs can use @code{default-value} to look at a variable's
1042: default value.  This function takes a symbol as argument and returns its
1043: default value.  The argument is evaluated; usually you must quote it
1044: explicitly.  For example, here's how to obtain the default value of
1045: @code{fill-column}:
1046: 
1047: @example
1048: (default-value 'fill-column)
1049: @end example
1050: 
1051: @node File Variables
1052: @subsection Local Variables in Files
1053: @cindex local variables in files
1054: @cindex file local variables
1055: 
1056:   A file can specify local variable values to use when editing the
1057: file with Emacs.  Visiting the file or setting a major mode checks for
1058: local variable specifications; it automatically makes these variables
1059: local to the buffer, and sets them to the values specified in the
1060: file.
1061: 
1062:   File local variables override directory local variables
1063: (@pxref{Directory Variables}), if any are specified for a file's
1064: directory.
1065: 
1066: @menu
1067: * Specifying File Variables:: Specifying file local variables.
1068: * Safe File Variables::       Making sure file local variables are safe.
1069: @end menu
1070: 
1071: @node Specifying File Variables
1072: @subsubsection Specifying File Variables
1073: 
1074:   There are two ways to specify file local variable values: in the first
1075: line, or with a local variables list.  Here's how to specify them in the
1076: first line:
1077: 
1078: @example
1079: -*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*-
1080: @end example
1081: 
1082: @noindent
1083: You can specify any number of variable/value pairs in this way, each
1084: pair with a colon and semicolon.  The special variable/value pair
1085: @code{mode: @var{modename};}, if present, specifies a major mode.  The
1086: @var{value}s are used literally, and not evaluated.
1087: 
1088: @findex add-file-local-variable-prop-line
1089: @findex delete-file-local-variable-prop-line
1090: @findex copy-dir-locals-to-file-locals-prop-line
1091:   You can use @kbd{M-x add-file-local-variable-prop-line} instead of
1092: adding entries by hand.  This command prompts for a variable and
1093: value, and adds them to the first line in the appropriate way.
1094: @kbd{M-x delete-file-local-variable-prop-line} prompts for a variable,
1095: and deletes its entry from the line.  The command @kbd{M-x
1096: copy-dir-locals-to-file-locals-prop-line} copies the current
1097: directory-local variables to the first line (@pxref{Directory
1098: Variables}).
1099: 
1100:   Here is an example first line that specifies Lisp mode and sets two
1101: variables with numeric values:
1102: 
1103: @smallexample
1104: ;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*-
1105: @end smallexample
1106: 
1107: @noindent
1108: Aside from @code{mode}, other keywords that have special meanings as
1109: file variables are @code{coding}, @code{unibyte}, and @code{eval}.
1110: These are described below.
1111: 
1112: @cindex shell scripts, and local file variables
1113: @cindex man pages, and local file variables
1114:   In shell scripts, the first line is used to identify the script
1115: interpreter, so you cannot put any local variables there.  To
1116: accommodate this, Emacs looks for local variable specifications in the
1117: @emph{second} line if the first line specifies an interpreter.  The
1118: same is true for man pages which start with the magic string
1119: @samp{'\"} to specify a list of troff preprocessors (not all do,
1120: however).
1121: 
1122:   Apart from using a @samp{-*-} line, you can define file local
1123: variables using a @dfn{local variables list} near the end of the file.
1124: The start of the local variables list should be no more than 3000
1125: characters from the end of the file, and must be on the last page if
1126: the file is divided into pages.
1127: 
1128:   If a file has both a local variables list and a @samp{-*-} line,
1129: Emacs processes @emph{everything} in the @samp{-*-} line first, and
1130: @emph{everything} in the local variables list afterward.  The exception
1131: to this is a major mode specification.  Emacs applies this first,
1132: wherever it appears, since most major modes kill all local variables as
1133: part of their initialization.
1134: 
1135:   A local variables list starts with a line containing the string
1136: @samp{Local Variables:}, and ends with a line containing the string
1137: @samp{End:}.  In between come the variable names and values, one set
1138: per line, like this:
1139: 
1140: @example
1141: /* Local Variables:  */
1142: /* mode: c           */
1143: /* comment-column: 0 */
1144: /* End:              */
1145: @end example
1146: 
1147: @noindent
1148: In this example, each line starts with the prefix @samp{/*} and ends
1149: with the suffix @samp{*/}.  Emacs recognizes the prefix and suffix by
1150: finding them surrounding the magic string @samp{Local Variables:}, on
1151: the first line of the list; it then automatically discards them from
1152: the other lines of the list.  The usual reason for using a prefix
1153: and/or suffix is to embed the local variables list in a comment, so it
1154: won't confuse other programs that the file is intended for.  The
1155: example above is for the C programming language, where comments start
1156: with @samp{/*} and end with @samp{*/}.
1157: 
1158: If some unrelated text might look to Emacs as a local variables list,
1159: you can countermand that by inserting a form-feed character (a page
1160: delimiter, @pxref{Pages}) after that text.  Emacs only looks for
1161: file-local variables in the last page of a file, after the last page
1162: delimiter.
1163: 
1164: @findex add-file-local-variable
1165: @findex delete-file-local-variable
1166: @findex copy-dir-locals-to-file-locals
1167:   Instead of typing in the local variables list directly, you can use
1168: the command @kbd{M-x add-file-local-variable}.  This prompts for a
1169: variable and value, and adds them to the list, adding the @samp{Local
1170: Variables:} string and start and end markers as necessary.  The
1171: command @kbd{M-x delete-file-local-variable} deletes a variable from
1172: the list.  @kbd{M-x copy-dir-locals-to-file-locals} copies
1173: directory-local variables to the list (@pxref{Directory Variables}).
1174: 
1175:   As with the @samp{-*-} line, the variables in a local variables list
1176: are used literally, and are not evaluated first.  If you want to split
1177: a long string value across multiple lines of the file, you can use
1178: backslash-newline, which is ignored in Lisp string constants; you
1179: should put the prefix and suffix on each line, even lines that start
1180: or end within the string, as they will be stripped off when processing
1181: the list.  Here is an example:
1182: 
1183: @example
1184: # Local Variables:
1185: # compile-command: "cc foo.c -Dfoo=bar -Dhack=whatever \
1186: #   -Dmumble=blaah"
1187: # End:
1188: @end example
1189: 
1190:   Some names have special meanings in a local variables
1191: list:
1192: 
1193: @itemize
1194: @item
1195: @code{mode} enables the specified major mode.
1196: 
1197: @item
1198: @code{eval} evaluates the specified Lisp expression (the value
1199: returned by that expression is ignored).
1200: 
1201: @item
1202: @code{coding} specifies the coding system for character code
1203: conversion of this file.  @xref{Coding Systems}.
1204: 
1205: @item
1206: @code{unibyte} says to load or compile a file of Emacs Lisp in unibyte
1207: mode, if the value is @code{t}.  @xref{Disabling Multibyte, ,
1208: Disabling Multibyte Characters, elisp, GNU Emacs Lisp Reference
1209: Manual}.
1210: 
1211: @end itemize
1212: 
1213: @noindent
1214: These four keywords are not really variables; setting them in any
1215: other context has no special meaning.
1216: 
1217:   Do not use the @code{mode} keyword for minor modes.  To enable or
1218: disable a minor mode in a local variables list, use the @code{eval}
1219: keyword with a Lisp expression that runs the mode command
1220: (@pxref{Minor Modes}).  For example, the following local variables
1221: list enables Eldoc mode (@pxref{Lisp Doc}) by calling
1222: @code{eldoc-mode} with no argument (calling it with an argument of 1
1223: would do the same), and disables Font Lock mode (@pxref{Font Lock}) by
1224: calling @code{font-lock-mode} with an argument of @minus{}1.
1225: 
1226: @example
1227: ;; Local Variables:
1228: ;; eval: (eldoc-mode)
1229: ;; eval: (font-lock-mode -1)
1230: ;; End:
1231: @end example
1232: 
1233: @noindent
1234: Note, however, that it is often a mistake to specify minor modes this
1235: way.  Minor modes represent individual user preferences, and it may be
1236: inappropriate to impose your preferences on another user who might
1237: edit the file.  If you wish to automatically enable or disable a minor
1238: mode in a situation-dependent way, it is often better to do it in a
1239: major mode hook (@pxref{Hooks}).
1240: 
1241:   Use the command @kbd{M-x normal-mode} to reset the local variables
1242: and major mode of a buffer according to the file name and contents,
1243: including the local variables list if any.  @xref{Choosing Modes}.
1244: 
1245: @node Safe File Variables
1246: @subsubsection Safety of File Variables
1247: 
1248:   File-local variables can be dangerous; when you visit someone else's
1249: file, there's no telling what its local variables list could do to
1250: your Emacs.  Improper values of the @code{eval} ``variable'', and
1251: other variables such as @code{load-path}, could execute Lisp code you
1252: didn't intend to run.
1253: 
1254:   Therefore, whenever Emacs encounters file local variable values that
1255: are not known to be safe, it displays the file's entire local
1256: variables list, and asks you for confirmation before setting them.
1257: You can type @kbd{y} or @key{SPC} to put the local variables list into
1258: effect, or @kbd{n} to ignore it.  When Emacs is run in batch mode
1259: (@pxref{Initial Options}), it can't really ask you, so it assumes the
1260: answer @kbd{n}.
1261: 
1262:   Emacs normally recognizes certain variable/value pairs as safe.
1263: For instance, it is safe to give @code{comment-column} or
1264: @code{fill-column} any integer value.  If a file specifies only
1265: known-safe variable/value pairs, Emacs does not ask for confirmation
1266: before setting them.  Otherwise, you can tell Emacs to record all the
1267: variable/value pairs in this file as safe, by typing @kbd{!} at the
1268: confirmation prompt.  When Emacs encounters these variable/value pairs
1269: subsequently, in the same file or others, it will assume they are
1270: safe.
1271: 
1272: @vindex safe-local-variable-values
1273: @cindex risky variable
1274:   Some variables, such as @code{load-path}, are considered
1275: particularly @dfn{risky}: there is seldom any reason to specify them
1276: as local variables, and changing them can be dangerous.  If a file
1277: contains only risky local variables, Emacs neither offers nor accepts
1278: @kbd{!} as input at the confirmation prompt.  If some of the local
1279: variables in a file are risky, and some are only potentially unsafe, you
1280: can enter @kbd{!} at the prompt.  It applies all the variables, but only
1281: marks the non-risky ones as safe for the future.  If you really want to
1282: record safe values for risky variables, do it directly by customizing
1283: @samp{safe-local-variable-values} (@pxref{Easy Customization}).
1284: 
1285: @vindex enable-local-variables
1286:   The variable @code{enable-local-variables} allows you to change the
1287: way Emacs processes local variables.  Its default value is @code{t},
1288: which specifies the behavior described above.  If it is @code{nil},
1289: Emacs simply ignores all file local variables.  @code{:safe} means use
1290: only the safe values and ignore the rest.  Any other value says to
1291: query you about each file that has local variables, without trying to
1292: determine whether the values are known to be safe.
1293: 
1294: @vindex enable-local-eval
1295: @vindex safe-local-eval-forms
1296:   The variable @code{enable-local-eval} controls whether Emacs
1297: processes @code{eval} variables.  The three possibilities for the
1298: variable's value are @code{t}, @code{nil}, and anything else, just as
1299: for @code{enable-local-variables}.  The default is @code{maybe}, which
1300: is neither @code{t} nor @code{nil}, so normally Emacs does ask for
1301: confirmation about processing @code{eval} variables.
1302: 
1303:   As an exception, Emacs never asks for confirmation to evaluate any
1304: @code{eval} form if that form occurs within the variable
1305: @code{safe-local-eval-forms}.
1306: 
1307: @node Directory Variables
1308: @subsection Per-Directory Local Variables
1309: @cindex local variables, for all files in a directory
1310: @cindex directory-local variables
1311: @cindex per-directory local variables
1312: 
1313:   Sometimes, you may wish to define the same set of local variables to
1314: all the files in a certain directory and its subdirectories, such as
1315: the directory tree of a large software project.  This can be
1316: accomplished with @dfn{directory-local variables}.  File local
1317: variables override directory local variables, so if some of the files
1318: in a directory need specialized settings, you can specify the settings
1319: for the majority of the directory's files in directory variables, and
1320: then define file local variables in a few files which need the general
1321: settings overridden.
1322: 
1323: @cindex @file{.dir-locals.el} file
1324:   The usual way to define directory-local variables is to put a file
1325: named @file{.dir-locals.el}@footnote{
1326: On MS-DOS, the name of this file should be @file{_dir-locals.el}, due
1327: to limitations of the DOS filesystems.  If the filesystem is limited
1328: to 8+3 file names, the name of the file will be truncated by the OS to
1329: @file{_dir-loc.el}.
1330: }in a directory.  Whenever Emacs visits any file in that directory or
1331: any of its subdirectories, it will apply the directory-local variables
1332: specified in @file{.dir-locals.el}, as though they had been defined as
1333: file-local variables for that file (@pxref{File Variables}).  Emacs
1334: searches for @file{.dir-locals.el} starting in the directory of the
1335: visited file, and moving up the directory tree.  To avoid slowdown,
1336: this search is skipped for remote files.  If needed, the search can be
1337: extended for remote files by setting the variable
1338: @code{enable-remote-dir-locals} to @code{t}.
1339: 
1340:   You can also use @file{.dir-locals-2.el}; if found, Emacs loads it
1341: in addition to @file{.dir-locals.el}.  This is useful when
1342: @file{.dir-locals.el} is under version control in a shared repository
1343: and can't be used for personal customizations.
1344: 
1345:   The @file{.dir-locals.el} file should hold a specially-constructed
1346: list, which maps major mode names (symbols) to alists
1347: (@pxref{Association Lists,,, elisp, The Emacs Lisp Reference Manual}).
1348: Each alist entry consists of a variable name and the directory-local
1349: value to assign to that variable, when the specified major mode is
1350: enabled.  Instead of a mode name, you can specify @samp{nil}, which
1351: means that the alist applies to any mode; or you can specify a
1352: subdirectory (a string), in which case the alist applies to all
1353: files in that subdirectory.
1354: 
1355:   Here's an example of a @file{.dir-locals.el} file:
1356: 
1357: @example
1358: ((nil . ((indent-tabs-mode . t)
1359:          (fill-column . 80)))
1360:  (c-mode . ((c-file-style . "BSD")
1361:             (subdirs . nil)))
1362:  ("src/imported"
1363:   . ((nil . ((change-log-default-name
1364:               . "ChangeLog.local"))))))
1365: @end example
1366: 
1367: @noindent
1368: This sets @samp{indent-tabs-mode} and @code{fill-column} for any file
1369: in the directory tree, and the indentation style for any C source
1370: file.  The special @code{subdirs} element is not a variable, but a
1371: special keyword which indicates that the C mode settings are only to
1372: be applied in the current directory, not in any subdirectories.
1373: Finally, it specifies a different @file{ChangeLog} file name for any
1374: file in the @file{src/imported} subdirectory.
1375: 
1376: You can specify the variables @code{mode}, @code{eval}, and
1377: @code{unibyte} in your @file{.dir-locals.el}, and they have the same
1378: meanings as they would have in file local variables.  @code{coding}
1379: cannot be specified as a directory local variable.  @xref{File
1380: Variables}.
1381: 
1382: @findex add-dir-local-variable
1383: @findex delete-dir-local-variable
1384: @findex copy-file-locals-to-dir-locals
1385:   Instead of editing the @file{.dir-locals.el} file by hand, you can
1386: use the command @kbd{M-x add-dir-local-variable}.  This prompts for a
1387: mode or subdirectory, and for variable and value, and adds the
1388: entry defining the directory-local variable.  @kbd{M-x
1389: delete-dir-local-variable} deletes an entry.  @kbd{M-x
1390: copy-file-locals-to-dir-locals} copies the file-local variables in the
1391: current file into @file{.dir-locals.el}.
1392: 
1393: @findex dir-locals-set-class-variables
1394: @findex dir-locals-set-directory-class
1395:   Another method of specifying directory-local variables is to define
1396: a group of variables/value pairs in a @dfn{directory class}, using the
1397: @code{dir-locals-set-class-variables} function; then, tell Emacs which
1398: directories correspond to the class by using the
1399: @code{dir-locals-set-directory-class} function.  These function calls
1400: normally go in your initialization file (@pxref{Init File}).  This
1401: method is useful when you can't put @file{.dir-locals.el} in a
1402: directory for some reason.  For example, you could apply settings to
1403: an unwritable directory this way:
1404: 
1405: @example
1406: (dir-locals-set-class-variables 'unwritable-directory
1407:    '((nil . ((some-useful-setting . value)))))
1408: 
1409: (dir-locals-set-directory-class
1410:    "/usr/include/" 'unwritable-directory)
1411: @end example
1412: 
1413:   If a variable has both a directory-local and file-local value
1414: specified, the file-local value takes effect.  Unsafe directory-local
1415: variables are handled in the same way as unsafe file-local variables
1416: (@pxref{Safe File Variables}).
1417: 
1418:   Directory-local variables also take effect in certain buffers that
1419: do not visit a file directly but perform work within a directory, such
1420: as Dired buffers (@pxref{Dired}).
1421: 
1422: @node Key Bindings
1423: @section Customizing Key Bindings
1424: @cindex key bindings
1425: 
1426:   This section describes @dfn{key bindings}, which map keys to
1427: commands, and @dfn{keymaps}, which record key bindings.  It also
1428: explains how to customize key bindings, which is done by editing your
1429: init file (@pxref{Init Rebinding}).
1430: 
1431: @cindex reserved key bindings
1432: @cindex keys, reserved
1433:   Since most modes define their own key bindings, activating a mode
1434: might override your custom key bindings.  A small number of keys are
1435: reserved for user-defined bindings, and should not be used by modes,
1436: so key bindings using those keys are safer in this regard.  The
1437: reserved key sequences are those consisting of @kbd{C-c} followed by a
1438: letter (either upper or lower case), and function keys @key{F5}
1439: through @key{F9} without modifiers (@pxref{Modifier Keys}).
1440: 
1441: @menu
1442: * Keymaps::             Generalities.  The global keymap.
1443: * Prefix Keymaps::      Keymaps for prefix keys.
1444: * Local Keymaps::       Major and minor modes have their own keymaps.
1445: * Minibuffer Maps::     The minibuffer uses its own local keymaps.
1446: * Rebinding::           How to redefine one key's meaning conveniently.
1447: * Init Rebinding::      Rebinding keys with your initialization file.
1448: * Modifier Keys::       Using modifier keys.
1449: * Function Keys::       Rebinding terminal function keys.
1450: * Named ASCII Chars::   Distinguishing @key{TAB} from @kbd{C-i}, and so on.
1451: * Mouse Buttons::       Rebinding mouse buttons in Emacs.
1452: * Disabling::           Disabling a command means confirmation is required
1453:                           before it can be executed.  This is done to protect
1454:                           beginners from surprises.
1455: @end menu
1456: 
1457: @node Keymaps
1458: @subsection Keymaps
1459: @cindex keymap
1460: 
1461:   As described in @ref{Commands}, each Emacs command is a Lisp
1462: function whose definition provides for interactive use.  Like every
1463: Lisp function, a command has a function name, which usually consists
1464: of lower-case letters and hyphens.
1465: 
1466:   A @dfn{key sequence} (@dfn{key}, for short) is a sequence of
1467: @dfn{input events} that have a meaning as a unit.  Input events
1468: include characters, function keys, and mouse buttons---all the inputs
1469: that you can send to the computer.  A key sequence gets its meaning
1470: from its @dfn{binding}, which says what command it runs.
1471: 
1472:   The bindings between key sequences and command functions are
1473: recorded in data structures called @dfn{keymaps}.  Emacs has many of
1474: these, each used on particular occasions.
1475: 
1476: @cindex global keymap
1477:   The @dfn{global} keymap is the most important keymap because it is
1478: always in effect.  The global keymap defines keys for Fundamental mode
1479: (@pxref{Major Modes}); most of these definitions are common to most or
1480: all major modes.  Each major or minor mode can have its own keymap
1481: which overrides the global definitions of some keys.
1482: 
1483:   For example, a self-inserting character such as @kbd{g} is
1484: self-inserting because the global keymap binds it to the command
1485: @code{self-insert-command}.  The standard Emacs editing characters
1486: such as @kbd{C-a} also get their standard meanings from the global
1487: keymap.  Commands to rebind keys, such as @kbd{M-x global-set-key},
1488: work by storing the new binding in the proper place in the global map
1489: (@pxref{Rebinding}).
1490: 
1491: @cindex function key
1492:   Most modern keyboards have function keys as well as character keys.
1493: Function keys send input events just as character keys do, and keymaps
1494: can have bindings for them.  Key sequences can mix function keys and
1495: characters.  For example, if your keyboard has a @key{Home} function
1496: key, Emacs can recognize key sequences like @kbd{C-x @key{Home}}.  You
1497: can even mix mouse events with keyboard events, such as
1498: @kbd{S-down-mouse-1}.
1499: 
1500:   On text terminals, typing a function key actually sends the computer
1501: a sequence of characters; the precise details of the sequence depend
1502: on the function key and on the terminal type.  (Often the sequence
1503: starts with @kbd{@key{ESC} [}.)  If Emacs understands your terminal
1504: type properly, it automatically handles such sequences as single input
1505: events.
1506: 
1507: @node Prefix Keymaps
1508: @subsection Prefix Keymaps
1509: 
1510:   Internally, Emacs records only single events in each keymap.
1511: Interpreting a key sequence of multiple events involves a chain of
1512: keymaps: the first keymap gives a definition for the first event,
1513: which is another keymap, which is used to look up the second event in
1514: the sequence, and so on.  Thus, a prefix key such as @kbd{C-x} or
1515: @key{ESC} has its own keymap, which holds the definition for the event
1516: that immediately follows that prefix.
1517: 
1518:   The definition of a prefix key is usually the keymap to use for
1519: looking up the following event.  The definition can also be a Lisp
1520: symbol whose function definition is the following keymap; the effect is
1521: the same, but it provides a command name for the prefix key that can be
1522: used as a description of what the prefix key is for.  Thus, the binding
1523: of @kbd{C-x} is the symbol @code{Control-X-prefix}, whose function
1524: definition is the keymap for @kbd{C-x} commands.  The definitions of
1525: @kbd{C-c}, @kbd{C-x}, @kbd{C-h}, and @key{ESC} as prefix keys appear in
1526: the global map, so these prefix keys are always available.
1527: 
1528:   Aside from ordinary prefix keys, there is a fictitious ``prefix key''
1529: which represents the menu bar; see @ref{Menu Bar,,,elisp, The Emacs Lisp
1530: Reference Manual}, for special information about menu bar key bindings.
1531: Mouse button events that invoke pop-up menus are also prefix keys; see
1532: @ref{Menu Keymaps,,,elisp, The Emacs Lisp Reference Manual}, for more
1533: details.
1534: 
1535:   Some prefix keymaps are stored in variables with names:
1536: 
1537: @itemize @bullet
1538: @item
1539: @vindex ctl-x-map
1540: @code{ctl-x-map} is the variable name for the map used for characters that
1541: follow @kbd{C-x}.
1542: @item
1543: @vindex help-map
1544: @code{help-map} is for characters that follow @kbd{C-h}.
1545: @item
1546: @vindex esc-map
1547: @code{esc-map} is for characters that follow @key{ESC}.  Thus, all Meta
1548: characters are actually defined by this map.
1549: @item
1550: @vindex ctl-x-4-map
1551: @code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}.
1552: @item
1553: @vindex mode-specific-map
1554: @code{mode-specific-map} is for characters that follow @kbd{C-c}.
1555: @end itemize
1556: 
1557: @node Local Keymaps
1558: @subsection Local Keymaps
1559: 
1560: @cindex local keymap
1561: @cindex minor mode keymap
1562:   So far, we have explained the ins and outs of the global map.  Major
1563: modes customize Emacs by providing their own key bindings in
1564: @dfn{local keymaps}.  For example, C mode overrides @key{TAB} to make
1565: it indent the current line for C code.  Minor modes can also have
1566: local keymaps; whenever a minor mode is in effect, the definitions in
1567: its keymap override both the major mode's local keymap and the global
1568: keymap.  In addition, portions of text in the buffer can specify their
1569: own keymaps, which override all other keymaps.
1570: 
1571:   A local keymap can redefine a key as a prefix key by defining it as
1572: a prefix keymap.  If the key is also defined globally as a prefix, its
1573: local and global definitions (both keymaps) effectively combine: both
1574: definitions are used to look up the event that follows the prefix key.
1575: For example, if a local keymap defines @kbd{C-c} as a prefix keymap,
1576: and that keymap defines @kbd{C-z} as a command, this provides a local
1577: meaning for @kbd{C-c C-z}.  This does not affect other sequences that
1578: start with @kbd{C-c}; if those sequences don't have their own local
1579: bindings, their global bindings remain in effect.
1580: 
1581:   Another way to think of this is that Emacs handles a multi-event key
1582: sequence by looking in several keymaps, one by one, for a binding of the
1583: whole key sequence.  First it checks the minor mode keymaps for minor
1584: modes that are enabled, then it checks the major mode's keymap, and then
1585: it checks the global keymap.  This is not precisely how key lookup
1586: works, but it's good enough for understanding the results in ordinary
1587: circumstances.
1588: 
1589: @node Minibuffer Maps
1590: @subsection Minibuffer Keymaps
1591: 
1592: @cindex minibuffer keymaps
1593: @vindex minibuffer-local-map
1594: @vindex minibuffer-local-ns-map
1595: @vindex minibuffer-local-completion-map
1596: @vindex minibuffer-local-must-match-map
1597: @vindex minibuffer-local-filename-completion-map
1598: @vindex minibuffer-local-filename-must-match-map
1599:   The minibuffer has its own set of local keymaps; they contain various
1600: completion and exit commands.
1601: 
1602: @itemize @bullet
1603: @item
1604: @code{minibuffer-local-map} is used for ordinary input (no completion).
1605: @item
1606: @code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
1607: just like @key{RET}.
1608: @item
1609: @code{minibuffer-local-completion-map} is for permissive completion.
1610: @item
1611: @code{minibuffer-local-must-match-map} is for strict completion and
1612: for cautious completion.
1613: @item
1614: @code{minibuffer-local-filename-completion-map} and
1615: @code{minibuffer-local-filename-must-match-map} are like the two
1616: previous ones, but they are specifically for file name completion.
1617: They do not bind @key{SPC}.
1618: @end itemize
1619: 
1620: @node Rebinding
1621: @subsection Changing Key Bindings Interactively
1622: @cindex key rebinding, this session
1623: @cindex redefining keys, this session
1624: @cindex binding keys
1625: 
1626:   The way to redefine an Emacs key is to change its entry in a keymap.
1627: You can change the global keymap, in which case the change is
1628: effective in all major modes (except those that have their own
1629: overriding local bindings for the same key).  Or you can change a
1630: local keymap, which affects all buffers using the same major mode.
1631: 
1632:   In this section, we describe how to rebind keys for the present
1633: Emacs session.  @xref{Init Rebinding}, for a description of how to
1634: make key rebindings affect future Emacs sessions.
1635: 
1636: @findex global-set-key
1637: @findex local-set-key
1638: @findex global-unset-key
1639: @findex local-unset-key
1640: @table @kbd
1641: @item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}
1642: Define @var{key} globally to run @var{cmd}.
1643: @item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET}
1644: Define @var{key} locally (in the major mode now in effect) to run
1645: @var{cmd}.
1646: @item M-x global-unset-key @key{RET} @var{key}
1647: Make @var{key} undefined in the global map.
1648: @item M-x local-unset-key @key{RET} @var{key}
1649: Make @var{key} undefined locally (in the major mode now in effect).
1650: @end table
1651: 
1652:   For example, the following binds @kbd{C-z} to the @code{shell}
1653: command (@pxref{Interactive Shell}), replacing the normal global
1654: definition of @kbd{C-z}:
1655: 
1656: @example
1657: M-x global-set-key @key{RET} C-z shell @key{RET}
1658: @end example
1659: 
1660: @noindent
1661: The @code{global-set-key} command reads the command name after the
1662: key.  After you press the key, a message like this appears so that you
1663: can confirm that you are binding the key you want:
1664: 
1665: @example
1666: Set key C-z to command:
1667: @end example
1668: 
1669:   You can redefine function keys and mouse events in the same way; just
1670: type the function key or click the mouse when it's time to specify the
1671: key to rebind.
1672: 
1673:   You can rebind a key that contains more than one event in the same
1674: way.  Emacs keeps reading the key to rebind until it is a complete key
1675: (that is, not a prefix key).  Thus, if you type @kbd{C-f} for
1676: @var{key}, that's the end; it enters the minibuffer immediately to
1677: read @var{cmd}.  But if you type @kbd{C-x}, since that's a prefix, it
1678: reads another character; if that is @kbd{4}, another prefix character,
1679: it reads one more character, and so on.  For example,
1680: 
1681: @example
1682: M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET}
1683: @end example
1684: 
1685: @noindent
1686: redefines @kbd{C-x 4 $} to run the (fictitious) command
1687: @code{spell-other-window}.
1688: 
1689:   You can remove the global definition of a key with
1690: @code{global-unset-key}.  This makes the key @dfn{undefined}; if you
1691: type it, Emacs will just beep.  Similarly, @code{local-unset-key} makes
1692: a key undefined in the current major mode keymap, which makes the global
1693: definition (or lack of one) come back into effect in that major mode.
1694: 
1695:   If you have redefined (or undefined) a key and you subsequently wish
1696: to retract the change, undefining the key will not do the job---you need
1697: to redefine the key with its standard definition.  To find the name of
1698: the standard definition of a key, go to a Fundamental mode buffer in a
1699: fresh Emacs and use @kbd{C-h c}.  The documentation of keys in this
1700: manual also lists their command names.
1701: 
1702:   If you want to prevent yourself from invoking a command by mistake, it
1703: is better to disable the command than to undefine the key.  A disabled
1704: command is less work to invoke when you really want to.
1705: @xref{Disabling}.
1706: 
1707: @node Init Rebinding
1708: @subsection Rebinding Keys in Your Init File
1709: @cindex rebinding major mode keys
1710: @cindex key rebinding, permanent
1711: @cindex rebinding keys, permanently
1712: @c This node is referenced in the tutorial.  When renaming or deleting
1713: @c it, the tutorial needs to be adjusted.  (TUTORIAL.de)
1714: 
1715:   If you have a set of key bindings that you like to use all the time,
1716: you can specify them in your initialization file by writing Lisp code.
1717: @xref{Init File}, for a description of the initialization file.
1718: 
1719: @findex kbd
1720:   There are several ways to write a key binding using Lisp.  The
1721: simplest is to use the @code{kbd} function, which converts a textual
1722: representation of a key sequence---similar to how we have written key
1723: sequences in this manual---into a form that can be passed as an
1724: argument to @code{global-set-key}.  For example, here's how to bind
1725: @kbd{C-z} to the @code{shell} command (@pxref{Interactive Shell}):
1726: 
1727: @example
1728: (global-set-key (kbd "C-z") 'shell)
1729: @end example
1730: 
1731: @noindent
1732: The single-quote before the command name, @code{shell}, marks it as a
1733: constant symbol rather than a variable.  If you omit the quote, Emacs
1734: would try to evaluate @code{shell} as a variable.  This probably
1735: causes an error; it certainly isn't what you want.
1736: 
1737:   Here are some additional examples, including binding function keys
1738: and mouse events:
1739: 
1740: @example
1741: (global-set-key (kbd "C-c y") 'clipboard-yank)
1742: (global-set-key (kbd "C-M-q") 'query-replace)
1743: (global-set-key (kbd "<f5>") 'flyspell-mode)
1744: (global-set-key (kbd "C-<f5>") 'display-line-numbers-mode)
1745: (global-set-key (kbd "C-<right>") 'forward-sentence)
1746: (global-set-key (kbd "<mouse-2>") 'mouse-save-then-kill)
1747: @end example
1748: 
1749:   Instead of using @code{kbd}, you can use a Lisp string or vector to
1750: specify the key sequence.  Using a string is simpler, but only works
1751: for @acronym{ASCII} characters and Meta-modified @acronym{ASCII}
1752: characters.  For example, here's how to bind @kbd{C-x M-l} to
1753: @code{make-symbolic-link} (@pxref{Copying and Naming}):
1754: 
1755: @example
1756: (global-set-key "\C-x\M-l" 'make-symbolic-link)
1757: @end example
1758: 
1759:   To bind a key sequence including @key{TAB}, @key{RET}, @key{ESC}, or
1760: @key{DEL}, the string should contain the Emacs Lisp escape sequence
1761: @samp{\t}, @samp{\r}, @samp{\e}, or @samp{\d} respectively.  Here is
1762: an example which binds @kbd{C-x @key{TAB}} to @code{indent-rigidly}
1763: (@pxref{Indentation}):
1764: 
1765: @example
1766: (global-set-key "\C-x\t" 'indent-rigidly)
1767: @end example
1768: 
1769:   When the key sequence includes function keys or mouse button events,
1770: or non-@acronym{ASCII} characters such as @code{C-=} or @code{H-a},
1771: you can use a vector to specify the key sequence.  Each element in the
1772: vector stands for an input event; the elements are separated by spaces
1773: and surrounded by a pair of square brackets.  If a vector element is a
1774: character, write it as a Lisp character constant: @samp{?} followed by
1775: the character as it would appear in a string.  Function keys are
1776: represented by symbols (@pxref{Function Keys}); simply write the
1777: symbol's name, with no other delimiters or punctuation.  Here are some
1778: examples:
1779: 
1780: @example
1781: (global-set-key [?\C-=] 'make-symbolic-link)
1782: (global-set-key [?\M-\C-=] 'make-symbolic-link)
1783: (global-set-key [?\H-a] 'make-symbolic-link)
1784: (global-set-key [f7] 'make-symbolic-link)
1785: (global-set-key [C-mouse-1] 'make-symbolic-link)
1786: @end example
1787: 
1788: @noindent
1789: You can use a vector for the simple cases too:
1790: 
1791: @example
1792: (global-set-key [?\C-z ?\M-l] 'make-symbolic-link)
1793: @end example
1794: 
1795:   Language and coding systems may cause problems with key bindings for
1796: non-@acronym{ASCII} characters.  @xref{Init Non-ASCII}.
1797: 
1798:   As described in @ref{Local Keymaps}, major modes and minor modes can
1799: define local keymaps.  These keymaps are constructed when the mode is
1800: used for the first time in a session.  If you wish to change one of
1801: these keymaps, you must use the @dfn{mode hook} (@pxref{Hooks}).
1802: 
1803: @findex define-key
1804:   For example, Texinfo mode runs the hook @code{texinfo-mode-hook}.
1805: Here's how you can use the hook to add local bindings for @kbd{C-c n}
1806: and @kbd{C-c p} in Texinfo mode:
1807: 
1808: @example
1809: (add-hook 'texinfo-mode-hook
1810:           (lambda ()
1811:             (define-key texinfo-mode-map "\C-cp"
1812:                         'backward-paragraph)
1813:             (define-key texinfo-mode-map "\C-cn"
1814:                         'forward-paragraph)))
1815: @end example
1816: 
1817: @node Modifier Keys
1818: @subsection Modifier Keys
1819: @cindex modifier keys, and key rebinding
1820: 
1821:   The default key bindings in Emacs are set up so that modified
1822: alphabetical characters are case-insensitive.  In other words,
1823: @kbd{C-A} does the same thing as @kbd{C-a}, and @kbd{M-A} does the
1824: same thing as @kbd{M-a}.  This concerns only alphabetical characters,
1825: and does not apply to shifted versions of other keys; for
1826: instance, @kbd{C-@@} is not the same as @kbd{C-2}.
1827: 
1828:   A @key{Control}-modified alphabetical character is always considered
1829: case-insensitive: Emacs always treats @kbd{C-A} as @kbd{C-a},
1830: @kbd{C-B} as @kbd{C-b}, and so forth.  The reason for this is
1831: historical.
1832: 
1833:   For all other modifiers, you can make the modified alphabetical
1834: characters case-sensitive when you customize Emacs.  For instance, you
1835: could make @kbd{M-a} and @kbd{M-A} run different commands.
1836: 
1837:   Although only the @key{Control} and @key{Meta} modifier keys are
1838: commonly used, Emacs supports three other modifier keys.  These are
1839: called @key{Super}, @key{Hyper}, and @key{Alt}.  Few terminals provide
1840: ways to use these modifiers; the key labeled @key{Alt} on most
1841: keyboards usually issues the @key{Meta} modifier, not @key{Alt}.  The
1842: standard key bindings in Emacs do not include any characters with
1843: these modifiers.  However, you can customize Emacs to assign meanings
1844: to them.  The modifier bits are labeled as @samp{s-}, @samp{H-} and
1845: @samp{A-} respectively.
1846: 
1847:   Even if your keyboard lacks these additional modifier keys, you can
1848: enter it using @kbd{C-x @@}: @kbd{C-x @@ h} adds the Hyper flag to
1849: the next character, @kbd{C-x @@ s} adds the Super flag, and
1850: @kbd{C-x @@ a} adds the Alt flag.  For instance, @kbd{C-x @@ h
1851: C-a} is a way to enter @kbd{Hyper-Control-a}.  (Unfortunately, there
1852: is no way to add two modifiers by using @kbd{C-x @@} twice for the
1853: same character, because the first one goes to work on the @kbd{C-x}.)
1854: 
1855: @node Function Keys
1856: @subsection Rebinding Function Keys
1857: 
1858:   Key sequences can contain function keys as well as ordinary
1859: characters.  Just as Lisp characters (actually integers) represent
1860: keyboard characters, Lisp symbols represent function keys.  If the
1861: function key has a word as its label, then that word is also the name of
1862: the corresponding Lisp symbol.  Here are the conventional Lisp names for
1863: common function keys:
1864: 
1865: @table @asis
1866: @item @code{left}, @code{up}, @code{right}, @code{down}
1867: Cursor arrow keys.
1868: 
1869: @item @code{begin}, @code{end}, @code{home}, @code{next}, @code{prior}
1870: Other cursor repositioning keys.
1871: 
1872: @item @code{select}, @code{print}, @code{execute}, @code{backtab}
1873: @itemx @code{insert}, @code{undo}, @code{redo}, @code{clearline}
1874: @itemx @code{insertline}, @code{deleteline}, @code{insertchar}, @code{deletechar}
1875: Miscellaneous function keys.
1876: 
1877: @item @code{f1}, @code{f2}, @dots{} @code{f35}
1878: Numbered function keys (across the top of the keyboard).
1879: 
1880: @item @code{kp-add}, @code{kp-subtract}, @code{kp-multiply}, @code{kp-divide}
1881: @itemx @code{kp-backtab}, @code{kp-space}, @code{kp-tab}, @code{kp-enter}
1882: @itemx @code{kp-separator}, @code{kp-decimal}, @code{kp-equal}
1883: @itemx @code{kp-prior}, @code{kp-next}, @code{kp-end}, @code{kp-home}
1884: @itemx @code{kp-left}, @code{kp-up}, @code{kp-right}, @code{kp-down}
1885: @itemx @code{kp-insert }, @code{kp-delete}
1886: Keypad keys (to the right of the regular keyboard), with names or punctuation.
1887: 
1888: @item @code{kp-0}, @code{kp-1}, @dots{} @code{kp-9}
1889: Keypad keys with digits.
1890: 
1891: @item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
1892: Keypad PF keys.
1893: @end table
1894: 
1895:   These names are conventional, but some systems (especially when using
1896: X) may use different names.  To make certain what symbol is used for a
1897: given function key on your terminal, type @kbd{C-h c} followed by that
1898: key.
1899: 
1900:   @xref{Init Rebinding}, for examples of binding function keys.
1901: 
1902: @cindex keypad
1903:   Many keyboards have a numeric keypad on the right-hand side.
1904: The numeric keys in the keypad double up as cursor motion keys,
1905: toggled by a key labeled @samp{Num Lock}.  By default, Emacs
1906: translates these keys to the corresponding keys on the main keyboard.
1907: For example, when @samp{Num Lock} is on, the key labeled @samp{8} on
1908: the numeric keypad produces @code{kp-8}, which is translated to
1909: @kbd{8}; when @samp{Num Lock} is off, the same key produces
1910: @code{kp-up}, which is translated to @key{UP}.  If you rebind a key
1911: such as @kbd{8} or @key{UP}, it affects the equivalent keypad key too.
1912: However, if you rebind a @samp{kp-} key directly, that won't affect
1913: its non-keypad equivalent.  Note that the modified keys are not
1914: translated: for instance, if you hold down the @key{Meta} key while
1915: pressing the @samp{8} key on the numeric keypad, that generates
1916: @kbd{M-@key{kp-8}}.
1917: 
1918:   Emacs provides a convenient method for binding the numeric keypad
1919: keys, using the variables @code{keypad-setup},
1920: @code{keypad-numlock-setup}, @code{keypad-shifted-setup}, and
1921: @code{keypad-numlock-shifted-setup}.  These can be found in the
1922: @samp{keyboard} customization group (@pxref{Easy Customization}).  You
1923: can rebind the keys to perform other tasks, such as issuing numeric
1924: prefix arguments.
1925: 
1926: @node Named ASCII Chars
1927: @subsection Named @acronym{ASCII} Control Characters
1928: 
1929:   @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC}, and @key{DEL}
1930: started out as names for certain @acronym{ASCII} control characters,
1931: used so often that they have special keys of their own.  For instance,
1932: @key{TAB} was another name for @kbd{C-i}.  Later, users found it
1933: convenient to distinguish in Emacs between these keys and the corresponding
1934: control characters typed with the @key{Ctrl} key.  Therefore, on most
1935: modern terminals, they are no longer the same: @key{TAB} is different
1936: from @kbd{C-i}.
1937: 
1938:   Emacs can distinguish these two kinds of input if the keyboard does.
1939: It treats the special keys as function keys named @code{tab},
1940: @code{return}, @code{backspace}, @code{linefeed}, @code{escape}, and
1941: @code{delete}.  These function keys translate automatically into the
1942: corresponding @acronym{ASCII} characters @emph{if} they have no
1943: bindings of their own.  As a result, neither users nor Lisp programs
1944: need to pay attention to the distinction unless they care to.
1945: 
1946:   If you do not want to distinguish between (for example) @key{TAB} and
1947: @kbd{C-i}, make just one binding, for the @acronym{ASCII} character @key{TAB}
1948: (octal code 011).  If you do want to distinguish, make one binding for
1949: this @acronym{ASCII} character, and another for the function key @code{tab}.
1950: 
1951:   With an ordinary @acronym{ASCII} terminal, there is no way to distinguish
1952: between @key{TAB} and @kbd{C-i} (and likewise for other such pairs),
1953: because the terminal sends the same character in both cases.
1954: 
1955: @node Mouse Buttons
1956: @subsection Rebinding Mouse Buttons
1957: @cindex mouse button events
1958: @cindex rebinding mouse buttons
1959: @cindex click events
1960: @cindex drag events
1961: @cindex down events
1962: @cindex button-down events
1963: 
1964:   Emacs uses Lisp symbols to designate mouse buttons, too.  The ordinary
1965: mouse events in Emacs are @dfn{click} events; these happen when you
1966: press a button and release it without moving the mouse.  You can also
1967: get @dfn{drag} events, when you move the mouse while holding the button
1968: down.  Drag events happen when you finally let go of the button.
1969: 
1970:   The symbols for basic click events are @code{mouse-1} for the leftmost
1971: button, @code{mouse-2} for the next, and so on.  Here is how you can
1972: redefine the second mouse button to split the current window:
1973: 
1974: @example
1975: (global-set-key [mouse-2] 'split-window-below)
1976: @end example
1977: 
1978:   The symbols for drag events are similar, but have the prefix
1979: @samp{drag-} before the word @samp{mouse}.  For example, dragging the
1980: first button generates a @code{drag-mouse-1} event.
1981: 
1982:   You can also define bindings for events that occur when a mouse button
1983: is pressed down.  These events start with @samp{down-} instead of
1984: @samp{drag-}.  Such events are generated only if they have key bindings.
1985: When you get a button-down event, a corresponding click or drag event
1986: will always follow.
1987: 
1988: @cindex double clicks
1989: @cindex triple clicks
1990:   If you wish, you can distinguish single, double, and triple clicks.  A
1991: double click means clicking a mouse button twice in approximately the
1992: same place.  The first click generates an ordinary click event.  The
1993: second click, if it comes soon enough, generates a double-click event
1994: instead.  The event type for a double-click event starts with
1995: @samp{double-}: for example, @code{double-mouse-3}.
1996: 
1997:   This means that you can give a special meaning to the second click at
1998: the same place, but it must act on the assumption that the ordinary
1999: single click definition has run when the first click was received.
2000: 
2001:   This constrains what you can do with double clicks, but user interface
2002: designers say that this constraint ought to be followed in any case.  A
2003: double click should do something similar to the single click, only
2004: more so.  The command for the double-click event should perform the
2005: extra work for the double click.
2006: 
2007:   If a double-click event has no binding, it changes to the
2008: corresponding single-click event.  Thus, if you don't define a
2009: particular double click specially, it executes the single-click command
2010: twice.
2011: 
2012:   Emacs also supports triple-click events whose names start with
2013: @samp{triple-}.  Emacs does not distinguish quadruple clicks as event
2014: types; clicks beyond the third generate additional triple-click events.
2015: However, the full number of clicks is recorded in the event list, so
2016: if you know Emacs Lisp you can distinguish if you really want to
2017: (@pxref{Click Events,,, elisp, The Emacs Lisp Reference Manual}).
2018: We don't recommend distinct meanings for more than three clicks, but
2019: sometimes it is useful for subsequent clicks to cycle through the same
2020: set of three meanings, so that four clicks are equivalent to one
2021: click, five are equivalent to two, and six are equivalent to three.
2022: 
2023:   Emacs also records multiple presses in drag and button-down events.
2024: For example, when you press a button twice, then move the mouse while
2025: holding the button, Emacs gets a @samp{double-drag-} event.  And at the
2026: moment when you press it down for the second time, Emacs gets a
2027: @samp{double-down-} event (which is ignored, like all button-down
2028: events, if it has no binding).
2029: 
2030: @vindex double-click-time
2031:   The variable @code{double-click-time} specifies how much time can
2032: elapse between clicks and still allow them to be grouped as a multiple
2033: click.  Its value is in units of milliseconds.  If the value is
2034: @code{nil}, double clicks are not detected at all.  If the value is
2035: @code{t}, then there is no time limit.  The default is 500.
2036: 
2037: @vindex double-click-fuzz
2038:   The variable @code{double-click-fuzz} specifies how much the mouse
2039: can move between clicks and still allow them to be grouped as a multiple
2040: click.  Its value is in units of pixels on windowed displays and in
2041: units of 1/8 of a character cell on text-mode terminals; the default is
2042: 3.
2043: 
2044:   The symbols for mouse events also indicate the status of the modifier
2045: keys, with the usual prefixes @samp{C-}, @samp{M-}, @samp{H-},
2046: @samp{s-}, @samp{A-}, and @samp{S-}.  These always precede @samp{double-}
2047: or @samp{triple-}, which always precede @samp{drag-} or @samp{down-}.
2048: 
2049:   A frame includes areas that don't show text from the buffer, such as
2050: the mode line and the scroll bar.  You can tell whether a mouse button
2051: comes from a special area of the screen by means of dummy prefix
2052: keys.  For example, if you click the mouse in the mode line, you get
2053: the prefix key @code{mode-line} before the ordinary mouse-button symbol.
2054: Thus, here is how to define the command for clicking the first button in
2055: a mode line to run @code{scroll-up-command}:
2056: 
2057: @example
2058: (global-set-key [mode-line mouse-1] 'scroll-up-command)
2059: @end example
2060: 
2061:   Here is the complete list of these dummy prefix keys and their
2062: meanings:
2063: 
2064: @table @code
2065: @item mode-line
2066: The mouse was in the mode line of a window.
2067: @item vertical-line
2068: The mouse was in the vertical line separating side-by-side windows.  (If
2069: you use scroll bars, they appear in place of these vertical lines.)
2070: @item vertical-scroll-bar
2071: The mouse was in a vertical scroll bar.  (This is the only kind of
2072: scroll bar Emacs currently supports.)
2073: @item menu-bar
2074: The mouse was in the menu bar.
2075: @item header-line
2076: The mouse was in a header line.
2077: @ignore
2078: @item horizontal-scroll-bar
2079: The mouse was in a horizontal scroll bar.  Horizontal scroll bars do
2080: horizontal scrolling, and people don't use them often.
2081: @end ignore
2082: @end table
2083: 
2084:   You can put more than one mouse button in a key sequence, but it isn't
2085: usual to do so.
2086: 
2087: @node Disabling
2088: @subsection Disabling Commands
2089: @cindex disabled command
2090: 
2091:   Disabling a command means that invoking it interactively asks for
2092: confirmation from the user.  The purpose of disabling a command is to
2093: prevent users from executing it by accident; we do this for commands
2094: that might be confusing to the uninitiated.
2095: 
2096:   Attempting to invoke a disabled command interactively in Emacs
2097: displays a window containing the command's name, its documentation,
2098: and some instructions on what to do immediately; then Emacs asks for
2099: input saying whether to execute the command as requested, enable it
2100: and execute it, or cancel.  If you decide to enable the command, you
2101: must then answer another question---whether to do this permanently, or
2102: just for the current session.  (Enabling permanently works by
2103: automatically editing your initialization file.)  You can also type
2104: @kbd{!} to enable @emph{all} commands, for the current session only.
2105: 
2106:   The direct mechanism for disabling a command is to put a
2107: non-@code{nil} @code{disabled} property on the Lisp symbol for the
2108: command.  Here is the Lisp program to do this:
2109: 
2110: @example
2111: (put 'delete-region 'disabled t)
2112: @end example
2113: 
2114:   If the value of the @code{disabled} property is a string, that string
2115: is included in the message displayed when the command is used:
2116: 
2117: @example
2118: (put 'delete-region 'disabled
2119:      "It's better to use `kill-region' instead.\n")
2120: @end example
2121: 
2122: @findex disable-command
2123: @findex enable-command
2124:   You can make a command disabled either by editing the initialization
2125: file directly, or with the command @kbd{M-x disable-command}, which
2126: edits the initialization file for you.  Likewise, @kbd{M-x
2127: enable-command} edits the initialization file to enable a command
2128: permanently.  @xref{Init File}.
2129: 
2130:   If Emacs was invoked with the @option{-q} or @option{--no-init-file}
2131: options (@pxref{Initial Options}), it will not edit your
2132: initialization file.  Doing so could lose information because Emacs
2133: has not read your initialization file.
2134: 
2135:   Whether a command is disabled is independent of what key is used to
2136: invoke it; disabling also applies if the command is invoked using
2137: @kbd{M-x}.  However, disabling a command has no effect on calling it
2138: as a function from Lisp programs.
2139: 
2140: @node Init File
2141: @section The Emacs Initialization File
2142: @cindex init file
2143: @cindex .emacs file
2144: @cindex ~/.emacs file
2145: @cindex Emacs initialization file
2146: @cindex startup (init file)
2147: 
2148:   When Emacs is started, it normally tries to load a Lisp program from
2149: an @dfn{initialization file}, or @dfn{init file} for short.  This
2150: file, if it exists, specifies how to initialize Emacs for you.  Emacs
2151: looks for your init file using the filenames @file{~/.emacs},
2152: @file{~/.emacs.el}, or @file{~/.emacs.d/init.el}; you can choose to
2153: use any one of these three names (@pxref{Find Init}).  Here, @file{~/}
2154: stands for your home directory.
2155: 
2156:   You can use the command line switch @samp{-q} to prevent loading
2157: your init file, and @samp{-u} (or @samp{--user}) to specify a
2158: different user's init file (@pxref{Initial Options}).
2159: 
2160: @cindex @file{default.el}, the default init file
2161:   There can also be a @dfn{default init file}, which is the library
2162: named @file{default.el}, found via the standard search path for
2163: libraries.  The Emacs distribution contains no such library; your site
2164: may create one for local customizations.  If this library exists, it is
2165: loaded whenever you start Emacs (except when you specify @samp{-q}).
2166: But your init file, if any, is loaded first; if it sets
2167: @code{inhibit-default-init} non-@code{nil}, then @file{default} is not
2168: loaded.
2169: 
2170: @cindex site init file
2171: @cindex @file{site-start.el}, the site startup file
2172:   Your site may also have a @dfn{site startup file}; this is named
2173: @file{site-start.el}, if it exists.  Like @file{default.el}, Emacs
2174: finds this file via the standard search path for Lisp libraries.
2175: Emacs loads this library before it loads your init file.  To inhibit
2176: loading of this library, use the option @samp{--no-site-file}.
2177: @xref{Initial Options}.  We recommend against using
2178: @file{site-start.el} for changes that some users may not like.  It is
2179: better to put them in @file{default.el}, so that users can more easily
2180: override them.
2181: 
2182: @cindex @file{site-lisp} directories
2183:   You can place @file{default.el} and @file{site-start.el} in any of
2184: the directories which Emacs searches for Lisp libraries.  The variable
2185: @code{load-path} (@pxref{Lisp Libraries}) specifies these directories.
2186: Many sites put these files in a subdirectory named @file{site-lisp} in
2187: the Emacs installation directory, such as
2188: @file{/usr/local/share/emacs/site-lisp}.
2189: 
2190:   Byte-compiling your init file is not recommended (@pxref{Byte
2191: Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference
2192: Manual}).  It generally does not speed up startup very much, and often
2193: leads to problems when you forget to recompile the file.  A better
2194: solution is to use the Emacs server to reduce the number of times you
2195: have to start Emacs (@pxref{Emacs Server}).  If your init file defines
2196: many functions, consider moving them to a separate (byte-compiled)
2197: file that you load in your init file.
2198: 
2199:   If you are going to write actual Emacs Lisp programs that go beyond
2200: minor customization, you should read the @cite{Emacs Lisp Reference Manual}.
2201: @ifnottex
2202: @xref{Top, Emacs Lisp, Emacs Lisp, elisp, the Emacs Lisp Reference
2203: Manual}.
2204: @end ifnottex
2205: 
2206: @menu
2207: * Init Syntax::         Syntax of constants in Emacs Lisp.
2208: * Init Examples::       How to do some things with an init file.
2209: * Terminal Init::       Each terminal type can have an init file.
2210: * Find Init::           How Emacs finds the init file.
2211: * Init Non-ASCII::      Using non-@acronym{ASCII} characters in an init file.
2212: * Early Init File::     Another init file, which is read early on.
2213: @end menu
2214: 
2215: @node Init Syntax
2216: @subsection Init File Syntax
2217: 
2218:   The init file contains one or more Lisp expressions.  Each of these
2219: consists of a function name followed by arguments, all surrounded by
2220: parentheses.  For example, @code{(setq fill-column 60)} calls the
2221: function @code{setq} to set the variable @code{fill-column}
2222: (@pxref{Filling}) to 60.
2223: 
2224:   You can set any Lisp variable with @code{setq}, but with certain
2225: variables @code{setq} won't do what you probably want in the
2226: @file{.emacs} file.  Some variables automatically become buffer-local
2227: when set with @code{setq}; what you want in @file{.emacs} is to set
2228: the default value, using @code{setq-default}.  Some customizable minor
2229: mode variables do special things to enable the mode when you set them
2230: with Customize, but ordinary @code{setq} won't do that; to enable the
2231: mode in your @file{.emacs} file, call the minor mode command.  The
2232: following section has examples of both of these methods.
2233: 
2234:   The second argument to @code{setq} is an expression for the new
2235: value of the variable.  This can be a constant, a variable, or a
2236: function call expression.  In @file{.emacs}, constants are used most
2237: of the time.  They can be:
2238: 
2239: @table @asis
2240: @item Numbers:
2241: Numbers are written in decimal, with an optional initial minus sign.
2242: 
2243: @item Strings:
2244: @cindex Lisp string syntax
2245: @cindex string syntax
2246: Lisp string syntax is the same as C string syntax with a few extra
2247: features.  Use a double-quote character to begin and end a string constant.
2248: 
2249: In a string, you can include newlines and special characters literally.
2250: But often it is cleaner to use backslash sequences for them: @samp{\n}
2251: for newline, @samp{\b} for backspace, @samp{\r} for carriage return,
2252: @samp{\t} for tab, @samp{\f} for formfeed (control-L), @samp{\e} for
2253: escape, @samp{\\} for a backslash, @samp{\"} for a double-quote, or
2254: @samp{\@var{ooo}} for the character whose octal code is @var{ooo}.
2255: Backslash and double-quote are the only characters for which backslash
2256: sequences are mandatory.
2257: 
2258: @samp{\C-} can be used as a prefix for a control character, as in
2259: @samp{\C-s} for @acronym{ASCII} control-S, and @samp{\M-} can be used as a prefix for
2260: a Meta character, as in @samp{\M-a} for @kbd{@key{Meta}-A} or
2261: @samp{\M-\C-a} for @kbd{@key{Ctrl}-@key{Meta}-A}.
2262: 
2263: @xref{Init Non-ASCII}, for information about including
2264: non-@acronym{ASCII} in your init file.
2265: 
2266: @item Characters:
2267: @cindex Lisp character syntax
2268: @cindex character syntax
2269: Lisp character constant syntax consists of a @samp{?} followed by
2270: either a character or an escape sequence starting with @samp{\}.
2271: Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}.  Note that
2272: strings and characters are not interchangeable in Lisp; some contexts
2273: require one and some contexts require the other.
2274: 
2275: @xref{Init Non-ASCII}, for information about binding commands to
2276: keys which send non-@acronym{ASCII} characters.
2277: 
2278: @item True:
2279: @code{t} stands for ``true''.
2280: 
2281: @item False:
2282: @code{nil} stands for ``false''.
2283: 
2284: @item Other Lisp objects:
2285: @cindex Lisp object syntax
2286: Write a single-quote (@code{'}) followed by the Lisp object you want.
2287: @end table
2288: 
2289: @node Init Examples
2290: @subsection Init File Examples
2291: 
2292:   Here are some examples of doing certain commonly desired things with
2293: Lisp expressions:
2294: 
2295: @itemize @bullet
2296: @item
2297: Add a directory to the variable @code{load-path}.  You can then put
2298: Lisp libraries that are not included with Emacs in this directory, and
2299: load them with @kbd{M-x load-library}.  @xref{Lisp Libraries}.
2300: 
2301: @example
2302: (add-to-list 'load-path "/path/to/lisp/libraries")
2303: @end example
2304: 
2305: @item
2306: Make @key{TAB} in C mode just insert a tab if point is in the middle of a
2307: line.
2308: 
2309: @example
2310: (setq c-tab-always-indent nil)
2311: @end example
2312: 
2313: Here we have a variable whose value is normally @code{t} for ``true''
2314: and the alternative is @code{nil} for ``false''.
2315: 
2316: @item
2317: Make searches case sensitive by default (in all buffers that do not
2318: override this).
2319: 
2320: @example
2321: (setq-default case-fold-search nil)
2322: @end example
2323: 
2324: This sets the default value, which is effective in all buffers that do
2325: not have local values for the variable (@pxref{Locals}).  Setting
2326: @code{case-fold-search} with @code{setq} affects only the current
2327: buffer's local value, which is probably not what you want to do in an
2328: init file.
2329: 
2330: @item
2331: @vindex user-mail-address@r{, in init file}
2332: Specify your own email address, if Emacs can't figure it out correctly.
2333: 
2334: @example
2335: (setq user-mail-address "cheney@@torture.gov")
2336: @end example
2337: 
2338: Various Emacs packages, such as Message mode, consult
2339: @code{user-mail-address} when they need to know your email address.
2340: @xref{Mail Headers}.
2341: 
2342: @item
2343: Make Text mode the default mode for new buffers.
2344: 
2345: @example
2346: (setq-default major-mode 'text-mode)
2347: @end example
2348: 
2349: Note that @code{text-mode} is used because it is the command for
2350: entering Text mode.  The single-quote before it makes the symbol a
2351: constant; otherwise, @code{text-mode} would be treated as a variable
2352: name.
2353: 
2354: @need 1500
2355: @item
2356: Set up defaults for the Latin-1 character set,
2357: which supports most of the languages of Western Europe.
2358: 
2359: @example
2360: (set-language-environment "Latin-1")
2361: @end example
2362: 
2363: @need 1500
2364: @item
2365: Turn off Line Number mode, a global minor mode.
2366: 
2367: @example
2368: (line-number-mode 0)
2369: @end example
2370: 
2371: @need 1500
2372: @item
2373: Turn on Auto Fill mode automatically in Text mode and related modes
2374: (@pxref{Hooks}).
2375: 
2376: @example
2377: (add-hook 'text-mode-hook 'auto-fill-mode)
2378: @end example
2379: 
2380: @item
2381: Load the installed Lisp library named @file{foo} (actually a file
2382: @file{foo.elc} or @file{foo.el} in a standard Emacs directory).
2383: 
2384: @example
2385: (load "foo")
2386: @end example
2387: 
2388: When the argument to @code{load} is a relative file name, not starting
2389: with @samp{/} or @samp{~}, @code{load} searches the directories in
2390: @code{load-path} (@pxref{Lisp Libraries}).
2391: 
2392: @item
2393: Load the compiled Lisp file @file{foo.elc} from your home directory.
2394: 
2395: @example
2396: (load "~/foo.elc")
2397: @end example
2398: 
2399: Here a full file name is used, so no searching is done.
2400: 
2401: @item
2402: @cindex loading Lisp libraries automatically
2403: @cindex autoload Lisp libraries
2404: Tell Emacs to find the definition for the function @code{myfunction}
2405: by loading a Lisp library named @file{mypackage} (i.e., a file
2406: @file{mypackage.elc} or @file{mypackage.el}):
2407: 
2408: @example
2409: (autoload 'myfunction "mypackage" "Do what I say." t)
2410: @end example
2411: 
2412: @noindent
2413: Here the string @code{"Do what I say."} is the function's
2414: documentation string.  You specify it in the @code{autoload}
2415: definition so it will be available for help commands even when the
2416: package is not loaded.  The last argument, @code{t}, indicates that
2417: this function is interactive; that is, it can be invoked interactively
2418: by typing @kbd{M-x myfunction @key{RET}} or by binding it to a key.
2419: If the function is not interactive, omit the @code{t} or use
2420: @code{nil}.
2421: 
2422: @item
2423: Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}
2424: (@pxref{Init Rebinding}).
2425: 
2426: @example
2427: (global-set-key "\C-xl" 'make-symbolic-link)
2428: @end example
2429: 
2430: or
2431: 
2432: @example
2433: (define-key global-map "\C-xl" 'make-symbolic-link)
2434: @end example
2435: 
2436: Note once again the single-quote used to refer to the symbol
2437: @code{make-symbolic-link} instead of its value as a variable.
2438: 
2439: @item
2440: Do the same thing for Lisp mode only.
2441: 
2442: @example
2443: (define-key lisp-mode-map "\C-xl" 'make-symbolic-link)
2444: @end example
2445: 
2446: @item
2447: Redefine all keys which now run @code{next-line} in Fundamental mode
2448: so that they run @code{forward-line} instead.
2449: 
2450: @findex substitute-key-definition
2451: @example
2452: (substitute-key-definition 'next-line 'forward-line
2453:                            global-map)
2454: @end example
2455: 
2456: @item
2457: Make @kbd{C-x C-v} undefined.
2458: 
2459: @example
2460: (global-unset-key "\C-x\C-v")
2461: @end example
2462: 
2463: One reason to undefine a key is so that you can make it a prefix.
2464: Simply defining @kbd{C-x C-v @var{anything}} will make @kbd{C-x C-v} a
2465: prefix, but @kbd{C-x C-v} must first be freed of its usual non-prefix
2466: definition.
2467: 
2468: @item
2469: Make @samp{$} have the syntax of punctuation in Text mode.
2470: Note the use of a character constant for @samp{$}.
2471: 
2472: @example
2473: (modify-syntax-entry ?\$ "." text-mode-syntax-table)
2474: @end example
2475: 
2476: @item
2477: Enable the use of the command @code{narrow-to-region} without confirmation.
2478: 
2479: @example
2480: (put 'narrow-to-region 'disabled nil)
2481: @end example
2482: 
2483: @item
2484: Adjusting the configuration to various platforms and Emacs versions.
2485: 
2486: Users typically want Emacs to behave the same on all systems, so the
2487: same init file is right for all platforms.  However, sometimes it
2488: happens that a function you use for customizing Emacs is not available
2489: on some platforms or in older Emacs versions.  To deal with that
2490: situation, put the customization inside a conditional that tests whether
2491: the function or facility is available, like this:
2492: 
2493: @example
2494: (if (fboundp 'blink-cursor-mode)
2495:     (blink-cursor-mode 0))
2496: 
2497: (if (boundp 'coding-category-utf-8)
2498:     (set-coding-priority '(coding-category-utf-8)))
2499: @end example
2500: 
2501: @noindent
2502: You can also simply disregard the errors that occur if the
2503: function is not defined.
2504: 
2505: @example
2506: (ignore-errors (set-face-background 'region "grey75"))
2507: @end example
2508: 
2509: A @code{setq} on a variable which does not exist is generally
2510: harmless, so those do not need a conditional.
2511: @end itemize
2512: 
2513: @node Terminal Init
2514: @subsection Terminal-specific Initialization
2515: 
2516: @vindex term-file-aliases
2517:   Each terminal type can have a Lisp library to be loaded into Emacs when
2518: it is run on that type of terminal.  For a terminal type named
2519: @var{termtype}, the library is called @file{term/@var{termtype}}.
2520: (If there is an entry of the form @code{(@var{termtype} . @var{alias})}
2521: in the @code{term-file-aliases} association list, Emacs uses
2522: @var{alias} in place of @var{termtype}.)  The library is
2523: found by searching the directories @code{load-path} as usual and trying the
2524: suffixes @samp{.elc} and @samp{.el}.  Normally it appears in the
2525: subdirectory @file{term} of the directory where most Emacs libraries are
2526: kept.
2527: 
2528:   The usual purpose of the terminal-specific library is to map the
2529: escape sequences used by the terminal's function keys onto more
2530: meaningful names, using @code{input-decode-map} (or
2531: @code{function-key-map} before it).  See the file
2532: @file{term/lk201.el} for an example of how this is done.  Many function
2533: keys are mapped automatically according to the information in the
2534: Termcap data base; the terminal-specific library needs to map only the
2535: function keys that Termcap does not specify.
2536: 
2537:   When the terminal type contains a hyphen, only the part of the name
2538: before the first hyphen is significant in choosing the library name.
2539: Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
2540: the library @file{term/aaa}.  The code in the library can use
2541: @code{(getenv "TERM")} to find the full terminal type name.
2542: 
2543: @vindex term-file-prefix
2544:   The library's name is constructed by concatenating the value of the
2545: variable @code{term-file-prefix} and the terminal type.  Your @file{.emacs}
2546: file can prevent the loading of the terminal-specific library by setting
2547: @code{term-file-prefix} to @code{nil}.
2548: 
2549: @vindex tty-setup-hook
2550:   Emacs runs the hook @code{tty-setup-hook} at the end of
2551: initialization, after both your @file{.emacs} file and any
2552: terminal-specific library have been read in.  Add hook functions to this
2553: hook if you wish to override part of any of the terminal-specific
2554: libraries and to define initializations for terminals that do not have a
2555: library.  @xref{Hooks}.
2556: 
2557: @node Find Init
2558: @subsection How Emacs Finds Your Init File
2559: 
2560:   Normally Emacs uses the environment variable @env{HOME}
2561: (@pxref{General Variables, HOME}) to find @file{.emacs}; that's what
2562: @samp{~} means in a file name.  If @file{.emacs} is not found inside
2563: @file{~/} (nor @file{.emacs.el}), Emacs looks for
2564: @file{~/.emacs.d/init.el} (which, like @file{~/.emacs.el}, can be
2565: byte-compiled).
2566: 
2567:   However, if you run Emacs from a shell started by @code{su}, Emacs
2568: tries to find your own @file{.emacs}, not that of the user you are
2569: currently pretending to be.  The idea is that you should get your own
2570: editor customizations even if you are running as the super user.
2571: 
2572:   More precisely, Emacs first determines which user's init file to use.
2573: It gets your user name from the environment variables @env{LOGNAME} and
2574: @env{USER}; if neither of those exists, it uses effective user-ID@.
2575: If that user name matches the real user-ID, then Emacs uses @env{HOME};
2576: otherwise, it looks up the home directory corresponding to that user
2577: name in the system's data base of users.
2578: @c  LocalWords:  backtab
2579: 
2580: @node Init Non-ASCII
2581: @subsection Non-@acronym{ASCII} Characters in Init Files
2582: @cindex international characters in @file{.emacs}
2583: @cindex non-@acronym{ASCII} characters in @file{.emacs}
2584: @cindex non-@acronym{ASCII} keys, binding
2585: @cindex rebinding non-@acronym{ASCII} keys
2586: 
2587:   Language and coding systems may cause problems if your init file
2588: contains non-@acronym{ASCII} characters, such as accented letters, in
2589: strings or key bindings.
2590: 
2591:   If you want to use non-@acronym{ASCII} characters in your init file,
2592: you should put a @w{@samp{-*-coding: @var{coding-system}-*-}} tag on
2593: the first line of the init file, and specify a coding system that
2594: supports the character(s) in question.  @xref{Recognize Coding}.  This
2595: is because the defaults for decoding non-@acronym{ASCII} text might
2596: not yet be set up by the time Emacs reads those parts of your init
2597: file which use such strings, possibly leading Emacs to decode those
2598: strings incorrectly.  You should then avoid adding Emacs Lisp code
2599: that modifies the coding system in other ways, such as calls to
2600: @code{set-language-environment}.
2601: 
2602:   To bind non-@acronym{ASCII} keys, you must use a vector (@pxref{Init
2603: Rebinding}).  The string syntax cannot be used, since the
2604: non-@acronym{ASCII} characters will be interpreted as meta keys.  For
2605: instance:
2606: 
2607: @example
2608: (global-set-key [?@var{char}] 'some-function)
2609: @end example
2610: 
2611: @noindent
2612: Type @kbd{C-q}, followed by the key you want to bind, to insert @var{char}.
2613: 
2614: @node Early Init File
2615: @subsection The Early Init File
2616: @cindex early init file
2617: 
2618:   Most customizations for Emacs should be put in the normal init file,
2619: @file{.emacs} or @file{~/.emacs.d/init.el}.  However, it is sometimes desirable
2620: to have customizations that take effect during Emacs startup earlier than the
2621: normal init file is processed.  Such customizations can be put in the early
2622: init file, @file{~/.emacs.d/early-init.el}.  This file is loaded before the
2623: package system and GUI is initialized, so in it you can customize variables
2624: that affect frame appearance as well as the package initialization process,
2625: such as @code{package-enable-at-startup}, @code{package-load-list}, and
2626: @code{package-user-dir}.  Note that variables like @code{package-archives}
2627: which only affect the installation of new packages, and not the process of
2628: making already-installed packages available, may be customized in the regular
2629: init file.  @xref{Package Installation}.
2630: 
2631:   We do not recommend that you move into @file{early-init.el}
2632: customizations that can be left in the normal init files.  That is
2633: because the early init file is read before the GUI is initialized, so
2634: customizations related to GUI features will not work reliably in
2635: @file{early-init.el}.  By contrast, the normal init files are read
2636: after the GUI is initialized.  If you must have customizations in the
2637: early init file that rely on GUI features, make them run off hooks
2638: provided by the Emacs startup, such as @code{window-setup-hook} or
2639: @code{tty-setup-hook}.  @xref{Hooks}.
2640: 
2641:   For more information on the early init file, @pxref{Init File,,,
2642: elisp, The Emacs Lisp Reference Manual}.
2643: