* mail/feedmail.el (feedmail-buffer-to-smtpmail):

[bpt/emacs.git] / doc / emacs / display.texi

@c This is part of the Emacs manual.
@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011
@c   Free Software Foundation, Inc.

@c See file emacs.texi for copying conditions.
@node Display, Search, Registers, Top
@chapter Controlling the Display

  Since only part of a large buffer fits in the window, Emacs tries to
show a part that is likely to be interesting.  Display-control
commands and variables allow you to specify which part of the text you
want to see, and how to display it.

@menu
* Scrolling::              Commands to move text up and down in a window.
* Auto Scrolling::         Redisplay scrolls text automatically when needed.
* Horizontal Scrolling::   Moving text left and right in a window.
* Follow Mode::            Follow mode lets two windows scroll as one.
* Faces::                  How to change the display style using faces.
* Standard Faces::         Emacs' predefined faces.
* Temporary Face Changes:: Commands to temporarily modify the default text face
* 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.
* Selective Display::      Hiding lines with lots of indentation.
* Optional Mode Line::     Optional mode line display features.
* Text Display::           How text characters are normally displayed.
* Cursor Display::         Features for displaying the cursor.
* Line Truncation::        Truncating lines to fit the screen width instead
                             of continuing them to multiple screen lines.
* Visual Line Mode::       Word wrap and screen line-based editing.
* Display Custom::         Information on variables for customizing display.
@end menu

@node Scrolling
@section Scrolling

  If a buffer contains text that is too large to fit entirely within a
window that is displaying the buffer, Emacs shows a contiguous portion of
the text.  The portion shown always contains point.

@cindex scrolling
  @dfn{Scrolling} means moving text up or down in the window so that
different parts of the text are visible.  Scrolling ``forward'' or
``up'' means that text moves up, and new text appears at the bottom.
Scrolling ``backward'' or ``down'' moves text down, and new text
appears at the top.

  Scrolling happens automatically if you move point past the bottom or
top of the window.  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 forth in cyclic
order; also, maybe redisplay the screen (@code{recenter-top-bottom}).
@item C-v
@itemx @key{next}
@itemx @key{PageDown}
Scroll forward by nearly a full window (@code{scroll-up}).
@item M-v
@itemx @key{prior}
@itemx @key{PageUp}
Scroll backward (@code{scroll-down}).
@item C-M-l
Scroll heuristically to bring useful information onto the screen
(@code{reposition-window}).
@end table

@kindex C-l
@findex recenter-top-bottom
  @kbd{C-l} (@code{recenter-top-bottom}) is a basic scrolling command.
It @dfn{recenters} the selected window, scrolling it so that the
current screen line is exactly in the center of the window, or as
close to the center as possible.

  Typing @kbd{C-l} twice in a row (@kbd{C-l C-l}) scrolls the window
so that point is on the topmost screen line.  Typing a third @kbd{C-l}
scrolls the window so that point is on the bottom-most screen line.
Each successive @kbd{C-l} cycles through these three screen positions.

@vindex recenter-positions
  You can change the cycling order by customizing the list variable
@code{recenter-positions}.  Each list element should be the symbol
@code{top}, @code{middle}, or @code{bottom}, or a number; an integer
number means to move the line to the specified screen line, while a
floating-point number between 0.0 and 1.0 specifies a percentage of
the screen space from the top.  The default, @code{(middle top
bottom)}, is the cycling order described above.  Furthermore, if you
change the variable @code{scroll-margin} to a non-zero value @var{n},
Emacs always leaves @var{n} 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.  For example, @kbd{C-u - 1 C-l}
puts point on the bottom line, and @kbd{C-u - 5 C-l} puts it five
lines from the bottom.  When given an argument, @kbd{C-l} does not
clear the screen or cycle through different screen positions.

  The more primitive command @code{recenter} behaves like
@code{recenter-top-bottom}, but does not cycle among screen positions.
Prior to Emacs 23, @kbd{C-l} was bound to @code{recenter}.

@vindex recenter-redisplay
  If the variable @code{recenter-redisplay} has a non-@code{nil}
value, Emacs clears and redisplays the screen each time @kbd{C-l}
recenters the window; the special value @code{tty} (the default) says
to do this on text-terminal frames only.  Redisplaying is useful in
case the screen becomes garbled for any reason (@pxref{Screen
Garbled}).

@kindex C-v
@kindex M-v
@kindex next
@kindex prior
@kindex PageDown
@kindex PageUp
@findex scroll-up
@findex scroll-down
  To read the buffer a windowful at a time, type @kbd{C-v}
(@code{scroll-up}).  This 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 at the new top of the window.

  @kbd{M-v} (@code{scroll-down}) scrolls backward in a similar way.

@vindex next-screen-context-lines
  The variable @code{next-screen-context-lines} controls the number of
lines of overlap left by @kbd{C-v} or @kbd{M-v}; by default, it is 2.
The function keys @key{next} and @key{prior}, or @key{PageDown} and
@key{PageUp}, are equivalent to @kbd{C-v} and @kbd{M-v} respectively.

  You can supply @kbd{C-v} or @kbd{M-v} 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.

  The names of scroll commands are based on the direction that the
text moves in the window.  Thus, the command to scroll forward is
called @code{scroll-up} because it moves the text upward on the
screen.  The keys @key{PageUp} and @key{PageDown} derive their names
and customary meanings from a different convention that developed
elsewhere; hence the strange result that @key{PageDown} runs
@code{scroll-up}.

@vindex scroll-preserve-screen-position
  Some users like the full-screen scroll commands to keep point at the
same screen position.  To enable this behavior, set the variable
@code{scroll-preserve-screen-position} to a non-@code{nil} value.
Then, whenever a command scrolls the text around point offscreen (or
within @code{scroll-margin} lines of the edge), Emacs moves point to
keep it at the same vertical and horizontal position within the
window.  This mode is convenient for browsing through a file by
scrolling by screenfuls; if you come back to the screen where you
started, point goes back to the line where it started.

