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

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

[Drew Adams]

In a few places this node uses the verb "to point" to refer to a
marker's position, as in the marker points to position N.

This is unfortunate, as it makes the text confusing - especially so
because the text in the node refers often to "point" meaning, well,
point, the position of the cursor.  Too many occurrences of "point", and
in some cases with different possible meanings (some of which are wrong).

It would be better to just talk about the position of the marker, or the
position the marker has, than to talk about the position the marker
points to.

Examples:

1. When a marker points at the place of insertion...

2. Certain special functions such as `insert-before-markers' relocate
   all such markers to point after the inserted text, regardless of the
   markers' insertion type.

3. ...it relocates markers initially pointing at the insertion point, to
   point after the inserted text.

#1 is not confusing or ambiguous.  #2 and #3 can confuse you into
thinking that "point after the inserted text" is maybe talking about
point (the cursor position) being (just) after the inserted text, as if
the text had another comma: "relocate all such markers to point, after
the inserted text,..."

Yes, lack of that comma does make the meaning clear, unless you read the
text carefully you can be confused or misled.

If the text instead speaks of the position of a marker, or speaks of
where a marker "is", instead of speaking of where a marker "points", the
problem disappears.  E.g.:

1. When a marker is at the place of insertion...

2. Certain special functions such as `insert-before-markers' relocate
   all such markers to be after the inserted text, regardless of the
   markers' insertion type.

3. ...it relocates markers that are initially at the insertion point, to
   be after the inserted text.

