Re: Documenting buffer display

[Eli Zaretskii <eliz@gnu.org>]

> Date: Tue, 23 Oct 2018 10:58:29 +0200
> From: martin rudalics <rudalics@gmx.at>
> CC: emacs-devel@gnu.org
> 
>      (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.

"Customize", as in setting display-buffer-overriding-action or
display-buffer-alist, you mean?

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

Nothing's wrong with that, IMNSHO: we do that for many other commands,
so it is a kind-of de-facto Emacs tradition/standard.

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

But there's also a huge advantage: users who are not very proficient
in Lisp will both discover the functionality and use it much easier.
Especially since we have many other commands factored in that way.  By
contrast, constructing display-buffer actions is not for the faint at
heart.

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

FWIW, I think it's wrong to advertise display-buffer-overriding-action,
and even display-buffer-alist, as the main way of user-level tweaking
commands into doing something completely different from what they were
coded to do.  I could argue that if such overrides are to be used as a
matter of routine, then the whole "middle layer" of
display-buffer-SOMETHING functions, including
pop-to-buffer-same-window, is entirely redundant, because many users
will override their preferences anyway.

My POV on this functionality is that the overriding action lists are
mainly for Lisp programs, not for users, and that those Lisp programs
don't abuse the feature to completely subvert certain display-buffer
function to do the opposite of what their names say.

But I digress.

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

So would adding to the doc string something like this:

  (This default behavior can be changed by customizing
  `display-buffer-overriding-action' and `display-buffer-alist'.)

take care of your concerns?  This is that "single sentence" I had in
mind a few messages back.

IOW, I assume that in 90% of the cases the *Find* buffer _will_ pop up
in the selected window, and that the other 10% are mostly due to users
who should be knowing what they are doing, and if they don't, it's
their funeral.  If *Find* does _not_ pop up in the selected window in
the vast majority of cases, then IMO find-dired has a bug that needs
to be fixed.

And I submit that you forget one very important class of readers:
those who are neither the author of find-dired nor those who want to
tweak the heck out of find-dired.  They are those who want to
understand _why_ find-dired works like it does, or _how_ does it cause
the buffer to be displayed in that particular window.  IOW, those who
see a call to pop-to-buffer-same-window and want to understand what
that does and which other variables/functions affect what it does.
This is the primary audience for doc strings.

> But your change strengthens the view that 'display-buffer' behaves as
> requested by its caller.

It usually does, or at least should, IMO.  It is IMO wrong to make the
documentation too complex in order to be 110% accurate, if that
accuracy comes at a price of leaving the reader without a more-or-less
clear mental picture regarding what a feature does in 90% of use case.
Rare corner cases should be "banished" to footnotes and parenthesized
notes, or even omitted altogether, if they complicate the main use
cases too much.  This is one such case: it makes little sense to me to
waste too much of the reader's prime time in order to explain how a
function designed to display a buffer in the selected window could be
tweaked into doing the opposite.

> That view inevitably leads to confusion.

Are you sure "confusion" is the right word here?  If so, please
elaborate, because I think you meant something like "inaccurate
information" (and IMO the inaccuracy is very minor).

In any case, would you agree that qualifications such as the one
proposed above will go a long way towards fixing those issues?

> >> 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'?

You mean, the discussion about the changes in the manual?  Because you
asked for review and comments.

> According to the majority of people because its documentation is
> confusing, wrong, incomplete, implicit, arcane or just bad.

Are you talking about the doc strings or about the manual?  If about
doc strings, then I'd like to hear or read those complaints, if they
are still valid after my recent changes.  I hope you trust me that I
wouldn't have left unfixed any doc strings matching any of the above
complaints.