Move cleanly section into its own chapter

2 files changed, 52 insertions, 54 deletions

diff --git a/doc/050-debian.yarn b/doc/050-debian.yarn
index 8620720..5b1b677 100644
--- a/doc/050-debian.yarn
+++ b/doc/050-debian.yarn
@@ -1,4 +1,4 @@
-# Building Debian packages
+# Building Debian packages: a discussion
 
 Ick projects may be marked as type `debian`, which means that instead
 of running arbitrary shell commands, Ick runs a built-in sequence of
@@ -203,56 +203,3 @@ will use both pockets, but release builds only the release pocket.
 FIXME: Further builds should use that APT repository.
 
 FIXME: signing packages?
-
-
-## The `cleanly` helper tool
-
-The Debian package build pipeline contains a number of steps. To allow
-the steps to be easily combined and reordered, the are not integrated
-deeply into the Ick program, but provided by a separate helper program
-instead, called `cleanly`. This de-couples the pipeline and Ick, and
-allows the pipeline to be used with other CI systems as well. This
-section describes how `cleanly` works.
-
-### Extract project metadata
-
-The first thing we need to do is determine, preferably automatically,
-what the name of the project is and what its version is.
-
-    SCENARIO cleanly performs pipeline steps
-    GIVEN a source code repository for project foo version 1.2-1
-
-    WHEN user runs, in foo, cleanly get-name
-    THEN the output is "foo\n"
-
-    WHEN user runs, in foo, cleanly get-upstream-version
-    THEN the output is "1.2\n"
-
-### Create upstream release tar archive
-
-We create a tar archive by extracing the source code from git. The
-operation needs to know the upstream name and version number.
-
-    WHEN user runs, in foo, cleanly tarball
-    THEN file foo-1.2.tar.xz exists
-
-### Create Debian source package
-
-Next up is the Debian source package. We assume the upstream project
-provides the Debian packaging files in the same branch and that the
-Debian version part is just 1. (FIXME: This will need to be made more
-flexible later.)
-
-    WHEN user runs, in foo, cleanly dsc
-    THEN file foo_1.2.orig.tar.xz exists
-    AND file foo_1.2-1.debian.tar.xz exists
-    AND file foo_1.2-1.dsc exists
-
-### Build a Debian binary package
-
-This is where things get interesting. We build a Debian binary
-package, given a source package. (Note that for this, we fake the
-actual build to avoid having to have `root` access.)
-
-    WHEN user runs, in foo, cleanly deb
-    THEN file foo_1.2-1_all.deb exists
diff --git a/doc/060-cleanly.yarn b/doc/060-cleanly.yarn
new file mode 100644
index 0000000..c7045cc
--- /dev/null
+++ b/doc/060-cleanly.yarn
@@ -0,0 +1,51 @@
+# The `cleanly` helper tool
+
+The Debian package build pipeline contains a number of steps. To allow
+the steps to be easily combined and reordered, the are not integrated
+deeply into the Ick program, but provided by a separate helper program
+instead, called `cleanly`. This de-couples the pipeline and Ick, and
+allows the pipeline to be used with other CI systems as well. This
+section describes how `cleanly` works.
+
+## Extract project metadata
+
+The first thing we need to do is determine, preferably automatically,
+what the name of the project is and what its version is.
+
+    SCENARIO cleanly performs pipeline steps
+    GIVEN a source code repository for project foo version 1.2-1
+
+    WHEN user runs, in foo, cleanly get-name
+    THEN the output is "foo\n"
+
+    WHEN user runs, in foo, cleanly get-upstream-version
+    THEN the output is "1.2\n"
+
+## Create upstream release tar archive
+
+We create a tar archive by extracing the source code from git. The
+operation needs to know the upstream name and version number.
+
+    WHEN user runs, in foo, cleanly tarball
+    THEN file foo-1.2.tar.xz exists
+
+## Create Debian source package
+
+Next up is the Debian source package. We assume the upstream project
+provides the Debian packaging files in the same branch and that the
+Debian version part is just 1. (FIXME: This will need to be made more
+flexible later.)
+
+    WHEN user runs, in foo, cleanly dsc
+    THEN file foo_1.2.orig.tar.xz exists
+    AND file foo_1.2-1.debian.tar.xz exists
+    AND file foo_1.2-1.dsc exists
+
+## Build a Debian binary package
+
+This is where things get interesting. We build a Debian binary
+package, given a source package. (Note that for this, we fake the
+actual build to avoid having to have `root` access.)
+
+    WHEN user runs, in foo, cleanly deb
+    THEN file foo_1.2-1_all.deb exists