peerdb/tripe-newpeers.in, peerdb/peers.in.5.in: Multiple inheritance.

[tripe] / peerdb / peers.in.5.in

diff --git a/peerdb/peers.in.5.in b/peerdb/peers.in.5.in
index 240296e996ebaf405d0ed22d10b49106f04d0306..c718fb11d627430ab32ddbdd8dbb6b6edfcd5378 100644 (file)
--- a/peerdb/peers.in.5.in
+++ b/peerdb/peers.in.5.in
@@ -97,15 +97,33 @@ There is a simple concept of
 .I inheritance
 for sections.  If a section contains an assignment
 .IP
-.BI "@inherits = " parent
+.BI "@inherit = " parent
+.RB [[,]
+.I parent
+\&...]
 .PP
 then any lookups which can't be satisfied in that section will be
-satisfied instead from the
+satisfied instead from its
 .I parent
-section (and, if necessary, its parent in turn, and so on).  Note that
+sections (and, if necessary, their parents in turn, and so on).
+.PP
+.hP \*o
+If a value can be found for a key via multiple parents then all of them
+must report the
+.I same
+value.  This restriction may be relaxed somewhat, if it turns out that a
+more flexible notion of multiple inheritance is useful.
+.hP \*o
+It's not allowed for a section to inherit, possibly indirectly, from
+itself.  Currently errors of this kind are only diagnosed when a cycle
+is encountered while looking up a key and none of the sections on the
+path from the original section up to and round the cycle define a value
+for it.  Future versions of this program might be more picky.
+.PP
+Note that
 .BI $( key )
 substitutions in the resulting value will be satisfied from the original
-section (though falling back to scanning the parent section).  For
+section (though falling back to scanning parent sections).  For
 example, given the sections
 .VS
 [parent]
@@ -113,7 +131,7 @@ detail = in parent
 blurb = expand $(detail)
 .VE
 Apart from its effect on lookups, as just described, the
-.B @inherits
+.B @inherit
 key is entirely ignored.  In particular, it is never written to the
 database.
 .
@@ -237,7 +255,7 @@ Sections whose names have the form
 .BI @ whatever
 are ignored (though their contents may be relevant if the section is
 named in another section's
-.B @inherits
+.B @inherit
 key).
 .hP \*o
 Sections whose names have the form
@@ -245,7 +263,7 @@ Sections whose names have the form
 are written to local-type database records with the same name.  The keys
 and values defined in the section (and its parent section, if it
 contains an
-.B @inherits
+.B @inherit
 key) are stored in the record using
 .B form-urlencoding
 as defined in RFC1822, except that the key-value pairs are separated by
@@ -254,7 +272,7 @@ semicolons
 rather than ampersands
 .RB ` & '.
 The
-.B @inherits
+.B @inherit
 key-value pair is not written to the database.
 .hP \*o
 Other sections are written to peer-type database records, named