@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-2016 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Customization
@chapter Customization Settings
@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}.
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
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
standard value for @var{option}. Evaluating the @code{defcustom} form
-evaluates @var{standard}, but does not necessarily install the
-standard value. If @var{option} already has a default value,
-@code{defcustom} does not change it. If the user has saved a
-customization for @var{option}, @code{defcustom} installs the user's
-customized value as @var{option}'s default value. If neither of those
-cases applies, @code{defcustom} installs the result of evaluating
-@var{standard} as the default value.
+evaluates @var{standard}, but does not necessarily bind the option to
+that value. If @var{option} already has a default value, it is left
+unchanged. If the user has already saved a customization for
+@var{option}, the user's customized value is installed as the default
+value. Otherwise, the result of evaluating @var{standard} is
+installed as the default value.
+
+Like @code{defvar}, this macro marks @code{option} as a special
+variable, meaning that it should always be dynamically bound. If
+@var{option} is already lexically bound, that lexical binding remains
+in effect until the binding construct exits. @xref{Variable Scoping}.
The expression @var{standard} can be evaluated at various other times,
too---whenever the customization facility needs to know @var{option}'s
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.
@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}.
+the option as a Lisp variable); preferably, though, it should not
+modify its value argument destructively. 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.
Specify @var{getfunction} as the way to extract the value of this
option. The function @var{getfunction} should take one argument, a
symbol, and should return whatever customize should use as the
-``current value'' for that symbol (which need not be the symbol's Lisp
+current value for that symbol (which need not be the symbol's Lisp
value). The default is @code{default-value}.
You have to really understand the workings of Custom to use
@end table
It is useful to specify the @code{:require} keyword for an option
-that ``turns on'' a certain feature. This causes Emacs to load the
+that turns on a certain feature. This causes Emacs to load the
feature, if it is not already loaded, whenever the option is set.
@xref{Common Keywords}. Here is an example, from the library
@file{saveplace.el}:
The value must be a number (floating point or integer).
@item float
-The value must be a floating point number.
+The value must be floating point.
@item string
The value must be a string. The customization buffer shows the string
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}}.
@end example
@noindent
-specifies that there are three ``known'' keys, namely @code{"foo"},
+specifies that there are three known keys, namely @code{"foo"},
@code{"bar"} and @code{"baz"}, which will always be shown first.
You may want to restrict the value type for specific keys, for
@item (radio @var{element-types}@dots{})
This is similar to @code{choice}, except that the choices are displayed
-using `radio buttons' rather than a menu. This has the advantage of
+using radio buttons rather than a menu. This has the advantage of
displaying documentation for the choices when applicable and so is often
a good choice for a choice between constant functions
(@code{function-item} customization types).
@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}
@node Defining New Types
@subsection Defining New Types
+@cindex customization types, define new
+@cindex define new customization types
In the previous sections we have described how to construct elaborate
type specifications for @code{defcustom}. In some cases you may want
@node Applying Customizations
@section Applying Customizations
+@cindex applying customizations
The following functions are responsible for installing the user's
customization settings for variables and faces, respectively. When
@node Custom Themes
@section Custom Themes
+@cindex 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,
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
+@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
@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''.
+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.
@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
+@defvar custom-known-themes
+The value of this variable is a list of themes loaded into Emacs.
+Each theme is represented by a Lisp symbol (the theme name). The
+default value of this variable is a list containing two dummy
+themes: @code{(user changed)}. The @code{changed} theme stores
+settings made before any Custom themes are applied (e.g., variables
+set outside of Customize). The @code{user} theme stores settings the
+user has customized and saved. Any additional themes declared with
+the @code{deftheme} macro are added to the front of this list.
+@end defvar
+
@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