From keramida@freebsd.org  Mon Feb  3 17:02:10 2003
Return-Path: <keramida@freebsd.org>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 03DC937B401
	for <bug-followup@freebsd.org>; Mon,  3 Feb 2003 17:02:10 -0800 (PST)
Received: from mailsrv.otenet.gr (mailsrv.otenet.gr [195.170.0.5])
	by mx1.FreeBSD.org (Postfix) with ESMTP id A961543F9B
	for <bug-followup@freebsd.org>; Mon,  3 Feb 2003 17:02:08 -0800 (PST)
	(envelope-from keramida@freebsd.org)
Received: from gothmog.gr (patr530-a159.otenet.gr [212.205.215.159])
	by mailsrv.otenet.gr (8.12.6/8.12.6) with ESMTP id h1411rig005583;
	Tue, 4 Feb 2003 03:01:54 +0200 (EET)
Received: from gothmog.gr (gothmog [127.0.0.1])
	by gothmog.gr (8.12.6/8.12.6) with ESMTP id h1411qUg002605;
	Tue, 4 Feb 2003 03:01:52 +0200 (EET)
	(envelope-from keramida@freebsd.org)
Received: (from giorgos@localhost)
	by gothmog.gr (8.12.6/8.12.6/Submit) id h1411Vwe002600;
	Tue, 4 Feb 2003 03:01:31 +0200 (EET)
	(envelope-from keramida@freebsd.org)
Message-Id: <20030204010131.GA2267@gothmog.gr>
Date: Tue, 4 Feb 2003 03:01:31 +0200
From: Giorgos Keramidas <keramida@freebsd.org>
To: "Gary W. Swearingen" <swear@attbi.com>
Cc: bug-followup@freebsd.org, Adam Weinberger <adam@vectors.cx>,
	Oliver Fromme <olli@secnetix.de>
In-Reply-To: <w2isw2ifv2.sw2@localhost.localdomain>
Subject: Re: ln(1) manpage is confusing
References: <w2isw2ifv2.sw2@localhost.localdomain>

>Number:         47879
>Category:       docs
>Synopsis:       Re: ln(1) manpage is confusing
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    keramida
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          sw-bug
>Submitter-Id:   current-users
>Arrival-Date:   Mon Feb 03 17:10:12 PST 2003
>Closed-Date:    Wed Feb 05 17:17:46 PST 2003
>Last-Modified:  Wed Feb 05 17:17:46 PST 2003
>Originator:     
>Release:        
>Organization:
>Environment:
>Description:
 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
 
>How-To-Repeat:
>Fix:
>Release-Note:
>Audit-Trail:
State-Changed-From-To: open->closed 
State-Changed-By: keramida 
State-Changed-When: Wed Feb 5 17:16:15 PST 2003 
State-Changed-Why:  
Followup to docs/47818 misfiled as a new PR. 
Shame... shame... me, posting misfiled PRs.  Tsk tsk. 


Responsible-Changed-From-To: gnats-admin->keramida 
Responsible-Changed-By: keramida 
Responsible-Changed-When: Wed Feb 5 17:16:15 PST 2003 
Responsible-Changed-Why:  

http://www.freebsd.org/cgi/query-pr.cgi?pr=47879 
>Unformatted:
