GNU bug report logs - #9896
ln man page ambiguity

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 9896 in the body.
You can then email your comments to 9896 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Michael J Daniel <michael.j.daniel <at> comcast.net>
To: bug-coreutils <at> gnu.org
Subject: ln man page ambiguity
Date: Fri, 28 Oct 2011 05:29:55 -0700

This bug is on the ln man page.

The ln man page uses the terms, "link", "target", "source", 
"destination", and "references"

For those of us who are not already experts on the use of ln,
the terms are ambiguous.
Does "source" mean "link" or "target"?
When is the man page talking about ln command line parameters,
and when is it talking about using links in other command lines?
Is a "reference" and target?

Please rewrite the page and remove all uses of "source", "destination", 
and "references".
If not, please clearly define, in the man page, "source" and 
"destination", and define
1) their relationship to the ln command line parameters,
2) use of file names in other command lines, and
3) "link" and "target".

I'd do it, if I were an expert on the use of ln.
But there's got to be an expert on the use of ln somewhere in gnu.org


thanks,
michael

PS) Let's not make this harder than it needs to be.

Message #8 received at 9896 <at> debbugs.gnu.org (full text, mbox):

From: Jim Meyering <jim <at> meyering.net>
To: Michael J Daniel <michael.j.daniel <at> comcast.net>
Cc: 9896 <at> debbugs.gnu.org
Subject: Re: bug#9896: ln man page ambiguity
Date: Sat, 19 Nov 2011 16:47:52 +0100

tags 9896 + notabug
close 9896
thanks

Michael J Daniel wrote:
> This bug is on the ln man page.
>
> The ln man page uses the terms, "link", "target", "source",
> "destination", and "references"
>
> For those of us who are not already experts on the use of ln,
> the terms are ambiguous.
> Does "source" mean "link" or "target"?
> When is the man page talking about ln command line parameters,
> and when is it talking about using links in other command lines?
> Is a "reference" and target?
>
> Please rewrite the page and remove all uses of "source",
> "destination", and "references".
> If not, please clearly define, in the man page, "source" and
> "destination", and define
> 1) their relationship to the ln command line parameters,
> 2) use of file names in other command lines, and
> 3) "link" and "target".
>
> I'd do it, if I were an expert on the use of ln.
> But there's got to be an expert on the use of ln somewhere in gnu.org

Thanks for the feedback.
The man page is generated from --help, which is intended to be a quick
reference, not the definitive description.  For the "full documentation"
see the note at the end of "man ln" output:

     The  full  documentation  for ln is maintained as a Texinfo manual.  If
     the info and ln programs are properly installed at your site, the  com-
     mand

            info coreutils 'ln invocation'

     should give you access to the complete manual.

If the full documentation is inadequate, please let us know,
preferably with precise suggestions for improvement.

If you see a way to improve the short --help output and/or
the man page, specific suggestions are most welcome, but do
bear in mind that we try to keep those brief and to the point.

I'm marking this "issue" as not-a-bug and closing it,
but you're welcome to reply here or to start a new thread.

Message #15 received at 9896 <at> debbugs.gnu.org (full text, mbox):

From: Michael J Daniel <michael.j.daniel <at> comcast.net>
To: 9896 <at> debbugs.gnu.org, jim <at> meyering.net
Subject: Re: bug#9896 acknowledged by developer         (Re: bug#9896: ln
	man page ambiguity)
Date: Sun, 20 Nov 2011 12:03:00 -0800

On 11/19/2011 07:49 AM, GNU bug Tracking System wrote:
> This is an automatic notification regarding your bug report
> #9896: ln man page ambiguity,
> which was filed against the coreutils package.
>
> Thank you for your report, which has now been closed.
> You can view the full report at
> http://debbugs.gnu.org/cgi/bugreport.cgi?bug=9896
>
> If you require further information, please followup to 9896 <at> debbugs.gnu.org.
>
> debbugs.gnu.org maintainers
> (administrator, GNU bugs database)
>
>
Wow,

I went to a great deal of trouble to try and help GNU.
Only to be mindlessly and flippantly dismissed.
This is the last help GNU.org will receive from me.

Message #18 received at 9896 <at> debbugs.gnu.org (full text, mbox):

From: Jim Meyering <jim <at> meyering.net>
To: Michael J Daniel <michael.j.daniel <at> comcast.net>
Cc: 9896 <at> debbugs.gnu.org
Subject: Re: bug#9896: acknowledged by developer (Re: bug#9896: ln man page
	ambiguity)
Date: Sun, 20 Nov 2011 21:26:26 +0100

Michael J Daniel wrote:
> On 11/19/2011 07:49 AM, GNU bug Tracking System wrote:
>> This is an automatic notification regarding your bug report
>> #9896: ln man page ambiguity,
>> which was filed against the coreutils package.
>>
>> Thank you for your report, which has now been closed.
>> You can view the full report at
>> http://debbugs.gnu.org/cgi/bugreport.cgi?bug=9896
>>
>> If you require further information, please followup to 9896 <at> debbugs.gnu.org.
>>
>> debbugs.gnu.org maintainers
>> (administrator, GNU bugs database)
>>
>>
> Wow,
>
> I went to a great deal of trouble to try and help GNU.
> Only to be mindlessly and flippantly dismissed.
> This is the last help GNU.org will receive from me.

