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

[Drew Adams]

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=/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''