emacs-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: document package.el


From: Eli Zaretskii
Subject: Re: document package.el
Date: Sat, 07 Aug 2010 10:47:55 +0300

> From: Tom Tromey <address@hidden>
> 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.

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

> address@hidden Packaging, Antinews, System Interface, Top
> address@hidden 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").

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

> address@hidden Version
> +A version number, which is a dotted list of integers, like
> address@hidden

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

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

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

> address@hidden 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:

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



reply via email to

[Prev in Thread] Current Thread [Next in Thread]