add examples to README

Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>

1 files changed, 57 insertions, 8 deletions

diff --git a/README.rst b/README.rst
index 91ed043..0b7ddb2 100644
--- a/README.rst
+++ b/README.rst
@@ -5,16 +5,52 @@ Consfigurator is a system for declarative configuration management using
 Common Lisp.  You can use it to configure hosts as root, deploy services as
 unprivileged users, and build disc images.
 
-Many or all of the good ideas here come straight from Joey Hess's Propellor_.
-I'm working on Consfigurator mainly because I think Propellor is great and
-reimplementing those ideas is good practice in writing Common Lisp, but also
-because after five years of using and extending Propellor, I've come to
-disagree with Joey about whether Haskell's type system helps or hinders using
-and extending Propellor.
+Quick start / introduction
+==========================
 
-.. Propellor_ https://propellor.branchable.com/
+1. Create a new directory ``consfig`` somewhere where ASDF will pick it up,
+   such as ``~/common-lisp/consfig``.
+
+2. Define a Lisp system which represents your configuration.
+
+    ~/common-lisp/consfig/com.example.consfig::
+
+        (asdf:defsystem :com.example.consfig
+          :serial t
+          :depends-on (#:consfigurator)
+          :components ((:file "package")
+                       (:file "consfig")))
+
+    ~/common-lisp/consfig/package.lisp::
+
+        (in-package :cl-user)
+
+        (defpackage :com.example.consfig
+          (:use #:cl #:consfigurator)
+          (:local-nicknames (#:file #:consfigurator.property.file)))
+
+3. Define some hosts and connections.
+
+    ~/common-lisp/consfig/consfig.lisp::
+
+        (in-package :com.example.consfig)
 
-Portabiilty and stability
+        (setconsfig :com.example.consfig)
+
+        (defhost athena.example.com
+          "Web and file server."
+          (file:contains-lines "/etc/default/locale" '("LANG=en_GB.UTF-8")))
+
+        (defhostdeploy :ssh athena.example.com)
+
+4. Get a Lisp REPL started up and evaluate ``(asdf:require-system
+   "com.example.consfig")``.
+
+5. Now you should be able to use configure athena by evaulating
+   ``(athena.example.com)``.  You can use the DEPLOY function to try out
+   configuring athena using a different connection type than defined here.
+
+Portability and stability
 =========================
 
 - **Consfigurator is still stabilising and so there may be breaking changes.**
@@ -25,3 +61,16 @@ Portabiilty and stability
 - No attempt is made to support running on Windows -- we often eschew Common
   Lisp pathnames in favour of simple strings with forward slashes as directory
   separators.
+
+Credits
+=======
+
+Many of the good ideas here come straight from Joey Hess's Propellor_.  I'm
+working on Consfigurator because I think Propellor is great, but wanted to add
+Consfigurator's ``:posix`` connections and arbitrary connection nesting --
+Propellor supports something equivalent to a single ``:lisp`` connection --
+and I wanted to implement that in Lisp.  Also, after five years of using and
+extending Propellor, I've come to disagree with Joey about whether Haskell's
+type system helps or hinders using and extending Propellor.
+
+.. Propellor_ https://propellor.branchable.com/