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).

2 files changed, 14 insertions, 9 deletions

diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi
index 6066ea9a936..b0dbe4d0a64 100644
--- a/doc/lispref/package.texi
+++ b/doc/lispref/package.texi
@@ -54,7 +54,8 @@ prefix used in the program (@pxref{Coding Conventions}).
 @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 @@ once it is installed.
 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 @@ subdirectories of the content directory.
   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 bd560370f7a..0b3c017b104 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -1047,12 +1047,15 @@ 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 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}