Re: Documenting buffer display

[martin rudalics <rudalics@gmx.at>]

 > 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