document package.el

document package.el

[Tom Tromey]

I'd appreciate comments on this patch.

I finally found a little time to write some documentation for
package.el.

Tom

2010-08-06  Tom Tromey  <tromey@redhat.com>

	* vol2.texi (Top): Update.
	* vol1.texi (Top): Update.
	* tips.texi (Library Headers): Mention Package-Version and
	Package-Requires.
	* package.texi: New file.
	* os.texi (System Interface): Update pointers.
	* elisp.texi (Top): Link to new nodes.  Include package.texi.
	* anti.texi (Antinews): Update pointers.

=== modified file 'doc/lispref/anti.texi'
--- doc/lispref/anti.texi	2010-01-13 08:35:10 +0000
+++ doc/lispref/anti.texi	2010-07-30 00:05:33 +0000
@@ -6,7 +6,7 @@
 
 @c This node must have no pointers.
 
-@node Antinews, GNU Free Documentation License, System Interface, Top
+@node Antinews, GNU Free Documentation License, Packaging, Top
 @appendix Emacs 22 Antinews
 @c Update the elisp.texi, vol1.texi, vol2.texi Antinews menu entries
 @c with the above version number.

=== modified file 'doc/lispref/elisp.texi'
--- doc/lispref/elisp.texi	2010-07-10 18:52:53 +0000
+++ doc/lispref/elisp.texi	2010-07-31 01:32:13 +0000
@@ -159,6 +159,8 @@
 * System Interface::        Getting the user id, system type, environment
                               variables, and other such things.
 
+* Packaging::               Preparing Lisp code for distribution.
+
 Appendices
 
 * Antinews::                Info for users downgrading to Emacs 22.
@@ -1394,6 +1396,12 @@
 * Session Management::      Saving and restoring state with
                               X Session Management.
 
+Preparing Lisp code for distribution
+
+* Packaging Basics::        The basic concepts of Emacs Lisp packages.
+* Simple Packages::         How to package a single .el file.
+* Multi-file Packages::     How to package multiple files.
+
 Starting Up Emacs
 
 * Startup Summary::         Sequence of actions Emacs performs at startup.
@@ -1490,6 +1498,8 @@
 @include display.texi
 @include os.texi
 
+@include package.texi
+
 @c MOVE to Emacs Manual:  include misc-modes.texi
 
 @c appendices

=== modified file 'doc/lispref/os.texi'
--- doc/lispref/os.texi	2010-07-10 18:52:53 +0000
+++ doc/lispref/os.texi	2010-07-30 00:05:24 +0000
@@ -5,7 +5,7 @@
 @c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/os
-@node System Interface, Antinews, Display, Top
+@node System Interface, Packaging, Display, Top
 @chapter Operating System Interface
 
   This chapter is about starting and getting out of Emacs, access to

=== added file 'doc/lispref/package.texi'
--- doc/lispref/package.texi	1970-01-01 00:00:00 +0000
+++ doc/lispref/package.texi	2010-08-06 22:05:47 +0000
@@ -0,0 +1,149 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 2010
+@c   Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../../info/os
+@node Packaging, Antinews, System Interface, Top
+@chapter Preparing Lisp code for distribution
+
+  Emacs provides a standard way for Emacs Lisp code to be distributed
+to users.  This approach lets users easily download, install,
+uninstall, and upgrade Lisp code that they might want to use.
+
+  A @dfn{package} is simply one or more files, formatted and bundled
+in a particular way.  Typically a package includes primarily Emacs
+Lisp code, but it is possible to create other kinds of packages as
+well, for example, a package consisting solely of documentation.
+
+@menu
+* Packaging Basics::        The basic concepts of Emacs Lisp packages.
+* Simple Packages::         How to package a single .el file.
+* Multi-file Packages::     How to package multiple files.
+@end menu
+
+@node Packaging Basics
+@section Packaging Basics
+
+  A package has a few attributes:
+
+@table @asis
+@item Name
+A string, the name of the package.
+
+@item Version
+A version number, which is a dotted list of integers, like
+@samp{1.2.0.3}.
+
+@item Brief description
+This is shown to the user in the package menu buffer.  It is just a
+single line.
+
+@item Long description
+This can be a @file{README} file or the like.  This is available to
+the user before the package is installed, via the package menu.  It
+should more fully describe the package and its capabilities, so a user
+can read it to decide whether he wants to install the package.
+
+@item Dependencies
+This is a list of other packages and their minimal acceptable
+versions.  This is used both at download time (to make sure all the
+needed code is available) and at activation time (to ensure a package
+is only activated if all its dependencies have been successfully
+activated).
+
+@item Manual
+A package can include an info manual.
+@end table
+
+  Conceptually, a package goes through several state transitions (in
+reality some of these transitions are grouped together):
+
+@table @asis
+@item Download
+Fetch the package from somewhere.
+
+@item Install
+Untar the package, or write a @file{.el} file into the appropriate
+install directory.  This step also includes extracting autoloads and
+byte-compiling the Emacs Lisp code.
+
+@item Activate
+Update @code{load-path} and @code{Info-directory-list} and evaluate
+the autoloads, so that the package is ready for the user to use.
+@end table
+
+  It is best for users if packages do not do too much work at
+activation time.  The best approach is to have activation consist of a
+some autoloads and little more.
+
+@node Simple Packages
+@section Simple Packages
+
+  The simplest package consists of a single Emacs Lisp source file.
+In this case, all the attributes of the package are taken from this
+file.
+
+  The package system expects this @file{.el} file to conform to the
+Emacs Lisp library header conventions.  See @xref{Library Headers}.
+
+  The name of the package is the same as the base name of the
+@file{.el} file, as written in the first comment line.
+
+  The short description of the package is also taken from the first
+line of the file.
+
+  If the file has a ``Commentary'' header, then it is used as the long
+description.
+
+  The version of the package comes either from the ``Package-Version''
+header, if it exists, or from the ``Version'' header.  A package is
+required to have a version number.
+
+  If the file has a ``Package-Requires'' header, then that is used as
+the package dependencies.  Otherwise, the package is assumed not to
+have any dependencies.
+
+  A single-file package cannot have an info manual.
+
+  The file will be scanned for autoload comments at install time.
+
+@node Multi-file Packages
+@section Multi-file Packages
+
+  A multi-file package is just a @file{.tar} file.  While less
+convenient to create than a single-file package, a multi-file package
+also offers more features: it can include an info manual, multiple
+Emacs Lisp files, and also other data files needed by a package.
+
+  The contents of the @file{.tar} file must all appear in a single
+directory, named after the package and version.  Also, the @file{.tar}
+file is typically also given this same name.  For example, if you are
+distributing version 1.3 of the superfrobnicator, the package file
+would be named ``superfrobnicator-1.3.tar'' and the contents would all
+appear in the directory @file{superfrobnicator-1.3} in that
+@file{.tar}.
+
+  The package must include a @file{-pkg.el} file, named after the
+package.  In our example above, this file would be called
+@file{superfrobnicator-pkg.el}.  This file must have a single form in
+it, a call to @code{define-package}.  The package dependencies and
+brief description are taken from this form.
+
+  If a @file{README} file exists in the content directory, then it is
+used as the long description.
+
+  If the package has an info manual, you should distribute the needed
+info files, plus a @file{dir} file made with @command{install-info}.
+
+  Do not include any @file{.elc} files in the package.  Those will be
+created at install time.  Note that there is no way to control the
+order in which files are byte-compiled; your package must be robust
+here.
+
+  The installation process will scan all the @file{.el} files in the
+package for autoload comments.  They are extracted into a
+@file{-autoloads.el} file (e.g.,
+@file{superfrobnicator-autoloads.el}), so do not include a file of
+that name in your package.
+

