emacs-gpu/doc/emacs/display.texi

@c -*- coding: utf-8 -*-
@c This is part of the Emacs manual.
@c Copyright (C) 1985--1987, 1993--1995, 1997, 2000--2026 Free Software
@c Foundation, Inc.

@c See file emacs.texi for copying conditions.
@node Display
@chapter Controlling the Display

  Since only part of a large buffer fits in the window, Emacs has to
show only a part of it.  This chapter describes commands and variables
that let you specify which part of the text you want to see, and how
the text is displayed.

@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
                             of the buffer.
* 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.
* Colors::                 Specifying colors for faces.
* Standard Faces::         The main predefined faces.
* Icons::                  How to change how icons look.
* 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.
* 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
@cindex scrolling

  If a window is too small to display all the text in its buffer, it
displays only a portion of it.  @dfn{Scrolling} commands change which
portion of the buffer is 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
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
occurs automatically to bring it back onscreen (@pxref{Auto
Scrolling}).  You can also scroll explicitly with these commands:

@table @kbd
@item C-v
@itemx @key{PageDown}
@itemx @key{next}
Scroll forward by nearly a full window (@code{scroll-up-command}).
@item M-v
@itemx @key{PageUp}
@itemx @key{prior}
Scroll backward (@code{scroll-down-command}).
@end table

@kindex C-v
@kindex M-v
@kindex PageDown
@kindex PageUp
@kindex next
@kindex prior
@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{PageDown} (or @key{next}) key is equivalent to @kbd{C-v}.

  @kbd{M-v} (@code{scroll-down-command}) scrolls backward in a similar
way.  The @key{PageUp} (or @key{prior}) 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}, these commands
move point to the farthest possible position.  If point is already
there, the commands signal 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}.  The
same property also causes Emacs not to exit incremental search when
one of these commands is invoked and @code{isearch-allow-scroll} is
non-@code{nil} (@pxref{Not Exiting Isearch}).

@vindex fast-but-imprecise-scrolling
  Sometimes, particularly when you hold down keys such as @kbd{C-v}
and @kbd{M-v}, activating keyboard auto-repeat, Emacs fails to keep up
with the rapid rate of scrolling requested; the display doesn't update
and Emacs can become unresponsive to input for quite a long time.  You
can counter this sluggishness by setting the variable
@code{fast-but-imprecise-scrolling} to a non-@code{nil} value.  This
instructs the scrolling commands not to fontify (@pxref{Font Lock})
any unfontified text they scroll over, instead to assume it has the
default face.  This can cause Emacs to scroll to somewhat wrong buffer
positions when the faces in use are not all the same size, even with
single (i.e., without auto-repeat) scrolling operations.

@vindex jit-lock-defer-time
As an alternative to setting @code{fast-but-imprecise-scrolling} you
might prefer to enable jit-lock deferred fontification (@pxref{Font
Lock}).  To do this, customize @code{jit-lock-defer-time} to a small
positive number such as 0.25, or even 0.1 if you type quickly.  This
gives you less jerky scrolling when you hold down @kbd{C-v}, but the
window contents after any action which scrolls into a fresh portion of
the buffer will be momentarily unfontified.

@vindex redisplay-skip-fontification-on-input
Finally, a third alternative to these variables is
@code{redisplay-skip-fontification-on-input}.  If this variable is
non-@code{nil}, skip some fontifications if there's input pending.
This usually does not affect the display because redisplay is
completely skipped anyway if input was pending, but it can make
scrolling smoother by avoiding unnecessary fontification.

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

  On graphical displays, you can also scroll a window using the scroll
bar; @pxref{Scroll Bars}.

@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 C-M-S-l
Scroll the other window; this is equivalent to @kbd{C-l} acting on the
other window.

@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}).
@end table

@kindex C-l
@findex recenter-top-bottom
  The @kbd{C-l} (@code{recenter-top-bottom}) command @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 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
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 of the window.  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}, @kbd{C-l} always leaves at least @var{n}
screen lines between point and the top or bottom of the window
(@pxref{Auto Scrolling}).

  You can also give @kbd{C-l} a prefix argument.  A plain prefix
argument, @kbd{C-u C-l}, simply recenters the line showing point.  A
positive argument @var{n} moves line showing point @var{n} lines down
from the top of the window.  An argument of zero moves point's line to
the top of the window.  A negative argument @minus{}@var{n} moves point's
line @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}
value, each invocation of @kbd{C-l} also clears and redisplays the
screen; 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}).

@findex recenter
  The more primitive command @kbd{M-x recenter} behaves like
@code{recenter-top-bottom}, but does not cycle among screen positions.

@kindex C-M-l
@findex reposition-window
  @kbd{C-M-l} (@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

@cindex automatic scrolling
  Emacs performs @dfn{automatic scrolling} when point moves out of the
visible portion of the text.  Normally, automatic scrolling centers
point vertically in the window, but there are several ways to alter
this behavior.

@vindex scroll-conservatively
@vindex scroll-minibuffer-conservatively
  If you set @code{scroll-conservatively} to a small number @var{n},
then moving point just a little off the screen (no more than @var{n}
lines) causes Emacs to scroll just enough to bring point back on
screen; if doing so fails to make point visible, Emacs scrolls just
far enough to center point in the window.  If you set
@code{scroll-conservatively} to a large number (larger than 100),
automatic scrolling never centers point, no matter how far point
moves; Emacs always scrolls text just enough to bring point into view,
either at the top or bottom of the window depending on the scroll
direction.  By default, @code{scroll-conservatively} is@tie{}0, which
means to always center point in the window.
This said, in minibuffer windows, scrolling is always conservative by
default because @code{scroll-minibuffer-conservatively} is non-@code{nil},
which takes precedence over @code{scroll-conservatively}.

@vindex scroll-step
  Another way to control automatic scrolling is to customize the
variable @code{scroll-step}.  Its value determines the number of lines
by which to automatically scroll, when point moves off the screen.  If
scrolling by that number of lines fails to bring point back into view,
point is centered instead.  The default value is zero, which (by
default) causes point to always be centered after scrolling.

@cindex aggressive scrolling
@vindex scroll-up-aggressively
@vindex scroll-down-aggressively
  A third way to control automatic scrolling is to customize the
variables @code{scroll-up-aggressively} and
@code{scroll-down-aggressively}, which directly specify the vertical
position of point after scrolling.  The value of
@code{scroll-up-aggressively} should be either @code{nil} (the
default), or a floating point number @var{f} between 0 and 1.  The
latter means that when point goes below the bottom window edge (i.e.,
scrolling forward), Emacs scrolls the window so that point is @var{f}
parts of the window height from the bottom window edge.  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 when point goes
above the top window edge (i.e., scrolling backward).  The value
specifies how far point should be from the top margin of the window
after scrolling.  Thus, as with @code{scroll-up-aggressively}, a
larger value is more aggressive.

  Note that the variables @code{scroll-conservatively},
@code{scroll-step}, and @code{scroll-up-aggressively} /
@code{scroll-down-aggressively} control automatic scrolling in
contradictory ways.  Therefore, you should pick no more than one of
these methods to customize automatic scrolling.  In case you customize
multiple variables, the order of priority is:
@code{scroll-conservatively}, then @code{scroll-step}, and finally
@code{scroll-up-aggressively} / @code{scroll-down-aggressively}.

@vindex scroll-margin
@vindex maximum-scroll-margin
  The variable @code{scroll-margin} restricts how close point can come
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.  The effective margin size is limited to a
quarter of the window height by default, but this limit can be
increased up to half (or decreased down to zero) by customizing
@code{maximum-scroll-margin}.

@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.  By default, all the lines in the window are scrolled
horizontally together, but if you set the variable
@code{auto-hscroll-mode} to the special value of @code{current-line},
only the line showing the cursor will be scrolled.  To disable
automatic horizontal scrolling entirely, 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 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 left and right 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 (whose value should be between 0 and 1)
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}.  When
@code{auto-hscroll-mode} is set to @code{current-line}, all the lines
other than the one showing the cursor will be scrolled by that minimal
amount.

  On graphical displays, you can scroll a window horizontally using
