RE: Documenting buffer display

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

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

Seriously?  This is what the discussion has devolved to?

I object to this personal characterization - which borders
on ad hominem attack.

I never said anything about `display-buffer' getting
anything wrong, let alone getting it all wrong.  And I
never said that its earlier behavior was so much superior,
or even that it was superior, or even that it was as good.

On the contrary, several times, including more than once
in the current discussion, I've thanked you for the work
you've done on `display-buffer' and its doc.  It is an
improvement that users have more fine-grained control over
buffer display.  I think I've been quite clear about this.

The points I made that you might want to characterize as
objections are (1) the doc can use some improvement (and
your trying to improve it now is a good thing, not a bad
thing) and (2) I would like to see the simple conveniences
of `pop-to-frames' and `special-display-*' continue to be
supported and not discouraged.

If someone can't make such points without being branded
in the way you just did then there is little hope for a
constructive discussion.  Do you want only an echo
chamber, or do you welcome input that might help even
if it might disagree with your point of view in some
regards?

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

Dunno whether it is a majority, but it's helpful that
you agree that this is a difficulty for at least some
of us.  (And I've never doubted that you agree about
this.  I know you recognize that this stuff is
complicated - in both behavior and explanation/doc.)

I, for one, am still at the state of being relatively
confused and ignorant.  I can't say that anything in
the doc is incorrect.  I expect that attempts to
clarify it are worthwhile, and I applaud them.
That's all.

FWIW, though I generally agree that the Emacs manuals
are mostly reference, we (Emacs generally, whether
officially or not) could use some more tutorial-like
presentations of using the various features provided
by `display-buffer'.  It is a powerful, complicated
construct, and its various possibilities deserve
more lead-you-by-the-hand exposure.

Somewhere.  Blogs, whatever, wherever.  Common use
cases presented and explicated.  That's one opinion.
The same thing is true for other complex areas, some
of which I've mentioned.  It wouldn't hurt to have
additional material out there that helps people to
better understand `display-buffer'.

I'm not saying that this is something that you guys
need to do.  I'm saying only that it is an area
where Emacs users could use more help, I think.
I think you might agree about this.

Hardly a day goes by, that one or more questions
related to this don't appear on Emacs Stack
Exchange or Reddit, for example.  And when I say
`display-buffer' I include questions about windows:
placement, which buffers, etc.