From c0bc613b24b3ff40c6ea88854544e6d03070dc70 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 12 Dec 2015 15:17:14 +0200 Subject: [PATCH] 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. --- doc/emacs/package.texi | 33 ++++++++++++++++++++++++++++++++- etc/NEWS | 13 ++++++++++++- lisp/emacs-lisp/package.el | 4 ++-- 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. -- 2.39.2