new repository

1 files changed, 81 insertions, 0 deletions

diff --git a/devdocs/elisp/changing-key-bindings.html b/devdocs/elisp/changing-key-bindings.html
new file mode 100644
index 00000000..61e5f3c7
--- /dev/null
+++ b/devdocs/elisp/changing-key-bindings.html
@@ -0,0 +1,81 @@
+ <h3 class="section">Changing Key Bindings</h3>   <p>The way to rebind a key is to change its entry in a keymap. If you change a binding in the global keymap, the change is effective in all buffers (though it has no direct effect in buffers that shadow the global binding with a local one). If you change the current buffer’s local map, that usually affects all buffers using the same major mode. The <code>global-set-key</code> and <code>local-set-key</code> functions are convenient interfaces for these operations (see <a href="key-binding-commands">Key Binding Commands</a>). You can also use <code>define-key</code>, a more general function; then you must explicitly specify the map to change. </p> <p>When choosing the key sequences for Lisp programs to rebind, please follow the Emacs conventions for use of various keys (see <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Key-Binding-Conventions.html">Key Binding Conventions</a>). </p>   <p>In writing the key sequence to rebind, it is good to use the special escape sequences for control and meta characters (see <a href="string-type">String Type</a>). The syntax ‘<samp>\C-</samp>’ means that the following character is a control character and ‘<samp>\M-</samp>’ means that the following character is a meta character. Thus, the string <code>"\M-x"</code> is read as containing a single <kbd>M-x</kbd>, <code>"\C-f"</code> is read as containing a single <kbd>C-f</kbd>, and <code>"\M-\C-x"</code> and <code>"\C-\M-x"</code> are both read as containing a single <kbd>C-M-x</kbd>. You can also use this escape syntax in vectors, as well as others that aren’t allowed in strings; one example is ‘<samp>[?\C-\H-x home]</samp>’. See <a href="character-type">Character Type</a>. </p> <p>The key definition and lookup functions accept an alternate syntax for event types in a key sequence that is a vector: you can use a list containing modifier names plus one base event (a character or function key name). For example, <code>(control ?a)</code> is equivalent to <code>?\C-a</code> and <code>(hyper control left)</code> is equivalent to <code>C-H-left</code>. One advantage of such lists is that the precise numeric codes for the modifier bits don’t appear in compiled files. </p> <p>The functions below signal an error if <var>keymap</var> is not a keymap, or if <var>key</var> is not a string or vector representing a key sequence. You can use event types (symbols) as shorthand for events that are lists. The <code>kbd</code> function (see <a href="key-sequences">Key Sequences</a>) is a convenient way to specify the key sequence. </p> <dl> <dt id="define-key">Function: <strong>define-key</strong> <em>keymap key binding</em>
+</dt> <dd>
+<p>This function sets the binding for <var>key</var> in <var>keymap</var>. (If <var>key</var> is more than one event long, the change is actually made in another keymap reached from <var>keymap</var>.) The argument <var>binding</var> can be any Lisp object, but only certain types are meaningful. (For a list of meaningful types, see <a href="key-lookup">Key Lookup</a>.) The value returned by <code>define-key</code> is <var>binding</var>. </p> <p>If <var>key</var> is <code>[t]</code>, this sets the default binding in <var>keymap</var>. When an event has no binding of its own, the Emacs command loop uses the keymap’s default binding, if there is one. </p>   <p>Every prefix of <var>key</var> must be a prefix key (i.e., bound to a keymap) or undefined; otherwise an error is signaled. If some prefix of <var>key</var> is undefined, then <code>define-key</code> defines it as a prefix key so that the rest of <var>key</var> can be defined as specified. </p> <p>If there was previously no binding for <var>key</var> in <var>keymap</var>, the new binding is added at the beginning of <var>keymap</var>. The order of bindings in a keymap makes no difference for keyboard input, but it does matter for menu keymaps (see <a href="menu-keymaps">Menu Keymaps</a>). </p>
+</dd>
+</dl> <p>This example creates a sparse keymap and makes a number of bindings in it: </p> <div class="example"> <pre class="example">(setq map (make-sparse-keymap))
+    ⇒ (keymap)
+</pre>
+<pre class="example">(define-key map "\C-f" 'forward-char)
+    ⇒ forward-char
+</pre>
+<pre class="example">map
+    ⇒ (keymap (6 . forward-char))
+</pre>
+
+<pre class="example">;; <span class="roman">Build sparse submap for <kbd>C-x</kbd> and bind <kbd>f</kbd> in that.</span>
+(define-key map (kbd "C-x f") 'forward-word)
+    ⇒ forward-word
+</pre>
+<pre class="example">map
+⇒ (keymap
+    (24 keymap                ; <kbd>C-x</kbd>
+        (102 . forward-word)) ;      <kbd>f</kbd>
+    (6 . forward-char))       ; <kbd>C-f</kbd>
+</pre>
+
+<pre class="example">;; <span class="roman">Bind <kbd>C-p</kbd> to the <code>ctl-x-map</code>.</span>
+(define-key map (kbd "C-p") ctl-x-map)
+;; <code>ctl-x-map</code>
+⇒ [nil … find-file … backward-kill-sentence]
+</pre>
+
+<pre class="example">;; <span class="roman">Bind <kbd>C-f</kbd> to <code>foo</code> in the <code>ctl-x-map</code>.</span>
+(define-key map (kbd "C-p C-f") 'foo)
+⇒ 'foo
+</pre>
+<pre class="example">map
+⇒ (keymap     ; <span class="roman">Note <code>foo</code> in <code>ctl-x-map</code>.</span>
+    (16 keymap [nil … foo … backward-kill-sentence])
+    (24 keymap
+        (102 . forward-word))
+    (6 . forward-char))
+</pre>
+</div> <p>Note that storing a new binding for <kbd>C-p C-f</kbd> actually works by changing an entry in <code>ctl-x-map</code>, and this has the effect of changing the bindings of both <kbd>C-p C-f</kbd> and <kbd>C-x C-f</kbd> in the default global map. </p> <p>The function <code>substitute-key-definition</code> scans a keymap for keys that have a certain binding and rebinds them with a different binding. Another feature which is cleaner and can often produce the same results is to remap one command into another (see <a href="remapping-commands">Remapping Commands</a>). </p> <dl> <dt id="substitute-key-definition">Function: <strong>substitute-key-definition</strong> <em>olddef newdef keymap &amp;optional oldmap</em>
+</dt> <dd>
+ <p>This function replaces <var>olddef</var> with <var>newdef</var> for any keys in <var>keymap</var> that were bound to <var>olddef</var>. In other words, <var>olddef</var> is replaced with <var>newdef</var> wherever it appears. The function returns <code>nil</code>. </p> <p>For example, this redefines <kbd>C-x C-f</kbd>, if you do it in an Emacs with standard bindings: </p> <div class="example"> <pre class="example">(substitute-key-definition
+ 'find-file 'find-file-read-only (current-global-map))
+</pre>
+</div> <p>If <var>oldmap</var> is non-<code>nil</code>, that changes the behavior of <code>substitute-key-definition</code>: the bindings in <var>oldmap</var> determine which keys to rebind. The rebindings still happen in <var>keymap</var>, not in <var>oldmap</var>. Thus, you can change one map under the control of the bindings in another. For example, </p> <div class="example"> <pre class="example">(substitute-key-definition
+  'delete-backward-char 'my-funny-delete
+  my-map global-map)
+</pre>
+</div> <p>puts the special deletion command in <code>my-map</code> for whichever keys are globally bound to the standard deletion command. </p> <p>Here is an example showing a keymap before and after substitution: </p> <div class="example"> <pre class="example">(setq map (list 'keymap
+                (cons ?1 olddef-1)
+                (cons ?2 olddef-2)
+                (cons ?3 olddef-1)))
+⇒ (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))
+</pre>
+
+<pre class="example">(substitute-key-definition 'olddef-1 'newdef map)
+⇒ nil
+</pre>
+<pre class="example">map
+⇒ (keymap (49 . newdef) (50 . olddef-2) (51 . newdef))
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="suppress-keymap">Function: <strong>suppress-keymap</strong> <em>keymap &amp;optional nodigits</em>
+</dt> <dd>
+ <p>This function changes the contents of the full keymap <var>keymap</var> by remapping <code>self-insert-command</code> to the command <code>undefined</code> (see <a href="remapping-commands">Remapping Commands</a>). This has the effect of undefining all printing characters, thus making ordinary insertion of text impossible. <code>suppress-keymap</code> returns <code>nil</code>. </p> <p>If <var>nodigits</var> is <code>nil</code>, then <code>suppress-keymap</code> defines digits to run <code>digit-argument</code>, and <kbd>-</kbd> to run <code>negative-argument</code>. Otherwise it makes them undefined like the rest of the printing characters. </p>   <p>The <code>suppress-keymap</code> function does not make it impossible to modify a buffer, as it does not suppress commands such as <code>yank</code> and <code>quoted-insert</code>. To prevent any modification of a buffer, make it read-only (see <a href="read-only-buffers">Read Only Buffers</a>). </p> <p>Since this function modifies <var>keymap</var>, you would normally use it on a newly created keymap. Operating on an existing keymap that is used for some other purpose is likely to cause trouble; for example, suppressing <code>global-map</code> would make it impossible to use most of Emacs. </p> <p>This function can be used to initialize the local keymap of a major mode for which insertion of text is not desirable. But usually such a mode should be derived from <code>special-mode</code> (see <a href="basic-major-modes">Basic Major Modes</a>); then its keymap will automatically inherit from <code>special-mode-map</code>, which is already suppressed. Here is how <code>special-mode-map</code> is defined: </p> <div class="example"> <pre class="example">(defvar special-mode-map
+  (let ((map (make-sparse-keymap)))
+    (suppress-keymap map)
+    (define-key map "q" 'quit-window)
+    …
+    map))
+</pre>
+</div> </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/Changing-Key-Bindings.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Changing-Key-Bindings.html</a>
+  </p>
+</div>