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

From: Drew Adams <[email-masked]>
Date: Sun, 3 Nov 2019 13:26:08 -0800 (PST)

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