Merge pull request #1030 from skangas/merge-emacs

bind-key.el

@@ -10,29 +10,29 @@
 ;; Keywords: keys keybinding config dotemacs extensions
 ;; URL: https://github.com/jwiegley/use-package
 
-;; This program is free software; you can redistribute it and/or modify
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
 ;; it under the terms of the GNU General Public License as published by
 ;; the Free Software Foundation, either version 3 of the License, or
 ;; (at your option) any later version.
 
-;; This program is distributed in the hope that it will be useful,
+;; GNU Emacs is distributed in the hope that it will be useful,
 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 ;; GNU General Public License for more details.
 
 ;; You should have received a copy of the GNU General Public License
-;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
+;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
 
 ;;; Commentary:
 
-;; If you have lots of keybindings set in your .emacs file, it can be hard to
-;; know which ones you haven't set yet, and which may now be overriding some
-;; new default in a new Emacs version.  This module aims to solve that
-;; problem.
-;;
-;; Bind keys as follows in your .emacs:
+;; If you have lots of keybindings set in your init file, it can be
+;; hard to know which ones you haven't set yet, and which may now be
+;; overriding some new default in a new Emacs version.  This module
+;; aims to solve that problem.
 ;;
-;;   (require 'bind-key)
+;; Bind keys as follows in your init file:
 ;;
 ;;   (bind-key "C-c x" 'my-ctrl-c-x-command)
 ;;
@@ -95,6 +95,8 @@
 ;; This display will tell you if you've overridden a default keybinding, and
 ;; what the default was.  Also, it will tell you if the key was rebound after
 ;; your binding it with `bind-key', and what it was rebound it to.
+;;
+;; See the `use-package' info manual for more information.
 
 ;;; Code:
 
@@ -103,7 +105,10 @@
 
 (defgroup bind-key nil
   "A simple way to manage personal keybindings."
-  :group 'emacs)
+  :group 'keyboard
+  :group 'convenience
+  :link '(emacs-commentary-link :tag "Commentary" "bind-key.el")
+  :version "29.1")
 
 (defcustom bind-key-column-widths '(18 . 40)
   "Width of columns in `describe-personal-keybindings'."
@@ -112,8 +117,7 @@
 
 (defcustom bind-key-segregation-regexp
   "\\`\\(\\(C-[chx] \\|M-[gso] \\)\\([CM]-\\)?\\|.+-\\)"
-  "Regular expression used to divide key sets in the output from
-\\[describe-personal-keybindings]."
+  "Regexp used by \\[describe-personal-keybindings] to divide key sets."
   :type 'regexp
   :group 'bind-key)
 
@@ -128,7 +132,18 @@
   "Keymap for `override-global-mode'.")
 
 (define-minor-mode override-global-mode
-  "A minor mode so that keymap settings override other modes."
+  "A minor mode for allowing keybindings to override other modes.
+The main purpose of this mode is to simplify bindings keys in
+such a way that they take precedence over other modes.
+
+To achieve this, the keymap `override-global-map' is added to
+`emulation-mode-map-alists', which makes it take precedence over
+keymaps in `minor-mode-map-alist'.  Thereby, key bindings get an
+even higher precedence than global key bindings defined with
+`keymap-global-set' (or, in Emacs 28 or older, `global-set-key').
+
+The macro `bind-key*' (which see) provides a convenient way to
+add keys to that keymap."
   :init-value t
   :lighter "")
 
@@ -147,9 +162,9 @@ Elements have the form ((KEY . [MAP]) CMD ORIGINAL-CMD)")
   "Bind KEY-NAME to COMMAND in KEYMAP (`global-map' if not passed).
 
 KEY-NAME may be a vector, in which case it is passed straight to
-`define-key'. Or it may be a string to be interpreted as
-spelled-out keystrokes, e.g., `C-c C-z'. See documentation of
-`edmacro-mode' for details.
+`define-key'.  Or it may be a string to be interpreted as
+spelled-out keystrokes, e.g., \"C-c C-z\".  See the documentation
+of `edmacro-mode' for details.
 
 COMMAND must be an interactive function or lambda form.
 
@@ -425,6 +440,11 @@ function symbol (unquoted)."
 
 ;;;###autoload
 (defmacro bind-keys* (&rest args)
+  "Bind multiple keys at once, in `override-global-map'.
+Accepts the same keyword arguments as `bind-keys' (which see).
+
+This binds keys in such a way that bindings are not overridden by
+other modes.  See `override-global-mode'."
   (macroexp-progn (bind-keys-form args 'override-global-map)))
 
 (defun get-binding-description (elem)