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})
+@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 default value was
-changed in that version. This keyword takes priority over :version.
-The @var{package} and @var{version} must appear in the alist
-@code{customize-package-emacs-version-alist}.
+@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 that use the @code{:package-version} keyword must also update
-the @code{customize-package-emacs-version-alist} variable.
+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 maps packages to alists that map all package versions used
-with the @code{:package-version} keyword to Emacs versions. Packages
-are symbols and versions are strings. For example, the MH-E package
-updates this alist with the following:
+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")))
+ '(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
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.