tidy up existing docs

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

1 files changed, 44 insertions, 41 deletions

diff --git a/doc/properties.rst b/doc/properties.rst
index 8da97c1..79808e3 100644
--- a/doc/properties.rst
+++ b/doc/properties.rst
@@ -1,42 +1,50 @@
+Properties
+==========
+
 Property subroutines
-~~~~~~~~~~~~~~~~~~~~
+--------------------
+
+A property is composed of four subroutines, which all take the same
+arguments.  At least one of ``:hostattrs`` or ``:apply`` must be present.
 
 ``:hostattrs`` subroutines
-==========================
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Executed in the root Lisp to (i) add and modify static informational
+attributes of hosts to which this property is applied or is to be applied;
+and (ii) check that applying this property makes sense -- e.g. that we're not
+trying to install a package using apt(1) on a FreeBSD host.
+
+When this subroutine is called, ``*HOSTATTRS*`` will be bound to the plist of
+static informational attributes of the host to which the property is to be
+applied, which may be modified.
 
-When this subroutine is executed, consfigurator:*hostattrs* will be bound to
-the plist of static information attributes of the host to which the property
-has been applied or is to be applied.  This subroutine typically pushes new
-entries to this list, but it might also modify existing entries (e.g. by
-pushing new entries to a sublist).
+Should signal the condition ``INCOMPATIBLE-PROPERTY`` if the contents of
+``*HOSTATTRS*`` indicates that the property should not be applied to this
+host.
 
-Should be a pure function aside from looking at consfigurator:*hostattrs*.
-Essentially just a conversion of the arguments to the property to
-informational attributes.
+Should be a pure function aside from looking at and modifying ``*HOSTATTRS*``.
+In particular, should not examine the actual state of the host.  Essentially a
+conversion of the arguments to the property to appropriate static information
+attributes.
 
 ``:check`` subroutines
-======================
+~~~~~~~~~~~~~~~~~~~~~~
 
 Determine whether or not the property is already applied to the host and
 return a generalised boolean indicating such.  Whether or not the ``:apply``
-and ``:unapply`` subroutines get called depends on this return value.
+and ``:unapply`` subroutines get called depends on this return value.  If
+absent, it is always assumed the property is applied, i.e., an attempt to
+apply the property will always be made.
 
 ``:apply`` and ``:unapply`` subroutines
-=======================================
-
-The return value or values is up to you, but a few keywords as the first
-return value are treated specially.
-
-- ``:madechange`` -- the property was not (fully) applied before we ran, but
-  now it is.
-
-- ``:nochange`` -- the property was already applied
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If neither of these values are returned but one of the ``:apply`` and
-``:unapply`` subroutines was executed, then it is assumed that the property
-did make a change.  If the ``:check`` function indicated that neither of these
-subroutines should be run, it is assumed that the property did not make a
-change.
+Apply or unapply the property.  Should return ``:nochange`` if the property
+was already applied; any other return value is interpreted as meaning that the
+property was not (fully) applied before we ran, but now it is.  (If the
+``:check`` function indicated that neither ``:apply`` nor ``:unapply`` should
+be run, then this is equivalent to those subroutines returning ``:nochange``.)
 
 The point of having both these return value semantics and the ``:check``
 subroutine is that a property might only be able to check whether it made a
@@ -44,24 +52,19 @@ change after trying to apply itself -- it might check whether running a
 command actually made a change to a particular file, for example.
 
 Errors in attempting to apply a property are indicated by signalling a
-``failed-change`` condition.
+``FAILED-CHANGE`` error condition.
 
 ``:posix`` vs. ``:lisp`` properties
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------
 
 ``:posix`` properties should not make any assumptions about what localhost is
 -- they may be running in the root Lisp, but they might be running in a Lisp
 process running on an intermediary host, or even on the host to be configured.
-They should perform I/O only by calling ``run``, ``readfile``, ``writefile``,
-requesting prerequisite data, and applying or unapplying other ``:posix``
-properties.  Otherwise, they should be pure functions.
-
-In this respect, the code which establishes connections (i.e., implementations
-of the ``establish-connection`` generic function) is like a ``:posix``
-property -- it should restrict its I/O to ``run``, ``readfile`` and
-``writefile`` to permit the arbitrary nesting of connections.
-
-``:lisp`` properties, by contrast, may assume that they are running in a Lisp
-process on the host to which they are to be applied, so they can perform
-arbitrary I/O in that context.  They can also make use of ``run``,
-``readfile`` and ``writefile`` if desired.
+They should perform I/O only by calling ``RUN``, ``RUNLINES``, ``READFILE``,
+``WRITEFILE``, requesting prerequisite data, and applying or unapplying other
+``:posix`` properties.  Otherwise, they should be pure functions.
+
+``:lisp`` properties, by contrast, may (and should) assume that they are
+running in a Lisp process on the host to which they are to be applied, so they
+can perform arbitrary I/O in that context.  They can also make use of ``RUN``,
+``RUNLINES``, ``READFILE`` and ``WRITEFILE`` if desired.