Recommend using 'keymap-set' in Commentaries

* lisp/calendar/timeclock.el, lisp/comint.el, lisp/ehelp.el:
* lisp/gnus/gnus-bookmark.el, lisp/gnus/smiley.el, lisp/ido.el:
* lisp/isearchb.el, lisp/mail/mailabbrev.el, lisp/net/ange-ftp.el:
* lisp/net/goto-addr.el, lisp/play/fortune.el, lisp/saveplace.el:
* lisp/shell.el, lisp/term.el, lisp/textmodes/makeinfo.el:
* lisp/textmodes/refer.el, lisp/textmodes/remember.el:
* lisp/textmodes/table.el, lisp/woman.el: Recommend using
'keymap-set' instead of 'define-key' in Commentaries.

lisp/calendar/timeclock.el

@@ -37,12 +37,12 @@
 ;; You'll probably want to bind the timeclock commands to some handy
 ;; keystrokes.  Assuming C-c t is unbound, you might use:
 ;;
-;;   (define-key (kbd "C-c t i") 'timeclock-in)
-;;   (define-key (kbd "C-c t o") 'timeclock-out)
-;;   (define-key (kbd "C-c t c") 'timeclock-change)
-;;   (define-key (kbd "C-c t r") 'timeclock-reread-log)
-;;   (define-key (kbd "C-c t u") 'timeclock-update-mode-line)
-;;   (define-key (kbd "C-c t w") 'timeclock-when-to-leave-string)
+;;   (keymap-set "C-c t i" 'timeclock-in)
+;;   (keymap-set "C-c t o" 'timeclock-out)
+;;   (keymap-set "C-c t c" 'timeclock-change)
+;;   (keymap-set "C-c t r" 'timeclock-reread-log)
+;;   (keymap-set "C-c t u" 'timeclock-update-mode-line)
+;;   (keymap-set "C-c t w" 'timeclock-when-to-leave-string)
 
 ;; If you want Emacs to display the amount of time "left" to your
 ;; workday in the mode-line, you can either set the value of

lisp/comint.el

@@ -3215,8 +3215,8 @@ its response can be seen."
 
 ;; These are not installed in the comint-mode keymap.  But they are
 ;; available for people who want them.  Shell-mode installs them:
-;; (define-key shell-mode-map "\t" 'completion-at-point)
-;; (define-key shell-mode-map "\M-?"
+;; (keymap-set shell-mode-map "TAB" 'completion-at-point)
+;; (keymap-set shell-mode-map "M-?"
 ;;             'comint-dynamic-list-filename-completions)))
 ;;
 ;; Commands like this are fine things to put in load hooks if you

lisp/ehelp.el

@@ -31,9 +31,9 @@
 ;; buffer.
 
 ;; To make this the default, you must do
-;; (define-key global-map "\C-h" 'ehelp-command)
-;; (define-key global-map [help] 'ehelp-command)
-;; (define-key global-map [f1] 'ehelp-command)
+;; (keymap-global-set "C-h" 'ehelp-command)
+;; (keymap-global-set "<help>" 'ehelp-command)
+;; (keymap-global-set "<f1>" 'ehelp-command)
 
 ;;; Code:
 

lisp/gnus/gnus-bookmark.el

@@ -55,10 +55,10 @@
 (require 'gnus-sum)
 
 ;; FIXME: should avoid using C-c (no?)
-;; (define-key gnus-summary-mode-map "\C-crm" 'gnus-bookmark-set)
-;; (define-key global-map "\C-crb" 'gnus-bookmark-jump)
-;; (define-key global-map "\C-crj" 'gnus-bookmark-jump)
-;; (define-key global-map "\C-crl" 'gnus-bookmark-bmenu-list)
+;; (keymap-set gnus-summary-mode-map "C-c r m" 'gnus-bookmark-set)
+;; (keymap-global-set "C-c r b" 'gnus-bookmark-jump)
+;; (keymap-global-set "C-c r j" 'gnus-bookmark-jump)
+;; (keymap-global-set "C-c r l" 'gnus-bookmark-bmenu-list)
 
 ;; FIXME: Add keybindings, see
 ;; http://thread.gmane.org/gmane.emacs.gnus.general/63101/focus=63379 [dead link]

lisp/gnus/smiley.el

@@ -189,12 +189,9 @@ regexp to replace with IMAGE.  IMAGE is the name of an image file in
 		    smiley-cached-regexp-alist))))))))
 
 ;; Not implemented:
-;; (defvar smiley-mouse-map
-;;   (let ((map (make-sparse-keymap)))
-;;     (define-key map [down-mouse-2] 'ignore) ; override widget
-;;     (define-key map [mouse-2]
-;;       'smiley-mouse-toggle-buffer)
-;;     map))
+;; (defvar-keymap smiley-mouse-map
+;;   "<down-mouse-2>" #'ignore ; override widget
+;;   "<mouse-2>"      #'smiley-mouse-toggle-buffer)
 
 ;;;###autoload
 (defun smiley-region (start end)

lisp/ido.el

@@ -214,7 +214,7 @@
 ;; `ido-buffer-completion-map'.
 ;;
 ;; (with-eval-after-load 'ido
-;;   (define-key ido-common-completion-map " " 'ido-next-match))
+;;   (keymap-set ido-common-completion-map "SPC" 'ido-next-match))
 
 ;; Seeing all the matching buffers or files
 ;; ----------------------------------------

lisp/isearchb.el

@@ -41,7 +41,7 @@
 ;; mode, just like with isearch.  I use C-z for this.  The binding in
 ;; my .emacs looks like:
 ;;
-;;   (define-key global-map [(control ?z)] 'isearchb-activate)
+;;   (keymap-global-set "C-z" 'isearchb-activate)
 ;;
 ;; Now, after pressing C-z (for example), each self-inserting
 ;; character thereafter will search for a buffer containing those

lisp/mail/mailabbrev.el

@@ -109,8 +109,8 @@
 ;;  (add-hook
 ;;   'mail-mode-hook
 ;;   (lambda ()
-;;      (define-key mail-mode-map [remap next-line] 'mail-abbrev-next-line)
-;;      (define-key mail-mode-map [remap end-of-buffer] 'mail-abbrev-end-of-buffer)))
+;;      (keymap-set mail-mode-map "<remap> <next-line>" 'mail-abbrev-next-line)
+;;      (keymap-set mail-mode-map "<remap> <end-of-buffer>" 'mail-abbrev-end-of-buffer)))
 ;;
 ;; If you want multiple addresses separated by a string other than ", " then
 ;; you can set the variable mail-alias-separator-string to it.  This has to

lisp/net/ange-ftp.el

@@ -1460,7 +1460,7 @@ only return the directory part of FILE."
 ;;;; ------------------------------------------------------------
 
 ;; (setq ange-ftp-tmp-keymap (make-sparse-keymap))
-;; (define-key ange-ftp-tmp-keymap "\C-m" 'exit-minibuffer)
+;; (keymap-set ange-ftp-tmp-keymap "C-m" 'exit-minibuffer)
 
 (defun ange-ftp-repaint-minibuffer ()
   "Clear any existing minibuffer message; let the minibuffer contents show."
@@ -4101,8 +4101,8 @@ E.g.,
 ;; Put these lines uncommented in your .emacs if you want C-r to refresh
 ;; ange-ftp's cache whilst doing filename completion.
 ;;
-;;(define-key minibuffer-local-completion-map "\C-r" 'ange-ftp-reread-dir)
-;;(define-key minibuffer-local-must-match-map "\C-r" 'ange-ftp-reread-dir)
+;;(keymap-set minibuffer-local-completion-map "C-r" 'ange-ftp-reread-dir)
+;;(keymap-set minibuffer-local-must-match-map "C-r" 'ange-ftp-reread-dir)
 
 ;;;###autoload
 (define-obsolete-function-alias 'ange-ftp-re-read-dir #'ange-ftp-reread-dir "29.1")

lisp/net/goto-addr.el

@@ -43,9 +43,8 @@
 ;; (for example):
 ;;
 ;; (setq goto-address-highlight-keymap
-;;   (let ((m (make-sparse-keymap)))
-;;     (define-key m [S-mouse-2] 'goto-address-at-point)
-;;     m))
+;;       (define-keymap
+;;         "S-<mouse-2>" 'goto-address-at-point))
 ;;
 
 ;; Known bugs/features:

lisp/play/fortune.el

@@ -57,9 +57,8 @@
 ;;
 ;; I also have this in my .gnus:
 ;;
-;;     (add-hook 'gnus-article-mode-hook
-;;               (lambda ()
-;;                 (define-key gnus-article-mode-map "i" #'fortune-from-region)))
+;;     (with-eval-after-load 'gnus-art
+;;       (keymap-set gnus-article-mode-map "i" #'fortune-from-region))
 ;;
 ;; which allows marking a region and then pressing "i" so that the marked
 ;; region will be automatically added to my favorite fortune file.

lisp/saveplace.el

@@ -38,7 +38,7 @@
 (require 'cl-lib)
 
 ;; this is what I was using during testing:
-;; (define-key ctl-x-map "p" 'toggle-save-place-globally)
+;; (keymap-set ctl-x-map "p" 'toggle-save-place-globally)
 
 (defgroup save-place nil
   "Automatically save place in files."

lisp/shell.el

@@ -48,8 +48,8 @@
 ;; Some suggestions for your init file.
 ;;
 ;; ;; Define M-# to run some strange command:
-;; (eval-after-load "shell"
-;;  '(define-key shell-mode-map "\M-#" 'shells-dynamic-spell))
+;; (with-eval-after-load 'shell
+;;   (keymap-set shell-mode-map "M-#" 'shells-dynamic-spell))
 
 ;; Brief Command Documentation:
 ;;============================================================================

lisp/term.el

@@ -4228,8 +4228,8 @@ This is a good place to put keybindings.")
 
 ;; These are not installed in the term-mode keymap.  But they are
 ;; available for people who want them.  Shell-mode installs them:
-;; (define-key shell-mode-map "\t" 'term-dynamic-complete)
-;; (define-key shell-mode-map "\M-?"
+;; (keymap-set shell-mode-map "TAB" 'term-dynamic-complete)
+;; (keymap-set shell-mode-map "M-?"
 ;;             'term-dynamic-list-filename-completions)))
 ;;
 ;; Commands like this are fine things to put in load hooks if you

lisp/textmodes/makeinfo.el

@@ -34,10 +34,10 @@
 ;;; Keybindings (defined in `texinfo.el')
 
 ;; makeinfo bindings
-; (define-key texinfo-mode-map "\C-c\C-m\C-r" 'makeinfo-region)
-; (define-key texinfo-mode-map "\C-c\C-m\C-b" 'makeinfo-buffer)
-; (define-key texinfo-mode-map "\C-c\C-m\C-k" 'kill-compilation)
-; (define-key texinfo-mode-map "\C-c\C-m\C-l"
+; (keymap-set texinfo-mode-map "C-c C-m C-r" 'makeinfo-region)
+; (keymap-set texinfo-mode-map "C-c C-m C-b" 'makeinfo-buffer)
+; (keymap-set texinfo-mode-map "C-c C-m C-k" 'kill-compilation)
+; (keymap-set texinfo-mode-map "C-c C-m C-l"
 ;   'makeinfo-recenter-compilation-buffer)
 
 ;;; Code:

lisp/textmodes/refer.el

@@ -46,7 +46,7 @@
 ;;	refer-yank-key to insert it at point in the current buffer
 ;;	(typically as the argument of a \cite{} command).
 ;;
-;;	I use (define-key tex-mode-map    "\C-c\C-y"  'refer-yank-key)
+;;	I use (keymap-set tex-mode-map    "C-c C-y"  'refer-yank-key)
 ;;	to bind this often-used function to a key in (la)tex-mode.
 ;;
 ;;      If the list of bibliography files changes, reinitialize the variable

lisp/textmodes/remember.el

@@ -129,7 +129,7 @@
 ;; To map the primary remember function to the keystroke F8, do the
 ;; following.
 ;;
-;;   (define-key global-map [f8] 'remember)
+;;   (keymap-global-set "<f8>" 'remember)
 ;;
 ;; * Feedback
 ;;

lisp/textmodes/table.el

@@ -343,7 +343,7 @@
 ;;
 ;;   (add-hook 'table-cell-map-hook
 ;;     (lambda ()
-;;       (define-key table-cell-map [<key sequence>] '<function>)))
+;;       (keymap-set table-cell-map "<key sequence>" '<function>)))
 ;;
 ;; -----
 ;; Menu:

lisp/woman.el

@@ -89,9 +89,8 @@
 ;; structure.
 
 ;; Or (3): Put this in your init file:
-;; (add-hook 'dired-mode-hook
-;;          (lambda ()
-;;            (define-key dired-mode-map "W" 'woman-dired-find-file)))
+;; (with-eval-after-load 'dired
+;;   (keymap-set dired-mode-map "W" 'woman-dired-find-file))
 ;; and open the directory containing the man page file using Dired,
 ;; put the cursor on the file, and press `W'.