From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: document package.el Date: Sat, 07 Aug 2010 10:47:55 +0300 Message-ID: <83bp9ex3ro.fsf@gnu.org> References: Reply-To: Eli Zaretskii NNTP-Posting-Host: lo.gmane.org X-Trace: dough.gmane.org 1281299247 31495 80.91.229.12 (8 Aug 2010 20:27:27 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Sun, 8 Aug 2010 20:27:27 +0000 (UTC) Cc: emacs-devel@gnu.org To: Tom Tromey Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Aug 08 22:27:22 2010 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1OiCSn-00080p-VF for ged-emacs-devel@m.gmane.org; Sun, 08 Aug 2010 22:27:22 +0200 Original-Received: from localhost ([127.0.0.1]:57954 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OiBQE-0005mo-GL for ged-emacs-devel@m.gmane.org; Sun, 08 Aug 2010 15:20:38 -0400 Original-Received: from [140.186.70.92] (port=51343 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Oi9jG-0002Ja-Qq for emacs-devel@gnu.org; Sun, 08 Aug 2010 13:32:16 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1Ohe8f-0001eC-QF for emacs-devel@gnu.org; Sat, 07 Aug 2010 03:48:21 -0400 Original-Received: from mtaout20.012.net.il ([80.179.55.166]:56398) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Ohe8f-0001e0-F0 for emacs-devel@gnu.org; Sat, 07 Aug 2010 03:48:17 -0400 Original-Received: from conversion-daemon.a-mtaout20.012.net.il by a-mtaout20.012.net.il (HyperSendmail v2007.08) id <0L6R00600UT34C00@a-mtaout20.012.net.il> for emacs-devel@gnu.org; Sat, 07 Aug 2010 10:47:56 +0300 (IDT) Original-Received: from HOME-C4E4A596F7 ([77.126.102.143]) by a-mtaout20.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0L6R00581UZU4SC0@a-mtaout20.012.net.il>; Sat, 07 Aug 2010 10:47:56 +0300 (IDT) In-reply-to: X-012-Sender: halo1@inter.net.il X-detected-operating-system: by eggs.gnu.org: Solaris 10 (beta) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:128427 Archived-At: > From: Tom Tromey > 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.