From 754bbf7a25a8dda49b5d08ef0d0443bbf5af0e36 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Sun, 7 Apr 2024 13:41:34 -0500
Subject: new repository

---
 devdocs/elisp/minor-mode-conventions.html | 41 +++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)
 create mode 100644 devdocs/elisp/minor-mode-conventions.html

(limited to 'devdocs/elisp/minor-mode-conventions.html')

diff --git a/devdocs/elisp/minor-mode-conventions.html b/devdocs/elisp/minor-mode-conventions.html
new file mode 100644
index 00000000..ab711037
--- /dev/null
+++ b/devdocs/elisp/minor-mode-conventions.html
@@ -0,0 +1,41 @@
+ <h4 class="subsection">Conventions for Writing Minor Modes</h4>   <p>There are conventions for writing minor modes just as there are for major modes (see <a href="major-modes">Major Modes</a>). These conventions are described below. The easiest way to follow them is to use the macro <code>define-minor-mode</code>. See <a href="defining-minor-modes">Defining Minor Modes</a>. </p> <ul> <li>  Define a variable whose name ends in ‘<samp>-mode</samp>’. We call this the <em>mode variable</em>. The minor mode command should set this variable. The value will be <code>nil</code> if the mode is disabled, and non-<code>nil</code> if the mode is enabled. The variable should be buffer-local if the minor mode is buffer-local. <p>This variable is used in conjunction with the <code>minor-mode-alist</code> to display the minor mode name in the mode line. It also determines whether the minor mode keymap is active, via <code>minor-mode-map-alist</code> (see <a href="controlling-active-maps">Controlling Active Maps</a>). Individual commands or hooks can also check its value. </p> </li>
+<li> Define a command, called the <em>mode command</em>, whose name is the same as the mode variable. Its job is to set the value of the mode variable, plus anything else that needs to be done to actually enable or disable the mode’s features. <p>The mode command should accept one optional argument. If called interactively with no prefix argument, it should toggle the mode (i.e., enable if it is disabled, and disable if it is enabled). If called interactively with a prefix argument, it should enable the mode if the argument is positive and disable it otherwise. </p> <p>If the mode command is called from Lisp (i.e., non-interactively), it should enable the mode if the argument is omitted or <code>nil</code>; it should toggle the mode if the argument is the symbol <code>toggle</code>; otherwise it should treat the argument in the same way as for an interactive call with a numeric prefix argument, as described above. </p> <p>The following example shows how to implement this behavior (it is similar to the code generated by the <code>define-minor-mode</code> macro): </p> <div class="example"> <pre class="example">(interactive (list (or current-prefix-arg 'toggle)))
+(let ((enable
+       (if (eq arg 'toggle)
+           (not foo-mode) ; <span class="roman">this is the mode’s mode variable</span>
+         (&gt; (prefix-numeric-value arg) 0))))
+  (if enable
+      <var>do-enable</var>
+    <var>do-disable</var>))
+</pre>
+</div> <p>The reason for this somewhat complex behavior is that it lets users easily toggle the minor mode interactively, and also lets the minor mode be easily enabled in a mode hook, like this: </p> <div class="example"> <pre class="example">(add-hook 'text-mode-hook 'foo-mode)
+</pre>
+</div> <p>This behaves correctly whether or not <code>foo-mode</code> was already enabled, since the <code>foo-mode</code> mode command unconditionally enables the minor mode when it is called from Lisp with no argument. Disabling a minor mode in a mode hook is a little uglier: </p> <div class="example"> <pre class="example">(add-hook 'text-mode-hook (lambda () (foo-mode -1)))
+</pre>
+</div> <p>However, this is not very commonly done. </p> <p>Enabling or disabling a minor mode twice in direct succession should not fail and should do the same thing as enabling or disabling it only once. In other words, the minor mode command should be idempotent. </p> </li>
+<li> Add an element to <code>minor-mode-alist</code> for each minor mode (see <a href="mode-line-variables#Definition-of-minor_002dmode_002dalist">Definition of minor-mode-alist</a>), if you want to indicate the minor mode in the mode line. This element should be a list of the following form: <div class="example"> <pre class="example">(<var>mode-variable</var> <var>string</var>)
+</pre>
+</div> <p>Here <var>mode-variable</var> is the variable that controls enabling of the minor mode, and <var>string</var> is a short string, starting with a space, to represent the mode in the mode line. These strings must be short so that there is room for several of them at once. </p> <p>When you add an element to <code>minor-mode-alist</code>, use <code>assq</code> to check for an existing element, to avoid duplication. For example: </p> <div class="example"> <pre class="example">(unless (assq 'leif-mode minor-mode-alist)
+  (push '(leif-mode " Leif") minor-mode-alist))
+</pre>
+</div> <p>or like this, using <code>add-to-list</code> (see <a href="list-variables">List Variables</a>): </p> <div class="example"> <pre class="example">(add-to-list 'minor-mode-alist '(leif-mode " Leif"))
+</pre>
+</div> </li>
+</ul> <p>In addition, several major mode conventions (see <a href="major-mode-conventions">Major Mode Conventions</a>) apply to minor modes as well: those regarding the names of global symbols, the use of a hook at the end of the initialization function, and the use of keymaps and other tables. </p> <p>The minor mode should, if possible, support enabling and disabling via Custom (see <a href="customization">Customization</a>). To do this, the mode variable should be defined with <code>defcustom</code>, usually with <code>:type 'boolean</code>. If just setting the variable is not sufficient to enable the mode, you should also specify a <code>:set</code> method which enables the mode by invoking the mode command. Note in the variable’s documentation string that setting the variable other than via Custom may not take effect. Also, mark the definition with an autoload cookie (see <a href="autoload#autoload-cookie">autoload cookie</a>), and specify a <code>:require</code> so that customizing the variable will load the library that defines the mode. For example: </p> <div class="example"> <pre class="example">;;;###autoload
+(defcustom msb-mode nil
+  "Toggle msb-mode.
+Setting this variable directly does not take effect;
+use either \\[customize] or the function `msb-mode'."
+  :set 'custom-set-minor-mode
+  :initialize 'custom-initialize-default
+  :version "20.4"
+  :type    'boolean
+  :group   'msb
+  :require 'msb)
+</pre>
+</div><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
+    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Minor-Mode-Conventions.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Minor-Mode-Conventions.html</a>
+  </p>
+</div>
-- 
cgit v1.2.3