From swear@attbi.com  Sun Feb  2 12:32:54 2003
Return-Path: <swear@attbi.com>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 817E437B401
	for <FreeBSD-gnats-submit@freebsd.org>; Sun,  2 Feb 2003 12:32:54 -0800 (PST)
Received: from rwcrmhc51.attbi.com (rwcrmhc51.attbi.com [204.127.198.38])
	by mx1.FreeBSD.org (Postfix) with ESMTP id A079F43F3F
	for <FreeBSD-gnats-submit@freebsd.org>; Sun,  2 Feb 2003 12:32:53 -0800 (PST)
	(envelope-from swear@attbi.com)
Received: from localhost.localdomain (<unknown.domain>[12.242.158.67])
          by rwcrmhc51.attbi.com (rwcrmhc51) with ESMTP
          id <2003020220324705100hri2ue>; Sun, 2 Feb 2003 20:32:47 +0000
Received: from localhost.localdomain (localhost [127.0.0.1])
	by localhost.localdomain (8.12.6/8.12.5) with ESMTP id h12KVu5F063867;
	Sun, 2 Feb 2003 12:32:02 -0800 (PST)
	(envelope-from swear@attbi.com)
Received: (from jojo@localhost)
	by localhost.localdomain (8.12.6/8.12.5/Submit) id h12KVjp9063862;
	Sun, 2 Feb 2003 12:31:45 -0800 (PST)
	(envelope-from swear@attbi.com)
Message-Id: <w2isw2ifv2.sw2@localhost.localdomain>
Date: 02 Feb 2003 12:31:45 -0800
From: "Gary W. Swearingen" <swear@attbi.com>
Reply-To: swear@attbi.com
To: FreeBSD-gnats-submit@freebsd.org
Cc: Giorgos Keramidas <keramida@ceid.upatras.gr>,
	Adam Weinberger <adam@vectors.cx>, Oliver Fromme <olli@secnetix.de>
Subject: ln(1) manpage is confusing
X-GNATS-Notify:

>Number:         47818
>Category:       docs
>Synopsis:       [patch] ln(1) manpage is confusing
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Sun Feb 02 12:40:13 PST 2003
>Closed-Date:    Sat Nov 13 11:05:40 UTC 2010
>Last-Modified:  Sat Nov 13 11:05:40 UTC 2010
>Originator:     Gary W. Swearingen
>Release:        FreeBSD 4.7-STABLE i386
>Organization:
none
>Environment:
n/a
================
>Description:

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.

2) The "ls -l" output shows an arrow coming out of the "target" instead
of the more natural direction.  This is not a problem with "ls", but
a problem with "ln" misnaming the argument.

3) The other argument is called "target" by code within the "ln" program
itself and by POSIX docs.

4) It's not intuitive that the "source" should be the source of the
link (ie, the source of the "arrow") or the source of data when the
linked file is accessed -- opposite senses.  Better not use the term.

5) The seemingly arbitrary assignment of the terms "source file" and
"target file" to the arguments makes their order hard to remember.

6) The order of the two arguments is opposite from their order when
output by "ls -l".  This is not necessarily bad, but it makes things
harder to remember and makes it important that the manual help readers
remember the correct order.  Good terms and naming is important.

7) The "ls -l" command shows an arrow coming out of the "target", using
the old ln(1)'s jargon.  Arrows should go into targets.  Better yet,
keep them in their quiver. (I.e, don't use the esoteric term.)

8) The "apropos" string in the "Name" section doesn't contain the
terms "symbolic", "soft", "hard", or the same followed by "link",
all of which are likely to be searched for by apropos(1) users.

9) The last sentence of the first paragraph is more noise than help.

10) The -h description is a little confusing about how a "target_file"
can point to a directory or how such a link could be followed by ln.

11) The beginning of the description doesn't mention the "link" command.

12) The descriptions could be better organized and otherwise improved.
================
>How-To-Repeat:
n/a
================
>Fix:
=========================
1) The names of the command arguments (eg, in the synopsis) are changed
to make clear what purpose the arguments serve and to make the command
read naturally as a command to the system.

    ln to_filename from_filename

That is, "link to [first] file from [second] file".  Of course, with
-s, to_filename can be any string and need not refer to a file, but that
is a detail better left for the description instead of using an esoteric
term like "target" to refer also to an existing filename (without -s).

The terms seem less arbitrary than the ln(1)-peculiar meanings of
"source" and "target", and are thus more easily remembered.

Note that during discussion, it seemed clear to me that any arugment
name which contained some form of the word "link" (as then proposed by
me and others) caused problems for some people.  The proposed names
leave the word only in the command name where it is unconfusing.