the horizontal scroll bar, if you turn on the optional
@code{horizontal-scroll-bar-mode}; @pxref{Scroll Bars}.

@node Narrowing
@section Narrowing
@cindex widening
@cindex restriction
@cindex narrowing
@cindex accessible portion

  @dfn{Narrowing} means focusing in on some portion of the buffer,
making the rest temporarily inaccessible.  The portion which you can
still get to is called the @dfn{accessible portion}.  Canceling the
narrowing, which makes the entire buffer once again accessible, is
called @dfn{widening}.  The bounds of narrowing in effect in a buffer
are called the buffer's @dfn{restriction}.

  Narrowing can make it easier to concentrate on a single subroutine or
paragraph by eliminating clutter.  It can also be used to limit the
range of operation of a replace command or repeating keyboard macro.

@table @kbd
@item C-x n n
Narrow down to between point and mark (@code{narrow-to-region}).
@item C-x n w
Widen to make the entire buffer accessible again (@code{widen}).
@item C-x n p
Narrow down to the current page (@code{narrow-to-page}).
@item C-x n d
Narrow down to the current defun (@code{narrow-to-defun}).
@end table

  When you have narrowed down to a part of the buffer, that part appears
to be all there is.  You can't see the rest, you can't move into it
(motion commands won't go outside the accessible part), you can't change
it in any way.  However, it is not gone, and if you save the file all
the inaccessible text will be saved.  The word @samp{Narrow} appears in
the mode line whenever narrowing is in effect.

@kindex C-x n n
@findex narrow-to-region
  The primary narrowing command is @kbd{C-x n n} (@code{narrow-to-region}).
It sets the current buffer's restrictions so that the text in the current
region remains accessible, but all text before the region or after the
region is inaccessible.  Point and mark do not change.

@kindex C-x n p
@findex narrow-to-page
@kindex C-x n d
@findex narrow-to-defun
  Alternatively, use @kbd{C-x n p} (@code{narrow-to-page}) to narrow
down to the current page.  @xref{Pages}, for the definition of a page.
@kbd{C-x n d} (@code{narrow-to-defun}) narrows down to the defun
containing point (@pxref{Defuns}).

@kindex C-x n w
@findex widen
  The way to cancel narrowing is to widen with @kbd{C-x n w}
(@code{widen}).  This makes all text in the buffer accessible again.

  You can get information on what part of the buffer you are narrowed down
to using the @kbd{C-x =} command.  @xref{Position Info}.

  Because narrowing can easily confuse users who do not understand it,
@code{narrow-to-region} is normally a disabled command.  Attempting to use
this command asks for confirmation and gives you the option of enabling it;
if you enable the command, confirmation will no longer be required for
it.  @xref{Disabling}.

@node View Mode
@section View Mode
@cindex View mode
@cindex mode, View

@kindex s @r{(View mode)}
@kindex SPC @r{(View mode)}
@kindex DEL @r{(View mode)}
  View mode is a minor mode that lets you scan a buffer by sequential
screenfuls.  It provides commands for scrolling through the buffer
conveniently but not for changing it.  Apart from the usual Emacs
cursor motion commands, you can type @key{SPC} to scroll forward one
windowful, @kbd{S-@key{SPC}} or @key{DEL} to scroll backward, and @kbd{s} to
start an incremental search.

@kindex q @r{(View mode)}
@kindex e @r{(View mode)}
@findex View-quit
@findex View-exit
  Typing @kbd{q} (@code{View-quit}) disables View mode, and switches
back to the buffer and position before View mode was enabled.  Typing
@kbd{e} (@code{View-exit}) disables View mode, keeping the current
buffer and position.

@findex view-buffer
@findex view-file
  @kbd{M-x view-buffer} prompts for an existing Emacs buffer, switches
to it, and enables View mode.  @kbd{M-x view-file} prompts for a file
and visits it with View mode enabled.

@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 Text Faces
@cindex faces

  Emacs can display text in several different styles, called
@dfn{faces}.  Each face can specify various @dfn{face attributes},
such as the font, height, weight, slant, foreground and background
color, and underlining or overlining.  Most major modes assign faces
to the text automatically, via Font Lock mode.  @xref{Font Lock}, for
more information about how these faces are assigned.

@findex list-faces-display
  To see what faces are currently defined, and what they look like,
type @kbd{M-x list-faces-display}.  With a prefix argument, this
prompts for a regular expression, and displays only faces with names
matching that regular expression (@pxref{Regexps}).

@vindex frame-background-mode
  It's possible for a given face to look different in different
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.  In addition, most Emacs faces are defined so
that their attributes are different on light and dark frame
backgrounds, for reasons of legibility.  By default, Emacs
automatically chooses which set of face attributes to display on each
frame, based on the frame's current background color.  However, you
can override this by giving the variable @code{frame-background-mode}
a non-@code{nil} value.  A value of @code{dark} makes Emacs treat all
frames as if they have a dark background, whereas a value of
@code{light} makes it treat all frames as if they have a light
background.

@cindex background color
@cindex @code{default face}
  You can customize a face to alter its attributes, and save those
customizations for future Emacs sessions.  @xref{Face Customization},
for details.

  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 @code{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

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

@subsection Color Names
@cindex color name
@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.

@subsection RGB Triplets
@cindex RGB triplet
  An RGB triplet is a string of the form @samp{#RRGGBB}.  Each of the
primary color components is represented by a hexadecimal number
between @samp{00} (intensity 0) and @samp{FF} (the maximum intensity).
It is also possible to use one, three, or four hex digits for each
component, so @samp{red} can be represented as @samp{#F00},
@samp{#fff000000}, or @samp{#ffff00000000}.  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 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; @xref{Frame
Parameters}.

@node Standard Faces
@section Standard Faces
@cindex standard faces

  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.
Its background color is used as the frame's background color.

@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 fixed-pitch-serif
This face is like @code{fixed-pitch}, except the font has serifs and
looks more like traditional typewriting.

@cindex @code{variable-pitch} face
@item variable-pitch
This face forces use of a variable-width (i.e., proportional) font.
The font size picked for this face matches the font picked for the
default (usually fixed-width) font.

@item variable-pitch-text
This is like the @code{variable-pitch} face (from which it inherits),
but is slightly larger.  A proportional font of the same height as a
monospace font usually appears visually smaller, and can therefore be
harder to read.  When displaying longer texts, this face can be a good
choice over the (slightly smaller) @code{variable-pitch} face.

@cindex @code{shadow} face
@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 text highlighting in various contexts, such as
when the mouse cursor is moved over a hyperlink.
@item isearch
This face is used to highlight the current Isearch match
(@pxref{Incremental Search}).
@item query-replace
This face is used to highlight the current Query Replace match
(@pxref{Replace}).
@item lazy-highlight
This face is used to highlight lazy matches for Isearch and Query
Replace (matches other than the current one).
@item region
This face is used for displaying an active region (@pxref{Mark}).
When Emacs is built with GTK+ support, its colors are taken from the
current GTK+ theme.
@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} (@pxref{Useless
Whitespace}).
@item escape-glyph
The face for displaying control characters and escape sequences
(@pxref{Text Display}).
@item homoglyph
The face for displaying lookalike characters, i.e., characters that
look like but are not the characters being represented
(@pxref{Text Display}).
@item nobreak-space
The face for displaying no-break space characters (@pxref{Text
Display}).
@item nobreak-hyphen
The face for displaying no-break hyphen characters (@pxref{Text
Display}).
@end table

  The following faces control the appearance of parts of the Emacs
frame:

@table @code
@cindex @code{mode-line} face
@item mode-line
This is the base face used for the mode lines, as well as header lines
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 text terminals.

The @code{mode-line-active} and @code{mode-line-inactive} faces (which
are the ones used on the mode lines) inherit from this face.

@cindex faces for mode lines
@item mode-line-active
Like @code{mode-line}, but used for the mode line of the currently
selected window.  This face inherits from @code{mode-line}, so changes
in that face affect mode lines in all windows.

@cindex @code{mode-line-inactive} face
@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.

@cindex @code{mode-line-highlight} face
@item mode-line-highlight
Like @code{highlight}, but used for mouse-sensitive portions of text
on mode lines.  Such portions of text typically pop up tooltips
(@pxref{Tooltips}) when the mouse pointer hovers above them.

@cindex @code{mode-line-buffer-id} face
@item mode-line-buffer-id
This face is used for buffer identification parts in the mode line.

@cindex @code{header-line} face
@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.

The @code{header-line-active} and @code{header-line-inactive} faces (which
are the ones actually used on the header lines) inherit from this face.

@cindex faces for header lines
@item header-line-active
Like @code{header-line}, but used for the header line of the currently
selected window.  This face inherits from @code{header-line}, so changes
in that face affect header lines in all windows.

@cindex @code{header-line-inactive} face
@item header-line-inactive
Like @code{header-line}, but used for header lines of the windows other
than the selected one (if those windows have a header line).  This face
inherits from @code{header-line}, so changes in that face affect header
lines in all windows.

@cindex @code{header-line-highlight} face
@item header-line-highlight
Similar to @code{highlight} and @code{mode-line-highlight}, but used
for mouse-sensitive portions of text on header lines.  This is a
separate face because the @code{header-line} face might be customized
in a way that does not interact well with @code{highlight}.

@cindex @code{tab-line} face
@item tab-line
Similar to @code{mode-line} for a window's tab line, which appears
at the top of a window with tabs representing window buffers.
@xref{Tab Line}.

The @code{tab-line-active} and @code{tab-line-inactive} faces (which
are the ones actually used on the tab lines) inherit from this face.

@cindex faces for tab lines
@item tab-line-active
Like @code{tab-line}, but used for the tab line of the currently
selected window.  This face inherits from @code{tab-line}, so changes
in that face affect tab lines in all windows.

@cindex @code{tab-line-inactive} face
@item tab-line-inactive
Like @code{tab-line}, but used for tab lines of the windows other
than the selected one (if those windows have a tab line).  This face
inherits from @code{tab-line}, so changes in that face affect tab
lines in all windows.

@cindex @code{vertical-border} face
@item vertical-border
This face is used for the vertical divider between windows on text
terminals.

@cindex @code{minibuffer-prompt} face
@vindex minibuffer-prompt-properties
@item minibuffer-prompt
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 (@pxref{Text Properties,,, elisp, the Emacs Lisp Reference
Manual}) used to display the prompt text.  (This variable takes effect
when you enter the minibuffer.)

@cindex @code{fringe} face
@item fringe
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 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
effect.  @xref{Tooltips}.

@item mouse
This face determines the color of the mouse pointer.
@end table

  The following faces likewise control the appearance of parts of the
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
This face determines the visual appearance of the scroll bar.
@xref{Scroll Bars}.
@item tool-bar
This face determines the color of tool bar icons.  @xref{Tool Bars}.
@item tab-bar
This face determines the color of tab bar icons.  @xref{Tab Bars}.
@cindex menu bar appearance
@cindex @code{menu} face, no effect if customized
@cindex customization of @code{menu} face
@item menu
This face determines the colors and font of Emacs's menus.  @xref{Menu
Bars}.
@cindex faces for text-mode menus
@cindex TTY menu faces
@item tty-menu-enabled-face
This face is used to display enabled menu items on text-mode
terminals.
@item tty-menu-disabled-face
This face is used to display disabled menu items on text-mode
terminals.
@item tty-menu-selected-face
This face is used to display on text-mode terminals the menu item that
would be selected if you click a mouse or press @key{RET}.
@end table

@node Icons
@section Icons
@cindex icons, on clickable buttons

Emacs sometimes displays clickable buttons (or other informative
icons), and you can customize how these look on display.

@vindex icon-preference
The main customization point here is the @code{icon-preference} user
option.  By using this, you can tell Emacs your overall preferences
for icons.  This is a list of icon types, and the first icon type
that's supported will be used.  The supported types are:

@table @code
@item image
Use an image for the icon.

@item emoji
Use a colorful emoji for the icon.

@item symbol
Use a monochrome symbol for the icon.

@item text
Use a simple text for the icon.
@end table

In addition, each individual icon can be customized with @kbd{M-x
customize-icon}, and themes can further alter the looks of the icons.

To get a quick description of an icon, use the @kbd{M-x describe-icon}
command.

@node Text Scale
@section Text Scale

@cindex adjust buffer font size
@cindex font size of @code{default} face, increase or decrease
@findex text-scale-adjust
@kindex C-x C-+
@kindex C-x C--
@kindex C-x C-=
@kindex C-x C-0
@kindex C-wheel-down
@kindex C-wheel-up
  To increase the font size of the @code{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) font size, 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 and adjusts the font size accordingly
by changing the height of the default face.

  Most faces don't have an explicit setting of the @code{:height}
attribute, and thus inherit the height from the @code{default} face.
Those faces are also scaled by the above commands.

  Faces other than @code{default} that have an explicit setting of the
@code{:height} attribute are not affected by these font size changes.
The @code{header-line} face is an exception: it will be scaled even if
it has an explicit setting of the @code{:height} attribute.

  Similarly, scrolling the mouse wheel with the @kbd{Ctrl} modifier
pressed, when the mouse pointer is above buffer text, will increase or
decrease the font size of the affected faces, depending on the
direction of the scrolling.

  The final key of these commands may be repeated without the leading
@kbd{C-x} and without the modifiers.  For instance, @w{@kbd{C-x C-= C-= C-=}}
and @w{@kbd{C-x C-= = =}} increase the face height by three steps.  Each
step scales the text height by a factor of 1.2; to change this factor,
customize the variable @code{text-scale-mode-step}.  A numeric
argument of 0 to the @code{text-scale-adjust} command restores the
default height, the same as typing @kbd{C-x C-0}.

@cindex adjust global font size
@findex global-text-scale-adjust
@vindex global-text-scale-adjust-resizes-frames
@kindex C-x C-M-+
@kindex C-x C-M-=
@kindex C-x C-M--
@kindex C-x C-M-0
@kindex C-M-wheel-down
@kindex C-M-wheel-up
  Similarly, to change the sizes of the fonts globally, type @kbd{C-x
C-M-+}, @kbd{C-x C-M-=}, @kbd{C-x C-M--} or @kbd{C-x C-M-0}, or scroll
the mouse wheel with both the @kbd{Ctrl} and @kbd{Meta} modifiers
pressed.  To enable frame resizing when the font size is changed
globally, customize the variable
@code{global-text-scale-adjust-resizes-frames} (@pxref{Easy
Customization}).

@cindex increase buffer font size
@findex text-scale-increase
@cindex decrease buffer font size
@findex text-scale-decrease
  The commands @code{text-scale-increase} and
@code{text-scale-decrease} increase or decrease the size of the font
in the current buffer, 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 font size
@findex text-scale-set
  The command @code{text-scale-set} scales the size of the font in the
current buffer to an absolute level specified by its prefix argument.

@findex text-scale-mode
  The above commands automatically enable the minor mode
@code{text-scale-mode} if the current font scaling is other than 1,
and disable it otherwise.

@cindex pinch to scale
@findex text-scale-pinch
  The command @code{text-scale-pinch} increases or decreases the text
scale based on the distance between fingers on a touchpad when a pinch
gesture is performed by placing two fingers on a touchpad and moving
them towards or apart from each other.  This is only available on some
systems with supported hardware.

@findex mouse-wheel-text-scale
  The command @code{mouse-wheel-text-scale} also changes the text
scale.  Normally, it is run when you press @key{Ctrl} while moving the
mouse wheel.  The text scale is increased when the wheel is moved
downwards, and it is decreased when the wheel is moved upwards.

@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 assigns faces to (or @dfn{fontifies}) the text in the buffer.
Each buffer's major mode tells Font Lock mode which text to fontify;
for instance, programming language modes fontify syntactically
relevant constructs like comments, strings, and function names.

@findex font-lock-mode
  Font Lock mode is enabled by default in major modes that support it.
To toggle it in the current buffer, type @kbd{M-x font-lock-mode}.  A
positive numeric argument unconditionally enables Font Lock mode, and
a negative or zero argument disables it.

@findex global-font-lock-mode
@vindex global-font-lock-mode
  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

@noindent
If you have disabled Global Font Lock mode, you can still enable Font
Lock for specific major modes by adding the function
@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 'font-lock-mode)
@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}.

@cindex just-in-time (JIT) font-lock
@cindex background syntax highlighting
  Fontifying very large buffers can take a long time.  To avoid large
delays when a file is visited, Emacs initially 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}.

  The information that major modes use for determining which parts of
