[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/trunk r105579: Document package manager in
From: |
Chong Yidong |
Subject: |
[Emacs-diffs] /srv/bzr/emacs/trunk r105579: Document package manager in Emacs manual. |
Date: |
Fri, 26 Aug 2011 11:48:19 -0400 |
User-agent: |
Bazaar (2.3.1) |
------------------------------------------------------------
revno: 105579
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Fri 2011-08-26 11:48:19 -0400
message:
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.
added:
doc/emacs/package.texi
modified:
doc/emacs/ChangeLog
doc/emacs/Makefile.in
doc/emacs/custom.texi
doc/emacs/emacs.texi
doc/emacs/help.texi
doc/emacs/makefile.w32-in
doc/emacs/misc.texi
doc/emacs/trouble.texi
etc/NEWS
=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog 2011-08-25 16:30:46 +0000
+++ b/doc/emacs/ChangeLog 2011-08-26 15:48:19 +0000
@@ -1,3 +1,11 @@
+2011-08-26 Chong Yidong <address@hidden>
+
+ * package.texi: New file, documenting the package manager.
+
+ * emacs.texi: Include it.
+
+ * help.texi (Help Summary): Add describe-package.
+
2011-08-25 Chong Yidong <address@hidden>
* misc.texi (Printing): Convert subnodes into subsections.
=== modified file 'doc/emacs/Makefile.in'
--- a/doc/emacs/Makefile.in 2011-07-10 04:05:33 +0000
+++ b/doc/emacs/Makefile.in 2011-08-26 15:48:19 +0000
@@ -96,6 +96,7 @@
${srcdir}/dired.texi \
${srcdir}/calendar.texi \
${srcdir}/misc.texi \
+ ${srcdir}/package.texi \
${srcdir}/custom.texi \
${srcdir}/trouble.texi \
${srcdir}/cmdargs.texi \
=== modified file 'doc/emacs/custom.texi'
--- a/doc/emacs/custom.texi 2011-07-13 21:38:56 +0000
+++ b/doc/emacs/custom.texi 2011-08-26 15:48:19 +0000
@@ -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.
address@hidden Customization, Quitting, Amusements, Top
address@hidden Customization
@chapter Customization
@cindex customization
=== modified file 'doc/emacs/emacs.texi'
--- a/doc/emacs/emacs.texi 2011-08-25 16:30:46 +0000
+++ b/doc/emacs/emacs.texi 2011-08-26 15:48:19 +0000
@@ -212,6 +212,7 @@
* 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 @@
@include rmail.texi
@c Includes picture-xtra.texi
@include misc.texi
address@hidden package.texi
@include custom.texi
@include trouble.texi
=== modified file 'doc/emacs/help.texi'
--- a/doc/emacs/help.texi 2011-07-15 15:46:28 +0000
+++ b/doc/emacs/help.texi 2011-08-26 15:48:19 +0000
@@ -126,16 +126,20 @@
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
address@hidden command.
address@hidden 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
=== modified file 'doc/emacs/makefile.w32-in'
--- a/doc/emacs/makefile.w32-in 2011-07-10 18:35:59 +0000
+++ b/doc/emacs/makefile.w32-in 2011-08-26 15:48:19 +0000
@@ -88,6 +88,7 @@
$(srcdir)/dired.texi \
$(srcdir)/calendar.texi \
$(srcdir)/misc.texi \
+ $(srcdir)/package.texi \
$(srcdir)/custom.texi \
$(srcdir)/trouble.texi \
$(srcdir)/cmdargs.texi \
=== modified file 'doc/emacs/misc.texi'
--- a/doc/emacs/misc.texi 2011-08-25 16:30:46 +0000
+++ b/doc/emacs/misc.texi 2011-08-26 15:48:19 +0000
@@ -2513,7 +2513,7 @@
find the one you select (@code{ffap-menu}).
@end table
address@hidden Amusements, Customization, Hyperlinking, Top
address@hidden Amusements, Packages, Hyperlinking, Top
@section Other Amusements
@cindex boredom
=== added file 'doc/emacs/package.texi'
--- a/doc/emacs/package.texi 1970-01-01 00:00:00 +0000
+++ b/doc/emacs/package.texi 2011-08-26 15:48:19 +0000
@@ -0,0 +1,230 @@
address@hidden This is part of the Emacs manual.
address@hidden Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011
address@hidden Free Software Foundation, Inc.
address@hidden See file emacs.texi for copying conditions.
address@hidden Packages
address@hidden Emacs Lisp Packages
address@hidden Package
address@hidden Emacs Lisp package archive
address@hidden Package archive
address@hidden Emacs Lisp package
+
+Emacs includes a facility that lets you easily download and install
address@hidden 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}.
+
address@hidden 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}.
+
address@hidden
+* Package Menu:: Buffer for viewing and managing packages.
+* Package Installation:: Options for package installation.
+* Package Files:: Where packages are installed.
address@hidden menu
+
address@hidden Package Menu
address@hidden The Package Menu Buffer
address@hidden package menu
address@hidden built-in package
address@hidden 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:
+
address@hidden @bullet
address@hidden
+The package name (e.g. @samp{auctex}).
+
address@hidden
+The package's version number (e.g. @samp{11.86}).
+
address@hidden
+The package's status---normally one of @samp{available} (can be
+downloaded from the package archive), @samp{installed}, or
address@hidden (included in Emacs by default).
+
+In some instances, the status can be @samp{held}, @samp{disabled}, or
address@hidden @xref{Package Installation}.
+
address@hidden
+A short description of the package.
address@hidden itemize
+
address@hidden
+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:
+
address@hidden @kbd
address@hidden h
+Print a short message summarizing how to use the package menu
+(@code{package-menu-quick-help}).
+
address@hidden ?
address@hidden @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}).
+
address@hidden i
+Mark the package on the current line for installation
+(@code{package-menu-mark-install}). If the package status is
address@hidden, this adds an @samp{I} character to the start of the
+line; typing @kbd{x} (see below) will download and install the
+package.
+
address@hidden d
+Mark the package on the current line for deletion
+(@code{package-menu-mark-delete}). If the package status is
address@hidden, this adds a @samp{D} character to the start of the
+line; typing @kbd{x} (see below) will delete the package.
address@hidden Files}, for information about what package deletion
+entails.
+
address@hidden u
+Remove any installation or deletion mark previously added to the
+current line by an @kbd{i} or @kbd{d} command.
+
address@hidden 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.
+
address@hidden r
+Refresh the package list (@code{package-menu-refresh}). This also
+retrieves the list of available packages from the package archive
+again.
address@hidden table
+
address@hidden
+For example, you can install a package by typing @kbd{i} on the line
+listing that package, followed by @kbd{x}.
+
address@hidden Package Installation
address@hidden Package Installation
+
address@hidden 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
address@hidden status, then downloads and installs it.
+
address@hidden 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.
+
address@hidden 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
address@hidden(@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}).
+
address@hidden package-enable-at-startup
address@hidden package-initialize
+ To disable automatic package loading, change the variable
address@hidden to @code{nil}. If you do this, you
+can use the command @kbd{M-x package-initialize} to load your
+packages.
+
address@hidden package-load-list
+ For finer control over package loading, you can use the variable
address@hidden 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,
address@hidden 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
address@hidden 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.
+
address@hidden Package Files
address@hidden Package Files and Directory Layout
address@hidden package directory
+
address@hidden package file
address@hidden 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}.
+
address@hidden 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 @address@hidden@var{version}}, where
address@hidden is the package name and @var{version} is its version
+string.
+
address@hidden system-wide packages
address@hidden 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.
=== modified file 'doc/emacs/trouble.texi'
--- a/doc/emacs/trouble.texi 2011-07-14 18:37:53 +0000
+++ b/doc/emacs/trouble.texi 2011-08-26 15:48:19 +0000
@@ -15,7 +15,7 @@
@raisesections
@end ifnottex
address@hidden Quitting, Lossage, Customization, Top
address@hidden Quitting
@section Quitting and Aborting
@cindex quitting
=== modified file 'etc/NEWS'
--- a/etc/NEWS 2011-08-20 22:41:41 +0000
+++ b/etc/NEWS 2011-08-26 15:48:19 +0000
@@ -319,11 +319,14 @@
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/trunk r105579: Document package manager in Emacs manual.,
Chong Yidong <=