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