Commit c04b48c0 authored by Martin Rudalics's avatar Martin Rudalics

Rewrite documentation of buffer display

* doc/emacs/windows.texi (Window Choice): Rewrite, replacing
references to older buffer display options with references to
and examples of buffer display actions.
(Temporary Displays): Rewrite display of *Completions*
example.

* doc/lispref/elisp.texi (Top): New Windows section
'Displaying Buffers'.
* doc/lispref/frames.texi (Child Frames): Adjust cross
reference.
* doc/lispref/windows.texi (Windows): New section 'Displaying
Buffers'.  Move sections 'Choosing Window', 'Display Action
Functions' and 'Choosing Window Options' there and adjust
namings.  Preferably write 'Buffer Display Action' instead of
'Display Action'.  More consistently use @w{} to make key
binding specifications unsplittable.
(Displaying Buffers): New section.
(Choosing Window): Make it a subsection of 'Displaying
Buffers'.  More explicitly describe how 'display-buffer'
compiles its list of action functions and the action alist.
(Buffer Display Action Functions): Rename from 'Display Action
Functions', make it a subsection of 'Displaying Buffers' and
rewrite it.  Elide more detailed descriptions of action alist
entries; these are now in the new section 'Buffer Display
Action Functions'.  Remove example.
(Buffer Display Action Alists): New subsection of 'Displaying
Buffers' giving a comprehensive description of recognized
action alist entries with appropriate indexing.  Contents were
partially moved here from the old 'Display Action Functions'
section.
(Choosing Window Options): Make it a subsection of 'Displaying
Buffers'.  Add examples of how to rewrite old buffer display
options with the help of buffer display actions.
(Precedence of Action Functions): New subsection of
'Displaying Buffers' explaining the execution order of action
functions with the help of a detailed example.
(The Zen of Buffer Display): New subsection of 'Displaying
Buffers' supplying guidelines on how to write and use buffer
display actions with examples.
(Side Windows, Displaying Buffers in Side Windows)
(Frame Layouts with Side Windows, Atomic Windows): Update
references to the 'Displaying Buffers' subsections.
parent 7cadb328
......@@ -48,8 +48,8 @@ other windows at all. However, there are other commands such as
@kbd{C-x 4 b} that select a different window and switch buffers in it.
Also, all commands that display information in a window, including
(for example) @kbd{C-h f} (@code{describe-function}) and @kbd{C-x C-b}
(@code{list-buffers}), work by switching buffers in a nonselected
window without affecting the selected window.
(@code{list-buffers}), usually work by displaying buffers in a
nonselected window without affecting the selected window.
When multiple windows show the same buffer, they can have different
regions, because they can have different values of point. However,
......@@ -340,11 +340,9 @@ heights of all the windows in the selected frame.
in response to a user command. There are several different ways in
which commands do this.
Many commands, like @kbd{C-x C-f} (@code{find-file}), display the
buffer by ``taking over'' the selected window, expecting that the
user's attention will be diverted to that buffer. These commands
usually work by calling @code{switch-to-buffer} internally
(@pxref{Select Buffer}).
Many commands, like @kbd{C-x C-f} (@code{find-file}), by default
display the buffer by ``taking over'' the selected window, expecting
that the user's attention will be diverted to that buffer.
Some commands try to display intelligently, trying not to take
over the selected window, e.g., by splitting off a new window and
......@@ -367,10 +365,9 @@ key (@pxref{Pop Up Window}).
Commands with names ending in @code{-other-frame} behave like
@code{display-buffer}, except that they (i) never display in the
selected window and (ii) prefer to create a new frame to display the
desired buffer instead of splitting a window---as though the variable
@code{pop-up-frames} is set to @code{t} (@pxref{Window Choice}).
Several of these commands are bound in the @kbd{C-x 5} prefix key.
selected window and (ii) prefer to either create a new frame or use a
window on some other frame to display the desired buffer. Several of
these commands are bound in the @kbd{C-x 5} prefix key.
@menu
* Window Choice:: How @code{display-buffer} works.
......@@ -383,33 +380,61 @@ Several of these commands are bound in the @kbd{C-x 5} prefix key.
The @code{display-buffer} command (as well as commands that call it
internally) chooses a window to display by following the steps given
below. @xref{Choosing Window,,Choosing a Window for Display, elisp,
The Emacs Lisp Reference Manual}, for details about how to alter this
sequence of steps.
below. @xref{Choosing Window,,Choosing a Window for Displaying a
Buffer, elisp, The Emacs Lisp Reference Manual}, for details about how
to alter this sequence of steps.
@itemize
@vindex same-window-buffer-names
@vindex same-window-regexps
@item
First, check if the buffer should be displayed in the selected window
regardless of other considerations. You can tell Emacs to do this by
adding the desired buffer's name to the list
@code{same-window-buffer-names}, or adding a matching regular
expression to the list @code{same-window-regexps}. By default, these
variables are @code{nil}, so this step is skipped.
adding a regular expression matching the buffer's name together with a
reference to the @code{display-buffer-same-window} action function
(@pxref{Buffer Display Action Functions,,Action Functions for Buffer
Display, elisp, The Emacs Lisp Reference Manual}) to the option
@code{display-buffer-alist} (@pxref{Choosing Window,,Choosing a Window
for Displaying a Buffer, elisp, The Emacs Lisp Reference Manual}).
For example, to display the buffer @file{*scratch*} preferably in the
selected window write:
@example
@group
(customize-set-variable
'display-buffer-alist
'("\\*scratch\\*" (display-buffer-same-window)))
@end group
@end example
By default, @code{display-buffer-alist} is @code{nil}, so this step is
skipped.
@item
Otherwise, if the buffer is already displayed in an existing window,
reuse that window. Normally, only windows on the selected frame
are considered, but windows on other frames are also reusable if you
change @code{pop-up-frames} (see below) to @code{t}.
reuse that window. Normally, only windows on the selected frame are
considered, but windows on other frames are also reusable if a
corresponding @code{reusable-frames} action alist entry (@pxref{Buffer
Display Action Alists,,Action Alists for Buffer Display, elisp, The
Emacs Lisp Reference Manual}) is used (see the next step for an
example of how to do that).
@vindex pop-up-frames
@item
Otherwise, optionally create a new frame and display the buffer there.
By default, this step is skipped. To enable it, change the variable
@code{pop-up-frames} to a non-@code{nil} value. The special value
@code{graphic-only} means to do this only on graphical displays.
By default, this step is skipped. To enable it, change the value of
the option @code{display-buffer-base-action} (@pxref{Choosing
Window,,Choosing a Window for Displaying a Buffer, elisp, The Emacs
Lisp Reference Manual}) as follows:
@example
@group
(customize-set-variable
'display-buffer-base-action
'((display-buffer-reuse-window display-buffer-pop-up-frame)
(reusable-frames . 0)))
@end group
@end example
This customization will also try to make the preceding step search for
a reusable window on all visible of iconified frames
@item
Otherwise, try to create a new window by splitting a window on the
......@@ -429,9 +454,9 @@ window was not split before (to avoid excessive splitting).
@item
Otherwise, display the buffer in a window previously showing it.
Normally, only windows on the selected frame are considered, but if
@code{pop-up-frames} is non-@code{nil} the window may be also on another
frame.
Normally, only windows on the selected frame are considered, but with
a suitable @code{reusable-frames} action alist entry (see above) the
window may be also on another frame.
@item
Otherwise, display the buffer in an existing window on the selected
......@@ -442,14 +467,9 @@ If all the above methods fail for whatever reason, create a new frame
and display the buffer there.
@end itemize
A more advanced and flexible way to customize the behavior of
@code{display-buffer} is by using the option @code{display-buffer-alist}
mentioned in the next section.
@node Temporary Displays
@subsection Displaying non-editable buffers.
@cindex pop-up windows
@cindex temporary windows
Some buffers are shown in windows for perusal rather than for editing.
......@@ -459,24 +479,24 @@ buffer called @file{*Completions*} instead. Such buffers are usually
displayed only for a short period of time.
Normally, Emacs chooses the window for such temporary displays via
@code{display-buffer} as described above. The @file{*Completions*}
buffer, on the other hand, is normally displayed in a window at the
bottom of the selected frame, regardless of the number of windows
already shown on that frame.
@code{display-buffer} as described in the previous subsection. The
@file{*Completions*} buffer, on the other hand, is normally displayed
in a window at the bottom of the selected frame, regardless of the
number of windows already shown on that frame.
If you prefer Emacs to display a temporary buffer in a different
fashion, we recommend customizing the variable
@code{display-buffer-alist} (@pxref{Choosing Window,,Choosing a Window
for Display, elisp, The Emacs Lisp Reference Manual}). For example,
to display @file{*Completions*} by splitting a window as described in
the previous section, use the following form in your initialization
file (@pxref{Init File}):
for Displaying a Buffer, elisp, The Emacs Lisp Reference Manual}).
For example, to display @file{*Completions*} always below the selected
window, use the following form in your initialization file
(@pxref{Init File}):
@example
@group
(customize-set-variable
'display-buffer-alist
'(("\\*Completions\\*" display-buffer-pop-up-window)))
'(("\\*Completions\\*" display-buffer-below-selected)))
@end group
@end example
......
......@@ -1043,9 +1043,7 @@ Windows
* Cyclic Window Ordering:: Moving around the existing windows.
* Buffers and Windows:: Each window displays the contents of a buffer.
* Switching Buffers:: Higher-level functions for switching to a buffer.
* Choosing Window:: How to choose a window for displaying a buffer.
* Display Action Functions:: Subroutines for @code{display-buffer}.
* Choosing Window Options:: Extra options affecting how buffers are displayed.
* Displaying Buffers:: Displaying a buffer in a suitable window.
* Window History:: Each window remembers the buffers displayed in it.
* Dedicated Windows:: How to avoid displaying another buffer in
a specific window.
......@@ -1067,6 +1065,18 @@ Windows
redisplay going past a certain point,
or window configuration changes.
Displaying Buffers
* Choosing Window:: How to choose a window for displaying a buffer.
* Buffer Display Action Functions:: Support functions for buffer display.
* Buffer Display Action Alists:: Alists for fine-tuning buffer display
action functions.
* Choosing Window Options:: Extra options affecting how buffers are displayed.
* Precedence of Action Functions:: A tutorial explaining the precedence of
buffer display action functions.
* The Zen of Buffer Display:: How to avoid that buffers get lost in between
windows.
Side Windows
* Displaying Buffers in Side Windows:: An action function for displaying
......
......@@ -3198,11 +3198,11 @@ and should be preferred when specifying a non-@code{nil}
@code{drag-with-mode-line} parameter.
When a child frame is used for displaying a buffer via
@code{display-buffer-in-child-frame} (@pxref{Display Action Functions}),
the frame's @code{auto-hide-function} parameter (@pxref{Frame
Interaction Parameters}) can be set to a function, in order to
appropriately deal with the frame when the window displaying the buffer
shall be quit.
@code{display-buffer-in-child-frame} (@pxref{Buffer Display Action
Functions}), the frame's @code{auto-hide-function} parameter
(@pxref{Frame Interaction Parameters}) can be set to a function, in
order to appropriately deal with the frame when the window displaying
the buffer shall be quit.
When a child frame is used during minibuffer interaction, for example,
to display completions in a separate window, the @code{minibuffer-exit}
......
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment