unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
From: martin rudalics <rudalics@gmx.at>
To: Eli Zaretskii <eliz@gnu.org>
Cc: emacs-devel@gnu.org
Subject: Re: Documenting buffer display
Date: Tue, 23 Oct 2018 10:58:29 +0200	[thread overview]
Message-ID: <5BCEE2B5.9090205@gmx.at> (raw)
In-Reply-To: <831s8hu6i8.fsf@gnu.org>

 > 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




  reply	other threads:[~2018-10-23  8:58 UTC|newest]

Thread overview: 32+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-10-20 12:20 Documenting buffer display martin rudalics
2018-10-20 13:21 ` Eli Zaretskii
2018-10-20 18:02   ` martin rudalics
2018-10-21 12:56     ` Eli Zaretskii
2018-10-22  9:06       ` martin rudalics
2018-10-22 13:55         ` Eli Zaretskii
2018-10-22 19:14           ` martin rudalics
2018-10-22 19:27             ` Eli Zaretskii
2018-10-23  8:58               ` martin rudalics [this message]
2018-10-23 11:26                 ` Pierre-Yves Luyten
2018-10-23 13:45                   ` martin rudalics
2018-10-23 17:40                   ` Stefan Monnier
2018-10-23 14:04                 ` Drew Adams
2018-10-23 18:18                   ` martin rudalics
2018-10-23 15:18                 ` Eli Zaretskii
2018-10-23 18:23                   ` martin rudalics
2018-10-23 19:07                     ` Eli Zaretskii
2018-10-24  9:44                       ` martin rudalics
2018-10-24 14:48                         ` Eli Zaretskii
2018-10-24 17:40                           ` martin rudalics
2018-10-24 18:25                             ` Eli Zaretskii
2018-10-25 20:42                             ` Juri Linkov
2018-10-23 15:52                 ` Alan Mackenzie
2018-10-23 18:25                   ` martin rudalics
2018-11-08 19:25                   ` martin rudalics
2018-10-22  1:39   ` Michael Welsh Duggan
2018-10-22  5:54     ` Eli Zaretskii
2018-10-20 15:22 ` Drew Adams
2018-10-20 18:02   ` martin rudalics
2018-10-20 18:24     ` Drew Adams
2018-10-21  8:22       ` martin rudalics
2018-11-04  9:06 ` martin rudalics

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.gnu.org/software/emacs/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=5BCEE2B5.9090205@gmx.at \
    --to=rudalics@gmx.at \
    --cc=eliz@gnu.org \
    --cc=emacs-devel@gnu.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).