=== modified file 'doc/lispref/tips.texi'
--- doc/lispref/tips.texi	2010-06-23 03:36:56 +0000
+++ doc/lispref/tips.texi	2010-07-31 18:43:10 +0000
@@ -1052,6 +1052,31 @@
 This field is important; it's how people will find your package when
 they're looking for things by topic area.  To separate the keywords, you
 can use spaces, commas, or both.
+
+@item Package-Version
+If @samp{Version} is not suitable for use by the package manager, then
+a package can define @samp{Package-Version}; it will be used instead.
+This is handy if @samp{Version} is an RCS id or something else that is
+not a dotted list of integers.
+
+@item Package-Requires
+If this exists, it names packages on which the current package
+depends for proper operation.  This is used by the package manager
+both at download time (to ensure that a complete set of packages is
+downloaded) and at activation time (to ensure that a package is
+activated if and only if all its dependencies have been).
+
+Its format is a list of lists.  The @code{car} of each sub-list is the
+name of a package, as a symbol.  The @code{cadr} of each sub-list is
+the minimum acceptable version number, as a string.  For instance:
+
+@smallexample
+;; Package-Requires: ((gnus "1.0") (bubbles "2.7.2"))
+@end smallexample
+
+The package code automatically defines a package named @samp{eamcs}
+with the version number of the currently running Emacs.  This can be
+used to require a minimal version of Emacs for a package.
 @end table
 
   Just about every Lisp library ought to have the @samp{Author} and

=== modified file 'doc/lispref/vol1.texi'
--- doc/lispref/vol1.texi	2010-07-10 18:52:53 +0000
+++ doc/lispref/vol1.texi	2010-07-31 01:32:31 +0000
@@ -180,6 +180,8 @@
 * System Interface::        Getting the user id, system type, environment
                               variables, and other such things.
 
+* Packaging::               Preparing Lisp code for distribution.
+
 Appendices
 
 * Antinews::                Info for users downgrading to Emacs 22.
@@ -1415,6 +1417,12 @@
 * Session Management::      Saving and restoring state with
                               X Session Management.
 
+Preparing Lisp code for distribution
+
+* Packaging Basics::        The basic concepts of Emacs Lisp packages.
+* Simple Packages::         How to package a single .el file.
+* Multi-file Packages::     How to package multiple files.
+
 Starting Up Emacs
 
 * Startup Summary::         Sequence of actions Emacs performs at startup.

=== modified file 'doc/lispref/vol2.texi'
--- doc/lispref/vol2.texi	2010-07-10 18:52:53 +0000
+++ doc/lispref/vol2.texi	2010-07-31 01:32:50 +0000
@@ -179,6 +179,8 @@
 * System Interface::        Getting the user id, system type, environment
                               variables, and other such things.
 
+* Packaging::               Preparing Lisp code for distribution.
+
 Appendices
 
 * Antinews::                Info for users downgrading to Emacs 22.
@@ -1414,6 +1416,12 @@
 * Session Management::      Saving and restoring state with
                               X Session Management.
 
+Preparing Lisp code for distribution
+
+* Packaging Basics::        The basic concepts of Emacs Lisp packages.
+* Simple Packages::         How to package a single .el file.
+* Multi-file Packages::     How to package multiple files.
+
 Starting Up Emacs
 
 * Startup Summary::         Sequence of actions Emacs performs at startup.

Re: document package.el

[Phil Hagelberg]

On Fri, Aug 6, 2010 at 3:42 PM, Tom Tromey <tromey@redhat.com> wrote:
> I'd appreciate comments on this patch.
>
> I finally found a little time to write some documentation for
> package.el.

Thanks; this looks great! I've had a number of people ask me about how
multi-file packages work, so now I will point them here.

The only thing I'd note is that it doesn't mention anything about the
user-level settings that control package activation and installation.
Perhaps the defcustom docstrings are sufficient for these already?

-Phil

Re: document package.el

[Tom Tromey]

Phil> The only thing I'd note is that it doesn't mention anything about the
Phil> user-level settings that control package activation and installation.
Phil> Perhaps the defcustom docstrings are sufficient for these already?

I didn't know about those.

I took a quick look and they all seem to be for users.
This documentation is intended for people making packages.

Tom

Re: document package.el

[Christoph]

On 8/6/2010 4:42 PM, Tom Tromey wrote:

> I'd appreciate comments on this patch.
>
> I finally found a little time to write some documentation for
> package.el.

Hi Tom,

I just tried package.el for the first time and I like it a lot! This 
could save me a lot of time googling around trying to find the latest 
versions.

I have a couple of thoughts:
I am wondering, is there a way to give package.el a list of packages to 
go download from ELPA and install? I would also want it to use this list 
to check for new versions of all packages in the list. Either on startup 
or on command (M-x package-upgrade). Also, on a new installation of 
Emacs I would just tell it "Go get the packages in the list" and it 
would recreate my package configuration on that machine. All I need in 
version control is the list as part of my init.el, instead of putting 
the entire elpa/ directory under version control and deploying it to the 
new machine.

Great work!

Christoph

Re: document package.el

[Geralt]

Hi,

