Date: Wed, 5 Feb 2003 17:20:09 -0800 (PST) From: Giorgos Keramidas <keramida@freebsd.org> To: freebsd-doc@FreeBSD.org Subject: Re: docs/47818: ln(1) manpage is confusing Message-ID: <200302060120.h161K9Bg090013@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: Giorgos Keramidas <keramida@freebsd.org> To: bug-followup@freebsd.org Cc: Subject: Re: docs/47818: ln(1) manpage is confusing Date: Thu, 6 Feb 2003 03:15:51 +0200 [-- adding to audit trail --] : Message-Id: <20030204010131.GA2267@gothmog.gr> : Date: Tue, 4 Feb 2003 03:01:31 +0200 : From: Giorgos Keramidas <keramida@freebsd.org> : : On 2003-02-02 12:31, "Gary W. Swearingen" <swear@attbi.com> wrote: : > >Originator: Gary W. Swearingen : > >Synopsis: ln(1) manpage is confusing : > >Category: docs : > >Release: FreeBSD 4.7-STABLE i386 : > >Environment: n/a : > >Description: : : This sort of change applies equally to 5.X and 4.X (or older) : versions. I still remember the thread in -doc. Thanks for : reminding me about it Gary, because I `lost' it in the rest of : the doc PRs. : : > The "ln" manual is confusing. This was cause for a recent -questions : > thread on the subject where that sentiment was confirmed by several : > people. Here are some problems: : > 1) Many newbies aren't familiar with its use of "target", or even with : > the more common use of the term. : : 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 : : 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). : : 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. : : > 9) The last sentence of the first paragraph is more noise than help. : : Perhaps, if we expanded the difference a bit with the following? : : How a link : .Dq points : 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? : : > 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? : : When the utility is called as link, exactly two arguments must be : supplied, neither of which may specify a directory. No options : may be supplied in this simple mode of operation, which performs : a link(2) operation using the two passed arguments. : : - Giorgos 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?200302060120.h161K9Bg090013>