Bug 44074

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) Lots of readers aren't familiar with its use of "target".

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" argument naming.

3) Code within the "ln" program itself calls the other argument the
"target".  I say this only to provide some evidence for the manual's
confused naming.

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.

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 "apropos" string in the "Name" section doesn't contain the
terms "symbolic", "soft", "hard", and those followed by "link",
which are likely to be searched for by apropos(1) users.

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

9) Soft links are much more commonly called that than the only term used
by the manual, "symbolic links".  The use of "soft links" is better, not
only because it recognizes the more common usage, but becase it is two
fewer syllables and is a more natural antonym for "hard links".  It
probably also makes more sense to most people as soft links seem softer
than hard links, but no more symbolic than hard links.

================

Fix: 1) The names of the soft link 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".

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

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 belongs.

2) The names of the hard link command arguments are augmented to
emphasize two things to aid the memory: A) the file named by the first
argument must pre-exist.  B) The command is not really creating
something called a link which sounds like somthing different that the
pre-existing file, but is just creating an alternate name (directory
entry) for the file named by the first arg.

  link to_existing_filename from_alternate_filename

That is "link to existing file from alternate file".

3) The new synopsis looks like this:

    ln [-fhinsv] to_filename [from_filename]
    ln [-fhinsv] to_filename ... dir_filename
    link to_existing_filename from_alternate_filename

Note that "filename" in the synopses could be "file" to make them read
even better, but it is better that the arguments retain their essential
descriptive power as names of filenames; they are not names of files.

This is partly because the objects being manipulated are directory
"filename" entries, not files which may or may not exist; in fact, the
filenames for files and links may contain arbritrary strings (like
directory entries created by touch(1)) and never name files at all.
It's also just generally good practice to name a filename as some kind
of filename and not as some kind of file, which it is not.

4) 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".  Some other
description is touched up to improve clarity.

5) Change "symbolic" to "soft" and add a note about the alternative
terms "symbolic link" and "symlink".

[.\" $FreeBSD: src/bin/ln/ln.1,v 1.11.2.7 2002/08/19 08:14:22 tjr Exp $]
How-To-Repeat: n/a
================