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

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

> > >> in Bug#25946 we discussed how to replace the obsolete variables
> > >> special-display-buffer-names and special-display-regexps.  The
> > >> attached patch extends the doc string of display-buffer-alist
> > >> based on that discussion.
> > >
> > > FWIW:
> > >
> > > 1. I *strongly* object to the deprecation of these user
> > > options.
> > > [...]
> >
> > I agree wholeheartedly.
> 
> Those variables were obsoleted in Emacs 24.3, which was released
> 4 years ago.  Isn't it too late to strongly object now to their
> deprecation?  That ship sailed long ago.

1. No, it should not be "too late" to do something sensible.

2. I _did_ object at the time.  And several times since.
With reasoned arguments each time.  The arguments are
still valid.

3. If for some reason Emacs stubbornly still does not
want to rehabilitate these options and document them
prominently (e.g. in the manual), then it should (IMHO)
at the very least explicitly decide to leave them
deprecated and supported - i.e., express the intention
not to desupport them.

(Obviously, #3 is not what I prefer.)  To be clear, I
have no objection to the point of view that says that
our docs should encourage users to use
`display-buffer-alist'.

I suspect that that was the (only?) aim behind the
deprecations: `d-b-a' was to completely replace them,
since it is a more general tool.  But we need not
throw out the motorbike just because we now have a
minivan, which is larger and more general-purpose.

These are simple-to-use, well-defined options (just as
well-defined as `display-buffer-alist'), which provide
a class of solid special cases (use cases).  In fact,
we would be well advised to think about perhaps
creating additional simple ways to provide other
special cases of `display-buffer-alist'.

This is not a race ("Time's up!").  These options work
just as well today as they did when they were deprecated.
No reason was ever given for their deprecation, beyond
"We now have the more general `display-buffer-alist'."

And if some users were steered away from them in the
interim, that is not the end of the world.  These are
_conveniences_, and good ones.  No one is obliged to
use them.  If someone prefers to slash her way through
the `display-buffer-alist' jungle for such simple use
cases, more power to her!

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