[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#19461: 25.0.50; doc of `display-buffer-*' functions that take ALIST
From: |
martin rudalics |
Subject: |
bug#19461: 25.0.50; doc of `display-buffer-*' functions that take ALIST arg |
Date: |
Sat, 3 Aug 2019 09:58:18 +0200 |
>> The doc strings say nothing about parameter ALIST, which in many cases
>> is the most important parameter.
>>
>> One can guess that it is an alist. And one can guess, for the doc
>> strings that mention `inhibit-switch-frame' or
>> `pop-up-frame-parameters', that one or more of its entries can have such
>> a key, but that's all. No guessing helps for
>> `display-buffer-(below-selected|at-bottom|in-previous-window|
>> use-some-window|no-window|same-window|assq-regexp)'. Likewise, some of
>> the "internal" functions.
>
> It is indeed pretty obscure what ALIST is.
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.
> Some of the functions say
> things like
>
> ---
> If ALIST contains a ’window-min-height’ entry, this function
> ensures that the window used is or can become at least as high as
> specified by that entry’s value.
> ---
>
> but looking at the code, it passes ALIST around a lot. So is ALIST a
> general buffer/window property thing?
> At least one of these doc strings
> should say what it is, and the rest could refer to it.
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.
martin
- bug#19461: 25.0.50; doc of `display-buffer-*' functions that take ALIST arg, Lars Ingebrigtsen, 2019/08/02
- bug#19461: 25.0.50; doc of `display-buffer-*' functions that take ALIST arg,
martin rudalics <=
- bug#19461: 25.0.50; doc of `display-buffer-*' functions that take ALIST arg, Eli Zaretskii, 2019/08/03
- bug#19461: 25.0.50; doc of `display-buffer-*' functions that take ALIST arg, Michael Heerdegen, 2019/08/03
- bug#19461: 25.0.50; doc of `display-buffer-*' functions that take ALIST arg, martin rudalics, 2019/08/04
- bug#19461: 25.0.50; doc of `display-buffer-*' functions that take ALIST arg, Michael Heerdegen, 2019/08/04
- bug#19461: 25.0.50; doc of `display-buffer-*' functions that take ALIST arg, martin rudalics, 2019/08/05
- bug#19461: 25.0.50; doc of `display-buffer-*' functions that take ALIST arg, Lars Ingebrigtsen, 2019/08/04
- bug#19461: 25.0.50; doc of `display-buffer-*' functions that take ALIST arg, Michael Heerdegen, 2019/08/04