X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/699c782b7668c44d0fa4446331b0590a6d5dac82..d7f413b893012eb5c9c93cd724008c2c1faae56f:/doc/emacs/package.texi

diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index 91b25cfa00..1af90edd95 100644
--- a/doc/emacs/package.texi
+++ b/doc/emacs/package.texi
@@ -1,6 +1,6 @@
 @c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012
-@c   Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software
+@c Foundation, Inc.
 @c See file emacs.texi for copying conditions.
 @node Packages
 @chapter Emacs Lisp Packages
@@ -14,7 +14,7 @@ Emacs includes a facility that lets you easily download and install
 separate Emacs Lisp program, sometimes including other components such
 as an Info manual.
 
-  @kbd{M-x list-packages} brings up a buffer named @samp{*Packages*}
+  @kbd{M-x list-packages} brings up a buffer named @file{*Packages*}
 with a list of all packages.  You can install or uninstall packages
 via this buffer.  @xref{Package Menu}.
 
@@ -52,18 +52,23 @@ on each line, with the following information:
 
 @itemize @bullet
 @item
-The package name (e.g. @samp{auctex}).
+The package name (e.g., @samp{auctex}).
 
 @item
-The package's version number (e.g. @samp{11.86}).
+The package's version number (e.g., @samp{11.86}).
 
 @item
 The package's status---normally one of @samp{available} (can be
-downloaded from the package archive), @samp{installed}, or
-@samp{built-in} (included in Emacs by default).
+downloaded from the package archive), @samp{installed},
+@samp{unsigned} (installed, but not signed; @pxref{Package Signing}),
+or @samp{built-in} (included in Emacs by default).
 
-In some instances, the status can be @samp{held}, @samp{disabled}, or
-@samp{obsolete}.  @xref{Package Installation}.
+The status can also be @samp{new}.  This is equivalent to
+@samp{available}, except that it means the package became newly
+available on the package archive after your last invocation of
+@kbd{M-x list-packages}.  In other instances, a package may have the
+status @samp{held}, @samp{disabled}, or @samp{obsolete}.
+@xref{Package Installation}.
 
 @item
 A short description of the package.
@@ -122,6 +127,12 @@ dependencies; also, delete all packages marked with @kbd{d}
 Refresh the package list (@code{package-menu-refresh}).  This fetches
 the list of available packages from the package archive again, and
 recomputes the package list.
+
+@item f
+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}.
 @end table
 
 @noindent
@@ -157,6 +168,45 @@ directory name of the package archive.  You can alter this list if you
 wish to use third party package archives---but do so at your own risk,
 and use only third parties that you think you can trust!
 
+@anchor{Package Signing}
+@cindex package security
+@cindex package signing
+  The maintainers of package archives can increase the trust that you
+can have in their packages by @dfn{signing} them.  They generate a
+private/public pair of cryptographic keys, and use the private key to
+create a @dfn{signature file} for each package.  With the public key, you
+can use the signature files to verify who created the package, and
+that it has not been modified.  A valid signature is not a cast-iron
+guarantee that a package is not malicious, so you should still
+exercise caution.  Package archives should provide instructions
+on how you can obtain their public key.  One way is to download the
+key from a server such as @url{http://pgp.mit.edu/}.
+Use @kbd{M-x package-import-keyring} to import the key into Emacs.
+Emacs stores package keys in the @file{gnupg} subdirectory
+of @code{package-user-dir}.
+The public key for the GNU package archive is distributed with Emacs,
+in the @file{etc/package-keyring.gpg}.  Emacs uses it automatically.
+
+@vindex package-check-signature
+@vindex package-unsigned-archives
+  If the user option @code{package-check-signature} is non-@code{nil},
+Emacs attempts to verify signatures when you install packages.  If the
+option has the value @code{allow-unsigned}, you can still install a
+package that is not signed.  If you use some archives that do not sign
+their packages, you can add them to the list @code{package-unsigned-archives}.
+
+  For more information on cryptographic keys and signing,
+@pxref{Top,, Top, gnupg, The GNU Privacy Guard Manual}.
+Emacs comes with an interface to GNU Privacy Guard,
+@pxref{Top,, EasyPG, epa, Emacs EasyPG Assistant Manual}.
+
+@vindex package-pinned-packages
+  If you have more than one package archive enabled, and some of them
+offer different versions of the same package, you may find the option
+@code{package-pinned-packages} useful.  You can add package/archive
+pairs to this list, to ensure that the specified package is only ever
+downloaded from the specified archive.
+
   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