@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011
-@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
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}.
@findex describe-package
The command @kbd{C-h P} (@code{describe-package}) prompts for the
-name of a package, and displays a help buffer describing that
+name of a package, and displays a help buffer describing the
attributes of the package and the features that it implements.
By default, Emacs downloads packages from a @dfn{package archive}
@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).
-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.
Remove any installation or deletion mark previously added to the
current line by an @kbd{i} or @kbd{d} command.
+@item U
+Mark all package with a newer available version for ``upgrading''
+(@code{package-menu-mark-upgrades}). This places an installation mark
+on the new available versions, and a deletion mark on the old
+installed versions.
+
@item x
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.
@item r
-Refresh the package list (@code{package-menu-refresh}). This also
-retrieves the list of available packages from the package archive
-again.
+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.
@end table
@noindent
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!
- Once a package is downloaded and installed, it takes effect in the
-current Emacs session. What ``taking effect'' means depends on the
-package; most packages just make some new commands available, while
-others have more wide-ranging effects on the Emacs session. For such
-information, consult the package's help buffer.
+ 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
+from package to package. Most packages just make some new commands
+available, while others have more wide-ranging effects on the Emacs
+session. For such information, consult the package's help buffer.
- By default, Emacs also automatically loads all installed packages
-(causing them to ``take effect'') in subsequent Emacs sessions. This
-happens at startup, after processing the init file (@pxref{Init
-File}). As an exception, Emacs does not load packages at startup if
-invoked with the @samp{-q} or @samp{--no-init-file} options
-(@pxref{Initial Options}).
+ By default, Emacs also automatically loads all installed packages in
+subsequent Emacs sessions. This happens at startup, after processing
+the init file (@pxref{Init File}). As an exception, Emacs does not
+load packages at startup if invoked with the @samp{-q} or
+@samp{--no-init-file} options (@pxref{Initial Options}).
@vindex package-enable-at-startup
-@findex package-initialize
To disable automatic package loading, change the variable
-@code{package-enable-at-startup} to @code{nil}. If you do this, you
-can use the command @kbd{M-x package-initialize} to load your
-packages.
+@code{package-enable-at-startup} to @code{nil}.
+
+@findex package-initialize
+ The reason automatic package loading occurs after loading the init
+file is that user options only receive their customized values after
+loading the init file, including user options which affect the
+packaging system. In some circumstances, you may want to load
+packages explicitly in your init file (usually because some other code
+in your init file depends on a package). In that case, your init file
+should call the function @code{package-initialize}. It is up to you
+to ensure that relevant user options, such as @code{package-load-list}
+(see below), are set up prior to the @code{package-initialize} call.
+You should also set @code{package-enable-at-startup} to @code{nil}, to
+avoid loading the packages again after processing the init file.
+Alternatively, you may choose to completely inhibit package loading at
+startup, and invoke the command @kbd{M-x package-initialize} to load
+your packages manually.
@vindex package-load-list
For finer control over package loading, you can use the variable