@kindex C-M-l
@findex reposition-window
  The @kbd{C-M-l} command (@code{reposition-window}) scrolls the current
window heuristically in a way designed to get useful information onto
the screen.  For example, in a Lisp file, this command tries to get the
entire current defun onto the screen if possible.

@node Auto Scrolling
@section Automatic Scrolling

  Emacs performs @dfn{automatic scrolling} when point moves out of the
visible portion of the text.

@vindex scroll-conservatively
  Normally, this centers point vertically within the window.  However,
if you set @code{scroll-conservatively} to a small number @var{n},
then if you move point just a little off the screen (less than @var{n}
lines), Emacs scrolls the text just far enough to bring point back on
screen.  By default, @code{scroll-conservatively} is@tie{}0.  If you
set @code{scroll-conservatively} to a large number (larger than 100),
Emacs will never center point as result of scrolling, even if point
moves far away from the text previously displayed in the window.  With
such a large value, Emacs will always scroll text just enough for
bringing point into view, so point will end up at the top or bottom of
the window, depending on the scroll direction.

@vindex scroll-step
  The variable @code{scroll-step} determines how many lines to scroll
the window when point moves off the screen.  If moving by that number
of lines fails to bring point back into view, point is centered
instead.  The default value is zero, which causes point to always be
centered after scrolling.

@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.@: when point moves forward in the buffer, and therefore text
scrolls up in the window.  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.

  Likewise, @code{scroll-down-aggressively} is used for scrolling
down, i.e.@: moving point back in the buffer.  The value specifies how
far point should be placed from the top 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
@code{scroll-conservatively} are set to a non-zero value.

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

@node Horizontal Scrolling
@section Horizontal Scrolling
@cindex horizontal scrolling

@vindex auto-hscroll-mode
  @dfn{Horizontal scrolling} means shifting all the lines sideways
within a window, so that some of the text near the left margin is not
displayed.  When the text in a window is scrolled horizontally, text
lines are truncated rather than continued (@pxref{Line Truncation}).
If a window shows truncated lines, Emacs performs automatic horizontal
scrolling whenever point moves off the left or right edge of the
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-mode
terminals, the cursor is left at the edge instead.)

@vindex hscroll-margin
  The variable @code{hscroll-margin} controls how close point can get
to the window's edges before automatic scrolling occurs.  It is
measured in columns.  For example, if the value is 5, then moving
point within 5 columns of an edge causes horizontal scrolling away
from that edge.

@vindex hscroll-step
  The variable @code{hscroll-step} determines how many columns to
scroll the window when point gets too close to the edge.  Zero, the
default value, means to center point horizontally within the window.
A positive integer value specifies the number of columns to scroll by.
A floating-point number specifies the fraction of the window's width
to scroll by.

  You can also perform explicit horizontal scrolling with the
following commands:

@table @kbd
@item C-x <
Scroll text in current window to the left (@code{scroll-left}).
@item C-x >
Scroll to the right (@code{scroll-right}).
@end table

@kindex C-x <
@kindex C-x >
@findex scroll-left
@findex scroll-right
  @kbd{C-x <} (@code{scroll-left}) scrolls text in the selected window
to the left by the full width of the window, less two columns.  (In
other words, the text in the window moves left relative to the
window.)  With a numeric argument @var{n}, it scrolls by @var{n}
columns.

  If the text is scrolled to the left, and point moves off the left
edge of the window, the cursor will freeze at the left edge of the
window, until point moves back to the displayed portion of the text.
This is independent of the current setting of
@code{auto-hscroll-mode}, which, for text scrolled to the left, only
affects the behavior at the right edge of the window.

  @kbd{C-x >} (@code{scroll-right}) scrolls similarly to the right.
The window cannot be scrolled any farther to the right once it is
displayed normally, with each line starting at the window's left
margin; attempting to do so has no effect.  This means that you don't
have to calculate the argument precisely for @w{@kbd{C-x >}}; any
sufficiently large argument will restore the normal display.

  If you use those commands to scroll a window horizontally, that sets
a lower bound for automatic horizontal scrolling.  Automatic scrolling
will continue to scroll the window, but never farther to the right
than the amount you previously set by @code{scroll-left}.

@node Follow Mode
@section Follow Mode
@cindex Follow mode
@cindex mode, Follow
@findex follow-mode
@cindex windows, synchronizing
@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.''
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
two windows, or scroll either one; the other window follows it.

  In Follow mode, if you move point outside the portion visible in one
window and into the portion visible in the other window, that selects
the other window---again, treating the two as if they were parts of
one large window.

  To turn off Follow mode, type @kbd{M-x follow-mode} a second time.

@node Faces
@section Faces: Controlling Text Display Style
@cindex faces

  Emacs can display text in several different styles, which are called
@dfn{faces}.  Each face can specify various @dfn{face attributes},
such as the font, height, weight and slant, the foreground and
background color, and underlining or overlining.  A face does not have
to specify all of these attributes; often it inherits most of them
from another face.

  On a text-only terminal, not all face attributes are meaningful.
Some text-only terminals support inverse video, bold, and underline
attributes; some support colors.  Text-only terminals generally do not
support changing the height, width or font.

  Most major modes assign faces to the text automatically through the
work of Font Lock mode.  @xref{Font Lock}, for more information about
Font Lock mode and syntactic highlighting.  You can print the current
buffer with the highlighting that appears on your screen using the
command @code{ps-print-buffer-with-faces}.  @xref{PostScript}.

  Enriched mode, the mode for editing formatted text, provides
commands and menus for specifying faces for text in the buffer.
@xref{Format Faces}.

@cindex face colors, setting
  To alter the appearance of a face, use the customization buffer.
