comparison man/custom.texi @ 58763:25b217a7d2af

(Easy Customization): Move up to section level, before Variables. Avoid using the term "variable"; say "option". New initial explanation. (Variables): In initial explanation, connect "variable" to the already-explained "user option".

58762:770cf3ce5391

replay sequences of keys.

@menu
* Minor Modes::		Each minor mode is one feature you can turn on
			  independently of any others.
* 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".

will get an error.  This means you must either set the mark, or
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

@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.

@menu
* Groups: Customization Groups.
                             How options are classified in a structure.
* Changing an Option::       How to edit a value and set an option.

* Specific Customization::   Making a customization buffer for specific
                                options, faces, or groups.
@end menu

@node Customization Groups
@subsubsection 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}.

that active field creates an ordinary customization buffer showing just
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

  Here is an example of what a user option looks like in the
customization buffer:

@smallexample

  The line after the option name indicates the @dfn{customization state}
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.

  The line after the @samp{[State]} line displays the beginning of the
option's documentation string.  If there are more lines of
documentation, this line ends with @samp{[More]}; invoke this to show
the full documentation string.

@smallexample
[State]: you have edited the value as text, but not set the option.
@end smallexample

@cindex setting option value
  Editing the value does not actually set the option variable.  To do
that, you must @dfn{set} the option.  To do this, invoke the word
@samp{[State]} and choose @samp{Set for Current Session}.

  The state of the option changes visibly when you set it:

@cindex customized options, saving
  Setting the option changes its value in the current Emacs session;
@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
Customizations}).

  You can also restore the option to its standard value by invoking
@samp{[State]} and selecting the @samp{Erase Customization} operation.
There are actually three reset operations:

accordingly.  This also eliminates any saved value for the option,
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,
you can get the customized value back again with this operation.
@end table

@cindex comments on customized options
  Sometimes it is useful to record a comment about a specific

Each of the other fields performs an operation---set, save or
reset---on each of the items in the buffer that could meaningfully be
set, saved or reset.

@node Saving Customizations
@subsubsection 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

customizations in your @file{~/.emacs} init file.  This is because
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
@cindex customizing faces
@cindex bold font
@cindex italic font
@cindex fonts and faces

the attribute's current value is the default---type just @key{RET} if
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

  Instead of finding the options you want to change by moving down
through the structure of groups, you can specify the particular option,
face or group that you want to customize.

Set up a customization buffer containing all options and faces that you
have customized but not saved.
@end table

@findex customize-option
  If you want to alter a particular user option variable 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
for.  Editing, setting and saving the value work as described above, but
only for the specified option.

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
as well.  However, these subgroups' own contents start out hidden.  You
can show their contents in the usual way, by invoking @samp{[Show]}.

@findex customize-apropos
  To control more precisely what to customize, you can use @kbd{M-x

  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 and faces that you have
saved.  Use @kbd{M-x customize-customized} to look at the options and
faces that you have set but not saved.

@node Hooks
@subsection Hooks
@cindex hook
@cindex running a hook

58763:25b217a7d2af

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.
* Key Bindings::	The keymaps say what command each key runs.
			  By changing them, you can "redefine keys".

will get an error.  This means you must either set the mark, or
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 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.  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
  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.
                             How options are classified in a structure.
* Changing an Option::       How to edit a value and set an option.

* Specific Customization::   Making a customization buffer for specific
                                options, faces, or groups.
@end menu

@node Customization Groups
@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}.

that active field creates an ordinary customization buffer showing just
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
@subsection Changing an Option

  Here is an example of what a user option looks like in the
customization buffer:

@smallexample

  The line after the option name indicates the @dfn{customization state}
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 user option.

  The line after the @samp{[State]} line displays the beginning of the
option's documentation string.  If there are more lines of
documentation, this line ends with @samp{[More]}; invoke this to show
the full documentation string.

@smallexample
[State]: you have edited the value as text, but not set the option.
@end smallexample

@cindex setting option value
  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}.

  The state of the option changes visibly when you set it:

@cindex customized options, saving
  Setting the option changes its value in the current Emacs session;
@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 again, each time you start Emacs (@pxref{Saving
Customizations}).

  You can also restore the option to its standard value by invoking
@samp{[State]} and selecting the @samp{Erase Customization} operation.
There are actually three reset operations:

accordingly.  This also eliminates any saved value for the option,
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 an option
and then reset it, which discards the customized value,
you can get the customized value back again with this operation.
@end table

@cindex comments on customized options
  Sometimes it is useful to record a comment about a specific

Each of the other fields performs an operation---set, save or
reset---on each of the items in the buffer that could meaningfully be
set, saved or reset.

@node 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

customizations in your @file{~/.emacs} init file.  This is because
saving customizations from such a session would wipe out all the other
customizations you might have on your init file.

@node Face Customization
@subsection Customizing Faces
@cindex customizing faces
@cindex bold font
@cindex italic font
@cindex fonts and faces

the attribute's current value is the default---type just @key{RET} if
you don't want to change that attribute.  Type @samp{none} if you want
to clear out the attribute.

@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 option,
face or group that you want to customize.

Set up a customization buffer containing all options and faces that you
have customized but not saved.
@end table

@findex customize-option
  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
for.  Editing, setting and saving the value work as described above, but
only for the specified option.

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 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]}.

@findex customize-apropos
  To control more precisely what to customize, you can use @kbd{M-x

  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 and faces that you have
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 buffera 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
@cindex running a hook