@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1997, 1998, 1999, 2000, 2002, 2003, 2004,
-@c 2005 Free Software Foundation, Inc.
+@c 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/customize
@node Customization, Loading, Macros, Top
Link to a web page; @var{url} is a string which specifies the
@acronym{URL}. The link appears in the customization buffer as
@var{url} and invokes the WWW browser specified by
-@var{browse-url-browser-function}.
+@code{browse-url-browser-function}.
@item (emacs-commentary-link @var{library})
Link to the commentary section of a library; @var{library} is a string
This option specifies that the item was first introduced in Emacs
version @var{version}, or that its default value was changed in that
version. The value @var{version} must be a string.
+
+@item :package-version '(@var{package} . @var{version})
+This option 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}.
+
+@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
+@code{customize-package-emacs-version-alist}.
@end table
+Packages distributed as part of Emacs that use the
+@code{:package-version} keyword must also update the
+@code{customize-package-emacs-version-alist} variable.
+
+@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:
+
+@example
+(@var{package} (@var{pversion} . @var{eversion})@dots{})
+@end example
+
+For each @var{package}, which is a symbol, there are one or more
+elements that contain a package version @var{pversion} with an
+associated Emacs version @var{eversion}. These versions are strings.
+For example, the MH-E package updates this alist with the following:
+
+@smallexample
+(add-to-list 'customize-package-emacs-version-alist
+ '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1")
+ ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1")
+ ("7.4" . "22.1") ("8.0" . "22.1")))
+@end smallexample
+
+The value of @var{package} needs to be unique and it needs to match
+the @var{package} value appearing in the @code{:package-version}
+keyword. Since the user might see the value in a error message, a good
+choice is the official name of the package, such as MH-E or Gnus.
+@end defvar
+
@node Group Definitions
@section Defining Custom Groups
@defmac defgroup group members doc [keyword value]@dots{}
Declare @var{group} as a customization group containing @var{members}.
Do not quote the symbol @var{group}. The argument @var{doc} specifies
-the documentation string for the group. It should not start with a
-@samp{*} as in @code{defcustom}; that convention is for variables only.
+the documentation string for the group.
The argument @var{members} is a list specifying an initial set of
customization items to be members of the group. However, most often
Use @code{defcustom} to declare user-editable variables.
-@defmac defcustom option default doc [keyword value]@dots{}
-Declare @var{option} as a customizable user option variable. Do not
-quote @var{option}. The argument @var{doc} specifies the documentation
-string for the variable. It should often start with a @samp{*} to mark
-it as a @dfn{user option} (@pxref{Defining Variables}). Do not start
-the documentation string with @samp{*} for options which cannot or
-normally should not be set with @code{set-variable}; examples of the
-former are global minor mode options such as
-@code{global-font-lock-mode} and examples of the latter are hooks.
-
-If @var{option} is void, @code{defcustom} initializes it to
-@var{default}. @var{default} should be an expression to compute the
-value; be careful in writing it, because it can be evaluated on more
-than one occasion. You should normally avoid using backquotes in
-@var{default} because they are not expanded when editing the value,
-causing list values to appear to have the wrong structure.
+@defmac defcustom option standard doc [keyword value]@dots{}
+This construct declares @var{option} as a customizable user option
+variable. You should not quote @var{option}. The argument @var{doc}
+specifies the documentation string for the variable. There is no need
+to start it with a @samp{*}, because @code{defcustom} automatically
+marks @var{option} as a @dfn{user option} (@pxref{Defining
+Variables}).
+
+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.
+
+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.
If you specify the @code{:set} option, to make the variable take other
special actions when set through the customization buffer, the
@end defun
Internally, @code{defcustom} uses the symbol property
-@code{standard-value} to record the expression for the default value,
+@code{standard-value} to record the expression for the standard value,
and @code{saved-value} to record the value saved by the user with the
customization buffer. Both properties are actually lists whose car is
an expression which evaluates to the value.
symbol for the key.
@smallexample
-:options '("foo" ((function-item some-function) integer) "baz")
+:options '("foo" ((function-item some-function) integer)
+ "baz")
@end smallexample
Many alists use lists with two elements, instead of cons cells. For
@item (list @var{element-types}@dots{})
The value must be a list with exactly as many elements as the
-@var{element-types} you have specified; and each element must fit the
+@var{element-types} given; and each element must fit the
corresponding @var{element-type}.
For example, @code{(list integer string function)} describes a list of
For example, @code{(choice integer string)} allows either an
integer or a string.
-In the customization buffer, the user selects one of the alternatives
+In the customization buffer, the user selects an alternative
using a menu, and can then edit the value in the usual way for that
alternative.
@code{help-echo} string and may actually be a function or form evaluated
to yield a help string. If it is a function, it is called with one
argument, the widget.
-@xref{Text help-echo}.
@item :match @var{function}
Specify how to decide whether a value matches the type. The