@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.
+* 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.
@node Easy Customization
@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. Many user options are
-documented in this manual. Most user options are actually Lisp
-variables (@pxref{Variables}), so their names appear in the Variable
-Index (@pxref{Variable Index}). The rest are faces and their
-attributes (@pxref{Faces}).
+@cindex settings
+ Emacs has many @dfn{settings} which have values that you can specify
+in order to customize various commands. Many are documented in this
+manual. Most settings are @dfn{user options}---that is to say, Lisp
+variables (@pxref{Variables})---so their names appear in the Variable
+Index (@pxref{Variable Index}). The other settings are faces and
+their attributes (@pxref{Faces}).
@findex customize
@cindex customization buffer
- You can browse interactively through 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}).
+ You can browse interactively through settings and change 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 settings; 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.
+buttons and editable fields.
@menu
-* Groups: Customization Groups. How options are classified in a structure.
-* Browsing: Browsing Custom. Browsing and searching for options and faces.
-* Changing a Variable:: How to edit a value and set an option.
+* Groups: Customization Groups. How settings are classified in a structure.
+* Browsing: Browsing Custom. Browsing and searching for settings.
+* Changing a Variable:: How to edit an option's value and set the option.
* Saving Customizations:: Specifying the file for saving customizations.
* Face Customization:: How to edit the attributes of a face.
* Specific Customization:: Making a customization buffer for specific
@subsection Customization Groups
@cindex customization groups
- For customization purposes, user options are organized into
-@dfn{groups} to help you find them. Groups are collected into bigger
-groups, all the way up to a master group called @code{Emacs}.
+ For customization purposes, settings are organized into @dfn{groups}
+to help you find them. Groups are collected into bigger groups, all
+the way up to a master group called @code{Emacs}.
@kbd{M-x customize} creates a customization buffer that shows the
top-level @code{Emacs} group and the second-level groups immediately
line.
@cindex editable fields (customization buffer)
-@cindex active fields (customization buffer)
+@cindex buttons (customization buffer)
Most of the text in the customization buffer is read-only, but it
-typically includes some @dfn{editable fields} that you can edit. There
-are also @dfn{active fields}; this means a field that does something
-when you @dfn{invoke} it. To invoke an active field, either click on it
-with @kbd{Mouse-1}, or move point to it and type @key{RET}.
+typically includes some @dfn{editable fields} that you can edit.
+There are also @dfn{buttons}, which do something when you @dfn{invoke}
+them. To invoke a button, either click on it with @kbd{Mouse-1}, or
+move point to it and type @key{RET}.
For example, the phrase @samp{[Go to Group]} that appears in a
-second-level group is an active field. Invoking the @samp{[Go to
-Group]} field for a group creates a new customization buffer, which
-shows that group and its contents. This field is a kind of hypertext
-link to another group.
-
- The @code{Emacs} group includes a few user options itself, but
-mainly it contains other groups, which contain more groups, which
-contain the user options. By browsing the hierarchy of groups, you
-will eventually find the feature you are interested in customizing.
-Then you can use the customization buffer to set the options
-pertaining to that feature. You can also go straight to a particular
-group by name, using the command @kbd{M-x customize-group}.
+second-level group is a button. Invoking it creates a new
+customization buffer, which shows that group and its contents. This
+is a kind of hypertext link to another group.
+
+ The @code{Emacs} group includes a few settings, but mainly it
+contains other groups, which contain more groups, which contain the
+settings. By browsing the hierarchy of groups, you will eventually
+find the feature you are interested in customizing. Then you can use
+the customization buffer to set that feature's settings. You can also
+go straight to a particular group by name, using the command @kbd{M-x
+customize-group}.
@node Browsing Custom
@subsection Browsing and Searching for Options and Faces
@findex customize-browse
-You can use @kbd{M-x customize} to browse the groups and options, but
-often @kbd{M-x customize-browse} is a more efficient alternative.
-That is because it lets you view the structure of customization groups
-on a larger scale. This command creates a special kind of
-customization buffer which shows only the names of the groups (and
-variables and faces), and their structure.
+
+ @kbd{M-x customize-browse} is another way to browse the available
+settings. This command creates a special customization buffer which
+shows only the names of groups and settings, and puts them in a
+structure.
In this buffer, you can show the contents of a group by invoking
@samp{[+]}. When the group contents are visible, this button changes to
@samp{[-]}; invoking that hides the group contents.
- Each group, variable, or face name in this buffer has an active field
-which says @samp{[Group]}, @samp{[Option]} or @samp{[Face]}. Invoking
-that active field creates an ordinary customization buffer showing just
-that group and its contents, just that variable, or just that face.
-This is the way to set values in it.
+ Each setting in this buffer has a button which says @samp{[Group]},
+@samp{[Option]} or @samp{[Face]}. Invoking this button creates an
+ordinary customization buffer showing just that group and its
+contents, just that user option, or just that face. This is the way
+to change settings that you find with @kbd{M-x customize-browse}.
- If you can guess part of the name of the options you are interested
-in, then sometimes @kbd{M-x customize-apropos} can be another useful
-way to search for options. However, unlike @code{customize} and
-@code{customize-browse}, @code{customize-apropos} can only find
-options that are loaded in the current Emacs session. @xref{Specific
-Customization,, Customizing Specific Items}.
+ If you can guess part of the name of the settings you are interested
+in, @kbd{M-x customize-apropos} is another way to search for settings.
+However, unlike @code{customize} and @code{customize-browse},
+@code{customize-apropos} can only find groups and settings that are
+loaded in the current Emacs session. @xref{Specific Customization,,
+Customizing Specific Items}.
@node Changing a Variable
@subsection Changing a Variable
- Here is an example of what a variable looks like in the
-customization buffer:
+ Here is an example of what a variable (a user option) looks like in
+the customization buffer:
@smallexample
Kill Ring Max: [Hide Value] 60
buffer initially hides values that take up several lines. Invoke
@samp{[Show Value]} to show the value.
- The line after the option name indicates the @dfn{customization state}
-of the variable: 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.
+ The line after the variable name indicates the @dfn{customization
+state} of the variable: in the example above, it says you have not
+changed the option yet. The @samp{[State]} button at the beginning of
+this line gives you a menu of various operations for customizing the
+variable.
The line after the @samp{[State]} line displays the beginning of the
variable's documentation string. If there are more lines of
-documentation, this line ends with @samp{[More]}; invoke this to show
-the full documentation string.
-
- To enter a new value for @samp{Kill Ring Max}, move point to the value
-and edit it textually. For example, you can type @kbd{M-d}, then insert
-another number.
+documentation, this line ends with a @samp{[More]} button; invoke that
+to show the full documentation string.
- When you begin to alter the text, you will see the @samp{[State]} line
-change to say that you have edited the value:
+ To enter a new value for @samp{Kill Ring Max}, move point to the
+value and edit it textually. For example, you can type @kbd{M-d},
+then insert another number. As you begin to alter the text, you will
+see the @samp{[State]} line change to say that you have edited the
+value:
@smallexample
[State]: EDITED, shown value does not take effect until you set or @r{@dots{}}
save it.
@end smallexample
-@cindex setting option value
- Editing the value does not actually set the variable. To do
-that, you must @dfn{set} it. To do this, invoke the word
-@samp{[State]} and choose @samp{Set for Current Session}.
+@cindex settings, how to set
+ Editing the value does not actually set the variable. To do that,
+you must @dfn{set} the variable. To do this, invoke the
+@samp{[State]} button and choose @samp{Set for Current Session}.
The state of the variable changes visibly when you set it:
@end smallexample
You don't have to worry about specifying a value that is not valid;
-setting the variable checks for validity and will not really install an
-unacceptable value.
+the @samp{Set for Current Session} operation checks for validity and
+will not install an unacceptable value.
@kindex M-TAB @r{(customization buffer)}
@findex widget-complete
- While editing a value or field that is a file name, directory name,
+ While editing a field that is a file name, directory name,
command name, or anything else for which completion is defined, you
can type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion.
(@kbd{@key{ESC} @key{TAB}} and @kbd{C-M-i} do the same thing.)
Some variables have a small fixed set of possible legitimate values.
-These variables don't let you edit the value textually. Instead, an
-active field @samp{[Value Menu]} appears before the value; invoke this
-field to edit the value. For a boolean ``on or off'' value, the active
-field says @samp{[Toggle]}, and it changes to the other value.
-@samp{[Value Menu]} and @samp{[Toggle]} edit the buffer; the changes
-take effect when you use the @samp{Set for Current Session} operation.
+These variables don't let you edit the value textually. Instead, a
+@samp{[Value Menu]} button appears before the value; invoke this
+button to change the value. For a boolean ``on or off'' value, the
+button says @samp{[Toggle]}, and it changes to the other value.
+@samp{[Value Menu]} and @samp{[Toggle]} simply edit the buffer; the
+changes take real effect when you use the @samp{Set for Current
+Session} operation.
Some variables have values with complex structure. For example, the
value of @code{file-coding-system-alist} is an association list. Here
@noindent
Each association in the list appears on four lines, with several
-editable or ``active'' fields. You can edit the regexps and coding
+editable fields and/or buttons. You can edit the regexps and coding
systems using ordinary editing commands. You can also invoke
-@samp{[Value Menu]} to switch to a kind of value---for instance, to
-specify a function instead of a pair of coding systems.
+@samp{[Value Menu]} to switch to a different kind of value---for
+instance, to specify a function instead of a pair of coding systems.
To delete an association from the list, invoke the @samp{[DEL]} button
for that item. To add an association, invoke @samp{[INS]} at the
@kindex S-TAB @r{(customization buffer)}
@findex widget-forward
@findex widget-backward
- Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful for
-moving through the customization buffer. @key{TAB}
-(@code{widget-forward}) moves forward to the next active or editable
-field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to the
-previous active or editable field.
+ Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful
+for moving through the customization buffer. @key{TAB}
+(@code{widget-forward}) moves forward to the next button or editable
+field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to
+the previous button or editable field.
Typing @key{RET} on an editable field also moves forward, just like
@key{TAB}. We set it up this way because people often type @key{RET}
when they are finished editing a field. To insert a newline within an
editable field, use @kbd{C-o} or @kbd{C-q C-j}.
-@cindex saving variable value
-@cindex customized variables, saving
+@cindex saving a setting
+@cindex settings, how to save
Setting the variable changes its value in the current Emacs session;
@dfn{saving} the value changes it for future sessions as well. To
save the variable, invoke @samp{[State]} and select the @samp{Save for
@item Erase Customization
This sets the variable to its standard value, and updates the text
-accordingly. This also eliminates any saved value for the option,
+accordingly. This also eliminates any saved value for the variable,
so that you will get the standard value in future Emacs sessions.
@item Use Backup Value
The state of a group indicates whether anything in that group has been
edited, set or saved.
- Near the top of the customization buffer there are two lines
-containing several active fields:
+ Near the top of the customization buffer there are two lines of buttons:
@smallexample
[Set for Current Session] [Save for Future Sessions]
Invoking @samp{[Finish]} either buries or kills this customization
buffer according to the setting of the option
@code{custom-buffer-done-kill}; the default is to bury the buffer.
-Each of the other fields performs an operation---set, save or
-reset---on each of the options in the buffer that could meaningfully
-be set, saved or reset. They do not operate on options whose values
-are hidden, nor on subgroups.
+Each of the other buttons performs an operation---set, save or
+reset---on each of the settings in the buffer that could meaningfully
+be set, saved or reset. They do not operate on settings whose values
+are hidden, nor on subgroups not visible in the buffer.
@node Saving Customizations
@subsection Saving Customizations
[ ] Inherit: *
@end smallexample
- Each face attribute has its own line. The @samp{[@var{x}]} field
+ Each face attribute has its own line. The @samp{[@var{x}]} button
before the attribute name indicates whether the attribute is
-@dfn{enabled}; @samp{X} means that it is. You can enable or disable the
-attribute by invoking that field. When the attribute is enabled, you
-can change the attribute value in the usual ways.
+@dfn{enabled}; @samp{[X]} means that it's enabled, and @samp{[ ]}
+means that it's disabled. You can enable or disable the attribute by
+clicking that button. When the attribute is enabled, you can change
+the attribute value in the usual ways.
For the colors, you can specify a color name (use @kbd{M-x
list-colors-display} for a list of them) or a hexadecimal color
@node Specific Customization
@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 variable,
-face, or group that you want to customize.
+ Instead of finding the setting you want to change by navigating the
+structure of groups, here are other ways to specify the settings that
+you want to customize.
@table @kbd
@item M-x customize-variable @key{RET} @var{variable} @key{RET}
@item M-x customize-group @key{RET} @var{group} @key{RET}
Set up a customization buffer with just one group, @var{group}.
@item M-x customize-apropos @key{RET} @var{regexp} @key{RET}
-Set up a customization buffer with all the variables, faces and groups
-that match @var{regexp}.
+Set up a customization buffer with all the settings and groups that
+match @var{regexp}.
@item M-x customize-changed-options @key{RET} @var{version} @key{RET}
-Set up a customization buffer with all the variables, faces and groups
+Set up a customization buffer with all the settings and groups
whose meaning has changed since Emacs version @var{version}.
@item M-x customize-saved
-Set up a customization buffer containing all variables and faces that you
+Set up a customization buffer containing all settings that you
have saved with customization buffers.
@item M-x customize-customized
-Set up a customization buffer containing all variables and faces that you
-have customized but not saved.
+Set up a customization buffer containing all settings that you have
+customized but not saved.
@end table
@findex customize-variable
customize-variable} and specify the variable name. This sets up the
customization buffer with just one variable---the one that you asked
for. Editing, setting and saving the value work as described above,
-but only for the specified variable. Minibuffer completion is very
-handy if you only know part of the name. However, it only finds
+but only for the specified variable. Minibuffer completion is handy
+if you only know part of the name. However, this command can only see
options that have been loaded in the current Emacs session.
@findex customize-face
@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 user options, faces, and other groups, all appear
+group, including variables, faces, and other groups, all appear
as well (even if not already loaded). However, the subgroups' own
contents are not included.
@findex customize-apropos
To control more precisely what to customize, you can use @kbd{M-x
-customize-apropos}. You specify a regular expression as argument; then
-all @emph{loaded} options, faces and groups whose names match this
+customize-apropos}. You specify a regular expression as argument;
+then all @emph{loaded} settings and groups whose names match this
regular expression are set up in the customization buffer. If you
-specify an empty regular expression, this includes @emph{all} groups,
-options and faces (but that takes a long time).
+specify an empty regular expression, this includes @emph{all} loaded
+groups and settings---which takes a long time to set up.
-@findex customize-changed-options
+@findex customize-changed
When you upgrade to a new Emacs version, you might want to customize
-new options and options whose meanings or default values have changed.
-To do this, use @kbd{M-x customize-changed-options} and specify a
-previous Emacs version number using the minibuffer. It creates a
-customization buffer which shows all the options (and groups) whose
-definitions have been changed since the specified version. (Not just
-those that are already loaded.)
+new settings and settings whose meanings or default values have
+changed. To do this, use @kbd{M-x customize-changed} and
+specify a previous Emacs version number using the minibuffer. It
+creates a customization buffer which shows all the settings and groups
+whose definitions have been changed since the specified version, loading
+them if necessary.
@findex customize-saved
@findex customize-customized
- If you change option values and then decide the change was a
-mistake, you can use two special commands to revisit your previous
-changes. Use @kbd{M-x customize-saved} to look at the options that
-you have saved. Use @kbd{M-x customize-customized} to look at the
-options that you have set but not saved.
+ If you change settings and then decide the change was a mistake, you
+can use two special commands to revisit your previous changes. Use
+@kbd{M-x customize-saved} to look at the settings that you have saved.
+Use @kbd{M-x customize-customized} to look at the settings that you
+have set but not saved.
@node Custom Themes
@subsection Customization Themes
@cindex custom themes
-@dfn{Custom themes} are collections of customized options that can be
-enabled or disabled as a unit. You can use Custom themes to switch
-quickly and easily between various collections of settings, and to
-transfer such collections from one computer to another.
+ @dfn{Custom themes} are collections of settings that can be enabled
+or disabled as a unit. You can use Custom themes to switch quickly
+and easily between various collections of settings, and to transfer
+such collections from one computer to another.
@findex customize-create-theme
-To define a Custom theme, use the command
-@kbd{M-x customize-create-theme}, which brings up a buffer named
-@samp{*New Custom Theme*}. At the top of the buffer is an editable
-field where you can specify the name of the theme. To add a
-customization option to the theme, click on the @samp{INS} button to
-open up a field where you can insert the name of the option. The
-current value of that option is applied to the theme. After adding as
-many options as you like, click on @samp{Done} to save the Custom
-theme.
+ To define a Custom theme, use the command @kbd{M-x
+customize-create-theme}, which brings up a buffer named @samp{*New
+Custom Theme*}. At the top of the buffer is an editable field where
+you can specify the name of the theme. To add a customization option
+to the theme, click on the @samp{INS} button to open up a field where
+you can insert the name of the option. The current value of that
+option is applied to the theme. After adding as many options as you
+like, click on @samp{Done} to save the Custom theme.
@vindex custom-theme-directory
-Saving a Custom theme named @var{foo} writes its definition into the
+ Saving a Custom theme named @var{foo} writes its definition into the
file @file{@var{foo}-theme.el}, in the directory @file{~/.emacs.d/}
(you can specify the directory by setting
@code{custom-theme-directory}).
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 Lisp allows any variable (with a few exceptions) 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 those that
-are also @dfn{user options}, the variables that are meant for users to
-change. Each user option that you can set with the customization
-buffer is (if it is not a face) 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
-(@pxref{Easy Customization}); here we describe other aspects of Emacs
-variables.
+most interesting variables for a non-programmer user are those meant
+for users to change---the @dfn{user options}.
+
+ Each user option that you can set with the customization buffer is
+in fact a Lisp variable. Emacs does not (usually) change the values
+of these variables; instead, you set the values, and thereby alter and
+control the behavior of certain Emacs commands. Use of the
+customization buffer is explained above (@pxref{Easy Customization});
+here we describe other aspects of Emacs variables.
@menu
* Examining:: Examining or setting one variable's value.
projects / emacs.git / commitdiff