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

[Bob Proulx]

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.

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