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

[Drew Adams]

An anonymous user on Emacs Wiki updated a couple of my files to add
`Package-Requires' to the file headers, saying that this helped
MELPA/Marmalade.
 
I read the doc for `Package-Requires' at (elisp) `Library Headers' and
the cross-reffed doc `Packaging Basics', but that doc is unclear, and
some info seems to be missing.
 
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.
 
2. It does not say how these version-number strings are compared,
rendering this spec of the field almost meaningless.  `string-lessp'?
`version<'?  `version<='?  Something else?  What happens to a value of
""?  Or "0"?  What happens if the mandatory version string is missing
altogether?  What happens if a (FILE VERSION) has only the form FILE? 
 
3. Node `Packaging Basics', to which `Package-Requires' refers for more
information about this stuff says this:
 
  Version
     A version number, in a form that the function `version-to-list'
     understands (e.g., `11.86').  Each release of a package should be
     accompanied by an increase in the version number.
 
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.
 
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'?
 
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?
 
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).
 
Of course, there is no description of what "release" means, so maybe
uploading is not releasing.  No idea.  For my libraries and packages, I
generally do not care about "releasing" - I do not have releases.  How
does that use case fit the model and its requirements?
 
6. `Packaging Basics' also says this about "attribute" `Dependencies':
 
  Dependencies
     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.
 
Note: "_possibly_ including".  That means that "minimal acceptable
version numbers" are optional, _not_ mandatory, which contradicts what
is said in #1.
 
Also, nowhere is it said what such "attributes" are.  The term is quoted
here, as if this node were somehow defining the notion for readers, but
it is nowhere defined.  We list the attributes but we do not say what an
attribute is.
 
In particular, what is such an attribute in Emacs Lisp?  Where is it
stored and what does it look like (its type etc.)?
 
In general, the doc for this stuff is quite flaky and incomplete.
Please try to actually _specify_ what the Lisp thingies and concepts
are, rigorously.  That is the starting point for user explanations in
the manual.
 
7. I am mostly concerned about #1 and #6.  In my single-file package
`crosshairs.el', for example, the anonymous wiki user added this header
line:
 
;; Package-Requires: ((col-highlight "22.0") (hl-line+ "20120823") (vline
"1.10"))
 
I don't know where s?he got the version numbers used here.  Perhaps from
`Version' header fields in those files.  But I do not want package.el,
MELPA, etc. to think that crosshairs.el has a hard requirement for
version 22.0 of col-highlight.el, and so on.
 
It requires feature col-highlight, but not any particular version of
that library.  How can I specify that using `Package Requires'?
 
vline.el is not even my library.  I have no way of knowing, and a priori
I do not care, which minimal version of `vline.el' is required by
crosshairs.
 
And what happens if the pkg mgr finds only vline.el version 1.09 or
something?  Does that mean that it will not install crosshairs.el?
 
None of the many obvious questions like this that come up are answered
in the doc.  Just how does the pkg mgr handle these dependencies?  How
strict is it wrt the version numbers of required packages/files?  And
what does it do if it does not find the right version - stop? load an
"incorrect" version anyway?
 
I would not mind saying simplythat crosshairs.el requires
libraries/features col-highlight, hl-line+, and vline, without adding
any version info.  What happens if I do that?  #1 seems to say that such
a format is not supported (why not?).
 
8. If Emacs packaging is so rudimentary that it requires a VERSION field
in `Package Requires', then I suppose I can add a vacuous version
number, but (a) that just represents added noise and (b) what is the
vacuous entry?
 
If I cannot write `Package-Requires': (col-highlight hl-line+ vline)'
and I cannot write `Package-Requires: ((col-highlight) (hl-line+)
(vline))', can I write `Package-Requires: ((col-highlight "") (hl-line+
"") (vline ""))'?  Or must I write `Package-Requires: ((col-highlight
"0") (hl-line+ "0") (vline "0"))'?
 
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 info about this.
 
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?
 
What are the rules here?  And what happens when the rules are not
respected?  No info at all about this.
 
Please:
 
a. Let me know what the minimal requirements are, to enable users to
use, say, crosshairs.el with the Emacs pkg mgr (to permit use, e.g., on
MELPA).
 
b. Update the doc to provide complete and correct, non-ambiguous and
non-contradictory explanations of what is required wrt specifying
package dependencies in a file header.  For a single-file package, at
least.
 

In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2012-12-18 on MS-W7-DANI
Bzr revision: 111265 eliz@gnu.org-20121218190556-x9wmq083vwecgu0f
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -Ic:/emacs/libs/libXpm-3.5.10/include -Ic:/emacs/libs/libXpm-3.5.10/src
 -Ic:/emacs/libs/libpng-dev_1.4.3-1_win32/include
 -Ic:/emacs/libs/zlib-dev_1.2.5-2_win32/include
 -Ic:/emacs/libs/giflib-4.1.4-1-lib/include
 -Ic:/emacs/libs/jpeg-6b-4-lib/include
 -Ic:/emacs/libs/tiff-3.8.2-1-lib/include
 -Ic:/emacs/libs/libxml2-2.7.8-w32-bin/include/libxml2
 -Ic:/emacs/libs/gnutls-3.0.9-w32-bin/include
 -Ic:/emacs/libs/libiconv-1.9.2-1-lib/include'