Re: Documenting buffer display

[Alan Mackenzie]

Hello, Martin.

On Tue, Oct 23, 2018 at 10:58:29 +0200, martin rudalics wrote:

[ .... ]

> Then why do we have all this dispute about 'display-buffer'?
> According to the majority of people because its documentation is
> confusing, wrong, incomplete, implicit, arcane or just bad.

I was one of the people recently criticising these things.  I think I
went over the top in what I said, so apologies for that.  The
documentation is difficult because the function does so much.  Yet
display-buffer is a coherent do-one-thing-and-do-it-well function, and I
think any replacement for it would not be as good.

All the same, there are some concrete things in display-buffer's doc
string I would like to comment on.

(i) PLEASE do not delete the extensive description of the ACTION
argument.  Without it, the function would be more difficult to
understand, even if the doc string were shorter.

(ii) The optional argument FRAME gets combined with other ALIST entries.
But where?  Is it considered before or after the other entries?

(iii) "If ACTION is non-nil .... where FUNCTION is either a function or
a list of functions ....".  Would it not be better to call this element
"FUNCTIONS" (plural)?

(iv) "If ACTION is non-nil .... ALIST is an arbitrary association
list...".  This is unfinished.  Could it not say, for example, "... an
arbitrary association list which FOO uses to BAR BAZ (see below)"?

(v) "Based on those arguments, it should display the buffer and return
the window.".  Possibly better would be "it should TRY TO display the
buffer and return the window.".  Maybe.

(vi) (Same paragraph): isn't there a missing "...otherwise the function
will throw an error" after the bit about (allow-no-window . t)?

(vii) `reusable frames': it sort of seems that a list of frames could be
given as the cdr of this entry.  That is not the case.  Maybe the text
could become: "value, AN ATOM, specifies frame(s) to search...".  This
will remove that uncertainty over the possibility of a list of frames,
forcing the reader to follow the hyperlink to get details.

(viii) `allow-no-window' is a little unclear on what happens when a
function fails to display and return a window.  The text implies that
the window remains undisplayed, whereas I think that instead the next
function is tried, and so on, until one returns a window.

> martin

-- 
Alan Mackenzie (Nuremberg, Germany).