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#17916: 24.4.50; `write-region' doc for numeric APPEND arg Date: Thu, 3 Jul 2014 10:23:37 -0700 (PDT) Message-ID: References: <> <<83wqbu1jmy.fsf@gnu.org>> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1404408271 20613 80.91.229.3 (3 Jul 2014 17:24:31 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 3 Jul 2014 17:24:31 +0000 (UTC) Cc: 17916@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Jul 03 19:24:25 2014 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 1X2kkB-00082N-QG for geb-bug-gnu-emacs@m.gmane.org; Thu, 03 Jul 2014 19:24:24 +0200 Original-Received: from localhost ([::1]:60998 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1X2kkB-0008Tv-3p for geb-bug-gnu-emacs@m.gmane.org; Thu, 03 Jul 2014 13:24:23 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:39277) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1X2kjz-0008Ss-Ab for bug-gnu-emacs@gnu.org; Thu, 03 Jul 2014 13:24:20 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1X2kjq-00013k-I9 for bug-gnu-emacs@gnu.org; Thu, 03 Jul 2014 13:24:11 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:50770) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1X2kjq-00013b-FS for bug-gnu-emacs@gnu.org; Thu, 03 Jul 2014 13:24:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1X2kjq-0002p5-1f for bug-gnu-emacs@gnu.org; Thu, 03 Jul 2014 13:24:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 03 Jul 2014 17:24:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 17916 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 17916-submit@debbugs.gnu.org id=B17916.140440822910827 (code B ref 17916); Thu, 03 Jul 2014 17:24:01 +0000 Original-Received: (at 17916) by debbugs.gnu.org; 3 Jul 2014 17:23:49 +0000 Original-Received: from localhost ([127.0.0.1]:41920 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1X2kjc-0002oW-Nd for submit@debbugs.gnu.org; Thu, 03 Jul 2014 13:23:49 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:51690) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1X2kja-0002oC-Qp for 17916@debbugs.gnu.org; Thu, 03 Jul 2014 13:23:47 -0400 Original-Received: from acsinet21.oracle.com (acsinet21.oracle.com [141.146.126.237]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id s63HNdpm018799 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Thu, 3 Jul 2014 17:23:40 GMT Original-Received: from aserz7021.oracle.com (aserz7021.oracle.com [141.146.126.230]) by acsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s63HNcJw006452 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Thu, 3 Jul 2014 17:23:39 GMT Original-Received: from abhmp0017.oracle.com (abhmp0017.oracle.com [141.146.116.23]) by aserz7021.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s63HNc7f006448; Thu, 3 Jul 2014 17:23:38 GMT In-Reply-To: <<83wqbu1jmy.fsf@gnu.org>> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6691.5000 (x86)] X-Source-IP: acsinet21.oracle.com [141.146.126.237] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.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:91158 Archived-At: > This assumes not only that the reader knows about 'seek', it also > assumes that she has general knowledge about writing to files: there > is no "inserting" stuff in the middle of a file. When you write, you > always overwrite whatever is there. Isn't that common knowledge? Hard to believe I need to explain this to you, Eli, but I'll try. "Writing to a file" can have several meanings, depending on the level of abstraction. If you situate yourself at the level of what this function actually does, and so understand that it is a low-level, physical write operation, then sure, all is clear. That's the point. Some users will not think in these terms about writing text to a file. They may well think that the existing file text and the text to be added are inserted into a buffer together, with the former being inserted at the given offset into the latter, and then the buffer is written to the file. That too is "writing to a file". Or they may put little thought into _how_ the text is written to the file, beyond what they read here: _that_ (nothing is said about how) the region text is "copied into" the file text at the given position. And as I pointed out, by itself "copied into" is ambiguous. ("Written over" is not so ambiguous.) Friendly suggestion: You need to be capable of seeing what the words can suggest, and not just understanding what you already understand about what the code actually does. That the actual behavior fits the words does not mean that the words fit only that behavior. The former is necessary but not sufficient for general comprehension. To avoid misunderstanding by readers it is enough to do as I suggested: add a few words to say that this is a physical write operation, and as such it overwrites existing file content starting at the given offset. I also made the separate but related point that what `write-region' does is NOT the "inverse of `M-x insert-file'." That statement can only add to the confusion I pointed to. It is NOT as if `insert-file' inserts text from a file into the buffer (true) whereas `write-region' inserts text from the buffer into a file (false). It is misleading to refer to what `write-region' does using "insert" or "into", without further explanation.