fill out README with some more general description and some fixes

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

1 files changed, 48 insertions, 15 deletions

diff --git a/README.rst b/README.rst
index 0b7ddb2..c42256f 100644
--- a/README.rst
+++ b/README.rst
@@ -3,17 +3,49 @@ Introduction
 
 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.
+unprivileged users, build and deploy containers, and produce disc images.
+
+Consfigurator's design gives you a great deal of flexibility about how to
+control the hosts you want to configure.  Input and output streams attached to
+an interactive POSIX sh running on the target host (or in the target
+container) is sufficient to use much of Consfigurator's functionality.  But if
+it is possible to get an implementation of Common Lisp started up on the host,
+then Configurator can transparently execute your deployment code over on the
+remote side, rather than exchanging information via POSIX sh.  This lets you
+use the full power of Common Lisp to deploy your configuration.
+
+Configurator has convenient abstractions for combining these different ways to
+execute your configuration on hosts with different ways of connecting to them.
+Connections can be arbitrarily nested.  For example, to combine SSHing to a
+Debian machine as an unprivileged user, using sudo to become root, and then
+starting up a Lisp process to execute your deployment code, you would just
+evaluate ``(deploy (:ssh (:sudo :user "root") :debian-sbcl) foo.example.com)``.
+
+Declarative configuration management systems like Consfigurator and Propellor_
+share a number of goals with projects like the `GNU Guix System`_ and
+`NixOS`_.  However, tools like Consfigurator and Propellor try to layer the
+power of declarative and reproducible configuration on top of traditional,
+battle-tested unix system administration infrastructure like apt, dpkg, yum,
+and distro package archives, rather than seeking to replace any of those.
+Let's get as much as we can out of all that existing distro policy-compliant
+work!
+
+.. _Propellor: https://propellor.branchable.com/
+.. _GNU Guix System: https://guix.gnu.org/
+.. _NixOS: https://nixos.org/
 
 Quick start / introduction
 ==========================
 
-1. Create a new directory ``consfig`` somewhere where ASDF will pick it up,
+1. Install Steel Bank Common Lisp and Consfigurator.  One way to do the latter
+   is to clone this git repository into ``~/.local/share/common-lisp/source``.
+
+2. 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.
+3. Define a Lisp system which represents your configuration.
 
-    ~/common-lisp/consfig/com.example.consfig::
+    ~/common-lisp/consfig/com.example.consfig.asd::
 
         (asdf:defsystem :com.example.consfig
           :serial t
@@ -29,7 +61,7 @@ Quick start / introduction
           (:use #:cl #:consfigurator)
           (:local-nicknames (#:file #:consfigurator.property.file)))
 
-3. Define some hosts and connections.
+4. Define some hosts and connections.
 
     ~/common-lisp/consfig/consfig.lisp::
 
@@ -43,12 +75,13 @@ Quick start / introduction
 
         (defhostdeploy :ssh athena.example.com)
 
-4. Get a Lisp REPL started up and evaluate ``(asdf:require-system
-   "com.example.consfig")``.
+5. Get a Lisp REPL started up -- ``M-x slime`` in Emacs or ``sbcl`` at a shell
+   prompt.  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.
+6. Now you should be able to use configure athena by evaulating
+   ``(com.example.consfig:athena.example.com)``.  You can use the
+   ``CONSFIGURATOR:DEPLOY`` function to try out configuring athena using a
+   different connection type than defined here.
 
 Portability and stability
 =========================
@@ -68,9 +101,9 @@ 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 supports something equivalent to a single, unnested ``: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/
+.. Propellor_: https://propellor.branchable.com/