Re: document package.el

[Chong Yidong]

Tom Tromey <address@hidden> 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
> address@hidden 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?

> address@hidden  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'.

> address@hidden Package-Version
> ...
> address@hidden Package-Requires

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