(Common Keywords): Use dotted notation for :package-version value.

Improve documentation for customize-package-emacs-version-alist.

2 files changed, 30 insertions, 9 deletions

diff --git a/lispref/ChangeLog b/lispref/ChangeLog
index f844494335c..c3920786a01 100644
--- a/lispref/ChangeLog
+++ b/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2006-04-13  Bill Wohler  <wohler@newt.com>
+
+        * customize.texi (Common Keywords): Use dotted notation for
+        :package-version value. Improve documentation for
+        customize-package-emacs-version-alist.
+
 2006-04-12  Bill Wohler  <wohler@newt.com>
 
         * customize.texi (Common Keywords): Move description of
diff --git a/lispref/customize.texi b/lispref/customize.texi
index 1d0e44ae93f..42fd14ae0ef 100644
--- a/lispref/customize.texi
+++ b/lispref/customize.texi
@@ -131,12 +131,14 @@ 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})
+@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}.
+@code{customize-package-emacs-version-alist}.  Since @var{package} must
+be unique and the user might see it in an error message, a good choice
+is the official name of the package, such as MH-E or Gnus.
 
 @end table
 
@@ -144,17 +146,30 @@ Packages 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