2) The new synopsis looks like this:

    ln [-fhinsv] to_filename {... directory_name | [from_filename]}
    link to_filename {directory_name | from_filename}

Note that "filename" is used in the synopses because the argument
specifies a filename, but not necessarily a file; with -s, the filename
need not refer to a file; if may refer to a directory or to nothing.

3) The description section's use of "source file" and "target file"
very-much echo the names of the arguments and so they are easily
replaced by new terms, "to filename" and "from filename".

4) Separating the hard and soft link cases was considered, but having
five synopsis lines and using more specific argument names (which has
its benefits), looked messy/confusing/redundant and gave too much to
decypher and think about.

5) Some other descriptions are reworked to improve clarity.


Preview results of this patch with something like this:
    zcat /usr/share/man/man1/ln.1.gz >/tmp/ln.1
    patch -s /tmp/ln.1 <this message>
    groff -mandoc -Tascii /tmp/ln.1 | less

Patch this:
[.\" $FreeBSD: src/bin/ln/ln.1,v 1.11.2.7 2002/08/19 08:14:22 tjr Exp $]
with this:

--- /pr/work/ln..orig.1	Tue Jan 14 11:29:50 2003
+++ /pr/work/ln.1	Sun Feb  2 11:20:32 2003
@@ -41,65 +41,85 @@
 .Sh NAME
 .Nm ln ,
 .Nm link
-.Nd make links
+.Nd make hard links and symbolic links (symlinks, soft links)
 .Sh SYNOPSIS
 .Nm
 .Op Fl fhinsv
-.Ar source_file
-.Op Ar target_file
-.Nm
-.Op Fl fhinsv
-.Ar source_file ...
-.Ar target_dir
+.Ar to_filename Brq ... Ar directory_name | Op Ar from_filename
 .Nm link
-.Ar source_file Ar target_file
+.Ar to_filename Brq Ar directory_name | Ar from_filename
 .Sh DESCRIPTION
 The
 .Nm
-utility creates a new directory entry (linked file) which has the
-same modes as the original file.
-It is useful for maintaining multiple copies of a file in many places
-at once without using up storage for the
-.Dq copies ;
-instead, a link
-.Dq points
-to the original copy.
-There are two types of links; hard links and symbolic links.
-How a link
-.Dq points
-to a file is one of the differences between a hard and symbolic link.
-.Pp
-The options are as follows:
-.Bl -tag -width flag
+command creates new directory entries
+which generally refer to existing files
+so that each file may be accessed by another filename,
+possibly in another directory or filesystem.
+.\"so that multiple virtual copies of a file can exist
+.\"while using storage for only one file.
+The
+.Nm link
+command is equivalent to
+.Nm ,
+except that it must have exactly two arguments and no options;
+therefore, it is not described further.
+.Pp
+Two types of links may be created:
+.Em hard links
+by default, and
+.Em symbolic links
+when the
+.Fl s
+option is used.
+Symbolic links are often called
+.Em symlinks
+or sometimes
+.Em soft links .
+The two types are described following these option descriptions
+(in which the
+.Qq from
+file (i.e., link) to be created can be
+.Ar from_filename
+or a file in the
+.Ar directory_name
+directory):
+.Bl -tag -width ".Fl f"
 .It Fl f
-If the target file already exists,
-then unlink it so that the link may occur.
+If the
+.Qq from
+file already exists, then replace it.
 (The
 .Fl f
-option overrides any previous
+option cancels any previous
 .Fl i
 options.)
 .It Fl h
-If the
-.Ar target_file
-or
-.Ar target_dir
-is a symbolic link, do not follow it.  This is most useful with the
+If
+.Ar directory_name
+is a symlink to a directory, do not follow it.  This is useful with the
 .Fl f
-option, to replace a symlink which may point to a directory.
+option, to replace the symlink.
+(By definition,
+.Ar from_filename
+is a file or a symlink to a file, which is never followed by
+.Nm . )
 .It Fl i
 Cause
 .Nm
-to write a prompt to standard error if the target file exists.
+to write a prompt to standard error if the
+.Qq from
+file exists.
 If the response from the standard input begins with the character
 .Sq Li y
 or
 .Sq Li Y ,
-then unlink the target file so that the link may occur.
+then remove the
+.Qq from
+file so that the link may occur.
 Otherwise, do not attempt the link.
 (The
 .Fl i
-option overrides any previous
+option cancels any previous
 .Fl f
 options.)
 .It Fl n
@@ -109,69 +129,93 @@
 .Nm
 implementations.
 .It Fl s
-Create a symbolic link.
+Create a symlink, instead of a hard link.
 .It Fl v
 Cause
 .Nm
 to be verbose, showing files as they are processed.
 .El
 .Pp
-By default,
-.Nm
-makes
-.Em hard
-links.
-A hard link to a file is indistinguishable from the original directory entry;
-any changes to a file are effectively independent of the name used to reference
-the file.
-Hard links may not normally refer to directories and may not span filesystems.
+Hard links to a file are indistinguishable from the file and from each other,
+except for the filenames;
+in fact, each file in a filesystem appears as one or more hard link
+directory entries by which the file's data may be accessed.
+All of a file's hard links have the same file owner, group, modes, and flags,
+and changes made to one effect them all identically,
+except that removing one hard link leaves the others uneffected
+until the last hard link is removed, removing the file's data too.
+A hard link cannot be created for a file on another filesystem nor (with
+.Nm )
+for a directory.
+(But note that the
+.Qq \&.
+and
+.Qq \&..
+directories appear as hard links.)
 .Pp
-A symbolic link contains the name of the file to
-which it is linked.  The referenced file is used when an
+Symlinks contain the filename of a directory or file
+which may be on any filesystem (or which may not exist,
+a feature which is sometimes utilized
+to store miscellaneous data in a directory entry).
+Symlinks to one file may have different owners, groups, modes, and flags,
+and are not effected by changes or removal of the file or other symlinks.
+.Ss "Command Forms"
+.Bl -tag -width ""
+.It Nm Ar to_filename
+That creates a link to
+.Ar to_filename
+from
+.Ar basename ,
+where the latter is the base name
+.Xr ( basename 1 )
+of
+.Ar to_filename .
+.It Nm Ar to_filename Ar from_filename
+That creates a link to
+.Ar to_filename
+from
+.Ar from_filename .
+.It Nm Ar to_filename Ar ... Ar directory_name
+That create links to one or more instances of
+.Ar to_filename
+from one or more corresponding instances of
+.Ar directory_name/basename
+where
+.Ar basename
+is the base name
+.Xr ( basename 1 )
+of the corresponding
+.Ar to_filename .
+.El
+.Sh "NOTES"
+The handling of symlinks by other programs is not well standardized
+and tends to be poorly documented for seldom-used cases;
+e.g., some follow the symlink if its name is followed by
+.Qq / .
+See the
+.Xr symlink 7
+manpage for some often-followed conventions,
+notable exceptions, and related discussion.
+.Pp
+Hard links are created with
+.Xr link 2 .
+Symlinks are created with
+.Xr symlink 2 .
+When used on symlinks, the
 .Xr open  2
-operation is performed on the link.
-A
+and
 .Xr stat  2
-on a symbolic link will return the linked-to file; an
+functions operate on the linked-to file, while
 .Xr lstat  2
-must be done to obtain information about the link.
+will access information about the symlink.
 The
 .Xr readlink  2
-call may be used to read the contents of a symbolic link.
-Symbolic links may span filesystems and may refer to directories.
-.Pp
-Given one or two arguments,
-.Nm
-creates a link to an existing file
-.Ar source_file  .
-If
-.Ar target_file
-is given, the link has that name;
-.Ar target_file
-may also be a directory in which to place the link;
-otherwise it is placed in the current directory.
-If only the directory is specified, the link will be made
-to the last component of
-.Ar source_file  .
-.Pp
-Given more than two arguments,
-.Nm
-makes links in
-.Ar target_dir
-to all the named source files.
-The links made will have the same name as the files being linked to.
-.Pp
-When the utility is called as
-.Nm 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
-.Xr link 2
-operation using the two passed arguments.
+call may be used to read the contents of a symlink.
 .Sh SEE ALSO
+.Xr basename 1 ,
 .Xr link 2 ,
 .Xr lstat 2 ,
+.Xr open 2 ,
 .Xr readlink 2 ,
 .Xr stat 2 ,
 .Xr symlink 2 ,
@@ -183,17 +227,17 @@
 .Fl n
 and
 .Fl v
-options are non-standard and their use in scripts is not recommended.
+options are non-standard and their omission from scripts is recommended.
 They are provided solely for compatibility with other
 .Nm
 implementations.
 .Sh STANDARDS
 The
 .Nm
-utility conforms to
+command conforms to
 .St -p1003.2-92 .
 .Pp
-The simplified
+The
 .Nm link
 command conforms to
 .St -susv2 .
>Release-Note:
>Audit-Trail:

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
 
State-Changed-From-To: open->feedback 
State-Changed-By: dannyboy 
State-Changed-When: Sat Feb 8 07:28:24 PST 2003 
State-Changed-Why:  
keramida has suggested changes and asks for comment. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=47818 

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).
 
