Re: Admin Guide -- more editing (ITS#708)

[Kurt@OpenLDAP.org]

Applied, please test, thanks.
        http://www.openldap.org/devel/admin/ (draft pages)


At 08:34 PM 9/4/00 +0000, cedric@earthling.net wrote:
>Full_Name: Cedric Tefft
>Version: N/A
>OS: N/A
>URL: ftp://ftp.openldap.org/incoming/
>Submission from: (NULL) (205.138.230.83)
>
>
>More spelling, grammar, and stylistic fixups.
>
>Index: guide/admin/dbtools.sdf
>===================================================================
>RCS file: /repo/OpenLDAP/pkg/openldap-guide/admin/dbtools.sdf,v
>retrieving revision 1.10
>diff -u -r1.10 dbtools.sdf
>--- guide/admin/dbtools.sdf     2000/09/02 18:16:36     1.10
>+++ guide/admin/dbtools.sdf     2000/09/04 20:24:58
>@@ -28,14 +28,14 @@
> 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 @@
> 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 @@
> >      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 @@
> 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 @@
> 
> >      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 @@
> 
> >      -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 @@
> 
> 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 @@
> {{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 @@
> >      # 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 @@
> >
> >      ...
> 
>-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
>Index: guide/admin/referrals.sdf
>===================================================================
>RCS file: /repo/OpenLDAP/pkg/openldap-guide/admin/referrals.sdf,v
>retrieving revision 1.14
>diff -u -r1.14 referrals.sdf
>--- guide/admin/referrals.sdf   2000/08/18 09:22:48     1.14
>+++ guide/admin/referrals.sdf   2000/09/04 20:24:58
>@@ -6,7 +6,7 @@
> 
> 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 @@
> 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 @@
> 
> 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
>Index: guide/admin/replication.sdf
>===================================================================
>RCS file: /repo/OpenLDAP/pkg/openldap-guide/admin/replication.sdf,v
>retrieving revision 1.14
>diff -u -r1.14 replication.sdf
>--- guide/admin/replication.sdf 2000/08/31 03:52:55     1.14
>+++ guide/admin/replication.sdf 2000/09/04 20:24:58
>@@ -6,8 +6,8 @@
> 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 @@
> 
> + 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 @@
> {{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 @@
> 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 @@
> 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
>Index: guide/admin/schema.sdf
>===================================================================
>RCS file: /repo/OpenLDAP/pkg/openldap-guide/admin/schema.sdf,v
>retrieving revision 1.10
>diff -u -r1.10 schema.sdf
>--- guide/admin/schema.sdf      2000/08/29 18:25:05     1.10
>+++ guide/admin/schema.sdf      2000/09/04 20:24:58
>@@ -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 @@
> 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 @@
> {{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 @@
> .{{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 @@
> 
> 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 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 @@
> 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 @@
> !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 @@
> 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 @@
> >              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 @@
> 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 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
>Index: guide/admin/slapdconfig.sdf
>===================================================================
>RCS file: /repo/OpenLDAP/pkg/openldap-guide/admin/slapdconfig.sdf,v
>retrieving revision 1.28
>diff -u -r1.28 slapdconfig.sdf
>--- guide/admin/slapdconfig.sdf 2000/08/31 16:36:01     1.28
>+++ guide/admin/slapdconfig.sdf 2000/09/04 20:24:58
>@@ -308,7 +308,7 @@
> {{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 @@
> 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 @@
> 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>