From unknown Fri Jun 20 07:26:04 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#17916 <17916@debbugs.gnu.org> To: bug#17916 <17916@debbugs.gnu.org> Subject: Status: 24.4.50; `write-region' doc for numeric APPEND arg Reply-To: bug#17916 <17916@debbugs.gnu.org> Date: Fri, 20 Jun 2025 14:26:04 +0000 retitle 17916 24.4.50; `write-region' doc for numeric APPEND arg reassign 17916 emacs submitter 17916 Drew Adams severity 17916 minor thanks From debbugs-submit-bounces@debbugs.gnu.org Thu Jul 03 12:15:02 2014 Received: (at submit) by debbugs.gnu.org; 3 Jul 2014 16:15:02 +0000 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 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 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 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00 autolearn=disabled version=3.3.2 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 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 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 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 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 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 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 MIME-Version: 1.0 Message-ID: Date: Thu, 3 Jul 2014 09:14:07 -0700 (PDT) From: Drew Adams To: bug-gnu-emacs@gnu.org Subject: 24.4.50; `write-region' doc for numeric APPEND arg X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6691.5000 (x86)] Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable 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-Received-From: 208.118.235.17 X-Spam-Score: -4.0 (----) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -4.0 (----) 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'' From debbugs-submit-bounces@debbugs.gnu.org Thu Jul 03 12:40:24 2014 Received: (at 17916) by debbugs.gnu.org; 3 Jul 2014 16:40:24 +0000 Received: from localhost ([127.0.0.1]:41895 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1X2k3Y-000094-0d for submit@debbugs.gnu.org; Thu, 03 Jul 2014 12:40:23 -0400 Received: from mtaout21.012.net.il ([80.179.55.169]:61728) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1X2k3Q-00008a-DR for 17916@debbugs.gnu.org; Thu, 03 Jul 2014 12:40:16 -0400 Received: from conversion-daemon.a-mtaout21.012.net.il by a-mtaout21.012.net.il (HyperSendmail v2007.08) id <0N8500H009RNTF00@a-mtaout21.012.net.il> for 17916@debbugs.gnu.org; Thu, 03 Jul 2014 19:40:04 +0300 (IDT) Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout21.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0N8500HUNAASOH60@a-mtaout21.012.net.il>; Thu, 03 Jul 2014 19:40:04 +0300 (IDT) Date: Thu, 03 Jul 2014 19:39:49 +0300 From: Eli Zaretskii Subject: Re: bug#17916: 24.4.50; `write-region' doc for numeric APPEND arg In-reply-to: X-012-Sender: halo1@inter.net.il To: Drew Adams Message-id: <83wqbu1jmy.fsf@gnu.org> References: X-Spam-Score: 1.0 (+) X-Debbugs-Envelope-To: 17916 Cc: 17916@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list Reply-To: Eli Zaretskii List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 1.0 (+) > Date: Thu, 3 Jul 2014 09:14:07 -0700 (PDT) > From: Drew Adams > > 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. 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? From debbugs-submit-bounces@debbugs.gnu.org Thu Jul 03 13:23:49 2014 Received: (at 17916) by debbugs.gnu.org; 3 Jul 2014 17:23:49 +0000 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 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 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 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 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 MIME-Version: 1.0 Message-ID: Date: Thu, 3 Jul 2014 10:23:37 -0700 (PDT) From: Drew Adams To: Eli Zaretskii Subject: RE: bug#17916: 24.4.50; `write-region' doc for numeric APPEND arg References: <> <<83wqbu1jmy.fsf@gnu.org>> 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)] Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Source-IP: acsinet21.oracle.com [141.146.126.237] X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 17916 Cc: 17916@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.3 (--) > 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. From debbugs-submit-bounces@debbugs.gnu.org Wed Jul 14 05:28:29 2021 Received: (at 17916) by debbugs.gnu.org; 14 Jul 2021 09:28:29 +0000 Received: from localhost ([127.0.0.1]:42914 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1m3bBt-0004Ug-3P for submit@debbugs.gnu.org; Wed, 14 Jul 2021 05:28:29 -0400 Received: from quimby.gnus.org ([95.216.78.240]:41254) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1m3bBr-0004UQ-6e for 17916@debbugs.gnu.org; Wed, 14 Jul 2021 05:28:27 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org; s=20200322; h=Content-Type:MIME-Version:Message-ID:In-Reply-To:Date: References:Subject:Cc:To:From:Sender:Reply-To:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=DSsrkqn21vz2bd6W0GxzBDHS1E1V2Jdvu9LYFT7Pzmk=; b=Sav+qaewf3jhNqjMB6823fGWyq IXdVvPi9/E7f0rqZRwiJdTPIubvY5whJoKYnIdeUZa5Mcg3ZuwcgEopu7cvBZHoT8A/Uw09yF7dC2 N6U9A9iS4ojSWtX5qOahxcBLpGjT4XqL4H0jQ55sbPYya97YttJPf4wzQUNsYe+u004Q=; Received: from cm-84.212.220.105.getinternet.no ([84.212.220.105] helo=elva) by quimby.gnus.org with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1m3bBi-0001ue-JD; Wed, 14 Jul 2021 11:28:20 +0200 From: Lars Ingebrigtsen To: Eli Zaretskii Subject: Re: bug#17916: 24.4.50; `write-region' doc for numeric APPEND arg References: <83wqbu1jmy.fsf@gnu.org> X-Now-Playing: Kid Sister's _Ultra Violet_: "Daydreaming (Feat Cee-Lo)" Date: Wed, 14 Jul 2021 11:28:17 +0200 In-Reply-To: <83wqbu1jmy.fsf@gnu.org> (Eli Zaretskii's message of "Thu, 03 Jul 2014 19:39:49 +0300") Message-ID: <87sg0hkzwu.fsf@gnus.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: Eli Zaretskii writes: > 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 w [...] Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 17916 Cc: 17916@debbugs.gnu.org, Drew Adams X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Eli Zaretskii writes: > 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? I agree with Eli that there's nothing that needs clarification here, so I'm closing this bug report. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no From debbugs-submit-bounces@debbugs.gnu.org Wed Jul 14 05:28:34 2021 Received: (at control) by debbugs.gnu.org; 14 Jul 2021 09:28:34 +0000 Received: from localhost ([127.0.0.1]:42917 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1m3bBy-0004Uz-BL for submit@debbugs.gnu.org; Wed, 14 Jul 2021 05:28:34 -0400 Received: from quimby.gnus.org ([95.216.78.240]:41270) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1m3bBx-0004Uc-06 for control@debbugs.gnu.org; Wed, 14 Jul 2021 05:28:33 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org; s=20200322; h=Subject:From:To:Message-Id:Date:Sender:Reply-To:Cc: MIME-Version:Content-Type:Content-Transfer-Encoding:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:In-Reply-To:References:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=hm+D561p3k810pJAATzVbwlkZyCihRIVvAUDrUJmIN4=; b=kZgcTmf21cnYYqYCjwKdmZIq9y 51bECLCETnqgqOsuyHztRSBUssA6MOq9iJv2ONbAg8PBOibB2nj5wkkB6WKZ0lhFz+ROQEgj7tps2 6uF+pLl5Bt7yQQS6ncvOLoFVpXQlXFDUfPol8sxpc3HhrU6+5f6ZE94Zq/ofBAGbeRNE=; Received: from cm-84.212.220.105.getinternet.no ([84.212.220.105] helo=elva) by quimby.gnus.org with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1m3bBp-0001un-Dv for control@debbugs.gnu.org; Wed, 14 Jul 2021 11:28:27 +0200 Date: Wed, 14 Jul 2021 11:28:24 +0200 Message-Id: <87r1g1kzwn.fsf@gnus.org> To: control@debbugs.gnu.org From: Lars Ingebrigtsen Subject: control message for bug #17916 X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: close 17916 quit Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) close 17916 quit From unknown Fri Jun 20 07:26:04 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Wed, 11 Aug 2021 11:24:05 +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