Finish moving SPF 2.0 into a book.

Omitted (at least temporarily) are "Packaging Recommendations" and
"Example Files".

9 files changed, 520 insertions, 5 deletions

diff --git a/specs/spf-2.0/about.mdwn b/specs/spf-2.0/about.mdwn
index 75743b6..1604e43 100644
--- a/specs/spf-2.0/about.mdwn
+++ b/specs/spf-2.0/about.mdwn
@@ -21,7 +21,7 @@ source package format:
       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.
+      See $[sectlink][rationale] 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
@@ -36,7 +36,7 @@ source package format:
       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.
+      binary packages.  See $[sectlink][rationale] for rationale behind this design.
   * The source package version is no longer included in `control`.
     - It is already given in the most recent entry in `changelog`.
   * The version identifier syntax now encodes information about source archive
@@ -63,3 +63,21 @@ Scope [scope]
 
 This specification applies both to source packages and to the package building
 tools that interact with them.
+
+
+Definitions [defs]
+==================
+
+TODO
+
+source package
+
+binary package
+
+package sources
+
+source package directory
+
+package building work area, work area
+
+package building tool
diff --git a/specs/spf-2.0/buildsys.mdwn b/specs/spf-2.0/buildsys.mdwn
new file mode 100644
index 0000000..5f5e302
--- /dev/null
+++ b/specs/spf-2.0/buildsys.mdwn
@@ -0,0 +1,22 @@
+Configuration Script [config]
+=============================
+
+TODO
+
+
+Build Makefile [build]
+======================
+
+TODO
+
+
+Build Work Area [work-area]
+===========================
+
+When building packages, a new directory named `tmp` shall be created in the
+source package directory.  In this directory, the package source code shall be
+copied or unpacked into a directory called `src` and an installation destination
+directory named `dest` shall be created.
+
+After all expected binary packages have been built, the work area (`tmp` and its
+children) shall be removed.
diff --git a/specs/spf-2.0/chapters b/specs/spf-2.0/chapters
index 477249a..12c6811 100644
--- a/specs/spf-2.0/chapters
+++ b/specs/spf-2.0/chapters
@@ -1 +1,7 @@
 about           About this Manual
