Merge code changes from emacs.git

Author: skangas

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)

use-package-bind-key.el

@@ -5,25 +5,31 @@
 ;; Author: John Wiegley <[email protected]>
 ;; Maintainer: John Wiegley <[email protected]>
 
-;; 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:
 
 ;; Provides support for the :bind, :bind*, :bind-keymap and :bind-keymap*
 ;; keywords.  Note that these are currently still baked into
 ;; `use-package-keywords' and `use-package-deferring-keywords', although this
 ;; is harmless if they are never used.
+;;
+;; These keywords are made available by default by requiring `use-package'.
+;;
+;; See the `use-package' info manual for more information.
 
 ;;; Code:
 
@@ -32,15 +38,14 @@
 
 ;;;###autoload
 (defun use-package-autoload-keymap (keymap-symbol package override)
-  "Loads PACKAGE and then binds the key sequence used to invoke
-this function to KEYMAP-SYMBOL. It then simulates pressing the
-same key sequence a again, so that the next key pressed is routed
-to the newly loaded keymap.
+  "Load PACKAGE and bind key sequence invoking this function to KEYMAP-SYMBOL.
+Then simulate pressing the same key sequence a again, so that the
+next key pressed is routed to the newly loaded keymap.
 
-This function supports use-package's :bind-keymap keyword. It
+This function supports use-package's :bind-keymap keyword.  It
 works by binding the given key sequence to an invocation of this
-function for a particular keymap. The keymap is expected to be
-defined by the package. In this way, loading the package is
+function for a particular keymap.  The keymap is expected to be
+defined by the package.  In this way, loading the package is
 deferred until the prefix key sequence is pressed."
   (if (not (require package nil t))
       (use-package-error (format "Cannot load package.el: %s" package))

use-package-core.el

@@ -5,29 +5,27 @@
 ;; Author: John Wiegley <[email protected]>
 ;; Maintainer: John Wiegley <[email protected]>
 
-;; 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:
 
-;; The `use-package' declaration macro allows you to isolate package
-;; configuration in your ".emacs" in a way that is performance-oriented and,
-;; well, just tidy.  I created it because I have over 80 packages that I use
-;; in Emacs, and things were getting difficult to manage.  Yet with this
-;; utility my total load time is just under 1 second, with no loss of
-;; functionality!
+;; This file contains the core implementation of the `use-package'
+;; macro.
 ;;
-;; Please see README.md from the same repository for documentation.
+;; See the `use-package' info manual for more information.
 
 ;;; Code:
 
@@ -63,7 +61,9 @@
 
 (defgroup use-package nil
   "A `use-package' declaration for simplifying your `.emacs'."
-  :group 'startup)
+  :group 'initialization
+  :link '(custom-manual "(use-package) Top")
+  :version "29.1")
 
 (defconst use-package-version "2.4.4"
   "This version of `use-package'.")
@@ -1609,8 +1609,8 @@ no keyword implies `:all'."
 (defmacro use-package (name &rest args)
   "Declare an Emacs package by specifying a group of configuration options.
 
-For full documentation, please see the README file that came with
-this file.  Usage:
+For the full documentation, see Info node `(use-package) top'.
+Usage:
 
   (use-package package-name
      [:keyword [option]]...)
@@ -1647,12 +1647,15 @@ this file.  Usage:
                  `:magic-fallback', or `:interpreter'.  This can be an integer,
                  to force loading after N seconds of idle time, if the package
                  has not already been loaded.
-:after           Delay the use-package declaration until after the named modules
-                 have loaded. Once load, it will be as though the use-package
-                 declaration (without `:after') had been seen at that moment.
 :demand          Prevent the automatic deferred loading introduced by constructs
                  such as `:bind' (see `:defer' for the complete list).
 
+:after           Delay the effect of the use-package declaration
+                 until after the named libraries have loaded.
+                 Before they have been loaded, no other keyword
+                 has any effect at all, and once they have been
+                 loaded it is as if `:after' was not specified.
+
 :if EXPR         Initialize and load only if EXPR evaluates to a non-nil value.
 :disabled        The package is ignored completely if this keyword is present.
 :defines         Declare certain variables to silence the byte-compiler.

use-package-delight.el

@@ -5,23 +5,28 @@
 ;; Author: John Wiegley <[email protected]>
 ;; Maintainer: John Wiegley <[email protected]>
 
-;; 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:
 
-;; Provides support for the :delight keyword, which is made available by
-;; default by requiring `use-package'.
+;; Provides support for the :delight keyword, which is made available
+;; by default by requiring `use-package'.  Using it requires the
+;; `delight' package to be installed (available on GNU ELPA).
+;;
+;; See the `use-package' info manual for more information.
 
 ;;; Code:
 

use-package-diminish.el

@@ -5,23 +5,28 @@
 ;; Author: John Wiegley <[email protected]>
 ;; Maintainer: John Wiegley <[email protected]>
 
-;; 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:
 
-;; Provides support for the :diminish keyword, which is made available by
-;; default by requiring `use-package'.
+;; Provides support for the :diminish keyword, which is made available
+;; by default by requiring `use-package'.  Using it requires the
+;; `diminish' package to be installed (available on GNU ELPA).
+;;
+;; See the `use-package' info manual for more information.
 
 ;;; Code:
 

use-package-ensure-system-package.el

@@ -9,24 +9,29 @@
 ;; Package-Requires: ((use-package "2.1") (system-packages "1.0.4"))
 ;; Filename: use-package-ensure-system-package.el
 
-;; 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:
-;;
+
 ;; The `:ensure-system-package` keyword allows you to ensure system
-;; binaries exist alongside your `use-package` declarations.
+;; binaries exist alongside your `use-package` declarations.  Using it
+;; requires the `system-packages' package to be installed (available
+;; on GNU ELPA).
 ;;
+;; See the `use-package' info manual for more information.
 
 ;;; Code:
 
@@ -37,10 +42,10 @@
   (declare-function system-packages-get-command "system-packages"))
 
 (defvar use-package-ensure-system-package--custom-packages '()
-  "List of custom packages installed.")
+  "List of commands used to install custom packages.")
 
 (defun use-package-ensure-system-package-consify (arg)
-  "Turn ARG into a cons of (`package-name' . `install-command')."
+  "Turn ARG into a cons of the form (PACKAGE-NAME . INSTALL-COMMAND')."
   (cond
    ((stringp arg)
     (cons arg `(system-packages-install ,arg)))
@@ -59,13 +64,15 @@
 	    `(system-packages-install ,(symbol-name (cdr arg)))))))))
 
 (defun use-package-ensure-system-package-update-custom-packages ()
+  "Update custom packages (not installed by system package manager).
+Run the same commands used for installing them."
   (interactive)
   (dolist (cmd use-package-ensure-system-package--custom-packages)
     (async-shell-command cmd)))
 
 ;;;###autoload
 (defun use-package-normalize/:ensure-system-package (_name-symbol keyword args)
-  "Turn ARGS into a list of conses of (`package-name' . `install-command')."
+  "Turn ARGS into a list of conses of the form (PACKAGE-NAME . INSTALL-COMMAND)."
   (use-package-as-one (symbol-name keyword) args
     (lambda (_label arg)
       (cond
@@ -75,7 +82,7 @@
         (list (use-package-ensure-system-package-consify arg)))))))
 
 (defun use-package-ensure-system-package-exists? (file-or-exe)
-  "If variable is a string, ensure the file path exists.
+  "If FILE-OR-EXE is a string, ensure the file path exists.
 If it is a symbol, ensure the binary exist."
   (if (stringp file-or-exe)
       (file-exists-p file-or-exe)