Re: Documenting buffer display

[martin rudalics]

> Thanks, please find a few comments below.

Thanks for the comments.  Everything not cited below will be
corrected in your sense.

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

I haven't done any indexing yet.  Suggestions, like the ones you
provide below, are highly welcome.

>> +In this section we describe how Emacs finds or creates a window
>> +suitable for displaying a buffer.  We first introduce the function
>> address@hidden workhorse for choosing such a window.
>> +Next, action functions---auxiliary functions called by
>> address@hidden 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.

Fully agreed but I ran out of ideas here.  It would be a great help if
you or anyone else came up with a rough sketch of what to do instead.

>> +* 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".

Agreed.  But IMO "display action function" is even worse because
"display" has a very different connotation in Emacs.  So I can only
propose "buffer display action function" or "display buffer action
function" instead.  WDYT?

>> address@hidden Action Functions
>> address@hidden Action Functions for Buffer Display
>
> I think @cindex entries here about "action functions" and "display
> action functions" are in order.

They are already indexed in Choosing Window thusly

@cindex display action
@cindex action function, for @code{display-buffer}
@cindex action alist, for @code{display-buffer}

so you suggest to move the indices to the corresponding sections?

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

They are defined in Choosing Window thusly

Here, @var{function} is either a function or a list of functions,
which we refer to as @dfn{action functions}; @var{alist} is an
association list, which we refer to as an @dfn{action alist}.

so you suggest to move the @dfns to the corresponding sections as well
and leave only the cross references in Choosing Window?

>> address@hidden Action Alists
>> address@hidden 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.

Same as for "Action Functions" above.

>> +   Many efforts in the design of @code{display-buffer} have been given
>> +to maintain compatibility with code that uses older options like
>> address@hidden, @code{pop-up-frames},
>> address@hidden, @code{same-window-buffer-names} and
>> address@hidden  Applications and users should refrain
>
> The text below this should have index entries for the obsolete
> variables you describe.

OK (they are not obsolete yet, BTW).

> FWIW, I find such tutorial-like style

I initially wanted to call this section "A Tutorial for ...".

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

Yes to all.  And I expect everyone who complained in the past about
how difficult it is to work with 'display-buffer' to do exactly that -
participate in the discovery (just as I did when I wrote those
examples).  Please keep in mind: I didn't invent the action functions,
frequently argued that people won't like them and that it will be hard
to document them.  In fact, writing action functions can be a pain and
examples are one way to relieve that pain.  Even if it takes space to
write the examples and time to read them.

> It could even annoy, if the
> reader is in a hurry.

Readers in a hurry are not supposed to read that section.  If
necessary, I can put an according warning at its start.

> Suggest to rewrite as reference text instead.
> I'm sure this stuff can be described other than by example.

On this list people have asked for examples quite often.  Roland
Winkler:

  The current discussion of 'display-buffer-alist' in the elisp manual
  appears rather technical, suited only for expert users.  On the
  other hand, the variable is declared with defcustom, as if
  individual users should customize it to their personal liking.

N. Jackson in the same thread:

  Perhaps `display-buffer-alist' is sufficient for the BBDB case. As
  its documentation is a little unclear (while recursive code is okay,
  recursive documentation is a little bit trying), it would be nice to
  see an example of how this might be done.

Honestly, I have no idea how to do if not with the help of a detailed
sequence of examples.  The "Precedence ..." section is IMO one way to
discover how 'display-buffer' works and why it works the way it does.
If anyone comes up with a better idea I'll be all ears.

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

Have a look at two recent threads.  This one is by Florian Weimer on
help-gnu-emacs:

  I see.  Further questions: How can I restore the window configuration
  after the process terminates?  Is there something similar to
  save-excursion?

To which Stefan Monnier answers:

  If you don't care about other people's configs and you only use a single
  frame, there's save-window-excursion (but for configs like mine, every
  use of save-window-excursion is generally a source of problems).
  A simpler solution to "undo" a pop-to-buffer is to (bury-buffer).

Now the canonical mechanism provided by 'pop-to-buffer' is to use
'quit-window' but how do I tell that to our former maintainer and how
do I put that in the manual?  So I mention it in the Zen section.

Or take this one by Alan:

  I've thought about this overnight.  And I think the answer is no, it
  would not be better to use pop-to-buffer.  At least, not if an ACTION
  argument needs to be constructed.

  The specification of the ACTION argument seems so arcane, so implicit, so
  difficult to use, that it will be simpler just to write a function such
  as edebug-pop-to-buffer.  edebug-pop-to-buffer will also be much easier
  to understand and maintain than an equivalent using pop-to-buffer with an
  ACTION.

  In short, pop-to-buffer and display-buffer with ACTION seem to be
  "pyrrhic functions".  At least, that's how I see it from reading the doc,
  not having yet tried to use them.  Also, edebug-pop-to-buffer already
  exists and works.

  There are around 479 calls to these two functions in the Emacs source.  A
  quick eyeballing of the grep results found just one single use of ACTION,
  in replace.el.  I dare say there are more, but very few altogether.

Maybe some of the tips and tricks I propose here will help Alan to
avoid sleepless nights (and Stefan when quitting an edebug session
will yet another time try to restore his window configuration on the
wrong frame).

martin