[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

bug#17916: 24.4.50; `write-region' doc for numeric APPEND arg

From: Drew Adams
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 (i686-pc-mingw32)
 of 2014-06-28 on ODIEONE
Bzr revision: 117431 address@hidden
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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]