Change yarns to show ick files explicitly

This makes them less obscure for readers who do not already know ick
files by heart. Turns out, that includes me.

3 files changed, 53 insertions, 54 deletions

diff --git a/doc/040-simple.yarn b/doc/040-simple.yarn
index 8bd5c15..2a82d4b 100644
--- a/doc/040-simple.yarn
+++ b/doc/040-simple.yarn
@@ -16,7 +16,7 @@ First of all, we need to have a project we build. We call the project
 FOO. For this example, it can be empty, since we don't actually need
 to build anything.
 
-    GIVEN a minimal project repository in FOO
+    GIVEN a minimal project repository in FOO.git
 
 We also need an ick file that specifies the target machine and the
 project. We use `localhost` as the target: we can't assume the
@@ -25,16 +25,27 @@ been set up correctly; most importantly, the user running Ick must
 have ssh access to it, preferably without having to type a key
 passphrase or a login password all the time.
 
-    GIVEN an ick file KITTEN.ick
-    AND KITTEN.ick uses $ICK_TEST_TARGET as a target
-    AND KITTEN.ick builds FOO using project type shell
-    AND KITTEN.ick builds FOO from repository FOO
-    AND KITTEN.ick builds FOO from branch master
-    AND KITTEN.ick builds FOO using "echo BUILDING FOO"
-
-We also want to verify that the source repository has been cloned.
-
-    AND KITTEN.ick builds FOO using "test -d .git"
+    GIVEN an ick file KITTEN.ick containing
+    ... {
+    ...     "state": "KITTEN.state",
+    ...     "targets": {
+    ...         "test": {
+    ...             "address": "$ICK_TEST_TARGET",
+    ...             "pbuilder-ci-tgz": "/var/cache/pbuilder/ci.tgz"
+    ...         }
+    ...     },
+    ...     "projects": {
+    ...         "FOO": {
+    ...             "project-type": "shell",
+    ...             "git": "FOO.git",
+    ...             "branch": "master",
+    ...             "commands": [ "echo BUILDING FOO", "test -d .git" ]
+    ...         }
+    ...     }
+    ... }
+
+The `test` command is there because we want to verify that the source
+repository has been cloned.
 
 Note that we use a very silly command to build the project. The only
 thing we are showing is that Ick runs the build command, not that
diff --git a/doc/070-pipeline.yarn b/doc/070-pipeline.yarn
index b4cc732..51ae419 100644
--- a/doc/070-pipeline.yarn
+++ b/doc/070-pipeline.yarn
@@ -12,11 +12,23 @@ First of all, we need a git repository with some source code.
 
 Then we need an Ick file.
 
-    AND an ick file foo.ick
-    AND foo.ick uses $ICK_TEST_TARGET as a target
-    AND foo.ick builds foo using project type debian
-    AND foo.ick builds foo from repository foo
-    AND foo.ick builds foo from branch master
+    AND an ick file foo.ick containing
+    ... {
+    ...     "state": "foo.state",
+    ...     "targets": {
+    ...         "test": {
+    ...             "address": "$ICK_TEST_TARGET",
+    ...             "pbuilder-ci-tgz": "/var/cache/pbuilder/ci.tgz"
+    ...         }
+    ...     },
+    ...     "projects": {
+    ...         "foo": {
+    ...             "project-type": "debian",
+    ...             "git": "foo",
+    ...             "branch": "master"
+    ...         }
+    ...     }
+    ... }
 
 Then we do the build.
 
diff --git a/doc/900-implements.yarn b/doc/900-implements.yarn
index 8e278c0..4aa30de 100644
--- a/doc/900-implements.yarn
+++ b/doc/900-implements.yarn
@@ -24,51 +24,27 @@ repository has a `master` branch.
 
 ## Ick file handling
 
-Create a basic ick file. Add the state automatically.
+Create an ick file.
 
-    IMPLEMENTS GIVEN an ick file (.+).ick
-    printf "state: %s/%s.state\n" "$DATADIR" "$MATCH_1" \
-        > "$DATADIR/$MATCH_1.ick"
+    IMPLEMENTS GIVEN an ick file (.+).ick containing (.*)
+    # Expand all $foo references.
+    expand_env_vars()
+    {
+        local temp="$(mktemp)"
+        printf '#!/bin/sh\ncat <<EOF\n%s' "$1" > "$temp"
+        sh "$temp"
+        rm -f "$temp"
+    }
 
-Add a target to an ick file.
-
-    IMPLEMENTS GIVEN (.+).ick uses \$ICK_TEST_TARGET as a target
-    "$SRCDIR/yaml-add" "$DATADIR/$MATCH_1.ick" \
-        targets test_target address "$ICK_TEST_TARGET"
-    "$SRCDIR/yaml-add" "$DATADIR/$MATCH_1.ick" \
-        targets test_target pbuilder-ci-tgz /var/cache/pbuilder/ci.tgz
-
-Set project type for a project.
-
-    IMPLEMENTS GIVEN (.+).ick builds (.+) using project type (.+)
-    "$SRCDIR/yaml-add" "$DATADIR/$MATCH_1.ick" \
-        projects "$MATCH_2" project-type "$MATCH_3"
-
-Set repository for a project.
-
-    IMPLEMENTS GIVEN (.+).ick builds (.+) from repository (.+)
-    "$SRCDIR/yaml-add" "$DATADIR/$MATCH_1.ick" \
-        projects "$MATCH_2" git "$DATADIR/$MATCH_3"
-
-Set branch for a project.
-
-    IMPLEMENTS GIVEN (.+).ick builds (.+) from branch (.+)
-    "$SRCDIR/yaml-add" "$DATADIR/$MATCH_1.ick" \
-        projects "$MATCH_2" branch "$MATCH_3"
-
-Add build commands for a project in an ick file.
-
-    IMPLEMENTS GIVEN (.+).ick builds (.+) using "(.+)"
-    "$SRCDIR/yaml-add" "$DATADIR/$MATCH_1.ick" \
-        projects "$MATCH_2" commands '"true"'
-    "$SRCDIR/yaml-add" "$DATADIR/$MATCH_1.ick" \
-        projects "$MATCH_2" commands "$MATCH_3"
+    expand_env_vars "$MATCH_2" > "$DATADIR/$MATCH_1.ick"
 
 ## Running Ick
 
-Run ick, capturing its output for later inspection.
+Run ick, capturing its output for later inspection. We run ick in
+`$DATADIR` so that relative references in the ick file work.
 
     IMPLEMENTS WHEN user runs ick (.+).ick
+    cd "$DATADIR"
     if ! "$SRCDIR/ick" --no-default-config \
         "$DATADIR/$MATCH_1.ick" \
         > "$DATADIR/ick.stdout" 2> "$DATADIR/ick.stderr"