ITS#708: Admin Guide -- more editing

  More spelling, grammar, and stylistic fixups.
Submitted by Cedric Tefft <cedric@earthling.net>

doc/guide/admin/dbtools.sdf

@@ -28,14 +28,14 @@ H2: Creating a database over LDAP
 With this method, you use the LDAP client of your choice
 (e.g., the ldapadd(1)) to add entries, just like you would
 once the database is created. You should be sure to set the
-following configuration options before starting slapd:
+following options in the configuration file before starting slapd:
 
 >	suffix <dn>
 
-As described in the preceding section, this option says what
-entries are to be held by this database. You should set this
-to the DN of the root of the subtree you are trying to create.
-For example
+As described in the {{SECT:General Database Directives}} section,
+this option defines which entries are to be held by this database.
+You should set this to the DN of the root of the subtree you
+are trying to create.  For example:
 
 >	suffix "dc=example, dc=com"
 
@@ -51,8 +51,8 @@ For example:
 You need to create this directory with appropriate permissions
 such that slapd can write to it.
 
-You need to make it so you can connect to slapd as directory user
-with permission to add entries. You can configure the directory
+You need to configure slapd so that you can connect to it as a directory
+user with permission to add entries. You can configure the directory
 to support a special {{super-user}} or {{root}} user just for
 this purpose. This is done through the following two options
 in the database definition:
@@ -79,7 +79,7 @@ contains the index definitions you want:
 >	index {<attrlist> | default} [pres,eq,approx,sub,none]
 
 For example, to index the cn, sn, uid and objectclass
-attributes the following index configuration lines could be
+attributes, the following index configuration lines could be
 used.
 
 >	index cn,sn,uid
@@ -119,7 +119,7 @@ H2: Creating a database off-line
 The second method of database creation is to do it off-line,
 using the slapd database tools described below. This method is
 best if you have many thousands of entries to create, which
-would take an unacceptably long time using
+would take an unacceptably long time to add using
 the LDAP method described above. These tools read the
 slapd configuration file and an input file containing a text
 representation of the entries to add. For database types which
@@ -130,10 +130,10 @@ file database definition first:
 
 >	suffix <dn>
 
-As described in the preceding section, this option says what
-entries are to be held by this database. You should set this
-to the DN of the root of the subtree you are trying to create.
-For example
+As described in the {{SECT:General Database Directives}} section,
+this option defines which entries are to be held by this database.
+You should set this to the DN of the root of the subtree you are
+trying to create.  For example:
 
 >	suffix "dc=example, dc=com"
 
@@ -191,18 +191,18 @@ the {{SECT:Command-Line Options}} section in {{SECT:Running slapd}}.
 
 > 	-n <databasenumber>
 
-An optional argument that specifies the configuration file
-database for which to build. The first database listed
+An optional argument that specifies which database to modify.
+The first database listed in the configuration file
 is "1", the second "2", etc. By default, the first ldbm database
 in the configuration file is used. Should not be used in
 conjunction with {{EX:-b}}.
 
 >	-b <suffix>
 
-An optional argument that specifies the configuration file
-database for which to build. The provided suffix is matched
-against database {{EX:suffix}} to determine the database
-number. Should not be used in conjunction with {{EX:-n}}.
+An optional argument that specifies which database to modify.
+The provided suffix is matched against a database {{EX:suffix}}
+directive to determine the database number. Should not be
+used in conjunction with {{EX:-n}}.
 
 
 H3: The {{EX:slapindex}} program
@@ -222,9 +222,9 @@ upon the current database contents.
 
 H3: The {{EX:slapcat}} program
 
-The {{EX:slapcat}} program is used to dump the database to a {{TERM:LDIF}}
+The {{EX:slapcat}} program is used to dump the database to an {{TERM:LDIF}}
 file. This can be useful when you want to make a human-readable
-backup of your database or for editing your database off-line.
+backup of your database or when you want to edit your database off-line.
 The program is invoked like this:
 
 >	slapcat -l <filename> -f <slapdconfigfile>
