From a9eac78e23f27379dc801dcd090d644a89a48ce4 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 7 Mar 2026 10:55:23 +0200
Subject: [PATCH] Improve documentation of 'define-keymap'

* lisp/emacs-lisp/shortdoc.el (keymaps): Add example for adding
key bindings to an existing keymap.
* lisp/keymap.el (define-keymap): Doc fix.  (Bug#80556)
---
 lisp/emacs-lisp/shortdoc.el | 7 +++++--
 lisp/keymap.el              | 3 ++-
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el
index 8b382bd14dd..08dbb9dad19 100644
--- a/lisp/emacs-lisp/shortdoc.el
+++ b/lisp/emacs-lisp/shortdoc.el
@@ -1586,9 +1586,12 @@ A FUNC form can have any number of `:no-eval' (or `:no-value'),
    :no-eval (text-property-search-backward 'face nil t)))
 
 (define-short-documentation-group keymaps
-  "Defining keymaps"
+  "Defining keymaps or adding bindings to existing keymaps"
   (define-keymap
-    :no-eval (define-keymap "C-c C-c" #'quit-buffer))
+    :no-eval (define-keymap "C-c C-c" #'quit-buffer)
+    :no-eval (define-keymap :keymap ctl-x-map
+               "C-r"      #'recentf-open
+               "k"        #'kill-current-buffer))
   (defvar-keymap
       :no-eval (defvar-keymap my-keymap "C-c C-c" #'quit-buffer))
   "Setting keys"
diff --git a/lisp/keymap.el b/lisp/keymap.el
index c2e86204be4..2cd6c8b1433 100644
--- a/lisp/keymap.el
+++ b/lisp/keymap.el
@@ -609,7 +609,8 @@ pairs.  Available keywords are:
              (see `set-keymap-parent').
 
 :keymap    If non-nil, instead of creating a new keymap, the given keymap
-             will be destructively modified instead.
+             will be destructively modified instead.  This can be used to
+             add key bindings to an existing keymap.
 
 :name      If non-nil, this should be a string to use as the menu for
              the keymap in case you use it as a menu with `x-popup-menu'.