- split out docs on format specifiers, since it's shared anyway

3 files changed, 251 insertions, 435 deletions

diff --git a/doc/format-specifiers.txt b/doc/format-specifiers.txt
new file mode 100644
index 0000000..b6be91d
--- /dev/null
+++ b/doc/format-specifiers.txt
@@ -0,0 +1,218 @@
+=== Functions In Function Specifiers ===
+
+Format specifiers can reference values of attributes in the entry which
+is currently being examined like so:
+  %{attribute}
+
+More built-in "function"s are available for importing values from other
+entries and combining them with data from the current entry.  Generally,
+function invocations look like this:
+  %function(ARG1[,...])
+
+A function-like invocation expects a comma-separated list of
+double-quoted arguments.  Any arguments which themselves contain a
+double-quote need to escape the double-quote using a '\' character.
+Naturally the '\' this character itself also needs to be escaped
+whenever it appears.  Some functions can take expressions as arguments,
+allowing functions to operate on data after it has been acted on by
+other functions.
+
+=== Implemented Functions ===
+  * first(EXPRESSION[,DEFAULT])
+    - Evaluates EXPRESSION, and if one or more values is available,
+      provides the first value.  If no values result, then DEFAULT is
+      evaluated as an expression and the result is provided.
+
+  * match(EXPRESSION,PATTERN[,DEFAULT])
+    - Selects the value of EXPRESSION which matches the globbing pattern
+      PATTERN.  If no values match, and a DEFAULT was specified, the
+      DEFAULT is produced, otherwise an error occurs.
+    - Example (examining "cn=group"):
+        dn: cn=group
+	member: bob
+	member: dave
+      %match("%{member}","b*")       -> bob
+      %match("%{member}","d*")       -> dave
+      %match("%{member}","e*")        FAILS
+      %match("%{member}","e*","jim") -> jim
+      %match("%{member}","*","jim")  -> jim (when a single value is required)
+      %match("%{member}","*","jim")  -> bob,dave (when a list is acceptable)
+  * regmatch(EXPRESSION,PATTERN[,DEFAULT])
+    - Selects the value of EXPRESSION which matches the extended regular
+      expression PATTERN.  If no values match, and a DEFAULT was
+      specified, the DEFAULT is produced.
+    - Example (examining "cn=group"):
+        dn: cn=group
+	member: bob
+	member: dave
+      %regmatch("%{member}","^b.*")       -> bob
+      %regmatch("%{member}","^d.*")       -> dave
+      %regmatch("%{member}","e")          -> dave
+      %regmatch("%{member}","^e")          FAILS
+      %regmatch("%{member}","^e.*","jim") -> jim
+      %regmatch("%{member}",".*","jim")   -> jim (when a single value is required)
+      %regmatch("%{member}",".*","jim")   -> bob,dave (when a list is acceptable)
+  * regsub(EXPRESSION,PATTERN,TEMPLATE[,DEFAULT])
+    - Selects the value of EXPRESSION which matches the extended regular
+      expression PATTERN and uses TEMPLATE to construct the output.  If
+      no values match, and a DEFAULT was specified, the DEFAULT is
+      produced, otherwise an error occurs.  The template is used to
+      construct a result using the n'th substring from the matched value
+      by using the sequence "%n" in the template.
+    - Example (examining "cn=group"):
+        dn: cn=group
+	member: bob
+	member: dave
+      %regsub("%{member}","o","%0")          -> bob
+      %regsub("%{member}","o","%1")          -> 
+      %regsub("%{member}","^o","%0")         FAILS
+      %regsub("%{member}","^d(.).*","%1")    -> a
+      %regsub("%{member}","^(.*)e","t%1y")   -> tdavy
+      %regsub("%{member}","^e","%1")         FAILS
+      %regsub("%{member}","^e.*","%1","jim") -> jim
+  * deref(THISATTRIBUTE,THATATTRIBUTE)
+    - Creates a separated list of the values of THATATTRIBUTE for
+      directory entries named by this entry's THISATTRIBUTE.
+    - Example (examining "cn=group"):
+        dn: cn=group
+	member: uid=bob
+	member: uid=pete
+        -
+	dn: uid=bob
+	uid: bob
+        -
+	dn: uid=pete
+	uid: pete
+      %deref("member","foo") -> FAIL     (when a single value is required)
+      %deref("member","foo") ->          (when a list is acceptable)
+      %deref("member","uid") -> FAIL     (when a single value is required)
+      %deref("member","uid") -> bob,pete (when a list is acceptable)
+  * deref_r(ATTRIBUTE[,OTHERATTRIBUTE[...]],VALUEATTRIBUTE)
+    - Looks for entries named by this entry's ATTRIBUTE, and then by
+      those entries' ATTRIBUTE, repeating the search no more entries to
+      find named by ATTRIBUTE.  Then searches for entries named by that
+      set's OTHERATTRIBUTE, similarly repeating until a complete set of
+      entries is obtained, repeating the process for listed attribute
+      except the last.  The VALUEATTRIBUTE of every entry examined along
+      the way will be returned.
+    - Example (examining "cn=group"):
+        dn: cn=group
+	member: cn=othergroup
+	member: uid=bob
+        -
+        dn: cn=othergroup
+	member: uid=pete
+	uid: bogus
+        -
+	dn: uid=bob
+	uid: bob
+        -
+	dn: uid=pete
+	uid: pete
+      %deref_r("member","foo") -> FAIL     (when a single value is required)
+      %deref_r("member","foo") ->          (when a list is acceptable)
+      %deref_r("member","uid") -> FAIL     (when a single value is required)
+      %deref_r("member","uid") -> bogus,bob,pete (when a list is acceptable)
+  * referred(SET,THATATTRIBUTE,THATOTHERATTRIBUTE)
+    - Creates a separated list of the values of THATOTHERATTRIBUTE for
+      directory entries which have entries in the current group in the
+      named SET and which also have this entry's name as a value for
+      THATATTRIBUTE.  Will fail if used in a context where a single
+      value is required.
+    - Example (examining "cn=group"):
+        dn: cn=group
+        -
+	dn: uid=bob
+	uid: bob
+	memberOf: cn=group
+        -
+	dn: uid=pete
+	uid: pete
+	memberOf: cn=group
+      %referred("cn=users","memberof","foo") -> FAIL  (when a single value is required)
+      %referred("cn=users","memberof","foo") ->       (when a list is acceptable)
+      %referred("cn=users","memberof","uid") -> FAIL  (when a single value is required)
+      %referred("cn=users","memberof","uid") -> bob,pete (when a list is acceptable)
+  * referred_r(MAP,ATTRIBUTE[,OTHERMAP,OTHERATTRIBUTE[,...],VALUEATTRIBUTE)
+    - Searches for entries in the current domain in both the current map
+      and MAP which refer to this entry using ATTRIBUTE, searching for
+      entries in the current map and MAP for the resulting entries,
+      until a complete set is formed.  Then searches for entries in MAP
+      and OTHERMAP which refer to entries in this set, repeating the
+      process until a new set is formed.  The value of VALUEATTRIBUTE
+      for every entry encountered will be returned.  Will fail if used
+      in a context where a single value is required.
+    - Example (examining "cn=group"):
+        dn: cn=group
+        -
+        dn: cn=othergroup
+	memberOf: cn=group
+	-
+	dn: uid=bob
+	uid: bob
+	memberOf: cn=group
+        -
+	dn: uid=pete
+	uid: pete
+	memberOf: cn=othergroup
+      %referred("people","memberof","foo") -> FAIL  (when a single value is required)
+      %referred("people","memberof","foo") ->       (when a list is acceptable)
+      %referred("people","memberof","uid") -> FAIL  (when a single value is required)
+      %referred("people","memberof","uid") -> bob,pete (when a list is acceptable)
+  * merge(SEPARATOR,EXPRESSION[,...])
+    - Evaluates and then creates a single value using multiple expressions
+      which can evaluate to either single values or lists.
+    - Example (examining "cn=group"):
+        dn: cn=group
+	membername: jim
+	member: uid=bob
+	member: uid=pete
+        -
+	dn: uid=bob
+	uid: bob
+        -
+	dn: uid=pete
+	uid: pete
+      %merge(",","%{membername}","%deref(\"member\",\"uid\")") -> jim,bob,pete
+  * collect(EXPRESSION[,...])
+    - Evaluates each EXPRESSION in turn, creating a single list using all of
+      the values which are produced by evaluating every expression.
+    - Example (examining "cn=group"):
+        dn: cn=group
+	cn: group
+	membername: jim
+	member: uid=bob
+	member: uid=pete
+      %collect("%{member}","%{membername}") -> ["uid=bob","uid=pete","jim"] (when a list is acceptable)
+      %collect("%{member}","%{membername}") -> FAIL (when a list is not acceptable)
+  * link(EXPRESSION,PAD[,SEPARATOR,EXPRESSION,PAD[,...])
+    - Evaluates each EXPRESSION in turn, padding each list of values using the
+      corresponding PAD value until they are all the same length, and then
+      producing a value using the first values from each list (separated by
+      the corresponding SEPARATOR), then using the second values from each
+      list, continuing until all lists have been exhausted.
+    - Example (examining "cn=group"):
+        dn: cn=group
+	cn: group
+	membername: jim
+	member: uid=bob
+	member: uid=pete
+      %link("%{member}","?","/","%{membername}","?") -> ["uid=bob/jim","uid=pete/?"] (when a list is acceptable)
+      %link("%{member}","-","/","%{membername}","") -> FAIL (when a list is not acceptable)
+
+  * ifeq(ATTRIBUTE,VALUE,MATCH,NOMATCH)
+    - Evaluates VALUE and compares it to the entry's values for ATTRIBUTE.
+      If there is at least one value which is considered equal according to
+      the matching rules for ATTRIBUTE, evaluate and return MATCH, otherwise
+      evaluate and return NOMATCH.  If VALUE can not be evaluated, fails to
+      evaluate.  If MATCH or NOMATCH (whichever is appropriate) can not be
+      evaluated, fails to evaluate.
+    - Example (examining "cn=group"):
+        dn: cn=group
+	cn: group
+	membername: jim
+	member: uid=bob
+	member: uid=pete
+      %ifeq("membername","jim","yes","no") -> yes
+      %ifeq("membername","jeff","yes","no") -> no
+      %ifeq("madeup","jeff","yes","no") -> no
diff --git a/doc/nis-design.txt b/doc/nis-design.txt
index d0d9c30..fd894a4 100644
--- a/doc/nis-design.txt
+++ b/doc/nis-design.txt
@@ -260,21 +260,16 @@ one notable exception being that patterns for the "/" operator can not
 currently be anchored to the beginning or end of the string).
 
 A format specifier can actually be interpreted in two ways: it can be
-interpreted as a single value, or it can be interpreted as providing a
-list of values.  When the format specifier is being interpreted as a
-single value, any reference to an attribute value which does not also
-specify an alternate value will cause the directory server entry to be
-ignored if the referenced attribute has no value defined for that entry,
-or contains multiple values.  In the above example, the entry would be
-ignored if the "uid", "uidNumber", "gidNumber", or "homeDirectory"
-attributes of the entry did not each contain exactly one value.
-
-The syntax further defines "functions" which can be used to concatenate
-lists of multiple values into a single result, for example for groups:
-  %{cn}:%{userPassword:-*}:%{gidNumber}:%merge(",","%{memberUid}")
-This filter takes advantage of a built-in "merge" function, which
-processes zero or more single or list values and concatenates them
-together with a "," separator, to generate the list of group members.
+interpreted as a single value (when given as "nis-key-format" or
+"nis-value-format"), or it can be interpreted as providing a list of
+values ("nis-keys-format" or "nis-values-format").  When the format
+specifier is being interpreted as a single value, any reference to an
+attribute value which does not also specify an alternate value will
+cause the directory server entry to be ignored if the referenced
+attribute has no value defined for that entry, or contains multiple
+values.  In the above example, the entry would be ignored if the "uid",
+"uidNumber", "gidNumber", or "homeDirectory" attributes of the entry did
+not each contain exactly one value.
 
 The "nis-filter", "nis-key-format", and "nis-value-format" settings have
 sensible defaults for the maps which we expect to be commonly used --
@@ -283,207 +278,12 @@ specifiers which could trigger undefined behavior on clients -- for
 example by leaving the user's numeric UID empty in a passwd entry, which
 may be treated as "0" by inattentive clients.
 
-A function-like invocation expects a comma-separated list of
-double-quoted arguments.  Any arguments which contain a double-quote
-need to escape the double-quote using a '\' character.  Naturally the
-'\' this character itself also needs to be escaped whenever it appears.
-
-=== Implemented Functions ===
-  * first(EXPRESSION[,DEFAULT])
-    - Evaluates EXPRESSION, and if one or more values is available,
-      provides the first value.  If no values result, then DEFAULT is
-      evaluated as an expression and the result is provided.
-  * match(EXPRESSION,PATTERN[,DEFAULT])
-    - Selects the value of EXPRESSION which matches the globbing pattern
-      PATTERN.  If zero or two or more values match, and a DEFAULT was
-      specified, the DEFAULT is produced, otherwise an error occurs.
-    - Example (examining "cn=group"):
-        dn: cn=group
-	member: bob
-	member: dave
-      %match("%{member}","b*")       -> bob
-      %match("%{member}","d*")       -> dave
-      %match("%{member}","e*")        FAILS
-      %match("%{member}","e*","jim") -> jim
-      %match("%{member}","*","jim")  -> jim (when a single value is required)
-      %match("%{member}","*","jim")  -> bob,dave (when a list is acceptable)
-  * regmatch(EXPRESSION,PATTERN[,DEFAULT])
-    - Selects the value of EXPRESSION which matches the extended regular
-      expression PATTERN.  If zero or two or more values match, and a
-      DEFAULT was specified, the DEFAULT is produced, otherwise an error
-      occurs.
-    - Example (examining "cn=group"):
-        dn: cn=group
-	member: bob
-	member: dave
-      %regmatch("%{member}","^b.*")       -> bob
-      %regmatch("%{member}","^d.*")       -> dave
-      %regmatch("%{member}","e")          -> dave
-      %regmatch("%{member}","^e")          FAILS
-      %regmatch("%{member}","^e.*","jim") -> jim
-      %regmatch("%{member}",".*","jim")   -> jim (when a single value is required)
-      %regmatch("%{member}",".*","jim")   -> bob,dave (when a list is acceptable)
-  * regsub(EXPRESSION,PATTERN,TEMPLATE[,DEFAULT])
-    - Selects the value of EXPRESSION which matches the extended regular
-      expression PATTERN and uses TEMPLATE to construct the output.  If
-      zero or two or more values match, and a DEFAULT was specified, the
-      DEFAULT is produced, otherwise an error occurs.  The template is
-      used to construct a result using the n'th substring from the
-      matched value by using the sequence "%n" in the template.
-    - Example (examining "cn=group"):
-        dn: cn=group
-	member: bob
-	member: dave
-      %regsub("%{member}","o","%0")          -> bob
-      %regsub("%{member}","o","%1")          -> 
-      %regsub("%{member}","^o","%0")         FAILS
-      %regsub("%{member}","^d(.).*","%1")    -> a
-      %regsub("%{member}","^(.*)e","t%1y")   -> tdavy
-      %regsub("%{member}","^e","%1")         FAILS
-      %regsub("%{member}","^e.*","%1","jim") -> jim
-  * deref(THISATTRIBUTE,THATATTRIBUTE)
-    - Creates a separated list of the values of THATATTRIBUTE for
-      directory entries named by this entry's THISATTRIBUTE.  Will fail
-      if used in a context where a single value is required.
-    - Example (examining "cn=group"):
-        dn: cn=group
-	member: uid=bob
-	member: uid=pete
-        -
-	dn: uid=bob
-	uid: bob
-        -
-	dn: uid=pete
-	uid: pete
-      %deref("member","foo") -> FAIL     (when a single value is required)
-      %deref("member","foo") ->          (when a list is acceptable)
-      %deref("member","uid") -> FAIL     (when a single value is required)
-      %deref("member","uid") -> bob,pete (when a list is acceptable)
-  * deref_r(ATTRIBUTE[,OTHERATTRIBUTE[...]],VALUEATTRIBUTE)
-    - Looks for entries named by this entry's ATTRIBUTE, and then by
-      those entries' ATTRIBUTE, repeating the search no more entries to
-      find named by ATTRIBUTE.  Then searches for entries named by that
-      set's OTHERATTRIBUTE, similarly repeating until a complete set of
-      entries is obtained, repeating the process for listed attribute
-      except the last.  The VALUEATTRIBUTE of every entry examined along
-      the way will be returned.
-    - Example (examining "cn=group"):
-        dn: cn=group
-	member: cn=othergroup
-	member: uid=bob
-        -
-        dn: cn=othergroup
-	member: uid=pete
-	uid: bogus
-        -
-	dn: uid=bob
-	uid: bob
-        -
-	dn: uid=pete
-	uid: pete
-      %deref_r("member","foo") -> FAIL     (when a single value is required)
-      %deref_r("member","foo") ->          (when a list is acceptable)
-      %deref_r("member","uid") -> FAIL     (when a single value is required)
-      %deref_r("member","uid") -> bogus,bob,pete (when a list is acceptable)
-  * referred(MAP,THATATTRIBUTE,THATOTHERATTRIBUTE)
-    - Creates a separated list of the values of THATOTHERATTRIBUTE for
-      directory entries which have entries in the current domain in the
-      named MAP and which also have this entry's name as a value for
-      THATATTRIBUTE.  Will fail if used in a context where a single
-      value is required.
-    - Example (examining "cn=group"):
-        dn: cn=group
-        -
-	dn: uid=bob
-	uid: bob
-	memberOf: cn=group
-        -
-	dn: uid=pete
-	uid: pete
-	memberOf: cn=group
-      %referred("people","memberof","foo") -> FAIL  (when a single value is required)
-      %referred("people","memberof","foo") ->       (when a list is acceptable)
-      %referred("people","memberof","uid") -> FAIL  (when a single value is required)
-      %referred("people","memberof","uid") -> bob,pete (when a list is acceptable)
-  * referred_r(MAP,ATTRIBUTE[,OTHERMAP,OTHERATTRIBUTE[,...],VALUEATTRIBUTE)
-    - Searches for entries in the current domain in both the current map
-      and MAP which refer to this entry using ATTRIBUTE, searching for
-      entries in the current map and MAP for the resulting entries,
-      until a complete set is formed.  Then searches for entries in MAP
-      and OTHERMAP which refer to entries in this set, repeating the
-      process until a new set is formed.  The value of VALUEATTRIBUTE
-      for every entry encountered will be returned.  Will fail if used
-      in a context where a single value is required.
-    - Example (examining "cn=group"):
-        dn: cn=group
-        -
-        dn: cn=othergroup
-	memberOf: cn=group
-	-
-	dn: uid=bob
-	uid: bob
-	memberOf: cn=group
-        -
-	dn: uid=pete
-	uid: pete
-	memberOf: cn=othergroup
-      %referred("people","memberof","foo") -> FAIL  (when a single value is required)
-      %referred("people","memberof","foo") ->       (when a list is acceptable)
-      %referred("people","memberof","uid") -> FAIL  (when a single value is required)
-      %referred("people","memberof","uid") -> bob,pete (when a list is acceptable)
-  * merge(SEPARATOR,EXPRESSION[,...])
-    - Evaluates and then creates a single value using multiple expressions
-      which can evaluate to either single values or lists.
-    - Example (examining "cn=group"):
-        dn: cn=group
-	membername: jim
-	member: uid=bob
-	member: uid=pete
-        -
-	dn: uid=bob
-	uid: bob
-        -
-	dn: uid=pete
-	uid: pete
-      %merge(",","%{membername}","%deref(\"member\",\"uid\")") -> jim,bob,pete
-  * collect(EXPRESSION[,...])
-    - Evaluates each EXPRESSION in turn, creating a single list using all of
-      the values which are produced by evaluating every expression.
-    - Example (examining "cn=group"):
-        dn: cn=group
-	cn: group
-	membername: jim
-	member: uid=bob
-	member: uid=pete
-      %collect("%{member}","%{membername}") -> ["uid=bob","uid=pete","jim"] (when a list is acceptable)
-      %collect("%{member}","%{membername}") -> FAIL (when a list is not acceptable)
-  * link(EXPRESSION,PAD[,SEPARATOR,EXPRESSION,PAD[,...])
-    - Evaluates each EXPRESSION in turn, padding each list of values using the
-      corresponding PAD value until they are all the same length, and then
-      producing a value using the first values from each list (separated by
-      the corresponding SEPARATOR), then using the second values from each
-      list, continuing until all lists have been exhausted.
-    - Example (examining "cn=group"):
-        dn: cn=group
-	cn: group
-	membername: jim
-	member: uid=bob
-	member: uid=pete
-      %link("%{member}","?","/","%{membername}","?") -> ["uid=bob/jim","uid=pete/?"] (when a list is acceptable)
-      %link("%{member}","-","/","%{membername}","") -> FAIL (when a list is not acceptable)
-  * ifeq(ATTRIBUTE,VALUE,MATCH,NOMATCH)
-    - Evaluates VALUE and compares it to the entry's values for ATTRIBUTE.
-      If there is at least one value which is considered equal according to
-      the matching rules for ATTRIBUTE, evaluate and return MATCH, otherwise
-      evaluate and return NOMATCH.  If VALUE can not be evaluated, fails to
-      evaluate.  If MATCH or NOMATCH (whichever is appropriate) can not be
-      evaluated, fails to evaluate.
-    - Example (examining "cn=group"):
-        dn: cn=group
-	cn: group
-	membername: jim
-	member: uid=bob
-	member: uid=pete
-      %ifeq("membername","jim","yes","no") -> yes
-      %ifeq("membername","jeff","yes","no") -> no
-      %ifeq("madeup","jeff","yes","no") -> no
+The format specifier syntax further defines "functions" which can be
+used to concatenate lists of multiple values into a single result, for
+example for groups:
+  %{cn}:%{userPassword:-*}:%{gidNumber}:%merge(",","%{memberUid}")
+This filter takes advantage of a built-in "merge" function, which
+processes zero or more single or list values and concatenates them
+together with a "," separator, to generate the list of the group's
+members.  The available functions are described more fully in
+"format-specifiers.txt".
diff --git a/doc/sch-design.txt b/doc/sch-design.txt
index a94ad81..8854193 100644
--- a/doc/sch-design.txt
+++ b/doc/sch-design.txt
@@ -110,219 +110,17 @@ entry's object classes) or an existing attribute, like so:
   cn=%{cn}
 
 A format specifier can actually be interpreted in two ways: it can be
-interpreted as a single value, or it can be interpreted as providing a
-list of values.  When the format specifier is being interpreted as a
-single value, any reference to an attribute value which does not also
-specify an alternate value will cause the directory server entry to be
-ignored if the referenced attribute has no value defined for that entry,
-or contains multiple values.  In the above example, the RDN is evaluated
-in such a manner.
-
-For all other attributes, if an attribute is multi-valued, the resulting
-entry will have a corresponding number of values.
-
-A pair of built-in "function"s are available for importing values from
-other entries.
-
-A function-like invocation expects a comma-separated list of
-double-quoted arguments.  Any arguments which contain a double-quote
-need to escape the double-quote using a '\' character.  Naturally the
-'\' this character itself also needs to be escaped whenever it appears.
-
-=== Implemented Functions ===
-  * first(EXPRESSION[,DEFAULT])
-    - Evaluates EXPRESSION, and if one or more values is available,
-      provides the first value.  If no values result, then DEFAULT is
-      evaluated as an expression and the result is provided.
-  * match(EXPRESSION,PATTERN[,DEFAULT])
-    - Selects the value of EXPRESSION which matches the globbing pattern
-      PATTERN.  If no values match, and a DEFAULT was specified, the
-      DEFAULT is produced, otherwise an error occurs.
-    - Example (examining "cn=group"):
-        dn: cn=group
-	member: bob
-	member: dave
-      %match("%{member}","b*")       -> bob
-      %match("%{member}","d*")       -> dave
-      %match("%{member}","e*")        FAILS
-      %match("%{member}","e*","jim") -> jim
-      %match("%{member}","*","jim")  -> jim (when a single value is required)
-      %match("%{member}","*","jim")  -> bob,dave (when a list is acceptable)
-  * regmatch(EXPRESSION,PATTERN[,DEFAULT])
-    - Selects the value of EXPRESSION which matches the extended regular
-      expression PATTERN.  If no values match, and a DEFAULT was
-      specified, the DEFAULT is produced.
-    - Example (examining "cn=group"):
-        dn: cn=group
-	member: bob
-	member: dave
-      %regmatch("%{member}","^b.*")       -> bob
-      %regmatch("%{member}","^d.*")       -> dave
-      %regmatch("%{member}","e")          -> dave
-      %regmatch("%{member}","^e")          FAILS
-      %regmatch("%{member}","^e.*","jim") -> jim
-      %regmatch("%{member}",".*","jim")   -> jim (when a single value is required)
-      %regmatch("%{member}",".*","jim")   -> bob,dave (when a list is acceptable)
-  * regsub(EXPRESSION,PATTERN,TEMPLATE[,DEFAULT])
-    - Selects the value of EXPRESSION which matches the extended regular
-      expression PATTERN and uses TEMPLATE to construct the output.  If
-      no values match, and a DEFAULT was specified, the DEFAULT is
-      produced, otherwise an error occurs.  The template is used to
-      construct a result using the n'th substring from the matched value
-      by using the sequence "%n" in the template.
-    - Example (examining "cn=group"):
-        dn: cn=group
-	member: bob
-	member: dave
-      %regsub("%{member}","o","%0")          -> bob
-      %regsub("%{member}","o","%1")          -> 
-      %regsub("%{member}","^o","%0")         FAILS
-      %regsub("%{member}","^d(.).*","%1")    -> a
-      %regsub("%{member}","^(.*)e","t%1y")   -> tdavy
-      %regsub("%{member}","^e","%1")         FAILS
-      %regsub("%{member}","^e.*","%1","jim") -> jim
-  * deref(THISATTRIBUTE,THATATTRIBUTE)
-    - Creates a separated list of the values of THATATTRIBUTE for
-      directory entries named by this entry's THISATTRIBUTE.
-    - Example (examining "cn=group"):
-        dn: cn=group
-	member: uid=bob
-	member: uid=pete
-        -
-	dn: uid=bob
-	uid: bob
-        -
-	dn: uid=pete
-	uid: pete
-      %deref("member","foo") -> FAIL     (when a single value is required)
-      %deref("member","foo") ->          (when a list is acceptable)
-      %deref("member","uid") -> FAIL     (when a single value is required)
-      %deref("member","uid") -> bob,pete (when a list is acceptable)
-  * deref_r(ATTRIBUTE[,OTHERATTRIBUTE[...]],VALUEATTRIBUTE)
-    - Looks for entries named by this entry's ATTRIBUTE, and then by
-      those entries' ATTRIBUTE, repeating the search no more entries to
-      find named by ATTRIBUTE.  Then searches for entries named by that
-      set's OTHERATTRIBUTE, similarly repeating until a complete set of
-      entries is obtained, repeating the process for listed attribute
-      except the last.  The VALUEATTRIBUTE of every entry examined along
-      the way will be returned.
-    - Example (examining "cn=group"):
-        dn: cn=group
-	member: cn=othergroup
-	member: uid=bob
-        -
-        dn: cn=othergroup
-	member: uid=pete
-	uid: bogus
-        -
-	dn: uid=bob
-	uid: bob
-        -
-	dn: uid=pete
-	uid: pete
-      %deref_r("member","foo") -> FAIL     (when a single value is required)
-      %deref_r("member","foo") ->          (when a list is acceptable)
-      %deref_r("member","uid") -> FAIL     (when a single value is required)
-      %deref_r("member","uid") -> bogus,bob,pete (when a list is acceptable)
-  * referred(SET,THATATTRIBUTE,THATOTHERATTRIBUTE)
-    - Creates a separated list of the values of THATOTHERATTRIBUTE for
-      directory entries which have entries in the current group in the
-      named SET and which also have this entry's name as a value for
-      THATATTRIBUTE.  Will fail if used in a context where a single
-      value is required.
-    - Example (examining "cn=group"):
-        dn: cn=group
-        -
-	dn: uid=bob
-	uid: bob
-	memberOf: cn=group
-        -
-	dn: uid=pete
-	uid: pete
-	memberOf: cn=group
-      %referred("cn=users","memberof","foo") -> FAIL  (when a single value is required)
-      %referred("cn=users","memberof","foo") ->       (when a list is acceptable)
-      %referred("cn=users","memberof","uid") -> FAIL  (when a single value is required)
-      %referred("cn=users","memberof","uid") -> bob,pete (when a list is acceptable)
-  * referred_r(MAP,ATTRIBUTE[,OTHERMAP,OTHERATTRIBUTE[,...],VALUEATTRIBUTE)
-    - Searches for entries in the current domain in both the current map
-      and MAP which refer to this entry using ATTRIBUTE, searching for
-      entries in the current map and MAP for the resulting entries,
-      until a complete set is formed.  Then searches for entries in MAP
-      and OTHERMAP which refer to entries in this set, repeating the
-      process until a new set is formed.  The value of VALUEATTRIBUTE
-      for every entry encountered will be returned.  Will fail if used
-      in a context where a single value is required.
-    - Example (examining "cn=group"):
-        dn: cn=group
-        -
-        dn: cn=othergroup
-	memberOf: cn=group
-	-
-	dn: uid=bob
-	uid: bob
-	memberOf: cn=group
-        -
-	dn: uid=pete
-	uid: pete
-	memberOf: cn=othergroup
-      %referred("people","memberof","foo") -> FAIL  (when a single value is required)
-      %referred("people","memberof","foo") ->       (when a list is acceptable)
-      %referred("people","memberof","uid") -> FAIL  (when a single value is required)
-      %referred("people","memberof","uid") -> bob,pete (when a list is acceptable)
-  * merge(SEPARATOR,EXPRESSION[,...])
-    - Evaluates and then creates a single value using multiple expressions
-      which can evaluate to either single values or lists.
-    - Example (examining "cn=group"):
-        dn: cn=group
-	membername: jim
-	member: uid=bob
-	member: uid=pete
-        -
-	dn: uid=bob
-	uid: bob
-        -
-	dn: uid=pete
-	uid: pete
-      %merge(",","%{membername}","%deref(\"member\",\"uid\")") -> jim,bob,pete
-  * collect(EXPRESSION[,...])
-    - Evaluates each EXPRESSION in turn, creating a single list using all of
-      the values which are produced by evaluating every expression.
-    - Example (examining "cn=group"):
-        dn: cn=group
-	cn: group
-	membername: jim
-	member: uid=bob
-	member: uid=pete
-      %collect("%{member}","%{membername}") -> ["uid=bob","uid=pete","jim"] (when a list is acceptable)
-      %collect("%{member}","%{membername}") -> FAIL (when a list is not acceptable)
-  * link(EXPRESSION,PAD[,SEPARATOR,EXPRESSION,PAD[,...])
-    - Evaluates each EXPRESSION in turn, padding each list of values using the
-      corresponding PAD value until they are all the same length, and then
-      producing a value using the first values from each list (separated by
-      the corresponding SEPARATOR), then using the second values from each
-      list, continuing until all lists have been exhausted.
-    - Example (examining "cn=group"):
-        dn: cn=group
-	cn: group
-	membername: jim
-	member: uid=bob
-	member: uid=pete
-      %link("%{member}","?","/","%{membername}","?") -> ["uid=bob/jim","uid=pete/?"] (when a list is acceptable)
-      %link("%{member}","-","/","%{membername}","") -> FAIL (when a list is not acceptable)
-  * ifeq(ATTRIBUTE,VALUE,MATCH,NOMATCH)
-    - Evaluates VALUE and compares it to the entry's values for ATTRIBUTE.
-      If there is at least one value which is considered equal according to
-      the matching rules for ATTRIBUTE, evaluate and return MATCH, otherwise
-      evaluate and return NOMATCH.  If VALUE can not be evaluated, fails to
-      evaluate.  If MATCH or NOMATCH (whichever is appropriate) can not be
-      evaluated, fails to evaluate.
-    - Example (examining "cn=group"):
-        dn: cn=group
-	cn: group
-	membername: jim
-	member: uid=bob
-	member: uid=pete
-      %ifeq("membername","jim","yes","no") -> yes
-      %ifeq("membername","jeff","yes","no") -> no
-      %ifeq("madeup","jeff","yes","no") -> no
+interpreted as a single value (as it is for "schema-compat-entry-rdn"
+values), or it can be interpreted as providing a list of values (as it
+is for "schema-compat-entry-attribute" values).  When the format
+specifier is being interpreted as a single value, any reference to an
+attribute value which does not also specify an alternate value will
+cause the directory server entry to be ignored if the referenced
+attribute has no value defined for that entry, or contains multiple
+values.
+
+The format specifier syntax further defines "functions" which can be
+used to manipulate values for attributes in the entry being examined,
+follow references to other entries and retrieve values from them, and to
+manipulate those values into whatever format is required.  The available
+functions are described more fully in "format-specifiers.txt".