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 09:14:07 -0700 (PDT) Message-ID: 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 1404404201 31732 80.91.229.3 (3 Jul 2014 16:16:41 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 3 Jul 2014 16:16:41 +0000 (UTC) To: 17916@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Jul 03 18:16:32 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 1X2jgQ-0001n5-Bu for geb-bug-gnu-emacs@m.gmane.org; Thu, 03 Jul 2014 18:16:26 +0200 Original-Received: from localhost ([::1]:60756 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1X2jgP-0006A3-UC for geb-bug-gnu-emacs@m.gmane.org; Thu, 03 Jul 2014 12:16:25 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:50791) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1X2jgD-00069E-CO for bug-gnu-emacs@gnu.org; Thu, 03 Jul 2014 12:16:23 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1X2jg2-0003yQ-Tc for bug-gnu-emacs@gnu.org; Thu, 03 Jul 2014 12:16:13 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:50723) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1X2jg2-0003yK-PH for bug-gnu-emacs@gnu.org; Thu, 03 Jul 2014 12:16:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1X2jg2-0007XC-Bo for bug-gnu-emacs@gnu.org; Thu, 03 Jul 2014 12:16: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 16:16:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 17916 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.140440410225043 (code B ref -1); Thu, 03 Jul 2014 16:16:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 3 Jul 2014 16:15:02 +0000 Original-Received: from localhost ([127.0.0.1]:41873 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1X2jez-0006Va-DQ for submit@debbugs.gnu.org; Thu, 03 Jul 2014 12:15:01 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:48786) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1X2jet-0006VA-Ot for submit@debbugs.gnu.org; Thu, 03 Jul 2014 12:14:55 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1X2jed-0003Tl-LP for submit@debbugs.gnu.org; Thu, 03 Jul 2014 12:14:46 -0400 Original-Received: from lists.gnu.org ([208.118.235.17]:39504) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1X2jed-0003Th-H1 for submit@debbugs.gnu.org; Thu, 03 Jul 2014 12:14:35 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:50102) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1X2jeQ-0004rK-O9 for bug-gnu-emacs@gnu.org; Thu, 03 Jul 2014 12:14:35 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1X2jeH-0003Hs-Rl for bug-gnu-emacs@gnu.org; Thu, 03 Jul 2014 12:14:22 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:22181) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1X2jeH-0003Hl-K5 for bug-gnu-emacs@gnu.org; Thu, 03 Jul 2014 12:14:13 -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 s63GEC5n006066 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Thu, 3 Jul 2014 16:14:13 GMT Original-Received: from userz7022.oracle.com (userz7022.oracle.com [156.151.31.86]) by acsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s63GEAqq018184 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Thu, 3 Jul 2014 16:14:11 GMT Original-Received: from abhmp0017.oracle.com (abhmp0017.oracle.com [141.146.116.23]) by userz7022.oracle.com (8.14.5+Sun/8.14.4) with ESMTP id s63GE8Fh023970 for ; Thu, 3 Jul 2014 16:14:09 GMT 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-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x 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:91151 Archived-At: The doc for `write-region' could be clearer, in particular wrt a numeric APPEND arg. It could explicitly say that it always _overwrites_ the existing file contents, rather than _inserting_ the region text at the given position. In (emacs) `Misc File Ops', we say: `M-x write-region' is the inverse of `M-x insert-file'; it copies the contents of the region into the specified file. "Copy into" is at best ambiguous here, and "inverse of" is incorrect. We should say explicitly that it overwrites the existing file contents with the region contents. (And that is not the case of `insert-file'.) Similarly, in (elisp) `Writing to Files' we say that it "writes the region ... into the file..." - the same ambiguous phrase. And wrt APPEND we say: If APPEND is a number, `write-region' seeks to that byte offset from the start of the file and writes the data from there. Because of the word "seek", this will be clear to some programmers, but it might not be clear to others. We should make clear that `write-region' overwrites existing bytes in the file; it does not insert the region text at the given position. In sum, make clear that you cannot use `write-region' to insert the region text into the file (except by appending it). In GNU Emacs 24.4.50.1 (i686-pc-mingw32) of 2014-06-28 on ODIEONE Bzr revision: 117431 rgm@gnu.org-20140628015517-eku6hj8mpgcvfnso Windowing system distributor `Microsoft Corp.', version 6.1.7601 Configured using: `configure --prefix=3D/c/Devel/emacs/snapshot/trunk --enable-checking=3Dyes,glyphs 'CFLAGS=3D-O0 -g3' LDFLAGS=3D-Lc:/Devel/emacs/lib 'CPPFLAGS=3D-DGC_MCHECK=3D1 -Ic:/Devel/emacs/include''