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.

Instead of deprecating them, we should not only continue
to support them, as we have been doing, but fully
document and even promote them.  If they did not exist
then Emacs would be well advised to invent them, as they
are convenient, _simple_ ways to specify special-display
of buffers.

"Special-display" is a thing.  Or at least it was.
Now, the term has been liquidated from the manual.
The only vestige of it is in the description of menu
"`Display Property': Enabling special display features."
That's unfortunate for users.

It is fine to have introduced a generalization, which
was done with `display-buffer-alist' etc.  It is not
fine to remove these simple, easy-to-use ways of
expressing common use cases.

2. The patch, though it proceeds from a good motivation
no doubt, can suggest that adding that code or similar
(e.g. some other regexp) in your init file will give you
the behavior of those deprecated options, in general.
That impression would be incorrect.

First, there are two such options, not just the
`-regexps' one.  More importantly are the so-called 
"alternative" forms of the option values - two 
"alternatives" for each option.  Just one example such 
as that given indicates nothing about these 
possibilities.

These options, and users, deserve a complete description
of how to get their full behavior using the more general
apparatus (`display-buffer-alist' etc.).  We should have
a section in the manual that describes these options and
"special-display" in general, just as was the case in
the past.

In that section it should be shown how this or that
behavior, which you can obtain simply using these
options, can also be had using `display-buffer-alist'.

I can almost guarantee that if we did that, then, as
a side benefit (and one that is sorely needed, IMO),
users would come away with a better understanding of
`display-buffer-alist' itself, and how to use it.
To this day - years after it was introduced - users
(including me) are still in the dark and confused
about `display-buffer-alist'.

IOW, introduce these options as first-class citizens,
and show _how they correspond_ to the more general
apparatus.

3. I also object to the way the doc strings for these
options were changed, to suggest that the "alternative"
value forms are perhaps only arcane or less-important
"alternatives".

Originally, the doc strings just said, outright, that
there are 3 forms the value can take: 1, 2, 3.  None
of those forms were relegated to the background, as
an afterthought or as something obscure or inferior.
Though simple to use, these are powerful options,
which should not be trivialized.

Users should be encouraged to use these options
whenever they do the job needed, and to use the more
general constructs when they need something else.

Instead, we've hidden these simple constructs, told
users that they are now deprecated, and tossed users
immediately onto the rocks of `display-buffer-alist'
as their only resort, even for these simple use cases.
That's not right.

Just one opinion.