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

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

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



Reply | Threaded
Open this post in threaded view
|

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 <[hidden email]>
>
> 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.



Reply | Threaded
Open this post in threaded view
|

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

Stefan Kangas
In reply to this post by Drew Adams
Drew Adams <[hidden email]> 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



Reply | Threaded
Open this post in threaded view
|

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.



Reply | Threaded
Open this post in threaded view
|

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 <[hidden email]>
> Cc: [hidden email]
>
> 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.