bug#50950: [External] : bug#50950: "(emacs) Mark" should contrast to "selecting" text in other editors

[Drew Adams]

FWIW -

I generally agree with Eli's feedback.  Some comments
on the text:

1. "In Emacs, selected text is called the @dfn{region}."

No, not really, and this should be gotten across at
the outset.

I guess you could say that in transient-mark-mode
selected text is the _active_ region.  But then
you'll need to distinguish active from inactive in
t-m-mode etc.

The region is simply the buffer expanse between
point and mark, and the region's text is the text
in that expanse (region).  It's point and mark that
are basic concepts to talking about (and defining)
the region.

I know that you're just trying, in this intro text,
to connect the region with what users already know
about, namely selected, highlighted text.  The
problem I see with the text is that it seems to be 
defining the region as the same thing as selected
text.

This is probably just a problem of wording.  E.g.,
if you want to introduce the region by saying that
it's _somewhat_ like XYZ, that could be OK.  And
you do that by saying it's "roughly analogous..."
Just don't say that selected text "is called the
region".

Care needs to be taken to clearly distinguish it
- it's _not_ XYZ - and to explain about t-m-mode
and  the "active" region, and that some Emacs
commands act on the text in the region even when
it's inactive (and when t-m-mode is off).

2. It's not just that there are names for point
and mark.  They are important concepts and things
you use.  Command can do things at point or mark,
for instance.

3. I think it's a mistake to speak of "moving
point" and saying "you move point".

Point is just the current cursor position.  You
move the cursor, not point.  (Yes, the value of
point changes when you move the cursor, but the
user POV is moving the cursor.)

4. "The region always starts at point...ends at...
the mark."  I wouldn't say that.  It's important
that users understand from the outset that point
and mark are at the ends of the region (or rather
that the region is defined by those positions as
its limits).  But neither point nor mark is the
start (or the end).

Start and end are anyway unclear.  We have
`region-beginning|end', for start and end; we
don't have point and mark for start and end.

Yes, you try to explain this later.  But the
text you're starting with can misguide, IMO, by
talking about point as the start and mark as the
end.

5. "normal movement commands" is unclear, to me.
I'd speak in terms of movement of the _cursor_.
There are also window, frame, text, etc. movements.

I think it's important (perhaps after making some
nod to what users might already have experienced
in other editors) to start with the concepts of
cursor and buffer, then move to point and mark,
and then move to region, active region, etc.

6. "move the mark"..."we call this setting the
mark".  I wouldn't say that.  I'd say that you
can (and Emacs can) set the mark to any buffer
position.  Just as for point (another buffer
position), it can mislead to speak of moving the
mark.  There's nothing analogous to the cursor
for the mark - no visual thingy that you move.
But when the mark is set to a new position you
can see that the region limit has changed.

7. "Setting the mark also @dfn{activates} it."
Only in t-m-mode.  When t-m-mode is off there's
no notion of an active/inactive mark or region.

8. "After some commands, including any command
that changes the text in the buffer, Emacs
automatically @dfn{deactivates} the mark."

It's not about "some commands".  It's about
most commands.  More precisely, this is the
_default_ behavior: after a command the mark
is deactivated.

9. "the region is no longer active, and
consequently any highlighting of it is removed."
Yes, but there's another important consequence
- one that's perhaps even more important: many
commands no longer act on the region (namely
those that act on it only when it's active).

10. (You can tell that I think the existing
text already has some of the same problems.
In particular, t-m-mode is introduced late,
which means readers need to then wonder just
what parts of what the read before that are no
longer true - that's not obvious.)

11. "The mark is useful even if it is not
active.  For example, you can move to previous
mark locations using the mark ring.  Mark Ring.  Additionally, some commands 
will have an
effect even on an inactive region (for example
upcase-region)."

This is important, and should be said earlier.
I'd say "mark and region" are useful, not mark.
I'd move the example of the mark being useful
on its own (e.g. mark-ring) earlier.  (I'd
start, as I said, with cursor, then point and
mark, then region, then active/inactive and
t-m-mode.)

HTH.  Feel free to ignore, of course.