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

[martin rudalics]

>> This problem is with us since day one of that buffer display code.
>> It's probably due to the fact that the 'display-buffer-*' functions
>> are inherently internal but never have been marked as such in order to
>> describe them in the manual and allow users to add new ones.
>
> What are the non-internal functions which should be called instead of
> these ones (and will call these ones when needed)?

There is just one and that is 'display-buffer' itself.  Functions like
'display-buffer-pop-up-window' or 'display-buffer-same-window' should
never get called by anyone but 'display-buffer' or a function
(in-)directly called by 'display-buffer'.  'display-buffer' is the
only function that can handle precedences correctly and knows how to
build ALIST from its various ingredients.  In fact, one can rewrite
any 'display-buffer-*' function with the help of 'display-buffer' and
an appropriate ACTION argument.

>> Saying what it is is non-trivial, see section 28.13.3 of the Elisp
>> manual.  So I have no good idea how to do what you propose.
>
> I gave it a go on the master branch, please take a look.

Good!  Referring to the Elisp manual seems like the only way to add
something useful.

Thanks, martin