* cus-edit.el (customize-package-emacs-version-alist): Update

docstring.
(customize-package-emacs-version): Use cdr instead of cadr now that
alists use dotted pairs.

* custom.el (defcustom): Fix docstring for :package-version.

3 files changed, 40 insertions, 12 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index b2948a5cecc..045d14192ed 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,12 @@
+2006-04-13  Bill Wohler  <wohler@newt.com>
+
+        * cus-edit.el (customize-package-emacs-version-alist): Update
+        docstring.
+        (customize-package-emacs-version): Use cdr instead of cadr now
+        that alists use dotted pairs.
+
+        * custom.el (defcustom): Fix docstring for :package-version.
+
 2006-04-13  Michael Albinus  <michael.albinus@gmx.de>
 
         * net/tramp.el (tramp-display-shell-command-buffer): New defvar.
diff --git a/lisp/cus-edit.el b/lisp/cus-edit.el
index 4de2a431392..e68d2eab293 100644
--- a/lisp/cus-edit.el
+++ b/lisp/cus-edit.el
@@ -1082,14 +1082,29 @@ Show the buffer in another window, but don't select it."
 ;; Packages will update this variable, so make it available.
 ;;;###autoload
 (defvar customize-package-emacs-version-alist nil
-  "Alist that maps packages to alists of package to Emacs versions.
-The value alists map all package versions used with
-the :package-version keyword to Emacs versions.  Packages are
-symbols and versions are strings.
-
-For example:
-  '((MH-E (\"7.4\" \"22.1\") (\"8.0\" \"22.1\"))
-    (Gnus (\"5.11\" \"22.1\")))")
+  "Alist mapping versions of Emacs to versions of a package.
+These package versions are listed in the :package-version
+keyword used in `defcustom', `defgroup', and `defface'. Its
+elements look like this:
+
+     (PACKAGE (PVERSION . EVERSION)...)
+
+For each PACKAGE, which is a symbol, there are one or more
+elements that contain a package version PVERSION with an
+associated Emacs version EVERSION.  These versions are strings.
+For example, the MH-E package updates this alist with the
+following:
+
+     (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\")))
+
+The value of PACKAGE needs to be unique and it needs to match the
+PACKAGE value appearing in the :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.")
 
 ;;;###autoload
 (defalias 'customize-changed 'customize-changed-options)
@@ -1154,7 +1169,7 @@ that were added or redefined since that version."
 
 (defun customize-package-emacs-version (symbol package-version)
   "Return Emacs version of SYMBOL.
-PACKAGE-VERSION has the form (PACKAGE VERSION).  The VERSION of
+PACKAGE-VERSION has the form (PACKAGE . VERSION).  The VERSION of
 PACKAGE is looked up in the associated list
 `customize-package-emacs-version-alist' to find the version of
 Emacs that is associated with it."
@@ -1167,9 +1182,10 @@ Emacs that is associated with it."
           ((setq package-versions (assq (car package-version)
                                         customize-package-emacs-version-alist))
            (setq emacs-version
-                 (cadr (assoc (cadr package-version) package-versions)))
+                 (cdr (assoc (cdr package-version) package-versions)))
            (unless emacs-version
-             (message "Package version of %s not found in %s" symbol
+             (message "%s version %s not found in %s" symbol
+                      (cdr package-version)
                       "customize-package-emacs-version-alist")))
           (t
            (message "Package %s neglected to update %s"
diff --git a/lisp/custom.el b/lisp/custom.el
index cd97b425038..2ac1e23ac49 100644
--- a/lisp/custom.el
+++ b/lisp/custom.el
@@ -272,11 +272,14 @@ The following common keywords are also meaningful.
         first introduced, or its default value was changed, in Emacs
         version VERSION.
 :package-version
-        VALUE should be a list with the form (PACKAGE VERSION)
+        VALUE should be a list with the form (PACKAGE . VERSION)
         specifying that the variable was first introduced, or its
         default value was changed, in PACKAGE version VERSION.  This
         keyword takes priority over :version.  The PACKAGE and VERSION
         must appear in the alist `customize-package-emacs-version-alist'.
+        Since 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.
 :tag LABEL
         Use LABEL, a string, instead of the item's name, to label the item
         in customization menus and buffers.