On Sat, Aug 7, 2010 at 3:43 AM, Christoph <cschol2112@googlemail.com> wrote:
> I have a couple of thoughts:
> I am wondering, is there a way to give package.el a list of packages to go
> download from ELPA and install? I would also want it to use this list to
> check for new versions of all packages in the list. Either on startup or on
> command (M-x package-upgrade). Also, on a new installation of Emacs I would
> just tell it "Go get the packages in the list" and it would recreate my
> package configuration on that machine. All I need in version control is the
> list as part of my init.el, instead of putting the entire elpa/ directory
> under version control and deploying it to the new machine.
>
recently I stumbled upon a package called el-get[1], it basically does
what you want, but is more general. It does not only support elpa, but
also different version control systems and websites to retrieve
packages from.


HTH,

Geralt.


[1]http://blog.tapoueh.org/articles/news/_el-get.html

Re: document package.el

[Tom Tromey]

>>>>> "Christoph" == Christoph  <cschol2112@googlemail.com> writes:

Christoph> I am wondering, is there a way to give package.el a list of
Christoph> packages to go download from ELPA and install? I would also
Christoph> want it to use this list to check for new versions of all
Christoph> packages in the list. Either on startup or on command (M-x
Christoph> package-upgrade). Also, on a new installation of Emacs I
Christoph> would just tell it "Go get the packages in the list" and it
Christoph> would recreate my package configuration on that machine.

There isn't anything like this.

I suppose it could be done with a little elisp.

Tom

Re: document package.el

[Juri Linkov]

> I am wondering, is there a way to give package.el a list of packages to go
> download from ELPA and install? I would also want it to use this list to
> check for new versions of all packages in the list. Either on startup or on
> command (M-x package-upgrade). Also, on a new installation of Emacs I would
> just tell it "Go get the packages in the list" and it would recreate my
> package configuration on that machine. All I need in version control is the
> list as part of my init.el, instead of putting the entire elpa/ directory
> under version control and deploying it to the new machine.

