each value in HOSTATTRS plist is now prepend-only

Previous approach would have required us to deep copy the list when we wanted
to use things like DEPLOY, DEPLOY-THESE and connections like :DEBIAN-SBCL, but
that would have meant that adding new kinds of hostattrs would have required
writing copy methods.  The new semantics should enable us to do the same
things with hostattrs with only shallow copying.

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

1 files changed, 19 insertions, 0 deletions

diff --git a/doc/hosts.rst b/doc/hosts.rst
new file mode 100644
index 0000000..885a447
--- /dev/null
+++ b/doc/hosts.rst
@@ -0,0 +1,19 @@
+Hosts
+=====
+
+The HOSTATTRS list
+------------------
+
+This is a plist of lists, such that for each keyword symbol identifying a type
+of static informational attribute, there is a list of entries.  Property
+``:HOSTATTRS`` subroutines may only push new entries to the front of each such
+sublist, using the function ``PUSH-HOSTATTR``.
+
+The relationship between older and newer entries in the sublist for each type
+of static informational attribute is attribute-dependent.  For example, for
+the ``:DATA`` attribute, the order of entries does not matter and each item is
+equally a piece of prerequisite data required by the host's properties.  For
+other kinds of attribute, it might be that later entries supercede earlier
+ones, or that the entries should be combined in some way.  Property ``:APPLY``
+subroutines decide how to interpret each type of static informational
+attribute.