buffer text to fontify and what faces to use can be based on several
different ways of analyzing the text:

@itemize @bullet
@item
Search for keywords and other textual patterns based on regular
expressions (@pxref{Regexp Search,, Regular Expression Search}).

@item
Find syntactically distinct parts of text based on built-in syntax
tables (@pxref{Syntax Tables,,, elisp, The Emacs Lisp Reference
Manual}).

@item
Use syntax tree produced by a full-blown parser, via a special-purpose
library, such as the tree-sitter library (@pxref{Parsing Program
Source,,, elisp, The Emacs Lisp Reference Manual}), or an external
program.
@end itemize

@menu
* Traditional Font Lock::  Font Lock based on regexps and syntax tables.
* Parser-based Font Lock:: Font Lock based on external parser.
* Semantic Font Lock::     Font Lock based on semantic analysis.
@end menu

@node Traditional Font Lock
@subsection Traditional Font Lock
@cindex traditional font-lock

  ``Traditional'' methods of providing font-lock information are based
on regular-expression search and on syntactic analysis using syntax
tables built into Emacs.  This subsection describes the use and
customization of font-lock for major modes which use these traditional
methods.

@vindex font-lock-maximum-decoration
  You can control the amount of fontification applied by Font Lock
mode by customizing the variable @code{font-lock-maximum-decoration},
for major modes that support this feature.  The value of this variable
should be a number (with 1 representing a minimal amount of
fontification; some modes support levels as high as 3); or @code{t},
meaning ``as high as possible'' (the default).  To be effective for a
given file buffer, the customization of
@code{font-lock-maximum-decoration} should be done @emph{before} the
file is visited; if you already have the file visited in a buffer when
you customize this variable, kill the buffer and visit the file again
after the customization.