@@ -242,7 +242,7 @@ The {{ldif}}(1) program is used to convert arbitrary data values to
 {{TERM:LDIF}} format. This can be useful when writing a program or
 script to create the LDIF file you will feed into the {{slapadd}}(8)
 or {{ldapadd}}(1) program, or when writing a SHELL backend. {{ldif}}(1)
-takes an attribute descriptin as an argument and reads the attribute
+takes an attribute description as an argument and reads the attribute
 value(s) from standard input. It produces the LDIF formatted
 attribute line(s) on standard output. The usage is:
 
@@ -257,7 +257,7 @@ value of the attribute.
 >	# leading hash mark
 >	EOF
 
-The -b option can be used to force ldif to interpret its input
+The {{EX:-b}} option can be used to force ldif to interpret its input
 as a single raw binary value. This option is useful when
 converting binary data such as a {{EX:jpegPhoto}} or {{EX:audio}}
 attribute.  For example:
@@ -282,7 +282,7 @@ The basic form of an entry is:
 >
 > 	...
 
-Lines starting with '{{EX:#}}' character are
+Lines starting with a '{{EX:#}}' character are
 comments.  An attribute description may be a simple attribute
 type like {{EX:cn}} or {{EX:objectClass}} or {{EX:1.2.3}} (an {{TERM:OID}}
 associated with an attribute type) or may include options such

doc/guide/admin/referrals.sdf

@@ -6,7 +6,7 @@ H1: Constructing a Distributed Directory Service
 
 For many sites, running one or more {{slapd}}(8) that hold an
 entire subtree of data is sufficient. But often it is desirable
-to have one {{slapd}}} refer to other directory services for a
+to have one {{slapd}} refer to other directory services for a
 certain part of the tree (which may or may not be running {{slapd}}).
 
 !if 0
@@ -28,7 +28,7 @@ together.
 This mechanism allows for hierarchical directory services to to be
 constructed.
 
-A referral object has an structural object class of
+A referral object has a structural object class of
 {{EX:referral}} and has the same {{TERM[expand]DN}} as the
 delegated subtree.  Generally, the referral object will also
 provide the auxiliary object class {{EX:extensibleObject}}.
@@ -106,7 +106,7 @@ is similar to an X.500 knowledge reference held in a
 
 H2: The ManageDsaIT Control
 
-Adding, modify, and deleting referral objects is generally done
+Adding, modifying, and deleting referral objects is generally done
 using {{ldapmodify}}(1) or similar tools which support the
 ManageDsaIT control.  The ManageDsaIT control informs the server
 that you intend to manage the referral object as a regular

doc/guide/admin/replication.sdf

@@ -6,8 +6,8 @@ H1: Replication with slurpd
 In certain configurations, a single {{slapd}}(8) instance may be
 insufficient to handle the number of clients requiring
 directory service via LDAP. It may become necessary to
-run more than one slapd instance.  Many sites,
-for instance, there are multiple slapd servers, one
+run more than one slapd instance.  At many sites,
+for instance, there are multiple slapd servers: one
 master and one or more slaves.  {{TERM:DNS}} can be setup such that
 a lookup of {{EX:ldap.example.com}} returns the {{TERM:IP}} addresses
 of these servers, distributing the load among them (or
@@ -193,7 +193,7 @@ inappropriate.
 
 + Do not include a {{EX:replogfile}} directive.
 
-+ Do include an updatedn line. The DN given should
++ Do include an {{EX:updatedn}} line. The DN given should
 match the DN given in the {{EX:binddn=}} parameter of the
 corresponding {{EX:replica=}} directive in the master slapd
 config file.
@@ -237,8 +237,8 @@ Suffix		Database
 {{EX:gdbm}}	GNU DBM backend
 !endblock
 
-In general, you should copy all files found in the database
-{{EX: directory}} unless you know it not used by {{slapd}}(8).
+In general, you should copy each file found in the database
+{{EX: directory}} unless you know it is not used by {{slapd}}(8).
 
 Note: The copy process assumes homogeneous servers with
 identically configured OpenLDAP installations.
@@ -261,7 +261,7 @@ standard LDAP port) on host slave.example.com. The slurpd
 process will bind to the slave slapd as 
 "{{EX:cn=Replicator,dc=example,dc=com}}" using simple authentication
 with password "{{EX:secret}}".  Note that the DN given by the {{EX:binddn=}}