@xref{Face Customization}.  You can also use X resources to specify
attributes of any particular face (@pxref{Resources}).  When
displaying a character, any attribute that isn't specified by its face
is taken from the @code{default} face, whose attributes reflect the
default settings of the frame itself.

@findex set-face-foreground
@findex set-face-background
  You can also change the foreground and background colors of a
specific 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.  @xref{Face Customization}, for information
about color names.  These commands affect the face colors on all
frames, both existing and those to be created in the future.  These
changes do not, however, persist for future Emacs sessions; to make
lasting changes, use the customization buffer (@pxref{Face
Customization}).

  You can also set foreground and background colors for the current
frame only; see @ref{Frame Parameters}.

  Emacs can display variable-width fonts, but some of the Emacs
commands that calculate width and indentation do not know how to
calculate variable widths.  This can sometimes lead to incorrect
results when you use variable-width fonts.  In particular, indentation
commands can give inconsistent results, so we recommend you avoid
variable-width fonts, especially for editing program source code.

@node Standard Faces
@section Standard Faces

@findex list-faces-display
  To see what faces are currently defined, and what they look like,
type @kbd{M-x list-faces-display}.  It's possible for a given face to
look different in different frames; this command shows the appearance
in the frame in which you type it.  With a prefix argument, this
prompts for a regular expression, and displays only faces with names
matching that regular expression.

  Here are the standard faces for specifying text appearance.  You can
apply them to specific text when you want the effects they produce.

@table @code
@item default
This face is used for ordinary text that doesn't specify any face.
@item bold
This face uses a bold variant of the default font.
@item italic
This face uses an italic variant of the default font.
@item bold-italic
This face uses a bold italic variant of the default font.
@item underline
This face underlines text.
@item fixed-pitch
This face forces use of a fixed-width font.  It's reasonable to
customize this face to use a different fixed-width font, if you like,
but you should not make it a variable-width font.
@item variable-pitch
This face forces use of a variable-width font.
@item shadow
This face is used for making the text less noticeable than the surrounding
ordinary text.  Usually this can be achieved by using shades of gray in
contrast with either black or white default foreground color.
@end table

  Here's an incomplete list of faces used to highlight parts of the
text temporarily for specific purposes.  (Many other modes define
their own faces for this purpose.)

@table @code
@item highlight
This face is used for highlighting portions of text, in various modes.
For example, mouse-sensitive text is highlighted using this face.
@item isearch
This face is used for highlighting the current Isearch match
(@pxref{Incremental Search}).
@item query-replace
This face is used for highlighting the current Query Replace match
(@pxref{Replace}).
@item lazy-highlight
This face is used for lazy highlighting of Isearch and Query Replace
matches other than the current one.
@item region
This face is used for displaying a selected region (@pxref{Mark}).
@item secondary-selection
This face is used for displaying a secondary X selection (@pxref{Secondary
Selection}).
@item trailing-whitespace
The face for highlighting excess spaces and tabs at the end of a line
when @code{show-trailing-whitespace} is non-@code{nil}; see
@ref{Useless Whitespace}.
@item nobreak-space
The face for displaying the character ``nobreak space.''
@item escape-glyph
The face for highlighting the @samp{\} or @samp{^} that indicates
a control character.  It's also used when @samp{\} indicates a
nobreak space or nobreak (soft) hyphen.
@end table

  These faces control the appearance of parts of the Emacs frame.
They exist as faces to provide a consistent way to customize the
appearance of these parts of the frame.

@table @code
@item mode-line
This face is used for the mode line of the currently selected window,
and for menu bars when toolkit menus are not used.  By default, it's
drawn with shadows for a ``raised'' effect on graphical displays, and
drawn as the inverse of the default face on non-windowed terminals.
@item mode-line-inactive
Like @code{mode-line}, but used for mode lines of the windows other
than the selected one (if @code{mode-line-in-non-selected-windows} is
non-@code{nil}).  This face inherits from @code{mode-line}, so changes
in that face affect mode lines in all windows.
@item mode-line-highlight
Like @code{highlight}, but used for portions of text on mode lines.
@item mode-line-buffer-id
This face is used for buffer identification parts in the mode line.
@item header-line
Similar to @code{mode-line} for a window's header line, which appears
at the top of a window just as the mode line appears at the bottom.
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.
By default this face inherits from the @code{mode-line-inactive} face
on character terminals.  On graphical displays the foreground color of
this face is used for the vertical line between windows without
scrollbars.
@item minibuffer-prompt
@cindex @code{minibuffer-prompt} face
@vindex minibuffer-prompt-properties
This face is used for the prompt strings displayed in the minibuffer.
By default, Emacs automatically adds this face to the value of
@code{minibuffer-prompt-properties}, which is a list of text
properties used to display the prompt text.  (This variable takes
effect when you enter the minibuffer.)
@item fringe
@cindex @code{fringe} face
The face for the fringes to the left and right of windows on graphic
displays.  (The fringes are the narrow portions of the Emacs frame
between the text area and the window's right and left borders.)
@xref{Fringes}.
@item scroll-bar
This face determines the visual appearance of the scroll bar.
@xref{Scroll Bars}.
@item border
This face determines the color of the frame border.
@item cursor
This face determines the color of the cursor.
@item mouse
This face determines the color of the mouse pointer.
@item tool-bar
This face determines the color of tool bar icons.  @xref{Tool Bars}.
@item tooltip
This face is used for tooltips.  @xref{Tooltips}.
@item menu
@cindex menu bar appearance
@cindex @code{menu} face, no effect if customized
@cindex customization of @code{menu} face
This face determines the colors and font of Emacs's menus.  @xref{Menu
Bars}.  This has no effect in Emacs built with GTK and in the
MS-Windows/Mac ports; you need to use system-wide styles and options
to change the appearance of GTK, Windows, or Mac menus.  Setting the
font of LessTif/Motif menus is currently not supported; attempts to
set the font are ignored in this case.
@end table

@node Temporary Face Changes
@section Temporary Face Changes

