From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.devel Subject: RE: Making DOC argument of define-minor-mode optional Date: Wed, 28 Dec 2016 16:44:24 -0800 (PST) Message-ID: <7be41013-b0a8-4887-92c6-eb624ab87443@default> References: <83eg226vr5.fsf@gnu.org> <87lgwaxk3z.fsf@petton.fr> <41b59c33-1be1-440e-a9b1-efb97c6e14a8@default> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1482972322 10361 195.159.176.226 (29 Dec 2016 00:45:22 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Thu, 29 Dec 2016 00:45:22 +0000 (UTC) Cc: emacs-devel@gnu.org To: Philipp Stephani , Nicolas Petton , Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Dec 29 01:45:18 2016 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cMOqL-00020e-Em for ged-emacs-devel@m.gmane.org; Thu, 29 Dec 2016 01:45:17 +0100 Original-Received: from localhost ([::1]:33215 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cMOqP-0000MZ-W2 for ged-emacs-devel@m.gmane.org; Wed, 28 Dec 2016 19:45:22 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:33591) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cMOpr-0000MI-W4 for emacs-devel@gnu.org; Wed, 28 Dec 2016 19:44:48 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cMOpr-0003ib-5G for emacs-devel@gnu.org; Wed, 28 Dec 2016 19:44:48 -0500 Original-Received: from userp1040.oracle.com ([156.151.31.81]:48734) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1cMOpl-0003eW-Ef; Wed, 28 Dec 2016 19:44:41 -0500 Original-Received: from aserv0021.oracle.com (aserv0021.oracle.com [141.146.126.233]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id uBT0iakJ019220 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Thu, 29 Dec 2016 00:44:37 GMT Original-Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by aserv0021.oracle.com (8.13.8/8.14.4) with ESMTP id uBT0iaHc021055 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Thu, 29 Dec 2016 00:44:36 GMT Original-Received: from abhmp0016.oracle.com (abhmp0016.oracle.com [141.146.116.22]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id uBT0iZDF009956; Thu, 29 Dec 2016 00:44:35 GMT In-Reply-To: X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 12.0.6753.5000 (x86)] X-Source-IP: aserv0021.oracle.com [141.146.126.233] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] [fuzzy] X-Received-From: 156.151.31.81 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:210934 Archived-At: [It's hard for me to follow the non plain-text messages you send. In this case, it's not clear whom you are responding to, and to whom you are asking the question. My part of the thread was two quotes back - dunno who replied to me with "That sounds like a good approach", to which you are replying.] >> I'd be in favor of (somehow) automatically having the >> definer-provided DOC be augmented by a link that shows >> the generic `define-minor-mode' doc, or similar. >>=20 >> IOW: >>=20 >> 1. Definers should need to provide a DOC string (even if >> =C2=A0 =C2=A0they can fake it with "", which is not encouraged). >>=20 >> 2. Users of the mode should have access to the generic >> =C2=A0 =C2=A0information also.=C2=A0 It should be sufficient that the >> =C2=A0 =C2=A0DOC in the definition provides mode-specific information. >> =C2=A0 =C2=A0It should not need to tell users general things about >> =C2=A0 =C2=A0using a minor mode. >=20 > Do you have a good idea how to design the interface for this? I don't have an idea about the implementation; sorry. > I was thinking about something like this: Create a new help > type, "mode", analogous to "variable" and "function". The > documentation for the mode would be different from the toggle > command and the mode variable, which would get a generic > docstring. C-h o and C-h m would show the mode docstring > instead of the toggle command docstring. The mode docstring > would contain only a description of the mode itself, not the > toggle command. >=20 > The primary downside is that many mode docstrings are written > to be applicable to the toggle command. Maybe `define-minor-mode' > could grow a :doc keyword argument for the mode docstring to > preserve backward compatibility. I do think that the doc for a minor mode should be accessible in the same way as for other functions by a user: `C-h f'. (It is also available from `C-h m'.) I don't think the "toggle command" should get a different doc string. In particular, it should not get only the generic minor-mode doc string (e.g. how to toggle). It should, as now, describe the mode. And a user should not need to use a different key sequence to get different bits of the relevant doc. What I was suggesting was a bit the other way around: have the specific mode doc have a link to generic doc about toggling etc. Alternatively, include the generic text (no link to it), with an indication that it is what it is: description of the behavior of any minor mode.