-directive must either exist in the slave slapd's database (or be
+directive must exist in the slave slapd's database (or be
 the rootdn specified in the slapd config file) in order for the
 bind operation to succeed.  The DN should also be listed as
 the {{EX:updatedn}} for the database in the slave's slapd.conf(5).
@@ -296,7 +296,7 @@ H3: Replication errors
 When slurpd propagates a change to a slave slapd and
 receives an error return code, it writes the reason for the
 error and the replication record to a reject file. The reject
-file is located in the same directory with the per-replica
+file is located in the same directory as the per-replica
 replication logfile, and has the same name, but with the
 string "{{F:.rej}}" appended. For example, for a replica running
 on host {{EX:slave.example.com}}, port 389, the reject file, if it

doc/guide/admin/schema.sdf

@@ -5,7 +5,7 @@
 H1: Schema Specification
 
 This chapter describes how to extend the schema used by {{slapd}}(8).
-The first section, {{SECT:Distribution Schema Files}} details optional
+The first section, {{SECT:Distributed Schema Files}} details optional
 schema definitions provided in the distribution and where to obtain
 other definitions.
 The second section, {{SECT:Extending Schema}}, details how to define
@@ -56,7 +56,7 @@ H2: Extending Schema
 Schema used by {{slapd}}(8) may be extended to support additional
 syntaxes, matching rules, attribute types, and object classes.
 This chapter details how to add attribute types and object classes
-using the syntaxes and matching rules already support by slapd.
+using the syntaxes and matching rules already supported by slapd.
 slapd can also be extended to support additional syntaxes
 and matching rules, but this requires some programming and hence
 is not discussed here.
@@ -74,7 +74,7 @@ Each schema element is identified by a globally unique
 {{TERM[expand]OID}} (OID).  OIDs are also used to identify
 other objects.
 They are commonly found in protocols described by {{TERM:ASN.1}}.  In
-particular, they are heavy used by {{TERM[expand]SNMP}} (SNMP).
+particular, they are heavily used by the {{TERM[expand]SNMP}} (SNMP).
 As OIDs are hierarchical, your organization
 can obtain one OID and branch it as needed.  For example,
 if your organization were assigned OID {{EX:1.1}}, you could branch