The following commands change the default face within a buffer.

@cindex adjust buffer face height
@findex text-scale-adjust
@kindex C-x C-+
@kindex C-x C--
@kindex C-x C-=
@kindex C-x C-0
  To increase the height of the default face in the current buffer,
type @kbd{C-x C-+} or @kbd{C-x C-=}.  To decrease it, type @kbd{C-x
C--}.  To restore the default (global) face height, type @kbd{C-x
C-0}.  These keys are all bound to the same command,
@code{text-scale-adjust}, which looks at the last key typed to
determine which action to take.

  The final key of these commands may be repeated without the leading
@kbd{C-x}.  For instance, @kbd{C-x C-= C-= C-=} increases the face
height by three steps.  Each step scales the height of the default
face by the value of the variable @code{text-scale-mode-step}.  As a
special case, an argument of 0 removes any scaling currently active.

@cindex increase buffer face height
@findex text-scale-increase
@cindex decrease buffer face height
@findex text-scale-decrease
  The commands @code{text-scale-increase} and
@code{text-scale-decrease} increase or decrease the height of the
default face, just like @kbd{C-x C-+} and @kbd{C-x C--} respectively.
You may find it convenient to bind to these commands, rather than
@code{text-scale-adjust}.

@cindex set buffer face height
@findex text-scale-set
The command @code{text-scale-set} sets the height of the default face
in the current buffer to an absolute level specified by its prefix
argument.

@findex text-scale-mode
  The above commands automatically enable or disable the minor mode
@code{text-scale-mode}, depending on whether the current font scaling
is other than 1 or not.

@cindex variable pitch mode
@findex variable-pitch-mode
  To temporarily change the face in the current buffer to a
variable-pitch (``proportional'') font, use the command @kbd{M-x
variable-pitch-mode} to enable or disable the Variable Pitch minor
mode.

@node Font Lock
@section Font Lock mode
@cindex Font Lock mode
@cindex mode, Font Lock
@cindex syntax highlighting and coloring

  Font Lock mode is a minor mode, always local to a particular buffer,
which highlights (or ``fontifies'') the buffer contents according to
the syntax of the text you are editing.  It can recognize comments and
strings in most programming languages; in several languages, it can
also recognize and properly highlight various other important
constructs, such as names of functions being defined or reserved
keywords.  Some special modes, such as Occur mode and Info mode, have
completely specialized ways of assigning fonts for Font Lock mode.

@findex font-lock-mode
  Font Lock mode is turned on by default in all modes which support it.
You can toggle font-lock for each buffer with the command @kbd{M-x
font-lock-mode}.  Using a positive argument unconditionally turns Font
Lock mode on, and a negative or zero argument turns it off.

@findex global-font-lock-mode
@vindex global-font-lock-mode
  If you do not wish Font Lock mode to be turned on by default,
customize the variable @code{global-font-lock-mode} using the Customize
interface (@pxref{Easy Customization}), or use the function
@code{global-font-lock-mode} in your @file{.emacs} file, like this:

@example
(global-font-lock-mode 0)
@end example

@noindent
This variable, like all the variables that control Font Lock mode,
take effect whenever fontification is done; that is, potentially at
any time.

@findex turn-on-font-lock
  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:

@example
(add-hook 'c-mode-hook 'turn-on-font-lock)
@end example

  Font Lock mode uses several specifically named faces to do its job,
including @code{font-lock-string-face}, @code{font-lock-comment-face},
and others.  The easiest way to find them all is to use @kbd{M-x
customize-group @key{RET} font-lock-faces @key{RET}}.  You can then
use that customization buffer to customize the appearance of these
faces.  @xref{Face Customization}.

@vindex font-lock-maximum-decoration
  The variable @code{font-lock-maximum-decoration} specifies the
preferred level of fontification, for modes that provide multiple
levels.  Level 1 is the least amount of fontification; some modes
support levels as high as 3.  The normal default is ``as high as
possible.''  You can specify an integer, which applies to all modes, or
you can specify different numbers for particular major modes; for
example, to use level 1 for C/C++ modes, and the default level
otherwise, use this:

@example
(setq font-lock-maximum-decoration
      '((c-mode . 1) (c++-mode . 1)))
@end example

@vindex font-lock-maximum-size
  Fontification can be too slow for large buffers, so you can suppress
it for buffers above a certain size.  The variable
@code{font-lock-maximum-size} specifies a buffer size, beyond which
buffer fontification is suppressed.

@c @w is used below to prevent a bad page-break.
@vindex font-lock-beginning-of-syntax-function
@cindex incorrect fontification
@cindex parenthesis in column zero and fontification
@cindex brace in column zero and fontification
  Comment and string fontification (or ``syntactic'' fontification)
relies on analysis of the syntactic structure of the buffer text.  For
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 @w{beginning} of a defun, and is thus always
outside any string or comment.  (@xref{Left Margin Paren}.)  If you
don't follow this convention, Font Lock mode can misfontify the text
that follows an open-parenthesis or open-brace in the leftmost column
that is inside a string or comment.

@cindex slow display during scrolling
  The variable @code{font-lock-beginning-of-syntax-function}, which is
always buffer-local, specifies how Font Lock mode can find a position
guaranteed to be outside any comment or string.  In modes which use
the leftmost column parenthesis convention, the default value of the
variable is @code{beginning-of-defun}---that tells Font Lock mode to
use the convention.  If you set this variable to @code{nil}, Font Lock
no longer relies on the convention.  This avoids incorrect results,
but the price is that, in some cases, fontification for a changed text
must rescan buffer text from the beginning of the buffer.  This can
considerably slow down redisplay while scrolling, particularly if you
are close to the end of a large buffer.

@findex font-lock-add-keywords
  Font Lock highlighting patterns already exist for many modes, but you
may want to fontify additional patterns.  You can use the function
@code{font-lock-add-keywords}, to add your own highlighting patterns for
a particular mode.  For example, to highlight @samp{FIXME:} words in C
comments, use this:

@example
(add-hook 'c-mode-hook
          (lambda ()
           (font-lock-add-keywords nil
            '(("\\<\\(FIXME\\):" 1
               font-lock-warning-face t)))))
