From owner-freebsd-doc Sat Feb 8 12:20: 9 2003 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 C68E437B401 for ; Sat, 8 Feb 2003 12:20:06 -0800 (PST) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id 5D22843F93 for ; Sat, 8 Feb 2003 12:20:06 -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 h18KK6NS023145 for ; Sat, 8 Feb 2003 12:20:06 -0800 (PST) (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.12.6/8.12.6/Submit) id h18KK66V023144; Sat, 8 Feb 2003 12:20:06 -0800 (PST) Date: Sat, 8 Feb 2003 12:20:06 -0800 (PST) Message-Id: <200302082020.h18KK66V023144@freefall.freebsd.org> To: freebsd-doc@FreeBSD.org Cc: From: swear@attbi.com (Gary W. Swearingen) Subject: Re: docs/47818: ln(1) manpage is confusing 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/47818; it has been noted by GNATS. From: swear@attbi.com (Gary W. Swearingen) To: bug-followup@FreeBSD.org Cc: Subject: Re: docs/47818: ln(1) manpage is confusing Date: 08 Feb 2003 12:10:05 -0800 Giorgos Keramidas writes: > I don't like the to_filename and from_filename names either though :( > > I would probably prefer the names: > > newlink for the hard or symbolic link file name > file for any existing files > I find "ln to_filename from_filename" ("link to filename from filename") has a really nice, rememberable ring to it. I reviewed the old thread and it's several suggestions and can find things wrong with all of them including a couple of my previous ideas. "link", "from_link", or "newlink" as the last argument isn't bad and I guess I wouldn't complain real loud about it, but the less we imply that a hard link is a link like a symlink, instead of just another filename entry in a directory, the better. I think "from_filename" is more generic and fits both soft and hard link cases better. If you really don't like "from_filename", how about "from_link" (or "from_newlink")? (I don't like the "new" part because it makes me want to go looking for the old link.) I don't like "file" even more. As you said before, that argument doesn't have to refer to a file. It can be just a filename string for the symlink's directory entry. More in next para.. > the difference in names makes it pretty clear which one is which, and > if you still have doubts if the reader will grasp the difference of > the two 'file' names, we can explicitly write in the text of the > manpage the fact that 'file ...' refers to existing files, while > 'newlink' refers to the files created by ln(1). The "difference in names" is too great in the case of a hard link. It makes it seem that a "file" and a "newlink" are very different things, when they are essentially identical, but maybe that's really more a problem with "newlink". The new manpage already explains what the arguments refer to, but I guess you can replace it to work better with any new arugment names. > Deciding what to call the two arguments of ln(1) is not an easy task. > I have thought a lot about it before replying. It is imperative we > find a good way to name them though, as this will also fix a lot of > the wrongs you have (rightfully) pointed out. Agreed. I must admit that your argument names run second-best of the candidates I've seen so far, and I'm no-doubt biased by having lived with mine for many hours, so I can live with yours, if you still want them after thinking about it again. (Maybe dropping "new"?) > Perhaps, if we expanded the difference a bit with the following? ... > to a file is one of the differences between a hard and symbolic link. > + Hard links are effectively different names for the same set of > + disk blocks. > + Removing one of the hard links of a file does not free the > + space of the rest of the hard links and return the disk space > + occupied by the file to the pool of free space on the disk. > + Symbolic links (also known as > + .Dq symlinks ) > + point to a specific file name. > + If you remove the file that a symbolic link points to, the > + disk space occupied by the file is freed to. > + The symbolic link continues to point to a file that no longer > + exists. > + It is then called a > + .Dq broken > + symbolic link. > > Does this look better than deleting the line? Worse, methinks. That sort of thing doesn't belong in the introductory paragraph(s). I think I covered that well enough in the descriptions of hardlinks and softlinks after the option descriptions. And I see no need to mention disk blocks at all; it's an implementation detail, which belongs outside the "DESCRIPTION" section, if anywhere. > > 11) The beginning of the description doesn't mention the "link" command. > > This needs fixing. I agree. But isn't the paragraph near the end of > description good enough already? I think not; the first paragraph(s) should introduce the manpage's commands, and an introduction is all that the command requires. Also, the paragraph you quote is wrong about specifying a directory. It also has an unnecessary implementation detail (which I moved to "NOTES" and generalized to all hard links, not just link(1)'s links). To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message