Sorry it came across that way.
We get far too many complaints about how --help/man
are inadequate, often from people who didn't even notice
that there is much more complete documentation available.

However, I was a bit hasty in closing this.

My point is that if something is unclear, the man page
is not the best place to look for explanation.
For that, please use the full documentation.
As I mentioned, we try to keep the --help output concise.
That means that there usually isn't a desire to define
every term we use.  Rather we try to choose terms whose
meaning is clear enough.  But ln is particularly confusing,
so rather than trying to clarify by expanding the --help/man page
I would much prefer to address any problems you find in the full
documentation.

The term "destination" is used also in the cp man page.
Do you think it requires definition there, too?

Rereading your report, I see you mentioned "source",
and at least that is easy to fix.  I've replaced the sole use
with TARGET in the change below:

From 39ed1b168eb7d44f8df3b0d581a8b68f92291621 Mon Sep 17 00:00:00 2001
From: Jim Meyering <meyering <at> redhat.com>
Date: Sun, 20 Nov 2011 21:18:53 +0100
Subject: [PATCH] doc: clarify ln's --help output

* src/ln.c (usage): Use TARGET, not "source" in description.
Reported by Michael J Daniel in http://bugs.gnu.org/9896.
---
 src/ln.c |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/src/ln.c b/src/ln.c
index 88737ed..90b6e59 100644
--- a/src/ln.c
+++ b/src/ln.c
@@ -394,7 +394,7 @@ the VERSION_CONTROL environment variable.  Here are the values:\n\
 "), stdout);
       printf (_("\
 Using -s ignores -L and -P.  Otherwise, the last option specified controls\n\
-behavior when the source is a symbolic link, defaulting to %s.\n\
+behavior when a TARGET is a symbolic link, defaulting to %s.\n\
 "), LINK_FOLLOWS_SYMLINKS ? "-L" : "-P");
       emit_ancillary_info ();
     }
--
1.7.8.rc2.3.g0911

Message #21 received at 9896 <at> debbugs.gnu.org (full text, mbox):

From: Bob Proulx <bob <at> proulx.com>
To: Michael J Daniel <michael.j.daniel <at> comcast.net>
Cc: 9896 <at> debbugs.gnu.org
Subject: Re: bug#9896: acknowledged by developer (Re: bug#9896: ln man page
	ambiguity)
Date: Sun, 20 Nov 2011 13:38:59 -0700

Michael J Daniel wrote:
> On 11/19/2011 07:49 AM, GNU bug Tracking System wrote:
> >This is an automatic notification regarding your bug report
> >#9896: ln man page ambiguity,
> >which was filed against the coreutils package.
> >
> >Thank you for your report, which has now been closed.
> >You can view the full report at
> >http://debbugs.gnu.org/cgi/bugreport.cgi?bug=9896
> >
> >If you require further information, please followup to 9896 <at> debbugs.gnu.org.
> >
> >debbugs.gnu.org maintainers
> >(administrator, GNU bugs database)
>
> Wow,
> 
> I went to a great deal of trouble to try and help GNU.
> Only to be mindlessly and flippantly dismissed.
> This is the last help GNU.org will receive from me.

I hate that message too.  It always annoys me when I receive it.
Perhaps we can get it changed.  It is derived from the upstream source
of the bug tracking system and is the same there too.  And just as
annoying.

But that isn't the message you should pay attention to!  That is the
automated notification message from the bug tracker concerning the
status of the bug ticket you filed.  It is a ROBOT talking.  That
robot has not yet been programmed with niceties and it is facts,
nothing but facts, straigt up from the start.  It isn't a very
talkative robot.  And being annoyed at the robot is typical.  Please
ignore the robot message.

Instead please pay attention to the message written by the human
person.  Instead read Jim's message concerning your bug report.  It
was thoughtful and addressed your concern.  You should have received
it directly.  Your message here reads as if you have not seen it so
perhaps it had been blocked somehow.  Let me repeat it here then.

Jim Meyering wrote:
> Thanks for the feedback.
> The man page is generated from --help, which is intended to be a quick
> reference, not the definitive description.  For the "full documentation"
> see the note at the end of "man ln" output:
> 
>      The  full  documentation  for ln is maintained as a Texinfo manual.  If
>      the info and ln programs are properly installed at your site, the  com-
>      mand
> 
>             info coreutils 'ln invocation'
> 
>      should give you access to the complete manual.
> 
> If the full documentation is inadequate, please let us know,
> preferably with precise suggestions for improvement.
> 
> If you see a way to improve the short --help output and/or
> the man page, specific suggestions are most welcome, but do
> bear in mind that we try to keep those brief and to the point.
> 
> I'm marking this "issue" as not-a-bug and closing it,
> but you're welcome to reply here or to start a new thread.

