Don't recommend legacy keymap functions in docstrings

* lisp/comint.el (comint-prompt-read-only):
* lisp/ielm.el (ielm-prompt-read-only):
* lisp/international/ogonek.el (ogonek-informacja, ogonek-information):
* lisp/mouse-copy.el (mouse-drag-secondary-pasting):
* lisp/mouse-drag.el (mouse-drag-throw, mouse-drag-drag): Don't
recommend using legacy keymap functions.

lisp/comint.el

@@ -186,11 +186,11 @@ narrowing in effect.  This way you will be certain that none of
 the remaining prompts will be accidentally messed up.  You may
 wish to put something like the following in your init file:
 
-\(add-hook \\='comint-mode-hook
-          (lambda ()
-            (define-key comint-mode-map [remap kill-region] \\='comint-kill-region)
-            (define-key comint-mode-map [remap kill-whole-line]
-              \\='comint-kill-whole-line)))
+    (with-eval-after-load \\='comint
+      (keymap-set comint-mode-map \"<remap> <kill-region>\"
+                                  \\='comint-kill-region)
+      (keymap-set comint-mode-map \"<remap> <kill-whole-line>\"
+                                  \\='comint-kill-whole-line))
 
 If you sometimes use `comint-mode' on text-only terminals or with `emacs -nw',
 you might wish to use another binding for `comint-kill-whole-line'."

lisp/ielm.el

@@ -60,11 +60,10 @@ narrowing in effect.  This way you will be certain that none of
 the remaining prompts will be accidentally messed up.  You may
 wish to put something like the following in your init file:
 
-\(add-hook \\='ielm-mode-hook
-          (lambda ()
-             (define-key ielm-map \"\\C-w\" \\='comint-kill-region)
-             (define-key ielm-map [C-S-backspace]
-               \\='comint-kill-whole-line)))
+    (with-eval-after-load \\='ielm
+      (keymap-set ielm-map \"C-w\" \\='comint-kill-region)
+      (keymap-set ielm-map \"C-S-<backspace>\"
+        \\='comint-kill-whole-line))
 
 If you set `comint-prompt-read-only' to t, you might wish to use
 `comint-mode-hook' and `comint-mode-map' instead of

lisp/international/ogonek.el

@@ -144,17 +144,17 @@ znak/ow diakrytycznych. Funkcje te mo/zna pogrupowa/c nast/epuj/aco.
    (defun deprefixify-iso8859-2-region (start end)
      (interactive \"*r\")
      (ogonek-deprefixify-region start end ?/ \"iso8859-2\"))
-   (global-set-key \"\\C-cd\" \\='deprefixify-iso8859-2-region) ; ctrl-c d
+   (keymap-global-set \"C-c d\" \\='deprefixify-iso8859-2-region) ; ctrl-c d
 
    (defun mazovia-to-iso8859-2 (start end)
      (interactive \"*r\")
      (ogonek-recode-region start end \"mazovia\" \"iso8859-2\"))
-   (global-set-key \"\\C-cr\" \\='mazovia-to-iso8859-2) ; ctrl-c r
+   (keymap-global-set \"C-c r\" \\='mazovia-to-iso8859-2) ; ctrl-c r
 
    (defun prefixify-iso8859-2-region (start end)
      (interactive \"*r\")
      (ogonek-prefixify-region start end \"iso8859-2\" ?/))
-   (global-set-key \"\\C-cp\" \\='prefixify-iso8859-2-region) ; ctrl-c p
+   (keymap-global-set \"C-c p\" \\='prefixify-iso8859-2-region) ; ctrl-c p
 
  Ka/zd/a operacj/e przekodowania mo/zna w ca/lo/sci odwo/la/c
  przez wykonanie polecenia `undo'.")
@@ -244,17 +244,17 @@ The functions come in the following groups.
    (defun deprefixify-iso8859-2-region (start end)
      (interactive \"*r\")
      (ogonek-deprefixify-region start end ?/ \"iso8859-2\"))
-   (global-set-key \"\\C-cd\" \\='deprefixify-iso8859-2-region) ; ctrl-c d
+   (keymap-global-set \"C-c d\" \\='deprefixify-iso8859-2-region) ; ctrl-c d
 
    (defun mazovia-to-iso8859-2 (start end)
      (interactive \"*r\")
      (ogonek-recode-region start end \"mazovia\" \"iso8859-2\"))
-   (global-set-key \"\\C-cr\" \\='mazovia-to-iso8859-2) ; ctrl-c r
+   (keymap-global-set \"C-c r\" \\='mazovia-to-iso8859-2) ; ctrl-c r
 
    (defun prefixify-iso8859-2-region (start end)
      (interactive \"*r\")
      (ogonek-prefixify-region start end \"iso8859-2\" ?/))
-   (global-set-key \"\\C-cp\" \\='prefixify-iso8859-2-region) ; ctrl-c p
+   (keymap-global-set \"C-c p\" \\='prefixify-iso8859-2-region) ; ctrl-c p
 
  Each recoding operation can be called off using the `undo' command.")
 

lisp/mouse-copy.el

@@ -152,7 +152,8 @@ If you have the bug (or the real fix :-), please let me know."
   "Drag out a secondary selection, then paste it at the current point.
 
 To test this function, evaluate:
-	(global-set-key [M-down-mouse-1] \\='mouse-drag-secondary-pasting)
+    (keymap-global-set \"M-<down-mouse-1>\"
+                       \\='mouse-drag-secondary-pasting)
 put the point at one place, then click and drag over some other region."
   (interactive "e")
   ;; Work-around: We see and react to each part of a multi-click event

lisp/mouse-drag.el

@@ -203,7 +203,7 @@ about which direction is natural.  Perhaps it has to do with which
 hemisphere you're in.)
 
 To test this function, evaluate:
-    (global-set-key [down-mouse-2] \\='mouse-drag-throw)"
+    (keymap-global-set \"<down-mouse-2>\" \\='mouse-drag-throw)"
   (interactive "e")
   ;; we want to do save-selected-window, but that requires 19.29
   (let* ((start-posn (event-start start-event))
@@ -263,7 +263,7 @@ Drag scrolling is identical to the \"hand\" option in MacPaint, or the
 middle button in Tk text widgets.
 
 To test this function, evaluate:
-    (global-set-key [down-mouse-2] \\='mouse-drag-drag)"
+    (keymap-global-set \"<down-mouse-2>\" \\='mouse-drag-drag)"
   (interactive "e")
   ;; we want to do save-selected-window, but that requires 19.29
   (let* ((start-posn (event-start start-event))