- formatting/markup fixes

- note that the purpose of grouping is so that we can save some work
  when figuring out where to search for referrants

1 files changed, 25 insertions, 19 deletions

diff --git a/doc/sch-getting-started.txt b/doc/sch-getting-started.txt
index ce04b68..49d25db 100644
--- a/doc/sch-getting-started.txt
+++ b/doc/sch-getting-started.txt
@@ -4,7 +4,7 @@ This module becomes useful when the information stored in a directory
 "looks" almost like a particular piece of client software expects it to
 look.
 
-Let's assume a hypothetical mailing list manager for the "example.com"
+Let's assume a hypothetical mailing list manager for the ''example.com''
 domain which expects subscription information for a mailing list to look
 like this:
 
@@ -14,7 +14,7 @@ like this:
     subscriber: dave@example.com
 
 We'll assume that some portion of the DN is not as important as the
-contents of the "cn" and "subscriber" attributes, because the mailing
+contents of the ''cn'' and ''subscriber'' attributes, because the mailing
 list manager lets us configure a base DN under which it will search for
 list information (if it doesn't afford you that much, then, well, wow).
 
@@ -66,7 +66,7 @@ The plugin expects to be used to convert data from one set of entries
 (a set found by searching the directory) into another set of entries
 which will appear in a different portion of the directory.  In our
 example, we'll make all of the plugin's data appear in a section of the
-tree contained by the entry "cn=compat,dc=example,dc=com".
+tree contained by the entry ''cn=compat,dc=example,dc=com''.
 
 At minimum, for a set of entries, we need to tell the plugin how to find
 the entries it should use as input (using a search base and a filter),
@@ -86,10 +86,10 @@ of the entry which caused the plugin to be loaded, like so:
     schema-compat-container-rdn: cn=lists
     schema-compat-entry-rdn: cn=%{cn}
 
-Suddenly, a container entry with the name "cn=compat,dc=example,dc=com"
+Suddenly, a container entry with the name ''cn=compat,dc=example,dc=com''
 appears in the directory.  Beneath it, a container entry with the name
-"cn=lists,cn=compat,dc=example,dc=com" appears, and beneath that, one
-with the name "cn=example-group,cn=lists,cn=compat,dc=example,dc=com".
+''cn=lists,cn=compat,dc=example,dc=com'' appears, and beneath that, one
+with the name ''cn=example-group,cn=lists,cn=compat,dc=example,dc=com''.
 
 The new entry for the list looks like this:
 
@@ -98,15 +98,15 @@ 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,
+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.
+of the ''cn'' attribute, but it could as easily have been anything else.
 
 == Configuring a Useful Set of Entries ==
 
 We can do more than just provide just a distinguished name, though.  By
-using the "schema-compat-entry-attribute" setting, we can add any
+using the ''schema-compat-entry-attribute'' setting, we can add any
 attribute from the source entry to the synthetic entry:
 
     dn: cn=Group Lists, cn=Schema Compatibility, cn=plugins, cn=config
@@ -120,9 +120,9 @@ attribute from the source entry to the synthetic entry:
     schema-compat-entry-rdn: cn=%{cn}
     schema-compat-entry-attribute: mail=%{cn}-list@example.com
 
-The "schema-compat-entry-attribute" value above reads each value of the
-"cn" attribute from the source entry, appends "-list@example.com", and
-sets the result as a value of the "mail" attribute in the synthetic
+The ''schema-compat-entry-attribute'' value above reads each value of the
+''cn'' attribute from the source entry, appends ''-list@example.com'', and
+sets the result as a value of the ''mail'' attribute in the synthetic
 entry.  Our synthetic example entry now looks like this:
 
     dn: cn=example-group,cn=lists,cn=compat,dc=boston,dc=redhat,dc=com
@@ -138,14 +138,14 @@ 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
+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
 referenced used like so:
 
-    %function("argument"[,...)
+    %function("argument"[,...])
 
 === Selecting Specific Values ===
 
@@ -165,14 +165,14 @@ but exactly one must be used, then the "first" function will do the job:
 The value which is used will the be the first in the plugin's sorting
 order.  This function can be particularly useful when you need to derive
 the synthesized entry's relative distinguished name (RDN) (with
-"schema-compat-entry-rdn"), but have only multi-valued attributes to
+''schema-compat-entry-rdn''), but have only multi-valued attributes to
 work with in the source entry.
 
 === References ===
 
 In cases where the source entry refers to other entries by their
 distinguished names, attributes from the referred-to entries can be used
-by using the "deref" function:
+by using the ''deref'' function:
 
     %deref(DN_ATTRIBUTE,ATTRIBUTE)
 
@@ -187,7 +187,7 @@ the source group's members can be retrieved and used like so:
 
 In cases where the source entry is referred to (by its distinguished
 name) by other entries, attributes from the referring entries can be used
-by using the "referred" function:
+by using the ''referred'' function:
 
     %referred(CONTAINER_RDN,DN_ATTRIBUTE,ATTRIBUTE)
 
@@ -196,8 +196,14 @@ the named container within the same container group.  The values of
 ATTRIBUTE in the entries which refer to the source entry with their
 DN_ATTRIBUTE attribute will be retrieved.
 
-Because multiple "schema-compat-search-base" values can be used with a
-given set of entries, this can simplify the configuration a bit.
+Because multiple ''schema-compat-search-base'' values can be specified
+for a given set of entries (for example, a set which reformats user
+information, gathering its input from multiple locations in your
+directory), retrieving information about where to search from the
+CONTAINER_RDN container in the same container group as the current set
+of entries (which might be a set of groups whose members list the group
+entry in their ''memberOf'' attributes) avoids having to duplicate this
+information.
 
 == The End Result ==