X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/a3e44e793796153ff1534be9c74fcab50b45de30..291d142b33ae732328c61c89e3680f63266d073a:/doc/emacs/custom.texi diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index 031ea8f5e7..fd680576b4 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -1,9 +1,8 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. -@node Customization, Quitting, Amusements, Top +@node Customization @chapter Customization @cindex customization @@ -24,169 +23,16 @@ Reference Manual}. @end ifnottex @menu -* Minor Modes:: Each minor mode is a feature you can turn on - independently of any others. * Easy Customization:: Convenient way to browse and change settings. * Variables:: Many Emacs commands examine Emacs variables to decide what to do; by setting variables, you can control their functioning. * Key Bindings:: The keymaps say what command each key runs. By changing them, you can "redefine keys". -* Syntax:: The syntax table controls how words and - expressions are parsed. * Init File:: How to write common customizations in the @file{.emacs} file. @end menu -@node Minor Modes -@section Minor Modes -@cindex minor modes -@cindex mode, minor - - Minor modes are optional features which you can turn on or off. For -example, Auto Fill mode is a minor mode in which @key{SPC} breaks -lines between words as you type. Minor modes are independent of one -another and of the selected major mode. Most minor modes say in the -mode line when they are enabled; for example, @samp{Fill} in the mode -line means that Auto Fill mode is enabled. - - Each minor mode is associated with a command, called the @dfn{mode -command}, which turns it on or off. The name of this command consists -of the name of the minor mode, followed by @samp{-mode}; for instance, -the mode command for Auto Fill mode is @code{auto-fill-mode}. Calling -the minor mode command with no prefix argument @dfn{toggles} the mode, -turning it on if it was off, and off if it was on. A positive -argument always turns the mode on, and a zero or negative argument -always turns it off. Mode commands are usually invoked with -@kbd{M-x}, but you can bind keys to them if you wish (@pxref{Key -Bindings}). - - Most minor modes also have a @dfn{mode variable}, with the same name -as the mode command. Its value is non-@code{nil} if the mode is -enabled, and @code{nil} if it is disabled. In some minor modes---but -not all---the value of the variable alone determines whether the mode -is active: the mode command works simply by setting the variable, and -changing the value of the variable has the same effect as calling the -mode command. Because not all minor modes work this way, we recommend -that you avoid changing the mode variables directly; use the mode -commands instead. - - Some minor modes are @dfn{buffer-local}: they apply only to the -current buffer, so you can enable the mode in certain buffers and not -others. Other minor modes are @dfn{global}: while enabled, they -affect everything you do in the Emacs session, in all buffers. Some -global minor modes are enabled by default. - - The following is a list of some buffer-local minor modes: - -@itemize @bullet -@item -Abbrev mode automatically expands text based on pre-defined -abbreviation definitions. @xref{Abbrevs}. - -@item -Auto Fill mode inserts newlines as you type to prevent lines from -becoming too long. @xref{Filling}. - -@item -Auto Save mode saves the buffer contents periodically to reduce the -amount of work you can lose in case of a crash. @xref{Auto Save}. - -@item -Enriched mode enables editing and saving of formatted text. -@xref{Formatted Text}. - -@item -Flyspell mode automatically highlights misspelled words. -@xref{Spelling}. - -@item -Font-Lock mode automatically highlights certain textual units found in -programs. It is enabled globally by default, but you can disable it -in individual buffers. @xref{Faces}. - -@findex linum-mode -@cindex Linum mode -@item -Linum mode displays each line's line number in the window's left -margin. Its mode command is @code{linum-mode}. - -@item -Outline minor mode provides similar facilities to the major mode -called Outline mode. @xref{Outline Mode}. - -@cindex Overwrite mode -@cindex mode, Overwrite -@findex overwrite-mode -@kindex INSERT -@item -Overwrite mode causes ordinary printing characters to replace existing -text instead of shoving it to the right. For example, if point is in -front of the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing -a @kbd{G} changes it to @samp{FOOGAR}, instead of producing -@samp{FOOGBAR} as usual. In Overwrite mode, the command @kbd{C-q} -inserts the next character whatever it may be, even if it is a -digit---this gives you a way to insert a character instead of -replacing an existing character. The mode command, -@code{overwrite-mode}, is bound to the @key{Insert} key. - -@findex binary-overwrite-mode -@item -Binary Overwrite mode is a variant of Overwrite mode for editing -binary files; it treats newlines and tabs like other characters, so -that they overwrite other characters and can be overwritten by them. -In Binary Overwrite mode, digits after @kbd{C-q} specify an octal -character code, as usual. - -@item -Visual Line mode performs ``word wrapping'', causing long lines to be -wrapped at word boundaries. @xref{Visual Line Mode}. -@end itemize - - Here are some useful global minor modes. Since Line Number mode and -Transient Mark mode can be enabled or disabled just by setting the -value of the minor mode variable, you @emph{can} set them differently -for particular buffers, by explicitly making the corresponding -variable local in those buffers. @xref{Locals}. - -@itemize @bullet -@item -Column Number mode enables display of the current column number in the -mode line. @xref{Mode Line}. - -@item -Delete Selection mode causes text insertion to first delete the text -in the region, if the region is active. @xref{Using Region}. - -@item -Icomplete mode displays an indication of available completions when -you are in the minibuffer and completion is active. @xref{Completion -Options}. - -@item -Line Number mode enables display of the current line number in the -mode line. It is enabled by default. @xref{Mode Line}. - -@item -Menu Bar mode gives each frame a menu bar. It is enabled by default. -@xref{Menu Bars}. - -@item -Scroll Bar mode gives each window a scroll bar. It is enabled by -default, but the scroll bar is only displayed on graphical terminals. -@xref{Scroll Bars}. - -@item -Tool Bar mode gives each frame a tool bar. It is enabled by default, -but the tool bar is only displayed on graphical terminals. @xref{Tool -Bars}. - -@item -Transient Mark mode highlights the region, and makes many Emacs -commands operate on the region when the mark is active. It is enabled -by default. @xref{Mark}. -@end itemize - @node Easy Customization @section Easy Customization Interface @@ -527,7 +373,8 @@ files for different Emacs versions, like this: (cond ((< emacs-major-version 22) ;; @r{Emacs 21 customization.} (setq custom-file "~/.custom-21.el")) - ((and (= emacs-major-version 22) (< emacs-minor-version 3)) + ((and (= emacs-major-version 22) + (< emacs-minor-version 3)) ;; @r{Emacs 22 customization, before version 22.3.} (setq custom-file "~/.custom-22.el")) (t @@ -583,15 +430,15 @@ means that it's disabled. You can enable or disable the attribute by clicking that button. When the attribute is enabled, you can change the attribute value in the usual ways. - For the colors, you can specify a color name (use @kbd{M-x -list-colors-display} for a list of them) or a hexadecimal color -specification of the form @samp{#@var{rr}@var{gg}@var{bb}}. -(@samp{#000000} is black, @samp{#ff0000} is red, @samp{#00ff00} is -green, @samp{#0000ff} is blue, and @samp{#ffffff} is white.) On a -black-and-white display, the colors you can use for the background are -@samp{black}, @samp{white}, @samp{gray}, @samp{gray1}, and -@samp{gray3}. Emacs supports these shades of gray by using background -stipple patterns instead of a color. + You can specify a color name (use @kbd{M-x list-colors-display} for +a list of them) or a hexadecimal color specification of the form +@samp{#@var{rr}@var{gg}@var{bb}}. (@samp{#000000} is black, +@samp{#ff0000} is red, @samp{#00ff00} is green, @samp{#0000ff} is +blue, and @samp{#ffffff} is white.) On a black-and-white display, the +colors you can use for the background are @samp{black}, @samp{white}, +@samp{gray}, @samp{gray1}, and @samp{gray3}. Emacs supports these +shades of gray by using background stipple patterns instead of a +color. Setting, saving and resetting a face work like the same operations for variables (@pxref{Changing a Variable}). @@ -771,7 +618,7 @@ using the help command @kbd{C-h v} (@code{describe-variable}). most interesting variables for a non-programmer user are those meant for users to change---these are called @dfn{user options}. @xref{Easy Customization}, for information about using the Customize facility to -set user options. In the following sections, we describe will other +set user options. In the following sections, we will describe other aspects of Emacs variables, such as how to set them outside Customize. Emacs Lisp allows any variable (with a few exceptions) to have any @@ -888,53 +735,48 @@ your initialization file to set it those sessions (@pxref{Init File}). hook is a Lisp variable which holds a list of functions, to be called on some well-defined occasion. (This is called @dfn{running the hook}.) The individual functions in the list are called the @dfn{hook -functions} of the hook. With rare exceptions, hooks in Emacs are -empty when Emacs starts up, so the only hook functions in any given -hook are the ones you explicitly put there as customization. - - Most major modes run one or more @dfn{mode hooks} as the last step -of initialization. This makes it easy for you to customize the -behavior of the mode, by setting up a hook function to override the -local variable assignments already made by the mode. But hooks are -also used in other contexts. For example, the hook -@code{kill-emacs-hook} runs just before quitting the Emacs job -(@pxref{Exiting}). +functions} of the hook. For example, the hook @code{kill-emacs-hook} +runs just before exiting Emacs (@pxref{Exiting}). @cindex normal hook - Most Emacs hooks are @dfn{normal hooks}. This means that running the -hook operates by calling all the hook functions, unconditionally, with -no arguments. We have made an effort to keep most hooks normal so that -you can use them in a uniform way. Every variable in Emacs whose name -ends in @samp{-hook} is a normal hook. + Most hooks are @dfn{normal hooks}. This means that when Emacs runs +the hook, it calls each hook function in turn, with no arguments. We +have made an effort to keep most hooks normal, so that you can use +them in a uniform way. Every variable whose name ends in @samp{-hook} +is a normal hook. @cindex abnormal hook - There are also a few @dfn{abnormal hooks}. These variables' names end -in @samp{-hooks} or @samp{-functions}, instead of @samp{-hook}. What -makes these hooks abnormal is that there is something peculiar about the -way its functions are called---perhaps they are given arguments, or -perhaps the values they return are used in some way. For example, -@code{find-file-not-found-functions} (@pxref{Visiting}) is abnormal because -as soon as one hook function returns a non-@code{nil} value, the rest -are not called at all. The documentation of each abnormal hook variable -explains in detail what is peculiar about it. + A few hooks are @dfn{abnormal hooks}. Their names end in +@samp{-hooks} or @samp{-functions}, instead of @samp{-hook}. What +makes these hooks abnormal is the way its functions are +called---perhaps they are given arguments, or perhaps the values they +return are used in some way. For example, +@code{find-file-not-found-functions} is abnormal because as soon as +one hook function returns a non-@code{nil} value, the rest are not +called at all (@pxref{Visiting}). The documentation of each abnormal +hook variable explains how its functions are used. @findex add-hook You can set a hook variable with @code{setq} like any other Lisp -variable, but the recommended way to add a hook function to a hook -(either normal or abnormal) is by calling @code{add-hook}. -@xref{Hooks,,, elisp, The Emacs Lisp Reference Manual}. +variable, but the recommended way to add a function to a hook (either +normal or abnormal) is to use @code{add-hook}, as shown by the +following examples. @xref{Hooks,,, elisp, The Emacs Lisp Reference +Manual}, for details. - For example, here's how to set up a hook to turn on Auto Fill mode -when entering Text mode and other modes based on Text mode: + Most major modes run one or more @dfn{mode hooks} as the last step +of initialization. Mode hooks are a convenient way to customize the +behavior of individual modes; they are always normal. For example, +here's how to set up a hook to turn on Auto Fill mode when entering +Text mode and other modes based on Text mode: @example -(add-hook 'text-mode-hook 'turn-on-auto-fill) +(add-hook 'text-mode-hook 'auto-fill-mode) @end example - The next example shows how to use a hook to customize the indentation -of C code. (People often have strong personal preferences for one -format compared to another.) Here the hook function is an anonymous -lambda expression. + Here is another example, showing how to use a hook to customize the +indentation of C code. The hook function uses an anonymous lambda +expression (@pxref{Lambda Expressions,,, elisp, The Emacs Lisp +Reference Manual}). @example @group @@ -944,24 +786,32 @@ lambda expression. @group (c-cleanup-list . (scope-operator empty-defun-braces - defun-close-semi)) -@end group -@group - (c-offsets-alist . ((arglist-close . c-lineup-arglist) - (substatement-open . 0))))) + defun-close-semi)))) @end group @group (add-hook 'c-mode-common-hook - '(lambda () - (c-add-style "my-style" my-c-style t))) + (lambda () (c-add-style "my-style" my-c-style t))) @end group @end example +@cindex Prog mode +@cindex program editing + Major mode hooks also apply to other major modes @dfn{derived} from +the original mode (@pxref{Derived Modes,,, elisp, The Emacs Lisp +Reference Manual}). For instance, HTML mode (@pxref{HTML Mode}) +inherits from Text mode; when HTML mode is enabled, it runs +@code{text-mode-hook} before running @code{html-mode-hook}. This +provides a convenient way to use a single hook to affect several +related modes. In particular, if you want to apply a hook function to +any programming language mode, add it to @code{prog-mode-hook}; Prog +mode is a major mode that does little else than to let other major +modes inherit from it, exactly for this purpose. + It is best to design your hook functions so that the order in which they are executed does not matter. Any dependence on the order is -``asking for trouble.'' However, the order is predictable: the most -recently added hook functions are executed first. +asking for trouble. However, the order is predictable: the hook +functions are executed in the order they appear in the hook. @findex remove-hook If you play with adding various different versions of a hook @@ -970,6 +820,12 @@ the versions you added will remain in the hook variable together. You can clear out individual functions by calling @code{remove-hook}, or do @code{(setq @var{hook-variable} nil)} to remove everything. +@cindex buffer-local hooks + If the hook variable is buffer-local, the buffer-local variable will +be used instead of the global variable. However, if the buffer-local +variable contains the element @code{t}, the global hook variable will +be run as well. + @node Locals @subsection Local Variables @@ -1086,9 +942,8 @@ first line: You can specify any number of variable/value pairs in this way, each pair with a colon and semicolon as shown above. The special variable/value pair @code{mode: @var{modename};}, if present, -specifies a major or minor mode; if you use this to specify a major -mode, it should come first in the line. The @var{value}s are used -literally, and not evaluated. +specifies a major mode, and should come first in the line. The +@var{value}s are used literally, and not evaluated. @findex add-file-local-variable-prop-line @findex delete-file-local-variable-prop-line @@ -1131,7 +986,10 @@ the file is divided into pages. If a file has both a local variables list and a @samp{-*-} line, Emacs processes @emph{everything} in the @samp{-*-} line first, and -@emph{everything} in the local variables list afterward. +@emph{everything} in the local variables list afterward. The exception +to this is a major mode specification. Emacs applies this first, +wherever it appears, since most major modes kill all local variables as +part of their initialization. A local variables list starts with a line containing the string @samp{Local Variables:}, and ends with a line containing the string @@ -1187,7 +1045,7 @@ list: @itemize @item -@code{mode} enables the specified major or minor mode. +@code{mode} enables the specified major mode. @item @code{eval} evaluates the specified Lisp expression (the value @@ -1206,18 +1064,14 @@ value is @code{t}. @xref{Enabling Multibyte}. These four ``variables'' are not really variables; setting them in any other context has no special meaning. - @emph{If @code{mode} is used to set a major mode, it should be the -first ``variable'' in the list.} Otherwise, the entries that precede -it will usually have no effect, since most major modes kill all local -variables as part of their initialization. - You can use the @code{mode} ``variable'' to enable minor modes as well as the major modes; in fact, you can use it more than once, first to set the major mode and then to enable minor modes which are -specific to particular buffers. +specific to particular buffers. Using @code{mode} for minor modes +is deprecated, though---instead, use @code{eval: (minor-mode 1)}. - Often, however, it is a mistake to enable minor modes this way. -Most minor modes, like Auto Fill mode, represent individual user + Often, however, it is a mistake to enable minor modes in file local +variables. Most minor modes, like Auto Fill mode, represent individual user preferences. If you want to use a minor mode, it is better to set up major mode hooks with your init file to turn that minor mode on for yourself alone (@pxref{Init File}), instead of using a local variable @@ -1332,17 +1186,21 @@ corresponding alist applies to all the files in that subdirectory. (tab-width . 4) (fill-column . 80))) (c-mode . ((c-file-style . "BSD"))) - (java-mode . ((c-file-style . "BSD"))) + (java-mode . ((c-file-style . "BSD") + (subdirs . nil))) ("src/imported" - . ((nil . ((change-log-default-name . "ChangeLog.local")))))) + . ((nil . ((change-log-default-name . + "ChangeLog.local")))))) @end example @noindent This example shows some settings for a hypothetical project. It sets @samp{indent-tabs-mode}, @code{tab-width}, and @code{fill-column} for any file in the project's directory tree, and it sets the indentation -style for any C or Java source file. Finally, it specifies a different -@file{ChangeLog} file name for any file in the @file{src/imported} +style for any C or Java source file. The special @code{subdirs} element +indicates that the Java mode settings are only to be applied in the +current directory, not in any subdirectories. Finally, it specifies a +different @file{ChangeLog} file name for any file in the @file{src/imported} subdirectory of the directory where you put the @file{.dir-locals.el} file. @@ -1561,7 +1419,7 @@ just like @key{RET}. @code{minibuffer-local-must-match-map} is for strict completion and for cautious completion. @item -Finally, @code{minibuffer-local-filename-completion-map} and +@code{minibuffer-local-filename-completion-map} and @code{minibuffer-local-must-match-filename-map} are like the two previous ones, but they are specifically for file name completion. They do not bind @key{SPC}. @@ -1692,7 +1550,6 @@ and mouse events: (global-set-key (kbd "C-") 'linum-mode) (global-set-key (kbd "C-") 'forward-sentence) (global-set-key (kbd "") 'mouse-save-then-kill) -(global-set-key (kbd "C-") 'mouse-yank-at-click) @end example Instead of using the @code{kbd} macro, you can use a Lisp string or @@ -1756,8 +1613,10 @@ and @kbd{C-c p} in Texinfo mode: @example (add-hook 'texinfo-mode-hook '(lambda () - (define-key texinfo-mode-map "\C-cp" 'backward-paragraph) - (define-key texinfo-mode-map "\C-cn" 'forward-paragraph))) + (define-key texinfo-mode-map "\C-cp" + 'backward-paragraph) + (define-key texinfo-mode-map "\C-cn" + 'forward-paragraph))) @end example @node Modifier Keys @@ -1915,7 +1774,7 @@ button, @code{mouse-2} for the next, and so on. Here is how you can redefine the second mouse button to split the current window: @example -(global-set-key [mouse-2] 'split-window-vertically) +(global-set-key [mouse-2] 'split-window-below) @end example The symbols for drag events are similar, but have the prefix @@ -1995,10 +1854,10 @@ comes from a special area of the screen by means of dummy ``prefix keys.'' For example, if you click the mouse in the mode line, you get the prefix key @code{mode-line} before the ordinary mouse-button symbol. Thus, here is how to define the command for clicking the first button in -a mode line to run @code{scroll-up}: +a mode line to run @code{scroll-up-command}: @example -(global-set-key [mode-line mouse-1] 'scroll-up) +(global-set-key [mode-line mouse-1] 'scroll-up-command) @end example Here is the complete list of these dummy prefix keys and their @@ -2079,39 +1938,11 @@ invoke it; disabling also applies if the command is invoked using @kbd{M-x}. However, disabling a command has no effect on calling it as a function from Lisp programs. -@node Syntax -@section The Syntax Table -@cindex syntax table - - All the Emacs commands which parse words or balance parentheses are -controlled by the @dfn{syntax table}. The syntax table says which -characters are opening delimiters, which are parts of words, which are -string quotes, and so on. It does this by assigning each character to -one of fifteen-odd @dfn{syntax classes}. In some cases it specifies -some additional information also. - - Each major mode has its own syntax table (though related major modes -sometimes share one syntax table), which it installs in each buffer -that uses the mode. The syntax table installed in the current buffer -is the one that all commands use, so we call it ``the'' syntax table. - -@kindex C-h s -@findex describe-syntax - To display a description of the contents of the current syntax -table, type @kbd{C-h s} (@code{describe-syntax}). The description of -each character includes the string you would have to give to -@code{modify-syntax-entry} to set up that character's current syntax, -starting with the character which designates its syntax class, plus -some English text to explain its meaning. - - A syntax table is actually a Lisp object, a char-table, whose -elements are cons cells. For full information on the syntax table, -see @ref{Syntax Tables,, Syntax Tables, elisp, The Emacs Lisp -Reference Manual}. - @node Init File @section The Init File, @file{~/.emacs} @cindex init file +@cindex .emacs file +@cindex ~/.emacs file @cindex Emacs initialization file @cindex key rebinding, permanent @cindex rebinding keys, permanently @@ -2343,8 +2174,7 @@ Turn off Line Number mode, a global minor mode. Turn on Auto Fill mode automatically in Text mode and related modes. @example -(add-hook 'text-mode-hook - '(lambda () (auto-fill-mode 1))) +(add-hook 'text-mode-hook 'auto-fill-mode) @end example This shows how to add a hook function to a normal hook variable @@ -2352,19 +2182,9 @@ This shows how to add a hook function to a normal hook variable @code{lambda}, with a single-quote in front of it to make it a list constant rather than an expression. -It's beyond the scope of this manual to explain Lisp functions, but for -this example it is enough to know that the effect is to execute -@code{(auto-fill-mode 1)} when Text mode is entered. You can replace -that with any other expression that you like, or with several -expressions in a row. - -Emacs comes with a function named @code{turn-on-auto-fill} whose -definition is @code{(lambda () (auto-fill-mode 1))}. Thus, a simpler -way to write the above example is as follows: - -@example -(add-hook 'text-mode-hook 'turn-on-auto-fill) -@end example +It's beyond the scope of this manual to explain Lisp functions, but +for this example it is enough to know that the effect is to execute +the @code{auto-fill-mode} function when Text mode is entered. @item Load the installed Lisp library named @file{foo} (actually a file