Re: Documenting buffer display

[Eli Zaretskii <eliz@gnu.org>]

> Date: Wed, 24 Oct 2018 11:44:56 +0200
> From: martin rudalics <rudalics@gmx.at>
> CC: emacs-devel@gnu.org
> 
>  >> What do you suppose a user to do if 'pop-to-buffer-same-window' is the
>  >> _only_ alternative an application offers to display a buffer?
>  >
>  > They should ask for a separate command, or for a user option to have
>  > the buffer displayed not in the selected window.  That option could
>  > (but doesn't have to) be implemented under the hood using action
>  > lists, of course.
> 
> That user option already exists as 'display-buffer-alist'.  That
> option was invented precisely for that purpose.  That option has no
> other purpose.

Just to clarify what I meant: I did NOT mean display-buffer-alist.  I
meant something like this:

  find-dired is an interactive compiled function...
  [...]
  By default, display the buffer in the selected window;
  NO-SELECT non-nil (interactively, prefix argument) means display the
  buffer in a window other than the selected one instead.

or

  By default, display the buffer in the selected window, but if
  the value of `find-dired-no-select' is non-nil,  display the
  buffer in a window other than the selected one instead.

This is our usual method of letting users tweak some minor aspects of
how a command works, and I see no reason why users would instead have
to construct action lists to do the same for commands that happen to
use display-buffer internally.