From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs Subject: bug#13801: [PATCH] Trivial fix for files.el Date: Sun, 24 Feb 2013 09:47:44 -0800 Message-ID: <6EA8FD3B20FB44C289A386DEA3E477D9@us.oracle.com> References: <20130224143332.f33f9e158da879bd206e83cc@gmail.com> <83mwutkayo.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1361728118 27982 80.91.229.3 (24 Feb 2013 17:48:38 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 24 Feb 2013 17:48:38 +0000 (UTC) Cc: 13801@debbugs.gnu.org To: "'Eli Zaretskii'" , "'Xue Fuqiao'" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Feb 24 18:49:00 2013 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1U9fh1-0004IM-4z for geb-bug-gnu-emacs@m.gmane.org; Sun, 24 Feb 2013 18:48:55 +0100 Original-Received: from localhost ([::1]:43539 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1U9fgg-0004F1-Eb for geb-bug-gnu-emacs@m.gmane.org; Sun, 24 Feb 2013 12:48:34 -0500 Original-Received: from eggs.gnu.org ([208.118.235.92]:40543) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1U9fgc-0004Ee-Gw for bug-gnu-emacs@gnu.org; Sun, 24 Feb 2013 12:48:32 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1U9fga-0007Is-5c for bug-gnu-emacs@gnu.org; Sun, 24 Feb 2013 12:48:30 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:42364) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1U9fga-0007Il-0B for bug-gnu-emacs@gnu.org; Sun, 24 Feb 2013 12:48:28 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.72) (envelope-from ) id 1U9fi6-00014Q-3W for bug-gnu-emacs@gnu.org; Sun, 24 Feb 2013 12:50:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 24 Feb 2013 17:50:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 13801 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 13801-submit@debbugs.gnu.org id=B13801.13617281744076 (code B ref 13801); Sun, 24 Feb 2013 17:50:02 +0000 Original-Received: (at 13801) by debbugs.gnu.org; 24 Feb 2013 17:49:34 +0000 Original-Received: from localhost ([127.0.0.1]:47828 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1U9fhd-00013g-LM for submit@debbugs.gnu.org; Sun, 24 Feb 2013 12:49:33 -0500 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:21985) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1U9fha-00013Y-5m for 13801@debbugs.gnu.org; Sun, 24 Feb 2013 12:49:31 -0500 Original-Received: from ucsinet22.oracle.com (ucsinet22.oracle.com [156.151.31.94]) by aserp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id r1OHlrrD000471 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sun, 24 Feb 2013 17:47:54 GMT Original-Received: from acsmt356.oracle.com (acsmt356.oracle.com [141.146.40.156]) by ucsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r1OHlqeC022518 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Sun, 24 Feb 2013 17:47:53 GMT Original-Received: from abhmt111.oracle.com (abhmt111.oracle.com [141.146.116.63]) by acsmt356.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id r1OHlqHO024158; Sun, 24 Feb 2013 11:47:52 -0600 Original-Received: from dradamslap1 (/71.202.147.44) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sun, 24 Feb 2013 09:47:52 -0800 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <83mwutkayo.fsf@gnu.org> Thread-Index: Ac4SoNDzA49yIz9JTF+MZNzrH1iKzAAEn0eA X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157 X-Source-IP: ucsinet22.oracle.com [156.151.31.94] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:71751 Archived-At: > The first line of the doc string should concisely say what > the option does. Correct. Including, if possible, what a nil or non-nil value does, if the option is Boolean. And the first line should (must) be a full sentence. > The old doc string did it, albeit not perfectly; Incorrect. The first line did not do that at all. At all. > the one you suggest does not. Correct. My guess is that it was an attempt to provide a short full sentence (good), but it does not say what the option does (not good). What is important in both the old and new doc strings, and can serve as the first line, is that the option does this (77 chars): "Non-nil means break a hard link for the visited file and write to a new file." If you feel that 77 chars is too much, you can drop "a" before "hard link" or "the" before "visited file". The rest of the doc string can clarify things further (e.g., mentioning `buffer-file-name'). Whatever the wording chosen, the point is that non-nil means Emacs writes a new file, bypassing any hard link for `buffer-file-name'. In fact, I'm not sure about "break" here. Is the effect that the hard link no longer exists, or simply that it is ignored by Emacs when saving? Depending on the answer, the doc might need to be tweaked a little more. The old first line was not even a complete sentence. And the old first sentence was four lines! And unless I'm mistaken, the old first sentence was incorrect or at least misleading regarding the condition where the option applies: "has multiple hardlinks". I think the correct criterion is simply having a hard link for the visited file (`buffer-file-name'), regardless of whether there are any other hard links, i.e., not necessarily multiple such. It is not easy to write a short summary sentence, especially when English is not your maternal language. This is a welcome initiative from Fuqiao. He clearly takes an interest in the doc (as do Eli and Drew), and that is a fairly rare resource. Thank you.