bug#9896: ln man page ambiguity

[Jim Meyering]

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.