@end example

@findex font-lock-remove-keywords
  To remove keywords from the font-lock highlighting patterns, use the
function @code{font-lock-remove-keywords}.  @xref{Search-based
Fontification,,, elisp, The Emacs Lisp Reference Manual}.

@cindex just-in-time (JIT) font-lock
@cindex background syntax highlighting
  Fontifying large buffers can take a long time.  To avoid large
delays when a file is visited, Emacs fontifies only the visible
portion of a buffer.  As you scroll through the buffer, each portion
that becomes visible is fontified as soon as it is displayed; this
type of Font Lock is called @dfn{Just-In-Time} (or @dfn{JIT}) Lock.
You can control how JIT Lock behaves, including telling it to perform
fontification while idle, by customizing variables in the
customization group @samp{jit-lock}.  @xref{Specific Customization}.

@node Highlight Interactively
@section Interactive Highlighting
@cindex highlighting by matching
@cindex interactive highlighting
@cindex Highlight Changes mode

@findex highlight-changes-mode
Highlight Changes mode is a minor mode that @dfn{highlights} the parts
of the buffer were changed most recently, by giving that text a
different face.  To enable or disable Highlight Changes mode, use
@kbd{M-x highlight-changes-mode}.

@cindex Hi Lock mode
@findex hi-lock-mode
  Hi Lock mode is a minor mode that highlights text that matches
regular expressions you specify.  For example, you can use it to
highlight all the references to a certain variable in a program source
file, highlight certain parts in a voluminous output of some program,
or highlight certain names in an article.  To enable or disable Hi
Lock mode, use the command @kbd{M-x hi-lock-mode}.  To enable Hi Lock
mode for all buffers, use @kbd{M-x global-hi-lock-mode} or place
@code{(global-hi-lock-mode 1)} in your @file{.emacs} file.

  Hi Lock mode works like Font Lock mode (@pxref{Font Lock}), except
that you specify explicitly the regular expressions to highlight.  You
control them with these commands:

@table @kbd
@item C-x w h @var{regexp} @key{RET} @var{face} @key{RET}
@kindex C-x w h
@findex highlight-regexp
Highlight text that matches @var{regexp} using face @var{face}
(@code{highlight-regexp}).  The highlighting will remain as long as
the buffer is loaded.  For example, to highlight all occurrences of
the word ``whim'' using the default face (a yellow background)
@kbd{C-x w h whim @key{RET} @key{RET}}.  Any face can be used for
highlighting, Hi Lock provides several of its own and these are
pre-loaded into a list of default values.  While being prompted
for a face use @kbd{M-n} and @kbd{M-p} to cycle through them.

You can use this command multiple times, specifying various regular
expressions to highlight in different ways.

@item C-x w r @var{regexp} @key{RET}
@kindex C-x w r
@findex unhighlight-regexp
Unhighlight @var{regexp} (@code{unhighlight-regexp}).

If you invoke this from the menu, you select the expression to
unhighlight from a list.  If you invoke this from the keyboard, you
use the minibuffer.  It will show the most recently added regular
expression; use @kbd{M-p} to show the next older expression and
@kbd{M-n} to select the next newer expression.  (You can also type the
expression by hand, with completion.)  When the expression you want to
unhighlight appears in the minibuffer, press @kbd{@key{RET}} to exit
the minibuffer and unhighlight it.

@item C-x w l @var{regexp} @key{RET} @var{face} @key{RET}
@kindex C-x w l
@findex highlight-lines-matching-regexp
@cindex lines, highlighting
@cindex highlighting lines of text
Highlight entire lines containing a match for @var{regexp}, using face
@var{face} (@code{highlight-lines-matching-regexp}).

@item C-x w b
@kindex C-x w b
@findex hi-lock-write-interactive-patterns
Insert all the current highlighting regexp/face pairs into the buffer
at point, with comment delimiters to prevent them from changing your
program.  (This key binding runs the
@code{hi-lock-write-interactive-patterns} command.)

These patterns are extracted from the comments, if appropriate, if you
invoke @kbd{M-x hi-lock-find-patterns}, or if you visit the file while
Hi Lock mode is enabled (since that runs @code{hi-lock-find-patterns}).

@item C-x w i
@kindex C-x w i
@findex hi-lock-find-patterns
Extract regexp/face pairs from comments in the current buffer
(@code{hi-lock-find-patterns}).  Thus, you can enter patterns
interactively with @code{highlight-regexp}, store them into the file
with @code{hi-lock-write-interactive-patterns}, edit them (perhaps
including different faces for different parenthesized parts of the
match), and finally use this command (@code{hi-lock-find-patterns}) to
have Hi Lock highlight the edited patterns.

@vindex hi-lock-file-patterns-policy
The variable @code{hi-lock-file-patterns-policy} controls whether Hi
Lock mode should automatically extract and highlight patterns found in a
file when it is visited.  Its value can be @code{nil} (never highlight),
@code{ask} (query the user), or a function.  If it is a function,
@code{hi-lock-find-patterns} calls it with the patterns as argument; if
the function returns non-@code{nil}, the patterns are used.  The default
is @code{ask}.  Note that patterns are always highlighted if you call
@code{hi-lock-find-patterns} directly, regardless of the value of this
variable.

@vindex hi-lock-exclude-modes
Also, @code{hi-lock-find-patterns} does nothing if the current major
mode's symbol is a member of the list @code{hi-lock-exclude-modes}.
@end table

@node Fringes
@section Window Fringes
@cindex fringes

  On a graphical display, 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.

  The most common use of the fringes is to indicate a continuation
