1 files changed, 30 insertions, 0 deletions
diff --git a/devdocs/elisp/derived-modes.html b/devdocs/elisp/derived-modes.html
new file mode 100644
index 00000000..ce3417bd
--- /dev/null
+++ b/devdocs/elisp/derived-modes.html
@@ -0,0 +1,30 @@
+ <h4 class="subsection">Defining Derived Modes</h4>  <p>The recommended way to define a new major mode is to derive it from an existing one using <code>define-derived-mode</code>. If there is no closely related mode, you should inherit from either <code>text-mode</code>, <code>special-mode</code>, or <code>prog-mode</code>. See <a href="basic-major-modes">Basic Major Modes</a>. If none of these are suitable, you can inherit from <code>fundamental-mode</code> (see <a href="major-modes">Major Modes</a>). </p> <dl> <dt id="define-derived-mode">Macro: <strong>define-derived-mode</strong> <em>variant parent name docstring keyword-args… body…</em>
+</dt> <dd>
+<p>This macro defines <var>variant</var> as a major mode command, using <var>name</var> as the string form of the mode name. <var>variant</var> and <var>parent</var> should be unquoted symbols. </p> <p>The new command <var>variant</var> is defined to call the function <var>parent</var>, then override certain aspects of that parent mode: </p> <ul> <li> The new mode has its own sparse keymap, named <code><var>variant</var>-map</code>. <code>define-derived-mode</code> makes the parent mode’s keymap the parent of the new map, unless <code><var>variant</var>-map</code> is already set and already has a parent. </li>
+<li> The new mode has its own syntax table, kept in the variable <code><var>variant</var>-syntax-table</code>, unless you override this using the <code>:syntax-table</code> keyword (see below). <code>define-derived-mode</code> makes the parent mode’s syntax-table the parent of <code><var>variant</var>-syntax-table</code>, unless the latter is already set and already has a parent different from the standard syntax table. </li>
+<li> The new mode has its own abbrev table, kept in the variable <code><var>variant</var>-abbrev-table</code>, unless you override this using the <code>:abbrev-table</code> keyword (see below). </li>
+<li> The new mode has its own mode hook, <code><var>variant</var>-hook</code>. It runs this hook, after running the hooks of its ancestor modes, with <code>run-mode-hooks</code>, as the last thing it does, apart from running any <code>:after-hook</code> form it may have. See <a href="mode-hooks">Mode Hooks</a>. </li>
+</ul> <p>In addition, you can specify how to override other aspects of <var>parent</var> with <var>body</var>. The command <var>variant</var> evaluates the forms in <var>body</var> after setting up all its usual overrides, just before running the mode hooks. </p> <p>If <var>parent</var> has a non-<code>nil</code> <code>mode-class</code> symbol property, then <code>define-derived-mode</code> sets the <code>mode-class</code> property of <var>variant</var> to the same value. This ensures, for example, that if <var>parent</var> is a special mode, then <var>variant</var> is also a special mode (see <a href="major-mode-conventions">Major Mode Conventions</a>). </p> <p>You can also specify <code>nil</code> for <var>parent</var>. This gives the new mode no parent. Then <code>define-derived-mode</code> behaves as described above, but, of course, omits all actions connected with <var>parent</var>. </p> <p>The argument <var>docstring</var> specifies the documentation string for the new mode. <code>define-derived-mode</code> adds some general information about the mode’s hook, followed by the mode’s keymap, at the end of this documentation string. If you omit <var>docstring</var>, <code>define-derived-mode</code> generates a documentation string. </p> <p>The <var>keyword-args</var> are pairs of keywords and values. The values, except for <code>:after-hook</code>’s, are evaluated. The following keywords are currently supported: </p> <dl compact> <dt><code>:syntax-table</code></dt> <dd>
+<p>You can use this to explicitly specify a syntax table for the new mode. If you specify a <code>nil</code> value, the new mode uses the same syntax table as <var>parent</var>, or the standard syntax table if <var>parent</var> is <code>nil</code>. (Note that this does <em>not</em> follow the convention used for non-keyword arguments that a <code>nil</code> value is equivalent with not specifying the argument.) </p> </dd> <dt><code>:abbrev-table</code></dt> <dd>
+<p>You can use this to explicitly specify an abbrev table for the new mode. If you specify a <code>nil</code> value, the new mode uses the same abbrev table as <var>parent</var>, or <code>fundamental-mode-abbrev-table</code> if <var>parent</var> is <code>nil</code>. (Again, a <code>nil</code> value is <em>not</em> equivalent to not specifying this keyword.) </p> </dd> <dt><code>:interactive</code></dt> <dd>
+<p>Modes are interactive commands by default. If you specify a <code>nil</code> value, the mode defined here won’t be interactive. This is useful for modes that are never meant to be activated by users manually, but are only supposed to be used in some specially-formatted buffer. </p> </dd> <dt><code>:group</code></dt> <dd>
+<p>If this is specified, the value should be the customization group for this mode. (Not all major modes have one.) The command <code>customize-mode</code> uses this. <code>define-derived-mode</code> does <em>not</em> automatically define the specified customization group. </p> </dd> <dt><code>:after-hook</code></dt> <dd><p>This optional keyword specifies a single Lisp form to evaluate as the final act of the mode function, after the mode hooks have been run. It should not be quoted. Since the form might be evaluated after the mode function has terminated, it should not access any element of the mode function’s local state. An <code>:after-hook</code> form is useful for setting up aspects of the mode which depend on the user’s settings, which in turn may have been changed in a mode hook. </p></dd> </dl> <p>Here is a hypothetical example: </p> <div class="example"> <pre class="example">(defvar hypertext-mode-map
+  (let ((map (make-sparse-keymap)))
+    (define-key map [down-mouse-3] 'do-hyper-link)
+    map))
+
+(define-derived-mode hypertext-mode
+  text-mode "Hypertext"
+  "Major mode for hypertext."
+  (setq-local case-fold-search nil))
+</pre>
+</div> <p>Do not write an <code>interactive</code> spec in the definition; <code>define-derived-mode</code> does that automatically. </p>
+</dd>
+</dl> <dl> <dt id="derived-mode-p">Function: <strong>derived-mode-p</strong> <em>&amp;rest modes</em>
+</dt> <dd><p>This function returns non-<code>nil</code> if the current major mode is derived from any of the major modes given by the symbols <var>modes</var>. </p></dd>
+</dl><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/Derived-Modes.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Derived-Modes.html</a>
+  </p>
+</div>