X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/177c0ea74342272645959b82cf219faa0b3dba16..b6c735af3fd1b762b75ceb101b5ff50b4e9a6179:/man/custom.texi diff --git a/man/custom.texi b/man/custom.texi index 6d80368388..bbde8b4aaf 100644 --- a/man/custom.texi +++ b/man/custom.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985,86,87,93,94,95,97,2000,2001,2002 +@c Copyright (C) 1985,86,87,93,94,95,97,2000,2001,2002,2004 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Customization, Quitting, Amusements, Top @@ -12,22 +12,26 @@ Manual} for how to make more far-reaching changes. @xref{X Resources}, for information on using X resources to customize Emacs. Customization that you do within Emacs normally affects only the -particular Emacs session that you do it in--it does not persist +particular Emacs session that you do it in---it does not persist between sessions unless you save the customization in a file such as @file{.emacs} or @file{.Xdefaults} that will affect future sessions. @xref{Init File}. In the customization buffer, when you save customizations for future sessions, this actually works by editing @file{.emacs} for you. + Another means of customization is the keyboard macro, which is a +sequence of keystrokes to be replayed with a single command. +@xref{Keyboard Macros}, for full instruction how to record, manage, and +replay sequences of keys. + @menu * Minor Modes:: Each minor mode is one feature you can turn on independently of any others. +* Easy Customization:: + Convenient way to browse and change user options. * Variables:: Many Emacs commands examine Emacs variables to decide what to do; by setting variables, you can control their functioning. -* Keyboard Macros:: A keyboard macro records a sequence of - keystrokes to be replayed with a single - command. * Key Bindings:: The keymaps say what command each key runs. By changing them, you can "redefine keys". * Keyboard Translations:: @@ -169,132 +173,28 @@ explicitly ``reactivate'' it, before each command that uses the region. The advantage of Transient Mark mode is that Emacs can display the region highlighted (currently only when using X). @xref{Mark}. -@node Variables -@section Variables -@cindex variable -@cindex option, user -@cindex user option - - A @dfn{variable} is a Lisp symbol which has a value. The symbol's -name is also called the name of the variable. A variable name can -contain any characters that can appear in a file, but conventionally -variable names consist of words separated by hyphens. A variable can -have a documentation string which describes what kind of value it should -have and how the value will be used. - - Lisp allows any variable to have any kind of value, but most variables -that Emacs uses require a value of a certain type. Often the value should -always be a string, or should always be a number. Sometimes we say that a -certain feature is turned on if a variable is ``non-@code{nil},'' meaning -that if the variable's value is @code{nil}, the feature is off, but the -feature is on for @emph{any} other value. The conventional value to use to -turn on the feature---since you have to pick one particular value when you -set the variable---is @code{t}. - - Emacs uses many Lisp variables for internal record keeping, as any -Lisp program must, but the most interesting variables for you are the -ones that exist for the sake of customization. Emacs does not (usually) -change the values of these variables; instead, you set the values, and -thereby alter and control the behavior of certain Emacs commands. These -variables are called @dfn{user options}. Most user options are -documented in this manual, and appear in the Variable Index -(@pxref{Variable Index}). - - One example of a variable which is a user option is @code{fill-column}, which -specifies the position of the right margin (as a number of characters from -the left margin) to be used by the fill commands (@pxref{Filling}). - -@menu -* Examining:: Examining or setting one variable's value. -* Easy Customization:: - Convenient and easy customization of variables. -* Hooks:: Hook variables let you specify programs for parts - of Emacs to run on particular occasions. -* Locals:: Per-buffer values of variables. -* File Variables:: How files can specify variable values. -@end menu - -@node Examining -@subsection Examining and Setting Variables -@cindex setting variables - -@table @kbd -@item C-h v @var{var} @key{RET} -Display the value and documentation of variable @var{var} -(@code{describe-variable}). -@item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET} -Change the value of variable @var{var} to @var{value}. -@end table - - To examine the value of a single variable, use @kbd{C-h v} -(@code{describe-variable}), which reads a variable name using the -minibuffer, with completion. It displays both the value and the -documentation of the variable. For example, - -@example -C-h v fill-column @key{RET} -@end example - -@noindent -displays something like this: - -@smallexample -fill-column's value is 70 - -Documentation: -*Column beyond which automatic line-wrapping should happen. -Automatically becomes buffer-local when set in any fashion. -@end smallexample - -@noindent -The star at the beginning of the documentation indicates that this -variable is a user option. @kbd{C-h v} is not restricted to user -options; it allows any variable name. - -@findex set-variable - The most convenient way to set a specific user option is with @kbd{M-x -set-variable}. This reads the variable name with the minibuffer (with -completion), and then reads a Lisp expression for the new value using -the minibuffer a second time. For example, - -@example -M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET} -@end example - -@noindent -sets @code{fill-column} to 75. - - @kbd{M-x set-variable} is limited to user option variables, but you can -set any variable with a Lisp expression, using the function @code{setq}. -Here is a @code{setq} expression to set @code{fill-column}: - -@example -(setq fill-column 75) -@end example - - To execute an expression like this one, go to the @samp{*scratch*} -buffer, type in the expression, and then type @kbd{C-j}. @xref{Lisp -Interaction}. - - Setting variables, like all means of customizing Emacs except where -otherwise stated, affects only the current Emacs session. - @node Easy Customization -@subsection Easy Customization Interface +@section Easy Customization Interface + +@cindex user option + Emacs has many @dfn{user options} which have values that you can set +in order to customize various commands. Most user options are +documented in this manual. Each user option is actually a Lisp +variable (@pxref{Variables}), so their names appear in the Variable +Index (@pxref{Variable Index}). @findex customize @cindex customization buffer - A convenient way to find the user option variables that you want to -change, and then change them, is with @kbd{M-x customize}. This -command creates a @dfn{customization buffer} with which you can browse -through the Emacs user options in a logically organized structure, -then edit and set their values. You can also use the customization -buffer to save settings permanently in your @file{~/.emacs} file -(@pxref{Init File}). - -The appearance of the example buffers in the following is typically -different under a window system where faces can be used to indicate the -active fields and other features. + You can browse interactively through the the user options and change +some of them using @kbd{M-x customize}. This command creates a +@dfn{customization buffer}, which offers commands to navigate through +a logically organized structure of the Emacs user options; you can +also use it to edit and set their values, and to save settings +permanently in your @file{~/.emacs} file (@pxref{Init File}). + + The appearance of the example buffers in this section is typically +different under a window system, since faces are then used to indicate +the active fields and other features. @menu * Groups: Customization Groups. @@ -307,7 +207,7 @@ active fields and other features. @end menu @node Customization Groups -@subsubsection Customization Groups +@subsection Customization Groups @cindex customization groups For customization purposes, user options are organized into @@ -387,7 +287,7 @@ that group and its contents, just that option, or just that face. This is the way to set values in it. @node Changing an Option -@subsubsection Changing an Option +@subsection Changing an Option Here is an example of what a user option looks like in the customization buffer: @@ -409,7 +309,7 @@ of the option: in the example above, it says you have not changed the option yet. The word @samp{[State]} at the beginning of this line is active; you can get a menu of various operations by invoking it with @kbd{Mouse-1} or @key{RET}. These operations are essential for -customizing the variable. +customizing the user option. The line after the @samp{[State]} line displays the beginning of the option's documentation string. If there are more lines of @@ -428,7 +328,7 @@ change to say that you have edited the value: @end smallexample @cindex setting option value - Editing the value does not actually set the option variable. To do + Editing the value does not actually set the option. To do that, you must @dfn{set} the option. To do this, invoke the word @samp{[State]} and choose @samp{Set for Current Session}. @@ -521,7 +421,7 @@ editable field, use @kbd{C-o} or @kbd{C-q C-j}. @dfn{saving} the value changes it for future sessions as well. To save the option, invoke @samp{[State]} and select the @samp{Save for Future Sessions} operation. This works by writing code so as to set -the option variable again each time you start Emacs (@pxref{Saving +the option again, each time you start Emacs (@pxref{Saving Customizations}). You can also restore the option to its standard value by invoking @@ -545,8 +445,8 @@ so that you will get the standard value in future Emacs sessions. @item Use Backup Value This sets the option to a previous value that was set in the -customization buffer in this session. If you customize a variable -and then reset the variable, which discards the customized value, +customization buffer in this session. If you customize an option +and then reset it, which discards the customized value, you can get the customized value back again with this operation. @end table @@ -581,29 +481,35 @@ reset---on each of the items in the buffer that could meaningfully be set, saved or reset. @node Saving Customizations -@subsubsection Saving Customizations +@subsection Saving Customizations @vindex custom-file The customization buffer normally saves customizations in @file{~/.emacs}. If you wish, you can save customizations in another file instead. To make this work, your @file{~/.emacs} should set -@code{custom-file} to the name of that file. Emacs loads the file -right after your @file{.emacs} if you did not load it already. For -example: +@code{custom-file} to the name of that file. Then you should load the +file by calling @code{load}. For example: @example -(setq custom-file "~/.emacs-custom") +(setq custom-file "~/.emacs-custom.el") +(load custom-file) @end example - The variable @code{custom-file} is useful if you want to have -different customizations for different Emacs versions: + You can also use @code{custom-file} to specify different +customization files for different Emacs versions, like this: @example -(if (< emacs-major-version 21) - ;; @r{Emacs 20 customization.} - (setq custom-file "~/.custom-20.el") - ;; @r{Emacs 21 customization.} - (setq custom-file "~/.custom-21.el")) +(cond ((< emacs-major-version 21) + ;; @r{Emacs 20 customization.} + (setq custom-file "~/.custom-20.el")) + ((and (= emacs-major-version 21) (< emacs-minor-version 4)) + ;; @r{Emacs 21 customization, before version 21.4.} + (setq custom-file "~/.custom-21.el")) + (t + ;; @r{Emacs version 21.4 or later.} + (setq custom-file "~/.custom-21.4.el"))) + +(load custom-file) @end example If Emacs was invoked with the @option{-q} or @option{--no-init-file} @@ -613,7 +519,7 @@ saving customizations from such a session would wipe out all the other customizations you might have on your init file. @node Face Customization -@subsubsection Customizing Faces +@subsection Customizing Faces @cindex customizing faces @cindex bold font @cindex italic font @@ -651,10 +557,15 @@ before the attribute name indicates whether the attribute is attribute by invoking that field. When the attribute is enabled, you can change the attribute value in the usual ways. - 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. + 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. Setting, saving and resetting a face work like the same operations for options (@pxref{Changing an Option}). @@ -674,7 +585,7 @@ you don't want to change that attribute. Type @samp{none} if you want to clear out the attribute. @node Specific Customization -@subsubsection Customizing Specific Items +@subsection Customizing Specific Items Instead of finding the options you want to change by moving down through the structure of groups, you can specify the particular option, @@ -702,7 +613,7 @@ have customized but not saved. @end table @findex customize-option - If you want to alter a particular user option variable with the + If you want to alter a particular user option with the customization buffer, and you know its name, you can use the command @kbd{M-x customize-option} and specify the option name. This sets up the customization buffer with just one option---the one that you asked @@ -717,7 +628,7 @@ on the character after point. @findex customize-group You can also set up the customization buffer with a specific group, using @kbd{M-x customize-group}. The immediate contents of the chosen -group, including option variables, faces, and other groups, all appear +group, including user options, faces, and other groups, all appear as well. However, these subgroups' own contents start out hidden. You can show their contents in the usual way, by invoking @samp{[Show]}. @@ -745,6 +656,111 @@ you can use two special commands to revisit your previous changes. Use saved. Use @kbd{M-x customize-customized} to look at the options and faces that you have set but not saved. +@node Variables +@section Variables +@cindex variable +@cindex option, user +@cindex user option + + A @dfn{variable} is a Lisp symbol which has a value. The symbol's +name is also called the name of the variable. A variable name can +contain any characters that can appear in a file, but conventionally +variable names consist of words separated by hyphens. A variable can +have a documentation string which describes what kind of value it should +have and how the value will be used. + + Lisp allows any variable to have any kind of value, but most variables +that Emacs uses need a value of a certain type. Often the value should +always be a string, or should always be a number. Sometimes we say that a +certain feature is turned on if a variable is ``non-@code{nil},'' meaning +that if the variable's value is @code{nil}, the feature is off, but the +feature is on for @emph{any} other value. The conventional value to use to +turn on the feature---since you have to pick one particular value when you +set the variable---is @code{t}. + + Emacs uses many Lisp variables for internal record keeping, but the +most interesting variables for a non-programmer user are the @dfn{user +options}, the variables that are meant for users to change. Each user +option that you can set with the customization buffer is, in fact, a +Lisp variable. Emacs does not (usually) change the values of these +variables; instead, you set the values, and thereby alter and control +the behavior of certain Emacs commands. Use of the customization +buffer is explained above; here we describe other aspects of Emacs +variables. + +@menu +* Examining:: Examining or setting one variable's value. +* Hooks:: Hook variables let you specify programs for parts + of Emacs to run on particular occasions. +* Locals:: Per-buffer values of variables. +* File Variables:: How files can specify variable values. +@end menu + +@node Examining +@subsection Examining and Setting Variables +@cindex setting variables + +@table @kbd +@item C-h v @var{var} @key{RET} +Display the value and documentation of variable @var{var} +(@code{describe-variable}). +@item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET} +Change the value of variable @var{var} to @var{value}. +@end table + + To examine the value of a single variable, use @kbd{C-h v} +(@code{describe-variable}), which reads a variable name using the +minibuffer, with completion. It displays both the value and the +documentation of the variable. For example, + +@example +C-h v fill-column @key{RET} +@end example + +@noindent +displays something like this: + +@smallexample +fill-column's value is 70 + +Documentation: +*Column beyond which automatic line-wrapping should happen. +Automatically becomes buffer-local when set in any fashion. +@end smallexample + +@noindent +The star at the beginning of the documentation indicates that this +variable is a user option. @kbd{C-h v} is not restricted to user +options; it allows any variable name. + +@findex set-variable + The most convenient way to set a specific user option is with @kbd{M-x +set-variable}. This reads the variable name with the minibuffer (with +completion), and then reads a Lisp expression for the new value using +the minibuffer a second time. For example, + +@example +M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET} +@end example + +@noindent +sets @code{fill-column} to 75. + + @kbd{M-x set-variable} is limited to user option variables, but you can +set any variable with a Lisp expression, using the function @code{setq}. +Here is a @code{setq} expression to set @code{fill-column}: + +@example +(setq fill-column 75) +@end example + + To execute an expression like this one, go to the @samp{*scratch*} +buffer, type in the expression, and then type @kbd{C-j}. @xref{Lisp +Interaction}. + + Setting variables, like all means of customizing Emacs except where +otherwise stated, affects only the current Emacs session. + @node Hooks @subsection Hooks @cindex hook @@ -783,11 +799,13 @@ 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. - The recommended way to add a hook function to a hook (either normal or -abnormal) is by calling @code{add-hook}. You can use any valid Lisp -function as the hook function, provided it can handle the proper number -of arguments (zero arguments, in the case of a normal hook). Of course, -not every Lisp function is @emph{useful} in any particular 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}. You can +specify any valid Lisp function as the hook function, provided it can +handle the proper number of arguments (zero arguments, in the case of +a normal hook). Of course, not every Lisp function is @emph{useful} +in any particular hook. 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: @@ -828,6 +846,11 @@ 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. + If you play with adding various different versions of a hook +function by calling @code{add-hook} over and over, remember that all +the versions you added will remain in the hook variable together. +To clear them out, you can do @code{(setq @var{hook-variable} nil)}. + @node Locals @subsection Local Variables @@ -952,7 +975,8 @@ numeric values: You can also specify the coding system for a file in this way: just specify a value for the ``variable'' named @code{coding}. The ``value'' must be a coding system name that Emacs recognizes. @xref{Coding -Systems}. +Systems}. @w{@samp{unibyte: t}} specifies unibyte loading for a +particular Lisp file. @xref{Enabling Multibyte}. The @code{eval} pseudo-variable, described below, can be specified in the first line as well. @@ -996,25 +1020,44 @@ local variables list in a comment, so it won't confuse other programs that the file is intended as input for. The example above is for a language where comment lines start with @samp{;;; } and end with @samp{***}; the local values for @code{comment-start} and -@code{comment-end} customize the rest of Emacs for this unusual syntax. -Don't use a prefix (or a suffix) if you don't need one. - - Two ``variable names'' have special meanings in a local variables -list: a value for the variable @code{mode} really sets the major mode, -and a value for the variable @code{eval} is simply evaluated as an -expression and the value is ignored. @code{mode} and @code{eval} are -not real variables; setting variables named @code{mode} and @code{eval} -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 in the list of the local -variables are likely to be ignored, since most modes kill all local -variables as part of their initialization. - - You can use the @code{mode} ``variable'' to set minor modes as well as -major modes; in fact, you can use it more than once, first to set the -major mode and then to set minor modes which are specific to particular -buffers. But most minor modes should not be specified in the file in -any fashion, because they represent user preferences. +@code{comment-end} customize the rest of Emacs for this unusual +syntax. Don't use a prefix (or a suffix) if you don't need one. + + If you write a multi-line string value, you should put the prefix +and suffix on each line, even lines that start or end within the +string. They will be stripped off for processing the list. If you +want to split a long string across multiple lines of the file, you can +use backslash-newline, which is ignored in Lisp string constants. +Here's an example of doing this: + +@example +# Local Variables: +# compile-command: "cc foo.c -Dfoo=bar -Dhack=whatever \ +# -Dmumble=blaah" +# End: +@end example + + Some ``variable names'' have special meanings in a local variables +list. Specifying the ``variable'' @code{mode} really sets the major +mode, while any value specified for the ``variable'' @code{eval} is +simply evaluated as an expression (its value is ignored). A value for +@code{coding} specifies the coding system for character code +conversion of this file, and a value of @code{t} for @code{unibyte} +says to visit the file in a unibyte buffer. These four ``variables'' +are not really variables; setting them in any other context has no +special meaning. + + @emph{If @code{mode} is used to set a major mode, it should be the +first ``variable'' in the list.} Otherwise, the entries that precede +it will usually be ignored, since most modes kill all local variables +as part of their initialization. + + You can use the @code{mode} ``variable'' to set minor modes as well +as the major modes; in fact, you can use it more than once, first to +set the major mode and then to set minor modes which are specific to +particular buffers. But most minor modes should not be specified in +the file at all, regardless of how, because they represent user +preferences. For example, you may be tempted to try to turn on Auto Fill mode with a local variable list. That is a mistake. The choice of Auto Fill mode @@ -1058,230 +1101,11 @@ value are @code{t}, @code{nil}, and anything else, just as for neither @code{t} nor @code{nil}, so normally Emacs does ask for confirmation about file settings for these variables. -@node Keyboard Macros -@section Keyboard Macros - -@cindex defining keyboard macros -@cindex keyboard macro - A @dfn{keyboard macro} is a command defined by the user to stand for -another sequence of keys. For example, if you discover that you are -about to type @kbd{C-n C-d} forty times, you can speed your work by -defining a keyboard macro to do @kbd{C-n C-d} and calling it with a -repeat count of forty. - -@table @kbd -@item C-x ( -Start defining a keyboard macro (@code{start-kbd-macro}). -@item C-x ) -End the definition of a keyboard macro (@code{end-kbd-macro}). -@item C-x e -Execute the most recent keyboard macro (@code{call-last-kbd-macro}). -@item C-u C-x ( -Re-execute last keyboard macro, then add more keys to its definition. -@item C-x q -When this point is reached during macro execution, ask for confirmation -(@code{kbd-macro-query}). -@item M-x name-last-kbd-macro -Give a command name (for the duration of the session) to the most -recently defined keyboard macro. -@item M-x insert-kbd-macro -Insert in the buffer a keyboard macro's definition, as Lisp code. -@item C-x C-k -Edit a previously defined keyboard macro (@code{edit-kbd-macro}). -@item M-x apply-macro-to-region-lines -Run the last keyboard macro on each complete line in the region. -@end table - - Keyboard macros differ from ordinary Emacs commands in that they are -written in the Emacs command language rather than in Lisp. This makes it -easier for the novice to write them, and makes them more convenient as -temporary hacks. However, the Emacs command language is not powerful -enough as a programming language to be useful for writing anything -intelligent or general. For such things, Lisp must be used. - - You define a keyboard macro while executing the commands which are the -definition. Put differently, as you define a keyboard macro, the -definition is being executed for the first time. This way, you can see -what the effects of your commands are, so that you don't have to figure -them out in your head. When you are finished, the keyboard macro is -defined and also has been, in effect, executed once. You can then do the -whole thing over again by invoking the macro. - -@menu -* Basic Kbd Macro:: Defining and running keyboard macros. -* Save Kbd Macro:: Giving keyboard macros names; saving them in files. -* Kbd Macro Query:: Making keyboard macros do different things each time. -@end menu - -@node Basic Kbd Macro -@subsection Basic Use - -@kindex C-x ( -@kindex C-x ) -@kindex C-x e -@findex start-kbd-macro -@findex end-kbd-macro -@findex call-last-kbd-macro - To start defining a keyboard macro, type the @kbd{C-x (} command -(@code{start-kbd-macro}). From then on, your keys continue to be -executed, but also become part of the definition of the macro. @samp{Def} -appears in the mode line to remind you of what is going on. When you are -finished, the @kbd{C-x )} command (@code{end-kbd-macro}) terminates the -definition (without becoming part of it!). For example, - -@example -C-x ( M-f foo C-x ) -@end example - -@noindent -defines a macro to move forward a word and then insert @samp{foo}. - - The macro thus defined can be invoked again with the @kbd{C-x e} -command (@code{call-last-kbd-macro}), which may be given a repeat count -as a numeric argument to execute the macro many times. @kbd{C-x )} can -also be given a repeat count as an argument, in which case it repeats -the macro that many times right after defining it, but defining the -macro counts as the first repetition (since it is executed as you define -it). Therefore, giving @kbd{C-x )} an argument of 4 executes the macro -immediately 3 additional times. An argument of zero to @kbd{C-x e} or -@kbd{C-x )} means repeat the macro indefinitely (until it gets an error -or you type @kbd{C-g} or, on MS-DOS, @kbd{C-@key{BREAK}}). - - If you wish to repeat an operation at regularly spaced places in the -text, define a macro and include as part of the macro the commands to move -to the next place you want to use it. For example, if you want to change -each line, you should position point at the start of a line, and define a -macro to change that line and leave point at the start of the next line. -Then repeating the macro will operate on successive lines. - - When a command reads an argument with the minibuffer, your -minibuffer input becomes part of the macro along with the command. So -when you replay the macro, the command gets the same argument as -when you entered the macro. For example, - -@example -C-x ( C-a C-@key{SPC} C-n M-w C-x b f o o @key{RET} C-y C-x b @key{RET} C-x ) -@end example - -@noindent -defines a macro that copies the current line into the buffer -@samp{foo}, then returns to the original buffer. - - You can use function keys in a keyboard macro, just like keyboard -keys. You can even use mouse events, but be careful about that: when -the macro replays the mouse event, it uses the original mouse position -of that event, the position that the mouse had while you were defining -the macro. The effect of this may be hard to predict. (Using the -current mouse position would be even less predictable.) - - One thing that doesn't always work well in a keyboard macro is the -command @kbd{C-M-c} (@code{exit-recursive-edit}). When this command -exits a recursive edit that started within the macro, it works as you'd -expect. But if it exits a recursive edit that started before you -invoked the keyboard macro, it also necessarily exits the keyboard macro -as part of the process. - - After you have terminated the definition of a keyboard macro, you can add -to the end of its definition by typing @kbd{C-u C-x (}. This is equivalent -to plain @kbd{C-x (} followed by retyping the whole definition so far. As -a consequence it re-executes the macro as previously defined. - -@findex edit-kbd-macro -@kindex C-x C-k - You can edit a keyboard macro already defined by typing @kbd{C-x C-k} -(@code{edit-kbd-macro}). Follow that with the keyboard input that you -would use to invoke the macro---@kbd{C-x e} or @kbd{M-x @var{name}} or -some other key sequence. This formats the macro definition in a buffer -and enters a specialized major mode for editing it. Type @kbd{C-h m} -once in that buffer to display details of how to edit the macro. When -you are finished editing, type @kbd{C-c C-c}. - -@findex apply-macro-to-region-lines - The command @kbd{M-x apply-macro-to-region-lines} repeats the last -defined keyboard macro on each complete line within the current region. -It does this line by line, by moving point to the beginning of the line -and then executing the macro. - -@node Save Kbd Macro -@subsection Naming and Saving Keyboard Macros - -@cindex saving keyboard macros -@findex name-last-kbd-macro - If you wish to save a keyboard macro for longer than until you define the -next one, you must give it a name using @kbd{M-x name-last-kbd-macro}. -This reads a name as an argument using the minibuffer and defines that name -to execute the macro. The macro name is a Lisp symbol, and defining it in -this way makes it a valid command name for calling with @kbd{M-x} or for -binding a key to with @code{global-set-key} (@pxref{Keymaps}). If you -specify a name that has a prior definition other than another keyboard -macro, an error message is shown and nothing is changed. - -@findex insert-kbd-macro - Once a macro has a command name, you can save its definition in a file. -Then it can be used in another editing session. First, visit the file -you want to save the definition in. Then use this command: - -@example -M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET} -@end example - -@noindent -This inserts some Lisp code that, when executed later, will define the -same macro with the same definition it has now. (You need not -understand Lisp code to do this, because @code{insert-kbd-macro} writes -the Lisp code for you.) Then save the file. You can load the file -later with @code{load-file} (@pxref{Lisp Libraries}). If the file you -save in is your init file @file{~/.emacs} (@pxref{Init File}) then the -macro will be defined each time you run Emacs. - - If you give @code{insert-kbd-macro} a numeric argument, it makes -additional Lisp code to record the keys (if any) that you have bound to the -keyboard macro, so that the macro will be reassigned the same keys when you -load the file. - -@node Kbd Macro Query -@subsection Executing Macros with Variations - -@kindex C-x q -@findex kbd-macro-query - Using @kbd{C-x q} (@code{kbd-macro-query}), you can get an effect -similar to that of @code{query-replace}, where the macro asks you each -time around whether to make a change. While defining the macro, -type @kbd{C-x q} at the point where you want the query to occur. During -macro definition, the @kbd{C-x q} does nothing, but when you run the -macro later, @kbd{C-x q} asks you interactively whether to continue. - - The valid responses when @kbd{C-x q} asks are @key{SPC} (or @kbd{y}), -@key{DEL} (or @kbd{n}), @key{RET} (or @kbd{q}), @kbd{C-l} and @kbd{C-r}. -The answers are the same as in @code{query-replace}, though not all of -the @code{query-replace} options are meaningful. - - These responses include @key{SPC} to continue, and @key{DEL} to skip -the remainder of this repetition of the macro and start right away with -the next repetition. @key{RET} means to skip the remainder of this -repetition and cancel further repetitions. @kbd{C-l} redraws the screen -and asks you again for a character to say what to do. - - @kbd{C-r} enters a recursive editing level, in which you can perform -editing which is not part of the macro. When you exit the recursive -edit using @kbd{C-M-c}, you are asked again how to continue with the -keyboard macro. If you type a @key{SPC} at this time, the rest of the -macro definition is executed. It is up to you to leave point and the -text in a state such that the rest of the macro will do what you -want.@refill - - @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument, -performs a completely different function. It enters a recursive edit -reading input from the keyboard, both when you type it during the -definition of the macro, and when it is executed from the macro. During -definition, the editing you do inside the recursive edit does not become -part of the macro. During macro execution, the recursive edit gives you -a chance to do some particularized editing on each repetition. -@xref{Recursive Edit}. - - Another way to vary the behavior of a keyboard macro is to use a -register as a counter, incrementing it on each repetition of the macro. -@xref{RegNumbers}. +@findex safe-local-eval-forms + The @code{safe-local-eval-forms} is a customizable list of eval +forms which are safe to eval, so Emacs should not ask for +confirmation to evaluate these forms, even if +@code{enable-local-variables} says to ask for confirmation in general. @node Key Bindings @section Customizing Key Bindings @@ -1304,7 +1128,7 @@ name which usually consists of lower-case letters and hyphens. * Init Rebinding:: Rebinding keys with your init file, @file{.emacs}. * Function Keys:: Rebinding terminal function keys. * Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on. -* Non-ASCII Rebinding:: Rebinding non-ASCII characters such as Latin-1. +* Non-ASCII Rebinding:: Rebinding non-@acronym{ASCII} characters such as Latin-1. * Mouse Buttons:: Rebinding mouse buttons in Emacs. * Disabling:: Disabling a command means confirmation is required before it can be executed. This is done to protect @@ -1628,8 +1452,8 @@ command is less work to invoke when you really want to. you can specify them in your @file{.emacs} file by using their Lisp syntax. (@xref{Init File}.) - The simplest method for doing this works for ASCII characters and -Meta-modified ASCII characters only. This method uses a string to + The simplest method for doing this works for @acronym{ASCII} characters and +Meta-modified @acronym{ASCII} characters only. This method uses a string to represent the key sequence you want to rebind. For example, here's how to bind @kbd{C-z} to @code{shell}: @@ -1659,7 +1483,7 @@ string, you can use the Emacs Lisp escape sequences, @samp{\t}, (global-set-key "\C-x\t" 'indent-rigidly) @end example - These examples show how to write some other special ASCII characters + These examples show how to write some other special @acronym{ASCII} characters in strings for key bindings: @example @@ -1669,7 +1493,7 @@ in strings for key bindings: @end example When the key sequence includes function keys or mouse button events, -or non-ASCII characters such as @code{C-=} or @code{H-a}, you must use +or non-@acronym{ASCII} characters such as @code{C-=} or @code{H-a}, you must use the more general method of rebinding, which uses a vector to specify the key sequence. @@ -1681,8 +1505,8 @@ character, write it as a Lisp character constant: @samp{?} followed by the character as it would appear in a string. Here are examples of using vectors to rebind @kbd{C-=} (a control -character not in ASCII), @kbd{C-M-=} (not in ASCII because @kbd{C-=} -is not), @kbd{H-a} (a Hyper character; ASCII doesn't have Hyper at +character not in @acronym{ASCII}), @kbd{C-M-=} (not in @acronym{ASCII} because @kbd{C-=} +is not), @kbd{H-a} (a Hyper character; @acronym{ASCII} doesn't have Hyper at all), @key{F7} (a function key), and @kbd{C-Mouse-1} (a keyboard-modified mouse button): @@ -1712,6 +1536,9 @@ As you see, you represent a multi-character key sequence with a vector by listing each of the characters within the square brackets that delimit the vector. + Language and coding systems can cause problems with key bindings +for non-@acronym{ASCII} characters. @xref{Non-ASCII Rebinding}. + @node Function Keys @subsection Rebinding Function Keys @@ -1755,7 +1582,7 @@ given function key on your terminal, type @kbd{C-h c} followed by that key. A key sequence which contains function key symbols (or anything but -ASCII characters) must be a vector rather than a string. The vector +@acronym{ASCII} characters) must be a vector rather than a string. The vector syntax uses spaces between the elements, and square brackets around the whole vector. Thus, to bind function key @samp{f1} to the command @code{rmail}, write the following: @@ -1803,10 +1630,10 @@ word: @end example @node Named ASCII Chars -@subsection Named ASCII Control Characters +@subsection Named @acronym{ASCII} Control Characters @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC} and @key{DEL} -started out as names for certain ASCII control characters, used so often +started out as names for certain @acronym{ASCII} control characters, used so often that they have special keys of their own. Later, users found it convenient to distinguish in Emacs between these keys and the ``same'' control characters typed with the @key{CTRL} key. @@ -1815,32 +1642,31 @@ control characters typed with the @key{CTRL} key. reports these keys to Emacs. It treats the ``special'' keys as function keys named @code{tab}, @code{return}, @code{backspace}, @code{linefeed}, @code{escape}, and @code{delete}. These function keys translate -automatically into the corresponding ASCII characters @emph{if} they +automatically into the corresponding @acronym{ASCII} characters @emph{if} they have no bindings of their own. As a result, neither users nor Lisp programs need to pay attention to the distinction unless they care to. If you do not want to distinguish between (for example) @key{TAB} and -@kbd{C-i}, make just one binding, for the ASCII character @key{TAB} +@kbd{C-i}, make just one binding, for the @acronym{ASCII} character @key{TAB} (octal code 011). If you do want to distinguish, make one binding for -this ASCII character, and another for the ``function key'' @code{tab}. +this @acronym{ASCII} character, and another for the ``function key'' @code{tab}. - With an ordinary ASCII terminal, there is no way to distinguish + With an ordinary @acronym{ASCII} terminal, there is no way to distinguish between @key{TAB} and @kbd{C-i} (and likewise for other such pairs), because the terminal sends the same character in both cases. @node Non-ASCII Rebinding -@subsection Non-ASCII Characters on the Keyboard -@cindex rebinding non-ASCII keys -@cindex non-ASCII keys, binding - -If your keyboard has keys that send non-ASCII characters, such as -accented letters, rebinding these keys is a bit tricky. There are two -solutions you can use. One is to specify a keyboard coding system, -using @code{set-keyboard-coding-system} (@pxref{Specify Coding}). -Then you can bind these keys in the usual way@footnote{Note that you -should avoid the string syntax for binding 8-bit characters, since -they will be interpreted as meta keys. @xref{Strings of -Events,,,elisp, The Emacs Lisp Reference Manual}.}, like this: +@subsection Non-@acronym{ASCII} Characters on the Keyboard +@cindex rebinding non-@acronym{ASCII} keys +@cindex non-@acronym{ASCII} keys, binding + +If your keyboard has keys that send non-@acronym{ASCII} +characters, such as accented letters, rebinding these keys +must be done by using a vector like this@footnote{Note that +you should avoid the string syntax for binding +non-@acronym{ASCII} characters, since they will be +interpreted as meta keys. @xref{Strings of Events,,,elisp, +The Emacs Lisp Reference Manual}.}: @example (global-set-key [?@var{char}] 'some-function) @@ -1849,25 +1675,15 @@ Events,,,elisp, The Emacs Lisp Reference Manual}.}, like this: @noindent Type @kbd{C-q} followed by the key you want to bind, to insert @var{char}. -If you don't specify the keyboard coding system, that approach won't -work. Instead, you need to find out the actual code that the terminal -sends. The easiest way to do this in Emacs is to create an empty buffer -with @kbd{C-x b temp @key{RET}}, make it unibyte with @kbd{M-x -toggle-enable-multibyte-characters @key{RET}}, then type the key to -insert the character into this buffer. - -Move point before the character, then type @kbd{C-x =}. This -displays a message in the minibuffer, showing the character code in -three ways, octal, decimal and hexadecimal, all within a set of -parentheses. Use the second of the three numbers, the decimal one, -inside the vector to bind: - -@example -(global-set-key [@var{decimal-code}] 'some-function) -@end example +Since this puts a non-@acronym{ASCII} character in the @file{.emacs}, +you should specify a coding system for that file that supports the +character in question. @xref{Init Syntax}. -If you bind 8-bit characters like this in your init file, you may find it -convenient to specify that it is unibyte. @xref{Enabling Multibyte}. +@strong{Warning:} if you change the keyboard encoding, or change +between multibyte and unibyte mode, or anything that would alter which +code @kbd{C-q} would insert for that character, you'll need to edit +the Lisp expression accordingly, to use the character code generated +by @kbd{C-q} in the new mode. @node Mouse Buttons @subsection Rebinding Mouse Buttons @@ -2083,8 +1899,8 @@ input processing; the keys that are looked up in keymaps contain the characters that result from keyboard translation. On a window system, the keyboard key named @key{DELETE} is a function -key and is distinct from the ASCII character named @key{DEL}. -@xref{Named ASCII Chars}. Keyboard translations affect only ASCII +key and is distinct from the @acronym{ASCII} character named @key{DEL}. +@xref{Named ASCII Chars}. Keyboard translations affect only @acronym{ASCII} character input, not function keys; thus, the above example used on a window system does not affect the @key{DELETE} key. However, the translation above isn't necessary on window systems, because Emacs can @@ -2137,7 +1953,7 @@ Reference Manual}. file your @dfn{init file} because it specifies how to initialize Emacs for you. You can use the command line switch @samp{-q} to prevent loading your init file, and @samp{-u} (or @samp{--user}) to specify a -different user's init file (@pxref{Entering Emacs}). +different user's init file (@pxref{Initial Options}). @cindex @file{default.el}, the default init file There can also be a @dfn{default init file}, which is the library @@ -2155,7 +1971,7 @@ loaded. @file{site-start.el}, if it exists. Like @file{default.el}, Emacs finds this file via the standard search path for Lisp libraries. Emacs loads this library before it loads your init file. To inhibit -loading of this library, use the option @samp{-no-site-file}. +loading of this library, use the option @samp{--no-site-file}. @xref{Initial Options}. You can place @file{default.el} and @file{site-start.el} in any of @@ -2193,9 +2009,20 @@ arguments, all surrounded by parentheses. For example, @code{(setq fill-column 60)} calls the function @code{setq} to set the variable @code{fill-column} (@pxref{Filling}) to 60. - The second argument to @code{setq} is an expression for the new value of -the variable. This can be a constant, a variable, or a function call -expression. In @file{.emacs}, constants are used most of the time. They can be: + You can set any Lisp variable with @code{setq}, but with certain +variables @code{setq} won't do what you probably want in the +@file{.emacs} file. Some variables automatically become buffer-local +when set with @code{setq}; what you want in @file{.emacs} is to set +the default value, using @code{setq-default}. Some customizable minor +mode variables do special things to enable the mode when you set them +with Customize, but ordinary @code{setq} won't do that; to enable the +mode in your @file{.emacs} file, call the minor mode command. The +following section has examples of both of these methods. + + The second argument to @code{setq} is an expression for the new +value of the variable. This can be a constant, a variable, or a +function call expression. In @file{.emacs}, constants are used most +of the time. They can be: @table @asis @item Numbers: @@ -2217,17 +2044,17 @@ Backslash and double-quote are the only characters for which backslash sequences are mandatory. @samp{\C-} can be used as a prefix for a control character, as in -@samp{\C-s} for ASCII control-S, and @samp{\M-} can be used as a prefix for +@samp{\C-s} for @acronym{ASCII} control-S, and @samp{\M-} can be used as a prefix for a Meta character, as in @samp{\M-a} for @kbd{Meta-A} or @samp{\M-\C-a} for @kbd{Control-Meta-A}.@refill @cindex international characters in @file{.emacs} -@cindex non-ASCII characters in @file{.emacs} -If you want to include non-ASCII characters in strings in your init +@cindex non-@acronym{ASCII} characters in @file{.emacs} +If you want to include non-@acronym{ASCII} characters in strings in your init file, you should consider putting a @w{@samp{-*-coding: @var{coding-system}-*-}} tag on the first line which states the coding system used to save your @file{.emacs}, as explained in @ref{Recognize -Coding}. This is because the defaults for decoding non-ASCII text might +Coding}. This is because the defaults for decoding non-@acronym{ASCII} text might not yet be set up by the time Emacs reads those parts of your init file which use such strings, possibly leading Emacs to decode those strings incorrectly. @@ -2240,7 +2067,7 @@ strings and characters are not interchangeable in Lisp; some contexts require one and some contexts require the other. @xref{Non-ASCII Rebinding}, for information about binding commands to -keys which send non-ASCII characters. +keys which send non-@acronym{ASCII} characters. @item True: @code{t} stands for `true'. @@ -2315,6 +2142,14 @@ which supports most of the languages of Western Europe. (set-language-environment "Latin-1") @end example +@need 1500 +@item +Turn off Line Number mode, a global minor mode. + +@example +(line-number-mode 0) +@end example + @need 1500 @item Turn on Auto Fill mode automatically in Text mode and related modes. @@ -2502,3 +2337,7 @@ If that user name matches the real user-ID, then Emacs uses @env{HOME}; otherwise, it looks up the home directory corresponding to that user name in the system's data base of users. @c LocalWords: backtab + +@ignore + arch-tag: c68abddb-4410-4fb5-925f-63394e971d93 +@end ignore