On 03/03/11 16:12, Howard Chu wrote:
The preface.html which you linked above clearly states:
Scope of this Document
This document provides a guide for installing OpenLDAP Software 2.4 (http://www.openldap.org/software/) on UNIX (and UNIX-like) systems. The document is aimed at experienced system administrators with basic understanding of LDAP-based directory services.
This document is meant to be used in conjunction with other OpenLDAP information resources provided with the software package and on the project's site (http://www.OpenLDAP.org/) on the World Wide Web. The site makes available a number of resources.
... <<<<
And then goes on to list various other resources.
A list of 7 resources, including the mailing lists and the issue tracking system. I assume reading all of those is not required?
The Manual Pages, of course are the most obvious information resource provided directly with the software, and in Unix they are traditionally the authoritative reference.
Well, not for the GNU project, at least (which supplies large chunks of the most popular modern Unix):
"In the GNU project, man pages are secondary. It is not necessary or expected for every GNU program to have a man page, but some of them do. It’s your choice whether to include a man page in your program."
http://www.gnu.org/prep/standards/standards.html#Man-Pages
It then goes on to discourage GNU authors from bothering with man pages.
Given the heritage of this project it seems obvious to me that this is how the docs would be structured.
That sounds as if you are saying that familiarity with the heritage of the project is necessary in order to work out how to use the software.
If the phrase "meant to be used in conjunction" isn't a strong enough hint that the Guide is not a standalone document, please feel free to suggest an alternate or stronger wording. Note that the preface also invites you to do the same.
I would say instead:
This document is not a complete guide to its subject matter; the man pages are the definitive documentation for OpenLDAP software. Specifically, the following man pages:
OpenLDAP API:
<ul> <li><a href="http://www.openldap.org/software/man.cgi?query=ldap">ldap(3)</a> </ul>
OpenLDAP configuration:
<ul> <li><a href="http://www.openldap.org/software/man.cgi?query=slapd.conf">slapd.conf(5)</a> <li><a href="http://www.openldap.org/software/man.cgi?query=slapd-config">slapd-config(5)</a> <li><a href="http://www.openldap.org/software/man.cgi?query=slapd.access">slapd.access(5)</a> </ul>
OpenLDAP command line tools:
<ul> <li><a href="http://www.openldap.org/software/man.cgi?query=slapacl">slapacl(8)</a> <li><a href="http://www.openldap.org/software/man.cgi?query=slapadd">slapadd(8)</a> <li><a href="http://www.openldap.org/software/man.cgi?query=slapauth">slapauth(8)</a> <li><a href="http://www.openldap.org/software/man.cgi?query=slapcat">slapcat(8)</a> <li><a href="http://www.openldap.org/software/man.cgi?query=slapdn">slapdn(8)</a> <li><a href="http://www.openldap.org/software/man.cgi?query=slapindex">slapindex(8)</a> <li><a href="http://www.openldap.org/software/man.cgi?query=slappasswd">slappasswd(8)</a> <li><a href="http://www.openldap.org/software/man.cgi?query=slapschema">slapschema(8)</a> <li><a href="http://www.openldap.org/software/man.cgi?query=slaptest">slaptest(8) </ul>
And then, for particularly relevant man pages, such as slapd.access for the Access section, I would put another link on the relevant page of the Guide.
Gerv