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

[martin rudalics <rudalics@gmx.at>]

 >> 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.
 >
 > See, I didn't even get that bit from the doc string.  :-)

Given that 'display-buffer-overriding-action' figures first in

   ‘display-buffer’ builds a list of action functions and an action
   alist by combining any action functions and alists specified by
   ‘display-buffer-overriding-action’, ‘display-buffer-alist’, the
   ACTION argument, ‘display-buffer-base-action’, and
   ‘display-buffer-fallback-action’ (in order).  Then it calls each
   function in the combined function list in turn, passing the
   buffer as the first argument and the combined action alist as the
   second argument, until one of the functions returns non-nil.

your interpretation is quite logical.  The problem here is that we talk
in operative terms like "builds" "combining" "calls" "passing" which
hardly contributes anything to the understanding of an average user.

In a first approximation it should suffice to talk here about
`display-buffer-alist' and the ACTION argument only and ...

 >> 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.
 >
 > It's an overwhelming doc string, but I think listing the action
 > functions is one of the best bits about it.  :-)

... here I'd just say what they can do - reuse the selected window, a
window showing the buffer already, some other window, pop up a new
window on this or another frame.

 > I've now shuffled it
 > to the front, and given a bit more introductory text to make it sound
 > less intimidating.
 >
 >> 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.
 >
 > Yeah, the manual is rather abrupt here, too, but the entire thing is
 > really complicated, and caters for many different use cases, so I don't
 > really even know where to begin.

By dropping what you understand least.  If this makes it an empty
entrance, start from scratch with what you wanted to know first.  If
anything is incorrect, I'll fix it.  But making this readable for a user
is next to impossible, at least for me (I'm repeating myself whenever I
talk about this subject).  Have a look at the Elisp manual where I try,
maybe it helps.

martin