You can also specify different numbers for particular major modes; for
example, to use level 1 for C/C++ modes, and the default level
otherwise, use the value

@example
'((c-mode . 1) (c++-mode . 1)))
@end example

@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 beginning of a defun, and is thus always outside
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.

@findex font-lock-add-keywords
  Font Lock highlighting patterns already exist for most 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
@vindex font-lock-ignore
@noindent
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}.
Alternatively, you can selectively disable highlighting due to some
keywords by customizing the @code{font-lock-ignore} option,
@pxref{Customizing Keywords,,, elisp, The Emacs Lisp Reference
Manual}.

@node Parser-based Font Lock
@subsection Parser-based Font Lock
@cindex font-lock via tree-sitter
@cindex parser-based font-lock
  If your Emacs was built with the tree-sitter library, it can use the
results of parsing the buffer text by that library for the purposes of
fontification.  This is usually faster and more accurate than the
``traditional'' methods described in the previous subsection, since
the tree-sitter library provides full-blown parsers for programming
languages and other kinds of formatted text which it supports.  Major
modes which utilize the tree-sitter library are named
@code{@var{foo}-ts-mode}, with the @samp{-ts-} part indicating the use
of the library.  This subsection documents the Font Lock support based
on the tree-sitter library.

@vindex treesit-font-lock-level
  You can control the amount of fontification applied by Font Lock
mode of major modes based on tree-sitter by customizing the variable
@code{treesit-font-lock-level}.  Its value is a number between 1 and
4:

