From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: npostavs@users.sourceforge.net Newsgroups: gmane.emacs.bugs Subject: bug#13281: 24.3.50; "Package-Requires" missing info in (elisp) `Library Headers' & (elisp) `Packaging Basics' Date: Sat, 25 Mar 2017 01:04:28 -0400 Message-ID: <87o9wq0wwz.fsf@users.sourceforge.net> References: <694F4092D5F546EF9DBAE459FEE9C073@us.oracle.com> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Trace: blaine.gmane.org 1490418254 13103 195.159.176.226 (25 Mar 2017 05:04:14 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sat, 25 Mar 2017 05:04:14 +0000 (UTC) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.2 (gnu/linux) Cc: 13281@debbugs.gnu.org To: "Drew Adams" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Mar 25 06:04:09 2017 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1crdry-0002aB-BV for geb-bug-gnu-emacs@m.gmane.org; Sat, 25 Mar 2017 06:04:06 +0100 Original-Received: from localhost ([::1]:35984 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1crds4-0005lP-Bt for geb-bug-gnu-emacs@m.gmane.org; Sat, 25 Mar 2017 01:04:12 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:42857) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1crdrx-0005k4-V9 for bug-gnu-emacs@gnu.org; Sat, 25 Mar 2017 01:04:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1crdru-0003zr-Q2 for bug-gnu-emacs@gnu.org; Sat, 25 Mar 2017 01:04:05 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:44874) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1crdru-0003zh-Ko for bug-gnu-emacs@gnu.org; Sat, 25 Mar 2017 01:04:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1crdru-0003Rz-9o for bug-gnu-emacs@gnu.org; Sat, 25 Mar 2017 01:04:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: npostavs@users.sourceforge.net Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 25 Mar 2017 05:04:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 13281 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 13281-submit@debbugs.gnu.org id=B13281.149041819313203 (code B ref 13281); Sat, 25 Mar 2017 05:04:02 +0000 Original-Received: (at 13281) by debbugs.gnu.org; 25 Mar 2017 05:03:13 +0000 Original-Received: from localhost ([127.0.0.1]:43073 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1crdr6-0003Qo-SZ for submit@debbugs.gnu.org; Sat, 25 Mar 2017 01:03:13 -0400 Original-Received: from mail-it0-f51.google.com ([209.85.214.51]:36365) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1crdr5-0003QX-6u; Sat, 25 Mar 2017 01:03:11 -0400 Original-Received: by mail-it0-f51.google.com with SMTP id w124so27747258itb.1; Fri, 24 Mar 2017 22:03:11 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version; bh=NWUZ1MtKxagqov3Cv9gpIT4H+gHmRD0R9NlRbEirutw=; b=NRnCU68rP4uz+ZYSp9wLrF2VxFlhb2WZAagaxVTulTSrsaPLx0AUc7sLJGF71K4gAi XrcT8QyLwPUncSkaAnNkM8PQDQ59kJ97O/iuWrpGixuxcRfEWWb4HBGPov5lS/XG0QC3 K//yy/Ik+u9UvEaF82vMYKSGdTS9uvhh/kXYwrCSSDXX01auYVARMUCzLSFwr0uTwj99 tzrm7ptW7icYSLf2gBqxVb9dHHOlvNtWpCZwvRO4kUTVqV48TTsdeyRpLzZBHslthb9+ Xtg3PoSDaNWQCGo71jKZ1DdK0PE+bBNNNbVlrEKeeLqYLj57NYjCukSRQVTdW1ob46JK lvwg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:references:date :in-reply-to:message-id:user-agent:mime-version; bh=NWUZ1MtKxagqov3Cv9gpIT4H+gHmRD0R9NlRbEirutw=; b=YQzSEdZuqwdGyNjlf9OmgqjVeOEd42CH0Z1X5Yo77K/qCgVmjqZInErz1Xrq/QO8Ms JBl2AaHGFSWYffUAdFAsxsxsFSxT1wP/ie4jyoJ2vsW0oBNQ9y0K49Ysa+OoSdwpFU3K bSt6Rho/ErTKis1mbxjYT6xxAU5Zl4B1wwrkiKFlryxnK2CVk1IkSMsA9E5snFukYM0X hnWCE0lgzFkT99Tm6HwujapIi8o1Kydzy2nCuH9J18nP6tp9bwfap5ujFhXqkGfTH6zT cS6gwhe/WltvhfS/vtbQIvNh5L64sFxB8doxKi/X3n1X7MRovzjNedwWhTprFXqNIA57 FlzA== X-Gm-Message-State: AFeK/H0zBcftuad/MT0Hd/IO1Op+c/193UqxK7fozIqVw1d6X4dg1LoTc3k/eKK4WRpqvg== X-Received: by 10.36.220.6 with SMTP id q6mr536563itg.77.1490418185530; Fri, 24 Mar 2017 22:03:05 -0700 (PDT) Original-Received: from zony ([45.2.7.65]) by smtp.googlemail.com with ESMTPSA id v185sm2046999itf.11.2017.03.24.22.03.04 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 24 Mar 2017 22:03:04 -0700 (PDT) In-Reply-To: <694F4092D5F546EF9DBAE459FEE9C073@us.oracle.com> (Drew Adams's message of "Wed, 26 Dec 2012 10:27:44 -0800") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:130906 Archived-At: --=-=-= Content-Type: text/plain tags 13281 patch quit "Drew Adams" writes: > > 1. Node `Package-Requires' says that this file-header field must be a > list of lists, each of whose cadr is a version number (string). IOW, > the version number seems to be mandatory: it must be present. It's not mandatory, I've clarified this in the patch below. > 2. It does not say how these version-number strings are compared, > rendering this spec of the field almost meaningless. `string-lessp'? > `version<'? `version<='? I added a mention of `version-to-list' in the patch. Along with the existing text saying "the minimum acceptable version number" I think that makes the meaning clear. > What is the relation between this `Version' "attribute" and the > file-header `Version' field? None? Where does the attribute value come > from, if not from that field? No info at all about this. `(elisp) Simple Packages' says The package's attributes are taken from the various headers `(elisp) Multi-file Packages' says One of the files in the content directory must be named `NAME-pkg.el'. It must contain a single Lisp form, consisting of a call to the function `define-package', described below. This defines the package's version, brief description, and requirements. I added the word "attributes" to the last sentence in the patch. I think that makes it clear. > > 4. #3 means that a library must use a version number that is > recognizable by `version-to-list'. And what if it does not - what > happens? How to refer to a required library, using `Package-Requires', > if that required library does not have a `Version' file-header entry > that corresponds to `version-to-list'? `(elisp) Simple Packages' says The version number comes from the `Package-Version' header, if it exists, or from the `Version' header otherwise. One or the other _must_ be present. > 5. Why does a package need to be released in "releases", each of which > is accompanied by an increase in the version number? And is it really > even true that this is a hard requirement? I added an explanation in the patch about why it's needed. > > This does not seem to be a requirement for multiple-file packages. Why > should it be a requirement for single-file packages? > > I know it is not required for multi-file packages because I have some > that work fine with MELPA etc., and their `Version' numbers are not > incremented each time the package files are uploaded, which is daily > (automatically). This doesn't cover MELPA though. MELPA automatically adds a version number based on the timestamp of when the source is retrieved. The manual does not document MELPA as it is not part of GNU Emacs. > > And what about inherited dependencies? If hl-line+.el requires > hl-line.el, do I need to flatten the `Package-Requires' for > crosshairs.el, to include hl-line? No. I added the word "recursively" to the "Dependencies" attribute description in the patch. > And what if the list of dependencies is long - do I need to write them > all on a single line, making the line-width far too wide for the file? > If not, what do `Package-Requires' continuation lines look like? It must be on a single line. I've added a mention about that in the patch. --=-=-= Content-Type: text/x-diff Content-Disposition: inline; filename=v1-0001-Improve-packaging-documentation.patch Content-Description: patch >From 2bd4a0c1720a5c22d8f07cfd47b4a3494d7503d1 Mon Sep 17 00:00:00 2001 From: Noam Postavsky Date: Sat, 25 Mar 2017 00:58:44 -0400 Subject: [PATCH v1] Improve packaging documentation * doc/lispref/package.texi (Packaging Basics): * doc/lispref/tips.texi (Library Headers): Clarify some header formats, relation between file headers and package attributes (Bug#13281). --- doc/lispref/package.texi | 12 +++++++----- doc/lispref/tips.texi | 11 +++++++---- 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi index 6066ea9a93..b0dbe4d0a6 100644 --- a/doc/lispref/package.texi +++ b/doc/lispref/package.texi @@ -54,7 +54,8 @@ Packaging Basics @item Version A version number, in a form that the function @code{version-to-list} understands (e.g., @samp{11.86}). Each release of a package should be -accompanied by an increase in the version number. +accompanied by an increase in the version number so that it will be +recognized as an upgrade by users querying the package archive. @item Brief description This is shown when the package is listed in the Package Menu. It @@ -71,8 +72,9 @@ Packaging Basics A list of other packages (possibly including minimal acceptable version numbers) on which this package depends. The list may be empty, meaning this package has no dependencies. Otherwise, -installing this package also automatically installs its dependencies; -if any dependency cannot be found, the package cannot be installed. +installing this package also automatically installs its dependencies, +recursively; if any dependency cannot be found, the package cannot be +installed. @end table @cindex content directory, package @@ -212,8 +214,8 @@ Multi-file Packages One of the files in the content directory must be named @file{@var{name}-pkg.el}. It must contain a single Lisp form, consisting of a call to the function @code{define-package}, described -below. This defines the package's version, brief description, and -requirements. +below. This defines the package's attributes: version, brief +description, and requirements. For example, if we distribute version 1.3 of the superfrobnicator as a multi-file package, the tar file would be diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index bd560370f7..0b3c017b10 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -1047,12 +1047,15 @@ Library Headers of packages is downloaded) and at activation time (to ensure that a package is only activated 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: +Its format is a list of lists on a single line. 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 +that can be parse by @code{version-to-list}. An entry that lacks a +version (i.e., an entry which is just a symbol, or a sub-list of one +element) is equivalent to entry with version "0". For instance: @smallexample -;; Package-Requires: ((gnus "1.0") (bubbles "2.7.2")) +;; Package-Requires: ((gnus "1.0") (bubbles "2.7.2") cl-lib (seq)) @end smallexample The package code automatically defines a package named @samp{emacs} -- 2.11.1 --=-=-=--