GNU bug report logs - #9896
ln man page ambiguity

Previous Next

Full log

View this message in rfc822 format

From: Jim Meyering <jim <at> meyering.net>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 9896 <at> debbugs.gnu.org, Michael J Daniel <michael.j.daniel <at> comcast.net>
Subject: bug#9896: acknowledged by developer (Re: bug#9896: ln man page ambiguity)
Date: Mon, 21 Nov 2011 00:10:24 +0100

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);

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.