move most of README into the manual

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

4 files changed, 193 insertions, 142 deletions

diff --git a/README.rst b/README.rst
index 2011e05..1134c79 100644
--- a/README.rst
+++ b/README.rst
@@ -63,155 +63,33 @@ images.
 
 We also have a few nice macros defined, though nothing too clever yet.
 
-Try it out / quick start
-========================
+Installation and usage
+======================
 
-1. Enable `Debian experimental`_, then ``apt-get install
-   cl-consfigurator/experimental`` (should work fine on Debian stable, testing
-   and unstable), or ``(ql:quickload "consfigurator")`` (see `Quicklisp`_).
-   If you would like to follow development more closely, you can clone this
-   repo to ``~/.local/share/common-lisp/source`` and ASDF should pick it up.
+Please see the `user's manual`_ which includes a tutorial/quick start guide.
 
-.. _Quicklisp: https://www.quicklisp.org/
-.. _Debian experimental: https://wiki.debian.org/DebianExperimental
-
-2. Create a new directory ``consfig`` somewhere where ASDF will pick it up,
-   such as ``~/common-lisp/consfig``.
-
-3. Define a Lisp system which represents your configuration.
-
-    ~/common-lisp/consfig/com.example.consfig.asd::
-
-        (asdf:defsystem :com.example.consfig
-          :serial t
-          :depends-on (#:consfigurator #:cl-interpol)
-          :components ((:file "package")
-                       (:file "consfig")))
-
-    ~/common-lisp/consfig/package.lisp::
-
-        (in-package :cl-user)
-
-        (defpackage :com.example.consfig
-          (:use #:cl #:consfigurator #:alexandria)
-          (:local-nicknames (#:file      #:consfigurator.property.file)
-                            (#:cmd       #:consfigurator.property.cmd)
-                            (#:data.pgp  #:consfigurator.data.pgp)))
-
-4. Define some hosts and deployments.
-
-    ~/common-lisp/consfig/consfig.lisp::
-
-        (in-package :com.example.consfig)
-        (in-consfig "com.example.consfig")
-	(named-readtables:in-readtable :interpol-syntax)
-
-	(try-register-data-source
-         :pgp :location #P"/path/to/com.example.consfig.gpg")
-
-        (defhost athena.example.com
-	    (:deploy (:ssh (:sudo :as "spwhitton@athena.example.com") :debian-sbcl))
-          "Web and file server."
-	  (file:has-content "/etc/foo" '("these" "are" "my" "lines"))
-	  (file:contains-lines "/etc/some.conf" '("FOO=bar")))
-
-    Here, "spwhitton" is my username on athena; we have to tell Consfigurator
-    what user it will be when it tries to sudo, so it knows whose password it
-    needs.  If you have passwordless sudo access configured, you can skip the
-    ``:AS`` keyword parameter and its argument.
-
-5. Get a Lisp REPL started up -- ``M-x slime`` in Emacs or ``sbcl`` at a shell
-   prompt.  Evaluate ``(asdf:load-system "consfigurator")``.
-
-6. When it's asked to use sudo to become root, Consfigurator will query your
-   registered sources of secrets to try to find the password it will need to
-   give to sudo.  You can easily write code to let Consfigurator query your
-   own sources of secrets, but for the purposes of this guide we'll use the
-   simple, PGP-based secrets source included with Consfigurator.  Unless
-   you've passwordless sudo access set up on athena, evaluate something like
-   this to initialise the store::
-
-     (consfigurator.data.pgp:set-data #P"/path/to/com.example.consfig.gpg"
-                                      "--user-passwd--athena.example.com"
-				      "spwhitton"
-				      "s3cre+")
-
-7. Now you can evaluate ``(asdf:load-system "com.example.consfig")`` followed
-   by ``(in-package :com.example.consfig)`` (or ``C-c ~`` in Emacs).  In the
-   future, now the secrets store exists, you can start with this step.
-
-8. You should now be able to evaluate ``(athena.example.com)`` to deploy
-   properties to athena, using the connection chain of SSH, sudo and then
-   handing over to a remote Lisp image.
-
-Other things to try
--------------------
-
-Note that some of these violate some of the ideas of declarative configuration
-management, because they apply individual properties without updating the
-definitions of hosts.  Sometimes that's the right thing to do, though, and
-Consfigurator makes it easy to reuse your property definitions in these
-non-declarative ways.
-
-Try deploying properties to athena using a different connection type
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Evaluate something like::
-
-  (deploy :ssh athena.example.com)
-
-Apply a security update to all your systems
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-It's useful to be able to quickly apply a security update across multiple
-machines without otherwise interacting with their configuration.  Supposing
-you have defined a variable ``*ALL-MY-SERVERS*`` which is a list hosts defined
-with ``DEFHOST``, you can evaluate::
-
-  (dolist (server *all-my-servers*)
-    (deploy-these :ssh server
-                  (cmd:single "apt-get update && apt-get upgrade openssl")))
-
-Regex replace a file across hosts
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-With ``*ALL-MY-SERVERS*`` as in the previous example,::
-
-  (dolist (server *all-my-servers*)
-    (deploy-these :ssh server
-                  (file:regex-replace-lines "/etc/baz" #?/foo/ "bar")))
-
-(relies on CL-INTERPOL syntax being enabled, as it is in the example consfig
-above)
-
-Portability and stability
-=========================
-
-- **Consfigurator is still stabilising and so there may be lots of breaking
-  changes.**
-
-- All of the code should be portable ANSI Common Lisp, but little to no
-  testing is done by the author on implementations other than SBCL, so testing
-  and portability patches are welcome.
-
-- Little attempt is made by the author to support systems other than Debian
-  GNU/Linux, but again, portability patches are welcome, and the design of
-  Consfigurator should enable supporting other systems.
+.. _user's manual: https://spwhitton.name/doc/consfigurator/
 
 Bug reports, patches etc.
 =========================
 
-Please see the included CONTRIBUTING.rst.
+Please see CONTRIBUTING.rst, included in the source tree, for information
+regarding the reporting of bugs and submission of patches/pull requests.
 
-Credits
+License
 =======
 
-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-type connections and arbitrary connection nesting, and I
-wanted to implement that in Lisp (Propellor only supports something equivalent
-to a single, unnested Lisp-type connection).  Additionally, 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.
+Copyright (C) 2020-2021  Sean Whitton
+
+Consfigurator is free software: you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later
+version.
+
+Consfigurator is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+details.
 
-.. Propellor_: https://propellor.branchable.com/
+You should have received a copy of the GNU General Public License along with
+Consfigurator.  If not, see <http://www.gnu.org/licenses/>.
diff --git a/doc/index.rst b/doc/index.rst
index e48bde5..55c910c 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -6,6 +6,7 @@ Consfigurator user's manual
    :caption: Contents:
 
    introduction
+   installation
    connections
    properties
    hosts
diff --git a/doc/installation.rst b/doc/installation.rst
new file mode 100644
index 0000000..42b23c5
--- /dev/null
+++ b/doc/installation.rst
@@ -0,0 +1,31 @@
+.. _Installation:
+
+Installation
+============
+
+Debian and Debian derivatives
+-----------------------------
+
+The most recent tagged release of Consfigurator is included in `Debian
+experimental`_, and the .deb there should work fine on Debian stable, testing
+and unstable, and derivatives like Ubuntu.  After enabling the repository,
+``apt-get install cl-consfigurator/experimental``.
+
+.. _Debian experimental: https://wiki.debian.org/DebianExperimental
+
+Quicklisp
+---------
+
+The most recent tagged release of Consfigurator is included in the
+`Quicklisp`_ service: ``(ql:quickload "consfigurator")``.
+
+.. _Quicklisp: https://www.quicklisp.org/
+
+From git
+--------
+
+If you would like to follow development more closely, you can::
+
+    % git clone https://git.spwhitton.name/consfigurator ~/.local/share/common-lisp/source/consfigurator
+
+and ASDF should pick it up.
diff --git a/doc/introduction.rst b/doc/introduction.rst
index 1b1e85b..e62f6b6 100644
--- a/doc/introduction.rst
+++ b/doc/introduction.rst
@@ -1,6 +1,120 @@
 Introduction
 ============
 
+Try it out / quick start
+------------------------
+
+1. Install Consfigurator: :ref:`Installation`.
+
+2. Create a new directory ``consfig`` somewhere where ASDF will pick it up,
+   such as ``~/common-lisp/consfig``.
+
+3. Define a Lisp system which represents your configuration.
+
+    ~/common-lisp/consfig/com.example.consfig.asd::
+
+        (asdf:defsystem :com.example.consfig
+          :serial t
+          :depends-on (#:consfigurator #:cl-interpol)
+          :components ((:file "package")
+                       (:file "consfig")))
+
+    ~/common-lisp/consfig/package.lisp::
+
+        (in-package :cl-user)
+
+        (defpackage :com.example.consfig
+          (:use #:cl #:consfigurator #:alexandria)
+          (:local-nicknames (#:file      #:consfigurator.property.file)
+                            (#:cmd       #:consfigurator.property.cmd)
+                            (#:data.pgp  #:consfigurator.data.pgp)))
+
+4. Define some hosts and deployments.
+
+    ~/common-lisp/consfig/consfig.lisp::
+
+        (in-package :com.example.consfig)
+        (in-consfig "com.example.consfig")
+	(named-readtables:in-readtable :interpol-syntax)
+
+	(try-register-data-source
+         :pgp :location #P"/path/to/com.example.consfig.gpg")
+
+        (defhost athena.example.com
+	    (:deploy (:ssh (:sudo :as "spwhitton@athena.example.com") :debian-sbcl))
+          "Web and file server."
+	  (file:has-content "/etc/foo" '("these" "are" "my" "lines"))
+	  (file:contains-lines "/etc/some.conf" '("FOO=bar")))
+
+    Here, "spwhitton" is my username on athena; we have to tell Consfigurator
+    what user it will be when it tries to sudo, so it knows whose password it
+    needs.  If you have passwordless sudo access configured, you can skip the
+    ``:AS`` keyword parameter and its argument.
+
+5. Get a Lisp REPL started up -- ``M-x slime`` in Emacs or ``sbcl`` at a shell
+   prompt.  Evaluate ``(asdf:load-system "consfigurator")``.
+
+6. When it's asked to use sudo to become root, Consfigurator will query your
+   registered sources of secrets to try to find the password it will need to
+   give to sudo.  You can easily write code to let Consfigurator query your
+   own sources of secrets, but for the purposes of this guide we'll use the
+   simple, PGP-based secrets source included with Consfigurator.  Unless
+   you've passwordless sudo access set up on athena, evaluate something like
+   this to initialise the store::
+
+     (consfigurator.data.pgp:set-data #P"/path/to/com.example.consfig.gpg"
+                                      "--user-passwd--athena.example.com"
+				      "spwhitton"
+				      "s3cre+")
+
+7. Now you can evaluate ``(asdf:load-system "com.example.consfig")`` followed
+   by ``(in-package :com.example.consfig)`` (or ``C-c ~`` in Emacs).  In the
+   future, now the secrets store exists, you can start with this step.
+
+8. You should now be able to evaluate ``(athena.example.com)`` to deploy
+   properties to athena, using the connection chain of SSH, sudo and then
+   handing over to a remote Lisp image.
+
+Other things to try
+~~~~~~~~~~~~~~~~~~~
+
+Note that some of these violate some of the ideas of declarative configuration
+management, because they apply individual properties without updating the
+definitions of hosts.  Sometimes that's the right thing to do, though, and
+Consfigurator makes it easy to reuse your property definitions in these
+non-declarative ways.
+
+Try deploying properties to athena using a different connection type
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Evaluate something like::
+
+  (deploy :ssh athena.example.com)
+
+Apply a security update to all your systems
++++++++++++++++++++++++++++++++++++++++++++
+
+It's useful to be able to quickly apply a security update across multiple
+machines without otherwise interacting with their configuration.  Supposing
+you have defined a variable ``*ALL-MY-SERVERS*`` which is a list hosts defined
+with ``DEFHOST``, you can evaluate::
+
+  (dolist (server *all-my-servers*)
+    (deploy-these :ssh server
+                  (cmd:single "apt-get update && apt-get upgrade openssl")))
+
+Regex replace a file across hosts
++++++++++++++++++++++++++++++++++
+
+With ``*ALL-MY-SERVERS*`` as in the previous example,::
+
+  (dolist (server *all-my-servers*)
+    (deploy-these :ssh server
+                  (file:regex-replace-lines "/etc/baz" #?/foo/ "bar")))
+
+(relies on CL-INTERPOL syntax being enabled, as it is in the example consfig
+above)
+
 Concepts and terminology
 ------------------------
 
@@ -135,3 +249,30 @@ recommended package nicknaming schemes for use in consfigs, e.g.::
     (:local-nicknames (#:file        #:consfigurator.property.file)
                       (#:cmd         #:consfigurator.property.cmd)
 		      (#:data.pgp    #:consfigurator.data.pgp)))
+
+Portability and stability
+-------------------------
+
+- **Consfigurator is still stabilising and so there may be lots of breaking
+  changes.**
+
+- All of the code should be portable ANSI Common Lisp, but little to no
+  testing is done by the author on implementations other than SBCL, so testing
+  and portability patches are welcome.
+
+- Little attempt is made by the author to support systems other than Debian
+  GNU/Linux, but again, portability patches are welcome, and the design of
+  Consfigurator should enable supporting other systems.
+
+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-type connections and arbitrary connection nesting, and I
+wanted to implement that in Lisp (Propellor only supports something equivalent
+to a single, unnested Lisp-type connection).  Additionally, 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/