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