Date: Sat, 8 Feb 2003 12:20:06 -0800 (PST) From: swear@attbi.com (Gary W. Swearingen) To: freebsd-doc@FreeBSD.org Subject: Re: docs/47818: ln(1) manpage is confusing Message-ID: <200302082020.h18KK66V023144@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 <keramida@freebsd.org> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200302082020.h18KK66V023144>