@table @asis
@item Level 1
This level usually fontifies only comments and function names in
function definitions.
@item Level 2
This level adds fontification of keywords, strings, and data types.
@item Level 3
This is the default level; it adds fontification of assignments,
numbers, etc.
@item Level 4
This level adds everything else that can be fontified: operators,
delimiters, brackets, other punctuation, function names in function
calls, property look ups, variables, etc.
@end table

@vindex treesit-font-lock-feature-list
@noindent
What exactly constitutes each of the syntactical categories mentioned
above depends on the major mode and the parser grammar used by
tree-sitter for the major-mode's language.  However, in general the
categories follow the conventions of the programming language or the
file format supported by the major mode.  The buffer-local value of
the variable @code{treesit-font-lock-feature-list} holds the
fontification features supported by a tree-sitter based major mode,
where each sub-list shows the features provided by the corresponding
fontification level.

  Once you change the value of @code{treesit-font-lock-level} via
@w{@kbd{M-x customize-variable}} (@pxref{Specific Customization}), it
takes effect immediately in all the existing buffers and for files you
visit in the future in the same session.

@node Semantic Font Lock
@subsection Semantic Font Lock
@cindex semantic highlighting

@dfn{Semantic highlighting} is feature in which
an editor uses some kind of semantic analysis to understand a program's
source code, and communicates useful information about the meaning of
different tokens to the user by highlighting these tokens according to
their specific role in the program.

Semantic highlighting is more sophisticated than traditional ``syntax
highlighting'', which only considers the syntactic role of a token,
i.e., how it affects the code's @emph{parsing}, unlike semantic analysis
which takes into account the token's effect on the program's
@emph{execution}.  For example, a semantic highlighting implementation
may be able to tell apart local and global variables and give distinct
highlighting to each category, even though the language's @emph{syntax}
doesn't make such a distinction.  Semantic highlighting is especially
beneficial in languages in which syntactic constructs can mean
completely different things depending on the context in which they
occur, such as Lisp and Prolog.  In such languages, syntactic analysis
alone misses a lot of important information that coders need to reason
about their programs.

Some language servers provide semantic highlighting information, which
Emacs can leverage via its LSP client, Eglot.  @xref{Eglot Features,,,
eglot, Eglot: The Emacs LSP Client}.

@vindex elisp-fontify-semantically
Additionally, Emacs implements semantic highlighting for Emacs Lisp as
an optional feature of @code{emacs-lisp-mode} (@pxref{Executing Lisp}).
To enable it, customize the option @code{elisp-fontify-semantically} to
a non-@code{nil} value.  The rest of this subsection describes the use
of this Emacs Lisp-specific semantic highlighting support.

When @code{elisp-fontify-semantically} is enabled,
@code{emacs-lisp-mode} analyzes your code and highlights symbols
according to their semantic roles, as part of the mode's usual Font Lock
highlighting (@pxref{Font Lock}).  It doesn't affect the highlighting of
strings, comments and other syntactic elements such as brackets;
@code{elisp-fontify-semantically} only affects highlighting of symbols.

@cindex symbol role, in semantic analysis
The semantic analysis assigns to each symbol a @dfn{symbol role}, such
as ``function'', ``local variable'', ``face name'', etc.  Each symbol
role has an associated face property, which is applied to symbols with
that role during semantic highlighting.  By default, most of these faces
inherit from appropriate @code{font-lock-*} faces.  For example,
locally-bound variables get the @code{elisp-bound-variable} face, which
inherits from @code{font-lock-variable-use-face}.

@vindex elisp-add-help-echo
The semantic analysis can differentiate between more than 50 such symbol roles,
but you don't need to memorize the appearance of so many faces to
leverage semantic highlighting: you can hover over an highlighted symbol
with the mouse to see a tooltip with the exact role Emacs inferred for
that symbol (@pxref{Tooltips}).  If you want to disable this extra
information, customize @code{elisp-add-help-echo} to the @code{nil} value.

There are a few more points you should keep in mind when using
@code{elisp-fontify-semantically}:

@itemize @bullet
@item
Syntax errors break semantic analysis, so for best results you may want
to enable @code{electric-pair-mode} to keep your code syntactically
correct while you edit it.  @xref{Matching}.

@cindex trusted buffers, and semantic highlighting
@vindex elisp-scope-safe-macros
@item
The analysis uses macro-expansion in some cases, but by default it only
does so in trusted buffers (@pxref{Host Security}).  In @emph{untrusted}
buffers, some macro arguments may not be highlighted.  See the
documentation string of @code{elisp-scope-safe-macro-p} for more
information about which macros Emacs considers safe to expand for
analysis.  The user option @code{elisp-scope-safe-macros} controls which
macros are safe to expand during analysis in untrusted buffers.

@item
The analysis is informed by definitions in the current Emacs session,
hence code that uses unloaded libraries may miss some highlighting.

@item
The analysis assumes that lexical binding is in effect (@pxref{Selecting
Lisp Dialect,,, elisp, the Emacs Lisp Reference Manual}).

@item
Semantic highlighting requires additional processing over traditional
Font Lock---the current implementation might be slow when editing very
large defuns.
@end itemize


@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 that 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
can control them with the following commands.  (The key bindings
below that begin with @kbd{C-x w} are deprecated in favor of the
global @kbd{M-s h} bindings, and will be removed in some future Emacs
version.)

@table @kbd
@item M-s h r @var{regexp} @key{RET} @var{face} @key{RET}
@itemx C-x w h @var{regexp} @key{RET} @var{face} @key{RET}
@kindex M-s h r
@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), type
@kbd{M-s h r 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.  A prefix
numeric argument limits the highlighting to the corresponding
subexpression.

@vindex hi-lock-auto-select-face
Setting the option @code{hi-lock-auto-select-face} to a non-@code{nil}
value causes this command (and other Hi Lock commands that read faces)
to automatically choose the next face from the default list without
prompting.

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

@item M-s h u @var{regexp} @key{RET}
@itemx C-x w r @var{regexp} @key{RET}
@kindex M-s h u
@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-n}
to show the next older expression and @kbd{M-p} 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 M-s h l @var{regexp} @key{RET} @var{face} @key{RET}
@itemx C-x w l @var{regexp} @key{RET} @var{face} @key{RET}
@kindex M-s h l
@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 M-s h p @var{phrase} @key{RET} @var{face} @key{RET}
@itemx C-x w p @var{phrase} @key{RET} @var{face} @key{RET}
@kindex M-s h p
@kindex C-x w p
@findex highlight-phrase
@cindex phrase, highlighting
@cindex highlighting phrase
Highlight matches of @var{phrase}, using face @var{face}
(@code{highlight-phrase}).  @var{phrase} can be any regexp,
but spaces will be replaced by matches to whitespace and
initial lower-case letters will become case insensitive.

@item M-s h .
@itemx C-x w .
@kindex M-s h .
@kindex C-x w .
@findex highlight-symbol-at-point
@cindex symbol, highlighting
@cindex highlighting symbol at point
Highlight the symbol found near point, using the next available face
(@code{highlight-symbol-at-point}).

@item M-s h w
@itemx C-x w b
@kindex M-s h w
@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 M-s h f
@itemx C-x w i
@kindex M-s h f
@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

