[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#26233: 26.0.50; [PATCH] Improve documentation for display-buffer-ali
bug#26233: 26.0.50; [PATCH] Improve documentation for display-buffer-alist
Sun, 26 Mar 2017 10:45:51 -0700 (PDT)
> > 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> 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
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> Yup, and your code is even more complex.
M> Let's agree to disagree on that.
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> `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> 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> 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> 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> 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> 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> 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> 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
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> 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> 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> 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> 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.
bug#26233: 26.0.50; [PATCH] Improve documentation for display-buffer-alist, martin rudalics, 2017/03/24