bug#13281: 24.3.50; "Package-Requires" missing info in (elisp) `Library Headers' & (elisp) `Packaging Basics'

[npostavs]

tags 13281 patch
quit

"Drew Adams" <drew.adams@oracle.com> 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.

>From 2bd4a0c1720a5c22d8f07cfd47b4a3494d7503d1 Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs@gmail.com>
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