@findex set-fringe-style
@findex fringe-mode
@vindex fringe-mode @r{(variable)}
  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 toggle display of the fringes or
to 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}.  You can make your changes to the fringes permanent
by customizing the variable @code{fringe-mode}.

  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
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 meanings of the curving arrows in the fringes are
swapped.

  The fringes indicate line truncation (@pxref{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 buffer
boundaries (@pxref{Displaying Boundaries}), unused lines near the end
of the window (@pxref{indicate-empty-lines}), and where a program you
are debugging is executing (@pxref{Debuggers}).

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

  If you customize @code{fringe-mode} to remove the fringes on one or
both sides of the window display, the features that display on the
fringe are not available.  Indicators of line continuation and
truncation are an exception: when fringes are not available, Emacs
uses the leftmost and rightmost character cells to indicate
continuation and truncation with special ASCII characters, see
@ref{Continuation Lines}, and @ref{Line Truncation}.  This reduces the
width available for displaying text on each line, because the
character cells used for truncation and continuation indicators are
reserved for that purpose.  Since buffer text can include
bidirectional text, and thus both left-to-right and right-to-left
paragraphs (@pxref{Bidirectional Editing}), removing only one of the
fringes still reserves two character cells, one on each side of the
window, for truncation and continuation indicators, because these
indicators are displayed on opposite sides of the window in
right-to-left paragraphs.

@node Displaying Boundaries
@section Displaying Boundaries

@cindex mode, display-fill-column-indicator
@findex display-fill-column-indicator-mode
@findex global-display-fill-column-indicator-mode
  Emacs can display an indication of the @code{fill-column} position
(@pxref{Fill Commands}).  The fill-column indicator is a useful
functionality especially in @code{prog-mode} and its descendants
(@pxref{Major Modes}) to indicate the position of a specific column
that has some special meaning for formatting the source code of a
program.  This assumes the buffer uses a fixed-pitch font, where all
the characters (with the possible exception of double-width
characters) have the same width on display.  If the buffer uses
variable-pitch fonts, the fill-column indicators on different lines
might appear unaligned.

  To activate the fill-column indication display, use the minor modes
@code{display-fill-@-column-indicator-mode} and
@code{global-display-fill-column-indicator-mode}, which enable
the indicator locally or globally, respectively.

Alternatively, you can set the two buffer-local variables
@code{display-fill-column-indicator} and
@code{display-fill-column-indicator-character} to activate the
indicator and control the character used for the indication.  Note
that both variables must be non-@code{nil} for the indication to be
displayed.  (Turning on the minor mode sets both these variables.)

There are 2 buffer local variables and a face to customize this mode:

@table @code
@item display-fill-column-indicator-column
@vindex display-fill-column-indicator-column
Specifies the column number where the indicator should be set.  It can
take positive numerical values for the column, or the special value
@code{t}, which means that the value of the variable
@code{fill-column} will be used.

Any other value disables the indicator.  The default value is @code{t}.

@item display-fill-column-indicator-character
@vindex display-fill-column-indicator-character
Specifies the character used for the indicator.  This character can be
any valid character including Unicode ones if the font supports them.
The value @code{nil} disables the indicator.  When the mode is enabled
through the functions @code{display-fill-column-indicator-mode} or
@code{global-display-fill-column-indicator-mode}, they will use the
character specified by this variable, if it is non-@code{nil};
otherwise Emacs will use the character U+2502 @sc{box drawings light vertical},
falling back to @samp{|} if U+2502 cannot be displayed.

@item fill-column-indicator
@vindex fill-column-indicator
Specifies the face used to display the indicator.  It inherits its
default values from the face @code{shadow}, but without background
color.  To change the indicator color, you need only set the foreground
color of this face.
@end table

@vindex indicate-buffer-boundaries
  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
possible to scroll the window.

  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 (@pxref{Association Lists,,, elisp, the Emacs
Lisp Reference Manual}), 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 buffer, without realizing it.  In most
cases, this @dfn{trailing whitespace} has no effect, but sometimes it
can be a nuisance.

@cindex @code{trailing-whitespace} face
  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
@vindex delete-trailing-lines
  Type @kbd{M-x delete-trailing-whitespace} to delete all trailing
whitespace.  This command deletes all extra spaces at the end of each
line in the buffer, and all empty lines at the end of the buffer; to
ignore the latter, change the variable @code{delete-trailing-lines} to
@code{nil}.  If the region is active, the command instead deletes
extra spaces at the end of each line in the region.

@vindex indicate-empty-lines
@cindex unused lines
@cindex fringes, and unused line indication
@anchor{indicate-empty-lines}
  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 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
@findex whitespace-toggle-options
  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}.  Individual elements in
that list can be toggled on or off in the current buffer by typing
@w{@kbd{M-x whitespace-toggle-options}}.  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 columns.  To change the column limit,
customize the variable @code{whitespace-line-column}.

@item newline
Highlight newlines.

@item missing-newline-at-eof
Highlight the final character if the buffer doesn't end with a newline
character.

@item empty
Highlight empty lines at the beginning and/or end of the buffer.

@item big-indent
@vindex whitespace-big-indent-regexp
Highlight too-deep indentation.  By default any sequence of at least 4
consecutive tab characters or 32 consecutive space characters is
highlighted.  To change that, customize the regular expression
@code{whitespace-big-indent-regexp}.

@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

@findex global-whitespace-toggle-options
@findex global-whitespace-mode
Global Whitespace mode is a global minor mode that lets you visualize
whitespace in all buffers.  To toggle individual features, use
@kbd{M-x global-whitespace-toggle-options}.

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

@vindex column-number-indicator-zero-based
  In Column Number mode, the displayed column number counts from zero
starting at the left margin of the window.  If you would prefer for
the displayed column number to count from one, you may set
@code{column-number-indicator-zero-based} to @code{nil}.

@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}.  (The
command @code{what-line} shows the line number relative to the whole
file.)  You can use @code{goto-line-relative} command to move point to
the line relative to the accessible portion of the narrowed buffer.

@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 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 to be newly arrived mail).

@cindex battery status (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.  The functions in
@code{battery-update-functions} are run after updating the mode line,
and can be used to trigger actions based on the battery status.

@cindex mode line, 3D appearance
@cindex attributes of mode line, changing
@cindex non-integral number of lines in a window
  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}.

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

@vindex mode-line-compact
@vindex mode-line-collapse-minor-modes
  Some modes put a lot of data in the mode line, pushing elements at the
end of the mode line off to the right.  Emacs can ``compress'' the mode
line if the @code{mode-line-compact} variable is non-@code{nil} by
turning stretches of spaces into a single space.  If this variable is
@code{long}, this is only done when the mode line is wider than the
currently selected window.  (This computation is approximate, based on
the number of characters, and not their displayed width.)  This variable
can be buffer-local to only compress mode-lines in certain buffers.  To
further ``compress'' the mode line, you may customize the
@code{mode-line-collapse-minor-modes} option to a non-@code{nil} value,
and Emacs will hide some minor mode indicators on the mode line by
collapsing them into a single clickable button.

