bug#39149: 27.0.50; describe-buffer-bindings is calling :filter function in wrong buffer

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stefan Kangas <stefankangas@gmail.com>
>> Date: Sat, 14 Nov 2020 16:24:07 -0800
>> Cc: 39149@debbugs.gnu.org
>>
>> a) Add a new argument to describe-map with the original buffer.  Ensure
>>    that the :filter function is run there.
>>
>> b) Change describe-map to return its output as a string.
>
> Unless I'm missing something, b) would be a backward-incompatible
> change, so I don't think we should consider it.

No: `describe-map' was added on master a month ago as a Lisp translation
of the old C function "describe_map".  It has never been exposed to Lisp
directly, but was used internally on the C level by
`substitute-command-keys' and `describe-buffer-bindings'.

What is true is that:

- `substitute-command-keys' has always returned a string.
- `describe-buffer-bindings' has always inserted into the current
  buffer.

Whether we go with option a) or b) shouldn't need to change that.

So we should think carefully about what their interface should be rather
than nail it down to match the old C code.

BTW, while we're on it, I'm not at all sure it would make sense to use
these functions outside of help.el.  I think we might want to consider
renaming `describe-map' to `help--describe-map', and similarly for
`describe-map-tree'.

> If adding an argument is deemed not a good idea, how about binding a
> special variable to convey that information to
> describe-buffer-bindings?

Yes, that could be a third option c).  Personally, I like option b)
better.