From owner-freebsd-doc Sat Dec 21 11:30: 6 2002 Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 1167737B401 for ; Sat, 21 Dec 2002 11:30:05 -0800 (PST) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id E842543EE5 for ; Sat, 21 Dec 2002 11:30:03 -0800 (PST) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.12.6/8.12.6) with ESMTP id gBLJU3NS006686 for ; Sat, 21 Dec 2002 11:30:03 -0800 (PST) (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.12.6/8.12.6/Submit) id gBLJU31d006685; Sat, 21 Dec 2002 11:30:03 -0800 (PST) Date: Sat, 21 Dec 2002 11:30:03 -0800 (PST) Message-Id: <200212211930.gBLJU31d006685@freefall.freebsd.org> To: freebsd-doc@FreeBSD.org Cc: From: swear@attbi.com (Gary W. Swearingen) Subject: Re: docs/46415: Proposed change in man-page wording for "chown" Reply-To: swear@attbi.com (Gary W. Swearingen) Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org 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 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