bug#37840: Missing in the Emacs manuals:

[martin rudalics]

> 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