bug#37840: Missing in the Emacs manuals:

[martin rudalics <rudalics@gmx.at>]

 > There is no detailed example in the emacs manuals on how to migrate
 > from using "special-display-frame-alist" and
 > "special-display-regexps" to "display-buffer-alist."

I'm not sure whether I'll be able to come up with something reasonable
in this regard, mainly because I've never been able to understand the
special display function mechanism.

 > E.g., how to migrate from
 >
 > (setq special-display-frame-alist
 >     (quote
 >      ((height . 42)
 >      (width . 83)
 >      (left . 770)
 >      (unsplittable)
 >      (tool-bar-lines . 0)
 >      (left-fringe . 0)
 >      (right-fringe . 0)
 >      (line-spacing . 0)
 >      (font . "Monaco-12")
 >      (top . 110))))
 >
 >   and
 >
 > (setq special-display-regexps '((".*output*" (right-fringe . 0) (left-fringe . 0) (top . 330) (left . 152)
 >    (width . 86) (height . 32)
 >    (tool-bar-lines . 0) (font . "Menlo-10") (menu-bar-lines . 0)))

You can try the following untested snippet (your regxp looks a bit
odd, BTW):

(setq my-special-display-frame-alist
       (quote
        ((height . 42)
	(width . 83)
	(left . 770)
	(unsplittable)
	(tool-bar-lines . 0)
	(left-fringe . 0)
	(right-fringe . 0)
	(line-spacing . 0)
	(font . "Monaco-12")
	(top . 110))))

(setq my-special-display-regexps
       '((".*output*"
	 (right-fringe . 0)
	 (left-fringe . 0)
	 (top . 330)
	 (left . 152)
	 (width . 86)
	 (height . 32)
	 (tool-bar-lines . 0)
	 (font . "Menlo-10")
	 (menu-bar-lines . 0))))

(setq display-buffer-alist
       `((".*output*"
	 (display-buffer-reuse-window
	  ; display-buffer-same-window
	  ; display-buffer-pop-up-window
	  display-buffer-pop-up-frame)
	 (reusable-frames . 0) (inhibit-switch-frame . nil)
	 (pop-up-frame-parameters . ,(append (cdr my-special-display-regexps)
					       special-display-frame-alist)))))

where you have to comment-in the respective alist functions when you
use 'same-window' or 'same-frame' in your 'special-display-regexps'
settings (apparently you don't).

I can put a similar example into the Elisp manual (Eli would have to
figure out the details to omit or add) but note the following two not
entirely negligible differences:

'special-display-popup-frame' (the default for
'special-display-function') uses

        (when (cdr (assq 'same-window args))
	 (condition-case nil
	     (progn (switch-to-buffer buffer nil t) (selected-window))
	   (error nil)))

which has no direct equivalent in the 'display-buffer-alist'
ecosystem.  I used 'display-buffer-same-window' instead but that does
not obey options like 'switch-to-buffer-in-dedicated-window' or
'switch-to-buffer-preserve-window-point'.  Which means that for a
faithful migration you would have to write your own action function
here.

The second difference derives from the fact that
'special-display-popup-frame' marks the window on a new frame as
dedicated to its buffer.  This is no more needed in the
'display-buffer-alist' world because there the 'quit-restore' window
parameter takes care of the problem the former tries to solve.  Still
this means a behavioral difference that should be mentioned.  I
_cannot_ add a non-nil 'dedicated' alist entry because that would be
applied by any other action function ('display-buffer-pop-up-window'
foremost) too.

Also I have left out details like the function to be called when the
car of the ARGS argument of 'special-display-popup-frame' is a symbol
or how to treat 'special-display-buffer-names' ...

martin