Document new features of package.el

* doc/emacs/package.texi (Package Menu): Document the 'external'
status and the new menu commands.
(Package Installation): Document archive priorities.

* lisp/emacs-lisp/package.el (package-archive-priorities): Doc fix.
(package-menu-hide-low-priority): Doc fix.

3 files changed, 46 insertions, 4 deletions

diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index 1a6a735d3ae..5f80b0afe3f 100644
--- a/doc/emacs/package.texi
+++ b/doc/emacs/package.texi
@@ -59,7 +59,12 @@ The package's version number (e.g., @samp{11.86}).
 The package's status---normally one of @samp{available} (can be
 downloaded from the package archive), @samp{installed},
 @c @samp{unsigned} (installed, but not signed; @pxref{Package Signing}),
-or @samp{built-in} (included in Emacs by default).
+or @samp{built-in} (included in Emacs by default).  The status
+@samp{external} means the package is not built-in and not from the
+directory specified by @code{package-user-dir} (@pxref{Package
+Files}).  External packages are treated much like built-in: they
+cannot be deleted through the package menu, and are not considered for
+upgrading.
 
 The status can also be @samp{new}.  This is equivalent to
 @samp{available}, except that it means the package became newly
@@ -106,7 +111,13 @@ line; typing @kbd{x} (see below) will delete the package.
 @xref{Package Files}, for information about what package deletion
 entails.
 
+@item ~
+Mark all obsolete packages for deletion
+(@code{package-menu-mark-obsolete-for-deletion}).  This marks for
+deletion all the packages whose status is @samp{obsolete}.
+
 @item u
+@itemx @key{DEL}
 Remove any installation or deletion mark previously added to the
 current line by an @kbd{i} or @kbd{d} command.
 
@@ -117,6 +128,7 @@ on the new available versions, and a deletion mark on the old
 installed versions.
 
 @item x
+@vindex package-menu-async
 Download and install all packages marked with @kbd{i}, and their
 dependencies; also, delete all packages marked with @kbd{d}
 (@code{package-menu-execute}).  This also removes the marks.
@@ -131,6 +143,14 @@ Filter the package list (@code{package-menu-filter}).  This prompts
 for a keyword (e.g., @samp{games}), then shows only the packages
 that relate to that keyword.  To restore the full package list,
 type @kbd{q}.
+
+@item H
+Permanently hide packages that match a regexp
+(@code{package-menu-hide-package}).
+
+@item (
+Toggle visibility of old versions of packages and also of versions
+from lower-priority archives (@code{package-menu-toggle-hiding}).
 @end table
 
 @noindent
@@ -205,6 +225,17 @@ offer different versions of the same package, you may find the option
 pairs to this list, to ensure that the specified package is only ever
 downloaded from the specified archive.
 
+@vindex package-archive-priorities
+@vindex package-menu-hide-low-priority
+  Another option that is useful when you have several package archives
+enabled is @code{package-archive-priorities}.  It specifies the
+priority of each archive (higher numbers specify higher priority
+archives).  By default, archives have the priority of zero, unless
+specified otherwise by this option's value.  Packages from
+lower-priority archives will not be shown in the menu, if the same
+package is available from a higher-priority archive.  (This is
+controlled by the value of @code{package-menu-hide-low-priority}.)
+
   Once a package is downloaded and installed, it is @dfn{loaded} into
 the current Emacs session.  Loading a package is not quite the same as
 loading a Lisp library (@pxref{Lisp Libraries}); its effect varies
diff --git a/etc/NEWS b/etc/NEWS
index c5eb0b47749..1f8ef358c0f 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -391,6 +391,7 @@ specified message types for the respective specified targets.
 
 ** package.el
 
++++
 *** New "external" package status.
 An external package is any installed package that's not built-in and
 not from `package-user-dir', which usually means it's from an entry in
@@ -398,14 +399,16 @@ not from `package-user-dir', which usually means it's from an entry in
 packages, in that they cannot be deleted through the package menu and
 are not considered for upgrades.
 
-The effect, is that a user can manually place a specific version of a
+The effect is that a user can manually place a specific version of a
 package inside `package-directory-list' and the package menu will
 always respect that.
 
++++
 *** If a package is available on multiple archives and one has higher
 priority (as per `package-archive-priorities') only that one is
 listed.  This can be configured with `package-menu-hide-low-priority'.
 
++++
 *** `package-menu-toggle-hiding' now toggles the hiding of packages.
 This includes the above-mentioned low-priority packages, as well as
 available packages whose version is lower than the currently installed
@@ -413,31 +416,39 @@ version (which were previously impossible to display).
 This allows users to downgrade a package if a lower version is
 available.
 
+---
 *** When filtering the package menu, keywords starting with "arc:" or
 "status:" represent package archive or status, respectively, instead
 of actual keywords.
 
+---
 *** Most functions which involve downloading information now take an
 ASYNC argument.  If it is non-nil, package.el performs the download(s)
 asynchronously.
 
+---
 *** New variable `package-menu-async' controls whether the
 package-menu uses asynchronous downloads.
 
+---
 *** `package-install-from-buffer' and `package-install-file' work on directories.
 This follows the same rules as installing from a .tar file, except the
 -pkg file is optional.
 
+---
 *** Packages which are dependencies of other packages cannot be deleted.
 The FORCE argument to `package-delete' overrides this.
 
+---
 *** New custom variable `package-selected-packages' tracks packages
 which were installed by the user (as opposed to installed as
 dependencies).  This variable can also be manually customized.
 
+---
 *** New command `package-install-user-selected-packages' installs all
 packages from `package-selected-packages' which are currently missing.
 
+---
 *** New command `package-autoremove' removes all packages which were
 installed strictly as dependencies but are no longer needed.
 
diff --git a/lisp/emacs-lisp/package.el b/lisp/emacs-lisp/package.el
index 265b1cc5485..67d78987a4f 100644
--- a/lisp/emacs-lisp/package.el
+++ b/lisp/emacs-lisp/package.el
@@ -216,7 +216,7 @@ of it available such that:
 
 This variable has three possible values:
     nil: no packages are hidden;
-    `archive': only criteria (a) is used;
+    `archive': only criterion (a) is used;
     t: both criteria are used.
 
 This variable has no effect if `package-menu--hide-packages' is
@@ -234,7 +234,7 @@ Each element has the form (ARCHIVE-ID . PRIORITY).
 
 When installing packages, the package with the highest version
 number from the archive with the highest priority is
-selected. When higher versions are available from archives with
+selected.  When higher versions are available from archives with
 lower priorities, the user has to select those manually.
 
 Archives not in this list have the priority 0.