Re: Documenting buffer display

[martin rudalics]

> 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.

NO-SELECT non-nil implies that the window to show the buffer will
not be selected which is probably not what the user wants here.

> 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.

Applications have the choice: Prescribe where and how buffers should
be displayed or delegate that task to 'display-buffer'.  'ediff' uses
the former approach through a number of options like, for example,
'ediff-split-window-function'.  'edebug' uses 'edebug-pop-to-buffer'.
Users of the latter call 'pop-to-buffer' or 'display-buffer' directly.
Both approaches are valid.

'switch-to-buffer' belongs to the first group unless the selected
window is dedicated to some other buffer in which case
'switch-to-buffer' leaves the decision to 'pop-to-buffer' and we
already have a hybrid approach.  This is problematic and I always
advocate against the use of 'switch-to-buffer' in code: The
application should decide whether it wants one or the other.

Still, if we want users to tweak only "some minor aspects of how a
command works", the approach you sketch above is completely valid and
I think that Juri's recent proposal to allow the directional choice of
windows goes in the same direction and is even more universal.  We can
use 'display-buffer-overriding-action' for the prefix argument case
and I am all for it.  In either case, such a solution is not too
distinct from Stephen Leake's 'other-frame-window' approach so we
maybe should study that as well.

But once an application directly or indirectly calls 'display-buffer'
the latter's customizations may kick in and invalidate all assumptions
about the window used.  So if your NO-SELECT or Juri's directional
effort fail, 'display-buffer' will inevitably rule the game.

martin