`display-buffer-alist' - help

[Drew Adams]

It would be helpful if you would provide some guidance wrt the use of
`display-buffer-alist' (both for a user and for 3rd-party/user code
that would test its value).

That could be done in the Emacs manual (preferably) and perhaps a
little bit in the `display-buffer-alist' doc string (dunno).  I
imagine that you were already planning on adding something to the
manual about this, which will be welcome.

Here is some feedback and a few questions, hoping it helps.

Both the current doc string and the Customize buffer for
`display-buffer-alist' are monsters, as I'm sure you'll agree.  The
doc string is 12,125 chars!  214 non-blank lines, comprising 115 whole
sentences, some of which are fairly complex.  And that's just in order
to provide the basic reference explanation (components and their
possible values), not also usage guidance.

Users (I, at least) could use a little more help with this, to make
sense of it all.  This is not something we can expect users to
assimilate easily without a bit of help, IMO.

The doc string is explained in Lisp terms only (cons, car, etc.).
Dunno whether that is appropriate, but it certainly is likely to throw
off a user who tries to figure out the Customize buffer s?he is
confronted with by referring to the doc that accompanies it.

That's a general problem, of course, but the more complex the
Customize buffer and the option structure, the more it can make a
difference.  Here, it is a real obstacle to understanding, IMO.

One thing that might help in this regard is to name the various parts
of the structure that you explain in the doc string, using names that
correspond to (a) what the user sees as Customize field/component/menu
labels: `Side', `Method', `Display', `Even window sizes', etc., or to
(b) what s?he sees as the Customize menu-item labels: `On graphic
displays only' etc.  (I think the former is clearer than the latter,
but sometimes it might help to refer to menu-item names.)

IOW, if you choose to explain the Lisp structure in the doc string,
then perhaps label the structure, using something like this:

 ((BUFFER-IDENTIFIERS DISPLAY-IDENTIFIERS)...), where
 BUFFER-IDENTIFIERS is (IDENTIFIER...), where IDENTIFIER is
 (NAME . BUF-NAME) or (REGEXP . BUF-REGEXP) or
 (LABEL . BUF-LABEL) etc.  And where DISPLAY-IDENTIFIERS is
 (METHOD...), where METHOD is ... etc.

Here, I've just reused the names you currently use in Customize.

Yes, that too is complex and not too easy to follow, but at least if
you use the same names it makes a connection to what users see in
Customize.

It will also perhaps suggest to you to use names that correspond
better among components.  For example, you use `Identifier' as the
menu name for `Buffer identifiers'.  But you use `Method' (not
`Specifier') as the menu name for `Display specifiers'.  The former is
clearer than the latter, esp. when trying to make the connection to
the doc string, since it uses the same term ("identifier") for both.

We appreciate that you have put so much effort into this new feature,
and it is great that you have provided so much careful doc to
accompany the option definition.  No question about that - thank you
for it.  But I'm sure you will appreciate that a little usage guidance
could help.

As one user who has previously used non-nil `pop-up-frames', I would
like, as a start, to know what I might customize
`display-buffer-alist' to, to get the closest behavior to what I had
before using `pop-up-frames', since that option is being deprecated.

And after doing that, should I set `pop-up-frames' to nil? or to
`unset' (the new default)? or leave it customized to t?  (I'm
guessing `unset', but I am not sure.)  IOW, since you would like to
wean people off of `pop-up-frames', please provide some upgrade
guidance.

Here is a related example of confusion.  I notice that without my
having customized or otherwise changed `display-buffer-alist' at all
explicitly, when I do `C-h v display-buffer-alist' it shows that the
current value differs from the "original" value.  `C-h v' shows both
values, which I guess is new with Emacs 24.  (See bug #8856 for the
emacs -Q load file that gives this.)

Did that change to `display-buffer-alist' from its original value come
from my setting `pop-up-frames' to t?  I guess not since, starting
from emacs -Q, if I do (setq pop-up-frames t) or if I use Customize to
change `pop-up-frames', `C-h v display-buffer-alist' then does not
show a current value of `display-buffer-alist' that differs from the
original value - the original value is unchanged.

Did that change to `display-buffer-alist' come from your silent
"normalization" of the value (via
`display-buffer-normalize-(specifiers|alist)')?  If so, shouldn't that
normalization already be incorporated into the "original value" shown
by `C-h v'?

IOW, is the normalization a part of defining the original value?
Maybe not, since the normalization seems (according to what I see in
the code) to be carried out only when displaying (`display-buffer').

But then what does change the original value (for `C-h v')?  I have no
idea where this comes from.  Just asking, as this under-the-covers
changing of the original value is confusing to me so far.

I also grepped for `display-buffer-alist-set' and
`display-buffer-alist-add' in the Lisp sources, since they are the
only places in `window.el' where you change `display-buffer-alist',
but it seems those functions are not even used yet (from Lisp at
least), so I guess they are not related to the behind-the-back value
change.

This is the kind of confusion that I'm hoping a little
`display-buffer-alist' usage explanation will clear up.  Thx.