On Sun, Jun 04, 2006 at 10:16:15PM +0200, Elad Efrat wrote:
> Thor Lancelot Simon wrote:
> 
> > I don't agree with you that "helpful" means "vague".
> 
> When was the last time you used the hashinit(9) interface?

Oh, a couple of weeks ago.  I also made the change in 1.135 that
caused us to diverge from the 4.4BSD interface, and periodically
have to answer questions about it.

The problem is that the bare description of the interface you
propose is not sufficient in this case, because our implementation
has slightly different performance characteristics than those the
readers of the manual page may be familiar with from other 4.4
variants -- so we really do need to say something about how it
works inside.

> My suggestions are based entirely on my own personal use of the
> interface and my own personal experiences with man-pages.

Perhaps other people's experience is not exactly like your own,
because, after all, every other person is not you.

I think it is reasonable to explain how our hashinit differs
from other implementations, and, in particular, to make the
user aware of the implications of our rounding the hash size
up.  I also think Chapman's text about hashmask is more helpful
than what you propose, because, in our implementation, %mask is
sometimes an even worse choice of hash function than it is in
the original implementation (because we support hashes of sizes
other than power-of-two).

Thor