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

From: Drew Adams <[email-masked]>
Date: Fri, 13 Feb 2015 06:52:56 -0800 (PST)

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