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

[Jim Meyering]

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 address@hidden
>>
>> 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 <address@hidden>
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