GNU bug report logs - #10754
define-minor-mode and doc of derived mode

Previous Next

Full log

View this message in rfc822 format

From: John Shahid <jvshahid <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: Glenn Morris <rgm <at> gnu.org>, 10754 <at> debbugs.gnu.org
Subject: bug#10754: define-minor-mode and doc of derived mode
Date: Fri, 08 Jun 2018 21:45:03 +0000

[Message part 1 (text/plain, inline)]

attached a poc patch. wdyt ?

[0001-allow-interpolation-of-arg-in-define-minor-mode-DOC.patch (text/x-diff, inline)]

From 1a1efd1417356d26dd818622497512c28005f03c Mon Sep 17 00:00:00 2001
From: John Shahid <jvshahid <at> gmail.com>
Date: Tue, 5 Jun 2018 19:56:12 -0400
Subject: [PATCH] allow interpolation of %{arg} in define-minor-mode DOC

* easy-mmode.el (define-minor-mode): interpolate %{arg} in DOC with
  documentation of the mode argument
* linum.el (linum-mode): use %{arg} in the docstring
---
 lisp/emacs-lisp/easy-mmode.el | 28 +++++++++++++++++++++-------
 lisp/linum.el                 |  4 +---
 2 files changed, 22 insertions(+), 10 deletions(-)

diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el
index a81b6fefb2..8d5dd39ea3 100644
--- a/lisp/emacs-lisp/easy-mmode.el
+++ b/lisp/emacs-lisp/easy-mmode.el
@@ -81,6 +81,23 @@ easy-mmode-pretty-mode-name
       ;; space.)
       (replace-regexp-in-string (regexp-quote lighter) lighter name t t))))
 
+(defconst easy-mmode-arg-docstring
+  "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'. Disable
+the mode otherwise")
+
+(defun easy-mmode-mode-docstring (doc mode-pretty-name keymap-sym)
+  (let ((doc (or doc
+                 (format "Toggle %s on or off.
+%%{arg}.
+\\{%s}" mode-pretty-name keymap-sym))))
+  (replace-regexp-in-string "%{arg}"
+                              (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 +118,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.
@@ -270,12 +289,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)
 	 ;; 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..6a0baf40a6 100644
--- a/lisp/linum.el
+++ b/lisp/linum.el
@@ -75,9 +75,7 @@ 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.
+%{arg}.
 
 Linum mode is a buffer-local minor mode."
   :lighter ""                           ; for desktop.el
-- 
2.17.1

Previous Next

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