bug#26233: 26.0.50; [PATCH] Improve documentation for display-buffer-alist

[Drew Adams <drew.adams@oracle.com>]

>  > 2. I _did_ object at the time.
> 
> Sorry, but the time was 2011 and at that time I wrote ...
> 
>  Your approach will divide Emacs users into two groups: A wide majority
>  that continues to use the old options and a small minority able to
>  write their own alist based functions.
> 
> ... and ...
> 
>  Most of what you propose above is easily available in Emacs 23 via
>  `special-display-regexps'.  An application would just temporarily add
>  the buffer, the function, and the alist to the head of that and get the
>  behavior without setting any arguments.  Is it really worth inventing a
>  new `display-buffer' in order to resolve such cosmetic issues?

I had to search the bugs list and emacs-devel to find that quote,
since you provided no URL for it.

To be clear, the "you" and "your" in your quote was apparently
Stefan, not me.

> You did not bother to participate in that discussion and so
> you did not object at the time.

Actually, I _did_ participate in that discussion, quite actively.
I sent 13 messages to that thread. Starting with this reply to
Juanma, who replied to you:

J> IMHO, you've taken a lot of time to think of this, and the added
J> complexity, if any, is added flexibility.  I think we should strive to
J> make the current funcionality of your changes clearer and better
J> documented. If we stat removing things now, we'll be doomed to re-add
J> them some day, not long, when people starts to ask for ways to make it
J> work like it was before (you've seen enough of my private bug reports
J> to know how true that is ;-)

D> I tend to agree with what Juanma says here, though I'm not
D> really able to judge what is needed, myself.  I expect that
D> Martin has looked at the various requirements more than anyone
D> else, and I imagine he has done a good job of coming up with
D> a coherent solution that covers them.  We definitely do not
D> want to start over from scratch and risk destabilizing things
D> a great deal.
D>
D> That said, there is a lot to understand, and I'm guessing that
D> we, including Martin, might not see clearly what TRT is until,
D> in fact, we start trying to explain/describe it better.

It's clear that from the very beginning (1) I supported your work
toward `display-buffer-alist' improvement, (2) I agreed with
those who said that we need to "make the current funcionality of
your changes clearer and better documented, and (3) I agreed with
Juanma's statement that:

  If we start removing things now, we'll be doomed to re-add
  them some day, not long, when people starts to ask for ways
  to make it work like it was before

It's time to "re-add" `special-display-*' support, I think,
i.e., to un-deprecate it (since it is still supported and it
still works well).

I don't think that we have today a use of `display-buffer-alist'
that rivals the use of the `special-display-*' options for
handling their use cases.  And I think we should add those
features back with full support (they are not gone, but they
have been deprecated).

Note, BTW, this from Juanma, which pretty much sparked the
discussion:

J> From someone who has read the docstring of
J> `display-buffer-alist' once too many and gleaned way too
J> little meaning from it (no offense, Martin, I love your
J> work, just not this variable's doc)...

FWIW, I agreed with that sentiment then, and I still do.

The following is also from that thread, this time as a
reply to your statement that I am the _only one_ to object
(so clearly, I did object).  You were replying to Stefan,
who said that the new code was more complex:

M>> I don't know how many times I went through the code of
M>> `special-display-buffer-names' but I know that I still
M>> don't understand it.
S>
S> Yup, and your code is even more complex.

M> Let's agree to disagree on that.
M>  
M> `special-display-buffer-names' had only one serious user,
M> namely Drew Adams.  I know that because my rewrite had a
M> number of bugs which we eliminated in a period of two
M> weeks mostly by trial and error.  In all that time no one
M> else complained.  I suppose you use it as well but since you
M> apparently advice `display-buffer' (or some subset of its
M> routines) you were not hit by these bugs.
M> 
M> `special-display-buffer-names' is complex because it prescribes
M> behavior for reusing the same window, reusing some other window
M> on the same frame, popping up a new window, reusing a window on
M> another frame and popping up a new frame.  That's the kind of
M> expressiveness Drew needs because he's got no other choice.
M> It's far too expressive for all other users.

D> A comment, since my case has been identified as unique -
D> 
D> 1. `special-display-buffer-names' is _very_, very old.  It has
D> been in GNU Emacs as far back as the introduction of frames, I
D> believe.  Someone can check the origin and the original design
D> arguments; I'm no expert on this.  
D> 
D> 2. AFAIK, from the outset it has been just as "complex" as it
D> is today - all of the possibilities have been there since Day
D> One.  They were not added incrementally because someone thought
D> that it would be neat to add a bell here or a whistle there.
D> They were thought to be important by the _original designers_,
D> many, many moon ago.
D> 
D> 3. The point is that I did not invent `special-display-buffer-names',
D> and it was not invented for me. ;-)  I have made use of it for
D> decades (since at least Emacs 19, maybe 18, IIRC), and I have
D> always made the _same_ use of it.
D> 
D> 4. Here is the _only_ use I make of it - Drew's weirdo use case.
D> I use only the form (BUFFER FUNCTION OTHER-ARGS...), and only
D> for two buffers: *Help* and *Completions*.
...
D> HTH.  Personally, I do not consider my use of
D> `special-display-buffer-names' to be strange or outlandish - it
D> seems pretty simple to me.
D>
D> If it is true that I am the only one to use this feature, so be
D> it.  But that in itself does not make this feature or my use of
D> it "complex".  And I would even guess that if more things worked
D> better in GNU Emacs wrt frames (as opposed to just windows) then
D> you might see more people using this feature.
D> 
D> FWIW, my code for this works in Emacs 20 through 23, and it also
D> works with Emacs 24 after Martin's efforts to fix some initial
D> bugs (thank you, Martin!).  And it works cross-platform, AFAIK.
D> Not so far out, really.

Going back further, you will see this, from me, in the May
2009 thread "display-buffer cleverness - how to tame?":

D> If the new `display-buffer' approach is so complex that just
D> describing a simple way to get back the old behavior is too
D> difficult (even for the implementor!), then, yes, I think we
D> have a problem.