line, when one line of text is split into multiple lines on the
screen.  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 screen line except the
last, indicating that ``this is not the real end.''  If the line's
direction is right-to-left (@pxref{Bidirectional Editing}), the
meaning of the curving arrows in the left and right 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
scrolls the display horizontally in the direction of the arrow.   The
fringes can also indicate other things, such as empty lines, or 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}.

@node Displaying Boundaries
@section Displaying Boundaries

@vindex indicate-buffer-boundaries
  On a graphical display, Emacs can indicate the buffer boundaries in
the fringes.  It indicates the first line and the last line with
angle images in the fringes.  This can be combined with up and down
arrow images which say whether it is possible to scroll the window up
and down.

  The buffer-local variable @code{indicate-buffer-boundaries} controls
how the buffer boundaries and window scrolling is indicated in the
fringes.  If the value is @code{left} or @code{right}, both angle and
arrow bitmaps are displayed in the left or right fringe, respectively.

  If value is an alist, each element @code{(@var{indicator} .
@var{position})} specifies the position of one of the indicators.
The @var{indicator} must be one of @code{top}, @code{bottom},
@code{up}, @code{down}, or @code{t} which specifies the default
position for the indicators not present in the alist.
The @var{position} is one of @code{left}, @code{right}, or @code{nil}
which specifies not to show this indicator.

  For example, @code{((top . left) (t . right))} places the top angle
bitmap in left fringe, the bottom angle bitmap in right fringe, and
both arrow bitmaps in right fringe.  To show just the angle bitmaps in
the left fringe, but no arrow bitmaps, use @code{((top .  left)
(bottom . left))}.

@node Useless Whitespace
@section Useless Whitespace

@cindex trailing whitespace
@cindex whitespace, trailing
@vindex show-trailing-whitespace
  It is easy to leave unnecessary spaces at the end of a line, or
empty lines at the end of a file, without realizing it.  In most
cases, this @dfn{trailing whitespace} has no effect, but there are
special circumstances where it matters, and it can be a nuisance.

  You can make trailing whitespace at the end of a line visible by
setting the buffer-local variable @code{show-trailing-whitespace} to
@code{t}.  Then Emacs displays trailing whitespace, using the face
@code{trailing-whitespace}.

  This feature does not apply when point is at the end of the line
containing the whitespace.  Strictly speaking, that is ``trailing
whitespace'' nonetheless, but displaying it specially in that case
looks ugly while you are typing in new text.  In this special case,
the location of point is enough to show you that the spaces are
present.

@findex delete-trailing-whitespace
  Type @kbd{M-x delete-trailing-whitespace @key{RET}} to delete all
trailing whitespace within the buffer's accessible portion
(@pxref{Narrowing}).  This command does not remove newline characters.

@vindex indicate-empty-lines
@cindex unused lines
@cindex fringes, and unused line indication
  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)};.  (This feature currently doesn't work on
text-only terminals.)

@node Selective Display
@section Selective Display
@cindex selective display
@findex set-selective-display
@kindex C-x $

  Emacs has the ability to hide lines indented more than a given
number of columns.  You can use this to get an overview of a part of a
program.

  To hide lines in the current buffer, type @kbd{C-x $}
(@code{set-selective-display}) with a numeric argument @var{n}.  Then
lines with at least @var{n} columns of indentation disappear from the
screen.  The only indication of their presence is that three dots
(@samp{@dots{}}) appear at the end of each visible line that is
followed by one or more hidden ones.

  The commands @kbd{C-n} and @kbd{C-p} move across the hidden lines as
if they were not there.

  The hidden lines are still present in the buffer, and most editing
commands see them as usual, so you may find point in the middle of the
hidden text.  When this happens, the cursor appears at the end of the
previous line, after the three dots.  If point is at the end of the
visible line, before the newline that ends it, the cursor appears before
the three dots.

  To make all lines visible again, type @kbd{C-x $} with no argument.

@vindex selective-display-ellipses
  If you set the variable @code{selective-display-ellipses} to
@code{nil}, the three dots do not appear at the end of a line that
precedes hidden lines.  Then there is no visible indication of the
hidden lines.  This variable becomes local automatically when set.

  See also @ref{Outline Mode} for another way to hide part of
the text in a buffer.

@node Optional Mode Line
@section Optional Mode Line Features

@cindex buffer size display
@cindex display of buffer size
@findex size-indication-mode
  The buffer percentage @var{pos} indicates the percentage of the
buffer above the top of the window.  You can additionally display the
size of the buffer by typing @kbd{M-x size-indication-mode} to turn on
Size Indication mode.  The size will be displayed immediately
following the buffer percentage like this:

@example
@var{POS} of @var{SIZE}
@end example

@noindent
Here @var{SIZE} is the human readable representation of the number of
characters in the buffer, which means that @samp{k} for 10^3, @samp{M}
for 10^6, @samp{G} for 10^9, etc., are used to abbreviate.

@cindex line number display
@cindex display of line number
@findex line-number-mode
  The current line number of point appears in the mode line when Line
Number mode is enabled.  Use the command @kbd{M-x line-number-mode} to
turn this mode on and off; normally it is on.  The line number appears
after the buffer percentage @var{pos}, with the letter @samp{L} to
indicate what it is.

@cindex Column Number mode
@cindex mode, Column Number
@findex column-number-mode
  Similarly, you can display the current column number by turning on
Column number mode with @kbd{M-x column-number-mode}.  The column
number is indicated by the letter @samp{C}.  However, when both of
these modes are enabled, the line and column numbers are displayed in
parentheses, the line number first, rather than with @samp{L} and
@samp{C}.  For example: @samp{(561,2)}.  @xref{Minor Modes}, for more
information about minor modes and about how to use these commands.

@cindex narrowing, and line number display
  If you have narrowed the buffer (@pxref{Narrowing}), the displayed
