bug#45688: 28.0.50; New action for display-buffer?

[martin rudalics]

> I think the doc string for `display-buffer' is pretty intimidating now,
> and seems more geared towards programmers than usage now.  Would it make
> sense to rearrange it a bit?  That is, start off with something like:
>
> -----
>
> Display BUFFER-OR-NAME in some window, without selecting it.  To change
> what window is used, set `display-buffer-overriding-action' to a list
> containing one or more of the following functions:
>
> Action functions and the action they try to perform are:
>   ‘display-buffer-same-window’ -- Use the selected window.
>   ‘display-buffer-reuse-window’ -- Use a window already showing
>      the buffer.
>   ‘display-buffer-in-previous-window’ -- Use a window that did
>      show the buffer before.
>
> etc etc, and then give the details about ACTION and the rest?

By no means.  `display-buffer-overriding-action' is _not_ intended for
the user.  It's an emergency exit for applications.  Better not even
mention it in the user manual and the doc-string.

In every other regard, feel free to change it in a way that sounds less
imitating.  For example, listing the action functions and alist entries
in the doc-string is merely distracting.  We started out with small sets
and every time a new function or entry was added, we also added it to
those lists.  And while you're there you could try to make the Emacs
manual entry more amenable for its audience.  IIUC that's what the blog
you mentioned criticized even more than the doc-string.

martin