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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 19841 in the body.
You can then email your comments to 19841 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 25.0.50; Doc for `transient-mark-mode' should say that highlighting
 is with face `region'
Date: Wed, 11 Feb 2015 13:32:24 -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

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

Message #8 received at 19841 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 19841 <at> debbugs.gnu.org
Subject: Re: bug#19841: 25.0.50;
 Doc for `transient-mark-mode' should say that highlighting is
 with	face `region'
Date: Fri, 13 Feb 2015 11:14:11 +0200

> Date: Wed, 11 Feb 2015 13:32:24 -0800 (PST)
> From: Drew Adams <drew.adams <at> 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.

Message #11 received at 19841 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 19841 <at> debbugs.gnu.org
Subject: RE: bug#19841: 25.0.50; Doc for `transient-mark-mode' should say that
 highlighting is with	face `region'
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.

Message #16 received at 19841-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 19841-done <at> debbugs.gnu.org
Subject: Re: bug#19841: 25.0.50;
 Doc for `transient-mark-mode' should say that highlighting is
 with	face `region'
Date: Fri, 13 Feb 2015 17:10:17 +0200

> Date: Fri, 13 Feb 2015 06:52:56 -0800 (PST)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 19841 <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.