bug#19841: 25.0.50; Doc for `transient-mark-mode' should say that highlighting is with face `region'

bug#19841: 25.0.50; Doc for `transient-mark-mode' should say that highlighting is with face `region'

[Drew Adams]

Please update the doc string, the Emacs manual, node `Disabled Transient
Mark', and the Elisp manual, node `The Mark'.

While you're at it, please so likewise for the Elisp manual node `The
Region'.  (At least Emacs manual node `Mark' mentions it.)

It is not obvious to users which face they can customize to change the
`transient-mark-mode' highlighting.

This thread is one indication of the need for this improvement:
http://lists.gnu.org/archive/html/help-gnu-emacs/2015-02/msg00236.html

In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2014-10-20 on LEG570
Bzr revision: 118168 rgm@gnu.org-20141020195941-icp42t8ttcnud09g
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking=yes,glyphs CPPFLAGS=-DGLYPH_DEBUG=1'

bug#19841: 25.0.50; Doc for `transient-mark-mode' should say that highlighting is with face `region'

[Eli Zaretskii]

> Date: Wed, 11 Feb 2015 13:32:24 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
> Please update the doc string, the Emacs manual, node `Disabled Transient
> Mark', and the Elisp manual, node `The Mark'.
> 
> While you're at it, please so likewise for the Elisp manual node `The
> Region'.  (At least Emacs manual node `Mark' mentions it.)
> 
> It is not obvious to users which face they can customize to change the
> `transient-mark-mode' highlighting.
> 
> This thread is one indication of the need for this improvement:
> http://lists.gnu.org/archive/html/help-gnu-emacs/2015-02/msg00236.html

I added references to the 'region' face to the 2 doc strings, but left
the manuals alone.  We generally don't mention faces of features where
those features are described; instead, there's a "Standard Faces" node
in the Emacs manual that documents them all in one place.

bug#19841: 25.0.50; Doc for `transient-mark-mode' should say that highlighting is with face `region'

[Drew Adams]

> > Please update the doc string, the Emacs manual, node `Disabled Transient
> > Mark', and the Elisp manual, node `The Mark'.
> >
> > While you're at it, please so likewise for the Elisp manual node `The
> > Region'.  (At least Emacs manual node `Mark' mentions it.)
> >
> > It is not obvious to users which face they can customize to change the
> > `transient-mark-mode' highlighting.
> >
> > This thread is one indication of the need for this improvement:
> > http://lists.gnu.org/archive/html/help-gnu-emacs/2015-02/msg00236.html
> 
> I added references to the 'region' face to the 2 doc strings, but left
> the manuals alone.  We generally don't mention faces of features where
> those features are described; instead, there's a "Standard Faces" node
> in the Emacs manual that documents them all in one place.

OK, thank you.

Wouldn't it be good to xref node Standard Faces for this?
The doc string mention is sufficient, but someone reading
the manual might not think to also look at the doc string.

And in the case of `transient-mark-mode' and the `region'
face, the connection is not at all obvious.  For some other
modes and their faces the names are similar (e.g. if the
`region' were called `transient-mark' or something).  But
for these two, in particular, I think a cross-ref wouldn't
hurt.

Anyway, feel free to close the bug, and use your judgment
about the manuals.  I haven't looked at the new doc-string
text, but I'm sure it's a big improvement.

bug#19841: 25.0.50; Doc for `transient-mark-mode' should say that highlighting is with face `region'

[Eli Zaretskii]

> Date: Fri, 13 Feb 2015 06:52:56 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 19841@debbugs.gnu.org
> 
> Wouldn't it be good to xref node Standard Faces for this?

I thought about that, but when I looked at the corresponding nodes, it
didn't look useful: the nodes are very large, and a single sentence
will get lost there.

> And in the case of `transient-mark-mode' and the `region'
> face, the connection is not at all obvious.

The region is mentioned.  In any case, I presume a user who wants to
find the face will simply go to "Standard Faces".

> Anyway, feel free to close the bug

Done.