Merge from emacs-24; up to 2014-06-01T23:37:[email protected]

10 files changed, 175 insertions, 80 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index b65e758542..daccb5a268 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,16 @@
+2014-06-08  Glenn Morris  <[email protected]>
+
+	* ack.texi (Acknowledgments):
+	* emacs.texi (Acknowledgments): Updates.
+
+	* programs.texi (Prettifying Symbols): Remove node.
+	(Misc for Programs): Mention more briefly here.
+	* emacs.texi (Top): Update menu.
+
+	* package.texi (Package Menu, Package Installation):
+	Mention signed packages.
+	(Package Installation): Mention package-pinned-packages.
+
 2014-06-02  Glenn Morris  <[email protected]>
 
 	* ack.texi (Acknowledgments): Remove some obsolete items.
diff --git a/doc/emacs/ack.texi b/doc/emacs/ack.texi
index 93fc51f718..9f2496da26 100644
--- a/doc/emacs/ack.texi
+++ b/doc/emacs/ack.texi
@@ -15,7 +15,7 @@ We thank them for their generosity as well.
 
 This list is intended to mention every contributor of a major package or
 feature we currently distribute; if you know of someone we have omitted,
-please report that as a manual bug.  More comprehensive information is
+please make a bug report.  More comprehensive information is
 available in the @file{ChangeLog} files, summarized in the file
 @file{etc/AUTHORS} in the distribution.
 
@@ -51,12 +51,12 @@ files.
 @item
 Michael Albinus wrote @file{dbus.el}, a package that implements the
 D-Bus message bus protocol; @file{zeroconf.el}, a mode for browsing
-Avahi services;
-and @file{secrets.el}, an interface to keyring daemons for
-storing confidential data.  He and Kai Großjohann wrote the Tramp package, which
-provides transparent remote file editing using rcp, ssh, ftp, and
-other network protocols.  He and Daniel Pittman wrote
-@file{tramp-cache.el}.
+Avahi services; @file{secrets.el}, an interface to keyring daemons for
+storing confidential data; and @file{filenotify.el} and the associated
+low-level interface routines, for watching file status changes.
+He and Kai Großjohann wrote the Tramp package, which provides
+transparent remote file editing using ssh, ftp, and other network
+protocols.  He and Daniel Pittman wrote @file{tramp-cache.el}.
 
 @item
 Ralf Angeli wrote @file{scroll-lock.el}, a minor mode which keeps the
@@ -88,7 +88,8 @@ moving the mouse in particular patterns.
 @item
 Juanma Barranquero wrote @file{emacs-lock.el} (based on the original
 version by Tom Wurgler), which makes it harder to exit with valuable
-buffers unsaved.  He also made many other contributions to other
+buffers unsaved; and @file{frameset.el}, for saving and restoring the
+frame/window setup.  He also made many other contributions to other
 areas, including MS Windows support.
 
 @item
@@ -203,7 +204,9 @@ for Korean Hanja.
 
 @item
 Andrew Choi and Yamamoto Mitsuharu wrote the Carbon support, used
-prior to Emacs 23 for Mac OS.
+prior to Emacs 23 for Mac OS.  Yamamoto Mitsuharu continued to
+contribute to Mac OS support in the newer Nextstep port; and also
+improved support for multi-monitor displays.
 
 @item
 Chong Yidong was the Emacs co-maintainer from Emacs 23 to 24.3.  He made many
@@ -350,6 +353,10 @@ Gary Foster wrote @file{scroll-all.el}, a mode for scrolling several buffers
 together.
 
 @item
+Romain Francoise contributed ACL (Access Control List) support,
+for preserving extended file attributes on backup and copy.
+
+@item
 Noah Friedman wrote @file{rlogin.el}, an interface to Rlogin,
 @file{type-break.el}, which reminds you to take periodic breaks from
 typing, and @code{eldoc-mode}, a mode to show the defined parameters or