line number is relative to the accessible portion of the buffer.
Thus, it isn't suitable as an argument to @code{goto-line}.  (Use
@code{what-line} command to see the line number relative to the whole
file.)

@vindex line-number-display-limit
  If the buffer is very large (larger than the value of
@code{line-number-display-limit}), Emacs won't compute the line
number, because that would be too slow; therefore, the line number
won't appear on the mode-line.  To remove this limit, set
@code{line-number-display-limit} to @code{nil}.

@vindex line-number-display-limit-width
  Line-number computation can also be slow if the lines in the buffer
are too long.  For this reason, Emacs doesn't display line numbers if
the average width, in characters, of lines near point is larger than
the value of @code{line-number-display-limit-width}.  The default
value is 200 characters.

@findex display-time
@cindex time (on mode line)
  Emacs can optionally display the time and system load in all mode
lines.  To enable this feature, type @kbd{M-x display-time} or customize
the option @code{display-time-mode}.  The information added to the mode
line looks like this:

@example
@var{hh}:@var{mm}pm @var{l.ll}
@end example

@noindent
@vindex display-time-24hr-format
Here @var{hh} and @var{mm} are the hour and minute, followed always by
@samp{am} or @samp{pm}.  @var{l.ll} is the average number, collected
for the last few minutes, of processes in the whole system that were
either running or ready to run (i.e.@: were waiting for an available
processor).  (Some fields may be missing if your operating system
cannot support them.)  If you prefer time display in 24-hour format,
set the variable @code{display-time-24hr-format} to @code{t}.

@cindex mail (on mode line)
@vindex display-time-use-mail-icon
@vindex display-time-mail-face
@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'').

@cindex mail (on mode line)
@findex display-battery-mode
@vindex display-battery-mode
@vindex battery-mode-line-format
  When running Emacs on a laptop computer, you can display the battery
charge on the mode-line, by using the command
@code{display-battery-mode} or customizing the variable
@code{display-battery-mode}.  The variable
@code{battery-mode-line-format} determines the way the battery charge
is displayed; the exact mode-line message depends on the operating
system, and it usually shows the current battery charge as a
percentage of the total charge.

@cindex mode line, 3D appearance
@cindex attributes of mode line, changing
@cindex non-integral number of lines in a window
  By default, the mode line is drawn on graphics displays with
3D-style highlighting, like that of a button when it is not being
pressed.  If you don't like this effect, you can disable the 3D
highlighting of the mode line, by customizing the attributes of the
@code{mode-line} face.  @xref{Face Customization}.

@cindex non-selected windows, mode line appearance
  By default, the mode line of nonselected windows is displayed in a
different face, called @code{mode-line-inactive}.  Only the selected
window is displayed in the @code{mode-line} face.  This helps show
which window is selected.  When the minibuffer is selected, since
it has no mode line, the window from which you activated the minibuffer
has its mode line displayed using @code{mode-line}; as a result,
ordinary entry to the minibuffer does not change any mode lines.

@vindex mode-line-in-non-selected-windows
  You can disable use of @code{mode-line-inactive} by setting variable
@code{mode-line-in-non-selected-windows} to @code{nil}; then all mode
lines are displayed in the @code{mode-line} face.

@vindex eol-mnemonic-unix
@vindex eol-mnemonic-dos
@vindex eol-mnemonic-mac
@vindex eol-mnemonic-undecided
  You can customize the mode line display for each of the end-of-line
formats by setting each of the variables @code{eol-mnemonic-unix},
@code{eol-mnemonic-dos}, @code{eol-mnemonic-mac}, and
@code{eol-mnemonic-undecided} to the strings you prefer.

@node Text Display
@section How Text Is Displayed
@cindex characters (in text)

  @acronym{ASCII} printing characters (octal codes 040 through 0176) in Emacs
buffers are displayed with their graphics, as are non-@acronym{ASCII} multibyte
printing characters (octal codes above 0400).

@vindex tab-width
  Some @acronym{ASCII} control characters are displayed in special
ways.  The newline character (octal code 012) is displayed by starting
a new line.  The tab character (octal code 011) is displayed by moving
to the next tab stop column (normally every 8 columns).  The number of
spaces per tab is controlled by the variable @code{tab-width}, which
must have an integer value between 1 and 1000, inclusive, and is made
buffer-local by changing it.  Note that how the tab character in the buffer
is displayed has nothing to do with the definition of @key{TAB} as a
command.

  Other @acronym{ASCII} control characters are normally displayed as a caret
(@samp{^}) followed by the non-control version of the character; thus,
control-A is displayed as @samp{^A}.  The caret appears in face
@code{escape-glyph}.

  Non-@acronym{ASCII} characters 0200 through 0237 (octal) are
displayed with octal escape sequences; thus, character code 0230
(octal) is displayed as @samp{\230}.  The backslash appears in face
@code{escape-glyph}.

@vindex ctl-arrow
  If the variable @code{ctl-arrow} is @code{nil}, control characters in
the buffer are displayed with octal escape sequences, except for newline
and tab.  Altering the value of @code{ctl-arrow} makes it local to the
current buffer; until that time, the default value is in effect.  The
default is initially @code{t}.

  The display of character codes 0240 through 0377 (octal) may be
either as escape sequences or as graphics.  They do not normally occur
in multibyte buffers, but if they do, they are displayed as Latin-1
graphics.  In unibyte mode, if you enable European display they are
displayed using their graphics (assuming your terminal supports them),
otherwise as escape sequences.  @xref{Unibyte Mode}.

@vindex nobreak-char-display
@cindex no-break space, display
@cindex no-break hyphen, display
@cindex soft hyphen, display
  Some character sets define ``no-break'' 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.

  You can customize the way any particular character code is displayed
by means of a display table.  @xref{Display Tables,, Display Tables,
elisp, The Emacs Lisp Reference Manual}.

@cindex glyphless characters
@cindex characters with no font glyphs
  On graphics displays, some characters could have no glyphs in any of
