Document `rectangle-mark-mode'.

[bpt/emacs.git] / doc / emacs / package.texi

diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index 7e2aa20..dee1210 100644 (file)
--- a/doc/emacs/package.texi
+++ b/doc/emacs/package.texi
@@ -1,6 +1,6 @@
 @c This is part of the Emacs manual.
 @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
 @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.
 
 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}.
 
 with a list of all packages.  You can install or uninstall packages
 via this buffer.  @xref{Package Menu}.
 


@@ -52,18 +52,22 @@ on each line, with the following information:
 
 @itemize @bullet
 @item
 
 @itemize @bullet
 @item

-The package name (e.g. @samp{auctex}).
+The package name (e.g., @samp{auctex}).

 
 @item
 
 @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).
 
 
 @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.
 
 @item
 A short description of the package.


@@ -122,6 +126,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.
 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
 @end table
 
 @noindent


@@ -157,25 +167,38 @@ 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!
 
 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
 
 @vindex package-enable-at-startup

-@findex package-initialize

   To disable automatic package loading, change the variable
   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
 
 @vindex package-load-list
   For finer control over package loading, you can use the variable