@@ -510,13 +517,14 @@ Emacs, including: @file{dns.el} for Domain Name Service lookups;
 @file{time-date.el} for general date and time handling.
 He also wrote @file{network-stream.el}, for opening network processes;
 @file{url-queue.el}, for controlling parallel downloads of URLs;
-and implemented libxml2 support.
+and implemented libxml2 support.  He also wrote @file{eww.el},
+an Emacs Lisp web browser; and implemented native zlib decompression.
 Components of Gnus have also been written by: Nagy Andras, David
 Blacka, Scott Byer, Ludovic Courtès, Julien Danjou, Kevin Greiner, Kai
 Großjohann, Joe Hildebrand, Paul Jarc, Simon Josefsson, Sascha
 Lüdecke, David Moore, Jim Radford, Benjamin Rutt, Raymond Scholz,
-Thomas Steffen, Reiner Steib, Didier Verna, Ilja Weis, Katsumi
-Yamaoka, Teodor Zlatanov, and others (@pxref{Contributors,,,gnus, the
+Thomas Steffen, Reiner Steib, Jan Tatarik, Didier Verna, Ilja Weis,
+Katsumi Yamaoka, Teodor Zlatanov, and others (@pxref{Contributors,,,gnus, the
 Gnus Manual}).
 
 @item
@@ -696,6 +704,10 @@ directory-local variables; and the @code{info-finder} feature that
 creates a virtual Info manual of package keywords.
 
 @item
+Leo Liu wrote @file{pcmpl-x.el}, providing completion for
+miscellaneous external tools; and revamped support for Octave in Emacs 24.4.
+
+@item
 Károly Lőrentey wrote the ``multi-terminal'' code, which allows
 Emacs to run on graphical and text terminals simultaneously.
 
@@ -840,8 +852,8 @@ client for the ``Music Player Daemon''; @file{smie.el}, a generic
 indentation engine; and @file{pcase.el}, implementing ML-style pattern
 matching.  In Emacs 24, he integrated the lexical binding code,
 cleaned up the CL namespace (making it acceptable to use CL
-functions at runtime), and added generalized variables to core Emacs
-Lisp.
+functions at runtime), added generalized variables to core Emacs
+Lisp, and implemented a new lightweight advice mechanism.
 
 @item
 Morioka Tomohiko wrote several packages for MIME support in Gnus and
@@ -1042,7 +1054,8 @@ Guillermo J. Rozas wrote @file{scheme.el}, a mode for editing Scheme and
 DSSSL code.
 
 @item
-Martin Rudalics implemented improved display-buffer handling in Emacs 24.
+Martin Rudalics implemented improved display-buffer handling in Emacs 24;
+and implemented ``pixel-wise'' resizing of windows and frames.
 
 @item
 Ivar Rummelhoff wrote @file{winner.el}, which records recent window
@@ -1390,7 +1403,8 @@ zone out in front of Emacs.
 Eli Zaretskii made many standard Emacs features work on MS-DOS and
 Microsoft Windows.  He also wrote @file{tty-colors.el}, which
 implements transparent mapping of X colors to tty colors; and
-@file{rxvt.el}.  He implemented support for bidirectional text.
+@file{rxvt.el}.  He implemented support for bidirectional text,
+and also menus on text-mode terminals.
 
 @item
 Jamie Zawinski wrote much of the support for faces and X selections.
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index d9aabb87da..e24e861b13 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -669,7 +669,6 @@ Editing Programs
 * Symbol Completion::   Completion on symbol names of your program or language.
 * MixedCase Words::     Dealing with identifiersLikeThis.
 * Semantic::            Suite of editing tools based on source code parsing.
-* Prettifying Symbols:: Display symbols as composed characters.
 * Misc for Programs::   Other Emacs features useful for editing programs.
 * C Modes::             Special commands of C, C++, Objective-C,
                           Java, IDL, Pike and AWK modes.
@@ -1366,12 +1365,14 @@ USA
 @node Acknowledgments
 @unnumberedsec Acknowledgments
 
+@c It's hard to update this fairly.
+@c I wonder if it would be better to drop it in favor of AUTHORS?
 Contributors to GNU Emacs include Jari Aalto, Per Abrahamsen, Tomas
 Abrahamsson, Jay K. Adams, Alon Albert, Michael Albinus, Nagy
 Andras, Benjamin Andresen, Ralf Angeli, Dmitry Antipov, Joe Arceneaux, Emil Åström,
 Miles Bader, David Bakhash, Juanma Barranquero, Eli Barzilay, Thomas
 Baumann, Steven L. Baur, Jay Belanger, Alexander L. Belikoff,
-Thomas Bellman, Scott Bender, Boaz Ben-Zvi, Sergey Berezin, Karl
+Thomas Bellman, Scott Bender, Boaz Ben-Zvi, Sergey Berezin, Stephen Berman, Karl
 Berry, Anna M. Bigatti, Ray Blaak, Martin Blais, Jim Blandy, Johan
 Bockgård, Jan Böcker, Joel Boehland, Lennart Borgman, Per Bothner,
 Terrence Brannon, Frank Bresz, Peter Breton, Emmanuel Briot, Kevin
@@ -1391,13 +1392,13 @@ Eglen, Christian Egli, Torbjörn Einarsson, Tsugutomo Enami, David
 Engster, Hans Henrik Eriksen, Michael Ernst, Ata Etemadi, Frederick
 Farnbach, Oscar Figueiredo, Fred Fish, Steve Fisk, Karl Fogel, Gary
 Foster, Eric S. Fraga, Romain Francoise, Noah Friedman, Andreas
-Fuchs, Shigeru Fukaya, Hallvard Furuseth, Keith Gabryelski, Peter S.
+Fuchs, Shigeru Fukaya, Xue Fuqiao, Hallvard Furuseth, Keith Gabryelski, Peter S.
 Galbraith, Kevin Gallagher, Fabián E. Gallina, Kevin Gallo, Juan León Lahoz García,
 Howard Gayle, Daniel German, Stephen Gildea, Julien Gilles, David
 Gillespie, Bob Glickstein, Deepak Goel, David De La Harpe Golden, Boris
 Goldowsky, David Goodger, Chris Gray, Kevin Greiner, Michelangelo Grigni, Odd
 Gripenstam, Kai Großjohann, Michael Gschwind, Bastien Guerry, Henry
-Guillaume, Doug Gwyn, Bruno Haible, Ken'ichi Handa, Lars Hansen, Chris
+Guillaume, Dmitry Gutov, Doug Gwyn, Bruno Haible, Ken'ichi Handa, Lars Hansen, Chris
 Hanson, Jesper Harder, Alexandru Harsanyi, K. Shane Hartman, John
 Heidemann, Jon K. Hellan, Magnus Henoch, Markus Heritsch, Dirk
 Herrmann, Karl Heuer, Manabu Higashida, Konrad Hinsen, Anders Holst,
@@ -1415,14 +1416,14 @@ Ryszard Kubiak, Igor Kuzmin, David Kågedal, Daniel LaLiberte, Karl
 Landstrom, Mario Lang, Aaron Larson, James R. Larus, Vinicius Jose
 Latorre, Werner Lemberg, Frederic Lepied, Peter Liljenberg, Christian
 Limpach, Lars Lindberg, Chris Lindblad, Anders Lindgren, Thomas Link,
-Juri Linkov, Francis Litterio, Sergey Litvinov, Emilio C. Lopes,
+Juri Linkov, Francis Litterio, Sergey Litvinov, Leo Liu, Emilio C. Lopes,
 Martin Lorentzon, Dave Love, Eric Ludlam, Károly Lőrentey, Sascha
 Lüdecke, Greg McGary, Roland McGrath, Michael McNamara, Alan Mackenzie,
 Christopher J. Madsen, Neil M. Mager, Ken Manheimer, Bill Mann,
 Brian Marick, Simon Marshall, Bengt Martensson, Charlie Martin,
 Yukihiro Matsumoto, Tomohiro Matsuyama, David Maus, Thomas May, Will Mengarini, David
 Megginson, Stefan Merten, Ben A. Mesander, Wayne Mesard, Brad
-Miller, Lawrence Mitchell, Richard Mlynarik, Gerd Möllmann, Stefan
+Miller, Lawrence Mitchell, Richard Mlynarik, Gerd Möllmann, Dani Moncayo, Stefan
 Monnier, Keith Moore, Jan Moringen, Morioka Tomohiko, Glenn Morris,
 Don Morrison, Diane Murray, Riccardo Murri, Sen Nagata, Erik Naggum,
 Gergely Nagy, Nobuyoshi Nakada, Thomas Neumann, Mike Newton, Thien-Thi Nguyen,
@@ -1453,7 +1454,7 @@ South, Andre Spiegel, Michael Staats, Thomas Steffen, Ulf Stegemann,
 Reiner Steib, Sam Steingold, Ake Stenhoff, Peter Stephenson, Ken
 Stevens, Andy Stewart, Jonathan Stigelman, Martin Stjernholm, Kim F.
 Storm, Steve Strassmann, Christopher Suckling, Olaf Sylvester, Naoto
-Takahashi, Steven Tamm, Luc Teirlinck, Jean-Philippe Theberge, Jens
+Takahashi, Steven Tamm, Jan Tatarik, Luc Teirlinck, Jean-Philippe Theberge, Jens
 T. Berger Thielemann, Spencer Thomas, Jim Thompson, Toru Tomabechi,
 David O'Toole, Markus Triska, Tom Tromey, Enami Tsugutomo, Eli
 Tziperman, Daiki Ueno, Masanobu Umeda, Rajesh Vaidheeswarran, Neil
diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index dee1210086..90bdafe456 100644
--- a/doc/emacs/package.texi
+++ b/doc/emacs/package.texi
@@ -59,8 +59,9 @@ 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).
 
 The status can also be @samp{new}.  This is equivalent to
 @samp{available}, except that it means the package became newly