@@ -105,7 +105,7 @@ service) see {{URL:http://www.alvestrand.no/harald/objectid/}}.
 .{{Under no circumstances should you use a fictious OID!}} 
 
 To obtain a fully registered OID at {{no cost}}, apply for
-a OID under {{ORG[expand]IANA}} (IANA) maintained
+an OID under {{ORG[expand]IANA}} (IANA) maintained
 {{Private Enterprise}} arch.  Any private enterprise (organization)
 may request an OID to be assigned under this arch.  Just fill
 out the {{ORG:IANA}} form at {{URL: http://www.iana.org/cgi-bin/enterprise.pl}}
@@ -120,7 +120,7 @@ identifying LDAP schema elements.
 
 H3: Name Prefix
 
-In addition to assign a unique object identifier to each schema
+In addition to assigning a unique object identifier to each schema
 element, you should provide a least one textual name for each
 element.  The name should be both descriptive and not likely
 to clash with names of other schema elements.  In particular,
@@ -197,7 +197,7 @@ where Attribute Type Description is defined by the following
 
 where whsp is a space ('{{EX: }}'), numericoid is a globally unique
 OID in numeric form (e.g. {{EX:1.2.3}}), qdescrs is one or more
-names, woid is either the name or OID, and noidlen is a optional length
+names, woid is either the name or OID, and noidlen is an optional length
 specifier (e.g {{EX:{10}}}).
 
 For example, the attribute types {{EX:name}} and {{EX:cn}} are defined
@@ -214,9 +214,9 @@ Notice that each defines the attribute's OID and descriptive
 names.  Each name is an alias for the OID.  {{slapd}}(8) returns
 the first listed name when returning results.
 
-The first attribute, {{EX:name}}, has a syntax of directory string
+The first attribute, {{EX:name}}, has a syntax of {{EX:directoryString}}
 (a UTF-8 encoded Unicode string) with a recommend maximun length.
-Note that syntaxes is specified by OID.  In addition, the equality
+Note that syntaxes are specified by OID.  In addition, the equality
 and substring matching uses case ignore rules.  Below are tables 
 listing commonly used supported syntax and matching rules.
 
@@ -263,10 +263,10 @@ caseExactSubstringsIA5Match	substrings	case sensitive, space insensitive
 !endblock
 
 The second attribute, {{EX:cn}}, is a subtype of {{EX:name}} hence
-in inherits the syntax, matching rules, and usage of {{EX:name}}.
+it inherits the syntax, matching rules, and usage of {{EX:name}}.
 {{EX:commonName}} is an alternative name.
 
-Neither attributes is restricted to a single value and both are
+Neither attribute is restricted to a single value and both are
 meant for usage by user applications.  You likely won't need to
 specify other parameters such as {{EX:OBSOLETE}}.
 
@@ -276,8 +276,8 @@ The following subsections provide a couple of examples.
 H4: myUniqueName
 
 Many organizations maintain a single unique name for each user.
-Though one could use {{EX:displayName}} ({{REF:RFC2798}}), but this
-attribute is meant to be controlled by the user, not the
+Though one could use {{EX:displayName}} ({{REF:RFC2798}}), this
+attribute is really meant to be controlled by the user, not the
 organization.  We could just copy the definition of {{EX:displayName}}
 from {{F:inetorgperson.schema}} and replace the OID, name, and
 description, e.g:
@@ -289,7 +289,7 @@ description, e.g:
 >		SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
 >		SINGLE-VALUE )
 
-However, if we desire this name to included in
+However, if we want this name to be included in
 {{EX:name}} assertions [e.g. {{EX:(name=*Jane*)}}], the attribute
 could alternatively be defined as a subtype of {{EX:name}}, e.g.:
 
@@ -317,8 +317,8 @@ As noted in the description, LDAP has no knowledge of the
 format of the photo.  It's assumed that all applications
 accessing this attribute agree on the handling of values.
 
-If you want to support multiple photo format, one could define
-a separate attributes type for each format, prefix the photo
+If you wanted to support multiple photo formats, you could define
+a separate attribute type for each format, prefix the photo
 with some typing information, or describe the value using
 {{TERM:ASN.1}} and use the {{EX:;binary}} transfer option.
 
@@ -353,7 +353,7 @@ where Object Class Description is defined by the following
 
 where whsp is a space ('{{EX: }}'), numericoid is a globally unique
 OID in numeric form (e.g. {{EX:1.2.3}}), qdescrs is one or more
-names, oids is one or more names and/or OIDs.
+names, and oids is one or more names and/or OIDs.
 
 
 H4: myPhotoObject

doc/guide/admin/slapdconfig.sdf

@@ -308,7 +308,7 @@ authentication requires specification of {{EX:binddn}} and
 {{EX:credentials}} parameters.
 
 Kerberos authentication is deprecated in favor of SASL authentication
-mechanisms, in particular the {EX:KERBEROS_V4}} and {{EX:GSSAPI}}
+mechanisms, in particular the {{EX:KERBEROS_V4}} and {{EX:GSSAPI}}
 mechanisms.  Kerberos authentication requires {{EX:binddn}} and
 {{EX:srvtab}} parameters.
 
@@ -319,8 +319,8 @@ credentials can be specified using {{EX:authcid}} and {{EX:credentials}}
 respectively.  The {{EX:authzid}} parameter may be used to specify
 an authorization identity.
 
-See the {{SECT:Replication}} chapter for more information on how to
-use this directive.
+See the chapter entitled {{SECT:Replication with slurpd}} for more
+information on how to use this directive.
 
 
 H4: replogfile <filename>
@@ -333,8 +333,8 @@ However, you can also use it to generate a transaction log, if
 slurpd is not running. In this case, you will need to periodically
 truncate the file, since it will grow indefinitely otherwise.
 
-See the {{SECT:Replication}} chapter for more information on how to
-use this directive.
+See the chapter entitled {{SECT:Replication with slurpd}} for more
+information on how to use this directive.
 
 
 H4: rootdn <dn>