Gervase Markham wrote:
On 03/03/11 15:33, Howard Chu wrote:
Note that a "Guide" is not a reference manual; it is not intended to be complete or exhaustive.
I'm not sure this use of terminology is universal; here is a counter-example: http://www.bugzilla.org/docs/tip/en/html/
It's certainly been the norm for Unix at least. E.g., compare the Guides vs Reference Manuals in the Solaris documentation.
http://download.oracle.com/docs/cd/E19253-01/index.html
Or the 4BSD system documentation:
http://www.freebsd.org/doc/en/books/faq/bibliography.html
Material in the 4BSD User's Supplementary Documents and Programmer's Supplementary Documents was a bit more friendly in prose, but only explained the approach to how to use the system. The details of each command or function are only found in the Reference Manuals.
It's only intended to provide an overview; the detailed/exhaustive docs are always the manpages.
I would suggest that neither: http://www.openldap.org/doc/ nor http://www.openldap.org/doc/admin24/preface.html nor the individual pages in the Admin Guide give the impression either that the Admin Guide is not complete, or that the manual pages are an essential read or the canonical reference.
Perhaps it would help OpenLDAP users if this were made a little more clear?
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. 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. Given the heritage of this project it seems obvious to me that this is how the docs would be structured. 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.
Thank you for your help and support :-)
Thank you for your feedback. We're always listening.