@@ -167,6 +168,48 @@ 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}.
+@c Uncomment this if it becomes true.
+@ignore
+The public key for the GNU package archive is distributed with Emacs,
+in the @file{etc/package-keyring.gpg}.  Emacs uses it automatically.
+@end ignore
+
+@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
diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 82bde75490..05008790b4 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -38,7 +38,6 @@ Highlight program syntax (@pxref{Font Lock}).
 * Symbol Completion::   Completion on symbol names of your program or language.
 * MixedCase Words::     Dealing with identifiersLikeThis.
 * Semantic::            Suite of editing tools based on source code parsing.
-* Prettifying Symbols:: Display symbols as composed characters.
 * Misc for Programs::   Other Emacs features useful for editing programs.
 * C Modes::             Special commands of C, C++, Objective-C, Java,
                           IDL, Pike and AWK modes.
@@ -1434,37 +1433,6 @@ is idle.
 @xref{Top, Semantic,, semantic, Semantic}, for details.
 @end ifnottex
 
-@node Prettifying Symbols
-@section Prettifying Symbols
-@cindex prettifying symbols
-@cindex symbol, prettifying
-
-@code{prettify-symbols-mode} and @code{global-prettify-symbols-mode}
-are two minor modes (@pxref{Minor Modes}) that can display specified
-symbols as composed characters.  For instance, in Emacs Lisp mode
-(@pxref{Lisp Eval}), this mode will replace the string ``lambda'' with
-the Greek lambda character.
-
-@findex prettify-symbols-mode
-@vindex prettify-symbols-alist
-When Prettify Symbols mode and Font Lock mode (@pxref{Font Lock}) are
-enabled, symbols are prettified (displayed as composed characters)
-according to the rules in @code{prettify-symbols-alist}, which are
-locally defined by major modes (@pxref{Major Modes}) supporting
-prettifying.  To add further customizations for a given major mode,
-you can modify @code{prettify-symbols-alist}.  For example:
-
-@example
-(add-hook 'emacs-lisp-mode-hook
-	  (lambda ()
-	    (push '("<=" . ?≤) prettify-symbols-alist)))
-@end example
-
-@findex global-prettify-symbols-mode
-You can enable this mode locally in desired buffers, or use
-@code{global-prettify-symbols-mode} to enable it for all modes that
-support it.
-
 @node Misc for Programs
 @section Other Features Useful for Editing Programs
 
@@ -1512,6 +1480,17 @@ with the Foldout package (@pxref{Foldout}).
 @xref{Top,,Autotyping, autotype, Autotyping}.
 @end ifinfo
 
+@findex prettify-symbols-mode
+  Prettify Symbols mode is a buffer-local minor mode that replaces
+certain strings with more ``attractive'' versions for display
+purposes.  For example, in Emacs Lisp mode, it replaces the string
+``lambda'' with the Greek lambda character.  You may wish to use this
+in non-programming modes as well.  You can customize the mode by
+adding more entries to @code{prettify-symbols-alist}.  There is also a
+global version, @code{global-prettify-symbols-mode}, which enables the
+mode in all buffers that support it.
+
+
 @node C Modes
 @section C and Related Modes
 @cindex C mode
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index fcfef71a1f..74557361ea 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,15 @@
+2014-06-08  Glenn Morris  <[email protected]>
+
+	* display.texi (Window Systems): Remove window-setup-hook.
+	* os.texi (Startup Summary, Init File):
+	Improve description of window-setup-hook.
+	(Terminal-Specific): Update window-setup-hook cross-reference.
+	* hooks.texi (Standard Hooks): Update window-setup-hook cross-reference.
+
+	* display.texi (Overlay Properties): Update re priority.  (Bug#17234)
+
+	* package.texi (Package Archives): Mention signing packages.
+
 2014-06-07  Eli Zaretskii  <[email protected]>
 
 	* commands.texi (Click Events): Update contents of click event's
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index e93f9ab5a4..b4f987bb2a 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1515,9 +1515,9 @@ of them:
 @table @code
 @item priority
 @kindex priority @r{(overlay property)}
-This property's value determines the priority of the overlay.  No priority, or
-@code{nil}, means zero.  A non-nil and non-integer value has
-undefined behavior.
+This property's value determines the priority of the overlay.
+If you want to specify a priority value, use either @code{nil}
+(or zero), or a positive integer.  Any other value has undefined behavior.
 
 The priority matters when two or more overlays cover the same
 character and both specify the same property; the one whose
@@ -1527,9 +1527,13 @@ completely override the other value; instead, its face attributes
 override the face attributes of the lower priority @code{face}
 property.
 
-Currently, all overlays take priority over text properties.  Please
-avoid using negative priority values, as we have not yet decided just
-what they should mean.
+Currently, all overlays take priority over text properties.
+
+Note that Emacs sometimes uses non-numeric priority values for some of
+its internal overlays, so do not try to do arithmetic on the
+priority of an overlay (unless it is one that you created).  If you
+need to put overlays in priority order, use the @var{sorted} argument
+of @code{overlays-at}.  @xref{Finding Overlays}.
 
 @item window
 @kindex window @r{(overlay property)}
@@ -6515,18 +6519,6 @@ indicator of Emacs capabilities on a given display type.  Instead, use
 @code{display-graphic-p} or any of the other @code{display-*-p}
 predicates described in @ref{Display Feature Testing}.
 
-@defvar window-setup-hook
-This variable is a normal hook which Emacs runs after handling the
-initialization files.  Emacs runs this hook after it has completed
-loading your init file, the default initialization file (if
-any), and the terminal-specific Lisp code, and running the hook
-@code{emacs-startup-hook}.
-
-This hook is used for internal purposes: setting up communication with
-the window system, and creating the initial window.  Users should not
-interfere with it.
-@end defvar
-
 @node Bidirectional Display
 @section Bidirectional Display
 @cindex bidirectional display
diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi
index 9408174872..547a2ffe44 100644
--- a/doc/lispref/hooks.texi
+++ b/doc/lispref/hooks.texi
@@ -55,6 +55,7 @@ not exactly a hook, but does a similar job.
 @item after-init-hook
 @itemx before-init-hook
 @itemx emacs-startup-hook
+@itemx window-setup-hook
 @xref{Init File}.
 
 @item after-insert-file-functions
@@ -220,9 +221,6 @@ Hook run when about to switch windows with a mouse command.
 @itemx window-size-change-functions
 @xref{Window Hooks}.
 
-@item window-setup-hook
-@xref{Window Systems}.
-
 @item window-text-change-functions
 @vindex window-text-change-functions
 Functions to call in redisplay when text in the window might change.
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index b63b932b4d..04c7adda24 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -218,7 +218,9 @@ parameters of the selected frame according to whatever the init files
 specify.
 
 @item
-It runs @code{window-setup-hook}.  @xref{Window Systems}.
+It runs @code{window-setup-hook}.  The only difference between this
+hook and @code{emacs-startup-hook} is that this one runs after the
+previously mentioned modifications to the frame parameters.
 
 @item
 @cindex startup screen
@@ -411,6 +413,12 @@ This normal hook is run, once, just after handling the command line
 arguments.  In batch mode, Emacs does not run this hook.
 @end defvar
 
+@defvar window-setup-hook
+This normal hook is very similar to @code{emacs-startup-hook}.
+The only difference is that it runs slightly later, after setting
+of the frame parameters.  @xref{Startup Summary, window-setup-hook}.
+@end defvar
+
 @defvar user-init-file
 This variable holds the absolute file name of the user's init file.  If the
 actual init file loaded is a compiled file, such as @file{.emacs.elc},
@@ -497,7 +505,7 @@ hook runs after loading your init file (if applicable) and the
 terminal-specific Lisp file, so you can use it to adjust the
 definitions made by that file.
 
-For a related feature, @pxref{Window Systems, window-setup-hook}.
+For a related feature, @pxref{Init File, window-setup-hook}.
 @end defvar
 
 @node Command-Line Arguments
diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi
index 4bc50b2358..c92497a8ce 100644
--- a/doc/lispref/package.texi
+++ b/doc/lispref/package.texi
@@ -342,3 +342,38 @@ otherwise, an error is raised.
 @noindent
 After you create an archive, remember that it is not accessible in the
 Package Menu interface unless it is in @code{package-archives}.
+
+@cindex package archive security
+@cindex package signing
+Maintaining a public package archive entails a degree of responsibility.
+When Emacs users install packages from your archive, those packages
+can cause Emacs to run arbitrary code with the permissions of the
+installing user.  (This is true for Emacs code in general, not just
+for packages.)  So you should ensure that your archive is
+well-maintained and keep the hosting system secure.
+
+  One way to increase the security of your packages is to @dfn{sign}
+them using a cryptographic key.  If you have generated a
+private/public gpg key pair, you can use gpg to sign the package like
+this:
+
+@c FIXME EasyPG / package-x way to do this.
+@example
+gpg -ba -o @var{file}.sig @var{file}
+@end example
+
+@noindent
+For a single-file package, @var{file} is the package Lisp file;
+for a multi-file package, it is the package tar file.
+You can also sign the archive's contents file in the same way.
+Make the @file{.sig} files available in the same location as the packages.
+You should also make your public key available for people to download;
+e.g., by uploading it to a key server such as @url{http://pgp.mit.edu/}.
+When people install packages from your archive, they can use
+your public key to verify the signatures.
+
+A full explanation of these matters is outside the scope of this
+manual.  For more information on cryptographic keys and signing,
+@pxref{Top,, GnuPG, gnupg, The GNU Privacy Guard Manual}.  Emacs comes
+with an interface to GNU Privacy Guard, @pxref{Top,, EasyPG, epa,
+Emacs EasyPG Assistant Manual}.