@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012
@c Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
-@node Display, Search, Registers, Top
+@node Display
@chapter Controlling the Display
Since only part of a large buffer fits in the window, Emacs has to
@menu
* Scrolling:: Commands to move text up and down in a window.
+* Recentering:: A scroll command that centers the current line.
* Auto Scrolling:: Redisplay scrolls text automatically when needed.
* Horizontal Scrolling:: Moving text left and right in a window.
* Narrowing:: Restricting display and editing to a portion
* View Mode:: Viewing read-only buffers.
* Follow Mode:: Follow mode lets two windows scroll as one.
* Faces:: How to change the display style using faces.
-* Standard Faces:: Emacs' predefined faces.
+* Colors:: Specifying colors for faces.
+* Standard Faces:: The main predefined faces.
* Text Scale:: Increasing or decreasing text size in a buffer.
* Font Lock:: Minor mode for syntactic highlighting using faces.
* Highlight Interactively:: Tell Emacs what text to highlight.
* Fringes:: Enabling or disabling window fringes.
* Displaying Boundaries:: Displaying top and bottom of the buffer.
-* Useless Whitespace:: Showing possibly-spurious trailing whitespace.
+* Useless Whitespace:: Showing possibly spurious trailing whitespace.
* Selective Display:: Hiding lines with lots of indentation.
* Optional Mode Line:: Optional mode line display features.
* Text Display:: How text characters are normally displayed.
Scrolling ``forward'' or ``up'' advances the portion of the buffer
displayed in the window; equivalently, it moves the buffer text
upwards relative to the window. Scrolling ``backward'' or ``down''
-moves the displayed portion backwards, and moves the text downwards
-relative to the window. In Emacs, scrolling ``up'' or ``down'' refers
-to the direction that the text moves in the window, @emph{not} the
-direction that the window moves relative to the text; this terminology
-was taken up by Emacs before the modern meaning of ``scrolling up''
-and ``scrolling down'' became widely adopted. Hence the strange
-result that @key{PageDown} scrolls ``up'' in the Emacs sense. In this
-manual, we refer to scrolling ``forward'' and ``backward'' where
-possible, in order to minimize confusion.
+displays an earlier portion of the buffer, and moves the text
+downwards relative to the window.
+
+ In Emacs, scrolling ``up'' or ``down'' refers to the direction that
+the text moves in the window, @emph{not} the direction that the window
+moves relative to the text. This terminology was adopted by Emacs
+before the modern meaning of ``scrolling up'' and ``scrolling down''
+became widespread. Hence, the strange result that @key{PageDown}
+scrolls ``up'' in the Emacs sense.
The portion of a buffer displayed in a window always contains point.
If you move point past the bottom or top of the window, scrolling
Scrolling}). You can also scroll explicitly with these commands:
@table @kbd
-@item C-l
-Scroll the selected window so that the current line is the center-most
-text line; on subsequent consecutive invocations, make the current
-line the top-most line, the bottom-most line, and so on in cyclic
-order; also, maybe redisplay the screen (@code{recenter-top-bottom}).
@item C-v
@itemx @key{next}
@itemx @key{PageDown}
@itemx @key{prior}
@itemx @key{PageUp}
Scroll backward (@code{scroll-down-command}).
+@end table
+
+@kindex C-v
+@kindex M-v
+@kindex next
+@kindex prior
+@kindex PageDown
+@kindex PageUp
+@findex scroll-up-command
+@findex scroll-down-command
+ @kbd{C-v} (@code{scroll-up-command}) scrolls forward by nearly the
+whole window height. The effect is to take the two lines at the
+bottom of the window and put them at the top, followed by lines that
+were not previously visible. If point was in the text that scrolled
+off the top, it ends up on the window's new topmost line. The
+@key{next} (or @key{PageDown}) key is equivalent to @kbd{C-v}.
+
+ @kbd{M-v} (@code{scroll-down-command}) scrolls backward in a similar
+way. The @key{prior} (or @key{PageUp}) key is equivalent to
+@kbd{M-v}.
+
+@vindex next-screen-context-lines
+ The number of lines of overlap left by these scroll commands is
+controlled by the variable @code{next-screen-context-lines}, whose
+default value is 2. You can supply the commands with a numeric prefix
+argument, @var{n}, to scroll by @var{n} lines; Emacs attempts to leave
+point unchanged, so that the text and point move up or down together.
+@kbd{C-v} with a negative argument is like @kbd{M-v} and vice versa.
+
+@vindex scroll-error-top-bottom
+ By default, these commands signal an error (by beeping or flashing
+the screen) if no more scrolling is possible, because the window has
+reached the beginning or end of the buffer. If you change the
+variable @code{scroll-error-top-bottom} to @code{t}, the command moves
+point to the farthest possible position. If point is already there,
+the command signals an error.
+
+@vindex scroll-preserve-screen-position
+@cindex @code{scroll-command} property
+ Some users like scroll commands to keep point at the same screen
+position, so that scrolling back to the same screen conveniently
+returns point to its original position. You can enable this behavior
+via the variable @code{scroll-preserve-screen-position}. If the value
+is @code{t}, Emacs adjusts point to keep the cursor at the same screen
+position whenever a scroll command moves it off-window, rather than
+moving it to the topmost or bottommost line. With any other
+non-@code{nil} value, Emacs adjusts point this way even if the scroll
+command leaves point in the window. This variable affects all the
+scroll commands documented in this section, as well as scrolling with
+the mouse wheel (@pxref{Mouse Commands}); in general, it affects any
+command that has a non-@code{nil} @code{scroll-command} property.
+@xref{Property Lists,,, elisp, The Emacs Lisp Reference Manual}.
+
+@vindex scroll-up
+@vindex scroll-down
+@findex scroll-up-line
+@findex scroll-down-line
+ The commands @kbd{M-x scroll-up} and @kbd{M-x scroll-down} behave
+similarly to @code{scroll-up-command} and @code{scroll-down-command},
+except they do not obey @code{scroll-error-top-bottom}. Prior to
+Emacs 24, these were the default commands for scrolling up and down.
+The commands @kbd{M-x scroll-up-line} and @kbd{M-x scroll-down-line}
+scroll the current window by one line at a time. If you intend to use
+any of these commands, you might want to give them key bindings
+(@pxref{Init Rebinding}).
+
+@node Recentering
+@section Recentering
+
+@table @kbd
+@item C-l
+Scroll the selected window so the current line is the center-most text
+line; on subsequent consecutive invocations, make the current line the
+top line, the bottom line, and so on in cyclic order. Possibly
+redisplay the screen too (@code{recenter-top-bottom}).
+
+@item M-x recenter
+Scroll the selected window so the current line is the center-most text
+line. Possibly redisplay the screen too.
+
@item C-M-l
Scroll heuristically to bring useful information onto the screen
(@code{reposition-window}).
screen lines between point and the top or bottom of the window
(@pxref{Auto Scrolling}).
- You can also supply @kbd{C-l} with a prefix argument. With a plain
-prefix argument, @kbd{C-u C-l}, Emacs simply recenters point. With a
-positive argument @var{n}, it scrolls to place point @var{n} lines
-down from the top of the window. An argument of zero puts point on
-the topmost line. A negative argument @var{-n} puts point @var{n}
-lines from the bottom of the window. When given an argument,
-@kbd{C-l} does not clear the screen or cycle through different screen
-positions.
+ You can also give @kbd{C-l} a prefix argument. A plain prefix
+argument, @kbd{C-u C-l}, simply recenters point. A positive argument
+@var{n} puts point @var{n} lines down from the top of the window. An
+argument of zero puts point on the topmost line. A negative argument
+@var{-n} puts point @var{n} lines from the bottom of the window. When
+given an argument, @kbd{C-l} does not clear the screen or cycle
+through different screen positions.
@vindex recenter-redisplay
If the variable @code{recenter-redisplay} has a non-@code{nil}
The more primitive command @kbd{M-x recenter} behaves like
@code{recenter-top-bottom}, but does not cycle among screen positions.
-@kindex C-v
-@kindex M-v
-@kindex next
-@kindex prior
-@kindex PageDown
-@kindex PageUp
-@findex scroll-up-command
-@findex scroll-down-command
- @kbd{C-v} (@code{scroll-up-command}) scrolls forward by nearly the
-whole window height. The effect is to take the two lines at the
-bottom of the window and put them at the top, followed by lines that
-were not previously visible. If point was in the text that scrolled
-off the top, it ends up on the window's new topmost line.
-
- Similarly, @kbd{M-v} (@code{scroll-down-command}) scrolls backward.
-
- We refer to @kbd{C-v} and @kbd{M-v} as @dfn{full-screen scroll
-commands}. The function key @key{next}, or @key{PageDown}, is
-equivalent to @kbd{C-v}; the function key @key{prior}, or
-@key{PageUp}, is equivalent to @kbd{M-v}.
-
-@vindex next-screen-context-lines
- The variable @code{next-screen-context-lines} controls the number of
-lines of overlap left by the full-screen scroll commands; by default,
-it is 2. You can supply these commands with a numeric prefix argument
-@var{n}. This scrolls the window by @var{n} lines, while attempting
-to leave point unchanged (so that the text and point move up or down
-together). @kbd{C-v} with a negative argument is like @kbd{M-v} and
-vice versa.
-
-@vindex scroll-error-top-bottom
- By default, the full-screen scroll commands signal an error (by
-beeping or flashing the screen) if no more scrolling is possible,
-because the window has reached the beginning or end of the buffer. If
-you change the variable @code{scroll-error-top-bottom} to @code{t},
-Emacs instead moves point to the farthest possible position. If point
-is already there, the command signals an error.
-
-@vindex scroll-preserve-screen-position
- Some users like scroll commands to keep point at the same screen
-position. Then, scrolling back to the same screen also conveniently
-returns point to its original position. You can enable this via the
-variable @code{scroll-preserve-screen-position}. If the value is
-@code{t}, Emacs adjusts point to keep it at the same vertical position
-within the window, rather than the window edge, whenever a scroll
-command moves it off the window. With any other non-@code{nil} value,
-Emacs adjusts point this way even if the scroll command leaves point
-in the window.
-
-@vindex scroll-up
-@vindex scroll-down
- The commands @code{scroll-up} and @code{scroll-down} behave
-similarly to @code{scroll-up-command} and @code{scroll-down-command},
-except they do not obey @code{scroll-error-top-bottom}. Prior to
-Emacs 24, these were the default commands for scrolling up and down.
-
@kindex C-M-l
@findex reposition-window
@kbd{C-M-l} (@code{reposition-window}) scrolls the current window
@cindex aggressive scrolling
@vindex scroll-up-aggressively
@vindex scroll-down-aggressively
- When the window does scroll by a longer distance, you can control
-how aggressively it scrolls by setting the variables
-@code{scroll-up-aggressively} and @code{scroll-down-aggressively}.
-The value of @code{scroll-up-aggressively} should be either
-@code{nil}, or a fraction @var{f} between 0 and 1. A fraction
-specifies where on the screen to put point when scrolling upward,
-i.e. forward. When point goes off the window end, the new start
-position is chosen to put point @var{f} parts of the window height
-from the bottom. Thus, larger @var{f} means more aggressive
-scrolling: more new text is brought into view. The default value,
-@code{nil}, is equivalent to 0.5.
+ When the window does scroll by a distance longer than
+@code{scroll-step}, you can control how aggressively it scrolls by
+setting the variables @code{scroll-up-aggressively} and
+@code{scroll-down-aggressively}. The value of
+@code{scroll-up-aggressively} should be either @code{nil}, or a
+fraction @var{f} between 0 and 1. A fraction specifies where on the
+screen to put point when scrolling upward, i.e.@: forward. When point
+goes off the window end, the new start position is chosen to put point
+@var{f} parts of the window height from the bottom margin. Thus,
+larger @var{f} means more aggressive scrolling: more new text is
+brought into view. The default value, @code{nil}, is equivalent to
+0.5.
Likewise, @code{scroll-down-aggressively} is used for scrolling
-down, i.e. backward. The value specifies how far point should be
-placed from the top of the window; thus, as with
+down, i.e.@: backward. The value specifies how far point should be
+placed from the top margin of the window; thus, as with
@code{scroll-up-aggressively}, a larger value is more aggressive.
These two variables are ignored if either @code{scroll-step} or
@vindex scroll-margin
The variable @code{scroll-margin} restricts how close point can come
-to the top or bottom of a window. Its value is a number of screen
+to the top or bottom of a window (even if aggressive scrolling
+specifies a fraction @var{f} that is larger than the window portion
+between the top and the bottom margins). Its value is a number of screen
lines; if point comes within that many lines of the top or bottom of
the window, Emacs performs automatic scrolling. By default,
@code{scroll-margin} is 0.
screen. To disable automatic horizontal scrolling, set the variable
@code{auto-hscroll-mode} to @code{nil}. Note that when the automatic
horizontal scrolling is turned off, if point moves off the edge of the
-screen, the cursor disappears to indicate that. (On text-only
-terminals, the cursor is left at the edge instead.)
+screen, the cursor disappears to indicate that. (On text terminals,
+the cursor is left at the edge instead.)
@vindex hscroll-margin
The variable @code{hscroll-margin} controls how close point can get
@cindex synchronizing windows
@dfn{Follow mode} is a minor mode that makes two windows, both
-showing the same buffer, scroll as a single tall ``virtual window.''
+showing the same buffer, scroll as a single tall ``virtual window''.
To use Follow mode, go to a frame with just one window, split it into
two side-by-side windows using @kbd{C-x 3}, and then type @kbd{M-x
follow-mode}. From then on, you can edit the buffer in either of the
To turn off Follow mode, type @kbd{M-x follow-mode} a second time.
@node Faces
-@section Faces: Controlling Text Display Style
+@section Text Faces
@cindex faces
Emacs can display text in several different styles, called
matching that regular expression (@pxref{Regexps}).
It's possible for a given face to look different in different
-frames. For instance, some text-only terminals do not support all
-face attributes, particularly font, height, and width, and some
-support a limited range of colors. The @code{list-faces-display}
-command shows the appearance for the selected frame.
+frames. For instance, some text terminals do not support all face
+attributes, particularly font, height, and width, and some support a
+limited range of colors.
-@cindex face colors, setting
@cindex background color
@cindex default face
You can customize a face to alter its appearance, and save those
changes for future Emacs sessions. @xref{Face Customization}. A face
does not have to specify every single attribute; often it inherits
most attributes from another face. Any ultimately unspecified
-attribute is taken from a face named @code{default}, whose attributes
-are all specified. The @code{default} face is the default for
-displaying text, and its background color is also used as the frame's
-background color.
+attribute is taken from the face named @code{default}.
+
+ The @code{default} face is the default for displaying text, and all
+of its attributes are specified. Its background color is also used as
+the frame's background color. @xref{Colors}.
+
+@cindex cursor face
+ Another special face is the @code{cursor} face. On graphical
+displays, the background color of this face is used to draw the text
+cursor. None of the other attributes of this face have any effect;
+the foreground color for text under the cursor is taken from the
+background color of the underlying text. On text terminals, the
+appearance of the text cursor is determined by the terminal, not by
+the @code{cursor} face.
You can also use X resources to specify attributes of any particular
face. @xref{Resources}.
+ Emacs can display variable-width fonts, but some Emacs commands,
+particularly indentation commands, do not account for variable
+character display widths. Therefore, we recommend not using
+variable-width fonts for most faces, particularly those assigned by
+Font Lock mode.
+
+@node Colors
+@section Colors for Faces
+@cindex color name
+@cindex RGB triplet
+
+ Faces can have various foreground and background colors. When you
+specify a color for a face---for instance, when customizing the face
+(@pxref{Face Customization})---you can use either a @dfn{color name}
+or an @dfn{RGB triplet}.
+
+@findex list-colors-display
+@vindex list-colors-sort
+ A color name is a pre-defined name, such as @samp{dark orange} or
+@samp{medium sea green}. To view a list of color names, type @kbd{M-x
+list-colors-display}. To control the order in which colors are shown,
+customize @code{list-colors-sort}. If you run this command on a
+graphical display, it shows the full range of color names known to
+Emacs (these are the standard X11 color names, defined in X's
+@file{rgb.txt} file). If you run the command on a text terminal, it
+shows only a small subset of colors that can be safely displayed on
+such terminals. However, Emacs understands X11 color names even on
+text terminals; if a face is given a color specified by an X11 color
+name, it is displayed using the closest-matching terminal color.
+
+ An RGB triplet is a string of the form @samp{#RRGGBB}. Each of the
+R, G, and B components is a hexadecimal number specifying the
+component's relative intensity, one to four digits long (usually two
+digits are used). The components must have the same number of digits.
+For hexadecimal values A to F, either upper or lower case are
+acceptable.
+
+ The @kbd{M-x list-colors-display} command also shows the equivalent
+RGB triplet for each named color. For instance, @samp{medium sea
+green} is equivalent to @samp{#3CB371}.
+
+@cindex face colors, setting
@findex set-face-foreground
@findex set-face-background
- You can also change the foreground and background colors of a face
-with @kbd{M-x set-face-foreground} and @kbd{M-x set-face-background}.
-These commands prompt in the minibuffer for a face name and a color
-name, with completion, and then set that face to use the specified
-color (@pxref{Face Customization}, for information about color names).
+ You can change the foreground and background colors of a face with
+@kbd{M-x set-face-foreground} and @kbd{M-x set-face-background}.
+These commands prompt in the minibuffer for a face name and a color,
+with completion, and then set that face to use the specified color.
They affect the face colors on all frames, but their effects do not
persist for future Emacs sessions, unlike using the customization
buffer or X resources. You can also use frame parameters to set
-foreground and background colors for a specific frame; see @ref{Frame
+foreground and background colors for a specific frame; @xref{Frame
Parameters}.
- Emacs can display variable-width fonts, but some Emacs commands,
-particularly indentation commands, do not account for variable
-character display widths. Therefore, we recommend not using
-variable-width fonts for most faces, particularly those assigned by
-Font Lock mode.
-
@node Standard Faces
@section Standard Faces
The face for displaying control characters and escape sequences
(@pxref{Text Display}).
@item nobreak-space
-The face for displaying ``non-breaking'' space characters (@pxref{Text
+The face for displaying ``no-break'' space characters (@pxref{Text
Display}).
@end table
Most windows do not have a header line---only some special modes, such
Info mode, create one.
@item vertical-border
-This face is used for the vertical divider between windows on
-text-only terminals.
+This face is used for the vertical divider between windows on text
+terminals.
@item minibuffer-prompt
@cindex @code{minibuffer-prompt} face
@vindex minibuffer-prompt-properties
between the text area and the window's right and left borders.)
@xref{Fringes}.
@item cursor
-This face determines the color of the text cursor.
+The @code{:background} attribute of this face specifies the color of
+the text cursor. @xref{Cursor Display}.
@item tooltip
This face is used for tooltip text. By default, if Emacs is built
with GTK support, tooltips are drawn via GTK and this face has no
@end table
The following faces likewise control the appearance of parts of the
-Emacs frame, but only on text-only terminals, or when Emacs is built
-on X with no toolkit support. (For all other cases, the appearance of
-the respective frame elements is determined by system-wide settings.)
+Emacs frame, but only on text terminals, or when Emacs is built on X
+with no toolkit support. (For all other cases, the appearance of the
+respective frame elements is determined by system-wide settings.)
@table @code
@item scroll-bar
@findex global-font-lock-mode
@vindex global-font-lock-mode
- To toggle Font Lock mode in all buffers, type @kbd{M-x
-global-font-lock-mode}. To impose this setting for future Emacs
-sessions, customize the variable @code{global-font-lock-mode}
-(@pxref{Easy Customization}), or add the following line to your init
-file:
+ Type @kbd{M-x global-font-lock-mode} to toggle Font Lock mode in all
+buffers. To impose this setting for future Emacs sessions, customize
+the variable @code{global-font-lock-mode} (@pxref{Easy
+Customization}), or add the following line to your init file:
@example
(global-font-lock-mode 0)
@end example
-@findex turn-on-font-lock
@noindent
If you have disabled Global Font Lock mode, you can still enable Font
Lock for specific major modes by adding the function
-@code{turn-on-font-lock} to the mode hooks (@pxref{Hooks}). For
-example, to enable Font Lock mode for editing C files, you can do
-this:
+@code{font-lock-mode} to the mode hooks (@pxref{Hooks}). For example,
+to enable Font Lock mode for editing C files, you can do this:
@example
-(add-hook 'c-mode-hook 'turn-on-font-lock)
+(add-hook 'c-mode-hook 'font-lock-mode)
@end example
Font Lock mode uses several specifically named faces to do its job,
the sake of speed, some modes, including Lisp mode, rely on a special
convention: an open-parenthesis or open-brace in the leftmost column
always defines the beginning of a defun, and is thus always outside
-any string or comment. Therefore, you should avoid placing a an
+any string or comment. Therefore, you should avoid placing an
open-parenthesis or open-brace in the leftmost column, if it is inside
a string or comment. @xref{Left Margin Paren}, for details.
@section Window Fringes
@cindex fringes
- On a graphical display, each Emacs window normally has narrow
+@findex set-fringe-style
+@findex fringe-mode
+ On graphical displays, each Emacs window normally has narrow
@dfn{fringes} on the left and right edges. The fringes are used to
display symbols that provide information about the text in the window.
+You can type @kbd{M-x fringe-mode} to disable the fringes, or modify
+their width. This command affects fringes in all frames; to modify
+fringes on the selected frame only, use @kbd{M-x set-fringe-style}.
The most common use of the fringes is to indicate a continuation
line (@pxref{Continuation Lines}). When one line of text is split
into multiple screen lines, the left fringe shows a curving arrow for
each screen line except the first, indicating that ``this is not the
-real beginning.'' The right fringe shows a curving arrow for each
+real beginning''. The right fringe shows a curving arrow for each
screen line except the last, indicating that ``this is not the real
-end.'' If the line's direction is right-to-left (@pxref{Bidirectional
+end''. If the line's direction is right-to-left (@pxref{Bidirectional
Editing}), the meanings of the curving arrows in the fringes are
swapped.
The fringes indicate line truncation with short horizontal arrows
meaning ``there's more text on this line which is scrolled
-horizontally out of view.'' Clicking the mouse on one of the arrows
+horizontally out of view''. Clicking the mouse on one of the arrows
scrolls the display horizontally in the direction of the arrow.
The fringes can also indicate other things, such as buffer
boundaries (@pxref{Displaying Boundaries}), and where a program you
are debugging is executing (@pxref{Debuggers}).
-@findex set-fringe-style
-@findex fringe-mode
- You can enable and disable the fringes for all frames using
-@kbd{M-x fringe-mode}. To enable and disable the fringes
-for the selected frame, use @kbd{M-x set-fringe-style}.
+@vindex overflow-newline-into-fringe
+ The fringe is also used for drawing the cursor, if the current line
+is exactly as wide as the window and point is at the end of the line.
+To disable this, change the variable
+@code{overflow-newline-into-fringe} to @code{nil}; this causes Emacs
+to continue or truncate lines that are exactly as wide as the window.
@node Displaying Boundaries
@section Displaying Boundaries
@vindex indicate-buffer-boundaries
- On a graphical display, Emacs can indicate the buffer boundaries in
+ On graphical displays, Emacs can indicate the buffer boundaries in
the fringes. If you enable this feature, the first line and the last
line are marked with angle images in the fringes. This can be
combined with up and down arrow images which say whether it is
@cindex fringes, and unused line indication
On graphical displays, Emacs can indicate unused lines at the end of
the window with a small image in the left fringe (@pxref{Fringes}).
-The image appears for window lines that do not correspond to any
-buffer text. Blank lines at the end of the buffer then stand out
-because they do not have this image in the fringe. To enable this
-feature, set the buffer-local variable @code{indicate-empty-lines} to
-a non-@code{nil} value. You can enable or disable this feature for
-all new buffers by setting the default value of this variable,
-e.g.@:@code{(setq-default indicate-empty-lines t)}.
+The image appears for screen lines that do not correspond to any
+buffer text, so blank lines at the end of the buffer stand out because
+they lack this image. To enable this feature, set the buffer-local
+variable @code{indicate-empty-lines} to a non-@code{nil} value. You
+can enable or disable this feature for all new buffers by setting the
+default value of this variable, e.g.@: @code{(setq-default
+indicate-empty-lines t)}.
+
+@cindex Whitespace mode
+@cindex mode, Whitespace
+@findex whitespace-mode
+@vindex whitespace-style
+ Whitespace mode is a buffer-local minor mode that lets you
+``visualize'' many kinds of whitespace in the buffer, by either
+drawing the whitespace characters with a special face or displaying
+them as special glyphs. To toggle this mode, type @kbd{M-x
+whitespace-mode}. The kinds of whitespace visualized are determined
+by the list variable @code{whitespace-style}. Here is a partial list
+of possible elements (see the variable's documentation for the full
+list):
+
+@table @code
+@item face
+Enable all visualizations which use special faces. This element has a
+special meaning: if it is absent from the list, none of the other
+visualizations take effect except @code{space-mark}, @code{tab-mark},
+and @code{newline-mark}.
+
+@item trailing
+Highlight trailing whitespace.
+
+@item tabs
+Highlight tab characters.
+
+@item spaces
+Highlight space and non-breaking space characters.
+
+@item lines
+@vindex whitespace-line-column
+Highlight lines longer than 80 lines. To change the column limit,
+customize the variable @code{whitespace-line-column}.
+
+@item newline
+Highlight newlines.
+
+@item empty
+Highlight empty lines.
+
+@item space-mark
+Draw space and non-breaking characters with a special glyph.
+
+@item tab-mark
+Draw tab characters with a special glyph.
+
+@item newline-mark
+Draw newline characters with a special glyph.
+@end table
@node Selective Display
@section Selective Display
@vindex display-time-mail-file
@vindex display-time-mail-directory
The word @samp{Mail} appears after the load level if there is mail
-for you that you have not read yet. On a graphical display you can use
-an icon instead of @samp{Mail} by customizing
-@code{display-time-use-mail-icon}; this may save some space on the mode
-line. You can customize @code{display-time-mail-face} to make the mail
-indicator prominent. Use @code{display-time-mail-file} to specify
-the mail file to check, or set @code{display-time-mail-directory}
-to specify the directory to check for incoming mail (any nonempty regular
-file in the directory is considered as ``newly arrived mail'').
+for you that you have not read yet. On graphical displays, you can
+use an icon instead of @samp{Mail} by customizing
+@code{display-time-use-mail-icon}; this may save some space on the
+mode line. You can customize @code{display-time-mail-face} to make
+the mail indicator prominent. Use @code{display-time-mail-file} to
+specify the mail file to check, or set
+@code{display-time-mail-directory} to specify the directory to check
+for incoming mail (any nonempty regular file in the directory is
+considered as ``newly arrived mail'').
@cindex mail (on mode line)
@findex display-battery-mode
@cindex mode line, 3D appearance
@cindex attributes of mode line, changing
@cindex non-integral number of lines in a window
- On a graphical display, the mode line is drawn as a 3D box. If you
+ On graphical displays, the mode line is drawn as a 3D box. If you
don't like this effect, you can disable it by customizing the
@code{mode-line} face and setting its @code{box} attribute to
@code{nil}. @xref{Face Customization}.
characters, as well as many non-@acronym{ASCII} characters.
@vindex tab-width
-@cindex control character
+@cindex control characters on display
The @acronym{ASCII} character set contains non-printing @dfn{control
characters}. Two of these are displayed specially: the newline
character (Unicode code point @code{U+000A}) is displayed by starting
in the buffer is displayed has nothing to do with the definition of
@key{TAB} as a command.
- Other @acronym{ASCII} control characters are displayed as a caret
+ Other @acronym{ASCII} control characters, whose codes are below
+@code{U+0020} (octal 40, decimal 32), are displayed as a caret
(@samp{^}) followed by the non-control version of the character, with
the @code{escape-glyph} face. For instance, the @samp{control-A}
character, @code{U+0001}, is displayed as @samp{^A}.
+@cindex octal escapes
@vindex ctl-arrow
- The non-@acronym{ASCII}, non-printing characters @code{U+0080}
-(octal 200) through @code{U+009F} (octal 237) are displayed as octal
-escape sequences, with the @code{escape-glyph} face. For instance,
+ The raw bytes with codes @code{U+0080} (octal 200) through
+@code{U+009F} (octal 237) are displayed as @dfn{octal escape
+sequences}, with the @code{escape-glyph} face. For instance,
character code @code{U+0098} (octal 230) is displayed as @samp{\230}.
If you change the buffer-local variable @code{ctl-arrow} to
-@code{nil}, @acronym{ASCII} control characters are also displayed as
-octal escape sequences instead of caret escape sequences.
+@code{nil}, the @acronym{ASCII} control characters are also displayed
+as octal escape sequences instead of caret escape sequences.
@vindex nobreak-char-display
-@cindex non-breaking space, display
-@cindex non-breaking hyphen, display
-@cindex soft hyphen, display
- There are two special ``non-breaking'' versions of the space and
-hyphen characters, which are used where a line should not be broken.
-Emacs normally displays these characters with special faces
-(respectively, @code{nobreak-space} and @code{escape-glyph}) to
-distinguish them from ordinary spaces and hyphens. You can turn off
-this feature by setting the variable @code{nobreak-char-display} to
-@code{nil}. If you set the variable to any other value, that means to
-prefix these characters with an escape character.
+@cindex non-breaking space
+@cindex non-breaking hyphen
+@cindex soft hyphen
+ Some non-@acronym{ASCII} characters have the same appearance as an
+@acronym{ASCII} space or hyphen (minus) character. Such characters
+can cause problems if they are entered into a buffer without your
+realization, e.g.@: by yanking; for instance, source code compilers
+typically do not treat non-@acronym{ASCII} spaces as whitespace
+characters. To deal with this problem, Emacs displays such characters
+specially: it displays @code{U+00A0} (no-break space) with the
+@code{nobreak-space} face, and it displays @code{U+00AD} (soft
+hyphen), @code{U+2010} (hyphen), and @code{U+2011} (non-breaking
+hyphen) with the @code{escape-glyph} face. To disable this, change
+the variable @code{nobreak-char-display} to @code{nil}. If you give
+this variable a non-@code{nil} and non-@code{t} value, Emacs instead
+displays such characters as a highlighted backslash followed by a
+space or hyphen.
You can customize the way any particular character code is displayed
by means of a display table. @xref{Display Tables,, Display Tables,
On graphical displays, some characters may have no glyphs in any of
the fonts available to Emacs. These @dfn{glyphless characters} are
normally displayed as boxes containing the hexadecimal character code.
-You can control the display method by customizing the variable
-@code{glyphless-char-display-control}. @xref{Glyphless Chars,,
-Glyphless Character Display, elisp, The Emacs Lisp Reference Manual},
-for details.
+Similarly, on text terminals, characters that cannot be displayed
+using the terminal encoding (@pxref{Terminal Coding}) are normally
+displayed as question signs. You can control the display method by
+customizing the variable @code{glyphless-char-display-control}.
+@xref{Glyphless Chars,, Glyphless Character Display, elisp, The Emacs
+Lisp Reference Manual}, for details.
@node Cursor Display
@section Displaying the Cursor
-
-@findex blink-cursor-mode
-@vindex blink-cursor-alist
-@cindex cursor, locating visually
-@cindex cursor, blinking
- You can customize the cursor's color, and whether it blinks, using
-the @code{cursor} Custom group (@pxref{Easy Customization}). On
-a graphical display, the command @kbd{M-x blink-cursor-mode} enables
-or disables the blinking of the cursor. (On text terminals, the
-terminal itself blinks the cursor, and Emacs has no control over it.)
-You can control how the cursor appears when it blinks off by setting
-the variable @code{blink-cursor-alist}.
-
-@vindex cursor-type
- You can change the shape of the cursor from the default ``box'' look
-to a bar by altering the @code{cursor-type} variable.
+@cindex text cursor
@vindex visible-cursor
- Some text terminals offer two different cursors: the normal cursor
-and the very visible cursor, where the latter may be e.g. bigger or
-blinking. By default Emacs uses the very visible cursor, and switches
-to it when you start or resume Emacs. If the variable
-@code{visible-cursor} is @code{nil} when Emacs starts or resumes, it
-doesn't switch, so it uses the normal cursor.
+ On a text terminal, the cursor's appearance is controlled by the
+terminal, largely out of the control of Emacs. Some terminals offer
+two different cursors: a ``visible'' static cursor, and a ``very
+visible'' blinking cursor. By default, Emacs uses the very visible
+cursor, and switches to it when you start or resume Emacs. If the
+variable @code{visible-cursor} is @code{nil} when Emacs starts or
+resumes, it uses the normal cursor.
+
+@cindex cursor face
+@vindex cursor-type
+ On a graphical display, many more properties of the text cursor can
+be altered. To customize its color, change the @code{:background}
+attribute of the face named @code{cursor} (@pxref{Face
+Customization}). (The other attributes of this face have no effect;
+the text shown under the cursor is drawn using the frame's background
+color.) To change its shape, customize the buffer-local variable
+@code{cursor-type}; possible values are @code{box} (the default),
+@code{hollow} (a hollow box), @code{bar} (a vertical bar), @code{(bar
+. @var{n})} (a vertical bar @var{n} pixels wide), @code{hbar} (a
+horizontal bar), @code{(hbar . @var{n})} (a horizontal bar @var{n}
+pixels tall), or @code{nil} (no cursor at all).
-@cindex cursor in non-selected windows
-@vindex cursor-in-non-selected-windows
- Normally, the cursor appears in non-selected windows without
-blinking, with the same appearance as when the blinking cursor blinks
-``off.'' For a box cursor, this is a hollow box; for a bar cursor,
-this is a thinner bar. To turn off cursors in non-selected windows,
-customize the variable @code{cursor-in-non-selected-windows} and
-assign it a @code{nil} value.
+@findex blink-cursor-mode
+@cindex cursor, blinking
+@cindex blinking cursor
+@vindex blink-cursor-alist
+ To disable cursor blinking, change the variable
+@code{blink-cursor-mode} to @code{nil} (@pxref{Easy Customization}),
+or add the line @code{(blink-cursor-mode 0)} to your init file.
+Alternatively, you can change how the cursor looks when it ``blinks
+off'' by customizing the list variable @code{blink-cursor-alist}.
+Each element in the list should have the form @code{(@var{on-type}
+. @var{off-type})}; this means that if the cursor is displayed as
+@var{on-type} when it blinks on (where @var{on-type} is one of the
+cursor types described above), then it is displayed as @var{off-type}
+when it blinks off.
@vindex x-stretch-cursor
@cindex wide block cursor
- On graphical displays, Emacs can optionally draw the block cursor
-as wide as the character under the cursor---for example, if the cursor
-is on a tab character, it would cover the full width occupied by that
-tab character. To enable this feature, set the variable
+ Some characters, such as tab characters, are ``extra wide''. When
+the cursor is positioned over such a character, it is normally drawn
+with the default character width. You can make the cursor stretch to
+cover wide characters, by changing the variable
@code{x-stretch-cursor} to a non-@code{nil} value.
+@cindex cursor in non-selected windows
+@vindex cursor-in-non-selected-windows
+ The cursor normally appears in non-selected windows as a
+non-blinking hollow box. (For a bar cursor, it instead appears as a
+thinner bar.) To turn off cursors in non-selected windows, change the
+variable @code{cursor-in-non-selected-windows} to @code{nil}.
+
@findex hl-line-mode
@findex global-hl-line-mode
@cindex highlight current line
global-hl-line-mode} enables or disables the same mode globally.
@node Line Truncation
-@section Truncation of Lines
+@section Line Truncation
@cindex truncation
@cindex line truncation, and fringes
- As an alternative to continuation (@pxref{Continuation Lines}), Emacs
-can display long lines by @dfn{truncation}. This means that all the
-characters that do not fit in the width of the screen or window do not
-appear at all. On graphical displays, a small straight arrow in the
-fringe indicates truncation at either end of the line. On text-only
-terminals, @samp{$} appears in the leftmost column when there is text
-truncated to the left, and in the rightmost column when there is text
-truncated to the right.
+ As an alternative to continuation (@pxref{Continuation Lines}),
+Emacs can display long lines by @dfn{truncation}. This means that all
+the characters that do not fit in the width of the screen or window do
+not appear at all. On graphical displays, a small straight arrow in
+the fringe indicates truncation at either end of the line. On text
+terminals, this is indicated with @samp{$} signs in the leftmost
+and/or rightmost columns.
@vindex truncate-lines
@findex toggle-truncate-lines
are truncated; if it is @code{nil}, they are continued onto multiple
screen lines. Setting the variable @code{truncate-lines} in any way
makes it local to the current buffer; until that time, the default
-value is in effect. The default value is normally @code{nil}.
+value, which is normally @code{nil}, is in effect.
-@c @vindex truncate-partial-width-windows @c Idx entry is in Split Windows.
- If the variable @code{truncate-partial-width-windows} is
-non-@code{nil}, it forces truncation rather than continuation in any
-window less than the full width of the screen or frame, regardless of
-the value of @code{truncate-lines}. See also @ref{Display,, Display,
-elisp, The Emacs Lisp Reference Manual}.
-
-@vindex overflow-newline-into-fringe
- If the variable @code{overflow-newline-into-fringe} is
-non-@code{nil} on a graphical display, then Emacs does not continue or
-truncate a line which is exactly as wide as the window. Instead, the
-newline overflows into the right fringe, and the cursor appears in the
-fringe when positioned on that newline.
+@vindex truncate-partial-width-windows
+ If a split window becomes too narrow, Emacs may automatically enable
+line truncation. @xref{Split Window}, for the variable
+@code{truncate-partial-width-windows} which controls this.
@node Visual Line Mode
@section Visual Line Mode
@node Display Custom
@section Customization of Display
- This section describes variables (@pxref{Variables}) that you can
-change to customize how Emacs displays. Beginning users can skip
-it.
-@c the reason for that pxref is because an xref early in the
-@c ``echo area'' section leads here.
+ This section describes variables that control miscellaneous aspects
+of the appearance of the Emacs screen. Beginning users can skip it.
@vindex visible-bell
If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts
The variable @code{echo-keystrokes} controls the echoing of multi-character
keys; its value is the number of seconds of pause required to cause echoing
to start, or zero, meaning don't echo at all. The value takes effect when
-there is someting to echo. @xref{Echo Area}.
-
-@vindex baud-rate
- The variable @anchor{baud-rate}@code{baud-rate} holds the output
-speed of the terminal. Setting this variable does not change the
-speed of actual data transmission, but the value is used for
-calculations. On text-only terminals, it affects padding, and
-decisions about whether to scroll part of the screen or redraw it
-instead. It also affects the behavior of incremental search. On
-graphical displays, @code{baud-rate} is only used to determine how
-frequently to look for pending input during display updating. A
-higher value of @code{baud-rate} means that check for pending input
-will be done less frequently.
+there is something to echo. @xref{Echo Area}.
@cindex mouse pointer
@cindex hourglass pointer display
itself, in pixels; the default is 2.
@findex tty-suppress-bold-inverse-default-colors
- On some text-only terminals, bold face and inverse video together
-result in text that is hard to read. Call the function
+ On some text terminals, bold face and inverse video together result
+in text that is hard to read. Call the function
@code{tty-suppress-bold-inverse-default-colors} with a non-@code{nil}
argument to suppress the effect of bold-face in this case.
-
-@vindex no-redraw-on-reenter
- On a text-only terminal, when you reenter Emacs after suspending, Emacs
-normally clears the screen and redraws the entire display. On some
-terminals with more than one page of memory, it is possible to arrange
-the termcap entry so that the @samp{ti} and @samp{te} strings (output
-to the terminal when Emacs is entered and exited, respectively) switch
-between pages of memory so as to use one page for Emacs and another
-page for other output. On such terminals, you might want to set the variable
-@code{no-redraw-on-reenter} non-@code{nil}; this tells Emacs to
-assume, when resumed, that the screen page it is using still contains
-what Emacs last wrote there.