@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")
@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.
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
+@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
+@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
+@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
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)
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