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

[Taylor R Campbell <campbell+netbsd-source-changes-d%mumble.net@localhost>]

> Date: Thu, 25 May 2023 15:10:41 +0300
> From: Valery Ushakov <uwe%stderr.spb.ru@localhost>
> 
> This new paragraph is wedged right between the list of the options and
> the continuation of that same paragraph that says that they can be
> prefixed with "no".
> 
> A description of an obsolete flag right in the middle of the manpage
> is a very poor narrative choice.
> 
> Calling nodump "not intuitive" is not intuitive.
> 
> Anyway, this change is strictly for the worse.  If you want to keep
> these random tidbits of information, move them elsewhere, like HISTORY
> section (which is probably the most appropriate place for the
> obsolete, unused, compat-only msdos flag).

Can I suggest framing this a little more constructively and a little
less derisively?

Personally I find the chflags options confusing, and I appreciate
jschauma@ taking the time to sort them out and clarify the
documentation even if it's not perfect the first time around.

Here are some questions that come to mind when I read the man page as
it is:

1. What is `arch' or `archived' supposed to mean?  Who sets it, who
   pays attention to it, and what consequences does it have?  Is it
   obsolete?  What was it used for?  From the current text, I have no
   idea!

2. What is `nodump' supposed to mean?  Who sets it, who pays attention
   to it, and what consequences does it have?  Does the kernel do
   anything about it, or is it just an extra bit of storage that
   programs like dump(8) can choose to examine?  From the current
   text, I have no idea!

3. What is the difference between `system' and `user' immutable or
   append-only?  If I set uchg, does that mean the _owner_ can't
   modify the file, or that _nobody_ can modify the file?

jschauma@'s change did help clarify (1) and (2).  Let's try to work
together to make it better?