From unknown Fri Jun 20 20:09:09 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#9896 <9896@debbugs.gnu.org> To: bug#9896 <9896@debbugs.gnu.org> Subject: Status: ln man page ambiguity Reply-To: bug#9896 <9896@debbugs.gnu.org> Date: Sat, 21 Jun 2025 03:09:09 +0000 retitle 9896 ln man page ambiguity reassign 9896 coreutils submitter 9896 Michael J Daniel severity 9896 normal tag 9896 notabug thanks From debbugs-submit-bounces@debbugs.gnu.org Fri Oct 28 12:07:20 2011 Received: (at submit) by debbugs.gnu.org; 28 Oct 2011 16:07:20 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RJoxj-0004C4-7U for submit@debbugs.gnu.org; Fri, 28 Oct 2011 12:07:20 -0400 Received: from eggs.gnu.org ([140.186.70.92]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RJlbM-0007Tx-UO for submit@debbugs.gnu.org; Fri, 28 Oct 2011 08:32:03 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1RJlZW-0004K4-2M for submit@debbugs.gnu.org; Fri, 28 Oct 2011 08:30:06 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-2.4 required=5.0 tests=BAYES_00,FREEMAIL_FROM, RCVD_IN_DNSWL_NONE,RP_MATCHES_RCVD,T_TO_NO_BRKTS_FREEMAIL autolearn=unavailable version=3.3.1 Received: from lists.gnu.org ([140.186.70.17]:57276) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJlZW-0004K0-0e for submit@debbugs.gnu.org; Fri, 28 Oct 2011 08:30:06 -0400 Received: from eggs.gnu.org ([140.186.70.92]:36596) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJlZU-0005oa-TP for bug-coreutils@gnu.org; Fri, 28 Oct 2011 08:30:05 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1RJlZP-0004Fi-5s for bug-coreutils@gnu.org; Fri, 28 Oct 2011 08:30:04 -0400 Received: from qmta15.emeryville.ca.mail.comcast.net ([76.96.27.228]:53156) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RJlZP-0004FV-02 for bug-coreutils@gnu.org; Fri, 28 Oct 2011 08:29:59 -0400 Received: from omta12.emeryville.ca.mail.comcast.net ([76.96.30.44]) by qmta15.emeryville.ca.mail.comcast.net with comcast id qCQw1h0010x6nqcAFCVqv2; Fri, 28 Oct 2011 12:29:50 +0000 Received: from [192.168.1.3] ([76.121.26.98]) by omta12.emeryville.ca.mail.comcast.net with comcast id qCW01h00A26zv2c8YCW1hd; Fri, 28 Oct 2011 12:30:01 +0000 Message-ID: <4EAAA043.3020305@comcast.net> Date: Fri, 28 Oct 2011 05:29:55 -0700 From: Michael J Daniel User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9.2.23) Gecko/20110922 Lightning/1.0b2 Thunderbird/3.1.15 MIME-Version: 1.0 To: bug-coreutils@gnu.org Subject: ln man page ambiguity Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-Received-From: 140.186.70.17 X-Spam-Score: -5.9 (-----) X-Debbugs-Envelope-To: submit X-Mailman-Approved-At: Fri, 28 Oct 2011 12:07:18 -0400 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -5.9 (-----) 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. From debbugs-submit-bounces@debbugs.gnu.org Sat Nov 19 10:49:00 2011 Received: (at 9896) by debbugs.gnu.org; 19 Nov 2011 15:49:00 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RRnA4-00007g-2M for submit@debbugs.gnu.org; Sat, 19 Nov 2011 10:49:00 -0500 Received: from mx.meyering.net ([88.168.87.75]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RRnA0-00007U-Bw; Sat, 19 Nov 2011 10:48:57 -0500 Received: from rho.meyering.net (localhost.localdomain [127.0.0.1]) by rho.meyering.net (Acme Bit-Twister) with ESMTP id A0A25600D7; Sat, 19 Nov 2011 16:47:52 +0100 (CET) From: Jim Meyering To: Michael J Daniel Subject: Re: bug#9896: ln man page ambiguity In-Reply-To: <4EAAA043.3020305@comcast.net> (Michael J. Daniel's message of "Fri, 28 Oct 2011 05:29:55 -0700") References: <4EAAA043.3020305@comcast.net> Date: Sat, 19 Nov 2011 16:47:52 +0100 Message-ID: <87ipmgjeqf.fsf@rho.meyering.net> Lines: 50 MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -2.7 (--) X-Debbugs-Envelope-To: 9896 Cc: 9896@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.7 (--) 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. From debbugs-submit-bounces@debbugs.gnu.org Sun Nov 20 15:04:15 2011 Received: (at 9896) by debbugs.gnu.org; 20 Nov 2011 20:04:15 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RSDcd-0003QL-2E for submit@debbugs.gnu.org; Sun, 20 Nov 2011 15:04:15 -0500 Received: from qmta11.emeryville.ca.mail.comcast.net ([76.96.27.211]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RSDca-0003Q0-92 for 9896@debbugs.gnu.org; Sun, 20 Nov 2011 15:04:13 -0500 Received: from omta15.emeryville.ca.mail.comcast.net ([76.96.30.71]) by qmta11.emeryville.ca.mail.comcast.net with comcast id zXjT1h0031Y3wxoABY2uca; Sun, 20 Nov 2011 20:02:54 +0000 Received: from [192.168.1.3] ([76.121.26.98]) by omta15.emeryville.ca.mail.comcast.net with comcast id zYDH1h00V26zv2c8bYDJBd; Sun, 20 Nov 2011 20:13:18 +0000 Message-ID: <4EC95CF4.5040200@comcast.net> Date: Sun, 20 Nov 2011 12:03:00 -0800 From: Michael J Daniel User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9.2.23) Gecko/20110922 Lightning/1.0b2 Thunderbird/3.1.15 MIME-Version: 1.0 To: 9896@debbugs.gnu.org, jim@meyering.net Subject: Re: bug#9896 acknowledged by developer (Re: bug#9896: ln man page ambiguity) References: <87ipmgjeqf.fsf@rho.meyering.net> <4EAAA043.3020305@comcast.net> In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-Spam-Score: -4.3 (----) X-Debbugs-Envelope-To: 9896 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -3.7 (---) 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@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. From debbugs-submit-bounces@debbugs.gnu.org Sun Nov 20 15:27:41 2011 Received: (at 9896) by debbugs.gnu.org; 20 Nov 2011 20:27:41 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RSDzJ-000400-DM for submit@debbugs.gnu.org; Sun, 20 Nov 2011 15:27:41 -0500 Received: from mx.meyering.net ([88.168.87.75]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RSDzF-0003zo-Qq for 9896@debbugs.gnu.org; Sun, 20 Nov 2011 15:27:40 -0500 Received: from rho.meyering.net (localhost.localdomain [127.0.0.1]) by rho.meyering.net (Acme Bit-Twister) with ESMTP id 8E8556004E; Sun, 20 Nov 2011 21:26:26 +0100 (CET) From: Jim Meyering To: Michael J Daniel Subject: Re: bug#9896: acknowledged by developer (Re: bug#9896: ln man page ambiguity) In-Reply-To: <4EC95CF4.5040200@comcast.net> (Michael J. Daniel's message of "Sun, 20 Nov 2011 12:03:00 -0800") References: <87ipmgjeqf.fsf@rho.meyering.net> <4EAAA043.3020305@comcast.net> <4EC95CF4.5040200@comcast.net> Date: Sun, 20 Nov 2011 21:26:26 +0100 Message-ID: <87ehx2ee19.fsf@rho.meyering.net> Lines: 73 MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -2.7 (--) X-Debbugs-Envelope-To: 9896 Cc: 9896@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.7 (--) 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@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 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 From debbugs-submit-bounces@debbugs.gnu.org Sun Nov 20 15:40:13 2011 Received: (at 9896) by debbugs.gnu.org; 20 Nov 2011 20:40:13 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RSEBR-00050c-83 for submit@debbugs.gnu.org; Sun, 20 Nov 2011 15:40:13 -0500 Received: from joseki.proulx.com ([216.17.153.58]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RSEBO-00050R-NR for 9896@debbugs.gnu.org; Sun, 20 Nov 2011 15:40:12 -0500 Received: from hysteria.proulx.com (hysteria.proulx.com [192.168.230.119]) by joseki.proulx.com (Postfix) with ESMTP id F137F211D1; Sun, 20 Nov 2011 13:38:59 -0700 (MST) Received: by hysteria.proulx.com (Postfix, from userid 1000) id A987F2DCC5; Sun, 20 Nov 2011 13:38:59 -0700 (MST) Date: Sun, 20 Nov 2011 13:38:59 -0700 From: Bob Proulx To: Michael J Daniel Subject: Re: bug#9896: acknowledged by developer (Re: bug#9896: ln man page ambiguity) Message-ID: <20111120203859.GA7567@hysteria.proulx.com> References: <87ipmgjeqf.fsf@rho.meyering.net> <4EAAA043.3020305@comcast.net> <4EC95CF4.5040200@comcast.net> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <4EC95CF4.5040200@comcast.net> User-Agent: Mutt/1.5.21 (2010-09-15) X-Spam-Score: -2.5 (--) X-Debbugs-Envelope-To: 9896 Cc: 9896@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.5 (--) 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@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 From debbugs-submit-bounces@debbugs.gnu.org Sun Nov 20 17:50:46 2011 Received: (at 9896) by debbugs.gnu.org; 20 Nov 2011 22:50:46 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RSGDm-00083X-Ih for submit@debbugs.gnu.org; Sun, 20 Nov 2011 17:50:46 -0500 Received: from smtp.cs.ucla.edu ([131.179.128.62]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RSGDj-00083O-Me for 9896@debbugs.gnu.org; Sun, 20 Nov 2011 17:50:45 -0500 Received: from localhost (localhost.localdomain [127.0.0.1]) by smtp.cs.ucla.edu (Postfix) with ESMTP id 6F4CCA60002; Sun, 20 Nov 2011 14:49:32 -0800 (PST) X-Virus-Scanned: amavisd-new at smtp.cs.ucla.edu Received: from smtp.cs.ucla.edu ([127.0.0.1]) by localhost (smtp.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id c4Dm227tE++8; Sun, 20 Nov 2011 14:49:32 -0800 (PST) Received: from [192.168.1.10] (pool-71-189-109-235.lsanca.fios.verizon.net [71.189.109.235]) by smtp.cs.ucla.edu (Postfix) with ESMTPSA id E3FA439E8006; Sun, 20 Nov 2011 14:49:31 -0800 (PST) Message-ID: <4EC98404.3050307@cs.ucla.edu> Date: Sun, 20 Nov 2011 14:49:40 -0800 From: Paul Eggert Organization: UCLA Computer Science Department User-Agent: Mozilla/5.0 (X11; Linux i686; rv:7.0.1) Gecko/20110929 Thunderbird/7.0.1 MIME-Version: 1.0 To: Jim Meyering Subject: Re: bug#9896: acknowledged by developer (Re: bug#9896: ln man page ambiguity) References: <87ipmgjeqf.fsf@rho.meyering.net> <4EAAA043.3020305@comcast.net> <4EC95CF4.5040200@comcast.net> <87ehx2ee19.fsf@rho.meyering.net> In-Reply-To: <87ehx2ee19.fsf@rho.meyering.net> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit X-Spam-Score: -2.9 (--) X-Debbugs-Envelope-To: 9896 Cc: 9896@debbugs.gnu.org, Michael J Daniel X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.9 (--) 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); From debbugs-submit-bounces@debbugs.gnu.org Sun Nov 20 18:11:38 2011 Received: (at 9896) by debbugs.gnu.org; 20 Nov 2011 23:11:38 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RSGXy-00005A-BF for submit@debbugs.gnu.org; Sun, 20 Nov 2011 18:11:38 -0500 Received: from mx.meyering.net ([88.168.87.75]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RSGXv-000053-Td for 9896@debbugs.gnu.org; Sun, 20 Nov 2011 18:11:37 -0500 Received: from rho.meyering.net (localhost.localdomain [127.0.0.1]) by rho.meyering.net (Acme Bit-Twister) with ESMTP id A41456004E; Mon, 21 Nov 2011 00:10:24 +0100 (CET) From: Jim Meyering To: Paul Eggert Subject: Re: bug#9896: acknowledged by developer (Re: bug#9896: ln man page ambiguity) In-Reply-To: <4EC98404.3050307@cs.ucla.edu> (Paul Eggert's message of "Sun, 20 Nov 2011 14:49:40 -0800") References: <87ipmgjeqf.fsf@rho.meyering.net> <4EAAA043.3020305@comcast.net> <4EC95CF4.5040200@comcast.net> <87ehx2ee19.fsf@rho.meyering.net> <4EC98404.3050307@cs.ucla.edu> Date: Mon, 21 Nov 2011 00:10:24 +0100 Message-ID: <87wraue6fz.fsf@rho.meyering.net> Lines: 68 MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -2.7 (--) X-Debbugs-Envelope-To: 9896 Cc: 9896@debbugs.gnu.org, Michael J Daniel X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.7 (--) 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); From debbugs-submit-bounces@debbugs.gnu.org Sun Nov 20 18:23:07 2011 Received: (at 9896) by debbugs.gnu.org; 20 Nov 2011 23:23:07 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RSGj5-0000MO-8H for submit@debbugs.gnu.org; Sun, 20 Nov 2011 18:23:07 -0500 Received: from smtp.cs.ucla.edu ([131.179.128.62]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RSGj1-0000ME-Qq for 9896@debbugs.gnu.org; Sun, 20 Nov 2011 18:23:05 -0500 Received: from localhost (localhost.localdomain [127.0.0.1]) by smtp.cs.ucla.edu (Postfix) with ESMTP id 68153A60002; Sun, 20 Nov 2011 15:21:52 -0800 (PST) X-Virus-Scanned: amavisd-new at smtp.cs.ucla.edu Received: from smtp.cs.ucla.edu ([127.0.0.1]) by localhost (smtp.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id ReqMKj1Giicg; Sun, 20 Nov 2011 15:21:52 -0800 (PST) Received: from [192.168.1.10] (pool-71-189-109-235.lsanca.fios.verizon.net [71.189.109.235]) by smtp.cs.ucla.edu (Postfix) with ESMTPSA id 0D87739E8006; Sun, 20 Nov 2011 15:21:52 -0800 (PST) Message-ID: <4EC98B98.3080101@cs.ucla.edu> Date: Sun, 20 Nov 2011 15:22:00 -0800 From: Paul Eggert Organization: UCLA Computer Science Department User-Agent: Mozilla/5.0 (X11; Linux i686; rv:7.0.1) Gecko/20110929 Thunderbird/7.0.1 MIME-Version: 1.0 To: Jim Meyering Subject: Re: bug#9896: acknowledged by developer (Re: bug#9896: ln man page ambiguity) References: <87ipmgjeqf.fsf@rho.meyering.net> <4EAAA043.3020305@comcast.net> <4EC95CF4.5040200@comcast.net> <87ehx2ee19.fsf@rho.meyering.net> <4EC98404.3050307@cs.ucla.edu> <87wraue6fz.fsf@rho.meyering.net> In-Reply-To: <87wraue6fz.fsf@rho.meyering.net> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit X-Spam-Score: -2.9 (--) X-Debbugs-Envelope-To: 9896 Cc: 9896@debbugs.gnu.org, Michael J Daniel X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.9 (--) 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. From debbugs-submit-bounces@debbugs.gnu.org Mon Nov 21 02:31:16 2011 Received: (at 9896) by debbugs.gnu.org; 21 Nov 2011 07:31:16 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RSOLT-0003ya-7a for submit@debbugs.gnu.org; Mon, 21 Nov 2011 02:31:15 -0500 Received: from mx.meyering.net ([88.168.87.75]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RSOLQ-0003yR-5F for 9896@debbugs.gnu.org; Mon, 21 Nov 2011 02:31:13 -0500 Received: from rho.meyering.net (localhost.localdomain [127.0.0.1]) by rho.meyering.net (Acme Bit-Twister) with ESMTP id 8B5B960152; Mon, 21 Nov 2011 08:29:58 +0100 (CET) From: Jim Meyering To: Paul Eggert Subject: Re: bug#9896: acknowledged by developer (Re: bug#9896: ln man page ambiguity) In-Reply-To: <4EC98B98.3080101@cs.ucla.edu> (Paul Eggert's message of "Sun, 20 Nov 2011 15:22:00 -0800") References: <87ipmgjeqf.fsf@rho.meyering.net> <4EAAA043.3020305@comcast.net> <4EC95CF4.5040200@comcast.net> <87ehx2ee19.fsf@rho.meyering.net> <4EC98404.3050307@cs.ucla.edu> <87wraue6fz.fsf@rho.meyering.net> <4EC98B98.3080101@cs.ucla.edu> Date: Mon, 21 Nov 2011 08:29:58 +0100 Message-ID: <8762iex79l.fsf@rho.meyering.net> Lines: 25 MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -2.7 (--) X-Debbugs-Envelope-To: 9896 Cc: 9896@debbugs.gnu.org, Michael J Daniel X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.7 (--) 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! From debbugs-submit-bounces@debbugs.gnu.org Mon Nov 21 02:55:11 2011 Received: (at 9896) by debbugs.gnu.org; 21 Nov 2011 07:55:11 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RSOic-0004f2-NU for submit@debbugs.gnu.org; Mon, 21 Nov 2011 02:55:11 -0500 Received: from senmx12-mx.siemens-enterprise.com ([62.134.46.10]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RSOiX-0004es-Mj for 9896@debbugs.gnu.org; Mon, 21 Nov 2011 02:55:06 -0500 Received: from MCHP064A.global-ad.net (unknown [172.29.37.63]) by senmx12-mx.siemens-enterprise.com (Server) with ESMTP id 1FF3323F03FC; Mon, 21 Nov 2011 08:53:52 +0100 (CET) Received: from MCHP058A.global-ad.net ([172.29.37.55]) by MCHP064A.global-ad.net ([172.29.37.63]) with mapi; Mon, 21 Nov 2011 08:53:51 +0100 From: "Voelker, Bernhard" To: Paul Eggert , Jim Meyering Date: Mon, 21 Nov 2011 08:53:51 +0100 Subject: RE: bug#9896: acknowledged by developer (Re: bug#9896: ln man page ambiguity) Thread-Topic: bug#9896: acknowledged by developer (Re: bug#9896: ln man page ambiguity) Thread-Index: Acyn1uIsB8otwZfSRpOKvum8n1+H6gASyQQw Message-ID: <7856072A9D04C24B82DFE2B1112FE38A0D86E9685B@MCHP058A.global-ad.net> References: <87ipmgjeqf.fsf@rho.meyering.net> <4EAAA043.3020305@comcast.net> <4EC95CF4.5040200@comcast.net> <87ehx2ee19.fsf@rho.meyering.net> <4EC98404.3050307@cs.ucla.edu> In-Reply-To: <4EC98404.3050307@cs.ucla.edu> Accept-Language: de-DE, en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: acceptlanguage: de-DE, en-US Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Spam-Score: -3.2 (---) X-Debbugs-Envelope-To: 9896 Cc: "9896@debbugs.gnu.org" <9896@debbugs.gnu.org>, Michael J Daniel X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -3.2 (---) =20 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 From debbugs-submit-bounces@debbugs.gnu.org Mon Dec 05 17:48:00 2011 Received: (at 9896) by debbugs.gnu.org; 5 Dec 2011 22:48:00 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RXhKK-0004RK-0s for submit@debbugs.gnu.org; Mon, 05 Dec 2011 17:48:00 -0500 Received: from smtp.cs.ucla.edu ([131.179.128.62]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RXhKH-0004R2-AR for 9896@debbugs.gnu.org; Mon, 05 Dec 2011 17:47:58 -0500 Received: from localhost (localhost.localdomain [127.0.0.1]) by smtp.cs.ucla.edu (Postfix) with ESMTP id E7B7C39E8008; Mon, 5 Dec 2011 14:47:21 -0800 (PST) X-Virus-Scanned: amavisd-new at smtp.cs.ucla.edu Received: from smtp.cs.ucla.edu ([127.0.0.1]) by localhost (smtp.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id U13CpcfB8pJR; Mon, 5 Dec 2011 14:47:21 -0800 (PST) Received: from penguin.cs.ucla.edu (Penguin.CS.UCLA.EDU [131.179.64.200]) by smtp.cs.ucla.edu (Postfix) with ESMTPSA id 8D5C939E8006; Mon, 5 Dec 2011 14:47:21 -0800 (PST) Message-ID: <4EDD49F9.2020004@cs.ucla.edu> Date: Mon, 05 Dec 2011 14:47:21 -0800 From: Paul Eggert Organization: UCLA Computer Science Department User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:8.0) Gecko/20111115 Thunderbird/8.0 MIME-Version: 1.0 To: "Voelker, Bernhard" Subject: Re: bug#9896: acknowledged by developer (Re: bug#9896: ln man page ambiguity) References: <87ipmgjeqf.fsf@rho.meyering.net> <4EAAA043.3020305@comcast.net> <4EC95CF4.5040200@comcast.net> <87ehx2ee19.fsf@rho.meyering.net> <4EC98404.3050307@cs.ucla.edu> <7856072A9D04C24B82DFE2B1112FE38A0D86E9685B@MCHP058A.global-ad.net> In-Reply-To: <7856072A9D04C24B82DFE2B1112FE38A0D86E9685B@MCHP058A.global-ad.net> Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit X-Spam-Score: -3.0 (---) X-Debbugs-Envelope-To: 9896 Cc: "9896@debbugs.gnu.org" <9896@debbugs.gnu.org>, Jim Meyering , Michael J Daniel X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -3.0 (---) 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. From unknown Fri Jun 20 20:09:09 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Tue, 03 Jan 2012 12:24:04 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator