Document substitution variables.

4 files changed, 50 insertions, 2 deletions

diff --git a/specs/spf-2.0/chapters b/specs/spf-2.0/chapters
index 12c6811..d64ad43 100644
--- a/specs/spf-2.0/chapters
+++ b/specs/spf-2.0/chapters
@@ -3,5 +3,6 @@ overview        Directory Structure Overview
 sources         Sources
 metadata        Metadata
 fields          Control Fields
+substvars       Substitution Variables
 buildsys        Build System
 scripts         Maintainer Scripts
diff --git a/specs/spf-2.0/fields.mdwn b/specs/spf-2.0/fields.mdwn
index 51a9415..897e4c9 100644
--- a/specs/spf-2.0/fields.mdwn
+++ b/specs/spf-2.0/fields.mdwn
@@ -68,23 +68,39 @@ The fields in the binary package metadata are:
     A list of packages that must be installed and configured before the package
     may itself be configured.
 
+    Variable substitutions are performed on the value of this field.
+
   * `Recommends` (optional)  
 
+    Variable substitutions are performed on the value of this field.
+
   * `Suggests` (optional)  
 
+    Variable substitutions are performed on the value of this field.
+
   * `Pre-Depends` (optional)  
 
     A list of packages that must be installed before the package may itself be
     installed.
 
+    Variable substitutions are performed on the value of this field.
+
   * `Conflicts` (optional)  
 
+    Variable substitutions are performed on the value of this field.
+
   * `Provides` (optional)  
 
+    Variable substitutions are performed on the value of this field.
+
   * `Replaces` (optional)  
 
+    Variable substitutions are performed on the value of this field.
+
   * `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.
+
+    Variable substitutions are performed on the value of this field.
diff --git a/specs/spf-2.0/overview.mdwn b/specs/spf-2.0/overview.mdwn
index 9dcdda0..d75642c 100644
--- a/specs/spf-2.0/overview.mdwn
+++ b/specs/spf-2.0/overview.mdwn
@@ -59,9 +59,12 @@ tree:
      +- platconf
      |      Optional.
      |      A list of build-time configuration files.
-     \- src/
+     +- src/
+     |      Optional.
+     |      Package sources (for native packages).
+     \- substvars
             Optional.
-            Package sources (for native packages).
+            Definitions of substitution variables.
 
 
 Descriptions of Files [files]
@@ -234,3 +237,12 @@ See $[sectlink][platconf] for the syntax of this file.
 This directory is optional.
 
 This directory contains the source files for native packages.
+
+`substvars` [files-substvars]
+-----------------------------
+
+This file is optional.
+
+This file contains control fields defining substitution variables.  See
+$[sectlink][control] for the syntax of this file and $[sectlink][substvars] for
+more information about substitution variables.
diff --git a/specs/spf-2.0/substvars.mdwn b/specs/spf-2.0/substvars.mdwn
new file mode 100644
index 0000000..bbe2853
--- /dev/null
+++ b/specs/spf-2.0/substvars.mdwn
@@ -0,0 +1,19 @@
+Variable Names [substvars-name]
+===============================
+
+Variable names may only consist of uppercase and lowercase Latin letters,
+digits, and hyphens.  Names must be at least one character long.  (A regular
+expression for this is `[A-Za-z0-9-]+`.)
+
+
+Variable Substitutions [substvars-exp]
+======================================
+
+Variable substitutions are performed on certain binary control field values, as
+explained in $[sectlink][fields-bin].
+
+The format for variable substitutions is as follows:
+
+    ${<var-name>}
+
+`<var-name>` is the name of the variable.