@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-2014 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.
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 %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}
@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
HCoop / bpt / emacs.git / blobdiff