Allow multiple keymaps in :map argument

[fishyfriend]

This is a reimplementation of #830, released as #1019 but reverted due to lacking copyright assignment. The copyright issue should now be solved as I have signed the Emacs copyright papers.

Sorry for the trouble of requesting a second review. I felt a rewrite was warranted due to discovered loose ends as well as readability.

Noteworthy changes:

• :map nil, which currently causes an error, is now treated as synonymous with :map global-map.

• nil, global-map, and override-global-map are explicitly disallowed as arguments for :prefix-map or :repeat-map. Existing checks here and here may have been intended for this purpose (perhaps mistakenly substituting map for (cadr args)?). These checks had simply been removed in the original PR as I couldn't make sense of them.

• A redundant check related to repeat maps has been removed

Original description from #830

This PR augments bind-keys to support passing a list of keymaps as the :map argument.

When one wants to bind the same key/command pair in multiple keymaps, the current options have some drawbacks:

;; Option 1: Code duplication, problematic when duplicated keybindings are numerous
(use-package foopkg
   :bind (:map bar-mode-map
          ("C-c x" . foocmd1)
          ("C-c y" . foocmd2)
          :map baz-mode-map
          ("C-c x" . foocmd1)
          ("C-c y" . foocmd2)))

;; Option 2: Use a loop, sacrificing the convenience and readability of :bind
(use-package foopkg
  :commands (foocmd1 foocmd2)
  :init
  (dolist (map (list bar-mode-map baz-mode-map))
    (bind-keys :map map
               ("C-c x" . foocmd1)
               ("C-c y" . foocmd2))))

With the new way, it is possible to avoid duplication and still use :bind:

(use-package foopkg
  :bind (:map (bar-mode-map baz-mode-map)
        ("C-c x" . foocmd1)
        ("C-c y" . foocmd2)))

Additionally this PR clarifies the documentation of bind-chords to reflect that this style is already available for that command.

---

Thanks, Jacob

[benthamite]

@jwiegley Would it be possible to merge this pull request? It seems like you were ready to merge the previous version and the only obstacle was the copyright assignment legal requirement, which is now addressed. Thanks.

[fishyfriend]

Hi, original submitter here, responding to @benthamite's comment. IMO a fresh review is needed before merging. Although this PR is not a huge set of changes, the part of bind-key.el involved is pretty complex, the functional changes are not totally identical to the original PR (see description), and the revised PR touches code that moved after the original version was reverted.

[benthamite]

@fishyfriend, oh, I see. Thanks for clarifying, and please disregard my previous comment.