Bug 47879

Description Giorgos Keramidas 2003-02-04 01:10:12 UTC

 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