Date: Sat, 21 Dec 2002 11:30:03 -0800 (PST) From: swear@attbi.com (Gary W. Swearingen) To: freebsd-doc@FreeBSD.org Subject: Re: docs/46415: Proposed change in man-page wording for "chown" Message-ID: <200212211930.gBLJU31d006685@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
The following reply was made to PR docs/46415; it has been noted by GNATS.
From: swear@attbi.com (Gary W. Swearingen)
To: root@asarian-host.net
Cc: FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: docs/46415: Proposed change in man-page wording for "chown"
Date: 21 Dec 2002 11:19:50 -0800
System Administrator <root@asarian-host.net> writes:
> Therefore, I believe that perhaps a more legible wording may be in order:
>
> -R If file designates a directory, chown changes the ownership of
> the directory and the entire subtree connected at that point.
1) That leaves one guessing what happens if "file" isn't a directory.
2) While using just "ownership" *should* be sufficient, the manpage
currently uses "owner" where it should use "user", so that "ownership"
is likely to be interpreted as related only to "owner" and not also to
"group" (groupship?). Short of fixing "owner" throughout, "ownership"
should be replaced with the twice-used "user ID and/or the group ID" or
maybe just "ID". 3) While "Entire subtree" provids a strong clue as to
meaning that just "subtree" doesn't, they can be seen as equivalent in
a strict reading. It could be more clear about being recursive. Maybe:
-R Change the user ID and/or the group ID of the directory entries
specified by the "file" arguments and, recursively, the contents
of any directory subtrees named by those directory entries.
(A little verbose, even redundant -- but clear, IMO. I'd probably end
it "... subtrees so specified." if it didn't sound too archaic.)
> Perhaps, all to the discretion of the developers, of course, the following text could be added:
>
> Caveat: depending on your shell, ".*" may expand the parent directory!
It's usually best to avoid "your", and "expand the parent directory"
seems to imply that ".*" might turn into a list of the parent
directory's files. "Caveat" is unnecessarily esoteric. How about:
Beware that ".*" is expanded by some shells to include "..".
(Using ".." explains how the parent directory can be included and
it shouldn't be necessary to explain that ".." IS the parent dir.)
Another issue is the placement of the warning. An unexpected ".." could
cause great harm with or without "-R". The warning seems to belong at
the end of the DESCRIPTION section as a separate paragraph, but it's
far more useful in reducing the occurances of disasters if it's in the
description of "-R". It's short enough to put in both places.
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200212211930.gBLJU31d006685>