bug#30660: mention describe-bindings on (info "(emacs) Keymaps")

[Stefan Kangas <stefan@marxist.se>]

[-- Attachment #1: Type: text/plain, Size: 428 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

> I don't know why describe-bindings was documented in both manuals,
> and see no reason to continue doing so (the ELisp manual prints in 2
> large volumes, so avoiding any unnecessary bloat there is generally
> a good idea).

Here's a separate patch to remove it, while preserving the information
by moving it to the doc string of 'describe-bindings'.

WDYT?

Best regards,
Stefan Kangas


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Remove-describe-bindings-from-elisp-manual.patch --]
[-- Type: text/x-diff, Size: 3943 bytes --]

From 872d71f8667d68ac449d89993f9f85138eb3c1bb Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Fri, 15 Nov 2019 05:05:00 +0100
Subject: [PATCH] Remove describe-bindings from elisp manual

Ref: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=30660#74

* doc/lispref/keymaps.texi (Scanning Keymaps): Remove
'describe-bindings'.
* lisp/help.el (describe-bindings): Add some information removed from
the elisp manual to the doc string instead.
---
 doc/lispref/keymaps.texi | 23 -----------------------
 lisp/help.el             | 28 +++++++++++++++++++++-------
 2 files changed, 21 insertions(+), 30 deletions(-)

diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 8ff329bdac..1162abfc2b 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -1987,29 +1987,6 @@ Scanning Keymaps
 @end table
 @end defun
 
-@deffn Command describe-bindings &optional prefix buffer-or-name
-This function creates a listing of all current key bindings, and
-displays it in a buffer named @file{*Help*}.  The text is grouped by
-modes---minor modes first, then the major mode, then global bindings.
-
-If @var{prefix} is non-@code{nil}, it should be a prefix key; then the
-listing includes only keys that start with @var{prefix}.
-
-When several characters with consecutive @acronym{ASCII} codes have the
-same definition, they are shown together, as
-@samp{@var{firstchar}..@var{lastchar}}.  In this instance, you need to
-know the @acronym{ASCII} codes to understand which characters this means.
-For example, in the default global map, the characters @samp{@key{SPC}
-..@: ~} are described by a single line.  @key{SPC} is @acronym{ASCII} 32,
-@kbd{~} is @acronym{ASCII} 126, and the characters between them include all
-the normal printing characters, (e.g., letters, digits, punctuation,
-etc.@:); all these characters are bound to @code{self-insert-command}.
-
-If @var{buffer-or-name} is non-@code{nil}, it should be a buffer or a
-buffer name.  Then @code{describe-bindings} lists that buffer's bindings,
-instead of the current buffer's.
-@end deffn
-
 @node Menu Keymaps
 @section Menu Keymaps
 @cindex menu keymaps
diff --git a/lisp/help.el b/lisp/help.el
index 3b3d1f977e..7b5f4b4b31 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -492,13 +492,27 @@ view-lossage
 
 (defun describe-bindings (&optional prefix buffer)
   "Display a buffer showing a list of all defined keys, and their definitions.
-The keys are displayed in order of precedence.
-
-The optional argument PREFIX, if non-nil, should be a key sequence;
-then we display only bindings that start with that prefix.
-The optional argument BUFFER specifies which buffer's bindings
-to display (default, the current buffer).  BUFFER can be a buffer
-or a buffer name."
+The keys are displayed in order of precedence: first local
+bindings of minor modes, then local bindings defined by the
+current major mode, and finally global bindings.
+
+If optional argument PREFIX is non-nil, it should be a key
+sequence and means to display only bindings starting with that
+prefix.
+
+If optional argument BUFFER is non-nil, it specifies which
+buffer's bindings to display (by default, the current buffer).
+BUFFER can be a buffer or a buffer name.
+
+When several characters with consecutive ASCII codes have the same
+definition, they are shown together, as `FIRSTCHAR..LASTCHAR'.  In
+this instance, you need to know the ASCII codes to understand which
+characters this means.  For example, in the default global map, the
+characters `<SPC> .. ~' are described by a single line.  <SPC> is
+ASCII 32, `~' is ASCII 126, and the characters between them include
+all the normal printing characters, (e.g., letters, digits,
+punctuation, etc.); all these characters are bound to
+`self-insert-command'."
   (interactive)
   (or buffer (setq buffer (current-buffer)))
   (help-setup-xref (list #'describe-bindings prefix buffer)
-- 
2.20.1