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

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

[Jens Lechtenboerger]

[-- Attachment #1: Type: text/plain, Size: 245 bytes --]

Hi there,

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.

Best wishes
Jens


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Improve-documentation-for-display-buffer-alist.patch --]
[-- Type: text/x-diff, Size: 1645 bytes --]

From 10c5930b3056aa8366f1c4e02b24ba3de3f79058 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jens=20Lechtenb=C3=B6rger?= <lechten@wi.uni-muenster.de>
Date: Fri, 24 Mar 2017 14:09:15 +0100
Subject: [PATCH] Improve documentation for display-buffer-alist

The obsolete variables special-display-buffer-names and
special-display-regexps refer to display-buffer-alist.  As a follow-up
to Bug#25946 this change extends the doc string for that variable.
* list/windows.el (display-buffer-alist): Extend doc string.
---
 lisp/window.el | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/lisp/window.el b/lisp/window.el
index 5050243..c5c3e89 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -6792,7 +6792,20 @@ display-buffer-alist
 `display-buffer' scans this alist until it either finds a
 matching regular expression or the function specified by a
 condition returns non-nil.  In any of these cases, it adds the
-associated action to the list of actions it will try."
+associated action to the list of actions it will try.
+
+If you aim to replicate behavior of the obsolete variables
+`special-display-buffer-names' or `special-display-regexps',
+you may want to add something similar to the following to your
+init file (which places buffers whose names end with
+\" output\" into separate frames):
+(customize-set-variable 'display-buffer-alist
+			'((\".* output\"
+			   (display-buffer-reuse-window
+                            display-buffer-pop-up-frame)
+			   (reusable-frames . t))
+			  ))
+(setq display-buffer-mark-dedicated t)"
   :type `(alist :key-type
 		(choice :tag "Condition"
 			regexp
-- 
2.1.4

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

[Drew Adams]

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

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

[martin rudalics]

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

Thanks.  Personally I'd prefer having that in the Elisp manual.  Either
in a new subsection or at the end of section 27.14 Action Functions for
`display-buffer'?  Code in doc-strings is sometimes tedious to read.

martin

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

[Jens Lechtenboerger]

On 2017-03-24, at 07:51, Drew Adams wrote:

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

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

I never used those alternative forms, but you are right.
They need to be documented as well.

However, I don't know how.

Many thanks for your input
Jens

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

[Jens Lechtenboerger]

On 2017-03-24, at 19:54, martin rudalics wrote:

>> 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.
>
> Thanks.  Personally I'd prefer having that in the Elisp manual.  Either
> in a new subsection or at the end of section 27.14 Action Functions for
> `display-buffer'?  Code in doc-strings is sometimes tedious to read.

I'm surprised.  I consider that information relevant to ordinary
users, not only developers.  As pointed out by Drew Adams, probably
a new section in the Emacs manual is necessary.  Also, she convinced
me that much more information is necessary, which I'm unable to
provide.

Best wishes
Jens

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

[Eli Zaretskii]

> From: Jens Lechtenboerger <lechten@wi.uni-muenster.de>
> Date: Sat, 25 Mar 2017 08:53:13 +0100
> Cc: 26233@debbugs.gnu.org
> 
> On 2017-03-24, at 07:51, Drew Adams wrote:
> 
> >> 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.

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

[martin rudalics]

 >> Thanks.  Personally I'd prefer having that in the Elisp manual.  Either
 >> in a new subsection or at the end of section 27.14 Action Functions for
 >> `display-buffer'?  Code in doc-strings is sometimes tedious to read.
 >
 > I'm surprised.  I consider that information relevant to ordinary
 > users, not only developers.  As pointed out by Drew Adams, probably
 > a new section in the Emacs manual is necessary.  Also, she convinced
 > me that much more information is necessary, which I'm unable to
 > provide.

That's why I used the term "personally".  If you think that putting
the information in the doc-string is better, let's do that.

martin

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

[Drew Adams]

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

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

[Jens Lechtenboerger]

On 2017-03-25, at 11:32, Eli Zaretskii wrote:

>> From: Jens Lechtenboerger <lechten@wi.uni-muenster.de>
>> Date: Sat, 25 Mar 2017 08:53:13 +0100
>> Cc: 26233@debbugs.gnu.org
>> 
>> On 2017-03-24, at 07:51, Drew Adams wrote:
>> 
>> >> 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.

I see it this way: The departure of that ship was announced long
ago, for those knowing where to look; however, it did not sail yet.
I've got several settings for special-display variables in my init
file (predating 24.3, I don't know since when).  They still work
today, and they work without any user visible warning.

Best wishes
Jens

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

[Eli Zaretskii]

> From: Jens Lechtenboerger <lechten@wi.uni-muenster.de>
> Cc: <drew.adams@oracle.com>,  <26233@debbugs.gnu.org>
> Date: Sat, 25 Mar 2017 15:58:51 +0100
> 
> > 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.
> 
> I see it this way: The departure of that ship was announced long
> ago, for those knowing where to look; however, it did not sail yet.
> I've got several settings for special-display variables in my init
> file (predating 24.3, I don't know since when).  They still work
> today, and they work without any user visible warning.

AFAIU, you describe how deprecated variables work.  The complaint was
about announcing the departure, not about the departure itself (which
didn't yet happen).  "the ship" I alluded to was the announcement.

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

[Jens Lechtenboerger]

On 2017-03-25, at 18:57, Eli Zaretskii wrote:

>> From: Jens Lechtenboerger <lechten@wi.uni-muenster.de>
>> Cc: <drew.adams@oracle.com>,  <26233@debbugs.gnu.org>
>> Date: Sat, 25 Mar 2017 15:58:51 +0100
>> 
>> > 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.
>> 
>> I see it this way: The departure of that ship was announced long
>> ago, for those knowing where to look; however, it did not sail yet.
>> I've got several settings for special-display variables in my init
>> file (predating 24.3, I don't know since when).  They still work
>> today, and they work without any user visible warning.
>
> AFAIU, you describe how deprecated variables work.

Yes, I just extended bug#5742.

> The complaint was about announcing the departure, not about the
> departure itself (which didn't yet happen).  "the ship" I alluded
> to was the announcement.

I see.  Given bug#5742 I'm not surprised that there have been only
few objections.

Best wishes
Jens

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

[martin rudalics]

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

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

 > `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.  In any case I deeply regret that I ever got involved in this.

martin

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

[Eli Zaretskii]

> Date: Sun, 26 Mar 2017 10:38:25 +0200
> From: martin rudalics <rudalics@gmx.at>
> CC: 26233@debbugs.gnu.org
> 
> I deeply regret that I ever got involved in this.

Please don't.  I think your work in this area had (and continues to
have) a tremendously positive effect on Emacs, both in the usability
and the maintainability areas.  Don't let a certain attitude convince
you otherwise.

Thank you for your continuing work on Emacs, in these areas and
elsewhere.

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

[Drew Adams]

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

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

[Lars Ingebrigtsen]

martin rudalics <rudalics@gmx.at> writes:

>> 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.
>
> Thanks.  Personally I'd prefer having that in the Elisp manual.  Either
> in a new subsection or at the end of section 27.14 Action Functions for
> `display-buffer'?  Code in doc-strings is sometimes tedious to read.

Very short (like a couple of lines) I think is fine in doc strings, but
more than that should go in the manual (with, perhaps, links from the
doc string).

But in this case we're talking about adding pointers to variables that
were obsoleted six years ago (four at the time of this bug report), so I
don't think either is really worth doing at this point.  So I'm closing
this bug report; please reopen if you disagree.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no