From 853a06b6be016bf6ba22de30579b0ae7a108a892 Mon Sep 17 00:00:00 2001
From: P. J. McDermott <pehjota>
Date: Sun, 18 Nov 2012 20:03:43 -0500
Subject: Add tutorial sections on docs and substvars.

---
(limited to 'dev/packaging/tutorials')

diff --git a/dev/packaging/tutorials/basic.mdwn b/dev/packaging/tutorials/basic.mdwn
index fc2ec65..4852908 100644
--- a/dev/packaging/tutorials/basic.mdwn
+++ b/dev/packaging/tutorials/basic.mdwn
@@ -496,6 +496,91 @@ So our `build` makefile should now look like this:
     	oh-installfiles
 
 
+Documentation and Finishing Touches
+===================================
+
+Source Package Documentation
+----------------------------
+
+SPF 2.0 [specifies][spf-docs] that one of the binary packages built from a
+source package provides documentation files about the source package and is
+depended upon by all of the other binary packages from the source package.
+
+So we should pick one common binary package that should be a dependency of all
+of our other binary packages.  `libexpat.1` is a good candidate for this, since
+it is already a direct dependency of `libexpat.1-dev` and `xmlwf` and an
+indirect dependency of `xmlwf-doc`.
+
+Per SPF 2.0, we can mark `libexpat.1` as providing source package documentation
+by making a `docs` file in its metadata directory.
+
+    $ touch libexpat.1.pkg/docs
+
+We should make all of our other binary packages directly depend on `libexpat.1`
+version `2.1.0-1`.  For example, `xmlwf-doc.pkg/control` should now look like
+this:
+
+    Architecture: all 
+    Platform: all 
+    Depends: libexpat.1 (= 2.1.0-1), xmlwf
+    Description: XML parser library - example application documentation files
+     This package provides the manual page for xmlwf, an example application of
+     Expat that determines if an XML document is well-formed.
+
+Substitution Variables
+----------------------
+
+We've hardcoded the `libexpat.1` binary package version in many of our control
+files.  What will we do when we make a new version of our source package?  We'll
+have to change all of these values in all of these places.
+
+[*Substitution variables*][spf-substvars] (*substvars* for short) make this
+unnecessary.  We can just use the `Binary-Version` substitution variable in our
+control files to refer to the version of our binary packages.  For example, our
+`xmlwf-doc.pkg/control` file should now look like this:
+
+    Architecture: all 
+    Platform: all 
+    Depends: libexpat.1 (= ${Binary-Version}), xmlwf
+    Description: XML parser library - example application documentation files
+     This package provides the manual page for xmlwf, an example application of
+     Expat that determines if an XML document is well-formed.
+
+But that's not all!  We can define our own variables as well.
+
+Note that the descriptions of our `libexpat.1` and `libexpat.1-dev` packages
+have a common paragraph.  We can put that in a file called `substvars`:
+
+    Common-Description:
+     Expat is an XML parser library written in C. It is a stream-oriented parser in
+     which an application registers handlers for things the parser might find in the
+     XML document (like start tags).
+
+As noted by the SPF 2.0 specification, the leading newline character in the
+value is fine:
+
+> Values may be comprised of multiple lines, and empty lines at the beginning
+> and end of each substitution variable value shall be removed.
+
+We can now use this variable in our `control` files.  Here's
+`libexpat.1.pkg/control`:
+
+    Architecture: any
+    Platform: all
+    Description: XML parser library
+     ${Common-Description}
+
+And here's `libexpat.1-dev.pkg/control`:
+
+    Architecture: any
+    Platform: all
+    Depends: libexpat.1 (= ${Binary-Version})
+    Description: XML parser library - development files
+     ${Common-Description}
+     .
+     This package provides development files for Expat.
+
+
 TODO: Finish.
 
 
@@ -517,3 +602,5 @@ TODO: Finish.
 [posix-colon]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#colon
 [spf-binpkg.pkg]: http://specs.os.libiquity.com/spf-2.0/overview.html#files-binpkg.pkg
 [spf-fields-bin]: http://specs.os.libiquity.com/spf-2.0/fields.html#fields-src
+[spf-docs]: http://specs.os.libiquity.com/spf-2.0/metadata.html#docs
+[spf-substvars]: http://specs.os.libiquity.com/spf-2.0/substvars.html
--
cgit v0.9.1