Update source package specification.

Changes:
  * Update the directory structure.
  * Update binary architecture string format.
  * Describe "Depends", "Pre-Depends", and "Description" control fields.

1 files changed, 24 insertions, 53 deletions

diff --git a/specs/source-package-format-1.0.txt b/specs/source-package-format-1.0.txt
index aa12f98..5b7008f 100644
--- a/specs/source-package-format-1.0.txt
+++ b/specs/source-package-format-1.0.txt
@@ -1,10 +1,10 @@
-ABOUT THIS DOCUMENT
+About This Document
 ===================
 
 This document describes version 1.0 of the format for software source packages.
 
 
-LEGAL NOTICE
+Legal Notice
 ============
 
 Copyright (C) 2012 Patrick "P. J." McDermott
@@ -14,7 +14,7 @@ under the terms of the Expat/MIT License:
 http://www.jclark.com/xml/copying.txt
 
 
-SPECIFICATION STATUS
+Specification Status
 ====================
 
 This specification is in draft status.  It is a work-in-progress and is subject
@@ -24,9 +24,10 @@ TODO
 ----
   * Finish describing binary package control fields.
   * Describe the control file format.
+  * Describe the formats of the config and changelog files.
 
 
-BACKGROUND
+Background
 ==========
 
 A source package consists of software source code, a build system, and package
@@ -34,7 +35,7 @@ metadata.  From it is built one or more binary packages, which can be installed
 into an operating system.
 
 
-RATIONALE
+Rationale
 =========
 
 This source package format is modeled after the package format of the OpenBricks
@@ -46,51 +47,9 @@ that of OpenBricks).  In this and other respects, this format draws inspiration
 from Debian's source package formats.
 
 
-DIRECTORY STRUCTURE
+Directory Structure
 ===================
 
-PROPOSAL 1
-----------
-
-This directory structure proposal has been declared defunct and removed from
-this document.
-
-PROPOSAL 2
-----------
-
-In this structure, all source and binary packaging files are kept in the same
-directory.
-
-Note that this directory structure is very functionally similar to that of
-Debian's source package formats.
-
-<pkgname>_<pkgver>-<pkgrev>/
- +- <binpkg>.install
- |    A list of patterns to match files to be installed in a binary package.
- +- <binpkg>.postinst
- +- <binpkg>.postrm
- +- <binpkg>.preinst
- +- <binpkg>.prerm
- +- build
- |    A makefile with target rules to build the binary package(s).
- +- control
- |    Metadata about the source and binary packages.
- +- format
- |    A magic file to identify the source format version.  Should simply contain
- |    the string "1.0".
- +- patches/
- |    Patches to be applied to package sources before building.
- +- <pkgname>_<pkgver>.<ext>
- |    Upstream source archive (for non-native packages).
- \- src/
-      Package sources (for native packages).
-
-PROPOSAL 3
-----------
-
-This structure is functionally equivalent to that of proposal 2, however, files
-and metadata related to binary packages are organized into directories.
-
 <pkgname>_<pkgver>-<pkgrev>/
  +- <binpkg>.pkg/
  |   +- control
@@ -104,8 +63,14 @@ and metadata related to binary packages are organized into directories.
  |   \- prerm
  +- build
  |    A makefile with target rules to build the binary package(s).
+ +- changelog
+ |    A log of changes made to the source package.
+ +- config
+ |    A list of build-time and run-time configuration files.
  +- control
  |    Metadata about the source package.
+ +- copyright
+ |    Information about copyrights and licenses in the source package.
  +- format
  |    A magic file to identify the source format version.  Should simply contain
  |    the string "1.0".
@@ -117,13 +82,13 @@ and metadata related to binary packages are organized into directories.
       Package sources (for native packages).
 
 
-CONTROL FILE FORMAT
+Control File Format
 ===================
 
 See documentation on Debian packaging.
 
 
-BINARY PACKAGE METADATA
+Binary Package Metadata
 =======================
 
 The fields in the binary package metadata are:
@@ -135,8 +100,8 @@ The fields in the binary package metadata are:
   * Architecture (required)
     The names of the architectures for which this package is built.  The list of
     names may consist of values selected from the following:
-      - A four-tuple binary architecture name to specify that the package can be
-        built for the binary architecture and any application platform.
+      - A three-tuple binary architecture name to specify that the package can
+        be built for the binary architecture and any application platform.
       - An application platform architecture name to specify that the package
         can be built for the application platform and its associated binary
         architecture.
@@ -153,16 +118,22 @@ The fields in the binary package metadata are:
     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.
 
 
-SOURCE PACKAGE METADATA
+Source Package Metadata
 =======================
 
 The fields in the source package metadata are: