Re: Documenting buffer display

[Eli Zaretskii <eliz@gnu.org>]

> Date: Sat, 20 Oct 2018 14:20:18 +0200
> From: martin rudalics <rudalics@gmx.at>
> 
> Attached find a rewrite of the documentation of buffer display
> functions to be applied against the release branch.
> 
> Work in progress.  Proofreading and suggestions welcome.

Thanks, please find a few comments below.

> +@node Displaying Buffers
> +@section Displaying a Buffer in a Suitable Window

Please consider adding one or more @cindex entries here, so that
readers could get here when they look for topics described in this
section.  Similarly for each of the new subsections.

> +In this section we describe how Emacs finds or creates a window
> +suitable for displaying a buffer.  We first introduce the function
> +@code{display-buffer}---the workhorse for choosing such a window.
> +Next, action functions---auxiliary functions called by
> +@code{display-buffer} to find or create a suitable window---are
> +presented.  Then we describe action alists---special association lists
> +used to fine-tune the behavior of action functions.
> +
> +   We continue with the description of additional options to customize
> +the behavior of @code{display-buffer}.  Then a series of examples will
> +try to explain the precedence among action functions in a single call
> +of @code{display-buffer}.  We conclude this section with some
> +guidelines for managing the complexity of buffer display.

I suggest to rewrite this text in terms of what the reader might be
looking for, or as a list of tasks related to the material in the
section.  The way the text is written now, it is an overview of the
topics covered by the section, without any explicit relation to what
the reader may want to do or learn about.  Such "abstract" overviews
are IME much less useful.

> +
> +@menu
> +* Choosing Window::         How to choose a window for displaying a buffer.
> +* Action Functions::        Support functions for buffer display.
> +* Action Alists::           Alists for fine-tuning buffer display.

I question the wisdom of removing "Display" from the names of these
nodes.  "Action Functions" and "Action Alists" are IMO too general,
and might clash with some other kind of "actions".

> +see @ref{Precedence of Action Functions} for an example.

Please put a comma after the right brace here.

> +@node Action Functions
> +@subsection Action Functions for Buffer Display

I think @cindex entries here about "action functions" and "display
action functions" are in order.

>  The following basic action functions are defined in Emacs.  Each of

"Action function" is a term introduced in this section, right?  If so,
its first instance should be in @dfn, and this section should define
the term.

> +display, and @var{alist}, an action alist.  As a rule, each action
> +function is supposed to return a window displaying @var{buffer} if it
> +succeeds and @code{nil} if it fails (for the sole exception to this
> +rule see the last function listed
> +below---@code{display-buffer-no-window}).

I think this exception is better described with the function; here it
is just a distraction.  The general rule should be: describe the
normal case in detail, and leave the exceptional cases for note-like
text near the end.

> +If there is no such window, this function tries to create a new window
> +by splitting the selected one and display @var{buffer} there.  It will
> +also adjust that window's size provided @var{alist} contains a suitable
> +@code{window-height} or @code{window-width} entry, see above.

Here and elsewhere, you mix 2 different styles: one using present
tense ("tries", "fails"), the other using future tense ("will
adjust").  I think we prefer to use the former consistently.

> +@node Action Alists
> +@subsection Action Alists for Buffer Display
> +
> +An action alist (@pxref{Choosing Window}) is an association list
> +mapping predefined symbols recognized by action functions to values

Here you provide the definition of "action alist", so its first
instance should be in @dfn, and there should be a @cindex entry here.

> +   Many efforts in the design of @code{display-buffer} have been given
> +to maintain compatibility with code that uses older options like
> +@code{pop-up-windows}, @code{pop-up-frames},
> +@code{pop-up-frame-alist}, @code{same-window-buffer-names} and
> +@code{same-window-regexps}.  Applications and users should refrain

The text below this should have index entries for the obsolete
variables you describe.

> +Let's now consider the following form:
> +
> +@example
> +(display-buffer (get-buffer-create "*foo*"))
> +@end example
> +
> +@noindent
> +Put this form into the buffer @file{*scratch*} of an uncustomized
> +Emacs session you just started and evaluate it: @code{display-buffer}
> +will fail to reuse a window showing @file{*foo*} but succeed in
> +popping up a new window.  If you evaluate the form again, nothing will
> +change---@code{display-buffer} reused the window already showing
> +@file{*foo*} because that action was applicable and had the highest
> +precedence among all applicable actions.

FWIW, I find such tutorial-like style not really appropriate for a
reference manual.  For starters, it takes more space; more
importantly, it gets to the point only implicitly and requires the
reader to participate in the discovery.  It could even annoy, if the
reader is in a hurry.  Suggest to rewrite as reference text instead.
I'm sure this stuff can be described other than by example.

> +@node The Zen of Buffer Display
> +@subsection The Zen of Buffer Display

This section is also in dire need of useful index entries.

> +@example
> +'(display-buffer-below-selected)
> +@end example
> +
> +on the other hand specifies one action function and an empty action

@noindent is missing here.

> +alist.  To combine the effects of the above two specifications one
> +would write the form
> +
> +@example
> +'(display-buffer-below-selected (inhibit-same-window . t))
> +@end example
> +
> +to add another action function one would write

And here.

> +@example
> +@group
> +'((display-buffer-below-selected display-buffer-at-bottom)
> +  (inhibit-same-window . t))
> +@end group
> +@end example
> +
> +and to add another alist entry one would write

And here.

And a final remark: the last two subsections you added read like more
or less arbitrary collection of tips and tricks.  While it's okay to
do that, I wonder whether such a long list of tricks means there might
be some more meaningful organization of most of this material.  Just a
thought.

Thanks again for working on this.