- try to cut down on the number of places that a given formatting

  function is being documented

3 files changed, 40 insertions, 88 deletions

diff --git a/doc/format-specifiers.txt b/doc/format-specifiers.txt
index 9868552..86548de 100644
--- a/doc/format-specifiers.txt
+++ b/doc/format-specifiers.txt
@@ -40,9 +40,11 @@ directory.
 
 === Functions ===
 
-Additionally, several 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:
+Additionally, several built-in "function"s are available.  These can be
+used to modify data that's been read from the current entry before it's
+incorporated into the result, or for importing values from other entries
+and combining them with data from the current entry.  Generally,
+function invocations look like this:
 
   %function(ARG[,...])
 
diff --git a/doc/nis-getting-started.txt b/doc/nis-getting-started.txt
index 9c35a2f..e150beb 100644
--- a/doc/nis-getting-started.txt
+++ b/doc/nis-getting-started.txt
@@ -176,9 +176,9 @@ setting a "nis-disallowed-chars" value in the map's configuration entry.
     nis-value-format: %{uid}:%{userPassword-:*}:%{uidNumber}:%{gidNumber}:%{gecos:-%{cn:-Some Unnamed User}}:%{homeDirectory}:%{loginShell:-/bin/bash}
     nis-disallowed-chars: :
 
-== Functions ==
+Format specifiers are described in more detail in "format-specifiers.txt".
 
-=== Matching ===
+== Functions ==
 
 We have another problem: the user has multiple values for the
 "userPassword" attribute.  One of them looks like a Unix-style hash:
@@ -212,81 +212,24 @@ Other matching functions are provided to perform wildcard matches
 The parameters passed to functions need to be enclosed in quotation
 marks and separated by a ",".
 
-=== Lists ===
-
-As an additional measure, attempting to reference attributes which have
-more than one value (consider multiple "uidNumber" values in a user
-entry) will also cause the entry to be rejected.
-
-In some cases, we'll want just one value, and it's not particularly
-important which one is used, so long as there is one.
-
-    %first(EXPRESSION)
-
-At other times, though, we want to use all of the values of a particular
-attribute, for example when that attribute names a member of a group.
-
-The plugin provides the "merge" function to handle this.
-
-    %merge(SEPARATOR,EXPRESSION[,...])
-
-The function simply evaluates every expression it is given, creating a
-list of every value it finds, separated by the given separator.  The
-specifier for a group entry which stores its members' names in its
-"memberUid" attribute might look like this:
-
-    %{cn}:%{userPassword}:%{gidNumber}:%merge(",","%{memberUid}")
-
-=== References ===
-
-Sometimes it's not enough to read an attribute from the entry which is
-being examined.  Sometimes the entry contains the distinguished name of
-another entry, and it's that entry which actually holds the data we
-seek.  Take for example, this group:
-
-   dn: cn=minions,ou=Groups,dc=example,dc=com
-   objectClass: posixGroup
-   cn: minions
-   member: uid=timtom,ou=People,dc=example,dc=com
-   member: uid=kevin,ou=People,dc=example,dc=com
+Now our configuration entry will correctly serve any {CRYPT}-style
+passwords which are present in entries.
 
