@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1997-2012 Free Software Foundation, Inc.
+@c Copyright (C) 1997-2013 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@node Customization, Loading, Macros, Top
+@node Customization
@chapter Customization Settings
@cindex customization item
- This chapter describes how to declare customizable variables and
-customization groups for classifying them. We use the term
-@dfn{customization item} to include customizable variables,
-customization groups, as well as faces.
-
- @xref{Defining Faces}, for the @code{defface} macro, which is used
-for declaring customizable faces.
+ Users of Emacs can customize variables and faces without writing
+Lisp code, by using the Customize interface. @xref{Easy
+Customization,,, emacs, The GNU Emacs Manual}. This chapter describes
+how to define @dfn{customization items} that users can interact with
+through the Customize interface.
+
+ Customization items include customizable variables, which are
+defined with the
+@ifinfo
+@code{defcustom} macro (@pxref{Variable Definitions});
+@end ifinfo
+@ifnotinfo
+@code{defcustom} macro;
+@end ifnotinfo
+customizable faces, which are defined with @code{defface} (described
+separately in @ref{Defining Faces}); and @dfn{customization groups},
+defined with
+@ifinfo
+@code{defgroup} (@pxref{Group Definitions}),
+@end ifinfo
+@ifnotinfo
+@code{defgroup},
+@end ifnotinfo
+which act as containers for groups of related customization items.
@menu
* Common Keywords:: Common keyword arguments for all kinds of
@cindex customization keywords
The customization declarations that we will describe in the next few
-sections (@code{defcustom}, @code{defgroup}, etc.) all accept keyword
-arguments for specifying various information. This section describes
-keywords that apply to all types of customization declarations.
+sections---@code{defcustom}, @code{defgroup}, etc.---all accept
+keyword arguments (@pxref{Constant Variables}) for specifying various
+information. This section describes keywords that apply to all types
+of customization declarations.
All of these keywords, except @code{:tag}, can be used more than once
in a given item. Each use of the keyword has an independent effect.
@item :link @var{link-data}
@kindex link@r{, customization keyword}
Include an external link after the documentation string for this item.
-This is a sentence containing an active field which references some
+This is a sentence containing a button that references some
other documentation.
There are several alternatives you can use for @var{link-data}:
@item (emacs-commentary-link @var{library})
Link to the commentary section of a library; @var{library} is a string
-which specifies the library name.
+which specifies the library name. @xref{Library Headers}.
@item (emacs-library-link @var{library})
Link to an Emacs Lisp library file; @var{library} is a string which
@code{:version}.
@var{package} should be the official name of the package, as a symbol
-(e.g.@: @code{MH-E}). @var{version} should be a string. If the
+(e.g., @code{MH-E}). @var{version} should be a string. If the
package @var{package} is released as part of Emacs, @var{package} and
@var{version} should appear in the value of
@code{customize-package-emacs-version-alist}.
@defvar customize-package-emacs-version-alist
This alist provides a mapping for the versions of Emacs that are
associated with versions of a package listed in the
-@code{:package-version} keyword. Its elements look like this:
+@code{:package-version} keyword. Its elements are:
@example
(@var{package} (@var{pversion} . @var{eversion})@dots{})
associated Emacs version @var{eversion}. These versions are strings.
For example, the MH-E package updates this alist with the following:
+@c Must be small else too wide.
+@c FIXME obviously this is out of date (in the code).
@smallexample
(add-to-list 'customize-package-emacs-version-alist
'(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1")
@cindex define customization group
@cindex customization groups, defining
- Each Emacs Lisp package should have one main customization group which
-contains all the options, faces and other groups in the package. If the
-package has a small number of options and faces, use just one group and
-put everything in it. When there are more than twelve or so options and
-faces, then you should structure them into subgroups, and put the
-subgroups under the package's main customization group. It is OK to
-put some of the options and faces in the package's main group alongside
-the subgroups.
+ Each Emacs Lisp package should have one main customization group
+which contains all the options, faces and other groups in the package.
+If the package has a small number of options and faces, use just one
+group and put everything in it. When there are more than twenty or so
+options and faces, then you should structure them into subgroups, and
+put the subgroups under the package's main customization group. It is
+OK to put some of the options and faces in the package's main group
+alongside the subgroups.
The package's main or only group should be a member of one or more of
the standard customization groups. (To display the full list of them,
group's @code{:prefix} keyword are omitted from tag names, whenever
the user customizes the group.
-The default value is @code{nil}, i.e.@: the prefix-discarding feature
+The default value is @code{nil}, i.e., the prefix-discarding feature
is disabled. This is because discarding prefixes often leads to
confusing names for options and faces.
@end defopt
@node Variable Definitions
@section Defining Customization Variables
@cindex define customization options
-@cindex customization variables, how to define
+@cindex customizable variables, how to define
+@cindex user options, how to define
+
+ @dfn{Customizable variables}, also called @dfn{user options}, are
+global Lisp variables whose values can be set through the Customize
+interface. Unlike other global variables, which are defined with
+@code{defvar} (@pxref{Defining Variables}), customizable variables are
+defined using the @code{defcustom} macro. In addition to calling
+@code{defvar} as a subroutine, @code{defcustom} states how the
+variable should be displayed in the Customize interface, the values it
+is allowed to take, etc.
@defmac defcustom option standard doc [keyword value]@dots{}
-This macro declares @var{option} as a user option (i.e.@: a
+This macro declares @var{option} as a user option (i.e., a
customizable variable). You should not quote @var{option}.
The argument @var{standard} is an expression that specifies the
The argument @var{doc} specifies the documentation string for the
variable.
-Every @code{defcustom} should specify @code{:group} at least once.
+If a @code{defcustom} does not specify any @code{:group}, the last group
+defined with @code{defgroup} in the same file will be used. This way, most
+@code{defcustom} do not need an explicit @code{:group}.
When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp
mode (@code{eval-defun}), a special feature of @code{eval-defun}
arranges to set the variable unconditionally, without testing whether
-its value is void. (The same feature applies to @code{defvar}.)
-@xref{Defining Variables}.
+its value is void. (The same feature applies to @code{defvar},
+@pxref{Defining Variables}.) Using @code{eval-defun} on a defcustom
+that is already defined calls the @code{:set} function (see below),
+if there is one.
If you put a @code{defcustom} in a pre-loaded Emacs Lisp file
(@pxref{Building Emacs}), the standard value installed at dump time
-might be incorrect, e.g.@: because another variable that it depends on
+might be incorrect, e.g., because another variable that it depends on
has not been assigned the right value yet. In that case, use
@code{custom-reevaluate-setting}, described below, to re-evaluate the
standard value after Emacs starts up.
@end defmac
- @code{defcustom} accepts the following additional keywords:
+ In addition to the keywords listed in @ref{Common Keywords}, this
+macro accepts the following keywords:
@table @code
@item :type @var{type}
Use @var{type} as the data type for this option. It specifies which
-values are legitimate, and how to display the value.
-@xref{Customization Types}, for more information.
+values are legitimate, and how to display the value
+(@pxref{Customization Types}).
@item :options @var{value-list}
@kindex options@r{, @code{defcustom} keyword}
@item :set-after @var{variables}
@kindex set-after@r{, @code{defcustom} keyword}
When setting variables according to saved customizations, make sure to
-set the variables @var{variables} before this one; in other words, delay
+set the variables @var{variables} before this one; i.e., delay
setting this variable until after those others have been handled. Use
@code{:set-after} if setting this variable won't work properly unless
those other variables already have their intended values.
@code{saved-value} to record the value saved by the user with the
customization buffer, and @code{customized-value} to record the value
set by the user with the customization buffer, but not saved.
-@xref{Property Lists}. These properties are lists, the car of which
-is an expression that evaluates to the value.
+@xref{Symbol Properties}. These properties are lists, the car of
+which is an expression that evaluates to the value.
@defun custom-reevaluate-setting symbol
This function re-evaluates the standard value of @var{symbol}, which
specify the text to describe each value in a way that fits the specific
meaning of the alternative.
+@item key-sequence
+The value is a key sequence. The customization buffer shows the key
+sequence using the same syntax as the @kbd{kbd} function. @xref{Key
+Sequences}.
+
@item coding-system
The value must be a coding-system name, and you can do completion with
@kbd{M-@key{TAB}}.
specifications for reasonable keys in the alist. Ordinarily, they are
simply atoms, which stand for themselves. For example:
-@smallexample
+@example
:options '("foo" "bar" "baz")
-@end smallexample
+@end example
@noindent
specifies that there are three ``known'' keys, namely @code{"foo"},
the list. The first element will specify the key, like before, while
the second element will specify the value type. For example:
-@smallexample
+@example
:options '("foo" ("bar" integer) "baz")
-@end smallexample
+@end example
Finally, you may want to change how the key is presented. By default,
the key is simply shown as a @code{const}, since the user cannot change
This is done by using a customization type specification instead of a
symbol for the key.
-@smallexample
-:options '("foo" ((function-item some-function) integer)
+@example
+:options '("foo"
+ ((function-item some-function) integer)
"baz")
-@end smallexample
+@end example
Many alists use lists with two elements, instead of cons cells. For
example,
-@smallexample
-(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
+@example
+(defcustom list-alist
+ '(("foo" 1) ("bar" 2) ("baz" 3))
"Each element is a list of the form (KEY VALUE).")
-@end smallexample
+@end example
@noindent
instead of
-@smallexample
-(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
+@example
+(defcustom cons-alist
+ '(("foo" . 1) ("bar" . 2) ("baz" . 3))
"Each element is a cons-cell (KEY . VALUE).")
-@end smallexample
+@end example
Because of the way lists are implemented on top of cons cells, you can
treat @code{list-alist} in the example above as a cons cell alist, where
the value type is a list with a single element containing the real
value.
-@smallexample
+@example
(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
"Each element is a list of the form (KEY VALUE)."
:type '(alist :value-type (group integer)))
-@end smallexample
+@end example
The @code{group} widget is used here instead of @code{list} only because
the formatting is better suited for the purpose.
Similarly, you can have alists with more values associated with each
key, using variations of this trick:
-@smallexample
+@example
(defcustom person-data '(("brian" 50 t)
("dorith" 55 nil)
("ken" 52 t))
"Alist of basic info about people.
Each element has the form (NAME AGE MALE-FLAG)."
:type '(alist :value-type (group integer boolean)))
-@end smallexample
+@end example
@item (plist :key-type @var{key-type} :value-type @var{value-type})
This customization type is similar to @code{alist} (see above), except
@noindent
describes a variable for which @code{t} means yes, @code{nil} means no,
-and @code{foo} means ``ask.''
+and @code{foo} means ``ask''.
@item (other @var{value})
This alternative can match any Lisp value, but if the user chooses this
@noindent
describes a variable for which @code{t} means yes, @code{nil} means no,
-and anything else means ``ask.'' If the user chooses @samp{Ask} from
+and anything else means ``ask''. If the user chooses @samp{Ask} from
the menu of alternatives, that specifies the value @code{foo}; but any
other value (not @code{t}, @code{nil} or @code{foo}) displays as
@samp{Ask}, just like @code{foo}.
@item %h
Like @samp{%d}, but if the documentation string is more than one line,
-add an active field to control whether to show all of it or just the
-first line.
+add a button to control whether to show all of it or just the first line.
@item %t
Substitute the tag here. You specify the tag with the @code{:tag}
the user invokes @samp{Save for future sessions} in the Customize
interface, that takes effect by writing a @code{custom-set-variables}
and/or a @code{custom-set-faces} form into the custom file, to be
-evaluated the next time Emacs starts up.
+evaluated the next time Emacs starts.
@defun custom-set-variables &rest args
This function installs the variable customizations specified by
@code{describe-theme} command or types @kbd{?} in the @samp{*Custom
Themes*} buffer.
-Two special theme names are disallowed: @code{user} is a ``dummy''
-theme which stores the user's direct customization settings, and
-@code{changed} is a ``dummy'' theme which stores changes made outside
-of the Customize system. If you specify either of these as the
-@var{theme} argument, @code{deftheme} signals an error.
+Two special theme names are disallowed (using them causes an error):
+@code{user} is a ``dummy'' theme that stores the user's direct
+customization settings, and @code{changed} is a ``dummy'' theme that
+stores changes made outside of the Customize system.
@end defmac
@defmac provide-theme theme
before loading any non-built-in theme for the first time.
The following functions are useful for programmatically enabling and
-disabling Custom themes:
+disabling themes:
@defun custom-theme-p theme
This function return a non-@code{nil} value if @var{theme} (a symbol)
-is the name of a Custom theme (i.e.@: a Custom theme which has been
+is the name of a Custom theme (i.e., a Custom theme which has been
loaded into Emacs, whether or not the theme is enabled). Otherwise,
it returns @code{nil}.
@end defun
This function loads the Custom theme named @var{theme} from its source
file, looking for the source file in the directories specified by the
variable @code{custom-theme-load-path}. @xref{Custom Themes,,, emacs,
-The GNU Emacs Manual}. It also @dfn{enables} the theme, causing its
-variable and face settings to take effect.
-
-If the optional argument @var{no-confirm} is non-@code{nil}, this
-skips prompting the user for confirmation before loading the theme.
-
-If the optional argument @var{no-enable} is non-@code{nil}, the theme
-is loaded but not enabled.
+The GNU Emacs Manual}. It also @dfn{enables} the theme (unless the
+optional argument @var{no-enable} is non-@code{nil}), causing its
+variable and face settings to take effect. It prompts the user for
+confirmation before loading the theme, unless the optional argument
+@var{no-confirm} is non-@code{nil}.
@end deffn
@deffn Command enable-theme theme
HCoop / bpt / emacs.git / blobdiff