From 2132d25f3a2f04af123ec20cbd15eee741638ffc Mon Sep 17 00:00:00 2001
From: P. J. McDermott <pjm@nac.net>
Date: Fri, 12 Oct 2012 18:39:02 -0400
Subject: Document the docs file in SPF 2.0.

---
(limited to 'specs/spf-2.0')

diff --git a/specs/spf-2.0/metadata.mdwn b/specs/spf-2.0/metadata.mdwn
index 90e88fa..1195826 100644
--- a/specs/spf-2.0/metadata.mdwn
+++ b/specs/spf-2.0/metadata.mdwn
@@ -38,6 +38,32 @@ field must follow the syntax of the `mailbox` symbol of RFC 5322 section 3.4.
 `date-time` symbol of RFC 5322 section 3.3.
 
 
+Source Package Documentation File List [docs]
+=============================================
+
+One binary package built from a source package provides documentation files
+about the source package.  This binary package is identified by the presence of
+a `<binpkg>.pkg/docs` file, where `<binpkg>` is the name of the binary package.
+
+All other binary packages built from the same source package must declare a hard
+run-time dependency (either `Depends` or `Pre-Depends`) on this binary package.
+
+At least the `copyright` and `changelog` files are provided by the binary
+package.  If found in the source package directory, a file named `README` is
+also provided.
+
+Additional documentation files may be listed in `<binpkg>.pkg/docs`.  Each file
+must be identified with an entry of the following format:
+
+    source destination
+
+`source` is the path to the file, relative to the build work area (see
+$[sectlink][work-area]).
+
+`destination` is the path to which the file should be installed, relative to the
+source package documentation directory in the user's filesystem hierarchy.
+
+
 Platform Configuration File Lists [platconf]
 ============================================
 
diff --git a/specs/spf-2.0/overview.mdwn b/specs/spf-2.0/overview.mdwn
index 1895815..9dcdda0 100644
--- a/specs/spf-2.0/overview.mdwn
+++ b/specs/spf-2.0/overview.mdwn
@@ -11,6 +11,10 @@ tree:
      |   +- control
      |   |      Required.
      |   |      Metadata about the binary package.
+     |   +- docs
+     |   |      Required for exactly one binary package.
+     |   |      A list of source package documentation files to be provided by
+     |   |      the package.
      |   +- platconf
      |   |      Optional.
      |   |      A list of run-time configuration files.
@@ -85,6 +89,16 @@ 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/docs` [files-binpkg.pkg-docs]
+-------------------------------------------
+
+This file is required for exactly one binary package.
+
+This file contains a list of source package documentation files to be provided
+by the binary package.
+
+See $[sectlink][docs] for more information about this file.
+
 `<binpkg>.pkg/platconf` [files-binpkg.pkg-platconf]
 ---------------------------------------------------
 
--
cgit v0.9.1