+overview        Directory Structure Overview
+sources         Sources
+metadata        Metadata
+fields          Control Fields
+buildsys        Build System
+scripts         Maintainer Scripts
diff --git a/specs/spf-2.0/fields.mdwn b/specs/spf-2.0/fields.mdwn
new file mode 100644
index 0000000..51a9415
--- /dev/null
+++ b/specs/spf-2.0/fields.mdwn
@@ -0,0 +1,90 @@
+Source Package Fields [fields-src]
+==================================
+
+The fields in the source package metadata are:
+
+  * `Maintainer` (required)  
+
+    The name and e-mail address of the package maintainer.  This field must
+    follow the syntax of the `mailbox` symbol in RFC 5322 section 3.4.
+
+  * `Build-Depends` (optional)  
+
+    A list of packages that must be installed before the package can be built.
+
+  * `Homepage` (optional)  
+
+    The URL of the Web site for the package.  Accessible at this site should be
+    origin source code and documentation and/or information.  Though the
+    information in this field is machine-usable, the URL must not be surrounded
+    by angle brackets or any other characters.
+
+
+Binary Package Fields [fields-bin]
+==================================
+
+The fields in the binary package metadata are:
+
+  * `Architecture` (required)  
+
+    A list of architectures for which this package may be built.  The value may
+    be any one of the following:
+
+    - The string `all` to specify that all of the provided files are
+      architecture-independent;
+    - The string `any` to specify that at least some of the provided files are
+      architecture-dependent; or
+    - A space-separated list of one or more real or wildcard binary architecture
+      strings to specify that at least some of the provided files are only
+      usable on systems of the named binary architecture(s).
+
+    A "wildcard" binary architecture string is one in which one or two
+    components (called "wildcard components") is the string `any`.  It shall be
+    considered to match any real binary architecture string for which the
+    non-wildcard components are equal.
+
+  * `Platform` (required)
+
+    A list of platforms for which this package may be built.  The value may be
+    any one of the following:
+
+    - The string `all` to specify that all of the provided files are
+      platform-independent;
+    - The string `any` to specify that at least some of the provided files are
+      platform-dependent; or
+    - A space-separated list of one or more platform strings to specify that at
+      least some of the provided files are only usable on systems of the named
+      platform(s).
+
+  * `Essential` (optional)  
+
+    A flag to indicate whether the package is essential for the functioning of a
+    system on which it is installed.  If this field is set to `yes`, opkg will
+    refuse to remove the package except when upgrading it.  If this field is set
+    to any other value or is omitted, the package may be removed by a user.
+
+  * `Depends` (optional)  
+
+    A list of packages that must be installed and configured before the package
+    may itself be configured.
+
+  * `Recommends` (optional)  
+
+  * `Suggests` (optional)  
+
+  * `Pre-Depends` (optional)  
+
+    A list of packages that must be installed before the package may itself be
+    installed.
+
+  * `Conflicts` (optional)  
+
+  * `Provides` (optional)  
+
+  * `Replaces` (optional)  
+
+  * `Description` (required)  
+
+    A description of the binary package.  This is a multiline field.  The first
+    line is a short synopsis, and all following lines are an extended
+    description.
diff --git a/specs/spf-2.0/index.mdwn b/specs/spf-2.0/index.mdwn
index 93e4529..451deb3 100644
--- a/specs/spf-2.0/index.mdwn
+++ b/specs/spf-2.0/index.mdwn
@@ -1,5 +1,5 @@
     Status: DRAFT
-    Date: 2012-08-04
+    Date: 2012-08-13
     Revises: Source Package Format 1.0
 
 
@@ -9,8 +9,8 @@ Abstract
 This document describes version 2.0 of the format for software packages.
 
 
-Status of This Document
-=======================
+Status
+======
 
 This specification is in `DRAFT` status.  It is a work-in-progress and is
 subject to change.  Comments and revisions are welcome.
diff --git a/specs/spf-2.0/metadata.mdwn b/specs/spf-2.0/metadata.mdwn
new file mode 100644
index 0000000..f5b08bd
--- /dev/null
+++ b/specs/spf-2.0/metadata.mdwn
@@ -0,0 +1,110 @@
+Control Files [control]
+=======================
+
+TODO
+
+
+Change Log [changelog]
+======================
+
+Changes made to the source package should be explained in the file `changelog`.
+
+Each new package revision must be documented with an entry of the following
+format:
+
+    package (version) distributions
+    [zero or more blank lines]
+      * change details
+    [zero or more blank lines]
+      * more change details
+        more detailed change details
+    [zero or more blank lines]
+     -- maintainer  date
+
+`package` is the source package name.  Source package names may only consist of
+lowercase Latin letters, digits, plus and minus signs, and periods.  Names must
+be at least two characters long and must start with either a letter or a digit.
+(A regular expression for this is `[a-z0-9][a-z0-9+.-]+`.)
+
+`version` is the source package version.  See $[sectlink][src-ver] for the
+syntax of source package version identifiers.
+
+`distributions` is a list of distributions into which the package should be
+installed when uploaded to the package archive.  The list consists of one or
+more distribution names, separated by spaces.
+
+`maintainer` is the name and e-mail address of the package maintainer.  This
+field must follow the syntax of the `mailbox` symbol of RFC 5322 section 3.4.
+
+`date` is the date of packaging.  This field must follow the syntax of the
+`date-time` symbol of RFC 5322 section 3.3.
+
+
+Platform Configuration File Lists [platconf]
+============================================
+
+Platform-specific configuration files used by the source package at build time
+shall be listed in the `platconf` file.  Platform-specific configuration files
+used by the binary package(s) at run time shall be listed in the
+`<binpkg>.pkg/platconf` file.
+
+Source packages with a `platconf` file, a `<binpkg>.pkg/platconf` file, or both
+shall list in their build-time dependencies a package (real or virtual) that
+provides the listed platform-specific configuration files.
+
+Each configuration file must be described with an entry of the following format:
+
+    source destination
+
+`source` is the path to the file, relative to the platform configuration
+directory -- either `/usr/share/config/PLATFORM/PACKAGE-VERSION` or
+`/usr/share/config/PLATFORM/PACKAGE`, where `PLATFORM` is the architecture
+string denoting an application platform, `PACKAGE` is the name of the
+configurable source package, and `VERSION` is the upstream version of the
+configurable source package.
+
+`destination` is the path (file or directory) to which the file should be
+copied.  For a file used at build time, it is a path relative to the package
+building work area.  For a file used at run time, it is an absolute path in the
+user's filesystem hierarchy.
+
+
+Source Package Version Identifier [src-ver]
+===========================================
+
+In general, the syntax of source package version identifiers is:
+
+    <pkgver>[+sip<siprev>][-<pkgrev>][+<dist>-<distrev>]
+
+`<pkgver>` is the version of the original upstream package or the native
+package.  It may only consist of lowercase Latin letters, digits, periods, and
+tildes.  It must be at least one character long.  (A regular expression for this
+is `[0-9a-z.~]+`.)
+
+If the upstream source archive needs to be repacked with certain changes for
+compliance with the Software Inclusion Policy, the string `+sip<siprev>` must be
+appended to `<pkgver>`.  `<siprev>` is a number that should be incremented on
+each repack while `<pkgver>` remains constant.  It should be reset to `1` for
+the first repack of a new upstream source archive.  It must be a string of one
+or more digits, the first of which must be greater than or equal to `1`.  (A
+regular expression for this is `[1-9][0-9]*`.)
+
+`<pkgrev>` is the version of the distribution packaging.  It is optional and
+should be omitted for native packages.  It should be incremented on each
+revision of packaging while `<pkgver>` and `<siprev>` remain constant.  It
+should be reset to `1` for the first revision of packaging for a new upstream
+package version or source archive repack.  It must be a string of one or more
+digits, the first of which must be greater than or equal to `1`.  (A regular
+expression for this is `[1-9][0-9]*`.)
+
+If the package is to be installed into a distribution other than `trunk`, the
+string `+<dist>-<distrev>` must be appended to the end of the version
+identifier.  `<dist>` is the distribution into which the package is to be
+installed, may only consist of lowercase Latin letters and digits, and must be
+at least one character long.  (A regular expression for this is `[a-z0-9]+`.)
+`<distrev>` is a number that should be incremented on each upload to `<dist>`
+while `<pkgver>`, `<siprev>`, and `<pkgrev>` remain constant.  It should be
+reset to `1` for the first upload to `<dist>` of a new upstream package version,
+source archive repack, or distribution packaging revision.  It must be a string
+of one or more digits, the first of which must be greater than or equal to `1`.
+(A regular expression for this is `[1-9][0-9]*`.)
diff --git a/specs/spf-2.0/overview.mdwn b/specs/spf-2.0/overview.mdwn
new file mode 100644
index 0000000..b4e6f09
--- /dev/null
+++ b/specs/spf-2.0/overview.mdwn
@@ -0,0 +1,246 @@
+Directory Tree [tree]
+=====================
+
+The source package directory hierarchy can be summarized with the following
+tree:
+
+    <source-package-directory>/
+     |  No naming requirements are made for this directory.
+     +- <binpkg>.pkg/
+     |   |  Required for each binary package after execution of "config".
+     |   +- control
+     |   |      Required.
+     |   |      Metadata about the binary package.
+     |   +- install
+     |   |      Required.
+     |   |      A list of patterns to match files to be installed in the binary
+     |   |      package.
+     |   +- platconf
+     |   |      Optional.
+     |   |      A list of run-time configuration files.
+     |   +- postinst
+     |   |      Optional.
+     |   |      A maintainer script to be executed after a binary package is
+     |   |      unpacked.
+     |   +- postrm
+     |   |      Optional.
+     |   |      A maintainer script to be executed after a binary package is
+     |   |      removed.
+     |   +- preinst
+     |   |      Optional.
+     |   |      A maintainer script to be executed before a binary package is
+     |   |      unpacked.
+     |   \- prerm
+     |          Optional.
+     |          A maintainer script to be executed before a binary package is
+     |          removed.
+     +- build
+     |      Required after execution of "config".
+     |      A makefile with target rules to build the binary package(s).
+     +- changelog
+     |      Required.
+     |      A log of changes made to the source package.
+     +- config
+     |      Optional.
+     |      A shell script to configure the package build.
+     +- control
+     |      Required.
+     |      Metadata about the source package.
+     +- copyright
+     |      Required.
+     |      Information about copyrights and licenses in the source package.
+     +- format
+     |      Required.
+     |      A magic file to identify the source format version.  Should simply
+     |      contain the string "2.0".
+     +- patches/
+     |      Optional.
+     |      Patches to be applied to package sources before building.
+     +- <pkgname>-<pkgver>.tar.<ext>
+     |      Optional.
+     |      Upstream source archive (for non-native packages).
+     +- platconf
+     |      Optional.
+     |      A list of build-time configuration files.
+     \- src/
+            Optional.
+            Package sources (for native packages).
+
+
+Descriptions of Files [files]
+=============================
+
+All of the following files are located under what is called a "source package
+directory" (`<source-package-directory>` in the tree in $[sectlink][tree]).  No
+naming requirements are made for this directory.
+
+`<binpkg>.pkg/` [files-binpkg.pkg]
+----------------------------------
+
+After execution of the `config` file, for each binary package there must exist a
+directory named `<binpkg>.pkg`, where `<binpkg>` is the name of the binary
+package.
+
+Binary package names may only consist of lowercase Latin letters, digits, plus
+and minus signs, and periods.  Names must be at least two characters long and
+must start with either a letter or a digit.  (A regular expression for this is
+`[a-z0-9][a-z0-9+.-]+`.)
+
+This directory contains metadata and scripts for a binary package.
+
+`<binpkg>.pkg/control` [files-binpkg.pkg-control]
+-------------------------------------------------
+
+This file is required.
+
+This file contains control fields describing the binary package.  See
+$[sectlink][control] for the syntax of this file and $[sectlink][fields-bin] for
+the list of control fields in this file.
+
+`<binpkg>.pkg/install` [files-binpkg.pkg-install]
+-------------------------------------------------
+
+This file is required.
+
+This file contains a list of patterns to match files to be installed in the
+binary package.
+
+Each line in this file is a pattern that is expanded to match files as explained
+in [POSIX.1-2008, Shell & Utilities Volume, Section 2.6.6][posix-xcu-2.6.6].
+
+A file or directory in the destination directory may not be matched by more than
+one binary package's `install` file.  The behavior of package building tools in
+such a case is undefined.
+
+`<binpkg>.pkg/platconf` [files-binpkg.pkg-platconf]
+---------------------------------------------------
+
+This file is optional.  Its presence indicates that a binary package is
+platform-specific.
+
+This file contains a list of run-time configuration files to be installed in the
+binary package.  Files listed in this file shall not be listed in the binary
+package's `install` file.
+
+See $[sectlink][platconf] for the syntax of this file.
+
+`<binpkg>.pkg/postinst` [files-binpkg.pkg-postinst]
+---------------------------------------------------
+
+This file is optional.
+
+This file is a maintainer script to be executed after a binary package is
+unpacked.  See $[sectlink][scripts] for more information about maintainer
+scripts.
+
+`<binpkg>.pkg/postrm` [files-binpkg.pkg-postrm]
+-----------------------------------------------
+
+This file is optional.
+
+This file is a maintainer script to be executed after a binary package is
+removed.  See $[sectlink][scripts] for more information about maintainer
+scripts.
+
+`<binpkg>.pkg/preinst` [files-binpkg.pkg-preinst]
+-------------------------------------------------
+
+This file is optional.
+
+This file is a maintainer script to be executed before a binary package is
+unpacked.  See $[sectlink][scripts] for more information about maintainer
+scripts.
+
+`<binpkg>.pkg/prerm` [files-binpkg.pkg-prerm]
+---------------------------------------------
+
+This file is optional.
+
+This file is a maintainer script to be executed before a binary package is
+removed.  See $[sectlink][scripts] for more information about maintainer
+scripts.
+
+`build` [files-build]
+---------------------
+
+After execution of the `config` file, this file must exist.
+
+This file is a makefile that controls the building of binary packages.  See
+$[sectlink][build] for requirements for this file.
+
+`changelog` [files-changelog]
+-----------------------------
+
+This file is required.
+
+This file is a log of changes made to the source package.  See
+$[sectlink][changelog] for the format of this file.
+
+`config` [files-config]
+-----------------------
+
+This file is optional.
+
+This file is a script in shell command language that configures the package
+build.  See $[sectlink][config] for requirements for this file.
+
+`control` [files-control]
+-------------------------
+
+This file is required.
+
+This file contains control fields describing the source package.  See
+$[sectlink][control] for the syntax of this file and $[sectlink][fields-src] for
+the list of control fields in this file.
+
+`copyright` [files-copyright]
+-----------------------------
+
+This file is required.
+
+This file contains information about the copyrights in and licenses for the
+source package.  This specification currently makes no requirements for the
+format of this file.
+
+`format` [files-format]
+-----------------------
+
+This file is required.
+
+This "magic" file identifies the format version of the source package.  For
+packages in this version of the source package format, this file should simply
+contain the string `2.0`.
+
+`patches/` [files-patches]
+--------------------------
+
+This directory is optional.
+
+This directory shall contain patches to be applied to package sources before
+configuring and building any binary packages.
+
+See $[sectlink][patches] for the syntax of patch files.
+
+`<pkgname>-<pkgver>.tar.<ext>` [files-src-src-ver-tar-ext]
+----------------------------------------------------------
+
+TODO
+
+`platconf` [files-platconf]
+---------------------------
+
+This file is optional.  Its presence indicates that each binary package is
+platform-specific.
+
+This file contains a list of build-time configuration files to be installed into
+the package building work area.
+
+See $[sectlink][platconf] for the syntax of this file.
+
+`src/` [files-src]
+------------------
+
+TODO
+
+
+[posix-xcu-2.6.6]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_06
diff --git a/specs/spf-2.0/scripts.mdwn b/specs/spf-2.0/scripts.mdwn
new file mode 100644
index 0000000..a32d899
--- /dev/null
+++ b/specs/spf-2.0/scripts.mdwn
@@ -0,0 +1,11 @@
+Maintainer Script Format [scripts-fmt]
+======================================
+
+TODO
+
+
+Calling Standard [scripts-calling]
+==================================
+
+TODO
+
diff --git a/specs/spf-2.0/sources.mdwn b/specs/spf-2.0/sources.mdwn
new file mode 100644
index 0000000..7dec8d9
--- /dev/null
+++ b/specs/spf-2.0/sources.mdwn
@@ -0,0 +1,12 @@
+Patch Files [patches]
+=====================
+
+Patch File Headers [patch-headers]
+----------------------------------
+
+TODO
+
+Patch File Format [patch-format]
+--------------------------------
+
+TODO