From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Philipp Stephani Newsgroups: gmane.emacs.devel Subject: Re: Making DOC argument of define-minor-mode optional Date: Wed, 28 Dec 2016 17:25:11 +0000 Message-ID: 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: multipart/alternative; boundary=001a1146eeaadd179e0544bb40c2 X-Trace: blaine.gmane.org 1482945962 8975 195.159.176.226 (28 Dec 2016 17:26:02 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Wed, 28 Dec 2016 17:26:02 +0000 (UTC) Cc: emacs-devel@gnu.org To: Drew Adams , Nicolas Petton , Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Dec 28 18:25:58 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 1cMHzB-0001Yp-3z for ged-emacs-devel@m.gmane.org; Wed, 28 Dec 2016 18:25:57 +0100 Original-Received: from localhost ([::1]:60262 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cMHzG-0004QW-2a for ged-emacs-devel@m.gmane.org; Wed, 28 Dec 2016 12:26:02 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:59062) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cMHyh-0004PI-24 for emacs-devel@gnu.org; Wed, 28 Dec 2016 12:25:28 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cMHyf-0006pQ-Ur for emacs-devel@gnu.org; Wed, 28 Dec 2016 12:25:27 -0500 Original-Received: from mail-wm0-x231.google.com ([2a00:1450:400c:c09::231]:37938) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1cMHyd-0006pA-Tf; Wed, 28 Dec 2016 12:25:24 -0500 Original-Received: by mail-wm0-x231.google.com with SMTP id k184so118575383wme.1; Wed, 28 Dec 2016 09:25:22 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=QmbIdZqp1pTRnsO7BWGK4s2Xknon/seBagdY46XfusM=; b=GxTBV+Mspu/T82yveDZOrAs4fFyeAqkYF5K/f99yKDuWXOvf8TzPVKL6KKhOKuvZG1 IOK17Cx5vy2bPBZKHYEB96xTUQqVRXrAaNYI27HJFwzXPMcesjWx2KoYrIZzCIQ8Wslk mejezBAJGABCT7UsQ4lGytt5uOk9hFqqZP4AGg6wDuTLVeCcpxxM+4FAv/O/IauALUIB nmQQF80rZN4l3r4koneT8rVvoFz1q0a++DakAB0YjJ6LnVALTrinQJSzJXIlWD3THX0k U2Qcw7dU13R6EU4JxmE3ohXzomG/QuO7CK/iWG5ng9zcLwxbSBAny1yzPY2lfjxXPUdq XdDA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=QmbIdZqp1pTRnsO7BWGK4s2Xknon/seBagdY46XfusM=; b=uIdeHLOgYeOL/98UQPVT8xLqtzA/M+URs/kOhrvx5y5NL6QiNalBIblx4/3EfCRdxE bIxpAs8zX4WhYIDQY35N8Gm/MosEi2ZkzQSq/RIx9R4yeXwDUJd0pH+rnpXl580l+ho8 V6TYnYBmq/rFYrcMWYQ+eXoCM13xk/wOSA/6BVPU5WE3WcEftEtR7WvrZ/1gJQL4BLr1 jlZaYPisCCIxZToWFzKHnqKiRIBIiNWhyMo8w4uz6JsNyLXOS/ZJ00J98LmdwA1fMOwa dJQkv6TBBGZ1a+h+RxXQUAv77jtRjqV605dgJT9RlgYnQUhsyDXedPRg1TkVFWSP1Q+B aR8w== X-Gm-Message-State: AIkVDXJj8a5f6ncKXyS2PKrNKah/V9aaKr34PaKjcemLnFUS9LscOWUdX5areUuTe1qGnQ5vHaNQJG8Ww1w3Bw== X-Received: by 10.28.140.148 with SMTP id o142mr26431669wmd.48.1482945921356; Wed, 28 Dec 2016 09:25:21 -0800 (PST) In-Reply-To: X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2a00:1450:400c:c09::231 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:210912 Archived-At: --001a1146eeaadd179e0544bb40c2 Content-Type: text/plain; charset=UTF-8 Philipp Stephani schrieb am So., 27. Nov. 2016 um 22:13 Uhr: > Drew Adams schrieb am Mi., 23. Nov. 2016 um > 17:35 Uhr: > > > >> the docstring created by define-minor-mode with nil DOC is useful > > >> and often better than what users write. > > >> Should DOC therefore be optional? > > > > > > Not sure we would like to educate Lisp programmers to stop > > > thinking about good doc strings. > > > > I agree. > > Me too. And definers of user-facing things, such as > defcustom and defface, do require DOC. Other definers, > such as defconst and defvar, do not require it. > > On the other hand, OP raises a real issue, I think. > > 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. > > IOW: > > 1. Definers should need to provide a DOC string (even if > they can fake it with "", which is not encouraged). > > 2. Users of the mode should have access to the generic > information also. It should be sufficient that the > DOC in the definition provides mode-specific information. > It should not need to tell users general things about > using a minor mode. > > > That sounds like a good approach. > Do you have a good idea how to design the interface for this? 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. 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. --001a1146eeaadd179e0544bb40c2 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable


Philip= p Stephani <p.stephani2@gmail.c= om> schrieb am So., 27. Nov. 2016 um 22:13=C2=A0Uhr:
Drew Adams <= ;drew.adams@oracle.com> schrieb am Mi., 23. Nov. 2016 um 17:35= =C2=A0Uhr:
> >> the docstring created by define-minor-mode with nil DOC= is useful
> >> and often better than what users write.
> >> Should DOC therefore be optional?
> >
> > Not sure we would like to educate Lisp programmers to stop
> > thinking about good doc strings.
>
> I agree.

Me too.=C2=A0 And definers of user-facing things, such as
defcustom and defface, do require DOC.=C2=A0 Other definers,
such as defconst and defvar, do not require it.

On the other hand, OP raises a real issue, I think.

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.

IOW:

1. Definers should need to provide a DOC string (even if
=C2=A0 =C2=A0they can fake it with "", which is not encouraged).<= br class=3D"gmail_msg">
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.

That sounds like a good approach.
<= div>
Do you have a good idea how to design the interface for = this? I was thinking about something like this: Create a new help type, &qu= ot;mode", analogous to "variable" and "function". = The documentation for the mode would be different from the toggle command a= nd 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.
The primary downside is that many mode docstring= s are written to be applicable to the toggle command. Maybe `define-minor-m= ode' could grow a :doc keyword argument for the mode docstring to prese= rve backward compatibility.=C2=A0
--001a1146eeaadd179e0544bb40c2--