Re: CVS commit: src/usr.bin/cksum

[John Hawkinson <jhawk%MIT.EDU@localhost>]

Hi...

Elad Efrat <elad%NetBSD.org@localhost> wrote on Sun, 21 Aug 2005
at 19:33:10 +0000 in <20050821193310.D23002DA27%cvs.netbsd.org@localhost>:

> Log Message:
> Add comments about intentionally not documenting the deprecated -1, -2, -4,
> -5, -6, and -m flags so they are not mistakenly get documented again in the
> future.

This...doesn't really seem to address the problem as well
as I would have liked...

The man page ought to explain what the options *do*. Just because they
are deprecated doesn't mean that a user should not be able to determine
their functionality.

It should say that they are deprecated, and maybe put the deprecated
options in a seperate section (DEPRECATED?) instead of lumped in with
the others.

Also, you say:

+.\" Note that the -a <algorithm> flag replaces the deprecated -1, -2, -4,
+.\" -5, -6, and -m flags. Their usage should be discouraged, so they are
+.\" intentionally left out of documentation.

But you don't say *why* they are de[recated. That's important too!
(and actually, I guess I don't know why they are deprecated? Why
are they deprecated?).

I'm confused why that is a comment, though, rather than in the
NOTES section? Why do you want to hide this information from users
who might legitimately want to know?

Thanks.

--jhawk