Gervase Markham wrote:
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
) 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?
Point taken. Though I would say familiarity with all of them is needed when
you run into a problem that isn't addressed in the formal docs.
> The Manual Pages, of
> course are the most obvious information resource provided directly with
> the software, and in Unix they are traditionally the authoritative
Well, not for the GNU project, at least (which supplies large chunks of
the most popular modern Unix):
GNU is Not Unix.
"In the GNU project, man pages are secondary. It is not
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."
It then goes on to discourage GNU authors from bothering with man pages.
Interesting reference. A couple of comments
1) They specifically need to call out this point, because they clearly are
going against established practice in making this point.
2) As much as I am a supporter of the GNU project, not all of their policies
actually make sense. E.g., the recommended viewer for their docs is Emacs.
Their philosophy has been "since memory is now plentiful and cheap on
computers, it's OK to use as much as you want without any second thought"
since the late 1980s. I dunno about you, but I run OpenLDAP on my Android G1
phone, and I *don't* run emacs or tex on it. Bytes of RAM and individual CPU
cycles are still scarce resources in the real world.
> 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.
Not at all, I was merely giving a counter-example to yours, showing that
there's a method to this madness and it is in fact a time-honored one.
Frankly, anybody who has been to school in the past century should recognize
it, because it's the standard model for educational texts. Just like a
handbook on (e.g. English) grammar is not a complete reference to a language -
it's simply a guide that gives the rules on how atoms fit together. It gives
examples on how sentences are constructed but that's by no means a statement
that those examples are the only possible sentences. There are dictionaries to
provide more complete references to all the available atoms, and you are
expected to construct your own sentences using the combination of those rules
and those available atoms.
> 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.
Fair enough. But again, as the preface states, suggestions/changes should be
posted to the ITS so that they may be tracked.
Specifically, the following man pages:
We'll have to think about how to integrate these hyperlinks into the Guide.
IMO we should not be encouraging people to rely on the web as their first
source of information; their first source of information should always be the
man pages that are already installed on their own hard drives. The reasons being
1) the manpages on their machine will most likely match the release of the
code that's actually running on their machine. We see a lot of problems from
people who read current documentation on the web site but they're in fact
running a 5-6 year old release that their distro provided, and they wonder why
some feature they tried to use didn't work (wasn't there). (We also
occasionally get the opposite, someone followed a link from an outdated HOWTO
to an old version of the Guide, tho they are running current code.)
2) relying on a remote server for documentation is dicy at best, especially
when you're in the middle of a disaster and you need the info Right Now and
your network has failed.
We could provide HTML-formatted copies of the manpages in the Guide but IMO
that's a waste of space.
And then, for particularly relevant man pages, such as slapd.access
the Access section, I would put another link on the relevant page of the
There already are multiple references to slapd.access in the Access Control
chapter, but I've added another at the top of the chapter as a result of this
-- Howard Chu
CTO, Symas Corp. http://www.symas.com
Director, Highland Sun http://highlandsun.com/hyc/
Chief Architect, OpenLDAP http://www.openldap.org/project/