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.

Thanks for these comments.

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

I would like to remove the description of the ALIST entries.  At least
these

 ‘window-height’ -- Value specifies either an integer (the number
    of lines of a new window), a floating point number (the
    fraction of a new window with respect to the height of the
    frame’s root window) or a function to be called with one
    argument - a new window.  The function is supposed to adjust
    the height of the window; its return value is ignored.
    Suitable functions are ‘shrink-window-if-larger-than-buffer’
    and ‘fit-window-to-buffer’.

 ‘window-width’ -- Value specifies either an integer (the number
    of columns of a new window), a floating point number (the
    fraction of a new window with respect to the width of the
    frame’s root window) or a function to be called with one
    argument - a new window.  The function is supposed to adjust
    the width of the window; its return value is ignored.

occupy too much space and are hardly indispensable for understanding
'display-buffer'.  WDYT?

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

It's inserted into the list of 'reusable-frames' after "most of" the
other entries.  So any separate specification of 'reusable-frames'
will usually override it.  Something similar holds for a non-nil
non-list value of the ACTION argument.  Search for 'extra-action' in
the code.  Applications should use neither the one nor the other.

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

I have no opinion in this regard.  If you feel strongly about it,
please change it.

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

I now try to say in the manual in more detail where and how ALIST is
constructed and used.  Inherently, an eventually fully constructed
ALIST is passed to all action functions 'display-buffer' eventually
calls.  But specifying how such an ALIST is constructed cannot be part
of the doc-string.  I now give one example of a fully constructed
ALIST in the manual.  And what an action function does with an entry
is described individually for each action function.

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

Maybe.  There was a time when 'display-buffer' was considered to never
fail.  Even now it hardly ever fails to display a buffer.  You need
quite a couple of ropes to accomplish that.

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

'display-buffer' doesn't throw an error, hopefully.  If it fails it
returns nil.

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

Please change this as you see fit.

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

Yes.  I'll try to fix this as soon as I understand the semantics.
(And please try my patch, read the new sections and send fixes for the more
embarrassing errors.)

Thanks, martin