bug#19461: 25.0.50; doc of `display-buffer-*' functions that take ALIST arg

[martin rudalics]

>> 'display-buffer' calls it ACTION argument.  A problem with this is
>> that so far we do not specify what a "valid" action function is.
>
> Maybe that should be done.  Would there be more to say than that an
> action function should either return a window (success) or nil (fail),

I think that's already all that can be said, maybe including the
special value 'fail' for 'display-buffer-no-window'.

> and respect the specified specifications in the ALIST,

An action function should respect the specifications provided that's
possible.  But due to fact that action lists are combined from various
sources, I'm quite confident that it's possible to construct an
inherently invalid ALIST where an action function "inherits" an ALIST
entry originally meant for another action that failed to produce a
window.  In such case, the display action should do its best to not
respect that entry.

> and what actions
> are predefined?

The predefined actions may vary continuously so that's probably not
very feasible.

>> "This is an action function for buffer display, see Info node `(elisp)
>> Buffer Display Action Functions'.  It should be called only by
>> 'display-buffer' or a function directly or indirectly called by the
>> latter."
>
> Sounds ok.  AFAIU this covers defining new actions by using existing
> ones, like in
>
> (defun my-display-buffer-pop-up-frame-dedicated (b alist)
>    (let ((w (display-buffer-pop-up-frame b alist)))
>      (when (windowp w) (set-window-dedicated-p w t))
>      w))
>
> right?

You mean in the sense that you do not have to provide that text in the
doc-string of 'my-display-buffer-pop-up-frame-dedicated' too?  I think
so.  But I wonder why you don't provide a non-nil 'dedicated' entry in
ALIST here.

martin