Add change log and summarize maintainer scripts.

1 files changed, 84 insertions, 11 deletions

diff --git a/specs/source-package-format-2.0.txt b/specs/source-package-format-2.0.txt
index 9840b02..4bf3740 100644
--- a/specs/source-package-format-2.0.txt
+++ b/specs/source-package-format-2.0.txt
@@ -28,7 +28,34 @@ into an operating system.
 4.  Changes Since Version 1.0
 =============================
 
-TODO
+Following is a summary of differences between versions 1.0 and 2.0 of this
+source package format:
+
+  * The platform configuration file list is now split between two files.
+    `platconf` lists build-time configuration files, and `<binpkg>.pkg/platconf`
+    lists run-time configuration files.
+    - As a result, the platform configuration file lists now have a simpler
+      syntax that does not include the type of configuration file.
+    - It is now easy to determine whether individual binary packages are
+      platform-specific.
+  * Package building can now be configured by a `config` script.
+    - There is now no need for any configuration logic in the `build` makefile.
+      See section 5 for rationale behind this design.
+    - The list of binary packages that can be built from a source package no
+      longer needs to be statically defined.
+  * The source package hierarchy has been clarified to to indicate whether each
+    file is required.
+    - Additionally, certain files are now only required by a certain step in the
+      build process, allowing them to be dynamically generated.
+  * Packages without any sources (such as pure metapackages) are now explicitly
+    allowed.
+  * Maintainer scripts are now explained.
+  * The set of required `build` makefile targets has been changed.
+    - The amount of redundant information in source packages is reduced by not
+      requiring the `build` file to list all binary packages.
+    - The user can choose to build all binary packages, only
+      architecture-independent binary packages, or only architecture-independent
+      binary packages.  See section 5 for rationale behind this design.
 
 
 5.  Rationale
@@ -148,7 +175,7 @@ children) shall be removed.
 
 All of the following files are located under what is called a "source package
 directory" (`<source-package-directory>` in the tree in section 8).  No naming
-requirements are made for this directory.  See section 19.1 for a recommended
+requirements are made for this directory.  See section 20.1 for a recommended
 naming convention for this directory.
 
 10.1.  `<binpkg>.pkg/`
@@ -196,6 +223,38 @@ package's `install` file.
 
 See section 14 for the syntax of this file.
 
+10.5.  `<binpkg>.pkg/postinst`
+------------------------------
+
+This file is optional.
+
+This file is a maintainer script to be executed after a binary package is
+unpacked.  See section 19 for more information about maintainer scripts.
+
+10.6.  `<binpkg>.pkg/postrm`
+----------------------------
+
+This file is optional.
+
+This file is a maintainer script to be executed after a binary package is
+removed.  See section 19 for more information about maintainer scripts.
+
+10.7.  `<binpkg>.pkg/preinst`
+------------------------------
+
+This file is optional.
+
+This file is a maintainer script to be executed before a binary package is
+unpacked.  See section 19 for more information about maintainer scripts.
+
+10.8.  `<binpkg>.pkg/prerm`
+------------------------------
+
+This file is optional.
+
+This file is a maintainer script to be executed before a binary package is
+removed.  See section 19 for more information about maintainer scripts.
+
 10.9.  `build`
 --------------
 
@@ -457,10 +516,24 @@ The fields in the binary package metadata are:
     description.
 
 
-19.  Packaging Recommendations
+19.  Maintainer Scripts
+=======================
+
+19.1.  Maintainer Script Format
+-------------------------------
+
+TODO
+
+19.2.  Calling Standard
+-----------------------
+
+TODO
+
+
+20.  Packaging Recommendations
 ==============================
 
-19.1.  Source Package Directory Naming
+20.1.  Source Package Directory Naming
 --------------------------------------
 
 It is recommended that the name of the source package directory be simply the
@@ -468,7 +541,7 @@ name of the source package.  Including the package version number or any part
 thereof in the directory name is not recommended, as this number will likely
 change over time.
 
-19.2.  `build` File Generation
+20.2.  `build` File Generation
 ------------------------------
 
 For non-trivial packages, it is recommended that the `config` script generates a
@@ -483,7 +556,7 @@ However, it is not specified by POSIX.1 (and therefore cannot be expected to be
 supported by all implementations).  Furthermore, conditional logic goes beyond
 the original design of the `make` utility.
 
-19.3.  Dynamic Binary Package Generation
+20.3.  Dynamic Binary Package Generation
 ----------------------------------------
 
 For certain source packages, the set of binary packages to be built depends on
@@ -494,15 +567,15 @@ generated by the `config` script from template directories named
 `<binpkg>.pkg.in/` or similar.
 
 
-20.  Example Files
+21.  Example Files
 ==================
 
 In the following sections are some example files that might be used for the
-`opkg` source package.  They observe the recommendation made in section 19.2 to
+`opkg` source package.  They observe the recommendation made in section 20.2 to
 make the `config` script generate a `build` makefile from an input `build.in`
 file.
 
-20.1.  Example `config` File
+21.1.  Example `config` File
 ----------------------------
 
 Following is an example `config` file:
@@ -520,7 +593,7 @@ Following is an example `config` file:
 It detects whether the user intends to cross build the software and generates
 appropriate `build` and `host` options for the software's `configure` script.
 
-20.2.  Example `build.in` File
+21.2.  Example `build.in` File
 ------------------------------
 
 Following is an example `build.in` file:
@@ -572,7 +645,7 @@ Additionally, this file relies on the opkhelper utilities to perform tasks
 related to the production of binary packages.
 
 
-21.  Legal Notice
+22.  Legal Notice
 =================
 
 Copyright (C) 2012 Patrick "P. J." McDermott