From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: John Shahid Newsgroups: gmane.emacs.bugs Subject: bug#10754: define-minor-mode and doc of derived mode Date: Sun, 17 Jun 2018 19:45:42 +0000 Message-ID: <87d0wpurh5.fsf@gmail.com> References: <87po12g7x4.fsf@gmail.com> <0edf0759-1044-4c6f-b70a-addebc9078f8@default> <87in6trm00.fsf@gmail.com> <83y3ffypek.fsf@gnu.org> <87fu1lv24d.fsf@gmail.com> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Trace: blaine.gmane.org 1529264650 10117 195.159.176.226 (17 Jun 2018 19:44:10 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 17 Jun 2018 19:44:10 +0000 (UTC) User-Agent: mu4e 1.1.0; emacs 27.0.50 Cc: 10754@debbugs.gnu.org To: Stefan Monnier Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Jun 17 21:44:06 2018 Return-path: Envelope-to: geb-bug-gnu-emacs@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 1fUdam-0002Ur-Bp for geb-bug-gnu-emacs@m.gmane.org; Sun, 17 Jun 2018 21:44:04 +0200 Original-Received: from localhost ([::1]:56247 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fUdct-00069l-Jg for geb-bug-gnu-emacs@m.gmane.org; Sun, 17 Jun 2018 15:46:15 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:45269) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fUdcl-00069f-Uq for bug-gnu-emacs@gnu.org; Sun, 17 Jun 2018 15:46:09 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fUdch-0005Pp-1o for bug-gnu-emacs@gnu.org; Sun, 17 Jun 2018 15:46:07 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:46179) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1fUdcg-0005PY-RS for bug-gnu-emacs@gnu.org; Sun, 17 Jun 2018 15:46:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1fUdcg-0002JQ-GW for bug-gnu-emacs@gnu.org; Sun, 17 Jun 2018 15:46:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: John Shahid Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 17 Jun 2018 19:46:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 10754 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 10754-submit@debbugs.gnu.org id=B10754.15292647558872 (code B ref 10754); Sun, 17 Jun 2018 19:46:02 +0000 Original-Received: (at 10754) by debbugs.gnu.org; 17 Jun 2018 19:45:55 +0000 Original-Received: from localhost ([127.0.0.1]:54076 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fUdcZ-0002J1-G4 for submit@debbugs.gnu.org; Sun, 17 Jun 2018 15:45:55 -0400 Original-Received: from mail-qt0-f174.google.com ([209.85.216.174]:40148) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fUdcX-0002In-Oc for 10754@debbugs.gnu.org; Sun, 17 Jun 2018 15:45:54 -0400 Original-Received: by mail-qt0-f174.google.com with SMTP id q6-v6so13492375qtn.7 for <10754@debbugs.gnu.org>; Sun, 17 Jun 2018 12:45:53 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=references:user-agent:from:to:cc:subject:in-reply-to:date :message-id:mime-version; bh=y9cQONtOZ9D5KVP76pQzwAfVdg5i4tGvBYbZ3l84Soo=; b=epyQrxioevqutrYnZckvQdH5RFI1R8BPKCyXM1dBsjiMcX5qhqL/k6eLvRXv8MXFXr RmiWKR9ZvdbSmh8L+v2JaIgcnkFMgF0p6FYEgCD607WIvWGk7haeBsxlc5JykXrlmriR EEjk7irgkm22qx3uhoMSL+/c+O4G0lbdx3k9ARRnM6hDsPpuyY4fAzp2nPk0OY6NY7m1 Ujxi57OkqJB4L7XtQb/0NMEUJH3pFj322mQintTKzEZfdwJ9eVA5L4J+NqGtYqVhK2HP x6LD7HhnJx96K/JpVwSPH1AkI4xVrsFfJ7FSx56l3uRkCHC7vZHxzstQWCqqvneNNjFo wRjA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:references:user-agent:from:to:cc:subject :in-reply-to:date:message-id:mime-version; bh=y9cQONtOZ9D5KVP76pQzwAfVdg5i4tGvBYbZ3l84Soo=; b=hAAFh+TmXGhYfz9dNy6g2ceFHsPuhs+1p8jh3cIiXa2Klo7IIXAk0Y+noWdvTBNLSy KVjTof2GeBwYz6j942RCqppRRtNEjr6bYozYiege/Pr0jnVRsTxu5P5JKmrAXNr8iEP5 fwqq8ixH0FtwNQpazrUnJqUCO+SFZeYemHAjeeVkJTfHwJNv1GijOc2CALhWeYIZFBwf V47PjB87UXzgY0/WVMKbLbd2tujBnNTEofpvhA2NQ1tjOmatqRPP3li4Km05C316ilf5 oawgzJ+rJkY7IoJeR4/XZ28THUpyZt8922o72sQ0gDHN7d1FFjbBu+05jlnBEDGv+37d ELvg== X-Gm-Message-State: APt69E0PNX6cw2BybW1hGxuOofYmuicA4eNfvben0cfKuuSjukb2OczK myZ9+EsSn1VLVI1dFfm4Je4= X-Google-Smtp-Source: ADUXVKKM89TxAvhKcAYk1MZ8aq+ULQgZTIGTqLc98+gpDsY/B21LiDGZSWDPPTnrJNp68YRwuefSag== X-Received: by 2002:aed:3dcb:: with SMTP id j11-v6mr8704329qtf.357.1529264748141; Sun, 17 Jun 2018 12:45:48 -0700 (PDT) Original-Received: from dee925c335f3 (cpe-184-152-55-93.nyc.res.rr.com. [184.152.55.93]) by smtp.gmail.com with ESMTPSA id a12-v6sm10170544qtk.57.2018.06.17.12.45.46 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sun, 17 Jun 2018 12:45:47 -0700 (PDT) In-reply-to: X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:147585 Archived-At: --=-=-= Content-Type: text/plain Stefan Monnier writes: >> I just thought of an alternative approach. Instead of interpolating the >> docstring we could append the extra argument description to the >> docstring ? > > FWIW, it's the approach I would have taken. Great. I changed the patch to append to the docstring instead of interpolate it. I like this approach better, it is cleaner imho. > >> We can add an optional arg to `define-minor-mode'. > > I'd rather avoid it if I can. I meant a keyword argument when I was saying optional. I forgot that `define-minor-mode' takes actual optional arguments. I attached the new patch, below. If this looks good, I will amend the patch to include other minor modes. --=-=-= Content-Type: text/x-diff Content-Disposition: inline; filename=0001-optionally-include-argument-description-in-minor-mod.patch >From d0e79015e211b5389c08c39f8fbe3044ab3a7de3 Mon Sep 17 00:00:00 2001 From: John Shahid Date: Tue, 5 Jun 2018 19:56:12 -0400 Subject: [PATCH] optionally include argument description in minor mode DOC * easy-mmode.el (define-minor-mode): add a new option `append-arg-docstring' to append DOC with documentation of the mode argument * linum.el (linum-mode): set append-arg-docstring to t --- lisp/emacs-lisp/easy-mmode.el | 32 +++++++++++++++++++++++++------- lisp/linum.el | 4 +--- 2 files changed, 26 insertions(+), 10 deletions(-) diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el index a81b6fefb2..7701842a94 100644 --- a/lisp/emacs-lisp/easy-mmode.el +++ b/lisp/emacs-lisp/easy-mmode.el @@ -81,6 +81,25 @@ easy-mmode-pretty-mode-name ;; space.) (replace-regexp-in-string (regexp-quote lighter) lighter name t t)))) +(defconst easy-mmode-arg-docstring + "If called interactively, enable %s if ARG is positive, and +disable it otherwise. If called from Lisp, enable the mode if +ARG is omitted or nil, and toggle it if ARG is `toggle'. Disable +the mode otherwise") + +(defun easy-mmode-mode-docstring (doc mode-pretty-name keymap-sym append-arg-docstring) + (unless doc + (setq append-arg-docstring t) + (setq doc (format "Toggle %s on or off. +\\{%s}" mode-pretty-name keymap-sym))) + (if append-arg-docstring + (concat doc + "\n\n" + (format easy-mmode-arg-docstring + mode-pretty-name + mode-pretty-name)) + doc)) + ;;;###autoload (defalias 'easy-mmode-define-minor-mode 'define-minor-mode) ;;;###autoload @@ -101,7 +120,9 @@ define-minor-mode if the argument is omitted or nil or a positive integer). If DOC is nil, give the mode command a basic doc-string -documenting what its argument does. +documenting what its argument does. All occurences of the string +\"%{arg}\" in DOC will be replaced by a docstring explaining +usages of the mode argument. Optional INIT-VALUE is the initial value of the mode's variable. Optional LIGHTER is displayed in the mode line when the mode is on. @@ -179,6 +200,7 @@ define-minor-mode (group nil) (type nil) (extra-args nil) + (append-arg-docstring nil) (extra-keywords nil) (variable nil) ;The PLACE where the state is stored. (setter `(setq ,mode)) ;The beginning of the exp to set the mode var. @@ -201,6 +223,7 @@ define-minor-mode (when (and globalp (symbolp mode)) (setq setter `(setq-default ,mode)) (setq getter `(default-value ',mode)))) + (`:append-arg-docstring (setq append-arg-docstring t)) (`:extra-args (setq extra-args (pop body))) (`:set (setq set (list :set (pop body)))) (`:initialize (setq initialize (list :initialize (pop body)))) @@ -270,12 +293,7 @@ define-minor-mode ;; The actual function. (defun ,modefun (&optional arg ,@extra-args) - ,(or doc - (format (concat "Toggle %s on or off. -With a prefix argument ARG, enable %s if ARG is -positive, and disable it otherwise. If called from Lisp, enable -the mode if ARG is omitted or nil, and toggle it if ARG is `toggle'. -\\{%s}") pretty-name pretty-name keymap-sym)) + ,(easy-mmode-mode-docstring doc pretty-name keymap-sym append-arg-docstring) ;; Use `toggle' rather than (if ,mode 0 1) so that using ;; repeat-command still does the toggling correctly. (interactive (list (or current-prefix-arg 'toggle))) diff --git a/lisp/linum.el b/lisp/linum.el index 9df0c5d023..6e673e58b0 100644 --- a/lisp/linum.el +++ b/lisp/linum.el @@ -75,12 +75,10 @@ linum-delay ;;;###autoload (define-minor-mode linum-mode "Toggle display of line numbers in the left margin (Linum mode). -With a prefix argument ARG, enable Linum mode if ARG is positive, -and disable it otherwise. If called from Lisp, enable the mode -if ARG is omitted or nil. Linum mode is a buffer-local minor mode." :lighter "" ; for desktop.el + :append-arg-docstring t (if linum-mode (progn (if linum-eager -- 2.17.1 --=-=-=--