Document package archives in the Lisp manual.

* doc/lispref/package.texi: Update index keywords.
(Package Archives): New node contents.  Document package-x.el.

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 4129b37986ff0927632c0829f9ed8194b82138df..32d13b57ffd2bb7f72fd3e39414e6b29df188e21 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2011-03-06  Chong Yidong  <cyd@stupidchicken.com>
+
+       * package.texi: Update index keywords.
+       (Package Archives): New node contents.  Document package-x.el.
+
 2011-03-06  Juanma Barranquero  <lekktu@gmail.com>
 
        * makefile.w32-in (srcs): Add package.texi.

diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi
index 4de44fe165df7fb783861356f1de563030d7f3c7..62fbc2a9a078ecd368acfd53870c57d62eb72021 100644 (file)
--- a/doc/lispref/package.texi
+++ b/doc/lispref/package.texi
@@ -5,7 +5,8 @@
 @setfilename ../../info/package
 @node Packaging, Antinews, System Interface, Top
 @chapter Preparing Lisp code for distribution
-@cindex packaging
+@cindex package
+@cindex Lisp package
 
   Emacs provides a standard way to distribute Emacs Lisp code to
 users.  A @dfn{package} is a collection of one or more files,
@@ -24,8 +25,11 @@ put it in a @dfn{package archive} for others to download.
 
 @node Packaging Basics
 @section Packaging Basics
-@cindex packaging basics
 @cindex package attributes
+@cindex package name
+@cindex package version
+@cindex dependencies
+@cindex package dependencies
 
   A package is either a @dfn{simple package} or a @dfn{multi-file
 package}.  A simple package is stored in a package archive as a single
@@ -69,6 +73,7 @@ installing this package also automatically installs its dependencies;
 if any dependency cannot be found, the package cannot be installed.
 @end table
 
+@cindex content directory, package
   Installing a package, either via the Package Menu, or via the
 command @code{package-install-file}, creates a subdirectory of
 @code{package-user-dir} named @file{@var{name}-@var{version}}, where
@@ -78,6 +83,7 @@ package's @dfn{content directory}.  It is where Emacs puts the
 package's contents (the single Lisp file for a simple package, or the
 files extracted from a multi-file package).
 
+@cindex package autoloads
   Emacs then searches every Lisp file in the content directory for
 autoload magic comments (@pxref{Autoload}).  These autoload
 definitions are saved to a file named @file{@var{name}-autoloads.el}
@@ -98,7 +104,8 @@ typically called to begin using the package.
 
 @node Simple Packages
 @section Simple Packages
-@cindex single file packages
+@cindex single file package
+@cindex simple package
 
   A simple package consists of a single Emacs Lisp source file.  The
 file must conform to the Emacs Lisp library header conventions
@@ -160,7 +167,7 @@ single-file package to a package archive.
 
 @node Multi-file Packages
 @section Multi-file Packages
-@cindex multi-file packages
+@cindex multi-file package
 
   A multi-file package is less convenient to create than a single-file
 package, but it offers more features: it can include multiple Emacs
@@ -206,10 +213,10 @@ file is used as the long description.
   If the content directory contains a file named @file{dir}, this is
 assumed to be an Info directory file made with @command{install-info}.
 @xref{Invoking install-info, Invoking install-info, Invoking
-install-info, texinfo, Texinfo}.  The Info files listed in this
-directory file should also be present in the content directory.  In
-this case, Emacs will automatically add the content directory to
-@code{Info-directory-list} when the package is activated.
+install-info, texinfo, Texinfo}.  The relevant Info files should also
+be present in the content directory.  In this case, Emacs will
+automatically add the content directory to @code{Info-directory-list}
+when the package is activated.
 
   Do not include any @file{.elc} files in the package.  Those are
 created when the package is installed.  Note that there is no way to
@@ -234,5 +241,79 @@ variable @code{load-file-name} (@pxref{Loading}).  Here is an example:
 
 @node Package Archives
 @section Creating and Maintaining Package Archives
-
-To be done.
+@cindex package archive
+
+  Via the Package Menu, users may download packages from @dfn{package
+archives}.  Such archives are specified by the variable
+@code{package-archives}, whose default value contains a single entry:
+the archive hosted by the GNU project at @url{elpa.gnu.org}.  This
+section describes how to set up and maintain a package archive.
+
+@cindex base location, package archive
+@defopt package-archives
+The value of this variable is an alist of package archives recognized
+by the Emacs package manager.
+
+Each alist element corresponds to one archive, and should have the
+form @code{(@var{id} . @var{location})}, where @var{id} is the name of
+the archive (a string) and @var{location} is its @dfn{base location}
+(a string).
+
+If the base location starts with @samp{http:}, it is treated as a HTTP
+URL, and packages are downloaded from this archive via HTTP (as is the
+case for the default GNU archive).
+
+Otherwise, the base location should be a directory name.  In this
+case, Emacs retrieves packages from this archive via ordinary file
+access.  Such ``local'' archives are mainly useful for testing.
+@end defopt
+
+  A package archive is simply a directory in which the package files,
+and associated files, are stored.  If you want the archive to be
+reachable via HTTP, this directory must be accessible to a web server.
+How to accomplish this is beyond the scope of this manual.
+
+  A convenient way to set up and update a package archive is via the
+@code{package-x} library.  This is included with Emacs, but not loaded
+by default; type @kbd{M-x load-library @kbd{RET} package-x @kbd{RET}}
+to load it, or add @code{(require 'package-x)} to your init file.
+@xref{Lisp Libraries,, Lisp Libraries, emacs, The GNU Emacs Manual}.
+Once loaded, you can make use of the following:
+
+@defopt package-archive-upload-base
+The value of this variable is the base location of a package archive,
+as a directory name.  The commands in the @code{package-x} library
+will use this base location.
+
+The directory name should be absolute.  You may specify a remote name,
+such as @file{/ssh:foo@@example.com:/var/www/packages/}, if the
+package archive is on a different machine.  @xref{Remote Files,,
+Remote Files, emacs, The GNU Emacs Manual}.
+@end defopt
+
+@deffn Command package-upload-file filename
+This command prompts for @var{filename}, a file name, and uploads that
+file to @code{package-archive-upload-base}.  The file must be either a
+simple package (a @file{.el} file) or a multi-file package (a
+@file{.tar} file); otherwise, an error is raised.  The package
+attributes are automatically extracted, and the archive's contents
+list is updated with this information.
+
+If @code{package-archive-upload-base} does not specify a valid
+directory, the function prompts interactively for one.  If the
+directory does not exist, it is created.  The directory need not have
+any initial contents (i.e., you can use this command to populate an
+initially empty archive).
+@end deffn
+
+@deffn Command package-upload-buffer
+This command is similar to @code{package-upload-file}, but instead of
+prompting for a package file, it uploads the contents of the current
+buffer.  The current buffer must be visiting a simple package (a
+@file{.el} file) or a multi-file package (a @file{.tar} file);
+otherwise, an error is raised.
+@end deffn
+
+@noindent
+After you create an archive, remember that it is not accessible in the
+Package Menu interface unless it is in @code{package-archives}.