the fonts available to Emacs.  On text terminals, some characters
could be impossible to encode with the terminal coding system
(@pxref{Terminal Coding}).  Emacs can display such @dfn{glyphless}
characters using one of the following methods:

@table @code
@item zero-width
Don't display the character.

@item thin-space
Display a thin space, 1-pixel wide on graphics displays or 1-character
wide on text terminals.

@item empty-box
Display an empty box.

@item acronym
Display the acronym of the character's name (such as @sc{zwnj} or
@sc{rlm}) in a box.

@item hex-code
Display the Unicode codepoint of the character in hexadecimal
notation, in a box.
@end table

@noindent
@cindex @code{glyphless-char} face
With the exception of @code{zero-width}, all other methods draw these
characters in a special face @code{glyphless-char}, which you can
customize.

@vindex glyphless-char-display-control
@vindex char-acronym-table
To control what glyphless characters are displayed using which method,
customize the variable @code{glyphless-char-display-control}; see its
doc string for the details.  For even finer control, set the elements
of 2 char-tables: @code{glyphless-char-display} and
@code{char-acronym-table}.

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

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

@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
@code{x-stretch-cursor} to a non-@code{nil} value.

@findex hl-line-mode
@findex global-hl-line-mode
@cindex highlight current line
  To make the cursor even more visible, you can use HL Line mode, a
minor mode that highlights the line containing point.  Use @kbd{M-x
hl-line-mode} to enable or disable it in the current buffer.  @kbd{M-x
global-hl-line-mode} enables or disables the same mode globally.

@node Line Truncation
@section Truncation of Lines

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

@vindex truncate-lines
@findex toggle-truncate-lines
  Horizontal scrolling automatically causes line truncation
(@pxref{Horizontal Scrolling}).  You can explicitly enable line
truncation for a particular buffer with the command @kbd{M-x
toggle-truncate-lines}.  This works by locally changing the variable
@code{truncate-lines}.  If that variable is non-@code{nil}, long 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}.

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

@node Visual Line Mode
@section Visual Line Mode

@cindex word wrap
  Another alternative to ordinary line continuation is to use
@dfn{word wrap}.  Here, each long logical line is divided into two or
more screen lines, like in ordinary line continuation.  However, Emacs
attempts to wrap the line at word boundaries near the right window
edge.  This makes the text easier to read, as wrapping does not occur
in the middle of words.

@cindex Visual Line mode
@findex visual-line-mode
@findex global-visual-line-mode
  Word wrap is enabled by Visual Line mode, an optional minor mode.
To turn on Visual Line mode in the current buffer, type @kbd{M-x
visual-line-mode}; repeating this command turns it off.  You can also
turn on Visual Line mode using the menu bar: in the Options menu,
select the @samp{Line Wrapping in this Buffer} submenu, followed by
the @samp{Word Wrap (Visual Line Mode)} menu item.  While Visual Line
mode is enabled, the mode-line shows the string @samp{wrap} in the
mode display.  The command @kbd{M-x global-visual-line-mode} toggles
Visual Line mode in all buffers.

@findex beginning-of-visual-line
@findex end-of-visual-line
@findex next-logical-line
@findex previous-logical-line
  In Visual Line mode, some editing commands work on screen lines
instead of logical lines: @kbd{C-a} (@code{beginning-of-visual-line})
moves to the beginning of the screen line, @kbd{C-e}
(@code{end-of-visual-line}) moves to the end of the screen line, and
@kbd{C-k} (@code{kill-visual-line}) kills text to the end of the
screen line.

  To move by logical lines, use the commands @kbd{M-x
next-logical-line} and @kbd{M-x previous-logical-line}.  These move
point to the next logical line and the previous logical line
respectively, regardless of whether Visual Line mode is enabled.  If
you use these commands frequently, it may be convenient to assign key
bindings to them.  @xref{Init Rebinding}.

  By default, word-wrapped lines do not display fringe indicators.
Visual Line mode is often used to edit files that contain many long
logical lines, so having a fringe indicator for each wrapped line
would be visually distracting.  You can change this by customizing the
variable @code{visual-line-fringe-indicators}.

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

@vindex visible-bell
  If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts
to make the whole screen blink when it would normally make an audible bell
sound.  This variable has no effect if your terminal does not have a way
to make the screen blink.

@vindex echo-keystrokes
  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.

@cindex mouse pointer
@cindex hourglass pointer display
@vindex display-hourglass
@vindex hourglass-delay
  On graphical displays, Emacs displays the mouse pointer as an
hourglass if Emacs is busy.  To disable this feature, set the variable
@code{display-hourglass} to @code{nil}.  The variable
@code{hourglass-delay} determines the number of seconds of ``busy
time'' before the hourglass is shown; the default is 1.

@vindex make-pointer-invisible
  If the mouse pointer lies inside an Emacs frame, Emacs makes it
invisible each time you type a character to insert text, to prevent it
from obscuring the text.  (To be precise, the hiding occurs when you
type a ``self-inserting'' character.  @xref{Inserting Text}.)  Moving
the mouse pointer makes it visible again.  To disable this feature,
set the variable @code{make-pointer-invisible} to @code{nil}.

@vindex underline-minimum-offset
@vindex x-underline-at-descent-line
  On graphical displays, the variable @code{underline-minimum-offset}
determines the minimum distance between the baseline and underline, in
pixels, for underlined text.  By default, the value is 1; increasing
it may improve the legibility of underlined text for certain fonts.
(However, Emacs will never draw the underline below the current line
area.)  The variable @code{x-underline-at-descent-line} determines how
to draw underlined text.  The default is @code{nil}, which means to
draw it at the baseline level of the font; if you change it to
@code{nil}, Emacs draws the underline at the same height as the font's
descent line.

@vindex overline-margin
  The variable @code{overline-margin} specifies the vertical position
of an overline above the text, including the height of the overline
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
@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.