[Date Prev][Date Next] [Chronological] [Thread] [Top]

Re: Allowing users to add, but not delete, entries?

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
(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?
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
reference.


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 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.


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:

OpenLDAP API:

<ul>
<li><a
href="http://www.openldap.org/software/man.cgi?query=ldap";>ldap(3)</a>
</ul>
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 for
the Access section, I would put another link on the relevant page of the
Guide.
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 conversation. 

--
  -- Howard Chu
  CTO, Symas Corp.           http://www.symas.com
  Director, Highland Sun     http://highlandsun.com/hyc/
  Chief Architect, OpenLDAP  http://www.openldap.org/project/