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/major-mode-conventions.html | 37 +++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)
 create mode 100644 devdocs/elisp/major-mode-conventions.html

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

diff --git a/devdocs/elisp/major-mode-conventions.html b/devdocs/elisp/major-mode-conventions.html
new file mode 100644
index 00000000..a1f96033
--- /dev/null
+++ b/devdocs/elisp/major-mode-conventions.html
@@ -0,0 +1,37 @@
+ <h4 class="subsection">Major Mode Conventions</h4>   <p>The code for every major mode should follow various coding conventions, including conventions for local keymap and syntax table initialization, function and variable names, and hooks. </p> <p>If you use the <code>define-derived-mode</code> macro, it will take care of many of these conventions automatically. See <a href="derived-modes">Derived Modes</a>. Note also that Fundamental mode is an exception to many of these conventions, because it represents the default state of Emacs. </p> <p>The following list of conventions is only partial. Each major mode should aim for consistency in general with other Emacs major modes, as this makes Emacs as a whole more coherent. It is impossible to list here all the possible points where this issue might come up; if the Emacs developers point out an area where your major mode deviates from the usual conventions, please make it compatible. </p> <ul> <li> Define a major mode command whose name ends in ‘<samp>-mode</samp>’. When called with no arguments, this command should switch to the new mode in the current buffer by setting up the keymap, syntax table, and buffer-local variables in an existing buffer. It should not change the buffer’s contents. </li>
+<li> Write a documentation string for this command that describes the special commands available in this mode. See <a href="mode-help">Mode Help</a>. <p>The documentation string may include the special documentation substrings, ‘<samp>\[<var>command</var>]</samp>’, ‘<samp>\{<var>keymap</var>}</samp>’, and ‘<samp>\&lt;<var>keymap</var>&gt;</samp>’, which allow the help display to adapt automatically to the user’s own key bindings. See <a href="keys-in-documentation">Keys in Documentation</a>. </p> </li>
+<li> The major mode command should start by calling <code>kill-all-local-variables</code>. This runs the normal hook <code>change-major-mode-hook</code>, then gets rid of the buffer-local variables of the major mode previously in effect. See <a href="creating-buffer_002dlocal">Creating Buffer-Local</a>. </li>
+<li> The major mode command should set the variable <code>major-mode</code> to the major mode command symbol. This is how <code>describe-mode</code> discovers which documentation to print. </li>
+<li> The major mode command should set the variable <code>mode-name</code> to the “pretty” name of the mode, usually a string (but see <a href="mode-line-data">Mode Line Data</a>, for other possible forms). The name of the mode appears in the mode line. </li>
+<li> Calling the major mode command twice in direct succession should not fail and should do the same thing as calling the command only once. In other words, the major mode command should be idempotent. </li>
+<li>  Since all global names are in the same name space, all the global variables, constants, and functions that are part of the mode should have names that start with the major mode name (or with an abbreviation of it if the name is long). See <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Coding-Conventions.html">Coding Conventions</a>. </li>
+<li> In a major mode for editing some kind of structured text, such as a programming language, indentation of text according to structure is probably useful. So the mode should set <code>indent-line-function</code> to a suitable function, and probably customize other variables for indentation. See <a href="auto_002dindentation">Auto-Indentation</a>. </li>
+<li>  The major mode should usually have its own keymap, which is used as the local keymap in all buffers in that mode. The major mode command should call <code>use-local-map</code> to install this local map. See <a href="active-keymaps">Active Keymaps</a>, for more information. <p>This keymap should be stored permanently in a global variable named <code><var>modename</var>-mode-map</code>. Normally the library that defines the mode sets this variable. </p> <p>See <a href="tips-for-defining">Tips for Defining</a>, for advice about how to write the code to set up the mode’s keymap variable. </p> </li>
+<li> The key sequences bound in a major mode keymap should usually start with <kbd>C-c</kbd>, followed by a control character, a digit, or <kbd>{</kbd>, <kbd>}</kbd>, <kbd>&lt;</kbd>, <kbd>&gt;</kbd>, <kbd>:</kbd> or <kbd>;</kbd>. The other punctuation characters are reserved for minor modes, and ordinary letters are reserved for users. <p>A major mode can also rebind the keys <kbd>M-n</kbd>, <kbd>M-p</kbd> and <kbd>M-s</kbd>. The bindings for <kbd>M-n</kbd> and <kbd>M-p</kbd> should normally be some kind of moving forward and backward, but this does not necessarily mean cursor motion. </p> <p>It is legitimate for a major mode to rebind a standard key sequence if it provides a command that does the same job in a way better suited to the text this mode is used for. For example, a major mode for editing a programming language might redefine <kbd>C-M-a</kbd> to move to the beginning of a function in a way that works better for that language. The recommended way of tailoring <kbd>C-M-a</kbd> to the needs of a major mode is to set <code>beginning-of-defun-function</code> (see <a href="list-motion">List Motion</a>) to invoke the function specific to the mode. </p> <p>It is also legitimate for a major mode to rebind a standard key sequence whose standard meaning is rarely useful in that mode. For instance, minibuffer modes rebind <kbd>M-r</kbd>, whose standard meaning is rarely of any use in the minibuffer. Major modes such as Dired or Rmail that do not allow self-insertion of text can reasonably redefine letters and other printing characters as special commands. </p> </li>
+<li> Major modes for editing text should not define <tt class="key">RET</tt> to do anything other than insert a newline. However, it is ok for specialized modes for text that users don’t directly edit, such as Dired and Info modes, to redefine <tt class="key">RET</tt> to do something entirely different. </li>
+<li> Major modes should not alter options that are primarily a matter of user preference, such as whether Auto-Fill mode is enabled. Leave this to each user to decide. However, a major mode should customize other variables so that Auto-Fill mode will work usefully <em>if</em> the user decides to use it. </li>
+<li>  The mode may have its own syntax table or may share one with other related modes. If it has its own syntax table, it should store this in a variable named <code><var>modename</var>-mode-syntax-table</code>. See <a href="syntax-tables">Syntax Tables</a>. </li>
+<li> If the mode handles a language that has a syntax for comments, it should set the variables that define the comment syntax. See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Options-for-Comments.html#Options-for-Comments">Options Controlling Comments</a> in <cite>The GNU Emacs Manual</cite>. </li>
+<li>  The mode may have its own abbrev table or may share one with other related modes. If it has its own abbrev table, it should store this in a variable named <code><var>modename</var>-mode-abbrev-table</code>. If the major mode command defines any abbrevs itself, it should pass <code>t</code> for the <var>system-flag</var> argument to <code>define-abbrev</code>. See <a href="defining-abbrevs">Defining Abbrevs</a>. </li>
+<li> The mode should specify how to do highlighting for Font Lock mode, by setting up a buffer-local value for the variable <code>font-lock-defaults</code> (see <a href="font-lock-mode">Font Lock Mode</a>). </li>
+<li> Each face that the mode defines should, if possible, inherit from an existing Emacs face. See <a href="basic-faces">Basic Faces</a>, and <a href="faces-for-font-lock">Faces for Font Lock</a>. </li>
+<li> Consider adding a mode-specific menu to the menu bar. This should preferably include the most important menu-specific settings and commands that will allow users discovering the main features quickly and efficiently. </li>
+<li>   Consider adding mode-specific context menus for the mode, to be used if and when users activate the <code>context-menu-mode</code> (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Menu-Mouse-Clicks.html#Menu-Mouse-Clicks">Menu Mouse Clicks</a> in <cite>The Emacs Manual</cite>). To this end, define a mode-specific function which builds one or more menus depending on the location of the <kbd>mouse-3</kbd> click in the buffer, and then add that function to the buffer-local value of <code>context-menu-functions</code>. </li>
+<li> The mode should specify how Imenu should find the definitions or sections of a buffer, by setting up a buffer-local value for the variable <code>imenu-generic-expression</code>, for the two variables <code>imenu-prev-index-position-function</code> and <code>imenu-extract-index-name-function</code>, or for the variable <code>imenu-create-index-function</code> (see <a href="imenu">Imenu</a>). </li>
+<li> The mode can tell ElDoc mode how to retrieve different types of documentation for whatever is at point, by adding one or more buffer-local entries to the special hook <code>eldoc-documentation-functions</code>. </li>
+<li> The mode can specify how to complete various keywords by adding one or more buffer-local entries to the special hook <code>completion-at-point-functions</code>. See <a href="completion-in-buffers">Completion in Buffers</a>. </li>
+<li>  To make a buffer-local binding for an Emacs customization variable, use <code>make-local-variable</code> in the major mode command, not <code>make-variable-buffer-local</code>. The latter function would make the variable local to every buffer in which it is subsequently set, which would affect buffers that do not use this mode. It is undesirable for a mode to have such global effects. See <a href="buffer_002dlocal-variables">Buffer-Local Variables</a>. <p>With rare exceptions, the only reasonable way to use <code>make-variable-buffer-local</code> in a Lisp package is for a variable which is used only within that package. Using it on a variable used by other packages would interfere with them. </p> </li>
+<li>   Each major mode should have a normal <em>mode hook</em> named <code><var>modename</var>-mode-hook</code>. The very last thing the major mode command should do is to call <code>run-mode-hooks</code>. This runs the normal hook <code>change-major-mode-after-body-hook</code>, the mode hook, the function <code>hack-local-variables</code> (when the buffer is visiting a file), and then the normal hook <code>after-change-major-mode-hook</code>. See <a href="mode-hooks">Mode Hooks</a>. </li>
+<li> The major mode command may start by calling some other major mode command (called the <em>parent mode</em>) and then alter some of its settings. A mode that does this is called a <em>derived mode</em>. The recommended way to define one is to use the <code>define-derived-mode</code> macro, but this is not required. Such a mode should call the parent mode command inside a <code>delay-mode-hooks</code> form. (Using <code>define-derived-mode</code> does this automatically.) See <a href="derived-modes">Derived Modes</a>, and <a href="mode-hooks">Mode Hooks</a>. </li>
+<li> If something special should be done if the user switches a buffer from this mode to any other major mode, this mode can set up a buffer-local value for <code>change-major-mode-hook</code> (see <a href="creating-buffer_002dlocal">Creating Buffer-Local</a>). </li>
+<li> If this mode is appropriate only for specially-prepared text produced by the mode itself (rather than by the user typing at the keyboard or by an external file), then the major mode command symbol should have a property named <code>mode-class</code> with value <code>special</code>, put on as follows:   <div class="example"> <pre class="example">(put 'funny-mode 'mode-class 'special)
+</pre>
+</div> <p>This tells Emacs that new buffers created while the current buffer is in Funny mode should not be put in Funny mode, even though the default value of <code>major-mode</code> is <code>nil</code>. By default, the value of <code>nil</code> for <code>major-mode</code> means to use the current buffer’s major mode when creating new buffers (see <a href="auto-major-mode">Auto Major Mode</a>), but with such <code>special</code> modes, Fundamental mode is used instead. Modes such as Dired, Rmail, and Buffer List use this feature. </p> <p>The function <code>view-buffer</code> does not enable View mode in buffers whose mode-class is special, because such modes usually provide their own View-like bindings. </p> <p>The <code>define-derived-mode</code> macro automatically marks the derived mode as special if the parent mode is special. Special mode is a convenient parent for such modes to inherit from; See <a href="basic-major-modes">Basic Major Modes</a>. </p> </li>
+<li> If you want to make the new mode the default for files with certain recognizable names, add an element to <code>auto-mode-alist</code> to select the mode for those file names (see <a href="auto-major-mode">Auto Major Mode</a>). If you define the mode command to autoload, you should add this element in the same file that calls <code>autoload</code>. If you use an autoload cookie for the mode command, you can also use an autoload cookie for the form that adds the element (see <a href="autoload#autoload-cookie">autoload cookie</a>). If you do not autoload the mode command, it is sufficient to add the element in the file that contains the mode definition. </li>
+<li>  The top-level forms in the file defining the mode should be written so that they may be evaluated more than once without adverse consequences. For instance, use <code>defvar</code> or <code>defcustom</code> to set mode-related variables, so that they are not reinitialized if they already have a value (see <a href="defining-variables">Defining Variables</a>). </li>
+</ul><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/Major-Mode-Conventions.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Major-Mode-Conventions.html</a>
+  </p>
+</div>
-- 
cgit v1.2.3