bug#81512: [PATCH] Add command `outline-occur'

 >>> [...] `display-buffer-default-alist' [...] seems to be
 >>> intended to override some (default) behavior; it's binding has one
 >>> of the highest priorities.  This means that it's on the other end
 >>> than variables that are typically named "-default", which are
 >>> considered with lowest priority.  Unless I'm missing something, the
 >>> name is confusing and not consistent with our typical nomenclature.
 >>
 >> Agreed.  But we already have 'display-buffer-base-action' which probably
 >> should have been called 'display-buffer-default-action' and the first
 >> occurrence of "alist" is in 'display-buffer-alist' so it's reasonable to
 >> have 'display-buffer-default-alist' right beneath that.  Anyway, feel
 >> free to suggest a better term.  We'll be all ears I suppose.
 >
 > But if, then the names are transposed: `display-buffer-alist' is the
 > default.  Right?

No.  'display-buffer-default-alist' is the default and
'display-buffer-alist' overrides it.  The hierarchy from highest to
lowest is

         • The variable ‘display-buffer-overriding-action’.

         • The user option ‘display-buffer-alist’.

         • The variable ‘display-buffer-default-alist’.

         • The ACTION argument.

         • The user option ‘display-buffer-base-action’.

         • The constant ‘display-buffer-fallback-action’.

 > So since we can't change that name, the newly introduced
 > `display-buffer-default-alist' should be named
 > `display-buffer-overriding-alist', or similar.

No.  While Juri expressed his desire to add such a thing too, I
sincerely hope we can do without it.

 >>> Second: the added documentation says that this is a variable "which Lisp
 >>> programs may let-bind to specify conditional actions for nested
 >>> `display-buffer' calls."  I don't understand the connection to nested
 >>> calls here.  When at all is `display-buffer' been called recursively?
 >>> And in such a case, which variable is then crucial for which call of
 >>> `display-buffer'?  Is the outer or inner call ignoring one the variables?
 >>
 >> A let-binding of `display-buffer-default-alist' is supposed to override
 >> the ACTION argument of a 'display-buffer' call nested within that
 >> binding.  For nested let-bindings of 'display-buffer-default-alist' the
 >> usual rules for let-bindings apply.  If something is not clear about
 >> this, we'll have to fix it.
 >
 > I see now that I parsed the sentence wrongly because of the ambiguity
 > "calls of `display-buffer' nested in the binding" vs. "recursive calls
 > of `display-buffer'" (nested calls, nested in each other).
 >
 > Don't we rather use the term "wrapped"?  But English is not my mother
 > language, maybe it is only me that misunderstands that wording.  Or it
 > should be improved, I can't tell you.  But in the docstring:
 >
 > | Lisp programs may let-bind this variable to specify conditional actions
 > | for nested `display-buffer' calls.
 >
 > if you just removed the word "nested" I would understand it better.
 > Because it's then not unclear what the word "nested" refers to, and
 > everything is also clear without it (to me at least).  The same is true
 > for the (more or less identical) text added to the manual.

If

      Lisp programs may let-bind it to specify conditional actions for
      wrapped ‘display-buffer’ calls.

is less ambiguous, let's use that.

 > But now I'm curious: why is there no other solution for `outline-occur'?
 >
 > Because, see: we have the defaults for `display-buffer'.  Then we have
 > `display-buffer-alist', a user option to change this behavior.  Now we
 > say, ok, in this case we want to override that again, by introducing
 > another variable.  What do you answer when a user asks "how can I change
 > the buffer displaying behavior of `outline-occur'?

'display-buffer-default-alist' does _not_ override
'display-buffer-alist'.  'display-buffer-default-alist' overrides the
ACTION argument of 'display-buffer'.  The example from the "Precedence
of Action Functions" section in the Elisp manual

      (defun foo (buffer)
         (display-buffer
          buffer
          '((display-buffer-below-selected display-buffer-at-bottom))))

      (defun bar ()
         (let ((display-buffer-default-alist
               '(("\\*bar\\*" (display-buffer-pop-up-frame)))))
           (foo (get-buffer-create "*bar*"))))

      (defun baz ()
         (let ((display-buffer-default-alist
               '(("\\*baz\\*" (display-buffer-same-window)))))
           (foo (get-buffer-create "*baz*"))))

should make that clear.  If it doesn't, tell us how to improve it.  We
could add a 'display-buffer-alist' specification and tell how it would
override everything specified by 'foo', 'bar' and 'baz'.

martin