-The "deref" function is provided to handle this case.  Given two
-attribute names, it will search out entries whose names are stored in
-that attribute in the current entry, and will read the contents of the
-second attribute from those entries.  It will typically be used in
-combination with the "merge" function.
-
-   %merge(",","%deref(\"member\",\"uid\")")
-
-Now, the plugin will read the "member" attribute from the group entry,
-visit the entries it names, read the "uid" attribute from those entries,
-and build a list from the values.
-
-=== Backward References ===
-
-Keeping track of group memberships by storing the names of groups of
-which the user is a member in the user's entry is also common.  For
-example:
-
-   dn: uid=timtom,ou=People,dc=example,dc=com
-   objectClass: posixAccount
-   uid: timtom
-   uidNumber: 1000
-   gidNumber: 1000
-   cn: Tim Tom
-   homeDirectory: /home/timtom
-   loginShell: /bin/sh
-   memberOf: cn=minions,ou=Groups,dc=example,dc=com
-   memberOf: cn=moppets,ou=Groups,dc=example,dc=com
-
-The "referred" function is provided to handle this case.  Given the name
-of another map in the same domain, and two attribute names, it will
-search out entries which are part of the other map which contain this
-entry's distinguished name as a value for the first attribute, and will
-read the contents of the second attribute from those entries.  It will
-typically be used in combination with the "merge" function.
+    dn: nis-domain=example.com+nis-map=users,cn=NIS Server,cn=plugins,cn=config
+    objectclass: extensibleObject
+    nis-domain: example.com
+    nis-map: users
+    nis-base: ou=People, dc=example, dc=com
+    nis-filter: (objectClass=posixAccount)
+    nis-key-format: %{uid}
+    nis-value-format: %{uid}:%regsub("%{userPassword}","^\{CRYPT\}(..*)","%1","*"):%{uidNumber}:%{gidNumber}:%{gecos:-%{cn:-Some Unnamed User},,,}:%{homeDirectory}:%{loginShell:-/bin/bash}
+    nis-disallowed-chars: :,
 
-   %merge(",","%referred(\"passwd.byname\",\"memberOf\",\"uid\")")
+The module provides more function-like operators than just %regsub(),
+but most of those aren't useful when examining user entries.  They turn
+out to be more useful when examining entries which represent other types
+of information, particularly groups.  They, too, are described in the
+"format-specifiers.txt" documentation.
 
 == Defaults ==
 
@@ -311,4 +254,6 @@ from the configuration:
 
 The above configuration sets up both the "passwd.byname" and
 "passwd.byuid" maps using the default key and value specifiers, which
-should work correctly for most cases.
+should work correctly for most cases.  Likewise, the module has compiled
+into it suitable defaults for a number of common NIS maps.  The full
+list is stored in "nis-known-maps.txt".
diff --git a/doc/sch-getting-started.txt b/doc/sch-getting-started.txt
index 49d25db..15d9ff6 100644
--- a/doc/sch-getting-started.txt
+++ b/doc/sch-getting-started.txt
@@ -98,10 +98,11 @@ The new entry for the list looks like this:
     objectClass: extensibleObject
     objectClass: top
 
-The ''schema-compat-entry-rdn'' attribute allows an expression to be used,
-to allow the value it takes in a new entry to vary based on the contents
-of the corresponding source entry.  In this example, we copied the value
-of the ''cn'' attribute, but it could as easily have been anything else.
+The ''schema-compat-entry-rdn'' attribute allows a format specifier to
+be used, to allow the value it takes in a new entry to vary based on the
+contents of the corresponding source entry.  In this example, we copied
+the value of the ''cn'' attribute, but it could as easily have been
+anything else.
 
 == Configuring a Useful Set of Entries ==
 
@@ -138,11 +139,11 @@ shell syntax, to allow default and alternate values to be used.
 
 == Functions ==
 
-The syntax for ''schema-compat-entry-attribute'' we've seen so far lets us
-create synthetic attributes with data from the source entry, and even
-rename attributes, but we can do more than that.  The expression used to
-build the value used can also include a number of function-like
-expressions which are evaluated by the plugin.  A function's result is
+The syntax for ''schema-compat-entry-attribute'' we've seen so far lets
+us create synthetic attributes with data from the source entry, and even
+rename attributes, but we can do more than that.  The format specifier
+used to build the value used can also include a number of function-like
+operators which are evaluated by the plugin.  A function's result is
 referenced used like so:
 
     %function("argument"[,...])
@@ -234,3 +235,7 @@ The resulting synthetic entry looks like this:
 
 Now, if we point our finicky mailing list manager at this section of the
 directory tree, it will like what it sees.
+
+The module also provides several other function-like operators which
+were not used in any of these examples.  They are described in the
+"format-specifiers.txt" file.