8 years later, we're still there, it seems.

And before that, in the same 2009 thread:

D> I'm sure the new display-buffer behavior is an improvement
D> in some way, but it seems too clever by half, at least in
D> one context I have.
D> 
D> I'm not suggesting the smarter behavior should be reverted
D> (I'd have to understand it first, to be able to suggest
D> that ;-)).  I just want to know which settings I need, to
D> get back the previous behavior for some code I have that
D> (apparently) depends on it.

Now back to the present -

>  > `display-buffer-alist' is notoriously difficult to
>  > understand and make use of.  As one example, though I've
>  > asked several times how to use it to get the same effect
>  > provided by these options I've never gotten a response.
>  >
>  > That's the first step for Emacs to take, IMO, after
>  > undeprecating these options (as well as anything else
>  > "special-display", of course, such as
>  > `special-display-alist'): State in the doc exactly how
>  > they correspond to a special case of using
>  > `display-buffer-alist'.  _Show_ the equivalence.
> 
> Despite the fact that many years ago I moved these options and the
> corresponding functions from C to Elisp, I still don't understand them
> and very likely never will.  If you asked me how to obtain a specific
> behavior with ‘display-buffer-alist’, I might be able to come up with an
> answer.

I'm still hoping that _someone_ can explain how to get the
behavior of the deprecated simple constructs using the
proclaimed replacement and generalization, `display-buffer-alist'.

> In any case I deeply regret that I ever got involved in this.

I'm sorry you feel that way.  I, for one, am very glad you
did get involved in this.  It is a _good_ thing to have
improved and generalized `display-buffer-alist'.  You did a
_lot_ of good work, which everyone has recognized and which
Emacs users now benefit from.

And it is a good thing (after several requests over the years,
by multiple users) that we now have better doc for it.  (It
could be better yet, I think; I still find it hard to follow.)

The missing pieces are to (1) un-deprecate `special-display-*'
and (2) document the relation between the `special-display-*'
features and `display-buffer-alist'.

If there is _no_ relation between the two, then that's all
the more reason to un-deprecate `special-display-*'.  If
the relation is too complicated for anyone to understand
or document then that too is all the more reason to fully
support and document `special-display-*'.

Let me end here with another quote from myself from that
2011 thread, to make clear (again) how I feel about your
work on this:

D> Let me be clear again that I have confidence in what you're
D> doing, Martin.  I agree with you and others that things are
D> currently quite complex for users, and I'm one of those who
D> does not yet understand how to use `display-buffer-alist'.
D> 
D> But I expect that with time, discussion, and experiment we
D> can iron things out and simplify somewhat (at least the doc,
D> and perhaps the design/UI).
D> 
D> Let me be clear too that I appreciate your trying to handle
D> the complexity, to deal with all of the various use cases,
D> and to maintain coherence wrt previous behavior.
D> 
D> I do _not_ want to see things get dumbed down just because
D> we haven't yet found an ideal way to present them (UI, doc).
D> The first task should be to handle all of the use cases.
D> Only secondly should we try to simplify, and do so without
D> sacrificing use cases.
D> 
D> Please continue to explain patiently to us all what we
D> don't understand, and please continue to resist simplistic
D> "solutions" proposed by _any_ of us who understand this
D> stuff less than you do.  Keep up the good work, and do not
D> hurry or simplify prematurely or simplistically just
D> because someone points out that things are, so far,
D> complex for users.  There's no hurry.