From d43f5a423d85bdc4f3557622a828335fde06bb8a Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Fri, 26 Aug 2011 11:48:19 -0400 Subject: [PATCH] Document package manager in Emacs manual. * doc/emacs/package.texi: New file, documenting the package manager. * doc/emacs/emacs.texi: Include it. * doc/emacs/help.texi (Help Summary): Add describe-package. --- doc/emacs/ChangeLog | 8 ++ doc/emacs/Makefile.in | 1 + doc/emacs/custom.texi | 2 +- doc/emacs/emacs.texi | 2 + doc/emacs/help.texi | 12 +- doc/emacs/makefile.w32-in | 1 + doc/emacs/misc.texi | 2 +- doc/emacs/package.texi | 230 ++++++++++++++++++++++++++++++++++++++ doc/emacs/trouble.texi | 2 +- etc/NEWS | 3 + 10 files changed, 256 insertions(+), 7 deletions(-) create mode 100644 doc/emacs/package.texi diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index 9050efa83d0..f74f06e962f 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,3 +1,11 @@ +2011-08-26 Chong Yidong + + * package.texi: New file, documenting the package manager. + + * emacs.texi: Include it. + + * help.texi (Help Summary): Add describe-package. + 2011-08-25 Chong Yidong * misc.texi (Printing): Convert subnodes into subsections. diff --git a/doc/emacs/Makefile.in b/doc/emacs/Makefile.in index 9465c726eba..66cd7f1d92e 100644 --- a/doc/emacs/Makefile.in +++ b/doc/emacs/Makefile.in @@ -96,6 +96,7 @@ EMACSSOURCES= \ ${srcdir}/dired.texi \ ${srcdir}/calendar.texi \ ${srcdir}/misc.texi \ + ${srcdir}/package.texi \ ${srcdir}/custom.texi \ ${srcdir}/trouble.texi \ ${srcdir}/cmdargs.texi \ diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index 6a6d465438d..a22d6c1f5dd 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -2,7 +2,7 @@ @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. -@node Customization, Quitting, Amusements, Top +@node Customization @chapter Customization @cindex customization diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 24a7e6d62e6..060f939fa7a 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -212,6 +212,7 @@ Advanced Features * Emulation:: Emulating some other editors with Emacs. * Hyperlinking:: Following links in buffers. * Amusements:: Various games and hacks. +* Packages:: Installing additional features. * Customization:: Modifying the behavior of Emacs. Recovery from Problems @@ -1497,6 +1498,7 @@ Lisp programming. @include rmail.texi @c Includes picture-xtra.texi @include misc.texi +@include package.texi @include custom.texi @include trouble.texi diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index 9a75bfb1887..bf93892c0db 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -126,16 +126,20 @@ The complete Emacs manual is available on-line in Info. Display the name and documentation of the command that @var{key} runs (@code{describe-key}). @item C-h l -Display a description of your last 300 keystrokes +Display a description of your last 300 keystrokes (@code{view-lossage}). @item C-h m Display documentation of the current major mode (@code{describe-mode}). @item C-h n Display news of recent Emacs changes (@code{view-emacs-news}). @item C-h p -Find packages by topic keyword (@code{finder-by-keyword}). For an -alternative interface to the same information, try the @code{info-finder} -command. +Find packages by topic keyword (@code{finder-by-keyword}). This lists +packages using a package menu buffer (@pxref{Package Menu}); for an +alternative interface to the same information, try the +@code{info-finder} command. +@item C-h P @var{package} @key{RET} +Display documentation about the package named @var{package} +(@code{describe-package}; @pxref{Packages}). @item C-h r Display the Emacs manual in Info (@code{info-emacs-manual}). @item C-h s diff --git a/doc/emacs/makefile.w32-in b/doc/emacs/makefile.w32-in index 4064f4ef6a3..e128a50ebd3 100644 --- a/doc/emacs/makefile.w32-in +++ b/doc/emacs/makefile.w32-in @@ -88,6 +88,7 @@ EMACSSOURCES= \ $(srcdir)/dired.texi \ $(srcdir)/calendar.texi \ $(srcdir)/misc.texi \ + $(srcdir)/package.texi \ $(srcdir)/custom.texi \ $(srcdir)/trouble.texi \ $(srcdir)/cmdargs.texi \ diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi index e43a8adce74..2dab70c512a 100644 --- a/doc/emacs/misc.texi +++ b/doc/emacs/misc.texi @@ -2513,7 +2513,7 @@ Display a menu of files and URLs mentioned in current buffer, then find the one you select (@code{ffap-menu}). @end table -@node Amusements, Customization, Hyperlinking, Top +@node Amusements, Packages, Hyperlinking, Top @section Other Amusements @cindex boredom diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi new file mode 100644 index 00000000000..739a8ce6c65 --- /dev/null +++ b/doc/emacs/package.texi @@ -0,0 +1,230 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011 +@c Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Packages +@chapter Emacs Lisp Packages +@cindex Package +@cindex Emacs Lisp package archive +@cindex Package archive +@cindex Emacs Lisp package + +Emacs includes a facility that lets you easily download and install +@dfn{packages} that implement additional features. Each package is a +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*} +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 +attributes of the package and the features that it implements. + + By default, Emacs downloads packages from a @dfn{package archive} +maintained by the Emacs developers and hosted by the GNU project. +Optionally, you can also download packages from archives maintained by +third parties. @xref{Package Installation}. + + For information about turning an Emacs Lisp program into an +installable package, @xref{Packaging,,,elisp, The Emacs Lisp Reference +Manual}. For information about finding third-party packages and other +Emacs Lisp extensions, @xref{Packages that do not come with +Emacs,,,efaq, GNU Emacs FAQ}. + +@menu +* Package Menu:: Buffer for viewing and managing packages. +* Package Installation:: Options for package installation. +* Package Files:: Where packages are installed. +@end menu + +@node Package Menu +@section The Package Menu Buffer +@cindex package menu +@cindex built-in package +@findex list-packages + +The command @kbd{M-x list-packages} brings up the @dfn{package menu}. +This is a buffer listing all the packages that Emacs knows about, one +on each line, with the following information: + +@itemize @bullet +@item +The package name (e.g. @samp{auctex}). + +@item +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}. + +@item +A short description of the package. +@end itemize + +@noindent +The @code{list-packages} command accesses the network, to retrieve the +list of available packages from the package archive server. If the +network is unavailable, it falls back on the most recently retrieved +list. + +The following commands are available in the package menu: + +@table @kbd +@item h +Print a short message summarizing how to use the package menu +(@code{package-menu-quick-help}). + +@item ? +@itemx @key{RET} +Display a help buffer for the package on the current line +(@code{package-menu-describe-package}), similar to the help window +displayed by the @kbd{C-h P} command (@pxref{Packages}). + +@item i +Mark the package on the current line for installation +(@code{package-menu-mark-install}). If the package status is +@samp{available}, this adds an @samp{I} character to the start of the +line; typing @kbd{x} (see below) will download and install the +package. + +@item d +Mark the package on the current line for deletion +(@code{package-menu-mark-delete}). If the package status is +@samp{installed}, this adds a @samp{D} character to the start of the +line; typing @kbd{x} (see below) will delete the package. +@xref{Package Files}, for information about what package deletion +entails. + +@item u +Remove any installation or deletion mark previously added to the +current line by an @kbd{i} or @kbd{d} command. + +@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. +@end table + +@noindent +For example, you can install a package by typing @kbd{i} on the line +listing that package, followed by @kbd{x}. + +@node Package Installation +@section Package Installation + +@findex package-install + Packages are most conveniently installed using the package menu +(@pxref{Package Menu}), but you can also use the command @kbd{M-x +package-install}. This prompts for the name of a package with the +@samp{available} status, then downloads and installs it. + +@cindex package requirements + A package may @dfn{require} certain other packages to be installed, +because it relies on functionality provided by them. When Emacs +installs such a package, it also automatically downloads and installs +any required package that is not already installed. (If a required +package is somehow unavailable, Emacs signals an error and stops +installation.) A package's requirements list is shown in its help +buffer. + +@vindex package-archives + By default, packages are downloaded from a single package archive +maintained by the Emacs developers. This is controlled by the +variable @code{package-archives}, whose value is a list of package +archives known to Emacs. Each list element must have the form +@code{(@var{id} . @var{location})}, where @var{id} is the name of a +package archive and @var{location} is the @acronym{HTTP} address or +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! + + 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. + + 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}). + +@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. + +@vindex package-load-list + For finer control over package loading, you can use the variable +@code{package-load-list}. Its value should be a list. A list element +of the form @code{(@var{name} @var{version})} tells Emacs to load +version @var{version} of the package named @var{name}. Here, +@var{version} should be a version string (corresponding to a specific +version of the package), or @code{t} (which means to load any +installed version), or @code{nil} (which means no version; this +``disables'' the package, preventing it from being loaded). A list +element can also be the symbol @code{all}, which means to load the +latest installed version of any package not named by the other list +elements. The default value is just @code{'(all)}. + + For example, if you set @code{package-load-list} to @code{'((muse +"3.20") all)}, then Emacs only loads version 3.20 of the @samp{muse} +package, plus any installed version of packages other than +@samp{muse}. Any other version of @samp{muse} that happens to be +installed will be ignored. The @samp{muse} package will be listed in +the package menu with the @samp{held} status. + +@node Package Files +@section Package Files and Directory Layout +@cindex package directory + +@cindex package file +@findex package-install-file + Each package is downloaded from the package archive in the form of a +single @dfn{package file}---either an Emacs Lisp source file, or a tar +file containing multiple Emacs Lisp source and other files. Package +files are automatically retrieved, processed, and disposed of by the +Emacs commands that install packages. Normally, you will not need to +deal directly with them, unless you are making a package +(@pxref{Packaging,,,elisp, The Emacs Lisp Reference Manual}). Should +you ever need to install a package directly from a package file, use +the command @kbd{M-x package-install-file}. + +@vindex package-user-dir + Once installed, the contents of a package are placed in a +subdirectory of @file{~/.emacs.d/elpa/} (you can change the name of +that directory by changing the variable @code{package-user-dir}). The +package subdirectory is named @file{@var{name}-@var{version}}, where +@var{name} is the package name and @var{version} is its version +string. + +@cindex system-wide packages +@vindex package-directory-list + In addition to @code{package-user-dir}, Emacs looks for installed +packages in the directories listed in @code{package-directory-list}. +These directories are meant for system administrators to make Emacs +packages available system-wide; Emacs itself never installs packages +there. The package subdirectories for @code{package-directory-list} +are laid out in the same way as in @code{package-user-dir}. + + Deleting a package (@pxref{Package Menu}) involves deleting the +corresponding package subdirectory. This only works for packages +installed in @code{package-user-dir}; if told to act on a package in a +system-wide package directory, the deletion command signals an error. diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi index 4be892639fc..fd06dde5174 100644 --- a/doc/emacs/trouble.texi +++ b/doc/emacs/trouble.texi @@ -15,7 +15,7 @@ also considered. @raisesections @end ifnottex -@node Quitting, Lossage, Customization, Top +@node Quitting @section Quitting and Aborting @cindex quitting diff --git a/etc/NEWS b/etc/NEWS index cec19d0c0a2..841b11bcdb9 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -319,11 +319,14 @@ for `list-colors-display'. This is a convenient way to download and install additional packages, from a package repository at elpa.gnu.org. ++++ *** `M-x list-packages' shows a list of packages, which can be selected for installation. ++++ *** New command `describe-package', bound to `C-h P'. ++++ *** By default, all installed packages are loaded and activated automatically when Emacs starts up. To disable this, set `package-enable-at-startup' to nil. To change which packages are -- 2.39.2