bug#38051: 26.3; (elisp) `Insertion' use of verb "point"

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

We'll have to agree to disagree, I guess.

IMO:

1. From a user point of view (conceptual model),
   markers _are_ objects that can be located
   _in_ a buffer, _at_ buffer positions.

   (So if chars are present, a marker can be
   located before or after a char, or between
   two chars).

2. Yes, we do sometimes draw a distinction,
   since marker changes, like overlay changes,
   are "not recorded in the buffer's undo list,
   since the overlays are not part of the buffer's
   contents." -- (elisp) `Managing Overlays'.

   Markers and overlays aren't part of a buffer's
   _contents_, but they are located in the buffer.

3. When we document `char-after', we don't say
   that the char (which is conceptually _in_ the
   buffer) "points at" a buffer position.  We
   say "Return the character _in_ current buffer
   _at_ position POS."

   Markers, like characters, are at buffer
   positions (chars are actually after, not at).

   The doc of `marker-position' doesn't say that
   the marker "points at" the position.  It says
   that the marker currently has that position -
   "the position of the marker".

Nothing is gained, IMO, and confusion can be
introduced, by saying that markers "point at"
buffer positions, instead of saying markers are
"located at" buffer positions or they "have"
buffer positions.

Yes, this question is more general than just
the particular text questioned by the bug
report, which compounds the problem of using
"points at" because of different uses of the
word "point".

I see nothing positive about using "point at"
or "point into" for markers.  Occam's razor
says simplify - just say that a marker can be
_in_ a buffer _at_ a buffer position.

IOW, speak of markers the same way we speak of
overlays.  `overlay-buffer' is the buffer that
"OVERLAY _belongs to_", not the buffer that
OVERLAY points to or that OVERLAY's positions
point to.  We create an overlay "in" a buffer,
or that a given overlay is "in" no buffer.

This means that I'd also change the doc of
`marker-buffer', to speak of the buffer where
MARKER is located, not "the buffer that MARKER
points into".  

And yes, a marker need not be located in any
buffer.  The doc string of `marker-buffer' says
that it "points into" no buffer, and that of
`marker-position' says that it "points nowhere".
We should instead just say that the marker is
not in any buffer.

Likewise, we should say that a marker is
located in a dead buffer, rather than saying
that it "points into" a dead buffer.

Note that we already do say that a marker is
"in no buffer", here: (setq m (point-marker)),
kill the buffer, then `C-h v m'.

This is not an argument for consistency.  It's
an argument for a simpler description and user
model: a marker can be in a buffer, or not.
If in a buffer, it has a non-nil position.  If
not, its position is nil.

This is how we treat overlays.  We should
treat markers the same way.  The (undefined!)
notion of a marker "pointing at" a buffer
position isn't needed, and it isn't helpful.