bug#12848: 24.2.50; Doc: give an example for a typical entry of `display-buffer-alist'

bug#12848: 24.2.50; Doc: give an example for a typical entry of `display-buffer-alist'

[Michael Heerdegen]

Hello,

`display-buffer-alist' entries are quite complex.  OTOH, it's not
uncommon that a typical user might need it.  We should give an example
entry, somewhere.

Today, I thought: "I want that *Help* is always displayed in a new frame
when it is not already displayed anywhere".  It took some
time to figure out what was needed:

(add-to-list
 'display-buffer-alist
 '("\\`\\*Help\\*\\'" . ; make *Help* pop up in a new frame when not already displayed
   ((display-buffer-reuse-window display-buffer-pop-up-frame) .
    ((reusable-frames . t)))))

I think something like that should be included as an example somewhere
in the docs - maybe in the documentation of `display-buffer-alist'
itself, maybe in the manual.


Thanks, and regards,

Michael.


In GNU Emacs 24.2.50.1 (x86_64-pc-linux-gnu, GTK+ Version 3.4.2)
 of 2012-11-01 on dex, modified by Debian
 (emacs-snapshot package, version 2:20121101-1)
Windowing system distributor `The X.Org Foundation', version 11.0.10707000
System Description:	Debian GNU/Linux testing (wheezy)

Configured using:
 `configure '--build' 'x86_64-linux-gnu' '--host' 'x86_64-linux-gnu'
 '--prefix=/usr' '--sharedstatedir=/var/lib' '--libexecdir=/usr/lib'
 '--localstatedir=/var' '--infodir=/usr/share/info'
 '--mandir=/usr/share/man' '--with-pop=yes'
 '--enable-locallisppath=/etc/emacs-snapshot:/etc/emacs:/usr/local/share/emacs/24.2.50/site-lisp:/usr/local/share/emacs/site-lisp:/usr/share/emacs/24.2.50/site-lisp:/usr/share/emacs/site-lisp'
 '--without-compress-info' '--with-crt-dir=/usr/lib/x86_64-linux-gnu/'
 '--with-x=yes' '--with-x-toolkit=gtk3' '--with-imagemagick=yes'
 'build_alias=x86_64-linux-gnu' 'host_alias=x86_64-linux-gnu'
 'CFLAGS=-DDEBIAN -DSITELOAD_PURESIZE_EXTRA=5000 -g -O2' 'LDFLAGS=-g
 -Wl,--as-needed -znocombreloc' 'CPPFLAGS=-D_FORTIFY_SOURCE=2''

bug#12848: 24.2.50; Doc: give an example for a typical entry of `display-buffer-alist'

[Drew Adams]

> We should give an example entry, somewhere.

+1

Or even more than one example, since you are now required to use this behemoth
to do what was previously done using any of several simpler user options, not to
mention that you can use it for much more than was possible before.

bug#12848: 24.2.50; Doc: give an example for a typical entry of `display-buffer-alist'

[martin rudalics]

> `display-buffer-alist' entries are quite complex.  OTOH, it's not
> uncommon that a typical user might need it.  We should give an example
> entry, somewhere.
> 
> Today, I thought: "I want that *Help* is always displayed in a new frame
> when it is not already displayed anywhere".  It took some
> time to figure out what was needed:
> 
> (add-to-list
>  'display-buffer-alist
>  '("\\`\\*Help\\*\\'" . ; make *Help* pop up in a new frame when not already displayed
>    ((display-buffer-reuse-window display-buffer-pop-up-frame) .
>     ((reusable-frames . t)))))
> 
> I think something like that should be included as an example somewhere
> in the docs - maybe in the documentation of `display-buffer-alist'
> itself, maybe in the manual.

I tried to provide an example in revision 110885 on the
Emacs-24 release branch.  Please have a look.

Thanks, martin

bug#12848: 24.2.50; Doc: give an example for a typical entry of `display-buffer-alist'

[Michael Heerdegen]

martin rudalics <rudalics@gmx.at> writes:

> I tried to provide an example in revision 110885 on the
> Emacs-24 release branch.  Please have a look.

Thanks.  I think your example is good and covers everything necessary.
It's also consistent with the code.  Very good.

Only one part is a bit unclear to me, namely the last sentence of this
paragraph:

|      (display-buffer
|       (get-buffer-create "*foo*")
|       '((display-buffer-reuse-window
|          display-buffer-pop-up-window
|          display-buffer-pop-up-frame)
|         (reusable-frames . 0)
|         (window-height . 10) (window-width . 40)))
| 
| Evaluating the form above will cause `display-buffer' to proceed as
| follows: If `*foo*' already appears on a visible or iconified frame, it
| will reuse its window.  Otherwise, it will try to pop up a new window
| or, if that is impossible, a new frame.  If all these steps fail, it
| will try to use some existing window.

In this case, the behavior depends on `display-buffer-base-action' and
`display-buffer-fallback-action', right?  Maybe we should mention that,
to make "try to use some existing window" a bit more specific.


Many thanks,

Michael.

bug#12848: 24.2.50; Doc: give an example for a typical entry of `display-buffer-alist'

[martin rudalics]

> In this case, the behavior depends on `display-buffer-base-action' and
> `display-buffer-fallback-action', right?  Maybe we should mention that,
> to make "try to use some existing window" a bit more specific.

I fixed the documentation in that sense.

Thanks, martin