@findex mode-line-invisible-mode
  By default, most buffers display a mode line, but if the mode line is
not useful in a buffer, you can use the command @w{@kbd{M-x
mode-line-invisible-mode}} to hide the mode line in the current buffer,
the mode line remains hidden until this command is called again.  To
always hide the mode line when entering to a major mode, add
@code{mode-line-invisible-mode} to a hook (@pxref{Hooks}).

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

  Most characters are @dfn{printing characters}: when they appear in a
buffer, they are displayed literally on the screen.  Printing
characters include @acronym{ASCII} numbers, letters, and punctuation
characters, as well as many non-@acronym{ASCII} characters.

@vindex tab-width
@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 U+000A) is displayed by starting
a new line, while the tab character (U+0009) is displayed as a
space that extends to the next tab stop column (normally every 8
columns).  The number of spaces per tab is controlled by the
buffer-local variable @code{tab-width}, which must have an integer
value between 1 and 1000, inclusive.  Note that the way 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, whose codes are below
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, U+0001, is displayed as @samp{^A}.

@cindex octal escapes
@vindex ctl-arrow
  The raw bytes with codes U+0080 (octal 200) through
U+009F (octal 237) are displayed as @dfn{octal escape
sequences}, with the @code{escape-glyph} face.  For instance,
character code U+0098 (octal 230) is displayed as @samp{\230}.
If you change the buffer-local variable @code{ctl-arrow} to
@code{nil}, the @acronym{ASCII} control characters are also displayed
as octal escape sequences instead of caret escape sequences.  (You can
also request that raw bytes be shown in hex, @pxref{Display Custom,
display-raw-bytes-as-hex}.)

@vindex nobreak-char-display
@cindex non-breaking space
@cindex non-breaking hyphen
@cindex soft hyphen
@cindex @code{escape-glyph} face
@cindex @code{nobreak-space} face
  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 U+00A0 @sc{no-break space} and other
characters from the Unicode horizontal space class with the
@code{nobreak-space} face, and it displays U+00AD @sc{soft
hyphen}, U+2010 @sc{hyphen}, and U+2011 @sc{non-breaking
hyphen} with the @code{nobreak-hyphen} 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,
elisp, The Emacs Lisp Reference Manual}.

@cindex glyphless characters
@cindex characters with no font glyphs
@cindex @code{glyphless-char} face
  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.
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}.  You
can also customize the @code{glyphless-char} face to make these
characters more prominent on display.  @xref{Glyphless Chars,,
Glyphless Character Display, elisp, The Emacs Lisp Reference Manual},
for details.

@findex glyphless-display-mode
  The @code{glyphless-display-mode} minor mode can be used to toggle
the display of glyphless characters in the current buffer.  The
glyphless characters will be displayed as boxes with acronyms of their
names inside.

@cindex curly quotes, and terminal capabilities
@cindex curved quotes, and terminal capabilities
@cindex @code{homoglyph} face

