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

-   By setting the @var{action} argument, an application effectively
+   There are cases, however, where Lisp programs want to modify the
+default behavior of a @code{display-buffer} call hidden behind another
+function.  In those cases, setting the @var{action} argument is not an
+option.  Fortunately, the @code{display-buffer-default-alist} variable
+can be used to specify a list of conditional default actions.  For
+instance, consider the case where an application wants to customize the
+behavior of the @code{display-buffer} call invoked internally by the
+@code{occur} function.
+
+@example
+@group
+(let ((display-buffer-default-alist
+       (append '(((category . occur)
+                  (display-buffer-pop-up-window)
+                  (post-command-select-window . t)))
+               display-buffer-default-alist)))
+  (occur "baz"))
+@end group
+@end example
+
+   By setting the @var{action} argument and the
+@code{display-buffer-default-alist} variable, an application effectively
  overrules any customization of @code{display-buffer-base-action}.  Our
-user can now either accept the choice of the application, or redouble
-by customizing the option @code{display-buffer-alist} as follows:

That example assumes that the user is familiar with 'occur', does not
describe how 'occur' triggers 'display-buffer' and whether the ACTION
argument is possibly overruled by 'display-buffer-default-alist'.  I'd
rather continue with the fictitious example from before somehow using

(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*"))))

where 'bar' emphasizes the basic behavior and 'baz' shows that another
application can prescribe a deviant one.

martin