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

Previous Next

Full log

View this message in rfc822 format

From: Drew Adams <drew.adams <at> oracle.com>
To: 17916 <at> debbugs.gnu.org
Subject: bug#17916: 24.4.50; `write-region' doc for numeric APPEND arg
Date: Thu, 3 Jul 2014 09:14:07 -0700 (PDT)

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 <at> gnu.org-20140628015517-eku6hj8mpgcvfnso
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/snapshot/trunk
 --enable-checking=yes,glyphs 'CFLAGS=-O0 -g3'
 LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

Previous Next

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