Emacs tries to determine if the curved quotes @t{‘} and @t{’}
can be displayed on the current display.  By default, if this seems to
be so, then Emacs will translate the @acronym{ASCII} quotes @w{(@samp{`}
and @samp{'})}, when they appear in messages and help texts, to these
curved quotes.  You can influence or inhibit this translation by
customizing the user option @code{text-quoting-style} (@pxref{Keys in
Documentation,,, elisp, The Emacs Lisp Reference Manual}).

  If the curved quotes @t{‘}, @t{’}, @t{“}, and @t{”} are
known to look just like @acronym{ASCII} characters, they are shown
with the @code{homoglyph} face.  Curved quotes that are known not to
be displayable are shown as their @acronym{ASCII} approximations
@samp{`}, @samp{'}, and @samp{"} with the @code{homoglyph} face.

@node Cursor Display
@section Displaying the Cursor
@cindex text cursor

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

@vindex cursor-type
  On a graphical display and many Xterm-compatible text terminals, the
color and shape 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{(box . @var{size})} (box cursor becoming a hollow
box under masked images larger than @var{size} pixels in either
dimension), @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).

@vindex xterm-update-cursor
  On Xterm-compatible text terminals cursor customization is controlled
by the user option @code{xterm-update-cursor}.  Valid values are
@code{t} to update the cursor's color and shape, @code{type} to update
the cursor's shape only, @code{color} to update the cursor's color only,
and @code{nil} to not update the cursor's appearance.  Text terminals
can not display a hollow box and instead use a filled box.  Similarly,
all text terminals ignore the pixel sizes for @code{bar} and
@code{hbar}.

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

  The remaining controls only work on graphical displays where Emacs can
fully control the way the cursor appears.

@findex blink-cursor-mode
@cindex cursor, blinking
@cindex blinking cursor
@vindex blink-cursor-mode
@vindex blink-cursor-blinks
@vindex blink-cursor-alist
  By default, the cursor stops blinking after 10 blinks, if Emacs does
not get any input during that time; any input event restarts the
count.  You can customize the variable @code{blink-cursor-blinks} to
control that: its value says how many times to blink without input
before stopping.  Setting that variable to a zero or negative value
will make the cursor blink forever.  To disable cursor blinking
altogether, change the variable @code{blink-cursor-mode} to @code{nil}
(@pxref{Easy Customization}), or add the line

@lisp
  (blink-cursor-mode 0)
@end lisp

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

@node Line Truncation
@section Line Truncation

@cindex truncation
@cindex line truncation
  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 rightmost
and/or leftmost columns.

@kindex C-x x t
@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{C-x x t}
(@code{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, which is normally @code{nil}, is in effect.

  Since line truncation and word wrap (described in the next section)
are contradictory, @code{toggle-truncate-lines} disables word wrap
when it turns on line truncation.

  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

@cindex word wrap
  Another alternative to ordinary line continuation
(@pxref{Continuation Lines}) is to use @dfn{word wrap}.  Here, each
long logical line is divided into two or more screen lines, or
``visual lines'', like in ordinary line continuation.  However, Emacs
attempts to wrap the line at word boundaries near the right window
edge.  (If the line's direction is right-to-left, it is wrapped at the
left window edge instead.)  This makes the text easier to read, as
wrapping does not occur in the middle of words.

@cindex mode, Visual Line
@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.

  Since word wrap and line truncation (described in the previous
section) are contradictory, turning on @code{visual-line-mode}
disables line truncation.

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

@vindex word-wrap-whitespace-mode
  By default, Emacs only breaks lines after whitespace characters like
@key{SPC} and @key{TAB}, but does not break after whitespace
characters like @key{EN QUAD}.  Emacs provides a minor mode called
@code{word-wrap-whitespace-mode} that switches on word wrapping in the
current mode, and sets up which characters to wrap lines on based on
the @code{word-wrap-whitespace-characters} user option.  There's also
a globalized version of that mode called
@code{global-word-wrap-whitespace-mode}.

@vindex word-wrap-by-category
@findex modify-category-entry
@findex char-category-set
@findex category-set-mnemonics
  Only breaking after whitespace character produces incorrect
results when CJK and Latin text are mixed
together (because CJK characters don't use whitespace to separate
words).  You can customize the option @code{word-wrap-by-category} to
allow Emacs to break lines after any character with @samp{|} category
(@pxref{Categories,,, elisp, the Emacs Lisp Reference Manual}), which
provides better support for CJK characters.  Also, if this variable is
set using Customize, Emacs automatically loads @file{kinsoku.el}.
When @file{kinsoku.el} is loaded, Emacs respects kinsoku rules when
breaking lines.  That means characters with the @samp{>} category don't
appear at the beginning of a line (e.g., U+FF0C @sc{fullwidth comma}), and
characters with the @samp{<} category don't appear at the end of a line
(e.g., U+300A @sc{left double angle bracket}).  You can view the category
set of a character using the commands @code{char-category-set} and
@code{category-set-mnemonics}, or by typing @kbd{C-u C-x =} with point
on the character and looking at the ``category'' section in the
report.  You can add categories to a character using the command
@code{modify-category-entry}.

@node Display Custom
@section Customization of Display

  This section describes variables that control miscellaneous aspects
of the appearance of the Emacs screen.  Beginning users can skip it.

@vindex display-line-numbers
@cindex number lines in a buffer
@cindex display line numbers
  If you want to have Emacs display line numbers for every line in the
buffer, customize the buffer-local variable
@code{display-line-numbers}; it is @code{nil} by default.  This
variable can have several different values to support various modes of
line-number display:

@table @asis
@item @code{t}
Display (an absolute) line number before each non-continuation screen
line that displays buffer text.  If the line is a continuation line,
or if the entire screen line displays a display or an overlay string,
that line will not be numbered.

@item @code{relative}
Display relative line numbers before non-continuation lines which show
buffer text.  The line numbers are relative to the line showing point,
so the numbers grow both up and down as lines become farther from the
current line.

@item @code{visual}
This value causes Emacs to count lines visually: only lines actually
shown on the display will be counted (disregarding any lines in
invisible parts of text), and lines which wrap to consume more than
one screen line will be numbered that many times.  The displayed
numbers are relative, as with @code{relative} value above.  This is
handy in modes that fold text, such as Outline mode (@pxref{Outline
Mode}), and when you need to move by exact number of screen lines.

@item anything else
Any other non-@code{nil} value is treated as @code{t}.
@end table

@findex display-line-numbers-mode
@findex global-display-line-numbers-mode
@vindex display-line-numbers-type
The command @kbd{M-x display-line-numbers-mode} provides a
convenient way to turn on display of line numbers.  This mode has a globalized
variant, @code{global-display-line-numbers-mode}.  The user option
@code{display-line-numbers-type} controls which sub-mode of
line-number display, described above, these modes will activate.

@noindent
Note that line numbers are not displayed in the minibuffer and in the
tooltips, even if you turn on @code{display-line-numbers-mode}
globally.

@vindex display-line-numbers-current-absolute
When Emacs displays relative line numbers, you can control the number
displayed before the current line, the line showing point.  By
default, Emacs displays the absolute number of the current line there,
even though all the other line numbers are relative.  If you customize
the variable @code{display-line-numbers-current-absolute} to a
@code{nil} value, the number displayed for the current line will be
zero.  This is handy if you don't care about the number of the current
line, and want to leave more horizontal space for text in large
buffers.

@vindex display-line-numbers-widen
In a narrowed buffer (@pxref{Narrowing}) lines are normally numbered
starting at the beginning of the narrowing.  However, if you customize
the variable @code{display-line-numbers-widen} to a non-@code{nil}
value, line numbers will disregard any narrowing and will start at the
first character of the buffer.

@vindex display-line-numbers-offset
If the value of @code{display-line-numbers-offset} is non-zero, it is
added to each absolute line number, and lines are counted from the
beginning of the buffer, as if @code{display-line-numbers-widen} were
non-@code{nil}.  It has no effect when set to zero, or when line
numbers are not absolute.

@vindex display-line-numbers-width-start
@vindex display-line-numbers-grow-only
@vindex display-line-numbers-width
In selective display mode (@pxref{Selective Display}), and other modes
that hide many lines from display (such as Outline and Org modes), you
may wish to customize the variables
@code{display-line-numbers-width-start} and
@code{display-line-numbers-grow-only}, or set
@code{display-line-numbers-width} to a large enough value, to avoid
occasional miscalculations of space reserved for the line numbers.

@cindex @code{line-number} face
The line numbers are displayed in a special face @code{line-number}.
The current line number is displayed in a different face,
@code{line-number-current-line}, so you can make the current line's
number have a distinct appearance, which will help locating the line
showing point.  Additional faces @code{line-number-major-tick} and
@code{line-number-minor-tick} can be used to highlight the line numbers
of lines which are a multiple of certain numbers.  Customize
@code{display-line-numbers-major-tick} and
@code{display-line-numbers-minor-tick} respectively to set those
numbers.

@vindex line-spacing
  The variable @code{line-spacing} controls the vertical spacing between
lines.  It can be set to an integer (specifying pixels) or a float
(specifying spacing relative to the default frame font height).  You can
also set this variable to a cons cell of integers or floats, such as
@code{(@var{top} . @var{bottom})}.  When set to a cons cell, the spacing
is distributed above and below the line, allowing for text to be
vertically centered within the line height. See also @ref{Line Height,,,
elisp, The Emacs Lisp Reference Manual}.

@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 something to echo.  @xref{Echo Area}.

@vindex echo-keystrokes-help
  If the variable @code{echo-keystrokes-help} is non-@code{nil} (the
default), the multi-character key sequence echo shown according to
@code{echo-keystrokes} will include a short help text about keys which
will invoke @code{describe-prefix-bindings} (@pxref{Misc Help}) to show
the list of commands for the prefix you already typed.  For a related
help facility, see @ref{which-key}.

@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{t}, Emacs draws the underline at the same height as the font's
descent line.  (If non-default line spacing was specified for the
underlined text, see @ref{Line Height,,, elisp, The Emacs Lisp
Reference Manual}, Emacs draws the underline below the additional
spacing.)

@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 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 display-raw-bytes-as-hex
  Raw bytes are displayed in octal format by default, for example a
byte with a decimal value of 128 is displayed as @code{\200}.  To
change display to the hexadecimal format of @code{\x80}, set the
variable @code{display-raw-bytes-as-hex} to @code{t}.
Care may be needed when interpreting a raw byte when copying
text from a terminal containing an Emacs session, or when a terminal's
@code{escape-glyph} face looks like the default face.  For example, by
default Emacs displays the four characters @samp{\}, @samp{2},
@samp{0}, @samp{0} with the same characters it displays a byte with
decimal value 128.  The problem can be worse with hex displays, where
the raw byte 128 followed by the character @samp{7} is displayed as
@code{\x807}, which Emacs Lisp reads as the single character U+0807
SAMARITAN LETTER IT; this confusion does not occur with the
corresponding octal display @code{\2007} because octal escapes contain
at most three digits.