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

[Drew Adams <drew.adams@oracle.com>]

> 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.