Re: Documenting buffer display

[martin rudalics]

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

I hope I addressed all issues.  Please have a look.

> (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?

I think it says that now.

> (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)?

I'm not quite sure what you meant here.  'display-buffer' will return
nil after one of its action functions "successfully" processed the
'allow-no-window' entry and will also return nil if it didn't find a
window (which is quite difficult to achieve).  But by design it never
throws an error.

> (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.

I use the tem "set" now.

> (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.

The window remains undisplayed if this entry is actually processed by
an action function and 'display-buffer' returns immediately
thereafter.  No further action functions are tried in that case.

martin