ln: add details to --help text

* src/ln.c (usage): Mention more about symlink properties.
* doc/coreutils.texi (ln invocation): Likewise.
* THANKS: Update.
Reported by Vitali Lovich.

Signed-off-by: Eric Blake <ebb9@byu.net>

3 files changed, 29 insertions, 3 deletions

diff --git a/THANKS b/THANKS
index da1fc1555..a3f9801a7 100644
--- a/THANKS
+++ b/THANKS
@@ -553,6 +553,7 @@ Uwe H. Steinfeld                    usteinfeld@gmx.net
 Vesselin Atanasov                   vesselin@bgnet.bg
 Vin Shelton                         acs@alumni.princeton.edu
 Vineet Chadha                       chadha@acis.ufl.edu
+Vitali Lovich                       vlovich@gmail.com
 Vitaly A. Ostanin                   vyt@altlinux.org
 Vlada Macek                         tuttle@bbs.fsik.cvut.cz
 Volker Borchert                     bt@teknon.de
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index c3a116470..57497e960 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -8689,9 +8689,32 @@ refers to a different file, by name.  When most operations (opening,
 reading, writing, and so on) are passed the symbolic link file, the
 kernel automatically @dfn{dereferences} the link and operates on the
 target of the link.  But some operations (e.g., removing) work on the
-link file itself, rather than on its target.  @xref{Symbolic Links,,,
+link file itself, rather than on its target.  The owner, group, and
+mode of a symlink are not significant to file access performed through
+the link.  @xref{Symbolic Links,,,
 libc, The GNU C Library Reference Manual}.
 
+Symbolic links can contain arbitrary strings; a @dfn{dangling symlink}
+occurs when the string in the symlink does not resolve to a file.
+There are no restrictions against creating dangling symbolic links.
+There are trade-offs to using absolute or relative symlinks.  An
+absolute symlink always points to the same file, even if the directory
+containing the link is moved.  However, if the symlink is visible from
+more than one machine (such as on a networked file system), the file
+pointed to might not always be the same.  A relative symbolic link is
+resolved in relation to the directory that contains the link, and is
+often useful in referring to files on the same device without regards
+to what name that device is mounted on when accessed via networked
+machines.
+
+When creating a relative symlink in a different location than the
+current directory, the resolution of the symlink will be different
+than the resolution of the same string from the current directory.
+Therefore, many users prefer to first change directories to the
+location where the relative symlink will be created, so that
+tab-completion or other file resolution will find the same target as
+what will be placed in the symlink.
+
 The program accepts the following options.  Also see @ref{Common options}.
 
 @table @samp
diff --git a/src/ln.c b/src/ln.c
index 2dc5628e8..d0f92669d 100644
--- a/src/ln.c
+++ b/src/ln.c
@@ -1,5 +1,5 @@
 /* `ln' program to create links between files.
-   Copyright (C) 1986, 1989-1991, 1995-2008 Free Software Foundation, Inc.
+   Copyright (C) 1986, 1989-1991, 1995-2009 Free Software Foundation, Inc.
 
    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
@@ -359,7 +359,9 @@ In the 1st form, create a link to TARGET with the name LINK_NAME.\n\
 In the 2nd form, create a link to TARGET in the current directory.\n\
 In the 3rd and 4th forms, create links to each TARGET in DIRECTORY.\n\
 Create hard links by default, symbolic links with --symbolic.\n\
-When creating hard links, each TARGET must exist.\n\
+When creating hard links, each TARGET must exist.  Symbolic links\n\
+can hold arbitrary text; if later resolved, a relative link is\n\
+interpreted in relation to its parent directory.\n\
 \n\
 "), stdout);
       fputs (_("\