bug#9896: acknowledged by developer (Re: bug#9896: ln man page ambiguity)

[Jim Meyering]

Paul Eggert wrote:
> On 11/20/11 12:26, Jim Meyering wrote:
>> ln is particularly confusing,
>
> You can say that again!  I found Michael's comment helpful, even if we
> can't satisfy every part of his request due to the need to make man
> pages brief reference manuals rather than longwinded tutorials.
>
> I suggest the following further changes, which follow his suggestions
> (1) to remove the use of the never-defined term "references", and (2)
> to define "destination" and use that definition systematically (we
> weren't doing that for -n).

Thanks!
However, ...

> diff --git a/src/ln.c b/src/ln.c
> index 88737ed..9f09933 100644
> --- a/src/ln.c
> +++ b/src/ln.c
> @@ -345,6 +345,7 @@ 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\
> +By default, destinations (locations of new links) should not already 
> exist.\n\

"location" might be construed to mean "directory in which it's created".
What do you think of this?

  By default, each destination (name of new link) should not already 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\
> @@ -363,9 +364,9 @@ Mandatory arguments to long options are mandatory for 
> short options too.\n\
>  "), stdout);
>        fputs (_("\
>    -i, --interactive           prompt whether to remove destinations\n\
> -  -L, --logical               make hard links to symbolic link references\n\
> -  -n, --no-dereference        treat destination that is a symlink to a\n\
> -                                directory as if it were a normal file\n\
> +  -L, --logical               dereference TARGETs that are symbolic links\n\
> +  -n, --no-dereference        treat LINK_NAME as a normal file if\n\
> +                                it is a symbolic link to a directory\n\

While I like using terms from Usage, using LINK_NAME here
might make readers think that it applies only to the 1st form:

Usage: ln [OPTION]... [-T] TARGET LINK_NAME   (1st form)
  or:  ln [OPTION]... TARGET                  (2nd form)
  or:  ln [OPTION]... TARGET... DIRECTORY     (3rd form)
  or:  ln [OPTION]... -t DIRECTORY TARGET...  (4th form)

since the others don't explicitly list "LINK_NAME".
Now that you've defined "destination", maybe it's better to use that?

>    -P, --physical              make hard links directly to symbolic links\n\
>    -s, --symbolic              make symbolic links instead of hard links\n\
>  "), stdout);
> @@ -373,7 +374,7 @@ Mandatory arguments to long options are mandatory for 
> short options too.\n\
>    -S, --suffix=SUFFIX         override the usual backup suffix\n\
>    -t, --target-directory=DIRECTORY  specify the DIRECTORY in which to 
> create\n\
>                                  the links\n\
> -  -T, --no-target-directory   treat LINK_NAME as a normal file\n\
> +  -T, --no-target-directory   treat LINK_NAME as a normal file always\n\
>    -v, --verbose               print name of each linked file\n\
>  "), stdout);
>        fputs (HELP_OPTION_DESCRIPTION, stdout);