State-Changed-From-To: feedback->open 
State-Changed-By: keramida 
State-Changed-When: Wed May 18 16:28:52 GMT 2005 
State-Changed-Why:  
Feedback is in the audit trail of this PR since a long time now. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=47818 
State-Changed-From-To: open->patched 
State-Changed-By: trhodes 
State-Changed-When: Tue Jan 13 15:24:46 UTC 2009 
State-Changed-Why:  
Patch committed which cleans up the language of the manual 
page and improves the .Nd line.  The "source/target" part 
remains as it is also used by other manual pages such as 
mv(1) and cp(1).  Thanks! 


Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Tue Jan 13 15:24:46 UTC 2009 
Responsible-Changed-Why:  
Over to me, MFC reminder. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=47818 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/47818: commit references a PR
Date: Tue, 13 Jan 2009 15:24:46 +0000 (UTC)

 Author: trhodes
 Date: Tue Jan 13 15:24:35 2009
 New Revision: 187148
 URL: http://svn.freebsd.org/changeset/base/187148
 
 Log:
   Clean up a bit of confusing language and improve .Nd.
   
   PR:		47818
   Reviewed by:	keramida
 
 Modified:
   head/bin/ln/ln.1
 
 Modified: head/bin/ln/ln.1
 ==============================================================================
 --- head/bin/ln/ln.1	Tue Jan 13 13:19:42 2009	(r187147)
 +++ head/bin/ln/ln.1	Tue Jan 13 15:24:35 2009	(r187148)
 @@ -38,7 +38,7 @@
  .Sh NAME
  .Nm ln ,
  .Nm link
 -.Nd make links
 +.Nd link files
  .Sh SYNOPSIS
  .Nm
  .Op Fl s Op Fl F
 @@ -57,8 +57,13 @@
  .Sh DESCRIPTION
  The
  .Nm
 -utility creates a new directory entry (linked file) which has the
 -same modes as the original file.
 +utility creates a new directory entry (linked file) for the file name
 +specified by
 +.Ar target_file .
 +The
 +.Ar target_file
 +will be created with the same file modes as the
 +.Ar source_file .
  It is useful for maintaining multiple copies of a file in many places
  at once without using up storage for the
  .Dq copies ;
 @@ -148,7 +153,7 @@ links.
  A hard link to a file is indistinguishable from the original directory entry;
  any changes to a file are effectively independent of the name used to reference
  the file.
 -Hard links may not normally refer to directories and may not span file systems.
 +Directories may not be hardlinked, and hard links may not span file systems.
  .Pp
  A symbolic link contains the name of the file to
  which it is linked.
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/47818: commit references a PR
Date: Fri, 23 Jan 2009 12:01:39 +0000 (UTC)

 Author: keramida (doc committer)
 Date: Fri Jan 23 12:01:24 2009
 New Revision: 187630
 URL: http://svn.freebsd.org/changeset/base/187630
 
 Log:
   MFC 187148 from /head
   
   Clean up a bit of confusing language and improve .Nd.
   
   PR:	47818
 
 Modified:
   stable/7/bin/ln/   (props changed)
   stable/7/bin/ln/ln.1
 
 Modified: stable/7/bin/ln/ln.1
 ==============================================================================
 --- stable/7/bin/ln/ln.1	Fri Jan 23 11:58:24 2009	(r187629)
 +++ stable/7/bin/ln/ln.1	Fri Jan 23 12:01:24 2009	(r187630)
 @@ -38,7 +38,7 @@
  .Sh NAME
  .Nm ln ,
  .Nm link
 -.Nd make links
 +.Nd link files
  .Sh SYNOPSIS
  .Nm
  .Op Fl s Op Fl F
 @@ -57,8 +57,13 @@
  .Sh DESCRIPTION
  The
  .Nm
 -utility creates a new directory entry (linked file) which has the
 -same modes as the original file.
 +utility creates a new directory entry (linked file) for the file name
 +specified by
 +.Ar target_file .
 +The
 +.Ar target_file
 +will be created with the same file modes as the
 +.Ar source_file .
  It is useful for maintaining multiple copies of a file in many places
  at once without using up storage for the
  .Dq copies ;
 @@ -148,7 +153,7 @@ links.
  A hard link to a file is indistinguishable from the original directory entry;
  any changes to a file are effectively independent of the name used to reference
  the file.
 -Hard links may not normally refer to directories and may not span file systems.
 +Directories may not be hardlinked, and hard links may not span file systems.
  .Pp
  A symbolic link contains the name of the file to
  which it is linked.
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 
State-Changed-From-To: patched->closed 
State-Changed-By: arundel 
State-Changed-When: Sat Nov 13 11:04:23 UTC 2010 
State-Changed-Why:  
Patch is in HEAD, 8.x and 7.x. 6.x went EoL. 

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