From mboxrd@z Thu Jan  1 00:00:00 1970
Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail
From: Drew Adams <drew.adams@oracle.com>
Newsgroups: gmane.emacs.bugs
Subject: bug#41884: 27.0.91;
 `C-h f whitespace-mode' doesn't say that it's a minor mode
Date: Sun, 2 Aug 2020 09:27:56 -0700 (PDT)
Message-ID: <25af197b-05fb-4193-b617-a7d25fe43fd9@default>
References: <<2f814ee0-f472-43f6-878b-a9c9489d771e@default>>
 <<CADwFkmm+bEojs03A76PoLPO08CQpTCfQZgErP2gYbXYumai1sw@mail.gmail.com>>
 <<833655ceg9.fsf@gnu.org>>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: quoted-printable
Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214";
	logging-data="7822"; mail-complaints-to="usenet@ciao.gmane.io"
Cc: 41884@debbugs.gnu.org
To: Eli Zaretskii <eliz@gnu.org>, Stefan Kangas <stefankangas@gmail.com>
Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sun Aug 02 18:29:09 2020
Return-path: <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org>
Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org
Original-Received: from lists.gnu.org ([209.51.188.17])
	by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org>)
	id 1k2GrF-0001wq-PF
	for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 02 Aug 2020 18:29:09 +0200
Original-Received: from localhost ([::1]:32852 helo=lists1p.gnu.org)
	by lists.gnu.org with esmtp (Exim 4.90_1)
	(envelope-from <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org>)
	id 1k2GrE-00055O-RQ
	for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 02 Aug 2020 12:29:08 -0400
Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:53978)
 by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <Debian-debbugs@debbugs.gnu.org>)
 id 1k2Gr8-00055C-3J
 for bug-gnu-emacs@gnu.org; Sun, 02 Aug 2020 12:29:02 -0400
Original-Received: from debbugs.gnu.org ([209.51.188.43]:59954)
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128)
 (Exim 4.90_1) (envelope-from <Debian-debbugs@debbugs.gnu.org>)
 id 1k2Gr7-0005tl-Qa
 for bug-gnu-emacs@gnu.org; Sun, 02 Aug 2020 12:29:01 -0400
Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2)
 (envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1k2Gr7-0004NZ-OW
 for bug-gnu-emacs@gnu.org; Sun, 02 Aug 2020 12:29:01 -0400
X-Loop: help-debbugs@gnu.org
Resent-From: Drew Adams <drew.adams@oracle.com>
Original-Sender: "Debbugs-submit" <debbugs-submit-bounces@debbugs.gnu.org>
Resent-CC: bug-gnu-emacs@gnu.org
Resent-Date: Sun, 02 Aug 2020 16:29:01 +0000
Resent-Message-ID: <handler.41884.B41884.159638568716767@debbugs.gnu.org>
Resent-Sender: help-debbugs@gnu.org
X-GNU-PR-Message: followup 41884
X-GNU-PR-Package: emacs
Original-Received: via spool by 41884-submit@debbugs.gnu.org id=B41884.159638568716767
 (code B ref 41884); Sun, 02 Aug 2020 16:29:01 +0000
Original-Received: (at 41884) by debbugs.gnu.org; 2 Aug 2020 16:28:07 +0000
Original-Received: from localhost ([127.0.0.1]:43267 helo=debbugs.gnu.org)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <debbugs-submit-bounces@debbugs.gnu.org>)
 id 1k2GqF-0004MN-6z
 for submit@debbugs.gnu.org; Sun, 02 Aug 2020 12:28:07 -0400
Original-Received: from userp2130.oracle.com ([156.151.31.86]:54596)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <drew.adams@oracle.com>) id 1k2GqC-0004Lm-Rr
 for 41884@debbugs.gnu.org; Sun, 02 Aug 2020 12:28:06 -0400
Original-Received: from pps.filterd (userp2130.oracle.com [127.0.0.1])
 by userp2130.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 072GRwDG118467;
 Sun, 2 Aug 2020 16:27:59 GMT
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com;
 h=mime-version :
 message-id : date : from : sender : to : cc : subject : references :
 in-reply-to : content-type : content-transfer-encoding; s=corp-2020-01-29;
 bh=TyaUJxWnLCtldQPuBwacb6yzPyDtAYOHxSmB0ASX92Q=;
 b=O0oNGzo70rAnHCHTYz/pjPZwOZm6fwGe5+qsK1U8TWdpSlJDFQnnAE/2fsqrD73p01Jv
 PwMsrYPT1+cRYpOh1bNpMSSA8hgVVBplrp+9NBY1HVlWamJAgyh8cghPOzG/nI+dfaZC
 9negG7JOX0oKwiuQ+PA1a/qmKXpxYcDRxhC27M+B79Q289uwoEBSSe9EFBUxRqSedMQ1
 ND0kV4fegir9uC8Xssm9Wtd5AaIfJtHFfSjiWpPWj8xPlONufQroidOdXkSc6FraGyuQ
 wIPQMytvbb2/z7tRp0+Wav0X7YPXqhS1IYtrWwcG3vaJkaNj+ztvbmDR24hoMvZOuRt1 rg== 
Original-Received: from userp3030.oracle.com (userp3030.oracle.com [156.151.31.80])
 by userp2130.oracle.com with ESMTP id 32mytquax5-1
 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL);
 Sun, 02 Aug 2020 16:27:59 +0000
Original-Received: from pps.filterd (userp3030.oracle.com [127.0.0.1])
 by userp3030.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 072GRanE158584;
 Sun, 2 Aug 2020 16:27:58 GMT
Original-Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75])
 by userp3030.oracle.com with ESMTP id 32njatxg3u-1
 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK);
 Sun, 02 Aug 2020 16:27:58 +0000
Original-Received: from abhmp0018.oracle.com (abhmp0018.oracle.com [141.146.116.24])
 by userv0122.oracle.com (8.14.4/8.14.4) with ESMTP id 072GRwdh007688;
 Sun, 2 Aug 2020 16:27:58 GMT
In-Reply-To: <<833655ceg9.fsf@gnu.org>>
X-Priority: 3
X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1  (1003210) [OL
 16.0.5017.0 (x86)]
X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9701
 signatures=668679
X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 bulkscore=0
 phishscore=0
 mlxlogscore=999 mlxscore=0 spamscore=0 malwarescore=0 adultscore=0
 suspectscore=0 classifier=spam adjust=0 reason=mlx scancount=1
 engine=8.12.0-2006250000 definitions=main-2008020128
X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9701
 signatures=668679
X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 phishscore=0
 impostorscore=0
 mlxlogscore=999 bulkscore=0 malwarescore=0 spamscore=0 suspectscore=0
 adultscore=0 mlxscore=0 priorityscore=1501 lowpriorityscore=0
 clxscore=1015 classifier=spam adjust=0 reason=mlx scancount=1
 engine=8.12.0-2006250000 definitions=main-2008020128
X-BeenThere: debbugs-submit@debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
X-BeenThere: bug-gnu-emacs@gnu.org
List-Id: "Bug reports for GNU Emacs,
 the Swiss army knife of text editors" <bug-gnu-emacs.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/bug-gnu-emacs>,
 <mailto:bug-gnu-emacs-request@gnu.org?subject=unsubscribe>
List-Archive: <https://lists.gnu.org/archive/html/bug-gnu-emacs>
List-Post: <mailto:bug-gnu-emacs@gnu.org>
List-Help: <mailto:bug-gnu-emacs-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/bug-gnu-emacs>,
 <mailto:bug-gnu-emacs-request@gnu.org?subject=subscribe>
Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org
Original-Sender: "bug-gnu-emacs"
 <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org>
Xref: news.gmane.io gmane.emacs.bugs:183864
Archived-At: <http://permalink.gmane.org/gmane.emacs.bugs/183864>

> > > The doc string for a minor mode should tell
> > > you it's a minor mode.
> >
> > Should all minor modes say this?
>=20
> No, they don't.

That wasn't Stefan's question.  Should they?
I think they should.

Typically it takes only adding the words "minor
mode".  In the case of `whitespace-mode' it takes
only adding the word "minor":

 Toggle whitespace visualization (Whitespace minor mode).

I can't imagine why we _wouldn't_ want to tell
users this in the doc string.
____

[And, for the related problem that crops up wrt
minor-mode command doc strings - of not always
documenting well how to turn the mode on/off:
if someone decides to opt for a simple one-size
fits all fix, then that could be to just provide
a link to the doc about minor modes in each
minor-mode doc string.

IOW, once every minor-mode doc string says that
it's about a minor mode, a simple link to the doc
that tells you about minor modes would take care
of lacunae such as the doc string neglecting to
tell you clearly how to turn it on/off.

(It's still better to give that info directly in
the doc string, IMO, but such a link would make
sure to cover any such omission.)]