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

[Stefan Kangas <stefan@marxist.se>]

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