I guess we need something like `require',
e.g. (package-require FEATURE &optional FILENAME NOERROR).

So you could put in your .emacs:

  (package-require 'company)
  (package-require 'js2-mode)
  (package-require 'rainbow-mode)

and it will take care of installing and activating
your preferred packages on a new installation.

Re: document package.el

[Stefan Monnier]

> So you could put in your .emacs:

>   (package-require 'company)
>   (package-require 'js2-mode)
>   (package-require 'rainbow-mode)

> and it will take care of installing and activating
> your preferred packages on a new installation.

Downloading&installing packages from .emacs should not be encouraged.


        Stefan

Re: document package.el

[Christoph]

On 8/26/2010 5:50 PM, Stefan Monnier wrote:

> Downloading&installing packages from .emacs should not be encouraged.

Why?

Christoph

Re: document package.el

[Uday S Reddy]

On 8/27/2010 4:14 AM, Christoph wrote:
> On 8/26/2010 5:50 PM, Stefan Monnier wrote:
>
>> Downloading&installing packages from .emacs should not be encouraged.
>
> Why?

Because if it gets stuck, your Emacs is stuck.  A start-up file should do quick 
and safe configuration actions and return to the user so that he/she can get on 
with using it.

You are free to put whatever you want in your .emacs of course.  But that can't 
be the policy.

Cheers,
Uday

Re: document package.el

[Christoph]

On 8/26/2010 5:27 PM, Juri Linkov wrote:

> I guess we need something like `require',
> e.g. (package-require FEATURE&optional FILENAME NOERROR).
>
> So you could put in your .emacs:
>
>    (package-require 'company)
>    (package-require 'js2-mode)
>    (package-require 'rainbow-mode)
>
> and it will take care of installing and activating
> your preferred packages on a new installation.

Interesting. On each subsequent startup, after installing, it could then 
check if a new version is available and prompt for update. Of course 
that could be optional for people who don't want to be bothered with 
updating on startup.

Christoph

Re: document package.el

[Uday S Reddy]

On 8/27/2010 12:27 AM, Juri Linkov wrote:

> I guess we need something like `require',
> e.g. (package-require FEATURE&optional FILENAME NOERROR).
>
> So you could put in your .emacs:
>
>    (package-require 'company)
>    (package-require 'js2-mode)
>    (package-require 'rainbow-mode)
>
> and it will take care of installing and activating
> your preferred packages on a new installation.

Separating out the .emacs issue, I think it would indeed be a good idea to have 
the preferred-package list stored somewhere so that we can use it for new 
installations.

There is the ~/.emacs.d/elpa/archives directory.  Would it be possible to copy 
this to a new installation in order to tell package.el what to install?

To tell you the truth, I am quite unclear yet what package.el can do, not 
having seen a manual for it.  Does it exist somewhere?

Cheers,
Uday

Re: document package.el

[Phil Hagelberg]

On Fri, Aug 27, 2010 at 12:07 AM, Uday S Reddy <u.s.reddy@cs.bham.ac.uk> wrote:
> Separating out the .emacs issue, I think it would indeed be a good idea to
> have the preferred-package list stored somewhere so that we can use it for
> new installations.

I have wanted to have this functionality as well as I often copy my
.emacs config around among multiple machines and would rather have a
single step to pull in my set of preferred packages rather than
getting them one by one. If it's agreed that we want it in package.el,
I can give it a shot.

-Phil

Re: document package.el

[Tom Tromey]

>>>>> "Phil" == Phil Hagelberg <phil@hagelb.org> writes:

Phil> I have wanted to have this functionality as well as I often copy
Phil> my .emacs config around among multiple machines and would rather
Phil> have a single step to pull in my set of preferred packages rather
Phil> than getting them one by one.

FWIW, you can just rsync ~/.emacs.d/elpa/.
If you're already copying .emacs and whatever else, it isn't much more
effort.

Tom

Re: document package.el

[Uday S Reddy]

On 8/7/2010 2:43 AM, Christoph wrote:

> I have a couple of thoughts:
> I am wondering, is there a way to give package.el a list of packages to go
> download from ELPA and install? I would also want it to use this list to check
> for new versions of all packages in the list. Either on startup or on command
> (M-x package-upgrade). Also, on a new installation of Emacs I would just tell
> it "Go get the packages in the list" and it would recreate my package
> configuration on that machine. All I need in version control is the list as
> part of my init.el, instead of putting the entire elpa/ directory under version
> control and deploying it to the new machine.

I personally think that upgrading packages should be a conscious, deliberate 
action.  You never know what changes the developers have put in the upgrade and 
what those change would entail in terms of how you will use the package.

Many of the complaints we here from users about version changes stem from the 
fact that their distros or local admins do automatic updates.  The users get 
burned as a result and take it out on us.  Emacs obviously shouldn't encourage 
such irresponsible practices.  You have to hit the button to make it happen.

I will also want to install the new versions along side the old ones, so that I 
have the option of going back to the old versions if I need to.  It is not yet 
clear to me if package.el allows that.

Cheers,
Uday

Re: document package.el

[Tom Tromey]

>>>>> "Uday" == Uday S Reddy <u.s.reddy@cs.bham.ac.uk> writes:

Uday> I personally think that upgrading packages should be a conscious,
Uday> deliberate action.  You never know what changes the developers have
Uday> put in the upgrade and what those change would entail in terms of how
Uday> you will use the package.

This is exactly why I didn't write package.el to work automatically :-)

It should be implementable, though, if somebody really wants it.

Another idea would be to do what Mozilla's plugin manager does: look for
updates in the background, and notify the users of possible upgrades.

Uday> I will also want to install the new versions along side the old ones,
Uday> so that I have the option of going back to the old versions if I need
Uday> to.  It is not yet clear to me if package.el allows that.

If you install a new version the old one will still be there.  You have
to explicitly delete it.  So, you can go back to an older one by
deleting the newer one.

This isn't foolproof because installing a new version of a package may
install new versions of its dependencies, and there's no easy way
(without reading through files in ~/.emacs.d/elpa/) to know what those
are after the fact.

Tom

Re: document package.el

[Chong Yidong]

Uday S Reddy <u.s.reddy@cs.bham.ac.uk> writes:

> I will also want to install the new versions along side the old ones,
> so that I have the option of going back to the old versions if I need
> to.  It is not yet clear to me if package.el allows that.

See `package-load-list'.

Re: document package.el

[Richard Stallman]

    I personally think that upgrading packages should be a conscious, deliberate 
    action.  You never know what changes the developers have put in the upgrade and 
    what those change would entail in terms of how you will use the package.

I agree.  Not only that, but we want users to be conscious of and control
what software they run.  Leading them to let things be updated automatically
is the opposite of that.

Re: document package.el

[Christoph]

On 8/27/2010 3:43 PM, Richard Stallman wrote:
>      I personally think that upgrading packages should be a conscious, deliberate
>      action.  You never know what changes the developers have put in the upgrade and
>      what those change would entail in terms of how you will use the package.
>
> I agree.  Not only that, but we want users to be conscious of and control
> what software they run.  Leading them to let things be updated automatically
> is the opposite of that.

Agreed, but like Tom said, there could (and imho should) be an option to 
check for updates of specified packages on startup or periodically and 
provide an "update available" notification to the user.

Options could be

- Check manually
- Check on startup
- Check in a user-specified interval (once per day, week, month)
- Check on startup and periodically

If updates are available, a list of packages with updates should be 
presented to the user, where he can mark the packages he would like to 
upgrade.

On a new installation this would also work and result in the latest 
version of all specified packages being installed. With user 
confirmation of course.

That's what I was initially looking for.

Christoph

Re: document package.el

[Uday S Reddy]

On 8/27/2010 11:58 PM, Christoph wrote:

> Agreed, but like Tom said, there could (and imho should) be an option to check
> for updates of specified packages on startup or periodically and provide an
> "update available" notification to the user.

Right, you want a biff that says "you've got updates!"

There are always a bunch of early adopter users who want the latest and the 
greatest versions.  Such users are valuable for us because they provide quick 
feedback, initial bug reports etc. before the stuff gets more widely used.

So, I would support adding a feature that will help them know when new updates 
are available.

Cheers,
Uday

Re: document package.el

[Eli Zaretskii]

> From: Tom Tromey <tromey@redhat.com>
> Date: Fri, 06 Aug 2010 16:42:54 -0600
> 
> I'd appreciate comments on this patch.
> 
> I finally found a little time to write some documentation for
> package.el.

Thanks.

I never used package.el, so I can only comment on the clarity of the
text and the correctness of Texinfo usage.  Where I talk about
functionality, it's based on ignorance rather than on anything else.

> +@setfilename ../../info/os

I guess you meant ../../info/package.

These lines in lispref sources are actually obsolete: they seem to be
for some use-case of compiling each source file independently outside
of the main manual file elisp.texi.  I don't see a need for this
use-case, but as long as we keep those lines, we might as well make
them consistent -- each one of them names the basename of the source
file.

> +@node Packaging, Antinews, System Interface, Top
> +@chapter Preparing Lisp code for distribution

It is a good idea to have a @cindex entry at the beginning of each
chapter/section/subsection whose text is the name of the node, or some
variant thereof.  E.g., "@cindex packaging" here.

> +uninstall, and upgrade Lisp code that they might want to use.

Perhaps qualify "Lisp code" by "unbundled", because the bundled ones
are supposed to be upgraded by installing a newer Emacs version.

> +Lisp code, but it is possible to create other kinds of packages as
> +well, for example, a package consisting solely of documentation.
                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Which somewhat contradicts what you said above ("upgrade Lisp code").

> +@node Packaging Basics
> +@section Packaging Basics

Same comment as above about a @cindex entry.  (Same goes for all the
other sections.)

> +  A package has a few attributes:

Suggest a "@cindex package attributes" here.

> +@item Version
> +A version number, which is a dotted list of integers, like
> +@samp{1.2.0.3}.

Only integers?  Emacs supports more flexible version strings, see
subr.el.

> +@item Manual
> +A package can include an info manual.

"Info", with a capital I (here and elsewhere).

> +  Conceptually, a package goes through several state transitions (in

Suggest a "@cindex package states" here.

> +@item Install
> +Untar the package, or write a @file{.el} file into the appropriate

Suggest to use "unpack", which is more neutral to the archive format.

> +activation time.  The best approach is to have activation consist of a
> +some autoloads and little more.                                     ^^

That "a" should be removed.

> +  The simplest package consists of a single Emacs Lisp source file.
> +In this case, all the attributes of the package are taken from this
> +file.

It would be good to have a cross-reference to where the attributes are
described after "all the attributes of the package".

In general, do not assume that the reader is going through the
documentation in order.  She could have gotten here by following some
@xref, and therefore does not necessarily remembers what are the
attributes, because she could have read about them a long time ago,
maybe not at all.

> +Emacs Lisp library header conventions.  See @xref{Library Headers}.

@xref produces the "See" part automatically, so either remove "See" or
use "See @ref".

> +  The name of the package is the same as the base name of the
> +@file{.el} file, as written in the first comment line.

This made me wonder whether package.el will fall back to the file's
name itself, if that first comment line is absent or malformed.
Perhaps the docs should cover what happens in that case (for every
attribute), even if just by saying that the corresponding attribute
will be displayed as empty.

> +                                                    A package is
> +required to have a version number.

And if it doesn't?

> +  The file will be scanned for autoload comments at install time.

At this point I wondered why nothing is done with the Author and
Maintainer headers.

> +  A multi-file package is just a @file{.tar} file.

Does package.el really support only .tar files?  That sounds like an
unnecessary limitation, since Emacs supports much more.

> +  The contents of the @file{.tar} file must all appear in a single
> +directory, named after the package and version.

Are subdirectories allowed?  If yes, I suggest to mention that.  If
no, it again sounds like a limitation that perhaps should be lifted.

> +  If a @file{README} file exists in the content directory, then it is
> +used as the long description.

If this means a multi-file package cannot have a long description in
the form of "Commentary", then this sounds like an inconvenience,
e.g., if a package starts as a single file and then develops into a
multi-file one.

> +  If the package has an info manual, you should distribute the needed
> +info files, plus a @file{dir} file made with @command{install-info}.

Not clear why the `dir' file is needed.  Are you trying to support
users that don't have install-info on their systems?

> +  The installation process will scan all the @file{.el} files in the
> +package for autoload comments.

I believe the rest of the Emacs documentation calls them "autoload
cookies".  Also, a cross reference to the "Autoloads" node would be
good here.

> +@item Package-Version
> +If @samp{Version} is not suitable for use by the package manager, then
> +a package can define @samp{Package-Version}; it will be used instead.
> +This is handy if @samp{Version} is an RCS id or something else that is
> +not a dotted list of integers.

A cross-reference here to the appropriate node of package.texi would
be a good idea.

In general, this section should have some verbiage explaining how
package.el comes into play and pointing to package.texi, because
otherwise text like the following one is a big surprise:

> +@item Package-Requires
> +If this exists, it names packages on which the current package
> +depends for proper operation.  This is used by the package manager
> +both at download time (to ensure that a complete set of packages is
> +downloaded) and at activation time (to ensure that a package is
> +activated if and only if all its dependencies have been).

"Package manager"? "download time"? "activation time"? these are
explained in package.texi, but the reader of this section is not
necessarily aware of that feature.

> +The package code automatically defines a package named @samp{eamcs}
                                                                ^^^^^
A typo.

> +with the version number of the currently running Emacs.  This can be
> +used to require a minimal version of Emacs for a package.

I wonder if this text and the preceding example should be copied (or
moved?) into package.texi, and this node just have an @xref pointing
there.

Thanks again for working on this.

Re: document package.el

[Chong Yidong]

Eli Zaretskii <eliz@gnu.org> writes:

>> +@item Version
>> +A version number, which is a dotted list of integers, like
>> +@samp{1.2.0.3}.
>
> Only integers?  Emacs supports more flexible version strings, see
> subr.el.

Oh yeah, I had forgotten about that.  The parts of package.el that deal
with version numbers probably ought to use `version-to-list',
`version-list-<', etc.

Re: document package.el

[Tom Tromey]

>>>>> "Chong" == Chong Yidong <cyd@stupidchicken.com> writes:

Chong> Oh yeah, I had forgotten about that.  The parts of package.el that deal
Chong> with version numbers probably ought to use `version-to-list',
Chong> `version-list-<', etc.

Yeah.  I actually took a quick look at this while writing the docs, but
some places in package.el reconstruct the version string from the split
version, so it looked like a change that would take more time than I
have.

I'm supportive if somebody else wants to take a stab at this.

Tom

Re: document package.el

[Tom Tromey]

>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:

Tom> I finally found a little time to write some documentation for
Tom> package.el.
[...]

Eli> At this point I wondered why nothing is done with the Author and
Eli> Maintainer headers.

They weren't needed by the package manager.

Tom> +  A multi-file package is just a @file{.tar} file.

Eli> Does package.el really support only .tar files?  That sounds like an
Eli> unnecessary limitation, since Emacs supports much more.

Emacs doesn't have built-in support for anything else.  It relies on
external programs.  Since I think it is best not to rely on the
environment this way, I purposely limited package.el.  I still think
this was a good decision, because it only affects packagers, not users.
I don't know of any gain to be had by expanding this.

In any case I wrote the documentation to describe what exists now.

Eli> If this means a multi-file package cannot have a long description in
Eli> the form of "Commentary", then this sounds like an inconvenience,
Eli> e.g., if a package starts as a single file and then develops into a
Eli> multi-file one.

The problem is knowing which file to extract this information from.
It is not uncommon for several files to have comment headers.

Tom> +  If the package has an info manual, you should distribute the needed
Tom> +info files, plus a @file{dir} file made with @command{install-info}.

Eli> Not clear why the `dir' file is needed.  Are you trying to support
Eli> users that don't have install-info on their systems?

Yes.

Tom

Re: document package.el

[Eli Zaretskii]

> From: Tom Tromey <tromey@redhat.com>
> Date: Sat, 21 Aug 2010 12:22:56 -0600
> Cc: emacs-devel@gnu.org
> 
> Eli> Does package.el really support only .tar files?  That sounds like an
> Eli> unnecessary limitation, since Emacs supports much more.
> 
> Emacs doesn't have built-in support for anything else.  It relies on
> external programs.  Since I think it is best not to rely on the
> environment this way, I purposely limited package.el.

Most environments that have Emacs also have the external programs
needed for the other formats.  The difference between a hard
limitation and a soft one (which is in effect only if the required
program is not available) is that in the former case the user doesn't
have any choice (except to hack package.el), while in the latter she
can install the missing program and be done.

> I still think this was a good decision, because it only affects
> packagers, not users.

"Only packagers"?  What about a package I downloaded from elsewhere?
I don't expect many packages nowadays to come in a .tar format.

> Tom> +  If the package has an info manual, you should distribute the needed
> Tom> +info files, plus a @file{dir} file made with @command{install-info}.
> 
> Eli> Not clear why the `dir' file is needed.  Are you trying to support
> Eli> users that don't have install-info on their systems?
> 
> Yes.

Why?

Re: document package.el

[Tom Tromey]

>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:

Eli> Most environments that have Emacs also have the external programs
Eli> needed for the other formats.

... but some don't.

Eli> "Only packagers"?  What about a package I downloaded from elsewhere?
Eli> I don't expect many packages nowadays to come in a .tar format.

I don't know what packages you could possibly mean.

Packages for use with package.el must be packaged according to the rules
imposed by package.el.  Of these rules, use of .tar is a trivial one,
the other impose a lot more burden.

Users of package.el generally install packages from the package archive,
via the package menu mode.  They don't generally just download random
.tar files.  And, if they did -- so what?  The .tar is just the
distribution format.

Tom> +  If the package has an info manual, you should distribute the needed
Tom> +info files, plus a @file{dir} file made with @command{install-info}.

Eli> Not clear why the `dir' file is needed.  Are you trying to support
Eli> users that don't have install-info on their systems?

Tom> Yes.

Eli> Why?

My goal in writing package.el was a seamless user experience.  I tried
hard to minimize the number of error modes that a user could see.
Hence:

* Use of .tar and not anything else, even .tar.gz -- because .tar can be
  unpacked entirely in elisp.
* Use of package dependencies, to make it so you can't install a package
  and have it not work.
* Before I upload a package I also generally make a point of looking at
  how it is activated, looking at least for autoload cookies.

The general theme is to make packagers do a bit more work so that users
get a better experience.

Tom

Re: document package.el

[Chong Yidong]

Tom Tromey <tromey@redhat.com> writes:

> +  A @dfn{package} is simply one or more files, formatted and bundled
> +in a particular way.  Typically a package includes primarily Emacs
> +Lisp code, but it is possible to create other kinds of packages as
> +well, for example, a package consisting solely of documentation.

I don't think the documentation-only use case is important to mention.
Just say that you can include stuff other than Emacs Lisp code, such as
Info files.

> +This is shown to the user in the package menu buffer.  It is just a
> +single line.

We should probably recommend a stronger length limit.  By default, there
are only 36 characters in the package buffer.

> +Emacs Lisp library header conventions.  See @xref{Library Headers}.

Omit the "See", as it would produce "See see Library Headers".

> +  The name of the package is the same as the base name of the
> +@file{.el} file, as written in the first comment line.

Give an example here.

> +  A multi-file package is just a @file{.tar} file.

BTW, this is off-topic, but I've been meaning to ask why you don't use
.tar.gz files.  Is the bandwidth difference insignificant?

> +@file{superfrobnicator-pkg.el}.  This file must have a single form in
> +it, a call to @code{define-package}.  The package dependencies and

You should add a @defun for `define-package'.

> +@item Package-Version
> ...
> +@item Package-Requires

In these list items, you should add xrefs to the packaging node.

Re: document package.el

[Tom Tromey]

>>>>> "Chong" == Chong Yidong <cyd@stupidchicken.com> writes:

I'll reply to the rest of the patch reviews later, whenever I can get
some time to update the patch.

Tom> +  A multi-file package is just a @file{.tar} file.

Chong> BTW, this is off-topic, but I've been meaning to ask why you don't use
Chong> .tar.gz files.  Is the bandwidth difference insignificant?

I haven't tried to measure it.

I wanted to have minimal dependencies on the user's side, so I didn't
want to rely on a decompressor.  With a recent enough Emacs, you don't
even need a 'tar' program, due to tar-untar-buffer.

Some sort of optional compression would be fine.  It seems like this
could be handled transparently by the URL package, though, in
conjunction with a server that knew how to serve compressed files
automatically.

Tom

Re: document package.el

[Tom Tromey]

Here is an updated version of my proposed package.el documentation.
I have tried to address all the comments.

Tom

=== modified file 'doc/lispref/ChangeLog'
--- doc/lispref/ChangeLog	2010-08-20 20:07:29 +0000
+++ doc/lispref/ChangeLog	2010-08-21 18:26:54 +0000
@@ -1,3 +1,14 @@
+2010-08-21  Tom Tromey  <tromey@redhat.com>
+
+	* vol2.texi (Top): Update.
+	* vol1.texi (Top): Update.
+	* tips.texi (Library Headers): Mention Package-Version and
+	Package-Requires.
+	* package.texi: New file.
+	* os.texi (System Interface): Update pointers.
+	* elisp.texi (Top): Link to new nodes.  Include package.texi.
+	* anti.texi (Antinews): Update pointers.
+
 2010-08-20  Eli Zaretskii  <eliz@gnu.org>
 
 	* commands.texi (Misc Events): Add cross-references to where

=== modified file 'doc/lispref/anti.texi'
--- doc/lispref/anti.texi	2010-01-13 08:35:10 +0000
+++ doc/lispref/anti.texi	2010-07-30 00:05:33 +0000
@@ -6,7 +6,7 @@
 
 @c This node must have no pointers.
 
-@node Antinews, GNU Free Documentation License, System Interface, Top
+@node Antinews, GNU Free Documentation License, Packaging, Top
 @appendix Emacs 22 Antinews
 @c Update the elisp.texi, vol1.texi, vol2.texi Antinews menu entries
 @c with the above version number.

=== modified file 'doc/lispref/elisp.texi'
--- doc/lispref/elisp.texi	2010-07-10 18:52:53 +0000
+++ doc/lispref/elisp.texi	2010-07-31 01:32:13 +0000
@@ -159,6 +159,8 @@
 * System Interface::        Getting the user id, system type, environment
                               variables, and other such things.
 
+* Packaging::               Preparing Lisp code for distribution.
+
 Appendices
 
 * Antinews::                Info for users downgrading to Emacs 22.
@@ -1394,6 +1396,12 @@
 * Session Management::      Saving and restoring state with
                               X Session Management.
 
+Preparing Lisp code for distribution
+
+* Packaging Basics::        The basic concepts of Emacs Lisp packages.
+* Simple Packages::         How to package a single .el file.
+* Multi-file Packages::     How to package multiple files.
+
 Starting Up Emacs
 
 * Startup Summary::         Sequence of actions Emacs performs at startup.
@@ -1490,6 +1498,8 @@
 @include display.texi
 @include os.texi
 
+@include package.texi
+
 @c MOVE to Emacs Manual:  include misc-modes.texi
 
 @c appendices

=== modified file 'doc/lispref/os.texi'
--- doc/lispref/os.texi	2010-07-10 18:52:53 +0000
+++ doc/lispref/os.texi	2010-07-30 00:05:24 +0000
@@ -5,7 +5,7 @@
 @c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/os
-@node System Interface, Antinews, Display, Top
+@node System Interface, Packaging, Display, Top
 @chapter Operating System Interface
 
   This chapter is about starting and getting out of Emacs, access to

=== added file 'doc/lispref/package.texi'
--- doc/lispref/package.texi	1970-01-01 00:00:00 +0000
+++ doc/lispref/package.texi	2010-08-21 18:35:39 +0000
@@ -0,0 +1,189 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 2010
+@c   Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../../info/package
+@node Packaging, Antinews, System Interface, Top
+@chapter Preparing Lisp code for distribution
+@cindex packaging
+
+  Emacs provides a standard way for Emacs Lisp code to be distributed
+to users.  This approach lets users easily download, install,
+uninstall, and upgrade Lisp code that they might want to use.
+
+  A @dfn{package} is simply one or more files, formatted and bundled
+in a particular way.  Typically a package includes primarily Emacs
+Lisp code, but it is possible to create other kinds of packages as
+well.
+
+@menu
+* Packaging Basics::        The basic concepts of Emacs Lisp packages.
+* Simple Packages::         How to package a single .el file.
+* Multi-file Packages::     How to package multiple files.
+@end menu
+
+@node Packaging Basics
+@section Packaging Basics
+@cindex packaging basics
+
+  A package has a few attributes:
+@cindex package attributes
+
+@table @asis
+@item Name
+A string, the name of the package.  This attribute is mandatory.  If
+it does not exist, the package cannot be installed by the package
+manager.
+
+@item Version
+A version number, which is anything that can be parsed by
+@code{version-to-list}.  This attribute is mandatory.  If it does not
+exist, the package cannot be installed by the package manager.
+
+@item Brief description
+This is shown to the user in the package menu buffer.  It is just a
+single line.  On a terminal with 80 characters per line, there are
+only 36 characters available in the package menu mode for showing the
+brief description, so it is best to keep it very brief.  If no brief
+name is given, an empty string is used.
+
+@item Long description
+This can be a @file{README} file or the like.  This is available to
+the user before the package is installed, via the package menu.  It
+should more fully describe the package and its capabilities, so a user
+can read it to decide whether he wants to install the package.  This
+attribute is optional.
+
+@item Dependencies
+This is a list of other packages and their minimal acceptable
+versions.  This is used both at download time (to make sure all the
+needed code is available) and at activation time (to ensure a package
+is only activated if all its dependencies have been successfully
+activated).  This attribute is optional.
+
+@item Manual
+A package can optionally include an Info manual.
+@end table
+
+  Conceptually, a package goes through several state transitions (in
+reality some of these transitions are grouped together):
+
+@table @asis
+@item Download
+Fetch the package from somewhere.
+
+@item Install
+Unpack the package, or write a @file{.el} file into the appropriate
+install directory.  This step also includes extracting autoloads and
+byte-compiling the Emacs Lisp code.
+
+@item Activate
+Update @code{load-path} and @code{Info-directory-list} and evaluate
+the autoloads, so that the package is ready for the user to use.
+@end table
+
+  It is best for users if packages do not do too much work at
+activation time.  The best approach is to have activation consist of
+some autoloads and little more.
+
+@node Simple Packages
+@section Simple Packages
+@cindex single file packages
+
+  The simplest package consists of a single Emacs Lisp source file.
+In this case, all the attributes of the package (@pxref{Packaging
+Basics}) are taken from this file.
+
+  The package system expects this @file{.el} file to conform to the
+Emacs Lisp library header conventions.  @xref{Library Headers}.
+
+  The name of the package is the same as the base name of the
+@file{.el} file, as written in the first comment line.  For example,
+given the header line:
+
+@smallexample
+;;; superfrobnicator.el --- frobnicate and bifurcate flanges
+@end smallexample
+
+the package name will be @samp{superfrobnicator}.
+
+  The short description of the package is also taken from the first
+line of the file.
+
+  If the file has a ``Commentary'' header, then it is used as the long
+description.
+
+  The version of the package comes either from the ``Package-Version''
+header, if it exists, or from the ``Version'' header.  A package is
+required to have a version number.  Each release of a package must be
+accompanied by an increase in the version number.
+
+  If the file has a ``Package-Requires'' header, then that is used as
+the package dependencies.  Otherwise, the package is assumed not to
+have any dependencies.
+
+  A single-file package cannot have an Info manual.
+
+  The file will be scanned for autoload cookies at install time.
+@xref{Autoload}.
+
+@node Multi-file Packages
+@section Multi-file Packages
+@cindex multi-file packages
+
+  A multi-file package is just a @file{.tar} file.  While less
+convenient to create than a single-file package, a multi-file package
+also offers more features: it can include an Info manual, multiple
+Emacs Lisp files, and also other data files needed by a package.
+
+  The contents of the @file{.tar} file must all appear beneath a
+single directory, named after the package and version.  Files can
+appear in subdirectories of this top-most directory, but Emacs Lisp
+code will only be found (and thus byte-compiled) at the top-most
+level.  Also, the @file{.tar} file is typically also given this same
+name.  For example, if you are distributing version 1.3 of the
+superfrobnicator, the package file would be named
+``superfrobnicator-1.3.tar'' and the contents would all appear in the
+directory @file{superfrobnicator-1.3} in that @file{.tar}.
+
+  The package must include a @file{-pkg.el} file, named after the
+package.  In our example above, this file would be called
+@file{superfrobnicator-pkg.el}.  This file must have a single form in
+it, a call to @code{define-package}.  The package dependencies and
+brief description are taken from this form.
+
+@defun define-package name version &optional docstring requirements
+Define a package.  @var{name} is the name of the package, a string.
+@var{version} is the package's version, a string.  It must be in a
+form that can be understood by @code{version-to-list}.
+@var{docstring} is the short description of the package.
+@var{requirements} is a list of required packages and their versions.
+@end defun
+
+  If a @file{README} file exists in the content directory, then it is
+used as the long description.
+
+  If the package has an Info manual, you should distribute the needed
+info files, plus a @file{dir} file made with @command{install-info}.
+@xref{Invoking install-info, Invoking install-info, Invoking
+install-info, texinfo, Texinfo}.
+
+  Do not include any @file{.elc} files in the package.  Those will be
+created at install time.  Note that there is no way to control the
+order in which files are byte-compiled; your package must be robust
+here.
+
+  The installation process will scan all the @file{.el} files in the
+package for autoload cookies.  @xref{Autoload}.  They are extracted
+into a @file{-autoloads.el} file (e.g.,
+@file{superfrobnicator-autoloads.el}), so do not include a file of
+that name in your package.
+
+  Any other files in the @file{.tar} file are simply unpacked when the
+package is installed.  This can be useful if your package needs
+auxiliary data files --- e.g., icons or sounds.
+
+  Emacs Lisp code installed via the package manager must take special
+care to the location-independent.  One easy way to do this is to make
+references to auxiliary data files relative to @var{load-file-name}.

=== modified file 'doc/lispref/tips.texi'
--- doc/lispref/tips.texi	2010-06-23 03:36:56 +0000
+++ doc/lispref/tips.texi	2010-08-21 18:17:25 +0000
@@ -1052,6 +1052,31 @@
 This field is important; it's how people will find your package when
 they're looking for things by topic area.  To separate the keywords, you
 can use spaces, commas, or both.
+
+@item Package-Version
+If @samp{Version} is not suitable for use by the package manager, then
+a package can define @samp{Package-Version}; it will be used instead.
+This is handy if @samp{Version} is an RCS id or something else that
+cannot be parsed by @code{version-to-list}.  @xref{Packaging Basics}.
+
+@item Package-Requires
+If this exists, it names packages on which the current package depends
+for proper operation.  @xref{Packaging Basics}.  This is used by the
+package manager both at download time (to ensure that a complete set
+of packages is downloaded) and at activation time (to ensure that a
+package is activated if and only if all its dependencies have been).
+
+Its format is a list of lists.  The @code{car} of each sub-list is the
+name of a package, as a symbol.  The @code{cadr} of each sub-list is
+the minimum acceptable version number, as a string.  For instance:
+
+@smallexample
+;; Package-Requires: ((gnus "1.0") (bubbles "2.7.2"))
+@end smallexample
+
+The package code automatically defines a package named @samp{emacs}
+with the version number of the currently running Emacs.  This can be
+used to require a minimal version of Emacs for a package.
 @end table
 
   Just about every Lisp library ought to have the @samp{Author} and

=== modified file 'doc/lispref/vol1.texi'
--- doc/lispref/vol1.texi	2010-07-10 18:52:53 +0000
+++ doc/lispref/vol1.texi	2010-07-31 01:32:31 +0000
@@ -180,6 +180,8 @@
 * System Interface::        Getting the user id, system type, environment
                               variables, and other such things.
 
+* Packaging::               Preparing Lisp code for distribution.
+
 Appendices
 
 * Antinews::                Info for users downgrading to Emacs 22.
@@ -1415,6 +1417,12 @@
 * Session Management::      Saving and restoring state with
                               X Session Management.
 
+Preparing Lisp code for distribution
+
+* Packaging Basics::        The basic concepts of Emacs Lisp packages.
+* Simple Packages::         How to package a single .el file.
+* Multi-file Packages::     How to package multiple files.
+
 Starting Up Emacs
 
 * Startup Summary::         Sequence of actions Emacs performs at startup.

=== modified file 'doc/lispref/vol2.texi'
--- doc/lispref/vol2.texi	2010-07-10 18:52:53 +0000
+++ doc/lispref/vol2.texi	2010-07-31 01:32:50 +0000
@@ -179,6 +179,8 @@
 * System Interface::        Getting the user id, system type, environment
                               variables, and other such things.
 
+* Packaging::               Preparing Lisp code for distribution.
+
 Appendices
 
 * Antinews::                Info for users downgrading to Emacs 22.
@@ -1414,6 +1416,12 @@
 * Session Management::      Saving and restoring state with
                               X Session Management.
 
+Preparing Lisp code for distribution
+
+* Packaging Basics::        The basic concepts of Emacs Lisp packages.
+* Simple Packages::         How to package a single .el file.
+* Multi-file Packages::     How to package multiple files.
+
 Starting Up Emacs
 
 * Startup Summary::         Sequence of actions Emacs performs at startup.

Re: document package.el

[Chong Yidong]

Tom Tromey <tromey@redhat.com> writes:

> +  Emacs Lisp code installed via the package manager must take special
> +care to the location-independent.  One easy way to do this is to make
           ^^^
Typo here.

Other that this, I see no problems with the patch, so go ahead and
install whenever you like.

It would be nice if you could write a more detailed explanation of how
to determine the pathname of non-Lisp files, such as images, that are
included with the package.

Re: document package.el

[Tom Tromey]

Chong> It would be nice if you could write a more detailed explanation of how
Chong> to determine the pathname of non-Lisp files, such as images, that are
Chong> included with the package.

What do you think of this addition?

For example:

@smallexample
(defconst superfrobnicator-base (file-name-directory load-file-name))

(defun superfrobnicator-fetch-image (file)
  (expand-file-name file superfrobnicator-base))
@end smallexample

Tom

Re: document package.el

[Chong Yidong]

Tom Tromey <tromey@redhat.com> writes:

> What do you think of this addition?
>
> For example:
>
> @smallexample
> (defconst superfrobnicator-base (file-name-directory load-file-name))
>
> (defun superfrobnicator-fetch-image (file)
>   (expand-file-name file superfrobnicator-base))
> @end smallexample

Looks good.

Re: document package.el

[Uday S Reddy]

Tom Tromey wrote:

> I'd appreciate comments on this patch.
> 
> I finally found a little time to write some documentation for
> package.el.

Dear Tom, thanks for providing this info page.  Very much appreciated!

The document doesn't seem to mention where the package will be installed or how 
to customize the location.  Is that intentional?

Does package.el handle only elisp files or other kinds of files as well?  Where 
will the other files be installed?

Sorry if all this has been covered before.  I am still trying to catch up on 
the old discussin.

Cheers,
Uday

Re: document package.el

[Tom Tromey]

Uday> The document doesn't seem to mention where the package will be
Uday> installed or how to customize the location.  Is that intentional?

This particular documentation is just for package authors.
Customizations would be described in the user documentation instead.

Uday> Does package.el handle only elisp files or other kinds of files as
Uday> well?  Where will the other files be installed?

Yes, anything in the appropriate directory in the .tar is unpacked.
You can ship anything you like in your package -- some existing packages ship
data files that they need.

Perhaps the docs should mention that elisp installed this way ought to
be location-independent.

Tom