@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1997-2011 Free Software Foundation, Inc.
+@c Copyright (C) 1997-2012 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
+@node Customization
+@chapter Customization Settings
-@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}).
+@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.
@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
@section Common Item Keywords
@cindex customization keywords
- All kinds of customization declarations (for variables and groups, and
-for faces) accept keyword arguments for specifying various information.
-This section describes some keywords that apply to all kinds.
+ 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.
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.
for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to
the Emacs manual which appears in the buffer as @samp{foo}.
-An item can have more than one external link; however, most items have
-none at all.
+You can use this keyword more than once, to add multiple links.
@item :load @var{file}
@kindex load@r{, customization keyword}
@kindex package-version@r{, customization keyword}
This keyword specifies that the item was first introduced in
@var{package} version @var{version}, or that its meaning or default
-value was changed in that version. The value of @var{package} is a
-symbol and @var{version} is a string.
-
-This keyword takes priority over @code{:version}.
+value was changed in that version. This keyword takes priority over
+@code{:version}.
-@var{package} should be the official name of the package, such as MH-E
-or Gnus. If the package @var{package} is released as part of Emacs,
-@var{package} and @var{version} should appear in the value of
+@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
+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}.
@end table
@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")
@table @code
@item :prefix @var{prefix}
@kindex prefix@r{, @code{defgroup} keyword}
-If the name of an item in the group starts with @var{prefix}, then the
-tag for that item is constructed (by default) by omitting @var{prefix}.
-
-One group can have any number of prefixes.
+If the name of an item in the group starts with @var{prefix}, and the
+customizable variable @code{custom-unlispify-remove-prefixes} is
+non-@code{nil}, the item's tag will omit @var{prefix}. A group can
+have any number of prefixes.
@end table
@end defmac
- The prefix-discarding feature is currently turned off, which means
-that @code{:prefix} currently has no effect. We did this because we
-found that discarding the specified prefixes often led to confusing
-names for options. This happened because the people who wrote the
-@code{defgroup} definitions for various groups added @code{:prefix}
-keywords whenever they make logical sense---that is, whenever the
-variables in the library have a common prefix.
+@defopt custom-unlispify-remove-prefixes
+If this variable is non-@code{nil}, the prefixes specified by a
+group's @code{:prefix} keyword are omitted from tag names, whenever
+the user customizes the group.
- In order to obtain good results with @code{:prefix}, it would be
-necessary to check the specific effects of discarding a particular
-prefix, given the specific items in a group and their names and
-documentation. If the resulting text is not clear, then @code{:prefix}
-should not be used in that case.
-
- It should be possible to recheck all the customization groups, delete
-the @code{:prefix} specifications which give unclear results, and then
-turn this feature back on, if someone would like to do the work.
+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
- Use @code{defcustom} to declare user-customizable variables.
-
@defmac defcustom option standard doc [keyword value]@dots{}
-This macro declares @var{option} as a customizable @dfn{user option}.
-You should not quote @var{option}.
-
-This causes the function @code{user-variable-p} to return @code{t}
-when given @var{option} as an argument. @xref{Defining Variables}.
-The argument @var{doc} specifies the documentation string for the
-variable. (Note that there is no need to start @var{doc} with a
-@samp{*}.)
+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
standard value for @var{option}. Evaluating the @code{defcustom} form
The expression @var{standard} can be evaluated at various other times,
too---whenever the customization facility needs to know @var{option}'s
standard value. So be sure to use an expression which is harmless to
-evaluate at any time. We recommend avoiding backquotes in
-@var{standard}, because they are not expanded when editing the value,
-so list values will appear to have the wrong structure.
+evaluate at any time.
-Every @code{defcustom} should specify @code{:group} at least once.
+The argument @var{doc} specifies the documentation string for the
+variable.
-If you specify the @code{:set} keyword, to make the variable take other
-special actions when set through the customization buffer, the
-variable's documentation string should tell the user specifically how
-to do the same job in hand-written Lisp code.
+Every @code{defcustom} should specify @code{:group} at least once.
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}
its value is void. (The same feature applies to @code{defvar}.)
@xref{Defining Variables}.
-If you put a @code{defcustom} in a file that is preloaded at dump time
-(@pxref{Building Emacs}), and the standard value installed for the
-variable at that time might not be correct, use
+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
+has not been assigned the right value yet. In that case, use
@code{custom-reevaluate-setting}, described below, to re-evaluate the
-standard value during or after Emacs startup.
+standard value after Emacs starts up.
@end defmac
@code{defcustom} accepts the following additional keywords:
@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
the option as a Lisp variable). The default for @var{setfunction} is
@code{set-default}.
+If you specify this keyword, the variable's documentation string
+should describe how to do the same job in hand-written Lisp code.
+
@item :get @var{getfunction}
@kindex get@r{, @code{defcustom} keyword}
Specify @var{getfunction} as the way to extract the value of this
You have to really understand the workings of Custom to use
@code{:get} correctly. It is meant for values that are treated in
Custom as variables but are not actually stored in Lisp variables. It
-is almost surely a mistake to specify @code{getfunction} for a value
+is almost surely a mistake to specify @var{getfunction} for a value
that really is stored in a Lisp variable.
@item :initialize @var{function}
These functions behave like @code{custom-initialize-set}
(@code{custom-initialize-default}, respectively), but catch errors.
If an error occurs during initialization, they set the variable to
-@code{nil} using @code{set-default}, and throw no error.
-
-These two functions are only meant for options defined in pre-loaded
-files, where some variables or functions used to compute the option's
-value may not yet be defined. The option normally gets updated in
-@file{startup.el}, ignoring the previously computed value. Because of
-this typical usage, the value which these two functions compute
-normally only matters when, after startup, one unsets the option's
-value and then reevaluates the defcustom. By that time, the necessary
-variables and functions will be defined, so there will not be an error.
+@code{nil} using @code{set-default}, and signal no error.
+
+These functions are meant for options defined in pre-loaded files,
+where the @var{standard} expression may signal an error because some
+required variable or function is not yet defined. The value normally
+gets updated in @file{startup.el}, ignoring the value computed by
+@code{defcustom}. After startup, if one unsets the value and
+reevaluates the @code{defcustom}, the @var{standard} expression can be
+evaluated without error.
@end table
@item :risky @var{value}
@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.
@defun custom-reevaluate-setting symbol
This function re-evaluates the standard value of @var{symbol}, which
-should be a user option declared via @code{defcustom}. (If the
+should be a user option declared via @code{defcustom}. If the
variable was customized, this function re-evaluates the saved value
-instead.) This is useful for customizable options that are defined
-before their value could be computed correctly, such as variables
-defined in packages that are loaded at dump time, but depend on the
-run-time information. For example, the value could be a file whose
-precise name depends on the hierarchy of files when Emacs runs, or a
-name of a program that needs to be searched at run time.
-
-A good place to put calls to this function is in the function
-@code{command-line} that is run during startup (@pxref{Startup Summary})
-or in the various hooks it calls.
+instead. Then it sets the user option to that value (using the
+option's @code{:set} property if that is defined).
+
+This is useful for customizable options that are defined before their
+value could be computed correctly. For example, during startup Emacs
+calls this function for some user options that were defined in
+pre-loaded Emacs Lisp files, but whose initial values depend on
+information available only at run-time.
+@end defun
+
+@defun custom-variable-p arg
+This function returns non-@code{nil} if @var{arg} is a customizable
+variable. A customizable variable is either a variable that has a
+@code{standard-value} or @code{custom-autoload} property (usually
+meaning it was declared with @code{defcustom}), or an alias for
+another customizable variable.
@end defun
@node Customization Types
@node Simple Types
@subsection Simple Types
- This section describes all the simple customization types.
+ This section describes all the simple customization types. For
+several of these customization types, the customization widget
+provides inline completion with @kbd{C-M-i} or @kbd{M-@key{TAB}}.
@table @code
@item sexp
-The value may be any Lisp object that can be printed and read back. You
-can use @code{sexp} as a fall-back for any option, if you don't want to
-take the time to work out a more specific type to use.
+The value may be any Lisp object that can be printed and read back.
+You can use @code{sexp} as a fall-back for any option, if you don't
+want to take the time to work out a more specific type to use.
@item integer
-The value must be an integer, and is represented textually
-in the customization buffer.
+The value must be an integer.
@item number
-The value must be a number (floating point or integer), and is
-represented textually in the customization buffer.
+The value must be a number (floating point or integer).
@item float
-The value must be a floating point number, and is represented
-textually in the customization buffer.
+The value must be a floating point number.
@item string
-The value must be a string, and the customization buffer shows just the
-contents, with no delimiting @samp{"} characters and no quoting with
-@samp{\}.
+The value must be a string. The customization buffer shows the string
+without delimiting @samp{"} characters or @samp{\} quotes.
@item regexp
Like @code{string} except that the string must be a valid regular
buffer, rather than by showing the number.
@item file
-The value must be a file name, and you can do completion with
-@kbd{M-@key{TAB}}.
+The value must be a file name. The widget provides completion.
@item (file :must-match t)
-The value must be a file name for an existing file, and you can do
-completion with @kbd{M-@key{TAB}}.
+The value must be a file name for an existing file. The widget
+provides completion.
@item directory
-The value must be a directory name, and you can do completion with
-@kbd{M-@key{TAB}}.
+The value must be a directory name. The widget provides completion.
@item hook
-The value must be a list of functions (or a single function, but that is
-obsolete usage). This customization type is used for hook variables.
-You can use the @code{:options} keyword in a hook variable's
-@code{defcustom} to specify a list of functions recommended for use in
-the hook; see @ref{Variable Definitions}.
+The value must be a list of functions. This customization type is
+used for hook variables. You can use the @code{:options} keyword in a
+hook variable's @code{defcustom} to specify a list of functions
+recommended for use in the hook; @xref{Variable Definitions}.
@item symbol
The value must be a symbol. It appears in the customization buffer as
-the name of the symbol.
+the symbol name. The widget provides completion.
@item function
-The value must be either a lambda expression or a function name. When
-it is a function name, you can do completion with @kbd{M-@key{TAB}}.
+The value must be either a lambda expression or a function name. The
+widget provides completion for function names.
@item variable
-The value must be a variable name, and you can do completion with
-@kbd{M-@key{TAB}}.
+The value must be a variable name. The widget provides completion.
@item face
-The value must be a symbol which is a face name, and you can do
-completion with @kbd{M-@key{TAB}}.
+The value must be a symbol which is a face name. The widget provides
+completion.
@item boolean
The value is boolean---either @code{nil} or @code{t}. Note that by
@kbd{M-@key{TAB}}.
@item color
-The value must be a valid color name, and you can do completion with
-@kbd{M-@key{TAB}}. A sample is provided.
+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 @file{*Colors*}
+buffer.
@end table
@node Composite Types
symbol)} is a customization type which matches values such as
@code{("foo" . foo)}.
-In the customization buffer, the @sc{car} and the @sc{cdr} are
-displayed and edited separately, each according to the type
-that you specify for it.
+In the customization buffer, the @sc{car} and @sc{cdr} are displayed
+and edited separately, each according to their specified type.
@item (list @var{element-types}@dots{})
The value must be a list with exactly as many elements as the
The argument to the @code{:options} keywords should be a list of
specifications for reasonable keys in the alist. Ordinarily, they are
-simply atoms, which stand for themselves as. For example:
+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)))
-
-(defcustom pets '(("brian")
- ("dorith" "dog" "guppy")
- ("ken" "cat"))
- "Alist of people's pets.
-In an element (KEY . VALUE), KEY is the person's name,
-and the VALUE is a list of that person's pets."
- :type '(alist :value-type (repeat string)))
-@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
defaults to @code{symbol} rather than @code{sexp}.
@item (choice @var{alternative-types}@dots{})
-The value must fit at least one of @var{alternative-types}.
-For example, @code{(choice integer string)} allows either an
-integer or a string.
+The value must fit one of @var{alternative-types}. For example,
+@code{(choice integer string)} allows either an integer or a string.
In the customization buffer, the user selects an alternative
using a menu, and can then edit the value in the usual way for that
@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}.
@subsection Splicing into Lists
The @code{:inline} feature lets you splice a variable number of
-elements into the middle of a list or vector. You use it in a
-@code{set}, @code{choice} or @code{repeat} type which appears among the
-element-types of a @code{list} or @code{vector}.
-
- Normally, each of the element-types in a @code{list} or @code{vector}
-describes one and only one element of the list or vector. Thus, if an
-element-type is a @code{repeat}, that specifies a list of unspecified
-length which appears as one element.
-
- But when the element-type uses @code{:inline}, the value it matches is
-merged directly into the containing sequence. For example, if it
-matches a list with three elements, those become three elements of the
-overall sequence. This is analogous to using @samp{,@@} in the backquote
-construct.
+elements into the middle of a @code{list} or @code{vector}
+customization type. You use it by adding @code{:inline t} to a type
+specification which is contained in a @code{list} or @code{vector}
+specification.
+
+ Normally, each entry in a @code{list} or @code{vector} type
+specification describes a single element type. But when an entry
+contains @code{:inline t}, the value it matches is merged directly
+into the containing sequence. For example, if the entry matches a
+list with three elements, those become three elements of the overall
+sequence. This is analogous to @samp{,@@} in a backquote construct
+(@pxref{Backquote}).
For example, to specify a list whose first element must be @code{baz}
and whose remaining arguments should be zero or more of @code{foo} and
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