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

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

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

[Eli Zaretskii]

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

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

[Drew Adams]

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

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

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

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

I agree with Eli that there's nothing that needs clarification here, so
I'm closing this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no