Re: Documenting buffer display

[martin rudalics]

> I must be missing something: using pop-to-buffer-SAME-window to
> display a buffer in ANOTHER window?  How can that make sense?

Hysterical raisins. In the beginning, someone wrote a function called
'find-dired' to "Run `find' and go into Dired mode on a buffer of the
output".  In order to display that buffer, the author called
'switch-to-buffer' - probably because in his daily routine he
preferred to continue working on that dired buffer right away in the
selected window.

In the end, Trevor Murphy writes that

  Like, I could imagine an alternate world where that call to
  `switch-to-buffer' could be replaced with something as heavy-handed as
  …

     (pop-to-buffer (get-buffer-create "*Find*")    
'(display-buffer-same-window (inhibit-same-window)))

  … so that Emacs would still try very hard to display the Find buffer
  in the current window, but I could nevertheless override that by
  customizing `display-buffer-alist'.

And that's where 'pop-to-buffer-same-window' kicks in by accomplishing
_two_ things at the same time: It allows the author of 'find-dired'
and its "normal" users to continue working as if nothing changed at
all.  And it allows users like Trevor to customize the way *Find* is
displayed at their discretion.

An earlier approach to provide such behavior was to add functions like
'find-dired-other-window' and 'find-dired-other-frame' maybe with
appropriate key bindings.  The shortcomings of that approach are:

(1) The number of predefined functions to display a buffer is usually
    tripled.

(2) The user may have to memorize key bindings for three functions
    instead of one.

(3) These three functions still do not cover the entire spectrum of
    behaviors users want like showing the buffer on a specific side of
    the selected window or frame.

With 'pop-to-buffer-same-window' all 'find-dired' does now is to
_propose_ the selected window as the most suitable candidate for
displaying *Find*.  OTOH there's no more guarantee that *Find* will
actually appear in the selected window.  The ultimate decision of
where *Find* will appear is left to the user.

>> Which further means that a "not customized" caveat would be
>> counterproductive here.
>
> All I meant was to add something like "by default" to the doc string.
> I don't see how that could be wrong, all Stefan's advice
> notwithstanding.
>
> We shouldn't shoot ourselves in the foot by being afraid that complex
> enough customizations could invalidate the documentation.

The doc-string of 'pop-to-buffer-same-window' is not useful for people
who are happy with 'find-dired' behaving as it did before.  Such users
ideally will not even notice that something has changed and that they
have to react to that change in some way.

The doc-string of 'pop-to-buffer-same-window' is useful for two kinds
of persons:

(1) The author of 'find-dired' who now would be aware of the fact that
*Find* will not be necessarily shown in the selected window.  He will
be warned by the word "preferably" in

"Select buffer BUFFER in some window, preferably the same one."

but he won't care about whether the default behavior avoids the
selected window if its dedicated.  In fact, he has to be prepared for
the worst like *Find* popping up on a new frame or *Find* being
displayed in the selected window despite the fact that it is dedicated
to some other buffer.

(2) Users who want to know how to _change_ the default behavior by
customizing 'display-buffer-alist'.  Such people typically want to
show *Find* in some other window so they won't care about the
dedicated status of the selected window either.

I did not object to your changes when you made them because with Drew
such objections inevitably lead to discussions why 'display-buffer'
does it all wrong and why its earlier behavior was so much superior.
But your change strengthens the view that 'display-buffer' behaves as
requested by its caller.  That view inevitably leads to confusion.

>> Any explanation of what 'pop-to-buffer-same-window' does without
>> referring the reader to 'display-buffer' is misleading, at the very
>> least.
>
> I obviously disagree, as I did just that, and I object calling the
> current text "misleading".

Then why do we have all this dispute about 'display-buffer'?
According to the majority of people because its documentation is
confusing, wrong, incomplete, implicit, arcane or just bad.

martin