(This node also talks about "code point", which is a third meaning for
"point".  But that's unavoidable, and the text is not confusing.)


In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.17763
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

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

[Eli Zaretskii]

> Date: Sun, 3 Nov 2019 13:26:08 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
> In a few places this node uses the verb "to point" to refer to a
> marker's position, as in the marker points to position N.
> 
> This is unfortunate, as it makes the text confusing - especially so
> because the text in the node refers often to "point" meaning, well,
> point, the position of the cursor.  Too many occurrences of "point", and
> in some cases with different possible meanings (some of which are wrong).

FWIW, I see no reason to shy away from using the word "point" in its
usual sense, just because we also have a special meaning for it.

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

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

> In a few places this node uses the verb "to point" to refer to a
> marker's position, as in the marker points to position N.
>
> This is unfortunate, as it makes the text confusing - especially so
> because the text in the node refers often to "point" meaning, well,
> point, the position of the cursor.  Too many occurrences of "point", and
> in some cases with different possible meanings (some of which are wrong).

I agree with what Eli said in his reply, and I don't, in general, see
any risk for confusion.  In any case, I would suggest that we treat
this on a case by case basis, rather than a one size fits all.

You have pointed to three cases below, and I hope that you will find
the following observations useful.

> It would be better to just talk about the position of the marker, or the
> position the marker has, than to talk about the position the marker
> points to.
>
> Examples:
>
> 1. When a marker points at the place of insertion...
>
> 2. Certain special functions such as `insert-before-markers' relocate
>    all such markers to point after the inserted text, regardless of the
>    markers' insertion type.
>
> 3. ...it relocates markers initially pointing at the insertion point, to
>    point after the inserted text.
>
> #1 is not confusing or ambiguous.  #2 and #3 can confuse you into
> thinking that "point after the inserted text" is maybe talking about
> point (the cursor position) being (just) after the inserted text, as if
> the text had another comma: "relocate all such markers to point, after
> the inserted text,..."
>
> Yes, lack of that comma does make the meaning clear, unless you read the
> text carefully you can be confused or misled.
>
> If the text instead speaks of the position of a marker, or speaks of
> where a marker "is", instead of speaking of where a marker "points", the
> problem disappears.  E.g.:
>
> 1. When a marker is at the place of insertion...

I actually think it's more clear to say "points at" here, because the
marker is really an object in memory that "points at" a buffer
location.  It is not actually in the buffer itself.

> 2. Certain special functions such as `insert-before-markers' relocate
>    all such markers to be after the inserted text, regardless of the
>    markers' insertion type.

I think the original reads better, and is more clear, as above.

> 3. ...it relocates markers that are initially at the insertion point, to
>    be after the inserted text.

The same reasoning applies here.

> (This node also talks about "code point", which is a third meaning for
> "point".  But that's unavoidable, and the text is not confusing.)

Agreed.

Best regards,
Stefan Kangas

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

[Drew Adams]

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.

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

[Eli Zaretskii]

> Date: Fri, 8 Nov 2019 17:53:06 +0000 (UTC)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 38051@debbugs.gnu.org
> 
> 1. From a user point of view (conceptual model),
>    markers _are_ objects that can be located
>    _in_ a buffer, _at_ buffer positions.

That is incorrect.  A marker stores a buffer and a location within
that buffer, but it isn't itself located in a 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).

See above: that's correct about characters, but incorrect about
markers.

> This is how we treat overlays.

Overlays are completely different beasts.

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

[Drew Adams]

> FWIW, I see no reason to shy away from using the word "point" in its
> usual sense, just because we also have a special meaning for it.

Do you see no reason because you don't see the
possible confusion?  Or do you see that but don't
consider it's worth using different language to
prevent it?

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

[Eli Zaretskii]

> Date: Mon, 4 Nov 2019 10:10:34 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 38051@debbugs.gnu.org
> 
> > FWIW, I see no reason to shy away from using the word "point" in its
> > usual sense, just because we also have a special meaning for it.
> 
> Do you see no reason because you don't see the
> possible confusion?  Or do you see that but don't
> consider it's worth using different language to
> prevent it?

The former.

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

[Drew Adams]

> > 1. From a user point of view (conceptual model),
> >    markers _are_ objects that can be located
> >    _in_ a buffer, _at_ buffer positions.
> 
> That is incorrect.  A marker stores a buffer and a location within
> that buffer, but it isn't itself located in a buffer.

From a user point of view.  That's the point.
That can't be "incorrect".  It's a question of
what the user needs as a conceptual model to
work with markers (and overlays, for that matter).

Does the model fit the observable behavior?  That's
something that makes sense to ask.  So far, I've
seen no example of a case where it doesn't fit.

It does not matter one whit to a user what the
implementation of a marker is.  Whether a marker
"stores a buffer and a location" or a marker
stores a (code) pointer to a buffer and a location,
or however else it might be implemented.

Unless you can show the contrary.  Ehat user-visible
behavior is unexplained by the simpler user model
I described (and which we already use for overlays,
and which we already partly - but not consistently -
use for markers)?

> > 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).
> 
> See above: that's correct about characters, but incorrect about
> markers.

"Incorrect" is the wrong way to talk about such
things. A user description/model that is coherent,
consistent, and complete - jibes with observable
behavior - is fine and dandy.  Useful, sufficient.
 
> > This is how we treat overlays.
> 
> Overlays are completely different beasts.

If you say so (without any explanation of why you
think so).

Does an overlay store a buffer and two locations
within that buffer?  Why is it necessary (or even
useful) for a user to think in terms of a marker
doing that but not an overlay?

What is it in the user-observable behavior of a
marker that requires introducing the extra
(I'd say extraneous) construct of it "pointing to"
a buffer and a position within that buffer?  A
construct that is nowhere defined or explicated.

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

[Eli Zaretskii]

> Date: Fri, 8 Nov 2019 11:56:29 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: stefan@marxist.se, 38051@debbugs.gnu.org
> 
> > > 1. From a user point of view (conceptual model),
> > >    markers _are_ objects that can be located
> > >    _in_ a buffer, _at_ buffer positions.
> > 
> > That is incorrect.  A marker stores a buffer and a location within
> > that buffer, but it isn't itself located in a buffer.
> 
> From a user point of view.  That's the point.
> That can't be "incorrect".

Of course it can.  And it is.

> It's a question of what the user needs as a
> conceptual model to work with markers (and
> overlays, for that matter).

Wrong conceptual models will bite you down the road.  It is best to
have correct conceptual models.

> > Overlays are completely different beasts.
> 
> If you say so (without any explanation of why you
> think so).
> 
> Does an overlay store a buffer and two locations
> within that buffer?

No.  Like I said: it's a different beast.

> What is it in the user-observable behavior of a
> marker that requires introducing the extra
> (I'd say extraneous) construct of it "pointing to"
> a buffer and a position within that buffer?

Convenience and clarity of description.

And please, can we stop this bikeshedding?  It goes nowhere.

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

[Stefan Kangas]

tags 38051 + wontfix
close 38051
thanks

Eli Zaretskii <eliz@gnu.org> writes:

> > It's a question of what the user needs as a
> > conceptual model to work with markers (and
> > overlays, for that matter).
>
> Wrong conceptual models will bite you down the road.  It is best to
> have correct conceptual models.

I think this is the key here, not least because we are discussing the
Emacs Lisp manual.

I think we can indeed agree to disagree, while the decision seems to
be to not make any changes along the suggested lines.  I'm therefore
closing this bug report.  Thanks.

Best regards,
Stefan Kangas