And let me also say please do read the info documentation.  It is the
full documentation for the project and is much better at explaining
the behavior of programs than man pages.  Man pages make good quick
reference pages but make terrible tutorials.

For example the traditional Unix filesystem is a complicated beast.
And it has been extended significantly.  There are many commands that
work with files in the filesystem.  It isn't practical nor possible
for every command to explain how the filesystem works in every man
page.  Believe me that would cause a large number of bug reports that
the man pages were too confusing.  Instead the man pages must explain
isolated islands of information and stay on topic concerning their own
topic space.  Anything else quickly becomes unworkable.

But the info documentation isn't limited to the linear flow of the man
page.  The info documentation is hyperlinked and the entire manual
contains many links from section to section as needed to properly
document the system.  That is one of the reasons that many years ago
the info system became the official documentation of the GNU Project.

Bob

Message #24 received at 9896 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Jim Meyering <jim <at> meyering.net>
Cc: 9896 <at> debbugs.gnu.org, Michael J Daniel <michael.j.daniel <at> comcast.net>
Subject: Re: bug#9896: acknowledged by developer (Re: bug#9896: ln man page
	ambiguity)
Date: Sun, 20 Nov 2011 14:49:40 -0800

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

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

Message #27 received at 9896 <at> debbugs.gnu.org (full text, mbox):

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

Message #30 received at 9896 <at> debbugs.gnu.org (full text, mbox):

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

On 11/20/11 15:10, Jim Meyering wrote:
>> +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\

Yes, that's fine.

>> +  -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:

That's the intent.  -n applies only to the first form;
it does not apply to destinations in general.  -n is
like -T in that respect.

Message #33 received at 9896 <at> debbugs.gnu.org (full text, mbox):

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: Re: bug#9896: acknowledged by developer (Re: bug#9896: ln man page
	ambiguity)
Date: Mon, 21 Nov 2011 08:29:58 +0100

Paul Eggert wrote:
> On 11/20/11 15:10, Jim Meyering wrote:
>>> +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\
>
> Yes, that's fine.
>
>>> +  -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:
>
> That's the intent.  -n applies only to the first form;
> it does not apply to destinations in general.  -n is
> like -T in that respect.

That's perfect, then ;-)
You can tell I haven't used -n for too long.

Thanks!

Message #36 received at 9896 <at> debbugs.gnu.org (full text, mbox):

From: "Voelker, Bernhard" <bernhard.voelker <at> siemens-enterprise.com>
To: Paul Eggert <eggert <at> cs.ucla.edu>, Jim Meyering <jim <at> meyering.net>
Cc: "9896 <at> debbugs.gnu.org" <9896 <at> debbugs.gnu.org>,
	Michael J Daniel <michael.j.daniel <at> comcast.net>
Subject: RE: bug#9896: acknowledged by developer (Re: bug#9896: ln man page
	ambiguity)
Date: Mon, 21 Nov 2011 08:53:51 +0100

 
Paul Eggert wrote:
+  -n, --no-dereference        treat LINK_NAME as a normal file if\n\
+                                it is a symbolic link to a directory\n\

IMHO that's wrong.

ln also creates a hardlink of a symlink if that points to a file:

$ touch f
$ ln -s f flink
$ ln -n flink flink-n
$ ls -li
total 0
192387 -rw-r----- 1 ecs ecs 0 2011-11-21 08:50 f
192388 lrwxrwxrwx 2 ecs ecs 1 2011-11-21 08:51 flink -> f
192388 lrwxrwxrwx 2 ecs ecs 1 2011-11-21 08:51 flink-n -> f

Have a nice day,
Berny

Message #39 received at 9896 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: "Voelker, Bernhard" <bernhard.voelker <at> siemens-enterprise.com>
Cc: "9896 <at> debbugs.gnu.org" <9896 <at> debbugs.gnu.org>,
	Jim Meyering <jim <at> meyering.net>,
	Michael J Daniel <michael.j.daniel <at> comcast.net>
Subject: Re: bug#9896: acknowledged by developer (Re: bug#9896: ln man page
	ambiguity)
Date: Mon, 05 Dec 2011 14:47:21 -0800

On 11/20/11 23:53, Voelker, Bernhard wrote:
>  
> Paul Eggert wrote:
> +  -n, --no-dereference        treat LINK_NAME as a normal file if\n\
> +                                it is a symbolic link to a directory\n\
> 
> IMHO that's wrong.
> 
> ln also creates a hardlink of a symlink if that points to a file:
> 
> $ touch f
> $ ln -s f flink
> $ ln -n flink flink-n

You're right about ln's behavior, but the proposed wording is not
incorrect.  In the example, flink-n is not a symbolic link
to a directory, so the documentation says that "ln -n flink flink-n"
should behave like ordinary "ln flink flink-n", which is what happens.
In this respect, the proposed wording is no better or worse than
the current wording.

Perhaps the wording could be further improved.  To get things moving
in the meantime I committed the proposed wording.

Previous Next

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