@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.
-@setfilename ../../info/customize
-@node Customization, Loading, Macros, Top
-@chapter Writing Customization Definitions
-
-@cindex customization definitions
- This chapter describes how to declare user options for customization,
-and also customization groups for classifying them. We use the term
-@dfn{customization item} to include both kinds of customization
-definitions---as well as face definitions (@pxref{Defining Faces}).
+@node Customization
+@chapter Customization Settings
+
+@cindex customization item
+ 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
- customization declarations.
-* Group Definitions:: Writing customization group definitions.
-* Variable Definitions:: Declaring user options.
-* Customization Types:: Specifying the type of a user option.
+* Common Keywords:: Common keyword arguments for all kinds of
+ customization declarations.
+* Group Definitions:: Writing customization group definitions.
+* Variable Definitions:: Declaring user options.
+* Customization Types:: Specifying the type of a user option.
+* Applying Customizations:: Functions to apply customization settings.
+* Custom Themes:: Writing Custom themes.
@end menu
@node Common Keywords
@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}
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 @var{setfunction}
@kindex set@r{, @code{defcustom} keyword}
Specify @var{setfunction} as the way to change the value of this
-option when using the Customize user interface. The function
+option when using the Customize interface. The function
@var{setfunction} should take two arguments, a symbol (the option
name) and the new value, and should do whatever is necessary to update
the value properly for this option (which may not mean simply setting
@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
another customizable variable.
@end defun
-@defun user-variable-p arg
-This function is like @code{custom-variable-p}, except it also returns
-@code{t} if the first character of the variable's documentation string
-is the character @samp{*}. That is an obsolete way of indicating a
-user option, so for most purposes you may consider
-@code{user-variable-p} as equivalent to @code{custom-variable-p}.
-@end defun
-
@node Customization Types
@section Customization Types
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}}.
@item color
The value must be a valid color name. The widget provides completion
for color names, as well as a sample and a button for selecting a
-color name from a list of color names shown in a @samp{*Colors*}
+color name from a list of color names shown in a @file{*Colors*}
buffer.
@end table
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 data structure is itself recursive, this conversion is an infinite
recursion. The @code{lazy} widget prevents the recursion: it convert
its @code{:type} argument only when needed.
+
+@node Applying Customizations
+@section Applying Customizations
+
+The following functions are responsible for installing the user's
+customization settings for variables and faces, respectively. When
+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.
+
+@defun custom-set-variables &rest args
+This function installs the variable customizations specified by
+@var{args}. Each argument in @var{args} should have the form
+
+@example
+(@var{var} @var{expression} [@var{now} [@var{request} [@var{comment}]]])
+@end example
+
+@noindent
+@var{var} is a variable name (a symbol), and @var{expression} is an
+expression which evaluates to the desired customized value.
+
+If the @code{defcustom} form for @var{var} has been evaluated prior to
+this @code{custom-set-variables} call, @var{expression} is immediately
+evaluated, and the variable's value is set to the result. Otherwise,
+@var{expression} is stored into the variable's @code{saved-value}
+property, to be evaluated when the relevant @code{defcustom} is called
+(usually when the library defining that variable is loaded into
+Emacs).
+
+The @var{now}, @var{request}, and @var{comment} entries are for
+internal use only, and may be omitted. @var{now}, if non-@code{nil},
+means to set the variable's value now, even if the variable's
+@code{defcustom} form has not been evaluated. @var{request} is a list
+of features to be loaded immediately (@pxref{Named Features}).
+@var{comment} is a string describing the customization.
+@end defun
+
+@defun custom-set-faces &rest args
+This function installs the face customizations specified by
+@var{args}. Each argument in @var{args} should have the form
+
+@example
+(@var{face} @var{spec} [@var{now} [@var{comment}]])
+@end example
+
+@noindent
+@var{face} is a face name (a symbol), and @var{spec} is the customized
+face specification for that face (@pxref{Defining Faces}).
+
+The @var{now} and @var{comment} entries are for internal use only, and
+may be omitted. @var{now}, if non-@code{nil}, means to install the
+face specification now, even if the @code{defface} form has not been
+evaluated. @var{comment} is a string describing the customization.
+@end defun
+
+@node Custom Themes
+@section Custom Themes
+
+ @dfn{Custom themes} are collections of settings that can be enabled
+or disabled as a unit. @xref{Custom Themes,,, emacs, The GNU Emacs
+Manual}. Each Custom theme is defined by an Emacs Lisp source file,
+which should follow the conventions described in this section.
+(Instead of writing a Custom theme by hand, you can also create one
+using a Customize-like interface; @pxref{Creating Custom Themes,,,
+emacs, The GNU Emacs Manual}.)
+
+ A Custom theme file should be named @file{@var{foo}-theme.el}, where
+@var{foo} is the theme name. The first Lisp form in the file should
+be a call to @code{deftheme}, and the last form should be a call to
+@code{provide-theme}.
+
+@defmac deftheme theme &optional doc
+This macro declares @var{theme} (a symbol) as the name of a Custom
+theme. The optional argument @var{doc} should be a string describing
+the theme; this is the description shown when the user invokes the
+@code{describe-theme} command or types @kbd{?} in the @samp{*Custom
+Themes*} buffer.
+
+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
+This macro declares that the theme named @var{theme} has been fully
+specified.
+@end defmac
+
+ In between @code{deftheme} and @code{provide-theme} are Lisp forms
+specifying the theme settings: usually a call to
+@code{custom-theme-set-variables} and/or a call to
+@code{custom-theme-set-faces}.
+
+@defun custom-theme-set-variables theme &rest args
+This function specifies the Custom theme @var{theme}'s variable
+settings. @var{theme} should be a symbol. Each argument in
+@var{args} should be a list of the form
+
+@example
+(@var{var} @var{expression} [@var{now} [@var{request} [@var{comment}]]])
+@end example
+
+@noindent
+where the list entries have the same meanings as in
+@code{custom-set-variables}. @xref{Applying Customizations}.
+@end defun
+
+@defun custom-theme-set-faces theme &rest args
+This function specifies the Custom theme @var{theme}'s face settings.
+@var{theme} should be a symbol. Each argument in @var{args} should be
+a list of the form
+
+@example
+(@var{face} @var{spec} [@var{now} [@var{comment}]])
+@end example
+
+@noindent
+where the list entries have the same meanings as in
+@code{custom-set-faces}. @xref{Applying Customizations}.
+@end defun
+
+ In theory, a theme file can also contain other Lisp forms, which
+would be evaluated when loading the theme, but that is ``bad form''.
+To protect against loading themes containing malicious code, Emacs
+displays the source file and asks for confirmation from the user
+before loading any non-built-in theme for the first time.
+
+ The following functions are useful for programmatically enabling and
+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
+loaded into Emacs, whether or not the theme is enabled). Otherwise,
+it returns @code{nil}.
+@end defun
+
+@deffn Command load-theme theme &optional no-confirm no-enable
+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 (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
+This function enables the Custom theme named @var{theme}. It signals
+an error if no such theme has been loaded.
+@end deffn
+
+@deffn Command disable-theme theme
+This function disables the Custom theme named @var{theme}. The theme
+remains loaded, so that a subsequent call to @code{enable-theme} will
+re-enable it.
+@end deffn