ln documentation clarification

[Sittser, Steven]

I would like to suggest that you add a clarification to your
documentation of ln:

 

In the invocation "ln [option]... target linkname", the target parameter
is interpreted very differently depending on whether or not the "-s"
option is present.  If it is not, then target is, as with most file
parameters to most Unix commands, relative to the current directory (if
it is a relative path).  But, if the "-s" parameter is present, then
target is instead relative to the directory that linkname is in.

 

ln's behavior is very unusual - I'm not aware of any other Unix command
that: (1) interprets relative path names as relative to something other
than the current directory, or (2) interprets relative path names
differently depending on the presence or absence of a
seemingly-unrelated option.  I find this behavior very surprising
(though I understand the reason for it).

 

The man page for ln makes no mention of this.  I think it should.  (The
man page is a bit old - it says "ln 5.3.0, March 2005", and is in
Cygwin.)

 

The Coreutils manual
(http://www.gnu.org/software/coreutils/manual/coreutils.html, ver. 7.2)
includes a paragraph that hints at this (beginning "When creating a
relative symlink in a different location than the current
directory..."), but I don't think quite makes it clear.  It's such odd
behavior that I think it could use a more direct description.

 

Perhaps the following example would be of use:

 

    $ mkdir fred

    $ mkdir sam

    $ mkdir fred/sam

    $ echo "I am sam/target" >sam/target

    $ echo "I am fred/sam/target" >fred/sam/target

    $ ln sam/target fred/hardlink

    $ ln -s sam/target fred/symlink

    $ cat fred/hardlink

    I am sam/target

    $ cat fred/symlink

    I am fred/sam/target

    $

 

I think a user unfamiliar with the inner workings of ln would have
expected "I am sam/target" from both cat's.

 

                               - Steven Sittser