GNU bug report logs - #17916
24.4.50; `write-region' doc for numeric APPEND arg

Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.

Package: emacs; Severity: minor; Reported by: Drew Adams <drew.adams@HIDDEN>; dated Thu, 3 Jul 2014 16:16:02 UTC; Maintainer for emacs is bug-gnu-emacs@HIDDEN.

Message received at 17916 <at> debbugs.gnu.org:


Received: (at 17916) by debbugs.gnu.org; 3 Jul 2014 17:23:49 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Jul 03 13:23:49 2014
Received: from localhost ([127.0.0.1]:41920 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1X2kjc-0002oW-Nd
	for submit <at> 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 <drew.adams@HIDDEN>) id 1X2kja-0002oC-Qp
 for 17916 <at> 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: <f185b19a-8cf6-419a-8656-24b27239084d@default>
Date: Thu, 3 Jul 2014 10:23:37 -0700 (PDT)
From: Drew Adams <drew.adams@HIDDEN>
To: Eli Zaretskii <eliz@HIDDEN>
Subject: RE: bug#17916: 24.4.50; `write-region' doc for numeric APPEND arg
References: <<d50aa5b4-8835-470d-b190-eb664e864bd3@default>>
 <<83wqbu1jmy.fsf@HIDDEN>>
In-Reply-To: <<83wqbu1jmy.fsf@HIDDEN>>
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 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
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.




Information forwarded to bug-gnu-emacs@HIDDEN:
bug#17916; Package emacs. Full text available.

Message received at 17916 <at> debbugs.gnu.org:


Received: (at 17916) by debbugs.gnu.org; 3 Jul 2014 16:40:24 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Jul 03 12:40:24 2014
Received: from localhost ([127.0.0.1]:41895 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1X2k3Y-000094-0d
	for submit <at> 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 <eliz@HIDDEN>) id 1X2k3Q-00008a-DR
 for 17916 <at> 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@HIDDEN> for 17916 <at> 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@HIDDEN>;
 Thu, 03 Jul 2014 19:40:04 +0300 (IDT)
Date: Thu, 03 Jul 2014 19:39:49 +0300
From: Eli Zaretskii <eliz@HIDDEN>
Subject: Re: bug#17916: 24.4.50; `write-region' doc for numeric APPEND arg
In-reply-to: <d50aa5b4-8835-470d-b190-eb664e864bd3@default>
X-012-Sender: halo1@HIDDEN
To: Drew Adams <drew.adams@HIDDEN>
Message-id: <83wqbu1jmy.fsf@HIDDEN>
References: <d50aa5b4-8835-470d-b190-eb664e864bd3@default>
X-Spam-Score: 1.0 (+)
X-Debbugs-Envelope-To: 17916
Cc: 17916 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.15
Precedence: list
Reply-To: Eli Zaretskii <eliz@HIDDEN>
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: 1.0 (+)

> Date: Thu, 3 Jul 2014 09:14:07 -0700 (PDT)
> From: Drew Adams <drew.adams@HIDDEN>
> 
>   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?




Information forwarded to bug-gnu-emacs@HIDDEN:
bug#17916; Package emacs. Full text available.

Message received at submit <at> debbugs.gnu.org:


Received: (at submit) by debbugs.gnu.org; 3 Jul 2014 16:15:02 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Jul 03 12:15:02 2014
Received: from localhost ([127.0.0.1]:41873 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1X2jez-0006Va-DQ
	for submit <at> 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 <drew.adams@HIDDEN>) id 1X2jet-0006VA-Ot
 for submit <at> 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 <drew.adams@HIDDEN>) id 1X2jed-0003Tl-LP
 for submit <at> 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 <drew.adams@HIDDEN>) id 1X2jed-0003Th-H1
 for submit <at> 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 <drew.adams@HIDDEN>) id 1X2jeQ-0004rK-O9
 for bug-gnu-emacs@HIDDEN; Thu, 03 Jul 2014 12:14:35 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
 (envelope-from <drew.adams@HIDDEN>) id 1X2jeH-0003Hs-Rl
 for bug-gnu-emacs@HIDDEN; 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 <drew.adams@HIDDEN>) id 1X2jeH-0003Hl-K5
 for bug-gnu-emacs@HIDDEN; 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 <bug-gnu-emacs@HIDDEN>; 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 <bug-gnu-emacs@HIDDEN>; 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 <bug-gnu-emacs@HIDDEN>; Thu, 3 Jul 2014 16:14:09 GMT
MIME-Version: 1.0
Message-ID: <d50aa5b4-8835-470d-b190-eb664e864bd3@default>
Date: Thu, 3 Jul 2014 09:14:07 -0700 (PDT)
From: Drew Adams <drew.adams@HIDDEN>
To: bug-gnu-emacs@HIDDEN
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 <at> debbugs.gnu.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
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@HIDDEN
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''




Acknowledgement sent to Drew Adams <drew.adams@HIDDEN>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs@HIDDEN. Full text available.
Report forwarded to bug-gnu-emacs@HIDDEN:
bug#17916; Package emacs. Full text available.
Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.
Last modified: Fri, 31 Oct 2014 17:00:04 UTC

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997 nCipher Corporation Ltd, 1994-97 Ian Jackson.