Update README

1 files changed, 77 insertions, 12 deletions

diff --git a/README b/README
index aaa9e7f..0b28116 100644
--- a/README
+++ b/README
@@ -6,32 +6,97 @@ vmdb2 is a program for producing a disk image with Debian installed.
 Introduction
 -----------------------------------------------------------------------------
 
-[vmdebootstrap][] installs Debian onto a disk, or disk image. It is
-like the [debootstrap][] tool, except the end result is a disk or disk
-image, not a directory. vmdebootstrap takes care of creating
-partitions, and filesystems, and allows some more customization than
-vmdebootstrap does.
+[vmdebootstrap][] installs Debian onto a disk image. It is like the
+[debootstrap][] tool, except the end result is a bootable disk image,
+not a directory (FIXME: can't yet install a bootloader). vmdebootstrap
+takes care of creating partitions, and filesystems, and allows some
+more customization than the older vmdebootstrap does.
 
-vmdebootstrap is also a messy pile of kludge, and not flexible enough.
+vmdebootstrap is also a messy pile of kludge, and rather inflexible.
 vmdb2 is a re-implementation from scratch, without a need for
 backwards compatibility. It aims to provide more flexibility than
-vmdeboostrap, without becoming anywhere near as complicated. Think of
+vmdebootstrap, without becoming anywhere near as complicated. Think of
 vmdb2 as "vmdebootstrap the second generation". The name has changed
 to allow the two tools to installable in paralllel.
 
 The main user-visible difference between vmdebootstrap and vmdb2 is
-that the older program provides extensibitlity via a legion of command
-line options and the newer program by having the user user a domain
-specific language to express what kind of Debian system they want to
-create.
+that the older program provides extensibility via a legion of command
+line options and the newer program by providing a domain specific
+language to express what kind of Debian system is to be created.
 
 (Lars Wirzenius wrote both vmdebootstrap and vmdb2 and is entitled to
-sneer at his younger self.)
+sneer at his younger self. It's his way of dealing with the mountain
+of guilt of making something as awful as vmdebootstrap.)
 
 [vmdebootstrap]: http://liw.fi/vmdebootstrap/
 [debootstrap]: https://packages.debian.org/unstable/debootstrap
 
 
+Tutorial
+-----------------------------------------------------------------------------
+
+To use vmdb2, git clone the source and at the root of the source tree
+run the following command:
+
+    sudo ./vmdb2 --output simple.img simple.yaml --log simple.log
+
+`--output simple.img` specifies that the output image is called
+`simple.img`, the specification is `simple.yaml` and the log file goes
+to `simple.log`.
+
+
+Plugins and steps
+-----------------------------------------------------------------------------
+
+The `vmdb2` architecture consists of a main program that reads the
+input file, finds a matching "step runner" for each step used in the
+input file, and then runs the steps in order. If there's a problem, it
+runs corresponding "teardown" steps in reverse order of the steps.
+
+A step might be "mount this filesystem", and the corresponding
+teardown is "unmount".
+
+Steps (and teardowns) are provided by plugins; see the `vmdb/plugins`
+directory in the source tree. Steps are intended to be very cohesive
+and lowly coupled. They may share some state (such as mounted
+filesystems) via the `State` object, but not in any other way. A
+plugin may provide multiple steps.
+
+See the plugin directory for which steps currently exist. A list of
+steps that will become incomplete as soon as development continues:
+
+* chroot (run shell snippet in chroot)
+* shell (run shell snippet without chroot)
+* debootstrap (run deboostrap)
+* kernel (installs kernel)
+* mkimg (create disk image)
+* mklabel (create partition table on a disk image)
+* mkpart (create partition)
+* mkfs (create filesystem in a partition)
+* mount (mount filesystem, teardown unmounts it automatically)
+
+See `simple.yaml` for examples. Note how the file uses Jinja2
+templating for value fields to get value of `--output` in the right
+places. Also note how creating a partition or mounting a filesystem
+assigns a "tag" that can be referenced in steps where the
+partition/filesystem is needed, without having to know the actual path
+to the device node or mount point.
+
+
+Writing plugins
+-----------------------------------------------------------------------------
+
+More step runners would be good, and will be added based on
+actual reported needs by users ("I need to have this to..."), not
+speculatively ("This seems like a good idea").
+
+To write a plugin, see the existing ones for examples, and put it in
+`vmdb/plugins/foo_plugin.py` for some value of `foo`.
+
+Plugins are meant to be very easy to write. If not, there's probably
+something wrong with `vmdb2`. Please raise the issue.
+
+
 Hacking
 -----------------------------------------------------------------------------