unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
From: Eli Zaretskii <eliz@gnu.org>
To: martin rudalics <rudalics@gmx.at>
Cc: emacs-devel@gnu.org
Subject: Re: Documenting buffer display
Date: Sat, 20 Oct 2018 16:21:40 +0300	[thread overview]
Message-ID: <834ldgvjmj.fsf@gnu.org> (raw)
In-Reply-To: <5BCB1D82.3020108@gmx.at> (message from martin rudalics on Sat, 20 Oct 2018 14:20:18 +0200)

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



  reply	other threads:[~2018-10-20 13:21 UTC|newest]

Thread overview: 32+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-10-20 12:20 Documenting buffer display martin rudalics
2018-10-20 13:21 ` Eli Zaretskii [this message]
2018-10-20 18:02   ` martin rudalics
2018-10-21 12:56     ` Eli Zaretskii
2018-10-22  9:06       ` martin rudalics
2018-10-22 13:55         ` Eli Zaretskii
2018-10-22 19:14           ` martin rudalics
2018-10-22 19:27             ` Eli Zaretskii
2018-10-23  8:58               ` martin rudalics
2018-10-23 11:26                 ` Pierre-Yves Luyten
2018-10-23 13:45                   ` martin rudalics
2018-10-23 17:40                   ` Stefan Monnier
2018-10-23 14:04                 ` Drew Adams
2018-10-23 18:18                   ` martin rudalics
2018-10-23 15:18                 ` Eli Zaretskii
2018-10-23 18:23                   ` martin rudalics
2018-10-23 19:07                     ` Eli Zaretskii
2018-10-24  9:44                       ` martin rudalics
2018-10-24 14:48                         ` Eli Zaretskii
2018-10-24 17:40                           ` martin rudalics
2018-10-24 18:25                             ` Eli Zaretskii
2018-10-25 20:42                             ` Juri Linkov
2018-10-23 15:52                 ` Alan Mackenzie
2018-10-23 18:25                   ` martin rudalics
2018-11-08 19:25                   ` martin rudalics
2018-10-22  1:39   ` Michael Welsh Duggan
2018-10-22  5:54     ` Eli Zaretskii
2018-10-20 15:22 ` Drew Adams
2018-10-20 18:02   ` martin rudalics
2018-10-20 18:24     ` Drew Adams
2018-10-21  8:22       ` martin rudalics
2018-11-04  9:06 ` martin rudalics

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.gnu.org/software/emacs/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=834ldgvjmj.fsf@gnu.org \
    --to=eliz@gnu.org \
    --cc=emacs-devel@gnu.org \
    --cc=rudalics@gmx.at \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).