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

From: Eli Zaretskii <[email-masked]>
Date: Sat, 16 Oct 2021 17:11:58 +0300

> From: Stefan Kangas <[email-masked]>
> Date: Sat, 16 Oct 2021 09:04:38 -0400
> Cc: [email-masked]
> 
> Eli Zaretskii <[email-masked]> writes:
> 
> > As I said, rewriting this overview text is probably a good idea, so no
> > argument here.  But the new text should still explain how our region
> > is different in subtle but important ways from what people see in
> > other editors.  Would you like to propose such a rewording?
> 
> I have made an attempt in the attached patch.  I wrote this a week or
> two ago, and returned to it again, and with fresh eyes I only find some
> minor touch-ups to be made.  I'm interested to hear what you all think.

Are you happy with the result?

My main problem with this text is that it says there are important
differences, but with a single exception leaves it to the reader to
deduce or guess which parts of the description are about these
differences and which ones just describe related issues and features.

Another, more minor problem is that the text starts under the
assumption that when you say "selected text", the reader immediately
understands what you mean, and that is neither a given nor a good
style, IME: it is always better to have some introductory sentence
that provides context.  For example:

  Emacs, like many other applications, lets you select some arbitrary
  part of the buffer text and invoke commands that operate on such
  @dfn{selected text}.  In Emacs, we call the selected text @dfn{the
  region}; its handling is very similar to that of selected text in
  other programs, but there are also important differences.

As for differences themselves, I'd suggest an explicit itemized list,
first naming them and then explaining each difference in some detail,
including cross-references to sections which describe them in more
detail.  The differences I think we should describe here are:

  . the "mark" and its relation to region (after all, the chapter is
    called "The Mark and the Region")
  . the fact that region can be active or inactive, and the basic
    difference between these two
  . the fact that some commands operate on region if it's active, and
    some even if it's inactive (the main difference here is that in
    Emacs many more commands are region-sensitive than in other
    programs, where it basically only supports copy/paste)
  . maybe also that we have some unusual ways of extending the region

The main challenge in describing these is how to describe enough, but
not too much (because the full details are elsewhere, and this is just
an introduction).

Thanks.